Skip to content

Write HTML. Render video. Built for agents.

docs(skills): fix frame-worker contract, lint codes and stale references (#5515)

Märten Tropp63f32fefa958
diff --git a/skills-manifest.json b/skills-manifest.json
index 9d1f272ba0..558f0ab867 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -14,15 +14,15 @@
"files": 2
},
"general-video": {
- "hash": "d654955cbceaf3c7",
+ "hash": "17dfbb1d34efb012",
"files": 6
},
"hyperframes": {
- "hash": "7995559a6ae64821",
+ "hash": "9787b91e4c16bf7f",
"files": 31
},
"hyperframes-animation": {
- "hash": "9370b856259f4586",
+ "hash": "a5d09375a50f71c8",
"files": 122
},
"hyperframes-audio": {
@@ -54,7 +54,7 @@
"files": 1
},
"media-use": {
- "hash": "dd6a1116d3d01906",
+ "hash": "c4c3c723aa04bb7d",
"files": 112
},
"motion-graphics": {
@@ -70,7 +70,7 @@
"files": 35
},
"product-launch-video": {
- "hash": "39c46bb51002d67c",
+ "hash": "70d41a9836b6db41",
"files": 37
},
"remotion-to-hyperframes": {
diff --git a/skills/general-video/SKILL.md b/skills/general-video/SKILL.md
index 2fec78bf88..1b2e81744c 100644
--- a/skills/general-video/SKILL.md
+++ b/skills/general-video/SKILL.md
@@ -113,9 +113,9 @@ Use this dependency order. Skip a stage only when its input is absent.
`node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"`
- The builder writes one bounded packet per scene under `.hyperframes/frame-packets/` (the scene's exact storyboard block + the blueprint body + every cited rule recipe, inlined) and `_role.md` (`../hyperframes/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch the workers — 2–3 scene packets each, all in one wave (`../hyperframes/references/subagent-dispatch.md`); each worker's prompt carries `_role.md` and its packets — paste them in full, or hand the file paths for the worker to read first (equivalent either way) — plus a dispatch context with `PROJECT_DIR`, its `frame_id`s, and canvas size. WAIT on every scene's `compositions/<frame_id>.html` + `compositions/<frame_id>.motion.json`. Workers read only their packets and the design truth file; they never open `STORYBOARD.md` or the skill documents. With no delegation channel, fall back serially: process one packet at a time in this context, still working from the packet alone.
+ The builder writes one bounded packet per scene under `.hyperframes/frame-packets/` (the scene's exact storyboard block + the blueprint body + every cited rule recipe, inlined) and `_role.md` (`../hyperframes/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch the workers — 2–3 scene packets each, all in one wave (`../hyperframes/references/subagent-dispatch.md`); each worker's prompt carries `_role.md` and its packets — paste them in full, or hand the file paths for the worker to read first (equivalent either way) — plus a dispatch context with `PROJECT_DIR`, its `frame_id`s, and canvas size. WAIT on every scene's exact storyboard `src` (e.g. `compositions/frames/<frame_id>.html`) and the adjacent `<frame_id>.motion.json` sidecar. Workers read only their packets and the design truth file; they never open `STORYBOARD.md` or the skill documents. With no delegation channel, fall back serially: process one packet at a time in this context, still working from the packet alone.
-5. **Merge motion sidecars.** Collect the workers' `compositions/<frame_id>.motion.json` files and carry their durations and exit/entry vectors into assembly; where the doctrine chain (`/motion-doctrine`) is installed, translate them into the project ledger before stamping seams.
+5. **Merge motion sidecars.** Collect the workers' `<frame_id>.motion.json` files adjacent to each storyboard `src` and carry their durations and exit/entry vectors into assembly; where the doctrine chain (`/motion-doctrine`) is installed, translate them into the project ledger before stamping seams.
6. **Assemble.** Mount scenes, media, transitions, captions, and audio using the production loop. Real voice duration overrides estimates. When a music bed plays under any voice track, carve the bed before verifying: `/hyperframes-audio` → `scripts/carve.mjs --comp index.html`. A volume duck alone does not finish the mix.
7. **Verify.** Use `npx hyperframes lint` for fast feedback after the first HTML pass and structural changes. For the final gate, run `npx hyperframes check`; it reruns lint internally, so do not run a redundant standalone lint immediately before it. For sub-compositions, inspect midpoint snapshots. For multi-scene work, review the animation map.
8. **Final approval.** Once checks pass, open the final Studio preview — in autonomous mode too, before any render: opening it asks nothing. Ask whether to render or revise (autonomous: the one kept question). Render only after approval.
diff --git a/skills/general-video/sub-agents/frame-worker.md b/skills/general-video/sub-agents/frame-worker.md
index a3811a01b9..4eeca14fdc 100644
--- a/skills/general-video/sub-agents/frame-worker.md
+++ b/skills/general-video/sub-agents/frame-worker.md
@@ -1,6 +1,6 @@
# Frame worker — general-video delta
-> The shared law is the core contract above (the packet builder prepends `../../hyperframes/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a general-video scene; you run N-up, **one scene each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
+> The shared law is the core contract above (the packet builder prepends `../../hyperframes/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a general-video scene; each worker receives the **2–3 scene packets** the orchestrator assigns; build every assigned packet, one at a time. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
## Your scene is invented, not captured
@@ -12,10 +12,10 @@ Project inputs names the design file (resolution order `frame.md` → `design.md
## Output contract — composition + motion sidecar
-Write exactly two files, then stop:
+For each assigned packet, write exactly two files. Stop only after every assigned packet has both:
-1. `compositions/<frame_id>.html` — the sub-composition, a bare fragment per the core contract.
-2. `compositions/<frame_id>.motion.json` — one JSON object the orchestrator merges into the project's motion ledger:
+1. The packet's exact `src` (e.g. `compositions/frames/<frame_id>.html`) — the sub-composition, a bare fragment per the core contract.
+2. The sidecar `<frame_id>.motion.json` in the same directory (e.g. `compositions/frames/<frame_id>.motion.json`) — one JSON object the orchestrator merges into the project's motion ledger:
```json
{
diff --git a/skills/hyperframes-animation/adapters/animejs.md b/skills/hyperframes-animation/adapters/animejs.md
index 1f1b8f9793..613292aeec 100644
--- a/skills/hyperframes-animation/adapters/animejs.md
+++ b/skills/hyperframes-animation/adapters/animejs.md
@@ -120,7 +120,7 @@ After editing a composition that uses Anime.js:
```bash
npx hyperframes lint
-npx hyperframes validate
+npx hyperframes check
```
## Credits And References
diff --git a/skills/hyperframes-animation/transitions/TRANSITION-REGISTRY.md b/skills/hyperframes-animation/transitions/TRANSITION-REGISTRY.md
index 68fafca86c..a0d35b324b 100644
--- a/skills/hyperframes-animation/transitions/TRANSITION-REGISTRY.md
+++ b/skills/hyperframes-animation/transitions/TRANSITION-REGISTRY.md
@@ -1,10 +1,11 @@
# Transition Registry — machine source of truth
Single source of truth for **PLV scene-to-scene transitions**. The deterministic
-injector (`product-launch-video/scripts/inject-transitions.mjs`) reads the JSON
-block below and stamps the matching `gsap_template` onto the master timeline.
-The planner (`product-launch-video/agents/visual-design.md`) names a transition
-by its `name`; everything else is harness.
+injector (`product-launch-video/scripts/transitions.mjs inject`) reads its vendored
+copy of the JSON block below (`product-launch-video/scripts/lib/transitions.json`)
+and stamps the matching `gsap_template` onto the master timeline.
+The planner (`product-launch-video/references/story-design.md`) names a transition
+by its `name` in each frame's `transition_in`; everything else is harness.
This file is **not** the catalog of all transitions — that is `catalog.md` +
`css-*.md` (≈40 CSS + shader). This registry is the curated subset that is
diff --git a/skills/hyperframes/references/frame-worker-core.md b/skills/hyperframes/references/frame-worker-core.md
index f789fd892a..4619317529 100644
--- a/skills/hyperframes/references/frame-worker-core.md
+++ b/skills/hyperframes/references/frame-worker-core.md
@@ -7,8 +7,9 @@ You build the frame composition file(s) assigned in your dispatch and nothing el
**INPUT** — your dispatch provides this role, your frame packet(s), and:
- `PROJECT_DIR` — the project root; all paths are relative to it.
-- `frame_id` — e.g. `03-feature`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name (`compositions/frames/03-feature.html`) — that path **is** the frame's `src` in `STORYBOARD.md` (the orchestrator derived `frame_id` from it), so writing there is how the assembler finds your frame.
+- `frame_id` — e.g. `03-feature`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name. Write to the exact `src` in your packet's storyboard block (e.g. `compositions/frames/<frame_id>.html` or `compositions/<frame_id>.html`); the orchestrator derived `frame_id` from that path, and the assembler reads it verbatim.
- Your **packet** (`.hyperframes/frame-packets/<frame_id>.md`) — everything selected upstream for this frame. You never open the shared `STORYBOARD.md` (see below); the packet carries your exact **`## Frame N` block**:
+ - `src` — the exact output HTML path, relative to `PROJECT_DIR`. Preserve it; do not add or remove a `frames/` directory.
- `scene` — a one-line contact-sheet caption. **Design intent, never visible DOM text.**
- `voiceover` — the narration line. **Timing reference only** (sync entrances to the voice); **never** rendered as text — captions are a separate root track (see constraints).
- `duration` — your render length in seconds. **Fixed upstream; never change it or tween to fill a different length.**
@@ -24,7 +25,7 @@ You build the frame composition file(s) assigned in your dispatch and nothing el
**Retry** — if your context carries `lint` / `check` feedback from a prior pass, read it first and re-author so none of those findings recur; treat each as a hard constraint.
-**OUTPUT** — `compositions/frames/<frame_id>.html` for each assigned packet: exactly one bare `<template>…</template>` fragment. The first non-whitespace bytes are `<template`; the last are `</template>`. Never emit `<!doctype>`, `<html>`, `<head>`, `<body>`, or any markup outside that single template. Writing your assigned file(s) (past the self-check below) is your **terminal action** — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator picks up the file and marks the frame's `status`.
+**OUTPUT** — the HTML file at each assigned packet's `src`: exactly one bare `<template>…</template>` fragment. The first non-whitespace bytes are `<template`; the last are `</template>`. Never emit `<!doctype>`, `<html>`, `<head>`, `<body>`, or any markup outside that single template. The workflow delta specifies any required sidecars and the dispatch specifies which packets you own. Writing all assigned HTML files and required sidecars (past the self-check below) is your **terminal action** — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator picks up the file and marks the frame's `status`.
## When a confirmed sketch exists
@@ -56,24 +57,25 @@ Shared law for every narrative frame, each load-bearing; your workflow's delta a
1. **Read** — your packet top to bottom (your frame block, the inlined blueprint, the inlined rule recipes), then `frame.md` (the look). Internalize the self-check codes below before you write — most lethal is **template transport**: every `<style>` + `<script>` (including the gsap load) must live INSIDE `<template>`, because the runtime only clones template contents and the assembled-project `lint` / `check` gate can miss an unwired blank sub-composition.
2. **Design** — turn the time-coded shot sequence into a timeline using `frame.md`'s components and type ramp: each Scene window becomes a phase revealed on its `voiceover` cue, each named motion built from the recipe in your packet, the blueprint's signature move kept recognizable. Find a visual idea that reinforces the beat, not a literal restyle of the words.
-3. **Author** — write the full sub-composition to `compositions/frames/<frame_id>.html` (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously.
+3. **Author** — write the full sub-composition to the exact `src` in your packet (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously.
Prefix authored ids and globally reusable class names with `<frame_id>-` so sibling frames assembled from parallel workers cannot collide. Contract selectors such as `#root` and `.clip` are the only exceptions.
-4. **Self-check, then finish** — re-read your file against the checklist below and fix in place; then continue to your next assigned packet, if any. You do **not** run the CLI.
+4. **Self-check, then finish** — re-read your file against the checklist below and fix in place; write any sidecar required by the workflow delta, then continue to your next assigned packet, if any. You do **not** run the CLI.
## Self-check before finishing (you do NOT run the CLI)
-You **can't** meaningfully run `hyperframes lint` / `check` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them after assembly (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — the codes in parens are `hyperframes lint`'s and what the orchestrator may cite back:
+You **can't** meaningfully run `hyperframes lint` / `check` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them after assembly (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — backticked diagnostic codes below are emitted by `hyperframes lint`; bold labels are manual workflow checks, not lint codes:
-- `missing_template_wrapper` / `missing_composition_id` — the entire file is exactly one bare `<template>…</template>` fragment (no DOCTYPE / full document); root carries `data-composition-id="<frame_id>"`.
+- **Template wrapper (manual)** — the entire file is exactly one bare `<template>…</template>` fragment (no DOCTYPE / full document).
+- `root_missing_composition_id` — root carries `data-composition-id="<frame_id>"`; check that the value matches your assigned frame id.
- **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
- `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
-- `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
-- `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
+- **Clip attributes (manual)** — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
+- **Paused timeline + registration (manual for template frames)** — one paused timeline, registered at `window.__timelines["<frame_id>"]`. `gsap_timeline_not_registered` is a real lint code for standalone compositions, but the rule skips template/sub-compositions; it does not verify your frame registration.
- `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
- `gsap_css_transform_conflict` — never put a CSS `transform` (e.g. `translateY(-50%)` centering) on an element you then GSAP-animate a transform prop on (`x` / `y` / `scale` / `rotation`): GSAP overwrites the whole `transform` and silently drops the CSS centering (the element jumps). Center with `margin` / `inset` (or `top`/`left` + offset), fold the offset into the tween via `xPercent` / `yPercent`, or use `fromTo` (the rule exempts it).
- **Hero visibility** — the main subject is visible by `t <= 0.5s`; entrance tweens use `fromTo` instead of CSS-hidden starting states.
-- `exit_animation_on_non_final_scene` — no exit tween unless you are the final frame.
+- **Non-final exit (manual)** — no exit tween unless you are the final frame.
- **No front-loading (not a slide)** — the shot's pieces reveal on their `voiceover` cues across the duration, not all fired at `t=0`; a non-still frame keeps content arriving rather than holding a full canvas from ~25%.
- **Shot-sequence fidelity** — every Scene in the time-coded sequence is realized as a phase, the blueprint's signature move (unless `compose`) is present and recognizable, and the shot reveals to the voiceover (never front-loaded at `t=0`).
- `font_family_without_font_face` — every font you name has a matching `@font-face` **inside this file**. **Only use fonts that ship as files** with the project: the families declared in `frame.md` (their `.woff2` live in `assets/fonts/` or `capture/assets/fonts/` — point the `@font-face` `src` at the real file you find there). **Never name a font that has no file**, including system CJK / Japanese / Devanagari families (`Hiragino Sans`, `Yu Gothic`, `Noto Sans CJK`, `Noto Sans Devanagari`, …): the render machine is a clean headless Chrome with none of them installed, so the text silently falls back to a generic font and the typography is wrong in the MP4. For non-Latin or multilingual visible text, either use a shipped font that covers the script, or romanize / transliterate it (e.g. `日本語` → `Japanese`); if neither is possible it is out of scope for this frame — do not invent a font name.
diff --git a/skills/hyperframes/references/subagent-dispatch.md b/skills/hyperframes/references/subagent-dispatch.md
index 2148342b46..ebcadcbe5d 100644
--- a/skills/hyperframes/references/subagent-dispatch.md
+++ b/skills/hyperframes/references/subagent-dispatch.md
@@ -10,7 +10,7 @@ The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-vide
## Concurrency cap → batching rule (cap never changes scope)
-A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, one scene per dispatch, with the available slots chewing through the full list.
+A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, with the available slots chewing through the full list. The workflow sets how many scenes each worker gets (`general-video` assigns 2–3).
- When the harness queues excess children internally, submit **all N at once** and let the queue drain.
- Harness hard-caps active children (e.g. OpenClaw `maxChildrenPerAgent`) → dispatch in **waves of the cap size**: start `cap` workers, wait for their artifacts, start the next wave, until all N scenes exist. Example: 9 scenes on a cap-3 harness = 3 waves of 3 — never drop scenes, never merge scenes into one worker to fit the cap.
diff --git a/skills/media-use/references/grading.md b/skills/media-use/references/grading.md
index 7f7e79770b..0e1d8eeffc 100644
--- a/skills/media-use/references/grading.md
+++ b/skills/media-use/references/grading.md
@@ -17,7 +17,7 @@ Stop here and use that treatment workflow for requests such as retro, old home
video, camcorder, film, print, ASCII, glitch, privacy, or a media reveal. Do not
assemble those from a generic LUT plus handmade CSS vignette/grain/opacity.
-**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered, or `cube-validate.mjs` for a one-line `{ok,size}` check. Read `.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
+**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered. `npx hyperframes media-use resolve --type lut --intent "<look description>" --project .` validates generated or downloaded LUTs before freezing them; the validator is bundled in the CLI, not shipped as a standalone skill script. Read `<project>/.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
```bash
npx hyperframes media-use resolve --type grade --intent "warm daylight" --project . --json
@@ -158,5 +158,4 @@ validates generated or downloaded cubes as it freezes them under
```bash
npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project . --json
-node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube
```
diff --git a/skills/media-use/references/meta.md b/skills/media-use/references/meta.md
index c27838221e..8ad2f119b4 100644
--- a/skills/media-use/references/meta.md
+++ b/skills/media-use/references/meta.md
@@ -4,22 +4,22 @@ Maintainer-facing reference. Nothing here changes how you resolve or operate on
## What it owns (the gaps HyperFrames leaves)
-HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `scripts/lib/coverage.test.mjs` so the claim can't rot.
-
-| HyperFrames gap | media-use owns it via |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Audio-only, no image/icon | `resolve --type image\|icon` (heygen asset search) |
-| No third-party brand logos | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon) |
-| No voice / audio generation | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`) |
-| Scattered/duplicated audio engine | one consolidated engine under `audio/` (hyperframes-media retired) |
-| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs |
-| No transcript-driven cutting | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists |
-| No auto-duck / publish loudness | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes |
-| No cross-project memory | global content-addressed cache + auto-promote (`~/.media`) |
-| Grade recipes and LUT freezing | `resolve --type grade` emits a paste-ready recipe and `resolve --type lut` freezes validated `.cube` files; direct element analysis/authoring lives in `hyperframes media-treatment` |
-| No image generation | RAM-graded local mflux (FLUX) via `scripts/lib/mflux-provider.mjs`, codex `image_gen` upsell (`scripts/lib/codex-provider.mjs`) |
-| No video generation | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` in `scripts/lib/local-models.mjs`); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
-| Weak local-model defaults | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives (`scripts/lib/local-run.mjs`) |
+HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `packages/cli/src/media-use/lib/coverage.test.mjs` so the claim can't rot.
+
+| HyperFrames gap | media-use owns it via |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Audio-only, no image/icon | `resolve --type image\|icon` (heygen asset search) |
+| No third-party brand logos | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon) |
+| No voice / audio generation | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`) |
+| Scattered/duplicated audio engine | one consolidated engine under `audio/` (hyperframes-media retired) |
+| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs |
+| No transcript-driven cutting | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists |
+| No auto-duck / publish loudness | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes |
+| No cross-project memory | global content-addressed cache + auto-promote (`~/.media`) |
+| Grade recipes and LUT freezing | `resolve --type grade` emits a paste-ready recipe and `resolve --type lut` freezes validated `.cube` files; direct element analysis/authoring lives in `hyperframes media-treatment` |
+| No image generation | `resolve --type image` — RAM-graded local mflux (FLUX), codex `image_gen` upsell |
+| No video generation | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` ladder); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
+| Weak local-model defaults | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives |
## Usage stats
@@ -47,7 +47,7 @@ dev). Same public PostHog project key and opt-outs as the `hyperframes` CLI.
HeyGen request tagging: every generating `heygen` call (TTS, avatar video, catalog
search) carries the allowlisted `X-HeyGen-Client-Source: media-use` header, sourced
-from one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `scripts/lib/heygen-cli.mjs`)
+from one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `packages/cli/src/media-use/lib/heygen-cli.mjs`)
so a future call site can't silently ship untagged. Read-only discovery calls
(`voice list`, `avatar list`) are intentionally left untagged.
diff --git a/skills/media-use/references/operations.md b/skills/media-use/references/operations.md
index 491abebf40..463238b5f7 100644
--- a/skills/media-use/references/operations.md
+++ b/skills/media-use/references/operations.md
@@ -210,9 +210,9 @@ ffmpeg -i mix.wav \
GENERATES. Two paths, best-for-the-machine picked automatically:
1. **Local (default, free, private): mflux** (FLUX-on-MLX). `resolve` spec-checks
- AVAILABLE RAM and runs the best FLUX-class model that fits, via
- `scripts/lib/local-models.mjs` (`imagegen` ladder) + `mflux-provider.mjs`.
- The RAM ladder (agent sees it via `describeModelLadder("imagegen", specs)`):
+ AVAILABLE RAM and runs the best FLUX-class model that fits, using the
+ CLI-bundled `imagegen` ladder (its modules are not shipped in the standalone
+ skill). The RAM ladder:
| Tier | Model | Needs (available RAM) | Notes |
| ------ | -------------------- | --------------------- | ----------------------------------- |
@@ -245,7 +245,7 @@ clip), so treat the fallback as "HeyGen wasn't reachable," not "upgrade the
quality":
- **HeyGen avatar video (default, free for new API users):**
- `heygenVideoGenerate` (`scripts/lib/heygen-video-provider.mjs`) shells the
+ The CLI-bundled provider shells the
`heygen` CLI — never the raw API — auto-picking a public avatar and a
starfish voice (override with `--avatar-id`/`--voice-id`, threaded through
as `ctx.avatarId`/`ctx.voiceId`). If the CLI reports `not_authenticated`,
@@ -253,13 +253,13 @@ quality":
new API users — sign in) to stderr and falls through to LTX instead of
hard-failing.
- **Local fallback: LTX 2.3 on MLX** via `dgrauet/ltx-2-mlx`, the `videogen`
- ladder in `local-models.mjs` (`ltx-video-provider.mjs`). Generative clips
+ ladder bundled in the HyperFrames CLI. Generative clips
(t2v), spec-gated to RAM. Verified on 24GB: 512x320 x 33f with audio.
Every generating `heygen` call from media-use — TTS, avatar video, and
catalog search — sends the allowlisted `X-HeyGen-Client-Source: media-use`
header (persistent flag, works on every subcommand) via the shared
-`HEYGEN_CLIENT_SOURCE_ARGV` constant (`scripts/lib/heygen-cli.mjs`), so usage
+CLI-internal `HEYGEN_CLIENT_SOURCE_ARGV` constant, so usage
tags correctly in billing/resource meta and shows up in the API dashboards.
Read-only discovery (`avatar list`, `voice list`) doesn't need it.
diff --git a/skills/media-use/references/setup-providers.md b/skills/media-use/references/setup-providers.md
index d0a59e2f6c..ea4ec7db9e 100644
--- a/skills/media-use/references/setup-providers.md
+++ b/skills/media-use/references/setup-providers.md
@@ -36,8 +36,8 @@ before resolving bgm/sfx/image/icon/voice/avatar-video; music and sound effects
a host app's own tools need none of it. Local tools are opt-in
alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
transcription, and LTX for local video generation. `resolve` spec-checks
-AVAILABLE RAM for those local ladders (`describeModelLadder`); the agent can
-see the ladder and override.
+AVAILABLE RAM for those local ladders inside the CLI (the image tiers are listed
+in `references/operations.md`).
| Type | Provider / path |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -84,8 +84,7 @@ private, on-device path instead of or ahead of HeyGen for that type. Only
| `npx hyperframes` | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
-`scripts/lib/local-models.mjs` (the agent can read `describeModelLadder(cap, specs)`
-to see which model fits this machine). Without a tool on PATH, its provider
+the CLI's bundled media-use engine, not in the standalone skill. Without a tool on PATH, its provider
prints a one-line diagnostic to stderr and resolve falls through where another
provider exists (e.g. no `mflux` -> codex image upsell; no `parakeet-mlx` -> whisper.cpp).
diff --git a/skills/product-launch-video/SKILL.md b/skills/product-launch-video/SKILL.md
index bf763957cb..22ce3884f2 100644
--- a/skills/product-launch-video/SKILL.md
+++ b/skills/product-launch-video/SKILL.md
@@ -216,6 +216,14 @@ Inject transitions, run checks, pause for review, then render.
`node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html`
+**When a music bed plays under any voice track, carve the bed after assembly and transition injection, before checks.** The assembler's `data-volume` (0.12 by default under voice) is a fixed whole-bed gain, not the required spectral carve; the carve leaves it in place, so both apply. Read `/hyperframes-audio` → Voiceover carve.
+
+The assembler emits separate narration clips without an audio group. Before carving, add `data-audio-group="voiceover"` to each narration `<audio id="el-<frame_id>-voice">` in `index.html`, including any other voice clips that should join the same narration group. Keep the music bed and SFX outside that group. Multiple voice clips must be carved against their voice group, so later clips remain covered when the analysis is rerun. Then run from the composition project:
+
+`node <HYPERFRAMES_AUDIO_SKILL_DIR>/scripts/carve.mjs --comp ./index.html`
+
+`<HYPERFRAMES_AUDIO_SKILL_DIR>` is the installed `hyperframes-audio` skill directory. The script needs `ffmpeg` on PATH and `@hyperframes/core` installed in the composition project (`npm i -D @hyperframes/core`, or `bun add -D @hyperframes/core` in a Bun project). It detects the bed and overlapping voice tracks; use `--bed el-bgm` and repeat `--voice <voice-element-id>` when detection needs an explicit choice. Confirm the bed carries `data-fx-carve`, `data-fx-chain`, and `data-automation`; when multiple narration clips overlap the bed, `data-fx-carve.sources` should name the `voiceover` group, not individual clip ids. Skip this step only when no music plays under voice. Reassembling replaces `index.html`, so restore the narration group and rerun the carve after any reassembly.
+
`npx hyperframes lint`
`npx hyperframes check`