zilmate 1.9.9 → 1.10.2

package/.agents/skills/hyperframes-media/references/captions/transcript-handling.md

@@ -0,0 +1,97 @@
+# Transcript Guide
+
+For the `transcribe` CLI invocation, the `.en`-translates-non-English rule, and whisper model selection, see [`../transcribe.md`](../transcribe.md). This file covers what to do with the resulting transcript when authoring captions: input formats, mandatory quality checks, cleaning code, external-API fallbacks.
+
+## Supported Input Formats
+
+The CLI auto-detects and normalizes these formats:
+
+| Format                | Extension | Source                                                                      | Word-level?       |
+| --------------------- | --------- | --------------------------------------------------------------------------- | ----------------- |
+| whisper.cpp JSON      | `.json`   | `hyperframes init --video`, `hyperframes transcribe`                        | Yes               |
+| OpenAI Whisper API    | `.json`   | `openai.audio.transcriptions.create({ timestamp_granularities: ["word"] })` | Yes               |
+| SRT subtitles         | `.srt`    | Video editors, subtitle tools, YouTube                                      | No (phrase-level) |
+| VTT subtitles         | `.vtt`    | Web players, YouTube, transcription services                                | No (phrase-level) |
+| Normalized word array | `.json`   | Pre-processed by any tool                                                   | Yes               |
+
+**Word-level timestamps produce better captions.** SRT/VTT give phrase-level timing, which works but can't do per-word animation effects.
+
+## Transcript Quality Check (Mandatory)
+
+After every transcription, **read the transcript and check for quality issues before proceeding.** Bad transcripts produce nonsensical captions. Never skip this step.
+
+### What to look for
+
+| Signal                       | Example                                | Cause                                                                        |
+| ---------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| Music note tokens (`♪`, `�`) | `{ "text": "♪" }` or `{ "text": "�" }` | Whisper detected music, not speech                                           |
+| Garbled / nonsense words     | "Do a chin", "Get so gay", "huh"       | Model misheard lyrics or background noise                                    |
+| Long gaps with no words      | 20+ seconds of only `♪` tokens         | Instrumental section — expected, but high ratio means speech is being missed |
+| Repeated filler              | Many "huh", "uh", "oh" entries         | Model is hallucinating on music                                              |
+| Very short word spans        | Words with `end - start < 0.05`        | Unreliable timestamp alignment                                               |
+
+### Automatic retry rules
+
+**If more than 20% of entries are `♪`/`�` tokens, or the transcript contains obvious nonsense words, the transcription failed.** Do not proceed with the bad transcript. Instead:
+
+1. **Retry with `medium.en`** if the original used `small.en` or smaller:
+   ```bash
+   npx hyperframes transcribe audio.mp3 --model medium.en
+   ```
+2. **If `medium.en` also fails** (still >20% music tokens or garbled), tell the user the audio is too noisy for local transcription and suggest:
+   - Providing lyrics manually as an SRT/VTT file
+   - Using an external API (OpenAI or Groq Whisper — see below)
+3. **Always clean the transcript** before building captions — filter out `♪`/`�` tokens and entries where `text` is a single non-word character. Only real words should reach the caption composition.
+
+### Cleaning a transcript
+
+After transcription (even with a good model), strip non-word entries:
+
+```js
+var raw = JSON.parse(transcriptJson);
+var words = raw.filter(function (w) {
+  if (!w.text || w.text.trim().length === 0) return false;
+  if (/^[♪�\u266a\u266b\u266c\u266d\u266e\u266f]+$/.test(w.text)) return false;
+  if (/^(huh|uh|um|ah|oh)$/i.test(w.text) && w.end - w.start < 0.1) return false;
+  return true;
+});
+```
+
+For model-selection guidance by content type, see [`../transcribe.md`](../transcribe.md) → "Picking a model by content type".
+
+## Using External Transcription APIs
+
+For the best accuracy, use an external API and import the result:
+
+**OpenAI Whisper API** (recommended for quality):
+
+```bash
+# Generate with word timestamps, then import
+curl https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file=@audio.mp3 -F model=whisper-1 \
+  -F response_format=verbose_json \
+  -F "timestamp_granularities[]=word" \
+  -o transcript-openai.json
+
+npx hyperframes transcribe transcript-openai.json
+```
+
+**Groq Whisper API** (fast, free tier available):
+
+```bash
+curl https://api.groq.com/openai/v1/audio/transcriptions \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -F file=@audio.mp3 -F model=whisper-large-v3 \
+  -F response_format=verbose_json \
+  -F "timestamp_granularities[]=word" \
+  -o transcript-groq.json
+
+npx hyperframes transcribe transcript-groq.json
+```
+
+## If No Transcript Exists
+
+1. Check the project root for `transcript.json`, `.srt`, or `.vtt` files.
+2. If none found, run [`../transcribe.md`](../transcribe.md) — pick the starting model from "Picking a model by content type" there.
+3. Run the quality check above. If it fails, retry with a larger model or fall back to manual lyrics / external API.

