HyperFrames CLI

The HyperFrames CLI turns an HTML composition into a video with headless Chrome and FFmpeg, and it lints, audits, snapshots and diagnoses the project on the way. This skill is the command loop you run on your own Linux computer, from an empty folder to a verified MP4 in the owner's hands. The standard: no final render until check passes and the owner has seen a review package, and no hand-off until ffprobe agrees with the composition.

When to use

• "Make the video", "render it", "export a vertical cut", "give me a GIF of this"
• "Start a video from our website" (capture), "make one video per row of this sheet" (batch)
• "Check this before we render", "compare these two versions", "which grade looks better?"
• "Why won't it render?", "the render is black, stuck or slow"
• "Transcribe this narration", "cut the person out of this clip" (local media tools)
• Any time you are about to run an npx hyperframes command

What you need

• Run the check in references/computer-setup.md first: Node 22+ and FFmpeg are not installed by default, and anything outside /home/user is lost when the computer is rebuilt. Start every terminal call that runs the CLI with:

  export PATH="$HOME/.local/node/bin:$PATH" HYPERFRAMES_NO_TELEMETRY=1 HYPERFRAMES_SKIP_SKILLS=1
  

• The project in ~/Desktop/<your name> - Work space/<job>/<project>/, or the brief, URL or files to start one.
• The brief's targets: duration, aspect ratio, fps, deadline. With no brief, load hyperframes with skill_view: it owns intake and the end-to-end workflow.
• hyperframes-core loaded before you write or fix composition HTML.

Method

1. Set up and gate. Run the check in references/computer-setup.md, then gate on doctor's payload (it always exits 0):

   npx hyperframes doctor --json | node -e 'const j=JSON.parse(require("fs").readFileSync(0,"utf8")); process.exit(j.ok ? 0 : 1)' && echo READY
   

   Fix every fail before building (references/doctor-browser.md).
2. Scaffold. In the job folder, npx hyperframes init <project> --non-interactive gives the centered blank; pass --example=<name> only to start from a named example, --resolution portrait for vertical. Delete the AGENTS.md copies init writes (computer-setup.md step 7). From a website: npx hyperframes capture <url> --skip-vision --json; a non-zero exit, ok: false or a BLOCKED.md is a hard stop (references/init-and-scaffold.md).
3. Find the move. If the request names an asset, sound, image, voice or fast visual edit, resolve it through media-use before proposing a plan. Otherwise search before authoring motion by hand: npx hyperframes catalog --query "reveal a headline one line at a time" --json. Ask for the effect you want, not the mechanism you have in mind. Install with npx hyperframes add <name> --no-clipboard --json (see hyperframes-registry). Author by hand only once nothing fits (references/catalog-search.md).
4. Author. Write the composition following hyperframes-core. To learn what is on the timeline, run npx hyperframes timeline --json instead of reading index.html and every sub-composition: nested rows carry absolute absStart / absEnd and their owning file, not just local time. Query one-liners are in references/upgrade-info-misc.md.
5. Lint while editing. npx hyperframes lint after the first HTML pass and after every structural change. Fix errors at once: they stop check before its browser pass.
6. Run the final gate. npx hyperframes check --json, with --snapshots for annotated frames and per-finding crops. It reruns lint first, so do not prepend a standalone lint. It audits runtime errors, failed requests, layout, *.motion.json assertions and WCAG contrast in one browser session; persistent findings gate the exit code, transient entrance or exit findings are informational, --strict gates warnings. browserSkipped: true means layout, motion and contrast never ran: not a pass (references/lint-validate-inspect.md).
7. Smoke-test sub-compositions. Static audits cannot catch every mount failure. When index.html mounts data-composition-src, capture a visible midpoint for each host slot and look at them with vision_analyze:

   QC=$(mktemp -d) && npx hyperframes snapshot --at <t1>,<t2>,<t3> --no-end -o "$QC" && ls "$QC"
   

   Tiny unstyled content, canvas-sized icons, a missing hero element or a timeline-registration timeout is a render-blocking mount defect; the fixes are in the sub-compositions reference of hyperframes-core.
