<!-- Vendored into Video Production Buddy from C:\Users\ishan\Documents\hyperframes\skills\hyperframes-cli\SKILL.md Source commit: d291358 (2026-04-17) See .agents/skills/hyperframes/PROVENANCE.md for re-sync instructions.

Video Production Buddy-local edit: added validate to the top-line command list and a dedicated "Validation" section — upstream omits it even though the CLI ships it and hyperframes validate is the real browser-based contract check (contrast, timelines, assets) that runs before render. -->

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 (static checks)
4. Validate — npx hyperframes validate (browser-based runtime checks + contrast audit)
5. Preview — npx hyperframes preview
6. Render — npx hyperframes render

Lint catches static issues (missing data-composition-id, overlapping tracks, unregistered timelines). Validate catches runtime/visual issues by seeking into the paused composition in a real browser (contrast, broken overlays, missing assets). Run both before render.

Validation

bash
npx hyperframes validate                 # full validation (static + contrast + contract)
npx hyperframes validate --no-contrast   # skip WCAG contrast audit when iterating fast
npx hyperframes validate --json          # machine-readable output

Validation seeks to several timestamps in the paused composition, screenshots the page, samples pixels behind every text element to compute WCAG contrast ratios, and verifies runtime contracts (window.__timelines registration, class="clip" presence, valid data-* attributes). Run it before every render — it's cheap and catches issues lint cannot see.

Scaffolding

bash
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

bash
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

bash
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

bash
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

bash
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

bash
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

bash
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

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