hyperframes-cli

# HyperFrames CLI Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg. ## How to drive this CLI (single-voice — do NOT parallelize) This is a deterministic, ordered CLI workflow with ONE coherent operator voice. Do **not** fan out parallel sub-agents to run these commands — render/preview/lint share the project directory and media files (one-writer-per-dir), and the steps are sequentially dependent (scaffold → write → lint → preview → render). Run the commands yourself, in order, reading each command's real output before the next step. **Craft rules:** - **Lint is the gate.** Always `lint` before `preview`/`render`; never render past lint errors. Use `--strict` in CI/agent runs so a lint error fails the render instead of shipping a broken frame. - **Draft → review → final.** Iterate at `--quality draft`, review at `standard`, deliver at `high`. Don't burn render time at 60fps/high until the composition is locked. - **Doctor first on failure.** If a render fails, run `doctor` BEFORE changing flags — most failures are environment (missing FFmpeg/Chrome, low memory), not the command. ### Output contract Each invocation produces one observable artifact: `init` → a scaffolded project dir; `lint` → an errors/warnings/info report (`--json` for machine-readable); `preview` → a live studio URL; `render` → a video file at `renders/<name>_<timestamp>.mp4` (or `--output`); `transcribe`/`tts` → caption/audio files. State the exact output path to the user. ### Verify step - After `render`: confirm the output file exists and is non-empty (`ls -la <output>`), and report its path + size. A "render succeeded" log with no playable file on disk is not done. - After `lint`: report the actual error/warning counts from the command output — never assert "clean" without the lint having run. - **No-hallucination guardrail:** only claim a flag, template, or voice exists if it appears in this reference or in real `--help`/`--list` output. If unsure of a flag, run `npx hyperframes <cmd> --help` (or `tts --list`) and cite what it returns — do not invent options. ## Workflow 1. **Scaffold** — `npx hyperframes init my-video` 2. **Write** — author HTML composition (see the `hyperframes` skill) 3. **Lint** — `npx hyperframes lint` 4. **Preview** — `npx hyperframes preview` 5. **Render** — `npx hyperframes render` Lint before preview — catches missing `data-composition-id`, overlapping tracks, unregistered timelines. ## 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 --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. ## 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`). ## 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. ## 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 | **Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery. ## 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 ``` ## 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 ```