From 0477aa1aa83b104db6da30e95605c1e01aa27c65 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 20 Aug 2026 00:39:59 -0700 Subject: [PATCH] docs(skills): teach /hyperframes-audio the submix bus MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `` appeared in no skill, doc or registry file. The audio skill did cover groups, but only as membership tags to carve against — and its example groups three clips with no group ELEMENT at all. So an agent following the skill could never emit a group chain, fader or automation: it was never told the element exists. Adds "One bus for many tracks": the element, the five attributes it carries, and when to reach for it — the same compressor wanted on four narration clips is four chains that drift, and a compressor on the bus hears the whole voice instead of a third of it. Two things the skill has to say because they are the ways to get this wrong: - **Group automation is composition time.** A bus has no `data-start`, so `t: 0` in a group lane is the composition's start, not a clip's. Moving an envelope from a clip up onto its bus changes what its numbers mean. - **A carve stays on the clip.** `data-fx-carve` is not a group attribute. The one thing the skill already said about groups was about carve, which invites exactly that wrong inference; the bed carries the carve, pointed AT a group. Also corrects two framings that the bus makes false: the SKILL and attributes.md both said all three attributes go "on the audio/video element itself", when two of them also go on a bus. No flag needed, and the skill says so: the `audio-groups` canary gates the Studio UI for building groups, while a hand-authored bus parses, plays and renders for everyone. Verified rather than asserted: the documented example was run through `resolveAudioGroups` and `parseAudioFxChain` (group resolves, volume 0.9, both members found, compressor+peaking validate), its parameters checked against fx-registry.md ranges, and the whole pattern linted — the only findings were the throwaway fixture's own missing `data-start` and timeline registration, nothing about the bus. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 2 +- README.md | 22 +++---- skills-manifest.json | 2 +- skills/hyperframes-audio/SKILL.md | 60 ++++++++++++++++++- .../references/attributes.md | 4 ++ 5 files changed, 74 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 26b3f1049..91b37b715 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,7 +39,7 @@ Atomic capabilities the creation workflows compose against — pull one when you - `/hyperframes-keyframes` — seek-safe keyframe authoring across runtimes: GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth; plus `hyperframes keyframes` diagnostics for surfacing and verifying rendered motion. - `/hyperframes-creative` — non-animation creative direction: `frame.md` / `design.md` handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. - `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk. -- `/hyperframes-audio` — mix the audio already placed in a composition: voiceover carve (dip a music bed only in the bands the voice occupies, static or dynamic, level match included), the effect chain (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), and automation envelopes on volume or any effect parameter. Sourcing the audio is `/media-use`; this is what happens to it afterwards. +- `/hyperframes-audio` — mix the audio already placed in a composition: voiceover carve (dip a music bed only in the bands the voice occupies, static or dynamic, level match included), the effect chain (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes on volume or any effect parameter, and submix buses (``) that carry one chain, fader and automation clock for several tracks at once. Sourcing the audio is `/media-use`; this is what happens to it afterwards. - `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering). - `/hyperframes-registry` — install and wire registry blocks and components into compositions via `hyperframes add`. Covers authoring a new block or component to contribute upstream. - `/figma` — import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. diff --git a/README.md b/README.md index 796cb85f3..8bd276754 100644 --- a/README.md +++ b/README.md @@ -94,17 +94,17 @@ This writes `dist/hyperframes-plugin.zip` with a `hyperframes/` root folder and Atomic capabilities the creation workflows compose against — pull one when you need that specific layer. -| Skill | Covers | -| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/hyperframes-core` | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules. | -| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). | -| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. | -| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. | -| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | -| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus HeyGen-hosted cloud rendering (`cloud render`) and AWS Lambda rendering (`lambda deploy / render / progress`). | -| `/hyperframes-audio` | Mix the audio already placed in a composition — voiceover carve (dip a music bed only in the bands the voice occupies, static or dynamic, level match included), the effect chain (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), and automation envelopes on volume or any effect parameter. Sourcing the audio is `/media-use`. | -| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. | -| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. | +| Skill | Covers | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `/hyperframes-core` | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules. | +| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). | +| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. | +| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. | +| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | +| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus HeyGen-hosted cloud rendering (`cloud render`) and AWS Lambda rendering (`lambda deploy / render / progress`). | +| `/hyperframes-audio` | Mix the audio already placed in a composition — voiceover carve (dip a music bed only in the bands the voice occupies, static or dynamic, level match included), the effect chain (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes on volume or any effect parameter, and submix buses (``) carrying one chain, fader and automation clock for several tracks at once. Sourcing the audio is `/media-use`. | +| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. | +| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. | For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design) and [Open Design guide](https://hyperframes.heygen.com/guides/open-design). diff --git a/skills-manifest.json b/skills-manifest.json index fba704b9f..5158e9299 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -26,7 +26,7 @@ "files": 121 }, "hyperframes-audio": { - "hash": "f224ea9481998c08", + "hash": "4eb592347f37047d", "files": 6 }, "hyperframes-cli": { diff --git a/skills/hyperframes-audio/SKILL.md b/skills/hyperframes-audio/SKILL.md index ee13ddf36..2dd26e496 100644 --- a/skills/hyperframes-audio/SKILL.md +++ b/skills/hyperframes-audio/SKILL.md @@ -5,8 +5,9 @@ description: > fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, - bitcrush), or automation envelopes drawn on a track's volume or any effect - parameter. + bitcrush), automation envelopes drawn on a track's volume or any effect + parameter, or one submix bus carrying a chain, a fader and an automation clock + for several tracks at once (``). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`. @@ -38,7 +39,8 @@ no rate envelope; preprocess a derived synchronized asset. HyperFrames does not provide automatic waveform sync or drift correction. For copyable cut/crossfade/retime recipes, use `/hyperframes-core` → `references/creator-editing-recipes.md`. -Three attributes carry everything, all on the audio/video element itself: +Three attributes carry everything, on the audio/video element itself — or, for +the first two, on an `` bus (see "One bus for many tracks"): | Attribute | Holds | | ----------------- | --------------------------------------------------------- | @@ -261,6 +263,58 @@ A `sources` list naming two or more plain clip ids instead of a group is caught by the `audio_carve_ungrouped_sources` lint rule — it still works, but it is the version that silently rots when a clip is added. +### One bus for many tracks + +Membership alone is enough to carve against, as above — but add an +`` element with that id and the group becomes a real submix bus: +one chain, one fader, one automation clock for every member. + +```html + + + + +``` + +**Reach for the bus when the same treatment belongs on several tracks.** Four +narration clips that each want the same compressor is four chains to keep in +step, and they drift the moment one is edited; on the bus it is one chain, and +the compressor sees the whole voice rather than each clip in isolation — which is +the point, since a compressor cannot ride a sequence it only hears a third of. +Per-clip chains remain right for what is genuinely per-clip: one noisy take that +needs its own de-esser. + +| On the bus | Does | +| ----------------- | ----------------------------------------- | +| `data-fx-chain` | one chain over the summed members | +| `data-automation` | envelopes on the bus, in COMPOSITION time | +| `data-volume` | one fader for every member (default 1) | +| `data-label` | the display name; falls back to the id | +| `data-hidden` | drops every member from the mix | + +**Group automation is composition time, not clip time.** A bus has no +`data-start` — members are already at their composition positions when they +reach it — so `t: 0` in a group lane is the start of the composition, not of any +clip. A lane on a clip is clip-local; the same numbers mean different instants on +the two, which is the one thing to get right when moving an envelope from a clip +up onto its bus. + +**A carve stays on the clip.** `data-fx-carve` is not a group attribute: the bus +has no carve, and putting one there does nothing. The bed being carved is a +single track, and it is that track which carries `data-fx-carve` — pointed AT a +group, per the rule above. Group and carve meet in `sources`, not on one element. + +Nothing here needs a feature flag: the Studio UI for building groups is behind +the `audio-groups` canary, but a hand-authored `` parses, plays +and renders for everyone. + **One knob.** `strength` is 0..1 and derives everything: how deep to cut, how many bands, how wide, how far to favour intelligibility over raw voice energy, how far the level may drop, how far under the voice to aim. Those six move diff --git a/skills/hyperframes-audio/references/attributes.md b/skills/hyperframes-audio/references/attributes.md index 276ef235d..224275a9d 100644 --- a/skills/hyperframes-audio/references/attributes.md +++ b/skills/hyperframes-audio/references/attributes.md @@ -2,6 +2,10 @@ All three go on the `