mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-08 02:36:10 +00:00
JamesandClaude Opus 4.7
21243b6957
Follow-up on the PR #603 review. The previous fix named both attributes but didn't make their distinct shapes / roles obvious; a reader could still wonder "are these two views of the same data?". Now the doc opens with the shape contrast (array of declarations vs object of values) and the section closes with a numbered precedence layering so the merge order is unambiguous. - compositions.md: replaced the bullet list with a shape-first description ("JSON array of declarations" vs "JSON object keyed by variable id"), an explicit "they aren't redundant" line, and a numbered list of the three precedence layers (declared default → host data-variable-values → CLI --variables). - skills/hyperframes-cli/SKILL.md: highlighted the same shape contrast inside the parametrized-renders paragraph (declarations array vs values object). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
173 lines
9.7 KiB
Markdown
173 lines
9.7 KiB
Markdown
---
|
|
name: hyperframes-cli
|
|
description: HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, remove-background, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, removing the background from an avatar video for transparent overlays, or troubleshooting the HyperFrames environment.
|
|
---
|
|
|
|
# HyperFrames CLI
|
|
|
|
Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.
|
|
|
|
## Workflow
|
|
|
|
1. **Scaffold** — `npx hyperframes init my-video`
|
|
2. **Write** — author HTML composition (see the `hyperframes` skill)
|
|
3. **Lint** — `npx hyperframes lint`
|
|
4. **Visual inspect** — `npx hyperframes inspect`
|
|
5. **Preview** — `npx hyperframes preview`
|
|
6. **Render** — `npx hyperframes render`
|
|
|
|
Lint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.
|
|
|
|
## Scaffolding
|
|
|
|
```bash
|
|
npx hyperframes init my-video # interactive wizard
|
|
npx hyperframes init my-video --example warm-grain # pick an example
|
|
npx hyperframes init my-video --video clip.mp4 # with video file
|
|
npx hyperframes init my-video --audio track.mp3 # with audio file
|
|
npx hyperframes init my-video --example blank --tailwind # with Tailwind v4 browser runtime
|
|
npx hyperframes init my-video --non-interactive # skip prompts (CI/agents)
|
|
```
|
|
|
|
Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
|
|
|
|
`init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.
|
|
|
|
When using `--tailwind`, invoke the `tailwind` skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.
|
|
|
|
## Linting
|
|
|
|
```bash
|
|
npx hyperframes lint # current directory
|
|
npx hyperframes lint ./my-project # specific project
|
|
npx hyperframes lint --verbose # info-level findings
|
|
npx hyperframes lint --json # machine-readable
|
|
```
|
|
|
|
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).
|
|
|
|
## Visual Inspect
|
|
|
|
```bash
|
|
npx hyperframes inspect # inspect rendered layout over the timeline
|
|
npx hyperframes inspect ./my-project # specific project
|
|
npx hyperframes inspect --json # agent-readable findings
|
|
npx hyperframes inspect --samples 15 # denser timeline sweep
|
|
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
|
|
```
|
|
|
|
Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
|
|
|
|
- Text extending outside the nearest visual container or bubble
|
|
- Text clipped by its own fixed-width/fixed-height box
|
|
- Text extending outside the composition canvas
|
|
- Children escaping clipping containers
|
|
|
|
Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.
|
|
|
|
`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.
|
|
|
|
## Previewing
|
|
|
|
```bash
|
|
npx hyperframes preview # serve current directory
|
|
npx hyperframes preview --port 4567 # custom port (default 3002)
|
|
```
|
|
|
|
Hot-reloads on file changes. Opens the studio in your browser automatically.
|
|
|
|
When handing a project back to the user, use the Studio project URL, not the
|
|
source `index.html` path:
|
|
|
|
```text
|
|
http://localhost:<port>/#project/<project-name>
|
|
```
|
|
|
|
Use the actual port from the preview output and the project directory name. For
|
|
example, after `npx hyperframes preview --port 3017` in `codex-openai-video`,
|
|
report `http://localhost:3017/#project/codex-openai-video`.
|
|
|
|
Treat `index.html` as source-code context only. It is fine to link it as an
|
|
implementation file, but do not label it as the project or preview surface.
|
|
|
|
## Rendering
|
|
|
|
```bash
|
|
npx hyperframes render # standard MP4
|
|
npx hyperframes render --output final.mp4 # named output
|
|
npx hyperframes render --quality draft # fast iteration
|
|
npx hyperframes render --fps 60 --quality high # final delivery
|
|
npx hyperframes render --format webm # transparent WebM
|
|
npx hyperframes render --docker # byte-identical
|
|
```
|
|
|
|
| Flag | Options | Default | Notes |
|
|
| -------------------- | --------------------- | -------------------------- | ------------------------------------------------------------------ |
|
|
| `--output` | path | renders/name_timestamp.mp4 | Output path |
|
|
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
|
|
| `--quality` | draft, standard, high | standard | draft for iterating |
|
|
| `--format` | mp4, webm | mp4 | WebM supports transparency |
|
|
| `--workers` | 1-8 or auto | auto | Each spawns Chrome |
|
|
| `--docker` | flag | off | Reproducible output |
|
|
| `--gpu` | flag | off | GPU-accelerated encoding |
|
|
| `--strict` | flag | off | Fail on lint errors |
|
|
| `--strict-all` | flag | off | Fail on errors AND warnings |
|
|
| `--variables` | JSON object | — | Override variable values declared in `data-composition-variables` |
|
|
| `--variables-file` | path | — | JSON file with variable values (alternative to `--variables`) |
|
|
| `--strict-variables` | flag | off | Fail render on undeclared keys or type mismatches in `--variables` |
|
|
|
|
**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
|
|
|
|
**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI **`--variables '{"title":"Q4 Report"}'`** is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with **`data-variable-values`** — same object shape, scoped to one mount of the sub-composition. See the `hyperframes` skill for the full pattern.)
|
|
|
|
## Transcription
|
|
|
|
```bash
|
|
npx hyperframes transcribe audio.mp3
|
|
npx hyperframes transcribe video.mp4 --model medium.en --language en
|
|
npx hyperframes transcribe subtitles.srt # import existing
|
|
npx hyperframes transcribe subtitles.vtt
|
|
npx hyperframes transcribe openai-response.json
|
|
```
|
|
|
|
## Text-to-Speech
|
|
|
|
```bash
|
|
npx hyperframes tts "Text here" --voice af_nova --output narration.wav
|
|
npx hyperframes tts script.txt --voice bf_emma
|
|
npx hyperframes tts --list # show all voices
|
|
```
|
|
|
|
## Background Removal (transparent video)
|
|
|
|
Remove the background from a video or image so it can be used as a transparent overlay in a composition (e.g. an avatar floating on a background).
|
|
|
|
```bash
|
|
npx hyperframes remove-background avatar.mp4 -o transparent.webm # default: VP9 alpha WebM
|
|
npx hyperframes remove-background avatar.mp4 -o transparent.mov # ProRes 4444 for editing
|
|
npx hyperframes remove-background portrait.jpg -o cutout.png # single-image cutout
|
|
npx hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu
|
|
npx hyperframes remove-background --info # detected providers
|
|
```
|
|
|
|
Uses `u2net_human_seg` (MIT). First run downloads ~168 MB of weights to `~/.cache/hyperframes/background-removal/models/` and reuses them after. Drop the resulting `.webm` into a composition with `<video src="transparent.webm" autoplay muted loop>` — Chrome decodes the alpha natively.
|
|
|
|
## Troubleshooting
|
|
|
|
```bash
|
|
npx hyperframes doctor # check environment (Chrome, FFmpeg, Node, memory)
|
|
npx hyperframes browser # manage bundled Chrome
|
|
npx hyperframes info # version and environment details
|
|
npx hyperframes upgrade # check for updates
|
|
```
|
|
|
|
Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.
|
|
|
|
## Other
|
|
|
|
```bash
|
|
npx hyperframes compositions # list compositions in project
|
|
npx hyperframes docs # open documentation
|
|
npx hyperframes benchmark . # benchmark render performance
|
|
```
|