8. Review it yourself, then send a review package. Render --quality draft, tile it into a contact sheet in a temporary folder (QC=$(mktemp -d) && ffmpeg -v error -i renders/draft.mp4 -vf "fps=1,scale=480:-1,tile=4x3" -frames:v 1 "$QC/sheet.png" && echo "$QC/sheet.png") and check it with vision_analyze. To watch motion, run Studio for yourself (npx hyperframes preview --background --no-open, then browser_navigate to http://localhost:<port>/#project/<name>). Then attach key frames and the draft to your reply with MEDIA:/absolute/path and ask "render the final, or what changes?". Never hand the owner a localhost URL. The plan in chat and a storyboard sheet are not approval of the video.
9. Render the final after the owner's yes (or straight away when the owner said "just make it"): npx hyperframes render --quality delivery --output renders/<project>-final.mp4, started with terminal(background=true, notify_on_complete=true).
10. Verify the output. test -s the file. Read the render summary's second line (beginframe or screenshot capture, GPU mode, stage timings). Run ffprobe -v error -show_format -show_streams and compare duration (and fps, if the brief set one) with the root data-duration. Look at a contact sheet of the final.
11. Hand off and tidy. Attach the final with MEDIA:/absolute/path/final.mp4 (never only a path), plus its path, duration, resolution, fps and size; copy it to ~/Desktop/Team when teammates need it. Stop preview servers (npx hyperframes preview --stop) and run npx hyperframes clean --dry-run, then clean.

Project history (trial feature, optional)

Every write to the project is kept as an entry that can be undone. It is worth using when the owner or a teammate also edits the project, and only at two moments, never on every step:

• Start of a turn: npx hyperframes history begin --who <your-name> --label "<what you are about to do>", then npx hyperframes history --since mine --who <your-name> to see what others changed since your last turn. Build on their edits; never overwrite them.
• A check failed, or the owner says it got worse: npx hyperframes history undo --who <your-name> undoes your newest turn and leaves other people's edits alone. Do not hand-edit back. On a conflict it exits 2 and prints both choices.

End each turn with npx hyperframes history end, so your writes read as yours, not as "Changed outside the app". While a turn is open, every write counts as yours until 10 minutes pass without one; after that the turn ends by itself. The other subcommands are in references/upgrade-info-misc.md.

Read these before certain edits

• Zoom, punch-in or punch-out, reframe, camera move, any keyframe motion, or before running npx hyperframes keyframes: load hyperframes-keyframes first. The command surfaces animation trajectories; it does not diagnose clip cuts.
• A cut, trim, splice, reorder or source-timing edit: hyperframes-core and its clip and timeline contract; copy creator edit markup from its creator-editing recipes.
• Fade-in or fade-out, crossfade, track gain, volume automation, ducking, voiceover carve, effects on placed audio: hyperframes-audio, with hyperframes-core alongside when clip placement or picture timing also changes.
• A request naming an asset, sound, image, voice or fast visual edit: media-use before a plan is proposed. Voice comes from your text_to_speech tool.
• Composition variables: hyperframes-core. Motion rules and transitions: hyperframes-animation. Decks (present) and beat-synced videos: hyperframes.

Agent conventions

• Prefer --json on every call you parse. Server-mode render, preview and play give no ordinary JSON; preview --context --json and preview --selection --json are query-mode exceptions.
• doctor --json always exits zero: gate on its ok field, as in step 1.
• Non-interactive mode is automatic in your terminal and scaffolds the centered blank; --non-interactive forces it anyway.
• Use one HYPERFRAMES_RUN_ID for all commands of one verification loop. It only labels the CLI's usage events, so with telemetry off it changes nothing visible; never change it mid-loop.
• When disk is tight, npx hyperframes clean --dry-run, then clean: it removes what dead renders left and idle caches that rebuild themselves, never outputs, sources or anything a running render uses. Write quality-check frames to a temporary folder, not the project.
• Use --strict, --strict-all and --strict-variables when warnings, lint findings or the variable contract must gate the render.
• JSON paths redact the home folder as $HOME. Do not try to reverse it; build absolute paths from the project folder you already know.
• When the owner says "this element", nobody is clicking in Studio, so preview --selection has nothing to report. Identify the target from the owner's words, a frame you send, or timeline --json, and confirm with clarify if two things fit.
• Telemetry stays off (your environment line). npx hyperframes telemetry status confirms it.

Render choices

Need	Command
Fast iteration, review draft	npx hyperframes render --quality draft --output renders/draft.mp4
First real encode	npx hyperframes render --quality looks --output out.mp4
Final delivery	npx hyperframes render --quality delivery --output final.mp4
Reproducible container render, only if docker info succeeds	npx hyperframes render --docker --strict --output out.mp4
One video per variable row	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Transparent overlay	npx hyperframes render --format webm --output overlay.webm
One composition file	npx hyperframes render -c compositions/intro.html -o intro.mp4

Render locally. Most agent computers have no Docker, so --docker is the exception. A cloud Linux computer usually has no GPU either: expect screenshot capture · software gpu on the summary line, and at 8 GB of RAM or less the CLI's low-memory mode pins one worker. Budget the time: render the draft first, note its wall time, and expect the final to take longer (higher quality; 60 fps doubles the frames). Control it with --quality draft while iterating and --workers (2 on a small computer). Full flag table and batch rules: references/preview-render.md, references/compare-and-batch.md.

When a render fails

Run npx hyperframes doctor first. Then match the symptom: Chrome missing or crashing at start (browser ensure --force, or HYPERFRAMES_BROWSER_PATH=/usr/bin/chromium); navigation timeout on a heavy composition (raise --browser-timeout, in seconds); killed or frozen mid-render (low memory: stop Studio, --workers 1, --quality draft); disk full (clean). Never build a substitute rasteriser. Before you ask a teammate (ask_teammate) or tell the owner, write down the command, expected and actual result, the exact error, the outcome (correct, corrupt, fallback, hard exit, hung) and any workaround. The template is in references/preview-render.md.

References (read the matching one before running the command)

Commands	Reference
Setup, environment line, fonts	references/computer-setup.md
init, capture	references/init-and-scaffold.md
catalog, add basics	references/catalog-search.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, failures	references/preview-render.md
doctor, browser	references/doctor-browser.md
info, upgrade, timeline, compositions, docs, benchmark, clean, history, telemetry, transcribe, remove-background, media-treatment, normalize-audio, present, figma	references/upgrade-info-misc.md

Commands you never run

• cloud, auth, lambda, cloudrun: hosted or paid rendering. Render locally.
• publish: uploads the project to the maker's hosting.
• feedback, including --search-miss, --file-issue, and the pre-filled report_gap line a catalog search prints: they send your query or project details to the maker's public channel. Note an empty search in your hand-off instead.
• telemetry enable and events (the endpoint skills use to report their own invocation; it emits an event and exits 0 whatever you pass).
• skills (installs instruction packs for other coding assistants), usage (reads another coding assistant's login to report its plan allowance), and open (hands the project to a desktop app this computer does not have; ignore a render line that suggests it).
• tts: use your text_to_speech tool. models install parakeet installs an MLX model built for Apple Silicon Macs; transcribe with --engine whisper instead.
• validate, inspect, layout: deprecated aliases kept for old scripts. check is the maintained one.
• Never set a model-provider API key: with one set, capture and snapshot send frames to a hosted vision model. Always pass capture --skip-vision; snapshot --describe false makes sure.

Output

• In the reply: the final MP4 attached with MEDIA:/absolute/path/to/final.mp4, then path, duration, resolution, fps and size from ffprobe (a show_card may carry these).
• One line each on: the render's capture path and wall time, any check warnings you accepted and why, licences recorded in assets/LICENSES.md, and any empty catalog search (query, tier, the move you built by hand).
• For a review round instead of a final: key frames and the draft MP4 attached, and the question "render the final, or what changes?".

Checks before you finish

• doctor --json reported ok: true in this session.
• check exited 0 on the final source, with browserSkipped false.
• Every sub-composition slot showed real content in a snapshot.
• The owner approved the review package, or asked for the final directly.
• test -s passed and ffprobe duration, fps and resolution match the composition; the contact sheet shows no black, blank or frozen stretch.
• No preview, play or present server and no stray Chrome is still running (npx hyperframes preview --list).

Pitfalls

• Rendering the final because checks passed. Checks are not approval: the owner's yes to the review package is.
• Handing the owner http://localhost:.... They cannot open it; send PNGs and an MP4.
• Running lint and then check. check already lints; run it alone as the gate.
• Reading index.html and every sub-composition to find a clip. timeline --json answers in one call, with absolute times.
• Calling a 0 exit a good render. Verify with test -s, ffprobe and a contact sheet.
• Reporting a catalog miss to the maker, or treating No searchable words in query as a missing component (it means the query was not in English).
• Starting a 4K or 60 fps final with eight workers on a small computer. Draft first, time it, then size --workers from doctor's memory figure.
• Forgetting that FFmpeg and other system packages vanish on a rebuild. Run the setup check at the start of every job.