HyperFrames CLI
Everything runs through npx hyperframes. Requires Node.js >= 22 and FFmpeg.
How to drive this CLI (single-voice — do NOT parallelize)
This is a deterministic, ordered CLI workflow with ONE coherent operator voice. Do not fan out parallel sub-agents to run these commands — render/preview/lint share the project directory and media files (one-writer-per-dir), and the steps are sequentially dependent (scaffold → write → lint → preview → render). Run the commands yourself, in order, reading each command's real output before the next step.
Craft rules:
- Lint is the gate. Always
lintbeforepreview/render; never render past lint errors. Use--strictin CI/agent runs so a lint error fails the render instead of shipping a broken frame. - Draft → review → final. Iterate at
--quality draft, review atstandard, deliver athigh. Don't burn render time at 60fps/high until the composition is locked. - Doctor first on failure. If a render fails, run
doctorBEFORE changing flags — most failures are environment (missing FFmpeg/Chrome, low memory), not the command.
Output contract
Each invocation produces one observable artifact: init → a scaffolded project dir; lint → an errors/warnings/info report (--json for machine-readable); preview → a live studio URL; render → a video file at renders/<name>_<timestamp>.mp4 (or --output); transcribe/tts → caption/audio files. State the exact output path to the user.
Verify step
- After
render: confirm the output file exists and is non-empty (ls -la <output>), and report its path + size. A "render succeeded" log with no playable file on disk is not done. - After
lint: report the actual error/warning counts from the command output — never assert "clean" without the lint having run. - No-hallucination guardrail: only claim a flag, template, or voice exists if it appears in this reference or in real
--help/--listoutput. If unsure of a flag, runnpx hyperframes <cmd> --help(ortts --list) and cite what it returns — do not invent options.
Workflow
- Scaffold —
npx hyperframes init my-video - Write — author HTML composition (see the
hyperframesskill) - Lint —
npx hyperframes lint - Preview —
npx hyperframes preview - Render —
npx hyperframes render
Lint before preview — catches missing data-composition-id, overlapping tracks, unregistered timelines.
Scaffolding
npx hyperframes init my-video # interactive wizard
npx hyperframes init my-video --example warm-grain # pick an example
npx hyperframes init my-video --video clip.mp4 # with video file
npx hyperframes init my-video --audio track.mp3 # with audio file
npx hyperframes init my-video --non-interactive # skip prompts (CI/agents)
Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
init creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.
Linting
npx hyperframes lint # current directory
npx hyperframes lint ./my-project # specific project
npx hyperframes lint --verbose # info-level findings
npx hyperframes lint --json # machine-readable
Lints index.html and all files in compositions/. Reports errors (must fix), warnings (should fix), and info (with --verbose).
Previewing
npx hyperframes preview # serve current directory
npx hyperframes preview --port 4567 # custom port (default 3002)
Hot-reloads on file changes. Opens the studio in your browser automatically.
Rendering
npx hyperframes render # standard MP4
npx hyperframes render --output final.mp4 # named output
npx hyperframes render --quality draft # fast iteration
npx hyperframes render --fps 60 --quality high # final delivery
npx hyperframes render --format webm # transparent WebM
npx hyperframes render --docker # byte-identical
| Flag | Options | Default | Notes |
|---|---|---|---|
--output |
path | renders/name_timestamp.mp4 | Output path |
--fps |
24, 30, 60 | 30 | 60fps doubles render time |
--quality |
draft, standard, high | standard | draft for iterating |
--format |
mp4, webm | mp4 | WebM supports transparency |
--workers |
1-8 or auto | auto | Each spawns Chrome |
--docker |
flag | off | Reproducible output |
--gpu |
flag | off | GPU-accelerated encoding |
--strict |
flag | off | Fail on lint errors |
--strict-all |
flag | off | Fail on errors AND warnings |
Quality guidance: draft while iterating, standard for review, high for final delivery.
Transcription
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt # import existing
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
Text-to-Speech
npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # show all voices
Troubleshooting
npx hyperframes doctor # check environment (Chrome, FFmpeg, Node, memory)
npx hyperframes browser # manage bundled Chrome
npx hyperframes info # version and environment details
npx hyperframes upgrade # check for updates
Run doctor first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.
Other
npx hyperframes compositions # list compositions in project
npx hyperframes docs # open documentation
npx hyperframes benchmark . # benchmark render performance