takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/hyperframes-media/references/sfx.md

@@ -1,42 +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.
+# 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/assets/.agent/skills/hyperframes-media/references/transcribe.md

@@ -1,52 +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`.
+# 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/assets/.agent/skills/hyperframes-media/references/tts-to-captions.md

@@ -1,24 +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/`.
+# 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/assets/.agent/skills/hyperframes-media/references/tts.md

@@ -1,135 +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.
+# 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.