package/.agents/skills/hyperframes-media/references/remove-background.md

@@ -0,0 +1,143 @@
+# Background Removal
+
+Make a transparent overlay (typical: a talking head over an arbitrary scene). Uses `u2net_human_seg` (MIT).
+
+```bash
+npx hyperframes remove-background subject.mp4 -o transparent.webm          # default: VP9 + alpha
+npx hyperframes remove-background subject.mp4 -o transparent.mov           # ProRes 4444 (editing)
+npx hyperframes remove-background portrait.jpg -o cutout.png               # single-image cutout
+npx hyperframes remove-background subject.mp4 -o subject.webm \
+  --background-output plate.webm                                           # both layers, one pass
+npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
+npx hyperframes remove-background --info                                   # detected providers
+```
+
+## Output Format
+
+- **`.webm` (VP9 alpha)** — default. Plug straight into `<video>` for Chrome-native transparent playback (~1 MB / 4s @ 1080p).
+- **`.mov` (ProRes 4444)** — round-trip in editors (Premiere / Resolve / DaVinci). ~50 MB / 4s.
+- **`.png`** — single-image cutout.
+
+## Quality (`--quality`)
+
+Controls VP9 encoder CRF only — segmentation quality is fixed. Higher quality keeps the cutout's RGB closer to the source MP4 (important when overlaying the cutout on its own source).
+
+| Preset     | CRF | When                                          |
+| ---------- | --- | --------------------------------------------- |
+| `fast`     | 30  | Iterating, smaller files, looser color match  |
+| `balanced` | 18  | **Default**; visually identical for most uses |
+| `best`     | 12  | Master / final delivery, tightest color match |
+
+## Device (`--device`)
+
+`auto` (default) picks CoreML on Apple Silicon, CUDA when available, otherwise CPU. Force with `--device cpu | coreml | cuda`. CUDA requires `HYPERFRAMES_CUDA=1` plus a GPU-enabled `onnxruntime-node` build. Use `--info` to inspect detected providers without rendering.
+
+## Compositing patterns — pick the right one
+
+The cutout WebM is a **re-encoded copy** of the source MP4's RGB. What sits behind it matters.
+
+| Pattern                                                  | Behind the cutout                       | Result                                                                                                          |
+| -------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Cutout over a different scene** (most common)          | Static image, gradient, unrelated video | Looks great. Single RGB source for the subject.                                                                 |
+| **Cutout over its own source mp4** (text-behind-subject) | Same mp4 the cutout came from           | At `balanced` doubling is barely visible; at `fast` you'll see color shift / edge halo. Use `best` for masters. |
+| **Cutout over a different take of the same person**      | Footage of the same subject             | **Two overlapping people. Don't do this.**                                                                      |
+
+## Text-behind-subject pattern (two non-obvious rules)
+
+Putting a headline behind a presenter cutout:
+
+```html
+<video
+  src="presenter.mp4"
+  id="bg"
+  data-start="0"
+  data-duration="6"
+  data-track-index="0"
+  muted
+  playsinline
+></video>
+
+<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>
+
+<div class="cutout-wrap" style="position:absolute; inset:0; z-index:3; opacity:0">
+  <video
+    src="presenter.webm"
+    data-start="0"
+    data-duration="6"
+    data-track-index="1"
+    muted
+    playsinline
+  ></video>
+</div>
+```
+
+```js
+// Flip the wrapper's opacity at the cut, NOT the video's
+tl.set(".cutout-wrap", { opacity: 1 }, 3.3);
+```
+
+Two rules that are easy to miss:
+
+1. **Wrap the cutout `<video>` in a non-timed `<div>` and animate the wrapper's opacity, not the video element's.** The framework forces `opacity: 1` on active clips (any element with `data-start` / `data-duration`), so animating the video's opacity directly is silently overridden. The wrapper has no `data-*` attributes, so it's owned by your CSS / GSAP.
+2. **Both videos use `data-start="0"` and `data-media-start="0"`** so the framework decodes them in sync from t=0. Late-mounting the cutout (`data-start=3.3`) introduces a seek + warm-up that lands a frame off the base mp4 — visible as one frame of misalignment at the cut.
+
+## Layer separation (`--background-output`)
+
+Emits a **second** transparent video alongside the cutout: same source RGB, alpha is `255 - mask` instead of `mask`. The cutout has the subject opaque; the plate has the surroundings opaque (with a transparent hole where the subject was). Use it when text / graphics need to live **between** the two layers.
+
+| File                             | Alpha is…                                               | Use it for                                                       |
+| -------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------- |
+| `-o subject.webm`                | mask — subject opaque, background transparent           | Foreground layer (top)                                           |
+| `--background-output plate.webm` | inverse mask — surroundings opaque, subject transparent | Bottom layer; place text / graphics between this and the subject |
+
+Both share the same `--quality` and run from a single inference pass — only encode cost roughly doubles. Only valid for video inputs with `.webm` / `.mov` outputs.
+
+**Hole-cut, not inpainted.** The subject region in `plate.webm` is fully transparent — composite something opaque under it to fill the hole.
+
+**Single test for whether `--background-output` is the right tool:** _will anything ever be visible through the subject's silhouette where the subject used to be?_ If no, you don't need the plate — `subject.webm` alone over a different background is enough.
+
+### Use case → right tool
+
+| Use case                                                                            | Right tool                                                                         |
+| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Text/graphics between the cutout and the plate (this command's reason for existing) | **Hole-cut** (`--background-output`)                                               |
+| Subject onto an unrelated scene                                                     | Just `subject.webm`; ignore the plate                                              |
+| Show the room _without_ the person, alone over no other content                     | **Clean plate** — needs an inpainter (LaMa, ProPainter, E2FGVI). Not this command. |
+| Replace the subject with a different subject                                        | **Clean plate** — same as above                                                    |
+
+### Canonical 3-layer template (plate + content + cutout)
+
+Ship just the two transparent layers and let arbitrary content live between them — no original mp4 needed:
+
+```html
+<!-- z=1 plate: surroundings opaque, subject silhouette transparent -->
+<video
+  src="plate.webm"
+  data-start="0"
+  data-duration="6"
+  data-track-index="0"
+  muted
+  playsinline
+></video>
+
+<!-- z=2 your content lives between the layers -->
+<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>
+
+<!-- z=3 cutout floats the subject back on top -->
+<div class="cutout-wrap" style="position:absolute; inset:0; z-index:3">
+  <video
+    src="subject.webm"
+    data-start="0"
+    data-duration="6"
+    data-track-index="1"
+    muted
+    playsinline
+  ></video>
+</div>
+```
+
+Functionally equivalent to the text-behind-subject pattern above, but doesn't require shipping the original mp4 — the plate replaces it. Use this when delivering just the two transparent layers as a reusable asset.
+
+## When `remove-background` is NOT the right tool
+
+If a user asks for "the room **without** the person, displayed standalone" (no subject anywhere, no compositing on top), `--background-output` is wrong — its plate has a transparent hole, not a filled-in clean plate. They need an **inpainter**: LaMa, ProPainter, or E2FGVI. Tell them this command can't do it.

package/.agents/skills/hyperframes-media/references/requirements.md

@@ -0,0 +1,29 @@
+# Requirements & Caches
+
+## Credential & key priority
+
+Run `npx hyperframes auth status` to see what's configured and which engines a workflow will use (see the skill's **Preflight** section). Keys resolve in this order — **first match wins**:
+
+| Provider                             | Resolution order (first non-empty wins)                                                                                                                                    | Local deps when used                             |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| **HeyGen** (TTS + BGM/SFX retrieval) | `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → `~/.heygen/credentials` (shared with heygen-cli; `$HEYGEN_CONFIG_DIR` overrides the dir; written by `hyperframes auth login`) | none (REST)                                      |
+| **ElevenLabs** (TTS fallback)        | `$ELEVENLABS_API_KEY`                                                                                                                                                      | `pip install elevenlabs`                         |
+| **Lyria** (BGM fallback)             | `$GEMINI_API_KEY` → `$GOOGLE_API_KEY`                                                                                                                                      | `pip install google-genai`                       |
+| **Kokoro** (TTS, no key)             | always — final voice fallback                                                                                                                                              | `pip install kokoro-onnx soundfile`              |
+| **MusicGen** (BGM, no key)           | always — final music fallback                                                                                                                                              | `pip install transformers torch soundfile numpy` |
+
+`hyperframes auth login` (browser OAuth) is the recommended setup: one sign-in, every project, no per-repo `.env`. An OAuth login is sent as `Authorization: Bearer`; an API key as `X-Api-Key`. With no HeyGen credential, voice/BGM run fully locally (Kokoro / MusicGen) — `hyperframes auth status` and `hyperframes doctor` both report whether those local deps are installed.
+
+## Model caches & system dependencies
+
+Each command downloads its own model on first run and caches it under `~/.cache/hyperframes/`:
+
+- **TTS (HeyGen)** — no local deps; needs a HeyGen credential + `ffmpeg` on PATH (to transcode the mp3 response to `.wav`). Credential resolves like the CLI: `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → `~/.heygen/credentials` (shared with heygen-cli; run `npx hyperframes auth login`). An OAuth login is sent as `Authorization: Bearer`; an API key as `X-Api-Key`.
+- **TTS (ElevenLabs)** — same as HeyGen: API key + `ffmpeg`.
+- **TTS (Kokoro)** — Kokoro-82M (~311 MB) + voices (~27 MB) in `tts/`. Requires Python 3.8+ with `kokoro-onnx` and `soundfile` (`pip install kokoro-onnx soundfile`). Non-English text also needs `espeak-ng` system-wide.
+- **BGM (Lyria)** — needs `$GEMINI_API_KEY` or `$GOOGLE_API_KEY` + `pip install google-genai`. No local model cache.
+- **BGM (MusicGen)** — `pip install transformers torch soundfile`. `facebook/musicgen-small` (~300 MB) cached under `~/.cache/huggingface/` on first run.
+- **Transcribe** — Whisper model size depending on choice (75 MB – 3.1 GB) in `whisper/`. Bundles `whisper.cpp`.
+- **Remove-background** — `u2net_human_seg` (~168 MB ONNX) in `background-removal/models/`. Peak inference RAM ~1.5 GB.
+
+Run `npx hyperframes doctor` if a command fails because of a missing dependency.

