takomi 2.5.1 → 2.5.4

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

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

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

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