HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.
HyperFrames CLI
Everything runs through npx hyperframes. Requires Node.js >= 22 and FFmpeg.
Workflow
Scaffold — npx hyperframes init my-video
Write — author HTML composition (see the hyperframes skill)
Lint — npx hyperframes lint
Visual inspect — npx hyperframes inspect
Preview — npx hyperframes preview
Render — npx hyperframes render
Lint and inspect before preview. lint catches missing data-composition-id, overlapping tracks, and unregistered timelines. inspect opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.
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 --example blank --tailwind
npx hyperframes init my-video --non-interactive
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.
When using --tailwind, invoke the tailwind skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.
Use this after lint and validate, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
Text extending outside the nearest visual container or bubble
Text clipped by its own fixed-width/fixed-height box
Text extending outside the composition canvas
Children escaping clipping containers
Errors should be fixed before rendering. Warnings are surfaced for agent review; add --strict to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with data-layout-allow-overflow. If a decorative element should never be audited, mark it with data-layout-ignore.
npx hyperframes layout remains available as a compatibility alias for the same visual inspection pass.
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.
When handing a project back to the user, use the Studio project URL, not the
source index.html path:
http://localhost:<port>/#project/<project-name>
Use the actual port from the preview output and the project directory name. For
example, after npx hyperframes preview --port 3017 in codex-openai-video,
report http://localhost:3017/#project/codex-openai-video.
Treat index.html as source-code context only. It is fine to link it as an
implementation file, but do not label it as the project or preview surface.
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
--variables
JSON object
—
Override variable values declared in data-composition-variables
--variables-file
path
—
JSON file with variable values (alternative to --variables)
--strict-variables
flag
off
Fail render on undeclared keys or type mismatches in --variables
Quality guidance:draft while iterating, standard for review, high for final delivery.
Parametrized renders: the composition declares its variables on the <html> root with data-composition-variables — a JSON array of declarations ({id, type, label, default} per entry) that defines the schema. Scripts inside read the resolved values via window.__hyperframes.getVariables(). The CLI --variables '{"title":"Q4 Report"}' is a JSON object keyed by id that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with data-variable-values — same object shape, scoped to one mount of the sub-composition. See the hyperframes skill for the full pattern.)
Asset Preprocessing
npx hyperframes tts, transcribe, and remove-background produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each downloads its own model on first run. For voice selection, whisper model rules (the .en-translates-non-English gotcha), output format choice (VP9 alpha WebM vs ProRes), and the TTS → transcribe → captions chain, invoke the hyperframes-media skill.
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
Credits & Attribution
This skill is based on the excellent work by
HeyGen.
Special thanks to HeyGen for their generous open-source contributions, which helped shape this skill collection.
Adapted by webconsulting.at for this skill collection
