Hermes-agent

2026-06-14 14:30:48 -04:00
commit dac4b88b94
5058 changed files with 1884848 additions and 0 deletions
@@ -0,0 +1,185 @@
+# HyperFrames CLI
+
+Everything runs through `npx hyperframes` (or the globally-installed `hyperframes` after `npm install -g hyperframes`). Requires Node.js >= 22 and FFmpeg.
+
+## Workflow
+
+1. **Scaffold** — `npx hyperframes init my-video` (or `npx hyperframes capture <url>` if starting from a website)
+2. **Write** — author HTML composition (see `composition.md`)
+3. **Lint** — `npx hyperframes lint`
+4. **Validate** — `npx hyperframes validate` (WCAG contrast audit)
+5. **Inspect** — `npx hyperframes inspect` (visual layout audit)
+6. **Preview** — `npx hyperframes preview`
+7. **Render** — `npx hyperframes render`
+
+Always lint before preview/render — catches missing `data-composition-id`, overlapping tracks, and unregistered timelines.
+
+## init — Scaffold a Project
+
+```bash
+npx hyperframes init my-video                        # interactive wizard
+npx hyperframes init my-video --example warm-grain   # pick an example template
+npx hyperframes init my-video --video clip.mp4       # seed with a video file
+npx hyperframes init my-video --audio track.mp3      # seed with an audio file
+npx hyperframes init my-video --non-interactive      # skip prompts (CI / agent use)
+```
+
+Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
+
+`init` creates the correct file structure, copies media, transcribes audio with Whisper, and installs authoring skills. Use it instead of creating files by hand.
+
+## capture — Website → Editable Components
+
+```bash
+npx hyperframes capture https://example.com                  # → captures/example.com/
+npx hyperframes capture https://stripe.com -o stripe-video   # custom output dir
+npx hyperframes capture https://example.com --json           # machine-readable output
+npx hyperframes capture https://example.com --skip-assets    # skip images/SVGs
+```
+
+Captures the site into `captures/<hostname>/capture/` by default, producing `capture/screenshots/`, `capture/assets/`, `capture/extracted/` (tokens.json, visible-text.txt, fonts.json), and a self-contained snapshot.
+
+All downstream steps (DESIGN.md, SCRIPT.md, STORYBOARD, composition) read from the `capture/` subfolder — see `website-to-video.md`.
+
+## lint
+
+```bash
+npx hyperframes lint                # current directory
+npx hyperframes lint ./my-project   # specific project
+npx hyperframes lint --verbose      # include info-level findings
+npx hyperframes lint --json         # machine-readable output
+```
+
+Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (only with `--verbose`).
+
+## validate
+
+```bash
+npx hyperframes validate                 # WCAG contrast audit at 5 timestamps
+npx hyperframes validate --no-contrast   # skip while iterating
+```
+
+Seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and warns on contrast ratios below 4.5:1 (normal text) or 3:1 (large text — 24px+, or 19px+ bold). Run before final render.
+
+## inspect
+
+```bash
+npx hyperframes inspect                 # visual layout audit at 5 timestamps
+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. Reports overflow, off-frame elements, occluded text, contrast warnings, and per-timestamp layout summaries — catches issues that pure timeline lint can't see (e.g., a caption that wraps past the safe area only at a specific timestamp).
+
+`npx hyperframes layout` is a compatibility alias for the same visual inspection pass.
+
+## preview
+
+```bash
+npx hyperframes preview                # serve current directory (port 3002)
+npx hyperframes preview --port 4567    # custom port
+```
+
+Hot-reloads on file changes. Opens the Studio in your browser automatically.
+
+## render
+
+```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 reproducible render
+```
+
+| 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.
+
+## transcribe
+
+```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
+```
+
+Produces word-level timings suitable for caption components. First run downloads the Whisper model (cached after).
+
+## tts
+
+```bash
+npx hyperframes tts "Text here" --voice af_nova --output narration.wav
+npx hyperframes tts script.txt --voice bf_emma
+npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
+npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
+npx hyperframes tts --list                    # show all voices
+```
+
+Uses Kokoro (local, no API key). Voice ID first letter encodes language: `a` American English, `b` British English, `e` Spanish, `f` French, `h` Hindi, `i` Italian, `j` Japanese, `p` Brazilian Portuguese, `z` Mandarin. The CLI auto-infers the phonemizer locale from that prefix — pass `--lang` only to override (e.g. stylized accents). Valid `--lang` codes: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`. Non-English phonemization requires `espeak-ng` installed system-wide (`apt-get install espeak-ng` / `brew install espeak-ng`).
+
+## doctor
+
+```bash
+npx hyperframes doctor
+```
+
+Verifies environment:
+- Node.js >= 22
+- FFmpeg present on PATH
+- Available RAM (renders are memory-hungry — 4 GB minimum)
+- Chrome binary resolution (`chrome-headless-shell` preferred over system Chrome)
+- Current `hyperframes` version
+
+Run this **first** when a render fails. See `troubleshooting.md` for interpreting the output.
+
+## browser
+
+```bash
+npx hyperframes browser --install      # install the bundled chrome-headless-shell
+npx hyperframes browser --path         # print the resolved browser binary path
+npx hyperframes browser --clean        # clear the bundled browser cache
+```
+
+## info
+
+```bash
+npx hyperframes info
+```
+
+Prints version, Node version, FFmpeg version, OS, and resolved browser path — useful in bug reports.
+
+## upgrade
+
+```bash
+npx hyperframes upgrade -y
+```
+
+Check for and install updates. Run this if you hit `HeadlessExperimental.beginFrame` errors — the auto-detect fix shipped in `hyperframes@0.4.2` (commit 4c72ba4, March 2026).
+
+## Other
+
+```bash
+npx hyperframes compositions    # list compositions in the project
+npx hyperframes docs            # open documentation in browser
+npx hyperframes benchmark .     # benchmark render performance
+npx hyperframes add <block>     # install a block/component from the catalog
+npx hyperframes add --list      # browse the catalog
+```
+
+Popular catalog blocks: `flash-through-white` (shader transition), `instagram-follow` (social overlay), `data-chart` (animated chart), `lower-third` (talking-head overlay). See [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog).