Hyperframes hyperframes-cli

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.

install

source · Clone the upstream repo

git clone https://github.com/heygen-com/hyperframes

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/heygen-com/hyperframes "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/hyperframes-cli" ~/.claude/skills/heygen-com-hyperframes-hyperframes-cli && rm -rf "$T"

manifest: skills/hyperframes-cli/SKILL.md

source content

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
```
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