Jonathon's AI Wiki

HyperFrames Quickstart & CLI

9 min read

Source: Quickstart, CLI — HeyGen HyperFrames docs

The fastest path from zero to a rendered MP4, plus the full hyperframes CLI command surface. Two on-ramps: prompt an AI coding agent after npx skills add heygen-com/hyperframes, or scaffold a project by hand with init / preview / render. The CLI is the primary interface — it wraps the producer, engine, and studio packages and is engineered to be agent-friendly: explicit flags, fail-fast errors, and parseable JSON output on nearly every command. For the framework overview see HeyGen Hyperframes.

Key Takeaways

  • Two-minute path, two doors. Agent route: npx skills add heygen-com/hyperframes, then describe the video. Manual route: npx hyperframes init → preview → render.
  • Only two hard dependencies: Node.js 22+ and FFmpeg. npm/bun is the package manager; Docker is optional (for deterministic renders).
  • One CLI, ~24 commands spanning scaffolding, media preprocessing, linting, rendering, diagnostics, and three distinct cloud-render backends.
  • Agent-friendly by contract: missing required flags fail fast with a usage example; --json wraps output in a _meta envelope (version-check data, no network call) so an agent detects an outdated CLI from any command.
  • Three cloud-render options, one credential. cloud (HeyGen-hosted, zero-infra, pay-per-credit), lambda (bring-your-own-AWS), cloudrun (bring-your-own-GCP). All distributed; same render primitives.
  • init --non-interactive and command-specific --human-friendly — interactivity is per-command, never a global TTY assumption, which is what makes the CLI scriptable.

Quickstart

Option 1 — With an AI coding agent (recommended)

npx skills add heygen-com/hyperframes        # picker; or --all for everything

The installer shows a picker; select the core set (registers as slash commands in Claude Code, Cursor, Gemini CLI, Codex, Google Antigravity, GitHub Copilot CLI): /hyperframes (entry — read first, routes “make me a video”), /hyperframes-core (composition contract), /hyperframes-animation, /hyperframes-creative, /hyperframes-cli, /hyperframes-media, /hyperframes-registry, /general-video. Workflow skills (/product-launch-video, /website-to-video, /faceless-explainer, etc.) are optional add-ons that /hyperframes routes to. Then prompt, e.g.: “Using /hyperframes, create a 10-second product intro with a fade-in title over a dark background and subtle background music.” The agent handles scaffolding, animation, and rendering. (Claude Design uses a separate entry path — see HyperFrames + Claude Design.)

Option 2 — Start a project manually

Prerequisites — install once:

node --version            # must be >= v22
brew install ffmpeg       # macOS  (Ubuntu/Debian: sudo apt install ffmpeg; Windows: winget install ffmpeg)
ffmpeg -version           # expect ffmpeg version 7.x

Scaffold → preview → render:

npx hyperframes init my-video                 # interactive wizard (example + media import)
# or, for CI / agents:
npx hyperframes init my-video --non-interactive --example blank
cd my-video
npx hyperframes preview                        # Studio opens in browser; index.html hot-reloads
npx hyperframes render --output output.mp4     # ✔ Capturing frames... ✔ Encoding MP4...

init scaffolds meta.json, index.html (root composition), compositions/ (sub-compositions via data-composition-src), and assets/; it also installs the AI agent skills automatically. Pass --video ./intro.mp4 to auto-transcribe and patch in captions. When editing index.html directly, three rules apply (full contract in HyperFrames Core Concepts):

  • Root element needs data-composition-id, data-width, data-height.
  • Timed elements need data-start, data-duration, data-track-index, and class="clip".
  • GSAP timeline must be created { paused: true } and registered on window.__timelines.

CLI Command Reference

Every command documented on the CLI page. Most accept --json; flags below are the headline ones (see HyperFrames Rendering for the full render flag matrix).

