hyperframes 0.8.183 → 0.8.185

package/dist/skills/media-use/SKILL.md

@@ -1,104 +1,60 @@
 ---
 name: media-use
-description: Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm` needs the heygen CLI, while `--type sfx` needs no account (Openverse, then a bundled library). When `HEYGEN_API_BASE` is set, HeyGen calls go through that host with no CLI sign-in.
+description: Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.
 ---
 
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.
 
-# media-use
+# Media in HyperFrames
 
-The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.
+Media lands as a local file in the project's `assets/` with a ledger record; renders never fetch. One verb finds or makes it:
 
-Only when `HEYGEN_API_BASE` is set in your environment (a host app set it and pays for HeyGen with its own key): HeyGen media is already paid for. Do not ask the person to install or sign in to the `heygen` CLI and do not offer its OAuth allowance; catalog search, TTS and avatar calls here go through the host. When that same host also gives you its own HeyGen tools, use those first. When a call through the host is refused, tell the person the host's message as written (it names the fix, such as adding or replacing the key in the app's Settings) and stop; do not switch to another provider unless they ask.
+```bash
+npx hyperframes media-use resolve --type <type> --intent "<what you need>" --project <dir>
+```
 
-First run otherwise (no `HEYGEN_API_BASE`), when you will use HeyGen media (catalog search, TTS, avatar video): install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
+It prints one line, `resolved <id> → <path> (<type>, <metadata>)`. List reusable assets first with `--candidates` and judge the fit yourself; reuse, ingest (`--from`) and adopt are in `references/resolve.md`.
 
-Music and sound effects inside a host app: when the app you run in gives you its own music or sound-effect tools, use those. Without `HEYGEN_API_BASE`, `resolve --type bgm` searches the HeyGen catalog through the `heygen` CLI and fails without it, saying so. `resolve --type sfx` searches Openverse (CC0 and CC BY only, no account) and falls back to its bundled library offline; credit CC BY sounds as `audio/references/sfx.md` says.
+## Two ways to get it
 
-Without `HEYGEN_API_BASE`, before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
+| Need | HeyGen (best quality) | Free, no account |
+| --- | --- | --- |
+| Music (`bgm`) | Catalog of 10k+ tracks | Local MusicGen (`audio/references/bgm.md`) |
+| Sound effects (`sfx`) | | Openverse; 21 bundled offline |
+| Images, icons | Asset search, 75k+ | Local FLUX (mflux), if installed |
+| Logos (`logo`) | | theSVG, GitHub avatar, favicon; never redrawn |
+| Voiceover (`voice`) | HeyGen voices, voice cloning | `npx hyperframes tts` (Kokoro on device; Python 3.10+ with `pip install kokoro-onnx soundfile`) |
+| A presenter speaking | Avatar video (`--type video`) | Local LTX for generic clips, if installed |
+| Transcripts | | `npx hyperframes transcribe` (Parakeet or whisper) |
+| Cutouts | `heygen background-removal` | `npx hyperframes remove-background` |
+| Grades, LUTs, looks | | `npx hyperframes media-treatment` |
 
-## Resolve — the one verb
+**Host apps.** Inside an app that gives you its own media tools, use those first. When `HEYGEN_API_BASE` is set, the host pays for HeyGen: don't ask for the `heygen` CLI or a sign-in, and when a call is refused, relay the host's message as written and stop.
 
-```bash
-npx hyperframes media-use resolve --type <type> --intent "<description>" --project <dir>
-```
+**HeyGen.** Install the [`heygen` CLI](https://developers.heygen.com/cli) and sign in with `heygen auth login --oauth`: the OAuth session carries a free allowance on subscription credits; an API key (`--api-key`) bills API credits. Check setup with `npx hyperframes media-use resolve --doctor`. When a request needs HeyGen (a presenter or avatar, a HeyGen voice, catalog music) and `heygen` is missing or signed out, tell the person how to get it: the install link, `heygen auth login --oauth` for the free allowance, or an API key for credits. Then offer the free path or wait. Beyond `resolve`, the same CLI makes text-to-video (`heygen video-agent create`), avatar videos with a recorded track (`heygen video create`), cloned voices (`heygen voice clone create`), dubbing (`heygen lipsync`), translated videos (`heygen video-translate`) and short clips from a long video (`heygen ai-clipping`): recipes in `references/operations.md`.
+
+**Free.** Every tool in the free column needs no account; local models are opt-in installs (`references/setup-providers.md`). Without `heygen`, `resolve` for music, images and icons fails and says so; credit CC BY sounds (`audio/references/sfx.md`). `--local-only` skips every network provider.
+
+**Cost.** Confirm before a paid call you chose to make (an avatar video counts); one the person asked for just runs. `--provider <name>` pins one generator when the person names it.
+
+## Looks on real footage
+
+Feedback that footage is dark, flat or dull, should feel retro or printed, needs a face hidden, or needs a reveal is media intent: read `references/media-treatments.md`. Inspect the real `<img>`/`<video>`, pick one intent, start from `npx hyperframes media-treatment --capabilities --json`, then `--capability <id>`; never `--all`. Persist the final treatment with `npx hyperframes media-treatment`; no CSS or SVG stand-ins for supported effects, and no generated `.cube` just to encode exposure or warmth.
+
+## Offer once, never add silently
+
+When you build or review a piece, scan once for concrete gaps (on-screen text with no voiceover, emoji standing in for icons, placeholder images, silent cuts, 10 s+ with no music, a colour cast) and offer the specific fixes in one ask. No signal, no suggestion; respect "leave it".
+
+## Where to look
 
-Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search noise stays on disk.
-
-| Type    | One-line intent                                                                  |
-| ------- | -------------------------------------------------------------------------------- |
-| `bgm`   | background music (HeyGen catalog via the `heygen` CLI, 10k+ tracks)              |
-| `sfx`   | sound effects (Openverse CC0 / CC BY, bundled 21-file library offline)           |
-| `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                          |
-| `icon`  | icons, symbols (transparent)                                                     |
-| `logo`  | official brand marks (theSVG → GitHub avatar → favicon; never redrawn)           |
-| `voice` | TTS voiceover (HeyGen free-usage path; optional local Kokoro)                    |
-| `grade` | measured correction candidate; broad polish/stylization follows Media Treatments |
-| `lut`   | user-provided or explicitly chosen reusable validated `.cube` file               |
-
-Before resolving fresh, list reusable candidates with `--candidates` and judge fit yourself — reuse rules, all flags, ingest (`--from`), and adopt are in `references/resolve.md`.
-
-## Treat broad visual feedback as media intent
-
-When a user explicitly asks to fix, polish, stylize, obscure, emphasize, or
-reveal photographic media, read `references/media-treatments.md` even if they
-do not name color grading or an effect. Inspect the real `<img>`/`<video>`,
-choose one primary intent, then use deterministic persistence and verification.
-Use a matching recipe as an optional tested seed, or inspect
-`hyperframes media-treatment --capabilities --json`, then request one relevant
-family/effect with `--capability <id>` and assemble a custom treatment from
-canonical controls. Never load `--all` for ordinary authoring. A treatment may
-compose correction, a preset, finishing, compatible shader effects, supported
-keyframes, and optional Registry overlays. Add only source-justified bounded
-tuning and compatible parts, never effects merely to make the result look more
-sophisticated. Persist the final combined payload with
-`hyperframes media-treatment`.
-
-Use one progressively escalating workflow. For video, inspect one labeled
-early/middle/late contact sheet rather than reading frames separately. Apply one
-candidate and inspect one after-sheet for ordinary correction or polish.
-Escalate to individual frames or moving draft evidence only when the result is
-ambiguous, temporal, stylized, LUT-based, HDR/LOG-sensitive, private, or
-brand-critical.
-
-For ordinary correction or polish, persist the final treatment's
-preset/adjustment JSON.
-Do not generate a `.cube` LUT merely to encode exposure, shadows, contrast, or
-warmth. Use a LUT only when the user supplies one or the selected treatment
-explicitly owns one. `resolve --type grade --for ... --analyze` is measurement
-evidence, not permission to replace the chosen treatment with a generated LUT.
-Do not recreate supported vignette, grain, blur, pixelate, color, or treatment
-effects with CSS/SVG overlays; that bypasses Studio controls and the canonical
-preview/render shader path.
-
-## Be proactive — run a media opportunity pass
-
-The human usually can't tell which media would lift the piece. You can. When you build or review a composition, do **one** grounded scan and then **ask once** — don't silently add, and don't nag per asset.
-
-Surface an opportunity only when a concrete signal is present:
-
-| Signal detected                                          | Offer                                                                                                  |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| On-screen text / a script with no voiceover              | TTS voiceover (audio engine)                                                                           |
-| Emoji or a `<div>` styled as an icon                     | resolve real `icon`s                                                                                   |
-| Image that is a placeholder, tiny, or upscaled-looking   | a better `image` (and/or upscale — see `references/operations.md`)                                     |
-| Hard scene cuts / transitions with no sound              | transition `sfx`                                                                                       |
-| A piece over ~10s with no music bed                      | `bgm`                                                                                                  |
-| Footage that reads under/over-exposed or color-cast      | a corrective grade (inspect it with `hyperframes media-treatment --selector '#hero' --analyze --json`) |
-| Photographic media that feels visually flat or off-topic | one specific source-appropriate preset or custom treatment, with the intended target named             |
-| A meaningful media entrance/reveal that feels static     | one supported seek-safe treatment animation; preserve color unless the request also justifies a preset |
-
-Rules that keep this a help, not nagware: **grounded, not generic** (no signal → no suggestion); **opinionated + concrete** (propose the specific fix with defaults chosen — the human approves **all / some / none**); **once per project** (one consolidated ask; respect "leave it"); **surface, never silently mutate** (color grades especially: propose and preview — a gray-world "correction" ruins an intentional sunset or neon look).
-
-## Where to look — read only the file your task needs
-
-| Task                                                                      | Read                             |
-| ------------------------------------------------------------------------- | -------------------------------- |
-| resolve / reuse / adopt / ingest, flags, cascade, inventory               | `references/resolve.md`          |
-| color grading, LUTs, smart grade (`--for`), grade-compare                 | `references/grading.md`          |
-| voiceover / TTS, music, SFX, captions, transcription (audio engine)       | `references/audio.md`            |
-| cut / reframe / transform existing media, exact error diffusion, HEVC     | `references/operations.md`       |
-| source-aware creative treatments, realtime effects, overlays, reveals     | `references/media-treatments.md` |
-| install + auth, provider table, RAM ladders, `--local-only`, `--provider` | `references/setup-providers.md`  |
-| remembered preferences + frozen recipes (user memory)                     | `references/memory.md`           |
-| ownership matrix, usage stats, telemetry, privacy (maintainer-facing)     | `references/meta.md`             |
+| Task | Read |
+| --- | --- |
+| Resolve, reuse, adopt, ingest, flags | `references/resolve.md` |
+| Grading, LUTs, `grade-compare` | `references/grading.md` |
+| Voiceover, music, sound effects, captions, transcription | `references/audio.md` |
+| Cut, reframe or transform media; HeyGen recipes | `references/operations.md` |
+| Treatments, realtime effects, overlays, reveals | `references/media-treatments.md` |
+| Install, sign-in, providers, RAM ladders | `references/setup-providers.md` |
+| Fades, gain, ducking, automation, effects, buses on placed tracks | `references/mixing.md` |
+| Local commands: grade, cutout, loudness, beats | `references/local.md` |
+| Remembered preferences | `references/memory.md` |

