ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-10-30 09:16:55 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
688229314fb219c4317351c25483ecc3c56a519b
hyperframes/docs/packages/cli.mdx
T
WaterrrForeverandClaude Opus 5.5 688229314f feat(skills)!: publish seven knowledge skills aligned with Studio and retire the workflow skills (#5651) 
* refactor(skills): fold six domain skills into hyperframes and media-use guides

hyperframes-core, -animation, -keyframes, -creative and -studio move to
skills/hyperframes/{core,animation,keyframes,creative,studio}/, and
hyperframes-audio moves to skills/media-use/mix/. Each moved SKILL.md becomes
a frontmatter-free GUIDE.md so installers that scan recursively for SKILL.md
no longer see them as skills; the published list goes from 21 to 15.

Relative links, code paths and skill-name mentions are rewritten to the new
locations, the catalog surfaces, marketplace core-skills list, fallback core
set, module-copy targets and skills-manifest.json follow, and
`hyperframes skills update` now removes the retired skills (RETIRED_SKILLS)
when they are still installed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): slim the core entries and give media-use a HeyGen and a free path

The four entries every run opens are rewritten to what an agent cannot infer:
hyperframes 21.8 KB to 7.7 KB, hyperframes-cli 24.8 KB to 6.9 KB,
hyperframes-registry 9.9 KB to 4.3 KB, media-use 9.7 KB to 4.9 KB. Detail moved
whole into references (routing close calls and creator edits, CLI pin upgrades,
catalog search tiers, CLI conventions and feedback reports).

- hyperframes: state table, routing, the render contract, a terminal work loop
  (check, snapshot, preview before render), the desktop-app hand-off, and a
  table of the folded guides.
- media-use: one table of HeyGen versus free local tools per need; HeyGen
  sign-in, credits and the CLI's video-agent, avatar, clone, lipsync, translate
  and clipping commands; every free path works with no account.
- scripts/check-core-skills.mjs holds entries and descriptions to budget and
  checks every taught `npx hyperframes` command and path; runs in lint.
- Core entries are exempt from the formatter: its table padding cost ~1.5 KB
  per entry on every run.
- Content tests follow the text to its new home.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): plugin runs skip skills update; media-use explains HeyGen sign-in and TTS setup

The smoke eval showed a presenter request never reaching media-use and the
free voiceover failing on a missing kokoro-onnx; plugin runs also ran the
skills update the plugin rules forbid.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(skills): drop a committed Python bytecode file and ignore bytecode

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): align the entry with the Studio skills and keep the workflows' measured facts

The entry drops routing and the intent interview and carries the contract, the
editable-project rules and the work loop. Studio's format, runtimes, motion,
look and captions references come over for terminal use, frame presets move to
assets/, media-use gains Studio's mixing and local-command references, and
film.md and overlays.md keep what the workflow skills measured.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills)!: retire the workflow skills and folded guides; publish seven knowledge skills

The skill pack now publishes exactly seven skills - hyperframes,
hyperframes-cli, hyperframes-registry, media-use, figma, slideshow and
remotion-to-hyperframes - carrying knowledge, not process. The eight
workflow skills, the folded domain guides and the routing/interview
references are deleted; their measured facts already live in the
hyperframes references (format, runtimes, motion, look, captions, film,
overlays) and media-use's mixing reference.

- bake-basemap.mjs and locate.mjs move to skills/hyperframes/scripts/
  (bake-basemap gains --help); extract-audio-data.py moves to
  media-use/audio/scripts/ for the caption motion reference.
- skills update: the eight workflows join RETIRED_SKILLS so existing
  installs prune them (by lock attribution only, since their names are
  generic); naming a retired skill reports where its knowledge went and
  succeeds instead of failing as unknown.
- Capture prompts point at the hyperframes skill's references/film.md;
  the live-map warning names the new bake-basemap path.
- Content tests that pinned knowledge are retargeted to the kept
  references; tests of deleted workflows, scripts and process go.
- Catalog surfaces, templates and docs describe the seven skills.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): resolve the local.md captions link and allow capture's output files in citations

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): regenerate the skills manifest from tracked files only

The committed media-use hash included an ignored __pycache__ bytecode file present
in the local checkout, so CI's clean checkout hashed differently.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(docs): restore generated catalog pages and docs navigation to main

Catalog PRs commit item sources only; CI regenerates the pages from the edited
registry sources. docs/docs.json is catalog navigation, so its Workflows group
rename is left for a non-catalog PR.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* build(cli): raise the CLI size budget for the skill references it bundles

The CLI bundles skills/hyperframes, which now carries the folded domain guides and
frame presets (155 KB to 1.08 MB in git). Budgets are the CI-measured size plus 5%:
packed 7526634, unpacked 22593213.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test: keep repo-sweep guards meaningful after the workflow skills left

The last shell ffprobe caller and most root index.html examples lived in retired
skills. The shell detector is now pinned on a literal command line, and the
structure-rule sweep needs more than 5 roots (11 remain) rather than 30.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): slim figma, slideshow and remotion to the Studio shape; restore the storyboard board

slideshow 33.5 KB to 4.9, figma 18.2 to 6.2, remotion-to-hyperframes 11.0 to
4.9, each keeping the facts only it holds (the figma motion helpers, verify gate,
storyboard decoding and usage beacons; present and hand-off; the Remotion lint,
SSIM check and API map). The board page format from the storyboard recipe comes
back as hyperframes/references/storyboard.md: the desktop app's Storyboard tab
reads boards/storyboard.html by its frame, title and time classes. The entry and
the init template now say to snapshot the moments an edit changed before
replying, which the terminal eval found skipped in 22 of 38 runs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): manifest without local bytecode; Studio's edit prompt names kept files

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): render when the person asks for the file or for no stops, not only after approval

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): keep the voiceover carve in media-use; presets stage their own fonts

Review follow-ups on #5651:
- carve.mjs and its tests move to skills/media-use/audio/scripts; the audio
  docs, mixing.md and two Studio comments point there.
- code-editorial's FRAME.md says to copy its bundled WOFF2s and add the
  @font-face blocks, instead of promising the retired build-frame.mjs.
- media-use states the host rule before the HeyGen sign-in steps.
- storyboard-format marks transition_in as a note the agent builds itself.
- Two stale citations (creator-editing-recipes.md, sub-compositions.md).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* chore(skills): regenerate the manifest without local bytecode

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): the CLI render step follows step 4's rule, not approval alone

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(ci): run the core-skills check from lint again after the main merge

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): films that tell a story start from three storylines; maps use real imagery

Opus 5.5 arm D read motion.md and applied it, but its launch film was a
feature list (pain, three feature cards, proof, logo): film.md left story
to the model. And the map case never opened film.md, so it drew Natural
Earth outlines instead of baking satellite tiles.

- references/story.md: the generic half of Studio's moment-film story and
  craft (one thing, three storylines with world and device, the hook,
  beats, worlds, copy, brand, tells of a generated film). The person picks
  a storyline, or the agent takes its recommendation when asked for the
  file or for no stops.
- The entry's work loop names the storyline step for films over ~15 s; the
  references table routes stories to story.md and maps to film.md.
- film.md points at story.md and gives maps and real places a section.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): story.md follows the entry: no voiceover unless asked

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): bake-basemap starts from a globe and stops waiting out its idle timeout

The Opus 5.5 map run spent 13 of its 38 minutes on parallel bakes that
stalled and 15 more recording 300 frames, after rewriting the script because
it could only start on a flat map.

- PROJECTION=globe with a seeded starfield and atmosphere, and FROM/PAN to
  turn the globe to CENTER before the dive.
- Each frame polls for loaded tiles instead of waiting for an "idle" event
  that had often already fired: 30 frames went from 198-219 s to 10-13 s
  locally with byte-identical frames.
- Progress prints seconds a frame and minutes left; film.md shows the globe
  call and says to run one bake at a time.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): render in the foreground; wait on a detached render's log, never pgrep -f

Both Opus 5.5 explainer runs started a detached render, then waited with
`until ! pgrep -f "hyperframes render"`, which matches its own loop: each
render took 88-117 s and the wait sat for the tool's full 10 minutes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): route each kind of film; storylines carry look and sound; add review and sound

The entry routes by request (launch, explainer, music, data, vertical, 3D,
character) to a self-contained file under references/types/, and a film
over ~15 s now gets music and sounds on its visible actions unless the
person asked for silence. Each storyline names its look and its sound, so
picking one picks both; STORYBOARD.md frames carry `reads` and `sound`.

review.md is the whole-film pass: the check warnings, the review sheets,
seven questions to look for, P0/P1/P2 notes and REVIEW.md. motion.md gains
eases by role, six title entrances, a reading-time rule and nine measured
transitions; look.md a design plan before the first scene, with presets
kept for decks and named picks. story.md adds the second default that
generated design falls into, with what to do instead.

The blank template and format.md no longer teach the fade-and-slide-up
entrance on a dark canvas.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(cli): check warns on unread lines, dead stretches, small type, empty frame 0 and silence

A coding agent cannot watch its film, so check now measures what a viewer
notices over time. A new `craft` section holds warnings only (exit 0
unless --strict), sampled on the dense 8 fps grid the overlap pass
already seeks, skipped for --range checks:

- line_unread: a reading-size line (>= 30 px tall at 1080) on screen
  under 0.4 s for 1-2 words, else under 3/4 of 0.5 s + 0.3 s a word;
  the film's last line needs 2 s. Short lines are re-measured between
  samples to ~0.01 s before judging. Captions-track and
  data-layout-ignore text are exempt.
- dead_stretch: more than 3 s where the keepsMoving liveness signature
  does not change, outside the final 3 s and any data-hold element;
  quiet when sweep_static fires or a whole-composition keepsMoving
  assertion owns the limit.
- text_below_floor: text under 2.6% of the short side (28 px on 1080)
  held 0.5 s, one finding per file listing every element.
- first_frame_empty: frame 0 paints only the background.
- film_silent: over 15 s with no unmuted audio or audible video.

Each message names the fix and the skill reference to read. keepsMoving
now also leaves the film's last 3 s (a still end card) out of its
static runs, so the two agree.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(cli): snapshot --review captures a beat sheet, seam strips and a phone sheet

snapshot --review picks the frames that show a film over time instead of
evenly spaced ones, in the same single browser session:

- review-beats.jpg: one settled frame per scene at its start + 0.3 s,
  plus one per timed data-beat="name" element, labelled time and id.
  Scenes are the composition's top-level timed clips and sub-composition
  hosts, read like `timeline` reads rows (captions and audio excluded)
  and timed by the runtime's start resolver over the live page.
- review-seam-NN.jpg: frames at -0.2, -0.1, 0, +0.1, +0.2 s around
  every cut (each scene start, and any scene end no scene starts at).
- review-phone.jpg: the beat frames at 360 px wide.

--composition scopes the review to one sub-composition; with fewer than
two scenes the beats spread evenly and a note says so. snapshot also
gains --json: one envelope with every frame's path and time and, under
--review, the scenes, beats and seams behind the sheets; progress moves
to stderr.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): craft warnings stay out of --strict; a hold gets a real next action, not a caret

Craft findings (unread lines, dead stretches, small type, an empty first
frame, silence) are judgment calls a film may break on purpose, so
--strict keeps gating defects only. The check reference no longer
suggests a blinking caret to keep a still frame moving.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): review spreads beats when every scene starts together; map credits skip the type floor

A map film whose basemap and overlay both start at 0 s got one beat
frame; the even spread now keys on distinct scene starts. film.md tells
agents to mark the imagery credit data-layout-ignore and back it, since
the new type floor flagged it on the first real run.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): review frames each scene at its middle too, not only 0.3 s in

On the first real explainer, 0.3 s into a scene showed a bare colour
field before its title entered. Each scene longer than about a second
and a half now adds a frame at its middle, so the sheet shows what the
scene builds.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(skills): a film is built from a numeric SPEC.md, with defaults banned by name and a look test

Studied in full: flxrnc's Motion Lab (vague vs directed prompt), 0xMovez's
course, EianLu's riso skill, agentchengfeng's style samples and the two
Opus 5.5 guides. Their common point: adjectives are where the default look
lives, so the agent now writes SPEC.md before any scene (GOAL, OUTPUT,
TIME, LOOK, MOTION, SHOTS, BANNED, QA), with a number for every adjective.

spec.md bans the defaults by name, unless the brand or reference uses
them (a dark void with small things floating, glow and particles, the
cream-serif-mono-label look, fade-and-slide-up, corner brackets), and
grows that list after the first render. Each storyline gets a 3 s test of
its hero shot before the pick; a look is written as the rules of one
medium. Composition numbers: the hero fills 40% of the frame, one hero
move per shot, the shot's information in within 2.5 s then a held poster.

motion.md adds springs by damping ratio, shorter exits, overlap, stagger
and the beat grid; review.md reviews as a harsh director and grows BANNED;
vertical.md takes the riso skill's measured safe band; explainer.md the
shapes of information.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): story before look; every object reads as itself; posters only for info cards

The first spec-driven C02 swapped the dark default for a flat Swiss
poster, and the story went with it: two black bars nobody read as mirrors,
slogans instead of cause and effect, a storyline picked for its picture.

The spec now serves the story: a storyline is picked for the story a
stranger would follow, the look test asks first whether a stranger
understands what they see, and SPEC.md gains an OBJECTS line giving each
thing the material and details that make it read without a label. The
2.5 s held-poster rule is limited to information cards; in a story film
every shot causes the next. Explainers start from a person or situation
the viewer knows. Review names every object as a stranger would and
treats one that needs explaining as a P0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(skills): storylines are three films in words, each with a device and a form

The three storylines are pitched as text and the person picks from them;
nothing is built for a storyline before the pick, so the 3 s hero-shot
look test is gone. Ideas pair a device with a form, five or more first,
keeping the three that differ most, and the one stop states the rest in
an assumption line that names every paid item beside its free option.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* ci: list main's new embedded-captions hf-cli test among the retired workflow files

The merge with main removed it with the rest of the retired skill, and the
deletion guard rejects any removal it has not been told about.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(core): keep the audio preset comment within core's size budget

The comment's new citation to media-use's mixing reference made the published
package 14 bytes larger than its budget, which sits at main's exact size.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): craft keeps its own 8 fps grid; comments back within the checks

Review on #5651 found that the merge moved craft onto the overlap pass's
times, which main caps at 180, so a brief line in a long film fell between
samples and line_unread missed it. Craft now builds its own grid at 8 fps up to
600 samples, as before the merge, and a 60 s film with a line shown for 0.2 s
pins it.