CommandWhat it does
init [name]Scaffold a new project from an example. --example/-e (required in default mode), --resolution, --video/-V, --audio/-a, --tailwind, --skip-skills, --skip-transcribe, --model, --language, --non-interactive. Examples: blank, warm-grain, play-mode, swiss-grid, vignelli.
add <item>Install a registry block (scene) or component (effect/snippet) into an existing project. --dir, --no-clipboard, --json. Reads hyperframes.json; outputs files + a paste snippet (copied to clipboard by default).
catalogBrowse the registry. --type block|component, --tag, --json, --human-friendly (interactive picker that runs add on select).
compositionsList every composition in the project (ID, duration, resolution, element count). --json.
transcribe <file>Word-level timestamps via local whisper.cpp, or import an existing .srt/.vtt/.json transcript. --model/-m, --language/-l, --to srt|vtt, --output/-o, --preserve-cues, --json. Auto-patches caption HTML.
tts <text|file>On-device text-to-speech (Kokoro-82M, no API key). --voice/-v, --speed/-s, --lang/-l, --output/-o, --list, --json. Voice-ID first letter encodes language (a=American, b=British, e=Spanish, f=French, …).
remove-backgroundStrip background from a video/image with a local AI model → transparent media (PNG/alpha) for overlays.
preview [dir]Live preview server + hot reload (Hyperframes Studio). --port (default 3002). What-you-see-is-what-you-render; auto-detects embedded / local-studio / monorepo mode.
publish [dir]Zip + upload the project; prints a stable claimable hyperframes.dev URL. --yes skips confirmation. Survives CLI exit.
lint [dir]Structural check before rendering: missing attributes, missing adapter libs (GSAP/Lottie/Three.js), etc. --verbose (info-level), --json (counts + findings). Severity: ✗ error / ⚠ warning / ℹ info.
beats [dir]Detect beats in the music track and write a beat file the Studio uses for timeline guides. --json.
renderRender to MP4/WebM/MOV/png-sequence (see Rendering article + matrix below). --output, --format, --fps, --quality, --crf, --video-bitrate, --resolution, --hdr/--sdr, --workers, --gpu, --docker, --variables/--variables-file/--strict-variables, --browser-timeout.
benchmark [dir]Sweep fps/quality/worker configs and compare timing + file size to find optimal render settings. --runs (1-20), --json.
doctorVerify environment: CLI version, Node, FFmpeg, FFprobe, Chrome, Docker. --json always exits 0 — health is in the payload’s ok field (gate CI with jq -e '.ok'). Paths redacted to $HOME in JSON.
info [dir]Project metadata: name, resolution, duration, element counts by type, track count, total size. --json.
upgradeCompare installed vs latest npm version. --check (no prompt), --json, --yes/-y.
browser <ensure|path|clear>Manage the Chrome used for rendering. ensure downloads it; path prints only the executable path (for $(...)); clear removes the cached download.
docs [topic]Inline terminal docs. Topics: data-attributes, examples, rendering, gsap, troubleshooting, compositions.
feedbackAnonymous 1-5 satisfaction rating. --rating (required), --comment. Also offered to agents post-render; no-op if telemetry disabled.
telemetry <enable|disable|status>Manage anonymous usage telemetry (command names, render perf, coarse env fingerprint incl. detected agent name). Redacts paths/PII. Off via HYPERFRAMES_NO_TELEMETRY=1.
skillsInstall HyperFrames skills into AI coding tools. --claude, --gemini, --codex, --cursor (default: Claude/Gemini/Codex).
auth <login|status|logout>Sign in to HeyGen; credentials at ~/.heygen/credentials (mode 0600), shared with the heygen CLI. login --api-key (verified vs GET /v3/users/me), status --json, logout --keep-api-key/--yes. Resolution: HEYGEN_API_KEY → HYPERFRAMES_API_KEY → credentials file.
cloud <render|list|get|delete>HeyGen-hosted cloud render (see Cloud rendering below).
lambda <deploy|sites|render|render-batch|progress|destroy|policies>Bring-your-own-AWS distributed render (see below).
cloudrun <deploy|sites|render|render-batch|progress|destroy>Bring-your-own-GCP distributed render (see below).

The CLI’s “When to Use” list also names capture (capture a website for video production), inspect (check rendered layout for text overflow / clipped containers / overlapping text, and verify motion intent against the seeked timeline), and snapshot (capture key frames as PNG). The fetched docs page describes these only in that summary list and gives no dedicated flag section for them.^[inferred — the three appear in the “When to Use” bullets but the page’s Commands section had no standalone entry for them at fetch time; treat their flags as unconfirmed]

render flag matrix (headline options)

FlagValues / defaultPurpose
--formatmp4 (default), webm, mov, png-sequenceWebM/MOV carry transparency (VP9 + alpha); png-sequence writes RGBA PNGs
--fps24 / 30 / 60Frame rate
--qualitydraft / standard / highDrives CRF/bitrate (override with --crf 0-51 or --video-bitrate, mutually exclusive)
--resolutionlandscape, portrait, 4k, square, …Supersamples via Chrome deviceScaleFactor; aspect must match, scale an integer multiple
--dockeroffDeterministic, reproducible render
--gpu / --no-browser-gpuoff / on locallyHardware FFmpeg encode (NVENC/VideoToolbox/…); opt out of host GPU capture
--workers1-8 (default 4)Parallel render workers (auto low-memory mode ≤ 8 GB RAM pins to 1)
--variables / --variables-file / --strict-variablesJSON / path / offOverride data-composition-variables at render time for parametrized renders

