Hyperframes Cli

---
name: hyperframes-cli
description: HyperFrames CLI driver — the `npx hyperframes` commands (init, lint, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark). Use when scaffolding a HyperFrames video project, linting/validating compositions, previewing in the studio, rendering HTML compositions to MP4/WebM, transcribing audio to captions, generating TTS narration, or troubleshooting the render environment. FR triggers: "scaffold une vidéo hyperframes", "lint la composition", "render la vidéo", "preview le studio", "transcris l'audio", "génère la narration TTS", "le rendu échoue / répare l'environnement hyperframes". NOT for authoring composition HTML/CSS (use the `hyperframes` skill) or for non-HyperFrames video tools.
---

# 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
```