Index of every page on this site: llms.txt
All skills
heygen-com avatar

/hyperframes-cli

@fab75fb
by HeyGenheygen-com/hyperframes87k stars
8,101
Run it yourself

HyperFrames CLI - scaffold, check frames, edit timelines, preview, render, share and project history; read JSON and recover from failures.

Use this Skill: https://skilld.dev/gh/heygen-com/hyperframes/hyperframes-cli

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈39 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈31k more on demand in 12 files.

Description uses 1.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈156 characters, or 1.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Running the CLI: every npx hyperframes <command> here, the beacon included, means node <SKILLS>/hyperframes/scripts/plugin-cli.mjs <command> run in the project, where <SKILLS> holds this skill's folder (rules).

Usage beacon: run npx hyperframes events --skill=hyperframes-cli once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out.

HyperFrames CLI

Run npx hyperframes <command> as above, never a project's own scripts or wrapper unless the person names that command. It needs Node.js 22+ and FFmpeg. Every command has --help; most take --json, and a failure prints ✗ …, a Fix: line and exits non-zero.

A --json result may carry _meta.updateNotice: a newer HyperFrames release is out. Pass it to the person once per conversation, in your own words, at a natural pause; updating is theirs to decide.

Commands by job

Job Commands
Start init <dir> --skip-skills (blank; --example <name> only when asked), capture <url>
Read a project info, compositions, timeline --json, docs <topic>
Check it lint while writing; check --json as the gate (lint, runtime, layout, contrast)
Look at it snapshot (--at <t,…>, --range START,END, --composition <id>, --zoom, --angle, --against <video>), keyframes, compare, audio
Edit the timeline timeline with move, trim, split, set, duplicate, delete, apply, undo, ids
Reuse catalog, add (/hyperframes-registry)
Media and sound media-treatment, grade-compare, remove-background, tts, transcribe, beats, normalize-audio (/media-use)
Show and ship preview, present (/slideshow), render, share, publish (legacy), cloud, lambda, cloudrun
Desktop app open, catch-up
Upkeep doctor, browser, upgrade, usage, clean, feedback

captions is not a command: run transcribe, then read ../hyperframes/references/captions.md.

validate, inspect and layout are deprecated aliases of check; events is skills' own telemetry. Don't run them.

The loop

  1. Write, then npx hyperframes lint after the first pass and after structural changes.
  2. npx hyperframes check --json and fix every error. While a lint error remains the layout and contrast audits don't run; "0 samples" means nothing was checked. Contrast failures carry a suggestedColor. A finding at a single sample (an entrance in flight) is info; a 3 s+ video with no visible change fails sweep_static.
  3. npx hyperframes snapshot and read the PNGs (under .hyperframes/artifacts/snapshots/): that is how you see the video. With sub-compositions, snapshot a midpoint of every scene; tiny unstyled content or a missing hero is a mount defect (../hyperframes/references/format.md).
  4. npx hyperframes preview --background, check the URL answers 200, give the person the project URL and wait, unless they asked for the file or for no stops. Passing checks alone is not a reason to render.
  5. Time to render (step 4): npx hyperframes render --quality looks -o out.mp4 (draft while iterating, delivery for the final; paid plan: cloud render --fps <data-fps> --quality high -o out.mp4). Confirm the file is non-empty and its ffprobe duration matches the root data-duration, then look at decoded frames.

"This element" or the current selection: npx hyperframes preview --context --json --context-fields selection; no-selection means ask them to click it.

Edit the timeline

These are the edits Studio itself makes, so the result stays in Studio's shape.

  • timeline --json lists clips with absolute absStart/absEnd, owning file and the #id ref the edit commands take (timeline ids stamps missing ids).
  • timeline move|trim|split|set|duplicate|delete <ref> … --plan --json previews one edit; run it again without --plan. --start, --end, --duration set one edge or the length.
  • An edit is refused when the clip would overlap a neighbour (--overwrite, or move the neighbour first) or end past its composition: raise the root's data-duration first. No command changes data-duration.
  • Several edits at once: a JSON file such as [{"verb": "move", "ref": "#outro", "time": "9"}], then timeline apply plan.json --json. Each run prints a receipt; save it and timeline undo receipt.json reverts it.
<!-- history (trial): remove this block together with the command -->

Project history

Every write is kept and can be undone. At the start of a turn, npx hyperframes history begin --who <you> --label "<plan>", then history --since mine --who <you> to see what the person changed; build on their edits. A check failed or they say it got worse: history undo --who <you>, never hand-edit back. End the turn with history end.

<!-- /history (trial) -->

Render where

Need Command
Local render --quality looks -o out.mp4 (draft, delivery)
Reproducible container render --docker --strict -o out.mp4
Batch from variables render --batch rows.json -o "renders/{name}.mp4"
Hosted, no local Chrome or FFmpeg cloud render (references/cloud.md)
Your own AWS or GCP lambda render, cloudrun render (references/lambda.md, references/cloudrun.md)

A 30 s film renders in a minute or two: run it in the foreground. Detach only a render longer than your tool's timeout (HYPERFRAMES_RENDER_DETACHED=1, its own group, output to a log) and wait with until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done, never pgrep -f, which matches its own loop and waits until the tool times out.

After a verified render, send one feedback --rating, plus a report for anything the person asked for that HyperFrames can't do, unless telemetry is off: references/feedback.md.

When a command fails

Symptom Fix
Chrome missing or won't start npx hyperframes browser ensure; doctor --json always exits 0, gate on .ok
A heavy page isn't ready in time Raise --timeout on check or snapshot
Unusual codec looks blank Keep --proxy on (the default)
Render slow on Linux The summary's second line says screenshot + software gpu: the slow path
capture fails or writes BLOCKED.md Take nothing from its partial files; retry into a new -o folder
Disk tight clean --dry-run, then clean; never delete .hyperframes (it holds history)

References

Read the row before running its command.

Commands Read
init, capture, skills references/init-and-scaffold.md
lint, check, motion sidecars, snapshot references/lint-validate-inspect.md
compare, grade-compare, render --batch references/compare-and-batch.md
beats references/beats.md
preview, play, render, share, publish (legacy), Studio context references/preview-render.md
doctor, browser references/doctor-browser.md
auth, cloud, template variables references/cloud.md
lambda, cloudrun references/lambda.md, references/cloudrun.md
info, upgrade, compositions, timeline, docs, usage, telemetry references/upgrade-info-misc.md
--strict flags, run ids, clean, shader lint, JSON paths references/conventions.md
keyframes ../hyperframes/references/motion.md (Seeing motion)

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alerttoday4 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    HyperFrames CLI is a comprehensive tool for video project scaffolding, auditing, and cloud-based rendering. The skill demonstrates security maturity by redirecting npx calls to a local plugin script, implementing clear opt-out mechanisms for telemetry, and providing detailed instructions for redacting sensitive paths from feedback reports.

  • Socket1d

    No alerts

  • Snyktoday

    Risk: CRITICAL · 3 issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at fab75fb. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 days ago

README badge

README badge for heygen-com/hyperframes/hyperframes-cli