The Comments check passes again: REVIEW.md and STORYLINES.md join the files a
skill writes into a project, the comment lines this branch added come back
under each file's share at the merge-base, and the audio preset comment drops
a word the check reads as history.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-21 19:19:31 +00:00

2249 lines
136 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: CLI
sidebarTitle: "CLI reference"
description: "Create, preview, and render HTML video compositions from the command line."
---
This page lists every command and every flag. If you are still deciding which
command you need, the [CLI guide](/developers/cli) is the shorter route.
The installed version is always the authority. Run
`npx hyperframes <command> --help` to see exactly what your copy accepts.
```bash
# No install needed
npx hyperframes <command>
# Or install once
npm install -g hyperframes
```
## Find your command
| You want to | Use |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Start a project | [`init`](#init), [`add`](#add), [`catalog`](#catalog) |
| Bring in source material | [`capture`](#capture), [`transcribe`](#transcribe), [`tts`](#tts), [`remove-background`](#remove-background), [`media-treatment`](#media-treatment), [`beats`](#beats), [`audio`](#audio), [`normalize-audio`](#normalize-audio) |
| Look at it, or share it | [`preview`](#preview), [`present`](#present-and-play), [`play`](#present-and-play), [`publish`](#publish), [`open`](#open-and-catch-up), [`catch-up`](#open-and-catch-up) |
| Find problems | [`lint`](#lint), [`check`](#check), [`snapshot`](#snapshot), [`keyframes`](#keyframes), [`compare`](#compare-and-grade-compare), [`grade-compare`](#compare-and-grade-compare) |
| Edit from the terminal | [`timeline`](#timeline), [`history`](#history) |
| Make a file | [`render`](#render), [`benchmark`](#benchmark) |
| Render somewhere else | [`cloud`](#hyperframes-cloud), [`lambda`](#hyperframes-lambda), [`cloudrun`](#hyperframes-cloudrun) |
| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions) |
| Connect other tools | [`auth`](#hyperframes-auth), [`skills`](#skills), [`figma`](#figma-and-events), [`telemetry`](#telemetry), [`feedback`](#feedback) |
`validate`, `inspect`, and `layout` still work but are
[deprecated](#deprecated-validate-inspect-and-layout). Use `check` instead.
## What every command shares
Read this once and skip the repetition below.
**The project directory.** Most commands take it as the first argument and
default to the current directory: `npx hyperframes check ./my-video`. A few
take it as a flag instead — `add`, `transcribe`, `feedback`, `skills`, `history`, and
the `timeline` edit commands use `--dir`.
**`--json` for agents and scripts.** Almost every command accepts it. The
payload is wrapped with a `_meta` field so a script can spot an outdated CLI
from any command's output, without a second call:
```json
{
"name": "my-video",
"duration": 10.5,
"_meta": {
"version": "0.1.4",
"latestVersion": "0.1.5",
"updateAvailable": true
}
}
```
The version numbers come from a cache refreshed at most once a day, in a
background process, and never under CI or `HYPERFRAMES_NO_UPDATE_CHECK=1`.
`--json` never makes a network request of its own. Deprecated commands add
`_meta.deprecated: true`.
**Flags, not prompts.** A missing required flag fails immediately with a usage
example rather than waiting for input. Two commands are interactive on a TTY:
`init` prompts for a project name and example unless you pass
`--non-interactive`, and `catalog --human-friendly` opens a picker. Nothing else
prompts, apart from confirmations you can skip with `--yes` or `--no-confirm`.
**Version notices.** An owned install (npm, bun, pnpm, brew) updates itself
quietly in the background and prints one line on the next run:
`hyperframes auto-updated to v0.1.5`. It never crosses a major version. Anywhere
it cannot install — `npx`, an unknown installer — you get a notice instead:
```
Update available: 0.1.4 → 0.1.5
Run: npx hyperframes@latest
```
Both stay silent in CI and non-TTY shells. `HYPERFRAMES_NO_UPDATE_CHECK=1` turns
off the check, the install, and the notice.
## Create a project
### `init`
Scaffold a new composition project from an example.
```bash
# Default: centered Inter blank. Non-TTY skips the wizard.
npx hyperframes init my-video
# Start from a video file
npx hyperframes init my-video --video video.mp4 --non-interactive
# With the Tailwind browser runtime
npx hyperframes init my-video --tailwind
```
| Flag | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--example, -e` | Example to scaffold. Default is the centered blank. See [Examples](/examples) for the full list. |
| `--resolution` | Canvas preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` (2160×3840), `square` (1080×1080), `square-4k` (2160×2160). Aliases: `1080p`, `4k`, `uhd`, `1080p-square`, `square-1080p`, `4k-square`. Default: keep template dimensions. |
| `--video, -v` | Path to a video file (MP4, WebM, MOV) |
| `--audio, -a` | Path to an audio file (MP3, WAV, M4A) |
| `--tailwind` | Add Tailwind CSS browser-runtime support to the scaffolded HTML |
| `--non-interactive` | Never prompt. For agents and CI. |
| `--skip-transcribe` | Skip the automatic Whisper transcription |
| `--keep-original` | Copy the `--video` file as is instead of converting a non-web codec to H.264 MP4 |
| `--model` | Whisper model for that transcription (for example `small.en`, `medium.en`, `large`) |
| `--language` | Language code for transcription (`en`, `es`, `ja`, …). Filters out speech in other languages. |
| `--skip-skills` | Currently ignored. Set `HYPERFRAMES_SKIP_SKILLS=1` to opt out in CI or tests. |
Pass `--video` or `--audio` and the CLI transcribes the audio with Whisper and
patches the captions into the composition for you. `--skip-transcribe` turns
that off.
`--tailwind` injects the pinned Tailwind v4 browser runtime and exposes a
`window.__tailwindReady` promise that renders wait on before capturing frame 0.
The `/hyperframes-cli` skill's `references/init-and-scaffold.md` (Tailwind)
covers editing these projects, so agents follow v4 CSS-first patterns instead
of v3 `tailwind.config.js` patterns. The browser
runtime is meant for scaffolded projects and quick iteration — for offline or
locked-down production renders, compile Tailwind to CSS and link the stylesheet.
After scaffolding, `init` checks and installs the core AI skills from the
current GitHub source. See [`skills`](#skills).
### `add`
Install one item from the registry into a project you already have.
[`init`](#init) scaffolds whole projects; `add` drops in a **block** (a
sub-composition scene) or a **component** (an effect or snippet).
```bash
npx hyperframes add claude-code-window # a block
npx hyperframes add shader-wipe # a component
npx hyperframes add captions # every block with this tag
npx hyperframes add shader-wipe --dir ./my-video
npx hyperframes add shader-wipe --no-clipboard --json # headless / CI
```
The positional name is a registry item, or a tag — a tag installs every block
carrying it. `--dir` picks the project directory, `--json` prints the written
files and paste snippet, and `--no-clipboard` skips the clipboard copy for CI.
Every install produces files plus a **paste snippet**: the `<iframe>` tag for a
block, or the fragment path for a component. It goes to your clipboard by
default. Naming an example instead of a registry item (`add warm-grain`) gets
you a clear error pointing at `init --example`.
`add` reads [`hyperframes.json`](#hyperframes-json) to learn which registry to
pull from and where files land. If it is missing but the directory has an
`index.html`, a default one is written on first use.
When an item declares `registryDependencies`, `add` installs its dependencies
first, resolving them transitively. Before installing any item files, it checks
`minCliVersion` on every resolved item and reports upgrade guidance for an
incompatible CLI. A `deprecated` message produces a warning without blocking
installation.
### `catalog`
Browse the registry.
```bash
npx hyperframes catalog # table of everything
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly # picker; installs on select
```
Filter with `--type` (`block` or `component`) and `--tag` (`social`,
`transition`, `text`, …). Default output is a table of name, type, description,
and tags, shaped for agents to parse; `--json` is the structured form. Each
`--json` row has the item's name, type, title, description and tags, plus its
dimensions, duration and `preview` (`video` and `poster` URLs) when it has them.
`--human-friendly` opens a picker that runs `add` on whatever you select.
`--query "<what you want>"` searches by description instead of listing
everything, and `--on-device` switches that search from word match to meaning
search after a one-time 33 MB download. What each does, what is downloaded and
what stays on your machine: [How catalog search works](/developers/catalog-search).
## Bring in source material
### `capture`
Pull a real website into a working folder an agent can build from.
```bash
npx hyperframes capture https://stripe.com
npx hyperframes capture https://linear.app -o linear-capture
npx hyperframes capture https://example.com --json
```
```
◇ Captured Stripe | Financial Infrastructure → capture
Screenshots: 12
Assets: 45
Dropped: 9 (6 size-floor, 3 cap-reached)
Sections: 15
Fonts: sohne-var
```
Website capture accepts public HTTP(S) destinations without URL credentials.
Browser traffic goes through a per-capture proxy, and asset downloads use the
same checked-address policy. Each connection uses a validated numeric IPv4
address; redirects and later requests are checked again. Private, loopback,
link-local and special-use addresses are refused. IPv6-only sites are currently
unsupported. Plain WebSocket upgrades are refused; slow or refused resources
may be absent from the capture.
Capture needs direct internet access. Since 0.8.164 it does not use
`HTTPS_PROXY` or `HTTP_PROXY`: its own proxy dials each checked public address
itself. Where the only way out is a proxy, as in some sandboxes and corporate
networks, every page fails with `net::ERR_TUNNEL_CONNECTION_FAILED`, even though
`curl` reaches the same site through that proxy.
Capture uses a temporary browser profile with non-proxied WebRTC UDP disabled.
The profile and proxy are removed when the browser closes. The Chromium sandbox
is retained on macOS and Windows; Linux retains the container compatibility
exception.
Ancestor `.env` files can supply the supported vision API keys, models, Vertex
credentials/location and vision timeout. They cannot change the browser path,
executable discovery, TLS, proxy or process runtime settings. Set
`HYPERFRAMES_NO_CAPTURE_DOTENV=1` in the calling environment to skip these files.
An inherited `HYPERFRAMES_BROWSER_PATH` still selects a browser.
`Dropped` is how many assets the page referenced that are **not** in the
folder, and why. It is printed only when it is non-zero, and `--json` always
carries it as a `dropped` object. Without it, a capture of a spare page and a
capture that a limit truncated are the same three-line summary, and the only
way to tell them apart is to open the page yourself.
| Reason | What it means |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| `size-floor` | Fetched, then judged too small to be a real asset rather than a spacer or tracking pixel. |
| `budget-exhausted` | `--capture-budget` ran out before this one was reached. Raise it, or pass `--skip-vision` to buy time. |
| `cap-reached` | A per-run or per-family limit was already met: 30 inline SVGs, 30 fonts, 6 faces per family. |
| `unavailable` | The request or the write failed: network error, timeout, refused address, bad status, disk. |
Three of those are decisions the capture made and one is a failure it hit, so a
run that is thin with an all-zero `dropped` is a thin page, and a run that is
thin with counts on it was cut short.
```json
{
"assets": 45,
"dropped": { "size-floor": 6, "budget-exhausted": 0, "cap-reached": 3, "unavailable": 0 }
}
```
| Flag | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--output, -o` | Output directory. Default `./capture`, then `./capture-2/`, `./capture-3/`, … if that name is taken. |
| `--timeout` | Page load timeout in ms (default 120000) |
| `--capture-budget` | Budget in ms for everything after the page loads (default 120000). Cooperative — it stops new work, but cannot interrupt work already running. |
| `--skip-assets` | Do not download images and SVGs |
| `--skip-vision` | Do not run AI image captioning |
| `--max-screenshots` | Maximum page-capture files, including the full-page plate; derived contact sheets are excluded. Positive integer; default 21. A value of 1 captures only the top viewport. |
| `--json` | Structured output for programmatic use |
| `--video <folder>` | Switch to video-download mode against a captured folder's manifest. Pair with `--list`, `--index`, or `--video-url`. |
You get `AGENTS.md`, `CLAUDE.md`, `meta.json`, scroll screenshots, extracted
HTML and CSS, visible text, design tokens, font files, images, SVGs, animation
metadata, and contact sheets — plus whatever Lottie, video, and WebGL context
the page exposed. It is raw material for an agent, not a finished composition;
the `/hyperframes` skill uses it when a real product has to appear on screen. Dynamic sites, protected pages, and unusual media loaders produce
partial results, so read `dropped`, the warnings, and the contact sheets before
you build.
For AI image descriptions, set `GEMINI_API_KEY` in a `.env` file
(~$0.001/image), or `OPENROUTER_API_KEY` to route any vision model through
[OpenRouter](https://openrouter.ai) — it wins if both are set, and
`HYPERFRAMES_OPENROUTER_MODEL` overrides the model.
### `transcribe`
Turn audio or video into word-level timestamps, or import a transcript you
already have.
```bash
# Local transcription
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
# Import from another tool
npx hyperframes transcribe subtitles.srt
npx hyperframes transcribe openai-response.json
# Export a caption sidecar, from a transcript or straight from the media
npx hyperframes transcribe transcript.json --to srt
npx hyperframes transcribe video.mp4 --to vtt
```
| Flag | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dir, -d` | Project directory (default: current directory) |
| `--engine, -e` | ASR engine: `auto` (default — Parakeet if installed and the language is one of its 25, else whisper), `parakeet` (fails if Parakeet is missing, broken, or lacks the `--language`), or `whisper`. Under `auto` or `parakeet`, a `--language` other than English runs whisper when it is installed, with a note, because Parakeet detects the language itself |
| `--model, -m` | Whisper model (default `small.en`): `tiny.en`, `base.en`, `small.en`, `medium.en`, `large-v3` |
| `--language, -l` | Language code (`en`, `es`, `ja`, …). Whisper transcribes as this language; Parakeet detects the language itself, so it only takes a non-English `--language` when whisper is not installed. |
| `--to` | Write an `srt` or `vtt` sidecar: from a transcript file it exports instead of importing; from audio or video it is written beside `transcript.json`, with cues for languages without spaces grouped, which exporting that `transcript.json` later may split differently |
| `--output, -o` | Where the exported SRT/VTT goes |
| `--preserve-cues` | Keep each transcript entry as its own caption cue, skipping word-level grouping |
| `--optional` | Skip and exit 0 when whisper-cpp is unavailable, instead of failing. For pipelines that can carry on without captions. A broken Parakeet install is a real failure: it exits 1 even when whisper-cpp is missing. |
| `--timeout` | Whisper spawn timeout in ms, overriding the auto-scaled default. Raise it on slow or emulated CPUs where large models take many seconds per audio second. Whisper only — Parakeet has its own. Minimum 5000. Env: `HYPERFRAMES_TRANSCRIBE_TIMEOUT_MS`. |
| `--json` | Output the result as JSON |
The command works out what you gave it. Audio and video are transcribed
locally — Parakeet when it is installed (`hyperframes models install parakeet`;
faster and more accurate), whisper.cpp otherwise. Parakeet covers en, es, fr,
de, bg, hr, cs, da, nl, et, fi, el, hu, it, lv, lt, mt, pl, pt, ro, sk, sl, sv,
ru and uk; `auto` uses whisper for any other `--language`. If Parakeet fails under
`auto`, the run says why, names the repair command, and uses whisper. Transcript files are imported and
normalized instead: whisper.cpp JSON, OpenAI Whisper API JSON with word
timestamps, SRT, and VTT all land as the same `[{text, start, end}]` word array
in `transcript.json`. If the project has caption HTML, it is patched
automatically.
Word-level transcripts get grouped into readable cues at sentence boundaries.
Exporting straight from an `.srt` or `.vtt` keeps that file's cue boundaries.
Add `--preserve-cues` when the source `transcript.json` already holds finished
cues with no internal spaces — single-word or CJK captions.
<Tip>
For music or noisy audio, `--model medium.en` is noticeably more accurate. For
production content, transcribe through the OpenAI or Groq Whisper API and import
the JSON.
</Tip>
### `models`
List or download on-device models. Only asked-for installs happen; nothing downloads
on first use.
```bash
npx hyperframes models list # Parakeet and any downloaded whisper models
npx hyperframes models list --json # { ok, models: [{ engine, model, installed, runner, path }] }
npx hyperframes models install parakeet # progress on stderr
npx hyperframes models install parakeet --json # one JSON result
```
`list` reports Parakeet as installed only when `transcribe` would use it, through
the CLI's own runtime or `parakeet-mlx` (`runner`), and gives the reason when this
machine cannot run it. Whisper models appear once
`transcribe` has downloaded them.
`parakeet` installs the sherpa-onnx runtime from npm and NVIDIA's Parakeet TDT
0.6B v3 speech model (int8, about 640 MB, CC-BY-4.0) into
`~/.cache/hyperframes`. Every file is checked against a pinned size and
sha256. Re-running loads the runtime in a separate process and re-checks each
model file's sha256, reinstalls whichever fails, and changes nothing on a good
install. It runs on macOS
(arm64, x64), Windows (x64, ia32) and Linux (x64, arm64, glibc 2.32 or newer),
and refuses up front anywhere else. Ctrl-C stops the download and keeps no
partial file.
### `tts`
Generate speech with a local model (Kokoro-82M). No API key, nothing leaves the
machine.
```bash
npx hyperframes tts "Welcome to HyperFrames"
npx hyperframes tts "Intro" --voice bf_emma --output narration.wav
npx hyperframes tts "Slow and clear" --speed 0.8
npx hyperframes tts script.txt
npx hyperframes tts --list
```
| Flag | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--output, -o` | Output path (default `speech.wav` in the current directory) |
| `--voice, -v` | Voice ID. Run `--list` to see them all. |
| `--speed, -s` | Speed multiplier (default 1.0) |
| `--lang, -l` | Phonemizer locale: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`. Inferred from the voice ID when you leave it out. |
| `--list` | List the voices and exit |
| `--json` | Output the result as JSON |
A voice ID's first letter is its language: `a` American, `b` British,
`e` Spanish, `f` French, `h` Hindi, `i` Italian, `j` Japanese, `p` Brazilian
Portuguese, `z` Mandarin. So `--voice ef_dora` already speaks Spanish. Reach for
`--lang` only to deliberately mismatch them — English text through a French
phonemizer, for a stylized accent.
<Tip>
To get narration *and* caption timing in one pass: generate the audio with `tts`,
then run [`transcribe`](#transcribe) on the result.
</Tip>
### `remove-background`
Cut the background out of a video or image with a local AI model. The output is
transparent media you can drop straight into a `<video>` or `<img>`. No green
screen.
```bash
# Default: VP9-with-alpha WebM, plays natively in HTML5
npx hyperframes remove-background avatar.mp4 -o transparent.webm
# ProRes 4444 for an editing round-trip
npx hyperframes remove-background avatar.mp4 -o transparent.mov
# One image → transparent PNG
npx hyperframes remove-background portrait.jpg -o cutout.png
# Cutout and inverse-alpha background plate in one pass
npx hyperframes remove-background avatar.mp4 -o subject.webm --background-output plate.webm
# What providers does this machine have?
npx hyperframes remove-background --info
```
| Flag | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--output, -o` | Output path. The format follows the extension: `.webm` (default), `.mov`, `.png`. |
| `--background-output, -b` | Second output: the inverse-alpha plate, with the subject region transparent and its surroundings opaque. Must be `.webm` or `.mov`. It is a hole cut, not inpainted — composite something underneath. |
| `--device` | Execution provider: `auto` (default), `cpu`, `coreml`, `cuda` |
| `--quality` | WebM preset: `fast` (crf 30), `balanced` (crf 18, default), `best` (crf 12). Higher keeps the cutout's RGB closer to the source, which matters when you overlay it on its own footage. `.webm` only. |
| `--info` | Print the detected execution providers and exit |
| `--json` | Output the result as JSON |
Which format do you want?
| Format | Use case | Size (4s @ 1080p) |
| -------------------- | --------------------------------------------------------- | ----------------- |
| `.webm` (VP9 alpha) | Drop into `<video>` for HTML5-native transparent playback | ~1 MB |
| `.mov` (ProRes 4444) | Editing round-trip in Premiere / Resolve / DaVinci | ~50 MB |
| `.png` | Single-image cutout | varies |
The model is `u2net_human_seg` (Apache-2.0, ~168 MB ONNX). It downloads to
`~/.cache/hyperframes/background-removal/models/` on first run and is reused
after that. Peak inference RAM is about 1.5 GB.
`--device auto` picks CoreML on Apple Silicon, CUDA where available, CPU
otherwise. The first run installs the CPU build of `onnxruntime-node` into
`~/.cache/hyperframes/optional/` (one line on stderr, once, no prompt); for CUDA, set
`HYPERFRAMES_CUDA=1` and supply a GPU-enabled build. With
`HYPERFRAMES_NO_OPTIONAL_INSTALL=1` the CLI installs nothing on first use (this
package, `@google/genai`, or a missing `sharp`) and the command fails, naming the package;
a comma-separated list such as `HYPERFRAMES_NO_OPTIONAL_INSTALL=sharp` turns off only those.
<Tip>
Chrome's `<video>` only honours the alpha plane when the WebM is `yuva420p` with
the `alpha_mode=1` metadata tag. The CLI sets both. If you re-encode the output
yourself, keep them.
</Tip>
The [Remove background guide](/guides/remove-background) has the whole
workflow — using transparent video in compositions, per-platform performance,
where `u2net_human_seg` falls down, and free alternatives.
### `media-treatment`
Read or edit the colour and effect treatment stored on images and videos.
```bash
# Find out what exists, then look at one family or effect
npx hyperframes media-treatment --capabilities --json
npx hyperframes media-treatment --capability kuwahara --json
# Measure a selected local source
npx hyperframes media-treatment --selector '#hero' --analyze --json
# Apply, preview, or clear
npx hyperframes media-treatment --selector '#hero' \
--grading '{"preset":"skin-soft","intensity":0.6}' --apply
npx hyperframes media-treatment --file compositions/scene.html --selector 'video' \
--grading '{"preset":"warm-daylight"}' --dry-run --json
npx hyperframes media-treatment --selector '#hero' --clear
```
| Flag | Description |
| ---------------------- | --------------------------------------------------------------------- |
| `--capabilities` | Print the concise capability overview |
| `--capability <id>` | Inspect one family, control, effect, preset, or palette |
| `--all` | Print the exhaustive capability catalog |
| `--project <dir>` | Project directory (default: current directory) |
| `--file <path>` | Composition file (default `index.html`) |
| `--selector <css>` | CSS selector; every matched `<img>`, `<video>` or `<canvas>` gets the patch |
| `--selector-index <n>` | Zero-based match index to patch only one of several matches |
| `--grading <json>` | Validated colour-grading patch |
| `--apply` | Apply the patch |
| `--analyze` | Measure the selected local media and suggest a bounded correction |
| `--clear` | Remove colour grading from the target |
| `--dry-run` | Validate and report without writing |
| `--json` | Agent-readable JSON |
`--dry-run` accepts `--grading` without `--apply` and writes nothing. JSON includes `count`, `attribute`, the exact normalized `value` that apply would write (or `null` to remove it), and `lint`, the color-grading lint verdict and findings for the proposed HTML. When the selector matches several elements, each gets the patch merged into its own current grading, and JSON lists them under `targets` (each with its own `value`) instead of a single `value`; run `--clear` first for an identical look. Matches come from the main document or, when it has none, from the first `<template>` that has any, the same scope rule as Studio's source edits.
The command writes `data-color-grading` — the same contract Studio, preview, and
render all read, so the two can never disagree. It does not recognise subjects
or isolate part of an image; the effect covers the whole media layer.
### `beats`
Find the beats in a composition's music and write them where Studio expects
them.
```bash
npx hyperframes beats [dir]
npx hyperframes beats [dir] --json # { ok, file, count, bpm }
```
`beats` finds the music track — an `<audio>` element with
`data-timeline-role="music"`, or an id like `music`, `bgm`, or `soundtrack` —
decodes it with ffmpeg, runs the same beat tracker Studio uses, and writes
`beats/<audio-path>.json`:
```json
{
"version": 1,
"audio": "music.wav",
"beats": [{ "time": 2.027, "strength": 0.924 }]
}
```
Run it while authoring, so the file exists **before** Studio opens — Studio
loads this file as-is and only generates one when none exists. `time` is seconds
into the audio; `strength` (0–1) is relative loudness. Beats you add, move, or
delete in Studio save back to the same file.
A track without a steady beat (ambient, rubato, too short) gets no beat file:
the command fails and writes nothing rather than inventing a grid. Results
match Studio's to within a frame or two — Studio decodes in the browser, often
at a different sample rate, which can shift a beat slightly.
### `audio`
Measure how sound moves in time, so a cut or an animation can land on it.
```bash
npx hyperframes audio sfx/whoosh.mp3 # one file, in file seconds
npx hyperframes audio sfx/hit.wav --place-at 4.2 # not in the film yet: where it lands if it starts at 4.2 s
npx hyperframes audio --element '#riser' # one clip of the film, in film seconds
npx hyperframes audio --at 12 # every sound playing at 12 s
npx hyperframes audio --range 10,14 --only onsets # every hit between 10 and 14 s
```
Each sound reports:
- **moments**: where it starts (RMS first reaches 20% of its peak), where it
rises fastest, its loudest point, and where its tail fades 40 dB under the peak.
A short impact accents on its peak; a slow whoosh accents on its steepest rise.
- **onsets**: every hit, with a strength relative to the strongest.
- **loudness**: integrated and short-term-max LUFS (ITU-R BS.1770, matching
FFmpeg's `ebur128` to 0.1 LU), sample and true peak, clipping.
- **silence**: quiet spans under `--silence-db` (−50 dBFS).
- **kind**: a first guess of `sfx`, `voice` or `music`, with the features behind it.
- **envelope**: the level over time, about 2,000 values per sound.
A film query (`--element`, `--at`, `--range`) reads the project in
the current directory or `--dir`, finds the `<audio>` and `<video>` clips it
covers — nested compositions included — and analyzes only the part of each file
that plays. `--json` returns times in file seconds with each clip's placement
(`start`, `mediaStart`, `playbackRate`, and `dataStart`, the element's own
`data-start`, local to its composition), so film time is
`start + (t − mediaStart) / playbackRate`; the text output prints film time.
For a file not in the film yet, `--place-at <s>` answers as if it started at that
film second; `--skip-file-seconds <s>` cuts that much from the start of the file
first, and the result warns when the cut part held the file's loudest moment.
`--only` also asks for the music's structure, which is not measured unless asked:
- **beats**: beat times, or none with a `reason` (`no steady beat`, or too short
to tell) when the music has no beat to follow.
- **downbeats**: the first beat of each bar, with the `meter` (3 or 4). From
signal processing these are a guess (`confidence: "low"`).
- **bpm**: the tempo read off the beats (median interval), with a `curve` every
4 s for music that speeds up or slows down. It always comes from the provider
that answered `beats`.
- **sections**: spans where the sound stays alike, each with a letter; a part
that returns gets its earlier letter.
- **describe**: labels for what the audio holds, each with a score.
Word timing is not here: use [`transcribe`](#transcribe).
Every measurement comes from a provider ladder, tried in this order until one
answers:
| Capability | Ladder |
| --- | --- |
| moments, onsets, loudness, silence, envelope, kind | `signal` |
| beats, downbeats (and so bpm) | `api`, `apple-mu`, `beat-this`, `signal` |
| sections | `api`, `apple-mu`, `signal` |
| describe | `api`, `apple-sound` |
- `api` is an audio analysis service, used when `HYPERFRAMES_AUDIO_API_URL` and
`HYPERFRAMES_AUDIO_API_KEY` are both set. The audio is uploaded as 16 kHz mono
WAV through the same origin’s public asset direct-upload and completion endpoints.
Each decoded signal is uploaded once; analysis requests send its finalized asset ID as JSON.
The API key needs asset upload and audio-analysis permissions. Channels are averaged unless cancellation removes over 90% of the loudest
channel’s energy, in which case that channel is used. Requests carry the key in an `x-api-key` header and a new `Idempotency-Key` on each
request; the answer may come wrapped in `{ "data": … }`. Every beat,
downbeat or section boundary it answers moves onto the nearest beat signal
processing measured, when one is within a quarter beat; the rest are listed in
`snap.unsnapped`, and `snap.medianShiftMs` says how far the moved ones went.
- `apple-mu` is Apple's Music Understanding, which needs macOS 27. It is not
available yet.
- `beat-this` is [Beat This!](https://github.com/CPJKU/beat_this), used when
`HYPERFRAMES_BEAT_THIS_PYTHON` names a Python with `beat-this` installed and
its `small0` weights are on disk (`HYPERFRAMES_BEAT_THIS_CHECKPOINT`, or
`beat_this-small0.ckpt` in the Torch hub cache). The CLI never downloads them;
to set it up once:
```bash
uv init --bare ~/.beat-this
uv add --project ~/.beat-this "beat-this @ git+https://github.com/CPJKU/beat_this" torch torchaudio soundfile
~/.beat-this/.venv/bin/python -c "from beat_this.inference import load_checkpoint; load_checkpoint('small0')"
export HYPERFRAMES_BEAT_THIS_PYTHON=~/.beat-this/.venv/bin/python
```
- `apple-sound` is macOS's built-in sound classifier, through a small Swift
helper compiled once with the Xcode command line tools.
A provider that cannot run, or fails, is passed over with a warning that says
why. `--quality fast|local|best` limits which providers may run (`local` keeps
the audio on this machine, `fast` allows only signal processing),
`--provider beats=signal` pins one, and `--full` shows each ladder step.
Tune the analysis with `--onset-method`, `--threshold`, `--band lo,hi`,
`--hop-ms`, `--onset-ratio`, `--tail-db` and `--silence-db`. Decoding needs
FFmpeg.
## Look at it
### `normalize-audio`
Match one authored audio clip to a reference using the exact local media bytes
and FFmpeg's integrated EBU R128 loudness measurement.
```bash
# Measure only (the default)
npx hyperframes normalize-audio --reference target-audio --target user-audio
# Persist the computed gain on #user-audio
npx hyperframes normalize-audio --reference target-audio --target user-audio --write
# Agent-readable result
npx hyperframes normalize-audio --reference target-audio --target user-audio --json
```
`--reference` and `--target` are `<audio>` element ids, with or without `#`.
The reference stays unchanged; the command accounts for both clips' current
`data-volume` and writes the target's absolute matched gain. It measures
`data-media-start` and `data-duration`, rejects remote or out-of-project sources,
and refuses a result that exceeds Studio's +12 dB ceiling or would clip. Dry-run
is deliberate: inspect the measurement before passing `--write`. Use
`--tolerance <LU>` to change the default 0.5 LU no-op threshold.
### `preview`
Start a live preview server with hot reload.
```bash
npx hyperframes preview [dir]
npx hyperframes preview --port 4567
npx hyperframes preview --background # keep running after the command exits
npx hyperframes preview --foreground # stay attached in a non-interactive shell
npx hyperframes preview --status --json # inspect a managed preview from an agent
npx hyperframes preview --list # every running preview
```
| Flag | Description |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `--port` | Server port (default 3002) |
| `--open` / `--no-open` | Open a browser, or leave it closed |
| `--background` | Keep an embedded preview running after the command exits |
| `--foreground` | Keep the preview attached even when the shell is non-interactive |
| `--json` | Emit one versioned JSON result for managed start, status, stop, list, and kill-all operations |
| `--browser-gpu` / `--no-browser-gpu` | Hardware GPU for Studio thumbnails and frame capture, or deterministic SwiftShader (default: auto-detect) |
| `--proxy` / `--no-proxy` | Auto-transcode browser-hostile codecs (HEVC, ProRes, AV1) to a cached authoring proxy (default: on) |
| `--browser-path` | Open a specific browser. `--user-data-dir`, `--remote-debugging-port`, and `--browser-no-gpu` require it. |
To manage running servers: `--status` and `--stop` act on this project's
background preview, `--list` and `--kill-all` act on all of them, and
`--force-new` starts a second server for a project that already has one. Each
exits straight after.
Bare `preview` chooses the safest lifecycle for its caller: it stays in the
foreground in a human interactive terminal, while a non-interactive or agent
shell starts a managed background preview. Re-running the command for the same
project reuses the healthy preview. Every start or status result includes the
exact Studio project URL as well as the underlying server URL, so agents can
hand off the intended project without guessing from the port.
To read a running Studio from a script: `--selection` prints the selected
element and `--context` prints the agent-readable context, both with `--json`.
Narrow the context with `--context-fields` (`server`, `selection`, `lint`,
`capabilities`) and `--context-detail` (`compact` or `full`).
Your composition opens in HyperFrames Studio, and edits to `index.html` and its
sub-compositions refresh live. Preview and render share the same runtime.
The server picks one of three modes by itself: **embedded** (the default for
`npx` — Studio bundled in the CLI, no extra dependencies), **local studio**
(Vite with full HMR, when `@hyperframes/studio` is in your `node_modules`), or
**monorepo** (the studio dev server, when you run from the source repo).
`--background` works with the embedded server only.
<Note>
Preview plays in real time, so paint-heavy compositions can stutter on your
machine. Render seeks and captures one frame at a time, so the same work usually
means a longer render rather than dropped frames. Browser, font, and GPU
differences still move exact pixels — judge the rendered file. See
[Performance](/guides/performance).
</Note>
### `present` and `play`
`present` serves a slideshow and opens its presenter view. The presenter and
audience views stay in sync for as long as the command runs.
```bash
npx hyperframes present [dir]
npx hyperframes present [dir] --port 3004
```
`--port` defaults to 3004. `--open` / `--no-open` controls the browser, and
`--browser-path` opens a specific one — `--user-data-dir` and
`--remote-debugging-port` both require it.
`play` opens a composition in the lightweight Player instead of Studio — no
editor, just playback. Same flags, `--port` defaults to 3003, plus `--proxy` /
`--no-proxy`.
### `publish`
Upload the project and get back a stable `hyperframes.dev` URL.
```bash
npx hyperframes publish [dir]
npx hyperframes publish --yes
npx hyperframes publish --update <url-or-id>
npx hyperframes publish --space <space-id>
```
| Flag | Description |
| ------------------------ | ------------------------------------------------------------------ |
| `--yes, -y` | Skip the confirmation prompt |
| `--public` | Make the claimed project visible to anyone |
| `--update <url-or-id>` | Update an existing project in place. Requires sign-in. |
| `--space <space-id>` | Publish into a shared team space. Requires sign-in. |
| `--proxy` / `--no-proxy` | Bake H.264 proxies for browser-hostile codecs, or skip them |
`publish` zips the project, uploads it, and prints a URL that resolves to stored
content — so it keeps working after the CLI exits. No local server stays alive,
and no tunnel is opened.
You can publish while signed out. The printed URL then carries a claim token:
whoever opens it on `hyperframes.dev` can sign in, claim the project, and keep
editing in the web app.
Sign in with `npx hyperframes auth login` first when you want an owned, stable
link you can publish to again. `--update` and `--space` both need that
ownership.
### `open` and `catch-up`
`open` opens a project in the HyperFrames desktop app and adds it to Home.
```bash
npx hyperframes open # the project in the current directory
npx hyperframes open ./my-video
npx hyperframes open --json # for agents
```
| Flag | Description |
| -------- | ------------------------------------ |
| `[dir]` | Project directory (default: current) |
| `--json` | Machine-readable result |
When it runs under Claude Code, Codex, or Grok, the app's chat picks up that
conversation. When it cannot open the app, for example because the app is not
installed, `open` exits 1 and prints a download link. With `--json`, the result
names the `reason` and the `downloadUrl`.
`catch-up` is the other half of that hand-off. Run it when the person is back
from the desktop app, before you change anything: it lists what they asked and
what changed in the app since you last looked, and the files changed since
then.
```bash
npx hyperframes catch-up
npx hyperframes catch-up ./my-video
npx hyperframes catch-up --json
```
| Flag | Description |
| -------- | ------------------------------------ |
| `[dir]` | Project directory (default: current) |
| `--json` | Machine-readable result |
Each run marks what it showed as seen, so the next run lists only what is new.
A project that was never handed to the app from here has nothing to catch up
on.
## Check your work
### `lint`
Read the HTML and report common mistakes. No browser, so it is fast.
```bash
npx hyperframes lint [dir]
npx hyperframes lint [dir] --verbose # include info-level findings
npx hyperframes lint [dir] --json
```
```
◆ Linting my-project/index.html
✗ missing_gsap_script: Composition uses GSAP but no GSAP script is loaded.
⚠ video_missing_muted [clip-1]: <video id="clip-1"> has data-start but declares neither muted nor data-has-audio. If the file has sound, add data-has-audio="true" (the sound stays on this clip). If it is silent, add muted.
◇ 1 error(s), 1 warning(s)
```
Errors (`✗`) must be fixed before rendering — a missing adapter library, invalid
attributes. Warnings (`⚠`) are likely problems. Info (`ℹ`) notices are hidden
unless you pass `--verbose`, which keeps output clean for agents and CI.
`--json` adds `errorCount`, `warningCount`, `infoCount`, and a `findings` array.
The linter catches missing attributes, missing adapter libraries (GSAP, Lottie,
Three.js), and structural problems. [Troubleshooting](/guides/troubleshooting)
explains each rule.
### `check`
The browser gate. Everything the old `validate` → `inspect` → `snapshot` loop
did, in one command and one browser session.
```bash
npx hyperframes check [dir]
npx hyperframes check [dir] --json # {ok, browserSkipped, scope, lint, runtime, layout, motion, contrast, craft, hdr, snapshots}
npx hyperframes check [dir] --snapshots
npx hyperframes check [dir] --at 1.5,4,7.25
npx hyperframes check [dir] --strict # warnings fail too
```
`check` runs the linter first and skips the browser entirely on a lint error.
Then it loads the bundled composition once and sweeps a single seek grid,
running every audit at every sample: runtime console errors and failed requests,
layout defects (overflow, clipping, held overlaps, occlusion, coordinate-frame
drift), `*.motion.json` assertions, WCAG AA contrast, and craft warnings
(see [Craft warnings](#craft-warnings)).
When the browser never ran (lint errors, a linter crash, or a browser launch
failure), `browserSkipped` is `true` and the `layout`, `motion` and `contrast`
sections are empty, not clean.
Scoped checks add `scope` to the JSON report with the requested range and
components, hidden-finding count, and scope notes. Component filtering changes
the returned finding arrays only; section counts, `ok`, and the exit code still
cover every finding from the full check.
| Flag | Description |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--json` | One aggregated envelope. Every finding carries a selector, `data-*` identity, source file, bbox, and sample time. |
| `--snapshots` | Save the five audited frames under `.hyperframes/artifacts/snapshots/`, plus a `finding-NN-<code>.png` crop per finding |
| `--samples` | Midpoint samples across the duration (default 9) |
| `--at` | Explicit timestamps in seconds, comma-separated |
| `--at-transitions` | Also sample every tween start and end, to catch transient overlaps at transition seams |
| `--max-transition-samples` | Cap the transition-derived samples. When it truncates, the omitted count is reported. Default: unlimited. |
| `--range <start,end>` | Sample only this interval, in global seconds. Lint stays project-wide; whole-timeline motion, `sweep_static` and craft warnings are skipped. |
| `--components <selectors>` | Report only findings that involve these elements or their descendants. Counts, `ok` and the exit code still cover all. |
| `--max-issues` | Findings to print or return after static collapse (default 80) |
| `--collapse-static` / `--no-collapse-static` | Fold a repeated static finding into one row (default: on) |
| `--tolerance` | Allowed overflow in px before reporting (default 2) |
| `--timeout` | Render-ready budget in ms; also raises page navigation above its 10s floor (default 3000) |
| `--no-contrast` | Skip the WCAG pass while iterating |
| `--strict` | Exit non-zero on warnings too (default: errors only) |
| `--caption-zone "<x0=..;y0=..;x1=..;y1=..>"` | Opt-in band gate. Flags a text element's DOM box that overlaps the fractional band. Optional `severity` and `seek`. |
| `--frame-check` | Opt-in out-of-frame detection for `img`, `svg`, `video`, and `canvas` |
| `--layout` | Layout knobs, currently `proseCoverageFloor=0.05` (0–1, default 0.15) |
| `--browser-gpu` / `--no-browser-gpu` | Hardware GPU capture, or deterministic SwiftShader (default: auto-detect) |
| `--proxy` / `--no-proxy` | Auto-transcode browser-hostile codecs before checking (default: on) |
`--caption-zone` and `--frame-check` refuse a ranged check when none of their
configured seek samples falls inside `--range`; a requested gate never silently
passes without running.
Text under a `<video>` is judged by the frame the video shows at that sample.
An opaque video covers its whole box, as an opaque image does. A video with
transparency, such as a `remove-background` cutout, covers only where its
alpha is: a word partly behind the subject is an info finding whose
`coveredFraction` is the most covered word's share, and a word 80% hidden or two
neighbouring words each half hidden are an error. A CSS background on the video
still covers its whole box, and a mirrored video (`scaleX(-1)`) is read on the
side it is painted. When a video's frame cannot be read, the audit treats the
video as opaque and adds a `video_alpha_unread` info finding saying why: no frame
decoded yet, the seek still landing, a cross-origin source, no frame size, a
rotated, skewed or 3D-transformed video, or a frame that reads back fully
transparent. A fully transparent frame is treated as unread on purpose, since a
failed draw looks the same; mark text that sits under a cutout before its subject
enters with `data-layout-allow-occlusion`.
Contrast failures are errors, and each one reports the sampled foreground and
background colours, the measured ratio against the required one, and a
compliant colour you could use instead.
Severity is persistence-aware: a finding at a single sample demotes to info, a
finding that persists gates the exit code, and a composition of 3s or more
fails with `sweep_static` when its frame never changes and a GSAP timeline or
tween, or a CSS or Web animation, on the page held the same time without ever
finishing, so the seek never drove it.
Any other frame that never changes, such as a still title card, is a
`sweep_static` warning ("Nothing on screen moved under seek"), and so is an
audio-only advance; `--strict` fails the run on either. A composition that is
meant to be still can declare `data-no-timeline` to skip the guard.
{/* VISUAL: a `check --snapshots` overview frame beside one finding crop, with the labelled finding box visible on both */}
#### Craft warnings
The `craft` section reports what a viewer would notice over time and a single
frame cannot show. Every craft finding is a warning, even under `--strict`: a
film may break one on purpose. Its message names the fix and the skill reference to read.
They are measured on an 8 fps sweep of the whole film, with each short line's
edges re-measured to about 0.01 s, and skipped for a `--range` check.
| Code | Warns when |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `line_unread` | A reading-size line (30 px or taller at 1080) is on screen for less than its floor: 0.4 s for one or two words, otherwise three quarters of 0.5 s + 0.3 s a word. The film's last line needs 2 s. |
| `dead_stretch` | Nothing on screen changes for more than 3 s, by the same classifier `keepsMoving` uses. |
| `text_below_floor` | Text under 2.6% of the frame's short side (28 px on 1080) stays on screen 0.5 s or more. One finding per file lists every such element. |
| `first_frame_empty` | Frame 0 paints nothing but the background: no text, image, video, canvas or SVG. The first frame is the thumbnail on social players. |
| `film_silent` | A film longer than 15 s has no unmuted `<audio>` and no `<video>` with sound. |
Captions-track text (`data-track-kind="captions"`) and `data-layout-ignore`
text are exempt from the text rules. `dead_stretch` never counts the film's
last 3 s (a held end card) or time when an element marked `data-hold` is on
screen, and it stays quiet when `sweep_static` already reports the sweep or a
whole-composition `keepsMoving` assertion sets its own limit.
#### Mark intentional layout choices
When the audit is wrong because the layout is deliberate, say so in the HTML and
re-run. Put `data-layout-allow-overflow` on a planned off-canvas entrance,
`data-layout-allow-overlap` on text you meant to stack, `data-layout-allow-occlusion`
on text you meant to hide behind a prop, and `data-layout-ignore` on decoration
that should not be audited at all. Overflow, occlusion, and ignore markers are
inherited, so an ancestor works. The overlap marker is intentionally local: put it
on the specific text block participating in the layering, never on a scene/root
wrapper, so unrelated descendant collisions remain auditable.
For deliberate lower-third copy under `--caption-zone`, use
`data-layout-allow-caption-zone`. It silences `caption_zone_collision` and
nothing else — overflow, overlap, occlusion, and contrast still apply. Put it on
the narrowest wrapper that owns the band copy.
#### Verify motion, not just layout
Layout sampling cannot catch a render-≠-preview bug: an entrance the seek lands
past, a broken stagger order, an element that drifts off-frame mid-tween, a shot
that freezes. Motion assertions can. Drop a `*.motion.json` sidecar next to the
composition and `check` evaluates it automatically — no flag, no changes to your
HTML. Without a sidecar, nothing changes.
```json
{
"duration": 6,
"assertions": [
{ "kind": "appearsBy", "selector": "#headline", "bySec": 0.5 },
{ "kind": "before", "a": "#headline", "b": "#cta" },
{ "kind": "staysInFrame", "selector": ".card" },
{ "kind": "keepsMoving", "withinSelector": ".scene" }
]
}
```
| Assertion | Catches |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `appearsBy(selector, bySec)` | A reveal the seek lands past — the element must reach opacity ≥ 0.5 by `bySec` (`motion_appears_late`) |
| `before(a, b)` | Broken stagger order — `a` must first appear strictly before `b` (`motion_out_of_order`) |
| `staysInFrame(selector)` | Off-frame drift — once visible, the box never leaves the canvas (`motion_off_frame`) |
| `keepsMoving(withinSelector?)` | A frozen shot — no fully static window longer than `maxStaticSec`, default 2s (`motion_frozen`); the film's last 3 s never count |
`keepsMoving` uses the same motion classifier as the frozen-sweep guard: box
geometry, opacity, text and generated content, form-control state, painted CSS
counters, clip-path, variable-font axes, filters, colors, backgrounds, drawn
borders and shadows, the pixels of visible canvas/video/img elements, and video
playback time all count as motion — so a playing background video keeps a scope
live on its own, even a color-graded one whose picture is drawn into a canvas.
Audio playback time never counts here: it shows the timeline ran, but it is not
a moving picture. The frozen-sweep guard reports an audio-only advance as a
warning rather than a failure. Elements under
`data-layout-ignore` inside the scope never count; the opt-out does not apply to
the scope element itself, since naming it in an assertion outranks it. Content
the browser does not paint (`display: none` subtrees, `visibility: hidden`
boxes, skipped `content-visibility` contents) never counts as motion either,
except a video's playback time, since the runtime may draw that video's
picture elsewhere.
`duration`, `keepsMoving.withinSelector`, and `keepsMoving.maxStaticSec` are
optional. Findings use the same shape and envelope as layout findings and are
errors by default, so a failed assertion fails the run. A selector that matches
nothing reports `motion_selector_missing` rather than quietly passing.
### `snapshot`
Capture specific frames as PNGs, without waiting for a full render.
```bash
npx hyperframes snapshot my-project --at 2.9,10.4,18.7
npx hyperframes snapshot my-project --frames 10
npx hyperframes snapshot my-project --zoom '#headline'
npx hyperframes snapshot my-project --at 1.5,4.3 --against ref.mp4
npx hyperframes snapshot my-project --review --json
```
```
◆ Capturing 3 frames at [2.9s, 10.4s, 18.7s] from my-project
◇ 3 snapshots saved to <project>/.hyperframes/artifacts/snapshots/<id>
.hyperframes/artifacts/snapshots/<id>/frame-00-at-2.9s.png
.hyperframes/artifacts/snapshots/<id>/frame-01-at-10.4s.png
.hyperframes/artifacts/snapshots/<id>/frame-02-at-18.7s.png
```
| Flag | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--at` | Timestamps in seconds, comma-separated (`3.0,10.5,18.0`) |
| `--frames` | Evenly spaced frames instead (default 5) |
| `--range <start,end>` | Spread `--frames` across this interval only, in root-timeline seconds, with no end-of-timeline frame added |
| `--composition <id>` | Spread `--frames` across the visible interval of the element with this `data-composition-id`. Use one of `--at`, `--range` or `--composition`. |
| `--output, -o` | Where the PNGs go (default: a new `<project>/.hyperframes/artifacts/snapshots/<id>` per run) |
| `--end` / `--no-end` | Always add a readable end-of-timeline frame (default: on). `--no-end` captures only your `--at` times. |
| `--keep` | Add to `--output` instead of clearing it, naming each still for its time: `at-0s.png`, `at-1.5s.png`, `at-12.25s.png` (no trailing zeros). Snapshotting one moment again replaces only that still. No contact sheet. |
| `--zoom` | Crop to a CSS selector or an exact `x,y,w,h` region, using a raised device scale factor. Layout is untouched — never CSS zoom or a resized viewport. A selector that matches nothing is an error. |
| `--against` | A reference video, such as footage you are rebuilding. For every captured time also saves its frame-exact frame (`ref-XX-…png`) and a labelled render / reference pair (`pair-XX-…jpg`). |
| `--zoom-scale` | Pixel density for `--zoom` crops (default 3) |
| `--angle` | Orthogonal 3D camera for depth and occlusion checks: `front`, `iso`, `top`, `side`, or `yaw,pitch` in degrees. Tilts the whole stage, so you get real pixels. |
| `--review` | Capture the frames that show the film over time instead of evenly spaced ones: `review-beats.jpg` (each scene at its start + 0.3 s and at its middle, and each timed `data-beat="name"` element at its start + 0.3 s), `review-seam-NN.jpg` (−0.2 to +0.2 s around every cut) and `review-phone.jpg` (the beat frames 360 px wide). Scenes are the top-level timed clips and sub-composition hosts; `--composition` scopes to one. |
| `--json` | Print one envelope: `frames` with path, time and (under `--review`) role and label, the contact sheets, and under `--review` the scenes, beats and seams behind them. Progress goes to stderr. |
| `--describe` | Gemini vision analysis of each frame. Runs by default when `GEMINI_API_KEY` is set. Pass a question to override the prompt, or `--describe false` to opt out. |
| `--timeout` | Ms to wait for the runtime (default 5000) |
| `--browser-gpu`, `--proxy` | Same meaning as on [`check`](#check) |
Each snapshot is a 1920×1080 PNG taken by bundling the project, serving it,
launching headless Chrome, and seeking. Useful for visual verification while
an agent builds, for example a [product or website video](/guides/product-launch-video).
### `keyframes`
Show the GSAP, CSS, and Anime.js keyframes actually detected in a composition —
or render an onion-skin diagnostic of one element's motion.
```bash
npx hyperframes keyframes [dir]
npx hyperframes keyframes [dir] --selector "#card" --shot card-motion.png
```
| Flag | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--selector` | Only keyframes matching this CSS selector |
| `--runtime` | Filter hint: `gsap`, `css`, `anime`, or `all` |
| `--json` | Machine-readable results |
| `--shot` | Write an onion-skin PNG of the real element sampled over the timeline. Pair with `--selector` to focus one element. |
| `--samples` | Onion samples at equal time steps (default 9) |
| `--layout` | `path` — ghosts at real positions plus a path (default) — or `strip`, for in-place or overlapping motion. `strip` is a real per-time pixel filmstrip only when `--selector` targets an SVG element; any other selector (e.g. a DOM/sub-composition host) gets one live frame plus vector position markers instead |
| `--from`, `--to` | Sample only this time range, in seconds |
| `--angle` | Orbit camera: `front`, `iso`, `top`, `side`, `rear-iso`, or `yaw,pitch` in degrees |
| `--fit` / `--no-fit` | Zoom the motion to fill the diagnostic frame (default: on) |
| `--ghost` | Composite the real canvas frames as translucent ghosts, older fainter, instead of bounding-box markers. Needs a `<canvas>`. |
Use `--ghost` for motion that happens *inside* a canvas, where the marker onion
has nothing to draw.
### `compare` and `grade-compare`
`compare` renders two or more independent variants into one labelled PNG.
```bash
npx hyperframes compare ./variant-a ./variant-b --labels "A,B"
```
| Flag | Description |
| ----------- | -------------------------------------------------- |
| `--at` | Timeline time in seconds to seek before capture |
| `--labels` | Comma-separated labels, one per input path |
| `--out` | Output path (default `./compare.png`) |
| `--cols` | Grid columns (default: a sqrt heuristic, max 4) |
| `--timeout` | Render-ready timeout per variant (default 5000 ms) |
| `--json` | Machine-readable results |
`grade-compare` does the same for colour: candidate grades or LUTs applied to
one reference frame.
```bash
npx hyperframes grade-compare --for frame.png --luts warm.cube,cool.cube
```
| Flag | Description |
| ------------------------------ | -------------------------------------------------------- |
| `--for` | Required. An image, or a video sampled at zero seconds. |
| `--grades` | JSON array of `{ label, grading }` candidates |
| `--luts` | Comma-separated `.cube` LUT files |
| `--project` | Base directory for relative paths |
| `--out` | Output PNG (default `<project>/grade-compare.png`) |
| `--baseline` / `--no-baseline` | Include the ungraded frame as an `original` cell (on) |
| `--timeout` | Render-ready timeout (default 5000 ms) |
| `--json` | Machine-readable results |
### Deprecated: `validate`, `inspect`, and `layout`
All three still run, and all three print a deprecation line on stderr and set
`_meta.deprecated: true` in `--json` output. `validate` was the runtime-only
browser check; `inspect` (and its alias `layout`) was the layout sweep and
motion-sidecar pass. [`check`](#check) does everything they did, in one browser
session, and it is where new work should go. Their flags are unchanged — run
`npx hyperframes inspect --help` if you are maintaining automation that still
calls them.
## Edit from the command line
### `timeline`
Print the project's tracks and clips, or edit one clip.
```bash
npx hyperframes timeline [dir]
npx hyperframes timeline --json
```
```
timeline 10s
graphics (3)
|████████████████████████████████████████| #title title 0-10s
|████████████ | #intro intro 0-3s
| ████████████ | #outro outro 5-8s
```
| Flag | Description |
| -------- | ------------------------------------------------------------- |
| `[dir]` | Project directory (default: current) |
| `--json` | Every track and clip with its start, duration, file and track |
The edit commands take a clip ref, such as `#outro`, and write the change to the
file that holds the clip:
```bash
npx hyperframes timeline move '#outro' +1 --plan # show the result and diff, write nothing
npx hyperframes timeline move '#outro' after:#intro
npx hyperframes timeline trim '#intro' --duration 2
npx hyperframes timeline split '#outro' 6.5
npx hyperframes timeline set '#music' volume=0.5
npx hyperframes timeline duplicate '#intro' --at 3
npx hyperframes timeline delete '#outro' --json
npx hyperframes timeline delete '#outro' --start 6 --end 7 # cut one second out
```
| Command | What it does |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `move <ref> <time>` | Start the clip at `<time>`, keeping its length |
| `trim <ref>` | Change the clip's `--start`, `--end`, or `--duration` (at least one) |
| `split <ref> <time>` | Cut the clip in two at `<time>` |
| `delete <ref>` | Remove the clip, or only its `--start` to `--end` range, keeping the parts before and after |
| `set <ref> <field>=<value>` | Set `volume`, `rate` (playback rate) or `track` (a whole number) |
| `duplicate <ref>` | Copy the clip to `--at <time>` (default: right after the clip) |
| `apply <file>` | Apply a JSON array of edits, such as `[{"verb": "move", "ref": "#intro", "time": "+1"}]`, all or nothing. Pass `-` to read it from stdin. |
| `undo <receipt>` | Restore the files an edit changed, from its receipt (the JSON or its file) |
| `ids` | Stamp stable ids on the timeline's clips |
A time is seconds (`4.5`), an offset from the clip's start (`+1`, `-0.5`),
frames (`30f`), `end`, or an anchor on another clip: `after:#intro`,
`before:#intro`, `start-of:#intro` or `end-of:#intro`. A flag an edit command does not
use is refused before anything is written.
| Flag | Applies to | Description |
| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
| `--plan` | `move`, `trim`, `split`, `delete`, `set`, `duplicate`, `apply` | Print the result and the diff without writing |
| `--overwrite` | `move`, `trim` | Allow the clip to overlap a neighbour on its track |
| `--snap` | `move`, `trim`, `split`, `delete`, `duplicate` | Round times to whole frames. Needs `data-fps` on the project. |
| `--at` | `duplicate` | Where the copy starts |
| `--dir` | all edit commands | Project directory (default: current) |
| `--json` | all edit commands | Machine-readable result, with the receipt `undo` takes |
A refused edit, such as a move that would overlap a neighbour, writes nothing,
exits 2 and says how to fix it.
### `history`
List, undo and restore the project's recorded changes. Each change is an entry
with who made it, a label and the files it touched.
```bash
npx hyperframes history # newest 20 entries
npx hyperframes history --since mine --who claude # what changed since your last entry
npx hyperframes history begin --who claude --label "Bigger title"
npx hyperframes history end
npx hyperframes history undo --who claude # undo your newest turn
```
| Flag | Description |
| --------- | ------------------------------------------------- |
| `--dir` | Project directory (default: current) |
| `--json` | Machine-readable result |
| `--since` | Only entries after an entry id, a time, or `mine` |
| `--who` | Your name, for `--since mine` |
| `--limit` | Newest entries to show (default 20) |
| Command | What it does |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `show <ref> [--diff]` | One entry's files, before and after. `--diff` prints a text diff (needs `git`). |
| `undo [ref]` | Undo an entry, or with `--who <name>` and no ref, that name's newest turn still in effect |
| `restore <ref> [--who]` | Make the files what they were right after an entry, a time, or `start` |
| `peek <ref> [path]` | List the files at an entry, a time, or `start` without changing anything; with a path, print that file |
| `pin <ref> [--off]` | Keep an entry, and what it needs, when old history is trimmed. `--off` unpins it. |
| `begin --who --label` | Start a turn: your writes until `end` become one entry under your name. Another agent's open turn is ended first, or with `--exclusive` the command refuses instead. |
| `end` | End your turn and print its entry. `--who <name>` refuses unless the open turn is that name's; `--if-open` succeeds when no turn is open. |
Every command also takes `--dir` and `--json`. A ref is an entry id or a unique
prefix of one; a time is a local date or date-time such as `2026-09-24T14:30`.
Without a running preview, `history` keeps its data under `~/.cache/hyperframes/history`, or under
`HYPERFRAMES_HISTORY_ROOT` when that is set, which keeps an agent run or a test apart from your own
history. That path is resolved to an absolute one, and every agent on a project has to share it: the
lock lives there, while the turn marker lives in the project. A running preview server records to
its own location.
When a file in the entry has changed since, `undo` writes nothing, exits 2 and
lists the newer entries. Run it again with `--just-this` to put back only that
entry's files over the newer edits, or `--back-to-before` to go back to before
it, undoing the newer entries too.
## Render to a file
### `render`
Render a composition to MP4, WebM, MOV, GIF, or an RGBA PNG sequence.
```bash
# Fast iteration
npx hyperframes render --output output.mp4
# Deterministic output
npx hyperframes render --docker --output output.mp4
# Transparent, for overlays and lower thirds
npx hyperframes render --format webm --output overlay.webm
# HLS VOD stream (output is a directory of playlists and .ts segments)
npx hyperframes render --format hls --output stream
npx hyperframes render --output output.mp4 --fps 60 --quality high
npx hyperframes render --gpu --output gpu.mp4
```
The flags that come up most:
| Flag | Default | Description |
| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--output, -o` | `renders/<name>.mp4` | Output file path |
| `--composition, -c` | `index.html` | Render a different composition file. Sub-compositions using `<template>` wrappers must be referenced from `index.html` via `data-composition-src`. |
| `--format` | `mp4` | `mp4`, `webm`, `mov`, `gif`, `png-sequence`, or `hls`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory; `hls` writes a VOD playlist directory. |
| `--fps, -f` | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97 |
| `--quality, -q` | `looks` | `draft`, `looks` (CRF 16, default), `delivery` (= `high`), `standard`, or `high`. MOV always uses the fixed alpha-preserving ProRes 4444 profile. |
| `--resolution` | the composition's size | Supersample to a preset via Chrome's `deviceScaleFactor`. Aspect ratio must match and the scale must be a whole multiple. Not with `--hdr`. See [4K rendering](/guides/4k-rendering). |
| `--docker` | off | Render inside Docker for [deterministic output](/concepts/determinism) |
| `--variables` | — | JSON object merged over the composition's `data-composition-variables` defaults |
| `--variables-file` | — | Read those overrides from a JSON file instead |
| `--batch` | — | Render one output per variables row, from a JSON array or a `{ "rows": [...] }` object |
| `--json` | off | With `--batch`, print one final JSON result document instead of progress |
Quality and file size:
| Flag | Default | Description |
| ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
| `--crf` | from `--quality`| Override MP4/WebM encoder CRF, 0–51. Lower is better quality. Not with `--video-bitrate`; rejected for MOV. |
| `--video-bitrate` | from `--quality`| Target MP4/WebM bitrate, e.g. `10M` or `5000k`. Not with `--crf`; rejected for MOV. |
| `--vp9-cpu-used` | encoder default | libvpx-vp9 speed/quality trade-off for WebM, -8 to 8. Env: `PRODUCER_VP9_CPU_USED`. |
| `--gif-loop` | `0` | GIF loop count, `0` for forever. Range 0–65535, `--format gif` only. |
| `--hls-segment-seconds`| `4` | HLS target segment length in whole seconds, 1–60. `--format hls` only. Also fixes the encoder GOP so every segment starts on a keyframe. |
| `--video-frame-format` | `auto` | How source video frames are extracted: `auto`, `jpg`, `png`. Use `png` for UI recordings, screen captures, and other colour-sensitive footage. |
| `--hdr` | off | Force HDR even with no HDR sources. MP4 only. See [HDR rendering](/guides/hdr). |
| `--sdr` | off | Force SDR even when HDR sources are detected |
How it uses the machine, and when it gives up:
| Flag | Default | Description |
| -------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `--workers, -w` | auto | 1–24 workers. Each is a separate Chrome, roughly 256 MB. Auto weighs cores, memory, frame count, and cost. |
| `--low-memory-mode` / `--no-low-memory-mode` | auto at 8 GB RAM or less | Safe profile: one worker, screenshot capture, no calibration. See the note below. |
| `--gpu` | off | Hardware FFmpeg encoding (NVENC, VideoToolbox, AMF, VAAPI, QSV) |
| `--browser-gpu` / `--no-browser-gpu` | auto locally, off in Docker | Host GPU for Chrome and WebGL capture, or software rendering. Auto probes WebGL once and falls back. |
| `--page-side-compositing` / `--no-page-side-compositing` | on | Page-side WebGL for SDR shader transitions in mp4, hls and gif, ~6× faster. webm and mov use the layered path; gif always uses page-side WebGL, even with `--no-page-side-compositing`. |
| `--experimental-fast-capture` | on where it can engage | Chrome's draw-element capture, ~2× faster; falls back to screenshots on its own. Env: `PRODUCER_EXPERIMENTAL_FAST_CAPTURE`. |
| `--frames-cache-dir` | `<tmpdir>/hyperframes-extract-cache-<uid>` | Where extracted source frames cache. `off`, `none`, `false`, or `0` disables it. `doctor` reports the live value. |
| `--max-concurrent-renders` | `2` | Concurrent jobs on the Producer server, 1–10 |
| `--best-effort` / `--no-best-effort` | on | Finish with capture-readiness warnings, or fail when media is missing or unready |
| `--strict` / `--strict-all` | off | Fail on lint errors, or on errors and warnings |
| `--strict-variables` | off | Fail rather than warn on an undeclared or mistyped variable key |
| `--batch-concurrency` / `--batch-fail-fast` | `1` / off | Batch rows at once, and whether the first failure stops the rest |
| `--debug` | off | Keep intermediates and write diagnostics under the Producer `.debug` directory |
| `--quiet` | off | Less output |
| `--skill` | — | Record which authoring workflow started this render, in anonymous telemetry |
Low-memory detection reads **host** RAM, not cgroup or container limits, so
containerised callers — including `--docker` — should set
`PRODUCER_LOW_MEMORY_MODE` explicitly.
#### When a render times out
Three separate budgets can expire, and the error message tells you which. All
three have environment fallbacks that take **milliseconds**, even where the flag
does not.
- **The page never loaded.** `--browser-timeout` is the Puppeteer navigation
budget for the entry HTML, and the flag takes **seconds** (default 60, range
0.001–86400). Raise it when a composition with many videos, fonts, or asset
requests cannot reach `domcontentloaded` in time. Env:
`PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS`.
- **The player never became ready.** After navigation, `window.__hf` readiness
has its own budget: `--player-ready-timeout`, in ms, default 45000. Env:
`PRODUCER_PLAYER_READY_TIMEOUT_MS`.
- **A single CDP call hung.** `--protocol-timeout` is the per-call budget for
seek, paint, and screenshot round-trips, in ms, default 300000. This is the
one behind `Runtime.callFunctionOn timed out` and `Target closed`. Raise it on
hosts with 8 GB RAM or less and on asset-heavy compositions. The default
auto-scales with output pixel area, capped at 30 minutes; an explicit value
becomes a floor and disables that scaling below it. Env:
`PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS`.
#### Long renders and the capture path
Captured frames either stream into FFmpeg as they arrive or land on disk first
as raw RGBA, which costs `frames × width × height × 4` bytes — about 25 GB per
minute at 1080p30. Streaming is the default for single-worker mp4/mov renders
**at any duration**: the old four-minute ceiling guarded an FFmpeg timeout that
is now per-frame rather than whole-render, so it no longer applies.
Multi-worker mp4/mov renders also stream where capture runs BeginFrame — Linux
on the bundled `chrome-headless-shell`, at DPR 1, with no forced screenshot. On
macOS and Windows, multi-worker capture is screenshot-based and still writes
frames to disk unless you opt in with `HF_CAPTURE_PARALLEL_STREAM=true`. That
path now retries a stalled worker pool or a mid-stream encoder exit on a fresh
screenshot session, dropping an interleaved render to one worker, instead of
failing the render; it stays opt-in until its error rate matches the disk
path's.
Renders still land on the disk path when the output is `png-sequence` or `gif`,
when HDR or shader-transition layering is in play, and when streaming is
switched off. If a render fails preflight asking for tens of GB of temporary
frame storage, the message names the condition that applied and what takes that
render off disk. `--workers 1` is offered only for a multi-worker render that one
worker would stream; it is slower, so it is a fix for that render, not a default.
For `png-sequence` or `gif` output, or with streaming switched off, one worker
stores frames too: free disk, render to mp4, or undo the switch.
| Environment variable | Default | Effect |
| ------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------- |
| `PRODUCER_ENABLE_STREAMING_ENCODE` | `true` | `false` sends every render to the disk path |
| `HF_CAPTURE_PARALLEL_STREAM` | on for BeginFrame | `true` also streams multi-worker screenshot capture; `false` disables the router entirely |
| `PRODUCER_STREAMING_ENCODE_DURATION_CAP_ENABLED` | `false` | `true` restores the duration ceiling below |
| `PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS` | `240` | The ceiling's value; inert unless the flag above is `true`, including the `0` ("never") setting |
#### Segmented capture
For long renders, capture can be split into fixed-size segments, each encoded
by its own ffmpeg and stream-copied together at the end. It costs some speed
against a single-encoder streaming render, and buys three things:
- Scratch is encoded video rather than raw frames, at any duration.
- The browser restarts at segment boundaries, so a session never accumulates
the tens of thousands of frames where Chrome starts losing its target.
- A crash costs one segment. `--resume` re-runs the render and reuses the
segments a previous attempt finished, after re-validating each one; a
resumed render is byte-identical to an uninterrupted one.
Segments live in `renders/.hf-segments/<hash>/`, where the hash covers
everything that determines segment bytes, so changing the composition, fps,
resolution, quality or segment size starts a fresh set instead of splicing
mismatched encodes. The directory is deleted after a successful render unless
`--keep-segments`, and deliberately kept after a failure, because that is what
`--resume` reads next time.
mp4 and mov only; png-sequence, gif, webm, HDR and shader-transition renders
keep their existing routes.
| Environment variable | Default | Effect |
| ------------------------------ | ---------- | ------------------------------------------------------------------------------------------ |
| `HF_SEGMENTED_CAPTURE` | unset | `true` segments any eligible render; `false` is the kill switch |
| `HF_SEGMENTED_MIN_SECONDS` | off | Segment renders at least this long. Unset means duration never routes on its own |
| `HF_SEGMENT_FRAMES` | `3000` | Frames per segment (~100 s at 30 fps); minimum 30 |
| `HF_SEGMENT_BROWSER_RECYCLE` | `3` | Restart the browser every N segments; `0` keeps one session for the whole render |
#### Render the same composition with different content
Declare the variables on the composition root, read them inside it, then
override them at render time.
```html index.html
<html
data-composition-variables='[
{"id":"title","label":"Title","type":"string","default":"Hello"},
{"id":"theme","label":"Theme","type":"enum","options":[
{"value":"light","label":"Light"},
{"value":"dark","label":"Dark"}
],"default":"light"}
]'
>
<script>
const vars = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = vars.title;
document.body.dataset.theme = vars.theme;
</script>
</html>
```
```bash
# Declared defaults — preview uses these too
npx hyperframes render --output default.mp4
# Override; missing keys fall through to the defaults
npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4
npx hyperframes render --variables-file ./vars.json --output out.mp4
```
`getVariables()` returns the declared defaults merged with any overrides, so the
same composition runs unchanged in preview and in production. For many outputs
at once, `--batch` renders one file per row of a JSON array. See
[Variables](/concepts/variables) for the whole model.
#### Transparent WebM for overlays
`--format webm` produces VP9 with an alpha channel — the standard format for
overlayable video.
```bash
npx hyperframes render --format webm --output captions.webm
ffmpeg -c:v libvpx-vp9 -i captions.webm -i background.mp4 \
-filter_complex "[1:v][0:v]overlay=0:0" -y composited.mp4
```
<Tip>
For transparency to survive, your composition's root elements need
`background: transparent`. WebM renders capture PNG frames rather than JPEG to
keep the alpha channel.
</Tip>
[Rendering](/guides/rendering) covers every mode in context.
### `benchmark`
Find good render settings for this machine.
```bash
npx hyperframes benchmark [dir]
```
It runs several configurations — varying fps, quality, and worker count — and
compares time and file size. `--runs` sets runs per configuration (1–20,
default 3); `--json` prints the results as JSON.
## Keep the environment healthy
### `doctor`
Check the machine for everything a render needs.
```bash
npx hyperframes doctor
npx hyperframes doctor --json
```
```
hyperframes doctor
✓ Version 0.1.4 (latest)
✓ Node.js v22.x (linux x64)
✓ FFmpeg 7.x
✓ FFprobe 7.x
✓ Chrome (system or cached)
✓ Docker 24.x
✓ Docker running Running
◇ All checks passed
```
It reports CLI version, Node.js, CPU, memory, disk, the extracted-frame cache,
the archive extractor, `/dev/shm` on Linux, environment, whisper-cpp, local TTS
and BGM models, FFmpeg, FFprobe, Chrome, and Docker.
The **frames cache** row is worth knowing about: it prints the effective cache
directory, its free space, and whether the location came from
`HYPERFRAMES_EXTRACT_CACHE_DIR` or the default. Under 2 GB free it fails, since
a long render can fill the drive from there. Move it with that variable or
[`render --frames-cache-dir`](#render).
**Gating CI on it.** `doctor --json` always exits 0 when it ran successfully —
the command worked, whatever it found. Environment health lives in the payload's
`ok` field, so a new CLI release (which flips the version row to not-ok) can
never break your pipeline. Gate on the payload:
```bash
hyperframes doctor --json | jq -e '.ok' > /dev/null || handle_failure
```
In JSON mode, paths inside `detail` and `hint` are redacted — your home
directory becomes the literal `$HOME`, so output is safe to paste into a bug
report or an agent context.
### `clean`
Find and remove what HyperFrames left on disk.
```bash
npx hyperframes clean --dry-run # list it, remove nothing
npx hyperframes clean
npx hyperframes clean --snapshots # also remove snapshots and saved check reports
npx hyperframes clean --json
```
It looks in the current project (not its subfolders) and every project the Studio history knows, and removes:
- frames and staging folders left by renders that were killed or crashed (a render that is still running keeps its own);
- work folders of `--debug` renders nothing has written to for six hours;
- the history of projects that no longer exist;
- extracted video frames and video proxies nobody has used for an hour (they rebuild on demand).
`snapshots/` folders and the saved snapshots and check reports under `.hyperframes/artifacts/` are listed as also reclaimable and removed only with `--snapshots`. Rendered outputs, source
files, the browser download and models are never touched.
### `info` and `compositions`
`npx hyperframes info [dir]` prints project metadata: name, resolution,
duration, element counts by type, track count, and total size.
`npx hyperframes compositions` lists every composition in the project with its
ID, duration, resolution, and element count. Both take `--json`.
### `upgrade`
```bash
npx hyperframes upgrade
npx hyperframes upgrade --check # check and exit, no prompt
npx hyperframes upgrade --check --json # for agents
npx hyperframes upgrade --yes # upgrade a global install without prompting
npx hyperframes upgrade --project # bump pinned CLI scripts in package.json
```
`upgrade` compares your installed version against npm. `--check` exits without
prompting, `--yes, -y` upgrades a detected global install (otherwise it prints
the right `npx` command), and `--project [dir]` rewrites
`hyperframes@<version>` script pins in a project's `package.json`.
`--check --json` returns:
```json
{
"current": "0.7.84",
"latest": "0.7.85",
"updateAvailable": true,
"_meta": { "version": "0.7.84", "latestVersion": "0.7.85", "updateAvailable": true }
}
```
### `browser`
Manage the Chrome that rendering uses.
```bash
npx hyperframes browser ensure # find it, or download it
npx hyperframes browser ensure --force # discard any cached download and re-fetch
npx hyperframes browser path # print the executable path
npx hyperframes browser clear # remove the cached download
```
`path` prints only the path, so it composes:
`$(npx hyperframes browser path)`. Use `--force` when a download was
interrupted and left a partial file behind.
### `docs`
Read documentation in the terminal.
```bash
npx hyperframes docs [topic]
```
Topics: `data-attributes`, `examples`, `rendering`, `gsap`, `troubleshooting`,
`compositions`. Run it bare to list them.
### `feedback`
Send feedback about how it went. It is anonymous unless the app that launched
the CLI attaches your email (below).
```bash
npx hyperframes feedback --rating 10
npx hyperframes feedback --rating 7 --comment "render succeeded but GSAP timeline didn't animate"
npx hyperframes feedback --rating 3 --comment "GSAP timeline froze on seek" --file-issue
npx hyperframes feedback --comment "MISSING FEATURE: trim a clip from the timeline | WORKAROUND: none"
```
`--rating` is 0–10. `--comment` adds free text; a `--comment` with no `--rating` is a report with no score (a missing feature, or friction in the app that launched the CLI), kept out of the rating metric. `--source person`
or `--source agent` says who wrote a rating or comment report (a `--search-miss` report
carries neither), so the team can tell a person's feedback from an agent's. `--file-issue`
also opens a GitHub issue, `--dir` picks the project published as its repro
(default: current directory), and `--yes, -y` skips the consent prompt for
scripts.
With `--file-issue`, the CLI publishes a minimal repro to a public URL — with
your consent — and opens a pre-filled `bug` issue draft that you review and
submit yourself. No token, no backend. See
[Share feedback](/guides/feedback#report-a-reproducible-bug).
Agents can call this after a render;
[About feedback data](/guides/feedback#about-feedback-data) covers what the
surface includes. An app that launches the CLI can attach its signed-in
person's email with the `HYPERFRAMES_FEEDBACK_EMAIL` environment variable. It
is never a flag and never read from a project `.env`, and it goes only into
the feedback report, not telemetry. It is not verified: treat it as a way to
reply, not as proof of who sent the report. With
telemetry disabled it prints
`Telemetry is disabled. Feedback not sent.` and exits cleanly.
### `telemetry`
```bash
npx hyperframes telemetry enable
npx hyperframes telemetry disable
npx hyperframes telemetry status
```
Telemetry collects command names, render performance, render checkpoint and
error names, aggregate browser diagnostic counts, browser initialization
duration and tween count, aggregate video-extraction workload counts (extracted
frames, VFR preflights), example choices, the names of registry items `add` or
Studio installs and which of the two installed them, and system info — including a coarse
environment fingerprint: OS, kernel string, CPU and memory shape, sandbox
runtime such as gVisor or Docker, and the _name_ of a coding agent driving the
CLI when one is detected (`claude_code`, `codex`, `cursor`). That name is
inferred from which well-known environment variables exist. Local paths and URL query strings are redacted from error and
checkpoint messages. Project names, video content, and environment variable
values are never collected, except short self-identifying names: `AGENT`,
`AI_AGENT` and `TERM_PROGRAM` (filtered to short slugs), and `HYPERFRAMES_CLIENT`,
the `<app>/<version>/<channel>` tag an app that launches the CLI sets, sent as
`client` so reports from that app can be told apart.
Nothing personally identifying is collected until you sign in. When you run
`hyperframes auth login`, your HeyGen account email — or username, if the
account has no email — is linked to your usage, and your prior anonymous usage
is stitched to it. Nothing else personal, and only once you choose to sign in.
Turn it all off with `HYPERFRAMES_NO_TELEMETRY=1` or the command above.
[Feedback collection](/guides/feedback) explains the post-render prompt and the
Studio feedback bar.
One consequence worth knowing: turning telemetry off also opts the install out
of **canary rollouts**. A staged release enables a change for a stable slice of
installs, and an install that reports nothing cannot be compared against
anything. Every route counts — `telemetry disable`,
`HYPERFRAMES_NO_TELEMETRY=1`, `DO_NOT_TRACK=1`, and dev builds. See
[Canary rollouts](/contributing/canary-rollouts).
### `skills`
Install or refresh the HyperFrames skills that AI coding tools read.
```bash
# Install the complete published set and link it into installed agents
npx hyperframes skills
# What is installed?
npx hyperframes skills check
npx hyperframes skills check --json
# Refresh the core set and everything already installed
npx hyperframes skills update
# Refresh, and also install one skill on demand
npx hyperframes skills update slideshow
```
Bare `skills` installs everything. `skills update` keeps a deliberate partial
installation partial: it refreshes the core set plus whatever is already
installed, and never expands beyond that unless you name a skill. Naming one
adds it. `check` and `update` both accept `--json`, plus `--dir` and `--source`
to point removed-detection at a different skills directory or source — those two
scope the prune, not the install.
Set `HYPERFRAMES_SKIP_SKILLS=1` when something else manages the skills (CI, tests,
or an install pinned to one commit). `skills update` and bare `skills` then exit 0
with a one-line notice and leave the installed skills unchanged.
The CLI installs from the current HyperFrames GitHub source and links the global
bundles into whichever compatible agents it finds. After scaffolding, `init`
also refreshes the core set plus any HyperFrames skills you already have.
#### `fatal: active post-checkout hook found during git clone`
If Git LFS is installed globally, Git 2.45+ refuses to run the LFS
post-checkout hook during any `git clone` — including the clone the upstream
`skills` CLI does internally:
```
■ Failed to clone repository
fatal: active `post-checkout` hook found during `git clone`
└ Installation failed
```
`hyperframes skills` already handles this. You do not need an environment
variable.
If you called the upstream command directly instead, set it yourself:
```bash
GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes
```
### `figma` and `events`
`npx hyperframes figma` imports through the Figma REST API, with three
subcommands: `asset` (export an image or SVG), `tokens` (pull design tokens),
and `component` (import an editable component). Run it bare for usage. See
[Figma integration](/guides/figma) for setup and examples.
`npx hyperframes events` lets an installed workflow skill emit an anonymous
usage event (`--skill`, `--event`, `--outcome`). Nothing calls it by hand.
## hyperframes auth
Sign in to HeyGen and manage credentials. They live in `~/.heygen/credentials`
(mode `0600`) and are **shared with the `heygen` CLI** — sign in with one and
the other picks up the session.
First match wins:
1. `HEYGEN_API_KEY`
2. `HYPERFRAMES_API_KEY` (a HyperFrames alias for the same thing)
3. `HEYGEN_ACCESS_TOKEN` (an OAuth token a host app injects; never refreshed or saved)
4. `~/.heygen/credentials`
### `auth login`
Opens a browser for OAuth:
```bash
hyperframes auth login
```
Pass `--api-key` when you want a long-lived HeyGen API key instead. The key is
verified against `GET /v3/users/me` before the command reports success, so a
rejected key is never left on disk.
```bash
# Hidden-input prompt
hyperframes auth login --api-key
# From stdin, for CI
echo "$HEYGEN_API_KEY" | hyperframes auth login --api-key
```
### `auth status`
Shows the active credential's source and type, and the verified identity —
account plus billing snapshot. It exits non-zero when nothing is configured or
the API rejects the credential, so a script can test sign-in state.
```bash
hyperframes auth status
hyperframes auth status --json
```
### `auth refresh`
Force-refreshes the stored OAuth access token. Applies to an OAuth session, not
an API key.
```bash
hyperframes auth refresh
```
### `auth logout`
Removes the stored credential, with a confirmation on a TTY.
```bash
hyperframes auth logout
hyperframes auth logout --keep-api-key # clear only the OAuth session
hyperframes auth logout --yes # no prompt
```
### Environment variables
| Variable | Description |
| --------------------- | ------------------------------------------------ |
| `HEYGEN_API_KEY` | Override the stored credential. |
| `HYPERFRAMES_API_KEY` | Alias for `HEYGEN_API_KEY`. |
| `HEYGEN_ACCESS_TOKEN` | OAuth token from a host app; never refreshed. |
| `HEYGEN_API_URL` | API base URL (default `https://api.heygen.com`). |
| `HEYGEN_CONFIG_DIR` | Credentials directory (default `~/.heygen`). |
For the keys other capabilities use — ElevenLabs and Gemini for voice and music
fallback, OpenRouter and Gemini for capture — and how the skills prioritize
them, see [Authentication and API keys](/guides/authentication).
## hyperframes cloud
Render on HeyGen's hosted cloud. No local Chrome, no local ffmpeg, no AWS to
manage. Sign in once and the same credential drives every subcommand.
```bash
hyperframes auth login # one-time
hyperframes cloud render ./my-video # zip, upload, poll, download
hyperframes cloud render ./my-video --no-wait # submit and exit with the render_id
hyperframes cloud list # recent renders
```
### `cloud render [<projectDir>]`
End to end: zips the project, uploads it through the direct-to-S3 asset flow,
submits `POST /v3/hyperframes/renders`, polls
`GET /v3/hyperframes/renders/{id}` until it finishes or fails, and streams the
video to disk.
The zip excludes root `renders` and `snapshots`, `.git`, `node_modules`, `dist`,
`.next`, `coverage`, dotfiles, and anything your `.hyperframesignore` rules
match. Those rules use gitignore syntax and apply to `hyperframes publish` too.
Keep them narrow — a dynamically selected asset may have no static reference to
protect it.
Media files of 5 MB or more that the project names by path go up as HeyGen
assets before zipping, and the zip's copy of each HTML, CSS, script and JSON
file points at the asset URL instead; your project files are not changed.
Asset URLs are public and unsigned: anyone who has one can fetch the
media. Uploads are cached by content, so a re-render uploads only what changed.
Media the asset API does not take as is is converted on your machine first,
which needs ffmpeg: video (for example MKV, or over 200 MB) and audio (for
example FLAC or M4A) at visually lossless quality, still images such as AVIF to
PNG, and animated GIFs of 5 MB or more in the entry composition to the same
seekable video the renderer makes from them. A video or audio file that has to
be re-encoded is first cut to the parts the entry composition plays (plus half
a second either side), and the composition's media starts shift to match, so a
long source fits. Media inside sub-compositions, looping clips, clips with
`data-var-src` and files a script names keep their full length. A file no
plain string names, such as one a script builds a path to or one picked through
`--variables`, stays in the zip, as do animated GIFs inside sub-compositions.
The zip has to come in under 200 MB — the direct-upload cap — or the command
stops before uploading it and names the largest files left. Use `--dry-run`
first to see which media would upload and the compressed size, without
authenticating, uploading, or starting anything. If you are over, add only
paths you have verified are unneeded to `.hyperframesignore`.
Render parameters mirror local `hyperframes render` where they overlap:
| Flag | Default | Description |
| ---------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--fps` | `30` | Integer, 1–240 |
| `--quality` | `standard` | `draft`, `standard`, or `high` |
| `--format` | `mp4` | `mp4`, `webm`, or `mov` |
| `--resolution` | `1080p` | `1080p` or `4k`. 4k bills at 1.5×. |
| `--aspect-ratio` | auto | `16:9`, `9:16`, or `1:1`. Auto-detected from a local project's `data-width` and `data-height`, so you rarely need it. The renderer cannot reshape a composition — a value that disagrees with the authored ratio is an error. With `--asset-id` or `--url` the server defaults to `16:9`. |
| `--composition` / `-c` | `index.html` | Entry HTML file inside the zip |
| `--variables` | — | Inline JSON overriding `data-composition-variables` |
| `--variables-file` | — | Read those overrides from a JSON file |
| `--strict-variables` | off | Fail when a variable is undeclared or the wrong type |
| `--title` | — | Free-text label echoed back in detail responses |
| `--output` / `-o` | `renders/<render_id>.<ext>` | Where the downloaded video lands |
| `--dry-run` | off | Build and inspect the zip without authenticating, uploading, or rendering |
Lifecycle and control:
| Flag | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| `--no-wait` | Submit and exit immediately, printing the `render_id` to stdout |
| `--callback-url` | HTTPS webhook fired when the render terminates. It fires whether or not the CLI is still polling — pair with `--no-wait` for true fire-and-forget. |
| `--callback-id` | Opaque tracking ID echoed in webhook payloads |
| `--asset-id` | Skip zip and upload; submit an already-uploaded composition. Mutually exclusive with the project dir and `--url`. |
| `--url` | Submit a public HTTPS zip URL. Same mutual exclusion as `--asset-id`. |
| `--poll-interval` | Poll cadence in seconds (default 2) |
| `--max-wait` | Maximum poll duration in minutes (default 60) |
| `--idempotency-key` | `Idempotency-Key` for safe retries. 1–255 characters from `[A-Za-z0-9_:.-]`. |
| `--json` | Machine-readable JSON instead of human progress |
```bash
# Pick a composition and an output path.
hyperframes cloud render . \
--composition compositions/intro.html \
--output ./renders/intro.mp4
# Fire and forget, with a webhook.
hyperframes cloud render --callback-url https://example.com/hf-hook --no-wait
# Re-render something already uploaded, or render straight from a public URL.
hyperframes cloud render --asset-id asst_abc123
hyperframes cloud render --url https://cdn.example.com/site.zip
```
#### Why you want `--idempotency-key`
On a `401`, the CLI force-refreshes the OAuth token and replays the request. For
reads that is harmless. But `POST /v3/assets` — the zip upload — is not
idempotent on its own, so a retry without a key would create a duplicate asset
and bill the workspace twice.
Pass `--idempotency-key <key>` whenever you want safe retries. It is forwarded
to both the upload and the submit, and the server scopes idempotency per
endpoint, so reusing one value across both steps is safe and prevents a
duplicate at either. Use a UUID per logical render, or any opaque string.
```bash
hyperframes cloud render . --idempotency-key "$(uuidgen)"
```
### `cloud list`
Pages through recent renders, cursor-based. `--limit` caps one page (1–100,
default 10), `--token` resumes from a previous `next_token`, and `--all` walks
until exhausted. `--json` for the machine-readable form.
```bash
hyperframes cloud list
hyperframes cloud list --limit 50 --json
hyperframes cloud list --all
```
### `cloud get <render_id>`
Fetches one render's full detail record, including the short-lived signed
`video_url` and `thumbnail_url`. Those are presigned S3 URLs — re-fetch on
demand rather than caching them.
```bash
hyperframes cloud get hfr_abc123
hyperframes cloud get hfr_abc123 --json
```
### `cloud delete <render_id>`
Soft-deletes a render. Later `GET` calls return 404 and the signed video URL
stops working shortly after. It prompts interactively; `--no-confirm` skips
that, and is required alongside `--json`.
```bash
hyperframes cloud delete hfr_abc123
hyperframes cloud delete hfr_abc123 --no-confirm --json
```
### Which one should you use?
- **`hyperframes render`** — the fastest loop. Use it while authoring.
- **`hyperframes cloud render`** — zero infrastructure. HeyGen runs it, you pay
per credit. Use it when you do not want Chrome, ffmpeg, or AWS on your
machine.
- **`hyperframes lambda render`** — your own AWS, chunked in parallel. Use it
when you have already invested in AWS and want the work on your account.
`cloud` reuses whatever credential `hyperframes auth status` resolves. Override
the API base for staging with `HEYGEN_API_URL`.
## hyperframes lambda
Deploy distributed rendering to AWS Lambda and drive it from your laptop or CI.
The command group wraps the `@hyperframes/aws-lambda` SDK plus AWS SAM, so an
end-to-end render is three commands:
```bash
hyperframes lambda deploy
hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
hyperframes lambda destroy # when you're done
```
You need AWS credentials (env vars, `~/.aws/credentials`, SSO, or IMDS), the
[AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
on `PATH`, and `bun` on `PATH` to build the handler ZIP.
Flags are shared across the whole group. These identify the stack and shape the
deploy:
| Flag | Default | Description |
| ----------------- | ------------------------------------ | -------------------------------------------------------- |
| `--stack-name` | `hyperframes-default` | CloudFormation stack name |
| `--region` | `AWS_REGION`, else `us-east-1` | AWS region |
| `--profile` | `AWS_PROFILE` | AWS profile name |
| `--concurrency` | none | Lambda reserved concurrency. Without it, a new stack reserves none and each render runs up to 90% of the account's unreserved concurrency; a redeploy keeps the stack's current reservation; `none` removes it |
| `--memory` | `10240` | Lambda memory in MB |
| `--chrome-source` | `sparticuz` | `sparticuz` or `chrome-headless-shell` |
| `--skip-build` | off | Reuse the existing `handler.zip` |
And these drive `render` and `render-batch`:
| Flag | Default | Description |
| ----------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `--width`, `--height` | required | Render dimensions in pixels |
| `--site-id` | content hash | Reuse an uploaded site instead of uploading again |
| `--fps` | `30` | `24`, `25`, `30`, or `60` |
| `--format` | `mp4` | `mp4`, `mov`, `webm`, or `png-sequence` |
| `--codec` | `h264` | `h264` or `h265`, MP4 only |
| `--quality` | `standard` | `draft`, `standard`, or `high` |
| `--output-resolution` | — | Supersample via Chrome `deviceScaleFactor` to a preset (`1080p`, `4k`, `uhd`, `hd`, `landscape-4k`, …) without changing layout |
| `--chunk-size` | auto | Frames per chunk. By default each chunk is sized to finish inside the Lambda timeout |
| `--max-parallel-chunks` | auto | Chunks per render. By default one wave across the deploy's `--concurrency` (or 90% of the account's unreserved concurrency), widened when a chunk would outrun the Lambda timeout |
| `--target-chunk-frames` | — | Ceiling on frames per chunk. The planner adds chunks — up to `--max-parallel-chunks` — to stay under it, and short videos still collapse to fewer. Ignored when `--chunk-size` is set. |
| `--variables` | — | JSON object reaching every chunk worker as `window.__hfVariables` |
| `--variables-file` | — | Read those from a JSON file |
| `--strict-variables` | off | Fail instead of warn on an undeclared or mistyped key |
| `--execution-name` | `hf-render-<uuid>` | Step Functions execution name |
| `--output-key` | `renders/<exec>/output.<ext>` | Final output S3 key |
| `--batch` | — | JSONL batch file for `render-batch` |
| `--max-concurrent` | `50` | In-flight Step Functions executions for `render-batch` |
| `--dry-run` | off | For `render-batch`: print the manifest without calling AWS |
| `--wait` | off | Block until the render finishes, streaming per-chunk progress |
| `--wait-interval-ms` | `5000` | Poll cadence while `--wait` is set |
| `--json` | off | Machine-readable output |
### `lambda deploy`
Builds `packages/aws-lambda/dist/handler.zip` and SAM-deploys the stack at
`examples/aws-lambda/template.yaml`. On success it writes
`<cwd>/.hyperframes/lambda-stack-<stackName>.json`, so the other subcommands do
not have to re-derive the bucket and state-machine ARN. Re-running on the same
`--stack-name` is a no-op when nothing changed.
```bash
hyperframes lambda deploy \
--stack-name=hyperframes-prod \
--region=us-east-1 \
--concurrency=8 \
--memory=10240
```
### `lambda sites create <projectDir>`
Uploads the project's files to the bucket's shared content store, skipping any
file already there, and returns a `siteId` you can reuse. A re-render of the
same tree then skips the upload.
```bash
hyperframes lambda sites create ./my-project
# → siteId: abc1234deadbeef0 (stable across re-runs of the same tree)
hyperframes lambda render ./my-project --site-id=abc1234deadbeef0 --width 1920 --height 1080
```
### `lambda render <projectDir>`
Starts a Step Functions execution and returns a `renderId` immediately — poll it
with `lambda progress` — unless you pass `--wait`.
```bash
hyperframes lambda render ./my-project \
--width=1920 --height=1080 --fps=30 --format=mp4 \
--chunk-size=240 --max-parallel-chunks=16 \
--wait
hyperframes lambda render ./my-template --site-id=abc1234deadbeef0 \
--width=1920 --height=1080 \
--variables '{"title":"Hello Alice","accent":"#ff0000"}'
```
Variables travel inside the Step Functions Standard execution input, which AWS
caps at 256 KiB for the whole payload. So pass typed data through variables —
strings, numbers, records — and reference media by URL for the composition to
resolve at render time, rather than inlining bytes. The SDK checks the size
client-side and rejects an oversize input with a clear error before any AWS call
runs. The [templates-on-lambda guide](/deploy/templates-on-lambda) explains the
URL-your-assets convention.
### `lambda render-batch <projectDir>`
Fans out N personalised renders from a JSONL batch file — the headline
ergonomic for automated template pipelines. It deploys the site once (or skips
that with `--site-id`), then invokes `renderToLambda` per row with that row's
`variables` and `outputKey`.
```jsonl
{"outputKey": "renders/alice.mp4", "variables": {"name": "Alice", "accent": "#ff0000"}}
{"outputKey": "renders/bob.mp4", "variables": {"name": "Bob", "accent": "#0000ff"}}
{"outputKey": "renders/carol.mp4", "variables": {"name": "Carol"}, "executionName": "hf-carol-001"}
```
```bash
hyperframes lambda render-batch ./my-template \
--batch ./users.jsonl \
--width 1920 --height 1080 \
--max-concurrent 10
```
It prints one row per input line, with the `executionArn` and status:
```
Batch dispatched: 3 started, 0 failed-to-start.
✓ line 1 renders/alice.mp4 arn:aws:states:us-east-1:1234:execution:hf:hf-render-...
✓ line 2 renders/bob.mp4 arn:aws:states:us-east-1:1234:execution:hf:hf-render-...
✓ line 3 renders/carol.mp4 arn:aws:states:us-east-1:1234:execution:hf:hf-carol-001
```
Poll each one with `hyperframes lambda progress <renderId>`, or use the returned
`executionArn`. Run it with `--dry-run` first to lint the batch file before
committing to N billable executions — every entry comes back as
`status: "would-invoke"`.
`--max-concurrent` (default 50) caps `StartExecution` calls, so a 10,000-entry
batch does not try to spawn 10,000 executions and trip your account limits. It
is orchestrator-side only, and cannot enforce your account's Lambda concurrency
quota — pick a value from that quota and the reserved concurrency you set at
`lambda deploy --concurrency=<N>`. It is not `--max-parallel-chunks`, which caps
chunks inside one render. Without a reserved concurrency every render in the
batch sizes itself to the whole account, so reserve one before a large batch.
### `lambda progress <renderId | executionArn>`
Prints one snapshot: overall percent, frames rendered, Lambda invocations,
accrued cost, and any errors. A bare `renderId` is resolved against the stack's
state-machine ARN; a full SFN execution ARN also works.
```bash
hyperframes lambda progress hf-render-abcd1234
```
### `lambda destroy`
Runs `sam delete --no-prompts` and drops the local state file. The render S3
bucket is configured with CloudFormation `Retain`, so it survives — empty and
delete it via the console or AWS CLI if you want the storage back.
### `lambda policies role | user | validate`
Prints or validates the minimum IAM policy the CLI needs.
```bash
# Inline-policy doc for an IAM user that runs the CLI.
hyperframes lambda policies user
# { TrustRelationship, InlinePolicy } for a CloudFormation service role.
hyperframes lambda policies role
# Does a checked-in policy still cover the CLI?
hyperframes lambda policies validate ./infra/iam/hyperframes-deploy.json
```
`validate` reads the JSON doc and checks the union of its `Effect: Allow`
actions against what the CLI needs, expanding `s3:*`, `s3:Get*`, and `*`
wildcards. Missing actions print to stderr and it exits non-zero — wire it into
CI to catch drift before the next deploy fails.
The action list is deliberately broad (`Resource: "*"`) because CloudFormation
mints new function, state-machine, and bucket ARNs on every adopter's first
deploy. Narrow `Resource` to the deployed ARNs after that first success if your
security posture calls for it.
### State files
`hyperframes lambda` keeps per-stack metadata under
`<cwd>/.hyperframes/lambda-stack-<name>.json`, so the verbs never have to call
`describe-stacks`. Commit it or `.gitignore` it as you prefer — it holds the
bucket name, state-machine ARN, and region. None are secrets, but all identify
your AWS account.
## hyperframes cloudrun
The Google Cloud counterpart to [`lambda`](#hyperframes-lambda): distributed
rendering on Cloud Run plus Cloud Workflows, driven from your laptop or CI. It
wraps the `@hyperframes/gcp-cloud-run` SDK plus `terraform` (the module shipped
with the package) and `gcloud` or Cloud Build for the image.
```bash
hyperframes cloudrun deploy --project my-gcp-project
hyperframes cloudrun render ./my-project --width 1920 --height 1080 --wait
hyperframes cloudrun destroy --project my-gcp-project
```
**`deploy`** enables the required APIs, builds and pushes the render image via
Cloud Build unless you pass `--image`, then `terraform apply`s the module that
provisions the GCS bucket, Cloud Run service, Cloud Workflows definition, two
service accounts, and a runaway-request alert. It caches the bucket, service URL,
and workflow id so later verbs do not need them again. `--project` is required;
`--region` defaults to `us-central1` and `--repo` (the Artifact Registry repo)
to `hyperframes`. Sizing is `--cpu` (1, 2, 4, or 8; default 4), `--memory`
(default `16Gi`), `--max-instances` (the fan-out ceiling, default 100), and
`--timeout` (per-request seconds, max 3600). Omit one and the module default
stands; for anything finer, apply the Terraform module directly.
The other verbs mirror [`lambda`](#hyperframes-lambda) one for one, and so do
their flags:
- `sites create <projectDir>` uploads a project to GCS once and prints the
`gs://` URI.
- `render <projectDir>` starts a distributed render. `--width` and `--height`
are required, and `--render-id` stands in for `--execution-name`.
- `render-batch <projectDir>` fans out from a JSONL file.
- `progress <executionName>` prints progress and cost — coarse while running,
exact on success.
- `destroy` runs `terraform destroy` and force-destroys the render bucket.
Pick `cloudrun` when your backend and storage already live on GCP. The render
primitives are identical; only the storage (GCS), compute (Cloud Run), and
orchestration (Cloud Workflows) adapters differ. The deployed stack's
coordinates cache in `~/.hyperframes/cloudrun-state.json` — project id, region,
bucket, service URL, workflow id. None are secrets, but all identify your GCP
project. [Google Cloud Run](/deploy/gcp-cloud-run) has the full walkthrough.
## hyperframes.json
`hyperframes init` writes a `hyperframes.json` at the root of every new project,
and `hyperframes add` reads it to learn which registry to pull from and where
files go. Edit it to reshape your layout or point at a custom registry — or
delete it to fall back to the defaults.
```json
{
"$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
```
| Field | Description |
| ------------------ | --------------------------------------------------------------------------------------- |
| `registry` | Base URL of the registry `add` pulls from. Defaults to the public HyperFrames registry. |
| `paths.blocks` | Where block `.html` files land, relative to the project root. |
| `paths.components` | Where component files land. |
| `paths.assets` | Where referenced assets — images, fonts — land. |
Anything you leave out gets the default, so the file only needs your overrides.
## Related topics
<CardGroup cols={2}>
<Card title="Producer" icon="film" href="/packages/producer">
The rendering pipeline the CLI calls under the hood. Use directly for programmatic rendering.
</Card>
<Card title="Studio" icon="palette" href="/packages/studio">
The editor UI that powers `hyperframes preview`. Use directly to embed in your own app.
</Card>
<Card title="Core" icon="cube" href="/packages/core">
Types, linter, and runtime. Use directly for custom tooling and integrations.
</Card>
<Card title="Engine" icon="gear" href="/packages/engine">
The capture engine. Use directly for custom frame capture pipelines.
</Card>
</CardGroup>
Reference in New Issue View Git Blame Copy Permalink