package/dist/skills/media-use/audio/references/bgm.md

@@ -11,7 +11,7 @@ One music bed per composition, produced by the shared audio engine (`scripts/aud
 
 `audio_request.json` → `bgm: { mode?, query?, prompt? }`:
 
-- **`mode`** — `retrieve | generate | none`. Omit for **auto** (retrieve when credentialed, else generate). An **explicit** `retrieve` is strict: no credential ⇒ skip, never a detached generate (so a caller with no `wait-bgm` step, e.g. product-launch, can't get a pending job it won't await).
+- **`mode`** — `retrieve | generate | none`. Omit for **auto** (retrieve when credentialed, else generate). An **explicit** `retrieve` is strict: no credential ⇒ skip, never a detached generate (so a caller with no `wait-bgm` step can't get a pending job it won't await).
 - **`query`** — the mood, used for retrieval and as a fallback prompt seed (e.g. a storyboard's `music:` field, falling back to `message` → `arc` → `"calm cinematic underscore"`).
 - **`prompt`** — an explicit full prompt for generation; omit and the engine infers one (see Mood inference). Optional `blob` / `archetype` / `arc` feed that inference.
 

package/dist/skills/media-use/audio/references/captions/authoring.md

@@ -40,7 +40,7 @@ Scan for words deserving distinct treatment:
 - **Numbers/statistics** — bold weight, accent color
 - **Emotional keywords** — exaggerated animation (overshoot, bounce)
 - **Call-to-action** — highlight, underline, color pop
-- **Marker highlight** — for beyond-color emphasis (highlight sweep, circle, burst, scribble, sketchout), see `hyperframes-animation/rules/css-marker-patterns.md`.
+- **Marker highlight** — for beyond-color emphasis (highlight sweep, circle, burst, scribble, sketchout), search the registry (`/hyperframes-registry`).
 
 ## Script-to-Style Mapping
 
@@ -152,7 +152,6 @@ Caption components ship with transparent backgrounds — they're pure overlays.
 
 - [`motion.md`](motion.md) — karaoke, marker effects, audio-reactive modulation, scatter exits.
 - [`transcript-handling.md`](transcript-handling.md) — input formats, quality checks, cleaning, external API fallback.
-- `hyperframes-animation/rules/css-marker-patterns.md` — marker highlighting (deterministic, fully seekable).
 
 ## Constraints
 

package/dist/skills/media-use/audio/references/captions/motion.md

@@ -16,7 +16,7 @@ You are here because SKILL.md told you to read this file before writing animatio
 
 **Emphasis words always break the pattern.** When a word is flagged as emphasis (emotional keyword, ALL CAPS, brand name), give it a stronger animation than surrounding words (larger scale, accent color, overshoot ease). This creates contrast.
 
-**Marker highlight modes add a visual layer on top of karaoke.** For emphasis words that need more than color/scale, add a marker-style effect: highlight sweep, circle, burst, scribble, or sketchout. See `hyperframes-animation/rules/css-marker-patterns.md` for implementation details. Match mode to energy: burst for hype, circle for key terms, highlight for standard, scribble for subtle.
+**Marker highlight modes add a visual layer on top of karaoke.** For emphasis words that need more than color/scale, add a marker-style effect: highlight sweep, circle, burst, scribble, or sketchout (search the registry, `/hyperframes-registry`). Match mode to energy: burst for hype, circle for key terms, highlight for standard, scribble for subtle.
 
 ## Audio-Reactive Captions (Mandatory for Music)
 
@@ -69,7 +69,7 @@ Keep audio reactivity subtle — 3-6% scale variation and soft glow. Heavy pulsi
 To generate the audio data file:
 
 ```bash
-python3 skills/hyperframes-creative/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json
+python3 <SKILL_DIR>/audio/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json
 ```
 
 ## Combining Techniques
@@ -82,6 +82,6 @@ Don't use the same highlight animation on every group — cycle through styles u
 
 Caption motion uses standard HyperFrames runtime APIs. Use the canonical sources:
 
-- **GSAP timeline + tween syntax** — `hyperframes-animation/adapters/gsap.md` (eases, position parameter, performance)
-- **`window.__hyperframes.fitTextFontSize` / `pretext`** — `hyperframes-core/references/determinism-rules.md` → Layout Contract (overflow prevention, per-frame text measurement)
-- **Audio data extraction** — generate via `python3 skills/hyperframes-creative/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json`, then load inline as shown in "Audio-Reactive Captions" above
+- **GSAP timeline + tween syntax** — `/hyperframes` → `references/runtimes.md` and `references/motion.md`
+- **Fitting caption text** — `/hyperframes` → `references/captions.md`
+- **Audio data extraction** — generate via `python3 <SKILL_DIR>/audio/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json`, then load inline as shown in "Audio-Reactive Captions" above

package/dist/skills/media-use/audio/references/tts.md

@@ -175,9 +175,6 @@ not native TTS timestamps. Do not distribute words evenly across a clip.
 - **Timing:** This adapter requests no native word timestamps. It uses the
   existing transcription pass. `lang` selects transcription language; Gemini
   infers speech language from the text.
-- **Workflow adapters:** Product-launch, faceless-explainer, and PR-video audio
-  scripts accept `--provider gemini --voice Kore --tts-model gemini-3.8-flash-tts
---style "Warm and clear"`.
 
 An API error is reported as a failed line; an explicitly chosen Gemini voice
 never silently falls back to another provider. Check the engine's anomalies

package/dist/skills/media-use/audio/scripts/audio.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 // audio.mjs — the shared HyperFrames audio engine. ONE implementation of TTS +
-// BGM + SFX for every video workflow (product-launch, general-video, pr-to-video,
-// …). Workflows do NOT vendor a copy: they write a neutral `audio_request.json`
-// (a tiny per-workflow adapter maps their storyboard/scenes into it) and call:
+// BGM + SFX. Callers do NOT vendor a copy: they write a neutral
+// `audio_request.json` (mapping their storyboard/scenes into it) and call:
 //
 //   node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
 //
@@ -35,7 +34,7 @@
 //     total_duration_s }
 //
 // --only tts,bgm,sfx  runs a subset and MERGES into an existing --out (so a
-// workflow can do TTS+BGM early, then SFX later once cues exist). When BGM uses
+// caller can do TTS+BGM early, then SFX later once cues exist). When BGM uses
 // the generate path it is spawned detached (bgm_pending:true) — run wait-bgm.mjs
 // before assembling.
 
@@ -200,8 +199,8 @@ if (only.has("bgm")) {
   Object.keys(bgmFields).forEach((k) => (bgmFields[k] = k === "bgm_pending" ? false : null));
   // Mode resolution. An EXPLICIT mode (flag or request.bgm.mode) is strict:
   // "retrieve" means retrieve-or-nothing — it never silently starts a detached
-  // generate (a caller with no wait-bgm step, e.g. product-launch, must not get
-  // a pending job it can't await). Only the UNSET/auto default picks generate
+  // generate (a caller with no wait-bgm step must not get a pending job it
+  // can't await). Only the UNSET/auto default picks generate
   // when HeyGen is absent.
   const explicitMode = bgmModeOverride || request.bgm?.mode || null;
   let mode = noBgm ? "none" : explicitMode || (heygenOK ? "retrieve" : "generate");