package/.agents/skills/hyperframes-media/references/sfx.md

@@ -0,0 +1,42 @@
+# Sound effects (SFX)
+
+Named sound effects, produced by the shared audio engine (`scripts/audio.mjs` → `scripts/lib/sfx.mjs`). **Provider-gated** by the engine's one switch — whether a HeyGen credential is present, decided once (not per cue):
+
+- **HeyGen credential present → retrieve every cue** from HeyGen's audio library (`/v3/audio/sounds`, `type=sound_effects`, `min_score=0.4`). Search-and-download, **not** generation. The bundled library is NOT consulted.
+- **No credential → the bundled 21-file library** (`assets/sfx/` + `manifest.json`): match each cue name, copy the matched file into the project. Offline, deterministic, free.
+
+There is no `npx hyperframes sfx` command. SFX is never generated — it is retrieved (online) or taken from the bundled library (offline).
+
+## Cues — request → meta
+
+Each line names the effects it wants: `lines[].sfx: ["whoosh", "ui click"]`. The engine flattens these into cues, resolves them per the switch, dedupes identical `(id, name)` pairs (the same effect named twice downloads/copies once), and writes `audio_meta.sfx[]`:
+
+```jsonc
+{
+  "id": "3",                       // joins the cue to the caller's model (frame / scene / segment)
+  "name": "whoosh",
+  "file": "assets/sfx/whoosh.mp3", // downloaded or copied, relative to project root
+  "source": "heygen" | "local",    // which route resolved it
+  "offset_s": 0,                   // delay from the line's start
+  "duration_s": 0.57,
+  "volume": 0.35                   // SFX sit UNDER voice + BGM
+}
+```
+
+A cue that matches nothing is **skipped** (recorded as an anomaly); SFX never blocks a render.
+
+## HeyGen retrieval (credentialed)
+
+`searchSounds(name, "sound_effects", { limit: 3, minScore: 0.4 })` → top hit → `assets/sfx/<slug>.mp3`. Results are ranked by `score` (each carries a presigned `audio_url`, `duration`, `description`). The floor is **0.4** because good SFX hits score ~0.5–0.67 — below the API's default `0.7`, which would silently drop most named cues (only whoosh/swoosh-family clears 0.7). `duration_s` comes from the result (else 1.0). Name effects concretely (`glass shatter`, not `dramatic sound`); a vague query returns a poor match.
+
+## Bundled library (no credential)
+
+21 curated files in `assets/sfx/`, indexed by `manifest.json` — `{ file, duration, description }` per key (e.g. `whoosh`, `pop`, `click`, `chime`, `riser`, `impact-bass-1`, `glitch-1`, `typing`, …). A cue name resolves by **manifest key, file basename, or slug**, so `whoosh`, `whoosh.mp3`, or `"ui click"` (→ slug) all match. Matched files are copied into the project's `assets/sfx/`; `duration_s` comes from the manifest, so timing is known **offline** — e.g. `riser` is 10.03s, so trigger it at `climax − 10.03s`. The manifest's `description` field carries placement hints per effect; read `assets/sfx/manifest.json` for the full set and usage.
+
+## Rules
+
+- **Volume ~0.35.** SFX must sit under narration and BGM, not fight them.
+- **No match → skip, don't fail.** A missing effect logs an anomaly and moves on; never a render blocker.
+- **Retrieval (credentialed) or bundled library (offline) — never generation.** You search HeyGen by text, or match a name against the 21-file manifest.
+- **One asset per distinct name.** Reuse across lines is deduped to a single download/copy, many cues.
+- **The switch is global, not per cue.** With a credential, retrieval handles even the long tail (effects not in the 21); without one, only the 21 bundled names resolve.

