The capture pipeline writes capture/extracted/video-manifest.json
listing every <video> element on the source page (URL, dimensions,
heading, caption, preview PNG) but deliberately doesn't download the
mp4s — sites with 15+ feature videos would balloon capture size by
hundreds of MB.
User direction on this tradeoff: keep the capture lean, let the AI
agent decide per-beat whether the actual mp4 is worth fetching, and
provide a single CLI command to fetch one when the answer is yes.
That preserves the determinism (the manifest is the contract) and
the choice (agent picks what's relevant).
The motivating case is heygen.com's "Orb" — a 3D-rendered hero
animation that's at index 0 of the heygen manifest (768×768, heading
"Turn your ideas into videos in minutes"). On the last real-AI-test
run, the agent KNEW about it ("the genuine article was in the capture")
but composed a CSS-3D cube approximation instead because there was no
one-step way to fetch the actual mp4. This command closes that gap.
New command surface:
hyperframes capture-video <project-dir> --list
List manifest entries with index, dimensions, heading, URL.
hyperframes capture-video <project-dir> --index 0
Download the manifest entry at the given index.
hyperframes capture-video <project-dir> --url <URL>
Download a specific entry by exact URL match.
Behavior:
- Reads <project-dir>/capture/extracted/video-manifest.json.
- Resolves the target entry by --index or --url (clear error message
on out-of-range / missing).
- Downloads to <project-dir>/capture/assets/videos/<filename> — same
layout as the rest of the captured-assets tree, so compositions
reference videos with the same `capture/assets/...` path pattern
they already use for SVGs and rasters.
- Decodes URL-encoded characters and sanitizes the filename so
manifest entries like `Frame-2147227325%20(1).mp4` land as
`Frame-2147227325_1_.mp4` on disk.
- Idempotent: if the file already exists, warns and skips (delete +
re-run to refetch).
- On success, prints a ready-to-paste <video> embed snippet with
data-start / data-duration / data-track-index. Aspect-aware: square
videos (e.g. the Orb) get a 5s default duration suggestion vs 4s
for landscape feature videos.
Files changed:
- packages/cli/src/commands/capture-video.ts — new command (~170 LOC).
- packages/cli/src/cli.ts — registered `capture-video` subcommand.
- packages/cli/src/help.ts — added to the "Getting Started" group so
it appears in `hyperframes --help`.
- skills/website-to-hyperframes/references/beat-builder-guide.md —
updated the "Captured videos" landmine (from commit e6aa7fed) to
point at the CLI command instead of the raw curl pattern. The CLI
command becomes the documented path; curl is no longer mentioned
(one path is better than two).
Smoke-tested against the existing /videos/heygen-com capture:
`capture-video --list` correctly lists all 9 manifest entries with
the Orb at index 0 (768×768, "Turn your ideas into videos in
minutes"). Did NOT actually download in this commit — that's the
user's runtime choice. Command + help output verified.
Closes the asset-discoverability bundle for this turn:
e6aa7fed - doc landmine for asset-descriptions.md search
02f95f95 - broadened isLogo via structural DOM signals
953004b9 - LOGO tags in asset-descriptions.md (Gemini & no-Gemini)
this - on-demand video fetch for the Orb-class assets
hyperframes
CLI for creating, previewing, and rendering HTML video compositions.
Install
npm install -g hyperframes
Or use directly with npx:
npx hyperframes <command>
Requirements: Node.js >= 22, FFmpeg
Commands
init
Scaffold a new Hyperframes project from a template:
npx hyperframes init my-video
cd my-video
preview
Start the live preview studio in your browser:
npx hyperframes preview
# Studio running at http://localhost:3002
npx hyperframes preview --port 4567
render
Render a composition to MP4:
npx hyperframes render ./my-composition.html -o output.mp4
lint
Validate your Hyperframes HTML:
npx hyperframes lint ./my-composition
npx hyperframes lint ./my-composition --json # JSON output for CI/tooling
npx hyperframes lint ./my-composition --verbose # Include info-level findings
By default only errors and warnings are shown. Use --verbose to also display informational findings (e.g., external script dependency notices). Use --json for machine-readable output with errorCount, warningCount, infoCount, and a findings array.
compositions
List compositions found in the current project:
npx hyperframes compositions
benchmark
Run rendering benchmarks:
npx hyperframes benchmark ./my-composition.html
doctor
Check your environment for required dependencies (Chrome, FFmpeg, Node.js):
npx hyperframes doctor
browser
Manage the bundled Chrome/Chromium installation:
npx hyperframes browser
info
Print version and environment info:
npx hyperframes info
docs
Open the documentation in your browser:
npx hyperframes docs
upgrade
Check for updates and show upgrade instructions:
npx hyperframes upgrade
npx hyperframes upgrade --check --json # machine-readable for agents
Documentation
Full documentation: hyperframes.heygen.com/packages/cli
Related packages
@hyperframes/core— types, parsers, frame adapters@hyperframes/engine— rendering engine@hyperframes/producer— render pipeline@hyperframes/studio— composition editor UI