Cloud rendering

Three backends, all driven from one hyperframes auth login credential. Decision rule from the docs: local render for the authoring loop; lambda/cloudrun when you already run AWS/GCP and want chunked parallelism on your own account; cloud when you want zero infra and will pay per credit.

hyperframes cloud — HeyGen-hosted, no local Chrome/ffmpeg/AWS.

hyperframes cloud render ./my-video               # zip + upload + poll + download
hyperframes cloud render ./my-video --no-wait     # submit, print render_id, exit
hyperframes cloud list                            # cursor-paged (--limit/--token/--all)
hyperframes cloud get <id>                        # detail + short-lived signed video_url
hyperframes cloud delete <id>                     # soft-delete

render zips the project (excluding .git, node_modules, dist, etc.), uploads via POST /v3/assets, submits POST /v3/hyperframes/renders, polls until done, and streams the file down. Supports --fps, --quality, --format, --resolution (4k billed 1.5×, no webm/mov), --aspect-ratio, --variables, --callback-url/--callback-id (webhook with --no-wait), --asset-id/--url (skip upload), --poll-interval, --max-wait. Because POST /v3/assets is not idempotent, pass --idempotency-key "$(uuidgen)" for safe retries (the CLI auto-retries 401s by refreshing the OAuth token).

hyperframes lambda — bring-your-own-AWS via the @hyperframes/aws-lambda SDK + AWS SAM. End-to-end is three commands:

hyperframes lambda deploy                                          # SAM-deploys the stack (idempotent)
hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
hyperframes lambda destroy

Prereqs: AWS creds, AWS SAM CLI, and bun on PATH. sites create <dir> content-addresses an upload so a re-render of the same tree skips re-upload (returns a reusable siteId). render-batch <dir> --batch users.jsonl fans out N personalized renders (one {"outputKey","variables"} per line), capped by --max-concurrent (default 50); --dry-run lints the batch without billing. progress <renderId> prints percent / frames / invocations / accrued cost. policies role|user|validate prints or CI-validates the minimum IAM policy. Variables ride the Step Functions input (256 KiB cap) — pass typed data, URL-reference media.

hyperframes cloudrun — the GCP counterpart (Cloud Run + Cloud Workflows, @hyperframes/gcp-cloud-run SDK + Terraform). Same deploy / sites create / render / render-batch / progress / destroy verbs and render primitives; only the storage (GCS), compute (Cloud Run), and orchestration (Cloud Workflows) differ. deploy --project <id> is required; state caches to ~/.hyperframes/cloudrun-state.json.

Why it suits agents

  • Non-interactive by default where it counts. init --non-interactive --example blank and parseable stdout mean a subagent can scaffold and render with no human in the loop — no TTY prompts to hang on.
  • Fail-fast contract. A missing required flag returns a clear error plus a usage example instead of silently prompting — an agent gets a recoverable signal, not a stall.
  • _meta self-versioning. Any --json output embeds version / latestVersion / updateAvailable from a 24-hour cache (no network call), so an agent can notice it is running an outdated CLI without a separate upgrade --check.
  • CI-safe diagnostics. doctor --json always exits 0; gate on the payload’s ok field (jq -e '.ok'). Update notices and telemetry auto-suppress in CI / non-TTY shells.
  • Deterministic option. render --docker yields reproducible output — the contract you want when wiring rendering into a scheduled or durable agent loop.

Try It

  • Smoke-test the toolchain: npx hyperframes doctor (or doctor --json | jq .ok) to confirm Node 22+, FFmpeg, and Chrome are present before anything else.
  • Zero-to-MP4 by hand: npx hyperframes init demo --non-interactive --example warm-grain && cd demo && npx hyperframes preview, edit index.html, then npx hyperframes render --output demo.mp4.
  • Render one composition many ways: declare data-composition-variables, then npx hyperframes render --variables '{"title":"Q4"}' --output q4.mp4 — the foundation for lambda render-batch / cloudrun render-batch personalization at scale.
  • Go infra-free: hyperframes auth login once, then hyperframes cloud render ./demo — no local Chrome/ffmpeg/AWS needed.
  • Wire CI gating: hyperframes doctor --json | jq -e '.ok' and hyperframes lint --json as pre-render checks; hyperframes upgrade --check --json to flag drift.

Graph View

Backlinks