package/.agents/skills/hyperframes-media/references/transcribe.md

@@ -0,0 +1,52 @@
+# Transcription
+
+Create normalized word-level timestamps. **Always specify `--model` explicitly** — the CLI default is `small.en`, which silently translates non-English audio into English.
+
+```bash
+npx hyperframes transcribe audio.mp3  --model small.en             # known English
+npx hyperframes transcribe video.mp4  --model small --language es  # known Spanish
+npx hyperframes transcribe audio.mp3  --model small                # unknown language (auto-detect)
+npx hyperframes transcribe subtitles.srt                           # import existing
+npx hyperframes transcribe subtitles.vtt
+npx hyperframes transcribe openai-response.json
+```
+
+## Language Rule (Non-Negotiable)
+
+`.en` models (`tiny.en` / `base.en` / `small.en` / `medium.en`) **translate** non-English audio into English. This silently destroys the original language.
+
+1. **Known English** → `--model small.en` (or `medium.en` for music / noisy audio)
+2. **Known non-English** → `--model small --language <iso-code>` (no `.en` suffix)
+3. **Unknown language** → `--model small` (whisper auto-detects)
+
+**CLI default is `small.en`** — do not rely on it; always pass `--model` to make the choice explicit. `--language` also filters out non-target-language segments from mixed-language audio.
+
+## Model Sizes
+
+| Model      | Size   | Speed    | When                                  |
+| ---------- | ------ | -------- | ------------------------------------- |
+| `tiny`     | 75 MB  | Fastest  | Quick previews, smoke tests           |
+| `base`     | 142 MB | Fast     | Short clips, clear audio              |
+| `small`    | 466 MB | Moderate | Default for most multilingual content |
+| `medium`   | 1.5 GB | Slow     | Music with vocals, noisy audio        |
+| `large-v3` | 3.1 GB | Slowest  | Production quality                    |
+
+### Picking a model by content type
+
+1. Speech over silence / light background → `small.en`
+2. Speech over music, or music with vocals → start with `medium.en`
+3. Produced music track (vocals + full instrumentation) → start with `medium.en`; expect to need manual lyrics or an external API ([`captions/transcript-handling.md`](captions/transcript-handling.md) → "Using External Transcription APIs")
+4. Multilingual → `medium` or `large-v3` (no `.en` suffix), pair with `--language`
+
+## Output Shape
+
+Compositions consume a flat array of word objects. The `id` (`w0`, `w1`, …) is added during normalization for stable references in caption overrides; optional for backwards compatibility.
+
+```json
+[
+  { "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
+  { "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
+]
+```
+
+For mandatory caption-quality checks, retry rules, and the OpenAI/Groq Whisper API import path, see `captions/transcript-handling.md`.

