hyperframes-cli

name	hyperframes-cli
description	HyperFrames CLI tool — hyperframes init, lint, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting or validating compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

HyperFrames CLI

Everything runs through npx hyperframes. Requires Node.js >= 22 and FFmpeg.

Workflow

1. Scaffold — npx hyperframes init my-video
2. Write — author HTML composition (see the hyperframes skill)
3. Lint — npx hyperframes lint
4. Preview — npx hyperframes preview
5. 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 (outputs to renders/ automatically)
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.

Pitfalls

--out path must be a directory, not a filename

npx hyperframes render --out renders/output.mp4 → ✗ error: "Not a directory" npx hyperframes render → ✅ outputs to renders/name_timestamp.mp4 automatically Use --output (not --out) to specify a named file path.

index.html root timeline must match data-composition-id of the sub-composition

If index.html only contains a data-composition-src reference (no inline content), you still need a window.__timelines registration that matches a real data-composition-id. Best practice: register window.__timelines['<sub-comp-id>'] = gsap.timeline({paused:true}) — but since sub-compositions register their own timelines, the index.html script block is only needed to pass lint. Use the sub-composition's id (not 'root').

Sub-composition <div> needs data-start="0" and data-duration

The <div data-composition-id="..."> inside <template> must have data-start="0" and data-duration="N" or lint will warn and playback may not start.

Other

npx hyperframes compositions   # list compositions in project
npx hyperframes docs           # open documentation
npx hyperframes benchmark .    # benchmark render performance