Files
hyperframes/packages/cli
ukimsanov 570dedbde2 feat(cli): add capture-video for on-demand video fetch from manifest
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
2026-06-12 01:12:43 -07:00
..
2026-06-11 02:40:36 +00:00

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