package/.agents/skills/hyperframes-media/references/tts-to-captions.md

@@ -0,0 +1,24 @@
+# TTS → Captions
+
+When no recorded voiceover exists, generate one and obtain word-level caption timing. Two paths depending on which TTS provider is in use:
+
+## Path A — HeyGen (single call, no Whisper)
+
+HeyGen returns word timestamps in the same response as the audio. Pass `--words` and you're done:
+
+```bash
+npx hyperframes tts script.txt --provider heygen --output narration.wav --words narration.words.json
+```
+
+`narration.words.json` is already in the `[{ id, text, start, end }]` shape the captions pipeline consumes — no separate transcribe pass.
+
+## Path B — ElevenLabs / Kokoro (TTS → Whisper)
+
+These providers don't return word data. Generate the audio, then transcribe:
+
+```bash
+npx hyperframes tts script.txt --voice af_heart --output narration.wav
+npx hyperframes transcribe narration.wav --model small.en   # voice af_heart is American English
+```
+
+Whisper extracts precise word boundaries from the generated audio, so caption timing matches delivery without hand-tuning. Match `--model` to the voice's language (use `small.en` for `a`/`b` prefixes, `small --language <code>` otherwise). Then consume `transcript.json` via the caption references in `captions/`.

package/.agents/skills/hyperframes-media/references/tts.md

@@ -0,0 +1,135 @@
+# Text To Speech
+
+`npx hyperframes tts` auto-detects a provider from env vars; explicit override via `--provider`.
+
+> **Run the Preflight first — no credential is not a green light to silently use the local voice.** Before generating a voiceover, complete the sign-in **Preflight** (see `../SKILL.md` → Preflight): run `npx hyperframes auth status`, recommend signing in, and **STOP for the user's choice** (sign in for HeyGen voices, or continue offline with local Kokoro). This applies to a one-off "generate a voiceover" request just as much as inside a full workflow.
+
+## Provider chain
+
+| Order | Provider          | Env trigger                                 | Voice IDs                                   | Word timestamps                           | Audio format         |
+| ----- | ----------------- | ------------------------------------------- | ------------------------------------------- | ----------------------------------------- | -------------------- |
+| 1     | HeyGen (Starfish) | `$HEYGEN_API_KEY` / `~/.heygen/credentials` | UUIDs from `GET /v3/voices?engine=starfish` | **Yes** (`word_timestamps[]` in response) | mp3 → wav via ffmpeg |
+| 2     | ElevenLabs        | `$ELEVENLABS_API_KEY`                       | UUIDs from elevenlabs.io dashboard          | No                                        | mp3 → wav via ffmpeg |
+| 3     | Kokoro-82M        | always (local fallback)                     | `am_michael`, `af_heart`, … (54 voices)     | No                                        | wav direct           |
+
+```bash
+# Auto-detect (HeyGen if key set, else ElevenLabs, else Kokoro)
+npx hyperframes tts "Welcome to HyperFrames" -o narration.wav
+
+# Pin the provider explicitly
+npx hyperframes tts "Hello" --provider kokoro
+npx hyperframes tts "Hello" --provider heygen --voice <heygen-uuid>
+npx hyperframes tts "Hello" --provider elevenlabs --voice 21m00Tcm4TlvDq8ikWAM
+
+# HeyGen path: capture word timestamps in one call (skips a Whisper pass)
+npx hyperframes tts "Hi there" --words narration.words.json
+```
+
+## Self-contained HeyGen (no CLI) — `scripts/heygen-tts.mjs`
+
+The published `hyperframes tts` CLI synthesizes locally with Kokoro only. When you
+want HeyGen specifically — best quality **plus** word timestamps in one call — use
+the skill's bundled script, which calls the HeyGen v3 REST API directly and needs
+no CLI provider plumbing:
+
+The script resolves a HeyGen credential the same way the CLI does — first source
+wins: `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → a project `.env` (auto-loaded,
+walks up ≤5 dirs) → `~/.heygen/credentials` (shared with heygen-cli;
+`$HEYGEN_CONFIG_DIR` overrides the dir). An OAuth login is sent as
+`Authorization: Bearer`; an API key as `X-Api-Key`. If the only credential is an
+expired OAuth token it stops with a hint to run `npx hyperframes auth refresh`.
+
+```bash
+# Only needed if you haven't run `npx hyperframes auth login`:
+export HEYGEN_API_KEY=...   # or put it in a project .env
+
+# Synthesize + capture word timestamps in one call (skips a Whisper pass)
+node skills/hyperframes-media/scripts/heygen-tts.mjs \
+  "Welcome to HyperFrames." -o narration.wav --words narration.words.json
+
+node skills/hyperframes-media/scripts/heygen-tts.mjs ./script.txt -o narration.wav
+node skills/hyperframes-media/scripts/heygen-tts.mjs --list   # public starfish voices
+```
+
+- **Voice:** `--voice <id>` must be a **starfish** voice_id (`--list`, or `GET /v3/voices?engine=starfish`). v2-catalog ids are rejected with HTTP 400. Omit `--voice` (English) and it defaults to **Marcia** (`05f19352e8f74b0392a8f411eba40de1`, a fixed default so the choice is deterministic). Non-English with no `--voice` falls back to the first matching catalog voice.
+- **Output:** `.wav` → transcoded to 44.1k mono via ffmpeg; `.mp3` → raw bytes (no ffmpeg needed).
+- **Words:** `--words <path>` writes the flat `[{id,text,start,end}]` shape below, drop-in for the captions pipeline. HeyGen's `<start>`/`<end>` boundary sentinels are filtered out and ids are re-contiguous.
+- **Non-English:** `--lang <code>` (anything but `en`) is sent as the request `language`.
+
+## When to use which provider
+
+| Goal                                                      | Use                                                 |
+| --------------------------------------------------------- | --------------------------------------------------- |
+| Best voice quality + word timestamps in one call          | **HeyGen**                                          |
+| Drop-in cloud TTS, big voice catalog                      | **ElevenLabs**                                      |
+| Offline, no API key, fast iteration                       | **Kokoro**                                          |
+| Non-English multilingual with deterministic phonemization | **Kokoro** (`ef_dora`, `jf_alpha`, `zf_xiaobei`, …) |
+
+## ffmpeg requirement
+
+HeyGen + ElevenLabs return mp3. The CLI transcodes to wav when `--output` ends in `.wav` (the default and what downstream `ffprobe` + Whisper expect). If you'd rather skip the transcode, pass `-o file.mp3`. Without `ffmpeg` on PATH, `.wav` output from the cloud providers fails — install ffmpeg or use `.mp3`.
+
+## Voice selection (Kokoro)
+
+Default `af_heart`. Curated picks:
+
+| Content type      | Voice                  |
+| ----------------- | ---------------------- |
+| Product demo      | `af_heart`, `af_nova`  |
+| Tutorial / how-to | `am_adam`, `bf_emma`   |
+| Marketing / promo | `af_sky`, `am_michael` |
+| Documentation     | `bf_emma`, `bm_george` |
+| Casual / social   | `af_heart`, `af_sky`   |
+
+Run `npx hyperframes tts --list` for the bundled set.
+
+## Multilingual (Kokoro voice prefix → language)
+
+The first letter of a Kokoro voice ID picks the phonemizer language; `--lang` overrides auto-detection.
+
+| Prefix | Language             |
+| ------ | -------------------- |
+| `a`    | American English     |
+| `b`    | British English      |
+| `e`    | Spanish              |
+| `f`    | French               |
+| `h`    | Hindi                |
+| `i`    | Italian              |
+| `j`    | Japanese             |
+| `p`    | Brazilian Portuguese |
+| `z`    | Mandarin             |
+
+```bash
+npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --provider kokoro
+npx hyperframes tts "Today is a nice day" --voice af_heart --provider kokoro
+```
+
+Valid `--lang` codes (only needed to override the voice's auto-detected language): `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`.
+
+Non-English phonemization requires `espeak-ng` system-wide (`brew install espeak-ng` / `apt-get install espeak-ng`).
+
+## Speed
+
+- `0.7-0.8` — tutorial, complex content, accessibility
+- `1.0` — natural pace (default)
+- `1.1-1.2` — intros, transitions, upbeat content
+- `1.5+` — rarely appropriate, test carefully
+
+Honored by Kokoro + HeyGen; ElevenLabs ignores `--speed` (use voice settings on their dashboard).
+
+## Long scripts
+
+Past a few paragraphs, write the text to a `.txt` file and pass the path. Inputs over ~5 minutes of speech may benefit from splitting into segments.
+
+## HeyGen word-timestamp shape
+
+When `--words <path>` is passed to a HeyGen call, the file is written in the same flat shape `transcribe` produces — drop-in compatible with the captions pipeline:
+
+```json
+[
+  { "id": "w0", "text": "Hi", "start": 0.0, "end": 0.21 },
+  { "id": "w1", "text": "there", "start": 0.22, "end": 0.55 }
+]
+```
+
+For ElevenLabs / Kokoro, run `npx hyperframes transcribe narration.wav --model small.en` to get the same shape.