Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(audio): composition master bus (data-fx-chain on the root) (#5420)
Jerraie1925d4317fc
diff --git a/docs/reference/audio-effects.mdx b/docs/reference/audio-effects.mdxindex 910724a745..c1f9b8ddd4 100644--- a/docs/reference/audio-effects.mdx+++ b/docs/reference/audio-effects.mdx@@ -180,6 +180,41 @@ dangles.preview never lays it out.- Group ids and element ids share one namespace.+### The master bus: `data-fx-chain` on the composition root++```html+<div id="root" data-composition-id="main" data-width="1920" data-height="1080"+ data-fx-chain="{"version":1,"nodes":[+ {"type":"truepeak","id":"m1","label":"Delivery ceiling",+ "params":{"ceiling":-1.5,"lookahead":3,"release":80}}+ ]}"+>+```++The master bus is the `data-fx-chain` on the top-level composition root. It runs+once over the sum of every clip and every group, after each group's own chain and+fader, so a limiter here sees the peak of the whole mix. A clip can belong to+only one group, so this is the way to put one effect across everything.++- Only the **top-level** composition root is read as the master bus. On a clip or+ a group `data-fx-chain` keeps its own meaning, and on a sub-composition's root+ it is not applied while a parent composition contains it. A sub-composition file+ previewed or rendered on its own is the top-level root, so its chain is the+ master bus there.+- There is no master automation: `data-automation` on the root is not read as+ the master's.+- The render sums the tracks to a float WAV, runs the chain, and only then+ encodes AAC, so the chain reads unclipped samples. Preview inserts the chain+ between the clips' sum and the monitor.+- With a master chain on the root, preview plays every audible `<video>` through+ that bus too, as the render does. Without one, a video at volume 1 with no+ chain, group or automation of its own stays on native output.+- An unreadable master chain **fails the whole mix**: the render stops with an+ `audio_processing_failed` error under every strictness setting, and exports+ nothing. Preview plays dry with no message, and no lint rule checks a chain's+ contents, so one typo on the root blocks every export of that composition.+ Check a master chain in preview before rendering.+## Effect registrySixteen effects. Values outside a range are clamped on read. **AUTO** marks a@@ -223,7 +258,7 @@ the peak arrives, and holds that estimate at `ceiling`. Channels share onegain. It delays its output by `lookahead` plus about 0.3 ms (3.3 to 10.3 ms acrossthe range): the offline render trims that delay, live preview plays it, so thesound is that much behind the picture. A seek clears the limiter's delay line and-held gain on a group bus. Changing `lookahead` rebuilds the node.+held gain on a group or master bus. Changing `lookahead` rebuilds the node.The ceiling is held against that 4x estimate, not against the waveform itself. A4x interpolator cannot see the peaks of content close to Nyquist, so the true peakdiff --git a/packages/core/src/audibleVideo.test.ts b/packages/core/src/audibleVideo.test.tsindex 1d0ea261a5..2e2ee3fca2 100644--- a/packages/core/src/audibleVideo.test.ts+++ b/packages/core/src/audibleVideo.test.ts@@ -50,14 +50,19 @@ describe("AUDIBLE_MEDIA_SELECTOR", () => {describe("audibleVideoNeedsWebAudio", () => {it("keeps a unity, unprocessed video on native output", () => {expect(audibleVideoNeedsWebAudio({})).toBe(false);+ expect(audibleVideoNeedsWebAudio({ volume: 1, masterChain: null })).toBe(false);+ expect(audibleVideoNeedsWebAudio({ masterChain: "" })).toBe(false);expect(audibleVideoNeedsWebAudio({ volume: 1, fxChain: "", automation: null })).toBe(false);expect(audibleVideoNeedsWebAudio({ volume: Number.NaN })).toBe(false);});- it.each([{ volume: 1.5 }, { fxChain: "[]" }, { automation: "{}" }, { audioGroup: "music" }])(- "routes a video carrying %o",- (fields) => {- expect(audibleVideoNeedsWebAudio(fields)).toBe(true);- },- );+ it.each([+ { volume: 1.5 },+ { fxChain: "[]" },+ { automation: "{}" },+ { audioGroup: "music" },+ { volume: 1, masterChain: '{"version":1,"nodes":[]}' },+ ])("routes a video carrying %o", (fields) => {+ expect(audibleVideoNeedsWebAudio(fields)).toBe(true);+ });});diff --git a/packages/core/src/audibleVideo.ts b/packages/core/src/audibleVideo.tsindex 30c9aa5fd2..6c3b9aead3 100644--- a/packages/core/src/audibleVideo.ts+++ b/packages/core/src/audibleVideo.ts@@ -18,8 +18,10 @@ export function audibleVideoNeedsWebAudio(fields: {fxChain?: string | null;automation?: string | null;audioGroup?: string | null;+ masterChain?: string | null;}): boolean {return (- (fields.volume ?? 1) > 1 || Boolean(fields.fxChain || fields.automation || fields.audioGroup)+ (fields.volume ?? 1) > 1 ||+ Boolean(fields.fxChain || fields.automation || fields.audioGroup || fields.masterChain));}diff --git a/packages/core/src/audioFx.ts b/packages/core/src/audioFx.tsindex 7a75c2d947..8718390ad9 100644--- a/packages/core/src/audioFx.ts+++ b/packages/core/src/audioFx.ts@@ -288,7 +288,8 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [id: "limiter",label: "Limiter",group: "dynamics",- description: "Hard ceiling: nothing gets past the limit.",+ description:+ "Peak limiter that follows the signal's level. It has no lookahead, so a fast peak or an inter-sample peak can pass the ceiling; use the true-peak limiter for a delivery limit.",params: [{kind: "number",diff --git a/packages/core/src/audioFxCopy.test.ts b/packages/core/src/audioFxCopy.test.tsindex ad974b505b..72c69bfde3 100644--- a/packages/core/src/audioFxCopy.test.ts+++ b/packages/core/src/audioFxCopy.test.ts@@ -1,5 +1,5 @@import { describe, expect, it } from "vitest";-import { defaultAudioFxParams, HF_AUDIO_FX } from "./audioFx.js";+import { defaultAudioFxParams, getAudioFxDef, HF_AUDIO_FX } from "./audioFx.js";import { HF_AUDIO_FX_PRESETS } from "./audioFxPresets.js";import { audioBandAt, BANDS, EFFECT_COPY, PRESET_PROBLEM, SUMMARY } from "./audioFxCopy.js";@@ -197,3 +197,25 @@ describe("the true-peak copy does not promise a hard ceiling", () => {expect(hint).toMatch(/headroom/);});});++describe("the plain limiter copy does not promise a hard ceiling", () => {+ // The limiter follows the signal's level with no lookahead, and Level after is applied past+ // the ceiling, so a fast or inter-sample peak can end above it.+ it("says nothing about never clipping or nothing getting past", () => {+ const copy = EFFECT_COPY.limiter;+ const summary = SUMMARY.limiter;+ const description = getAudioFxDef("limiter")?.description;+ if (!copy || !summary || !description) throw new Error("limiter copy is missing");+ const shown = [+ description,+ copy.does,+ copy.reachFor,+ copy.params.limit?.label,+ summary({}),+ ].join("\n");+ expect(shown).not.toMatch(+ /never|nothing|guarantee|hard ceiling|no louder|must not|cannot exceed/i,+ );+ expect(shown).toMatch(/can (still )?(get )?pass|get past/i);+ });+});diff --git a/packages/core/src/audioFxCopy.ts b/packages/core/src/audioFxCopy.tsindex c6e2ac7aa0..d3c83d50ee 100644--- a/packages/core/src/audioFxCopy.ts+++ b/packages/core/src/audioFxCopy.ts@@ -152,13 +152,13 @@ export const EFFECT_COPY: Record<string, EffectCopy> = {},limiter: {title: "Peak Ceiling",- does: "Nothing gets louder than this, ever. A safety net at the end of the chain.",- reachFor: "You want to be sure it never clips or spikes.",+ does: "Pulls the loudest moments down toward this ceiling. It reacts to what it hears, so a fast peak can still get past, and Level after is applied on top of it.",+ reachFor: "You want peaks held down and can accept a small overshoot.",primary: "limit",primaryEnds: { low: "A lot of headroom", high: "Right up to the edge" },params: {limit: {- label: "Never exceed",+ label: "Ceiling",ends: { low: "A lot of headroom", high: "Right up to the edge" },},attack: { label: "How fast it catches" },@@ -411,7 +411,7 @@ export const SUMMARY: Record<string, (p: P) => string> = {: `${n(p.gain) > 0 ? "More" : "Less"} sparkle above ${hz(p.frequency)}`,compressor: (p) =>`Evening out, ${strength(Math.min(1, (n(p.ratio, 3) - 1) / 7), ["gentle", "moderate", "firm"])}`,- limiter: (p) => `Nothing louder than ${n(p.limit, -1)} dB`,+ limiter: (p) => `Peaks pulled down toward ${n(p.limit, -1)} dB`,truepeak: (p) => `Peaks pulled down toward ${n(p.ceiling, -1)} dBTP`,gate: (p) => `Closing gaps quieter than ${n(p.threshold, -45)} dB`,saturate: (p) =>diff --git a/packages/core/src/audioGroups.test.ts b/packages/core/src/audioGroups.test.tsindex 722da0a225..7b2821319a 100644--- a/packages/core/src/audioGroups.test.ts+++ b/packages/core/src/audioGroups.test.ts@@ -4,6 +4,7 @@ import {ensureAudioGroupInertStyle,HF_AUDIO_GROUP_ATTR,isMemberGroupHidden,+ readMasterFxChain,resolveAudioGroups,resolveCarveSourceIds,resolveGroupElement,@@ -305,3 +306,27 @@ describe("ensureAudioGroupInertStyle", () => {expect(document.querySelectorAll("#__hf-audio-group-inert")).toHaveLength(1);});});++describe("readMasterFxChain", () => {+ const CHAIN = `{"version":1,"nodes":[]}`;++ it("reads the chain off the top-level composition root", () => {+ document.body.innerHTML = `<div data-composition-id="main" data-fx-chain="${CHAIN}"></div>`;+ expect(readMasterFxChain(document)).toBe('{"version":1,"nodes":[]}');+ });++ it("is undefined when the root carries none", () => {+ document.body.innerHTML = `<div data-composition-id="main"><audio id="a"></audio></div>`;+ expect(readMasterFxChain(document)).toBeUndefined();+ });++ it("ignores a chain on a nested composition root", () => {+ document.body.innerHTML = `<div data-composition-id="main"><div data-composition-id="inner" data-fx-chain="${CHAIN}"></div></div>`;+ expect(readMasterFxChain(document)).toBeUndefined();+ });++ it("ignores a chain on a clip", () => {+ document.body.innerHTML = `<div data-composition-id="main"><audio id="a" data-fx-chain="${CHAIN}"></audio></div>`;+ expect(readMasterFxChain(document)).toBeUndefined();+ });+});diff --git a/packages/core/src/audioGroups.ts b/packages/core/src/audioGroups.tsindex b0cc736d11..1482eba48a 100644--- a/packages/core/src/audioGroups.ts+++ b/packages/core/src/audioGroups.ts@@ -128,6 +128,22 @@ export function isMemberGroupHidden(return resolveGroupElement(doc, groupId)?.hasAttribute("data-hidden") ?? false;}+/**+ * The top-level composition root, the only element the master bus is read from;+ * a sub-composition's root is skipped, so repeating one cannot stack chains.+ */+export function resolveMasterBusElement(root: ParentNode): Element | null {+ for (const el of root.querySelectorAll("[data-composition-id]")) {+ if (!el.parentElement?.closest("[data-composition-id]")) return el;+ }+ return null;+}++/** The master bus chain: the top-level root's `data-fx-chain`, if it carries one. */+export function readMasterFxChain(root: ParentNode): string | undefined {+ return resolveMasterBusElement(root)?.getAttribute(HF_AUDIO_FX_ATTR) || undefined;+}+export function resolveAudioGroups(root: ParentNode): HfAudioGroup[] {const membersByGroup = new Map<string, string[]>();const candidates = root.querySelectorAll(diff --git a/packages/core/src/runtime/audioFx.test.ts b/packages/core/src/runtime/audioFx.test.tsindex 6820a4bdc3..b1d110083c 100644--- a/packages/core/src/runtime/audioFx.test.ts+++ b/packages/core/src/runtime/audioFx.test.ts@@ -1,6 +1,6 @@// @vitest-environment happy-domimport { describe, expect, it } from "vitest";-import { attachElementFxChain } from "./audioFx.js";+import { attachElementFxChain, type FxAttributes } from "./audioFx.js";import { defaultAudioFxParams, HF_AUDIO_FX, HF_AUDIO_FX_ATTR } from "../audioFx.js";/**@@ -435,7 +435,7 @@ describe("attachElementFxChain", () => {],});- const build = () => {+ const build = (attrs?: FxAttributes) => {const clock = { currentTime: 0 };const made: { frequency: TimedParam }[] = [];class TimedNode extends Node {@@ -461,6 +461,7 @@ describe("attachElementFxChain", () => {new Node() as never,new Node() as never,{ scheduledAt: 0, elapsed: 0, rate: 1 },+ attrs,);return { clock, node, handle, param: () => made[0]?.frequency as unknown as TimedParam };};@@ -495,6 +496,14 @@ describe("attachElementFxChain", () => {expect(param().last()).toEqual({ time: 4, duration: 1 });});+ it("books no lane for a chain told its element carries none (the master bus)", () => {+ // The root's `data-automation` belongs to the composition, not to the bus.+ const { param } = build({ automation: null });+ expect(param().last()).toBeUndefined();+ const { param: ownParam } = build();+ expect(ownParam().last()).toEqual({ time: 0, duration: 8 });+ });+it("ignores a rate that is not a rate", () => {const { clock, handle, param } = build();clock.currentTime = 2;diff --git a/packages/core/src/runtime/audioFx.ts b/packages/core/src/runtime/audioFx.tsindex 085f10a152..2a4376ecca 100644--- a/packages/core/src/runtime/audioFx.ts+++ b/packages/core/src/runtime/audioFx.ts@@ -38,10 +38,9 @@ const NO_AUTOMATION: HfAutomation = { version: 1, lanes: [] };function readAutomation(el: { getAttribute?(name: string): string | null },chain: HfAudioFxChain,+ attr: string | null = HF_AUDIO_AUTOMATION_ATTR,): HfAutomation {- const raw =- (typeof el.getAttribute === "function" ? el.getAttribute(HF_AUDIO_AUTOMATION_ATTR) : null) ??- "";+ const raw = (attr && typeof el.getAttribute === "function" ? el.getAttribute(attr) : null) ?? "";if (!raw) return NO_AUTOMATION;try {return resolveAutomation(parseAutomation(raw), chain);@@ -119,12 +118,18 @@ export interface ElementFxHandle {setRate(rate: number): void;}+/** The attribute a chain's lanes are read from; the master bus has none. */+export interface FxAttributes {+ automation: string | null;+}+export function attachElementFxChain(ctx: BaseAudioContext,el: { getAttribute?(name: string): string | null },source: AudioNode,destination: AudioNode,timing?: AutomationTiming,+ attrs: FxAttributes = { automation: HF_AUDIO_AUTOMATION_ATTR },): ElementFxHandle | null {const { chain } = readChain(el);@@ -202,7 +207,13 @@ export function attachElementFxChain(const scheduleFor = (next: HfAudioFxChain, at: AutomationTiming | null): void => {automated =at && handle- ? scheduleChainAutomation(readAutomation(el, next), next, handle.nodes, at, handle.presets)+ ? scheduleChainAutomation(+ readAutomation(el, next, attrs.automation),+ next,+ handle.nodes,+ at,+ handle.presets,+ ): [];};@@ -282,7 +293,7 @@ export function attachElementFxChain(});observer.observe(target, {attributes: true,- attributeFilter: [HF_AUDIO_FX_ATTR, HF_AUDIO_AUTOMATION_ATTR],+ attributeFilter: attrs.automation ? [HF_AUDIO_FX_ATTR, attrs.automation] : [HF_AUDIO_FX_ATTR],});}diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.tsindex c0b68ca4d7..abac71baef 100644--- a/packages/core/src/runtime/init.test.ts+++ b/packages/core/src/runtime/init.test.ts@@ -5883,6 +5883,69 @@ describe("initSandboxRuntimeModular", () => {expect(ctx.mediaElementSources).toBe(0);});+ describe("under a composition root with a master chain", () => {+ const MASTER_CHAIN = '{"version":1,"nodes":[]}';+ const setRootChain = () =>+ document.querySelector("[data-root]")?.setAttribute("data-fx-chain", MASTER_CHAIN);++ it("joins the graph for a plain audible video at unity, so the master bus limits it", async () => {+ const video = mountMedia("video", { "data-has-audio": "true", "data-volume": "1" });+ setRootChain();+ const captureSpy = spyCapture();++ await startPlayback();++ expect(captureSpy).toHaveBeenCalledTimes(1);+ expect(captureSpy.mock.calls[0]?.[0]).toBe(video);+ expect(captureSpy.mock.calls[0]?.[4]).toBe(1);+ });++ it("acquires a media element source for it", async () => {+ mountMedia("video", { "data-has-audio": "true" });+ setRootChain();++ await startPlayback();+ await Promise.resolve();++ expect(ctx.mediaElementSources).toBe(1);+ });++ it("joins a video whose only audio is the composition, and every audio clip beside it", async () => {+ const video = mountMedia("video", { "data-has-audio": "true" });+ const audio = mountMedia("audio");+ setRootChain();+ const captureSpy = spyCapture();++ await startPlayback();++ expect(captureSpy.mock.calls.map((call) => call[0])).toEqual([video, audio]);+ });++ it("still keeps a muted or data-has-audio=false video out of the graph", async () => {+ mountMedia("video", { "data-has-audio": "true", muted: "" });+ mountMedia("video", { "data-has-audio": "false" });+ setRootChain();+ const captureSpy = spyCapture();++ await startPlayback();++ expect(captureSpy).not.toHaveBeenCalled();+ });++ it("does not count a chain on a sub-composition root", async () => {+ const video = mountMedia("video", { "data-has-audio": "true" });+ const inner = document.createElement("div");+ inner.setAttribute("data-composition-id", "inner");+ inner.setAttribute("data-fx-chain", MASTER_CHAIN);+ video.before(inner);+ const captureSpy = spyCapture();++ await startPlayback();++ expect(captureSpy).not.toHaveBeenCalled();+ });+ });+it.each([["data-fx-chain", "[]"],["data-automation", "[]"],diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.tsindex 295c0a3548..d85e18a6a5 100644--- a/packages/core/src/runtime/init.ts+++ b/packages/core/src/runtime/init.ts@@ -114,6 +114,7 @@ import {ensureAudioGroupInertStyle,HF_AUDIO_GROUP_TAG,isMemberGroupHidden,+ readMasterFxChain,} from "../audioGroups";import { clampNativeMediaVolume } from "../audioGain";import { quantizeTimeToFrame } from "../inline-scripts/parityContract";@@ -383,7 +384,7 @@ function pageAnimationsForOnePass(): () => Animation[] {return () => (list ??= document.getAnimations());}-// A `<video>` joins only for a gain `el.volume` cannot express: capture is a one-way door.+// A `<video>` joins only for a gain `el.volume` cannot express or a root master chain: capture is a one-way door.const joinsWebAudio = (el: Element): el is HTMLMediaElement =>isAudioElement(el) ||(isVideoElement(el) &&@@ -393,6 +394,7 @@ const joinsWebAudio = (el: Element): el is HTMLMediaElement =>fxChain: el.getAttribute("data-fx-chain"),automation: el.getAttribute("data-automation"),audioGroup: el.getAttribute("data-audio-group"),+ masterChain: readMasterFxChain(el.ownerDocument),}));const WEB_AUDIO_MEDIA = "audio[data-start], video[data-start]";const webAudioMediaIn = (root: ParentNode): HTMLMediaElement[] =>diff --git a/packages/core/src/runtime/webAudioTransport.test.ts b/packages/core/src/runtime/webAudioTransport.test.tsindex dcb384c6c6..79217cebe7 100644--- a/packages/core/src/runtime/webAudioTransport.test.ts+++ b/packages/core/src/runtime/webAudioTransport.test.ts@@ -1113,6 +1113,92 @@ describe("WebAudioTransport", () => {expect(fader.gain.value).toBeCloseTo(0.5, 6);});+ describe("master bus", () => {+ const GAIN_CHAIN = JSON.stringify({+ version: 1,+ nodes: [{ type: "gain", id: "g", params: { gain: -6 } }],+ });++ function withBusOut(setup: ReturnType<typeof setupGroupTransport>) {+ const busOut = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };+ (setup.transport as unknown as { _busOut: unknown })._busOut = busOut;+ return busOut;+ }++ it("splices the root's chain between the sum and the monitor", async () => {+ document.body.innerHTML = `<div id="root" data-composition-id="main"></div>`;+ document.getElementById("root")!.setAttribute("data-fx-chain", GAIN_CHAIN);+ const setup = setupGroupTransport();+ const busOut = withBusOut(setup);++ await scheduleGrouped(setup.transport, setup.gen, "a");++ const { masterGain } = setup.mock;+ expect(masterGain.disconnect).toHaveBeenCalledWith(busOut);+ // Wired into the chain's input, not straight to the bus output.+ expect(masterGain.connect).toHaveBeenCalledTimes(1);+ expect(masterGain.connect).not.toHaveBeenCalledWith(busOut);+ });++ it("feeds grouped members through the same master bus", async () => {+ document.body.innerHTML = `<div id="root" data-composition-id="main" data-fx-chain='${GAIN_CHAIN}'></div>`;+ const setup = setupGroupTransport();+ const busOut = withBusOut(setup);++ await scheduleGrouped(setup.transport, setup.gen, "a", "vo");++ expect(setup.mock.masterGain.disconnect).toHaveBeenCalledWith(busOut);+ expect(setup.mock.masterGain.connect).not.toHaveBeenCalledWith(busOut);+ });++ it("limits a plain video at unity played from its media element", async () => {+ document.body.innerHTML = `<div id="root" data-composition-id="main" data-fx-chain='${GAIN_CHAIN}'><video id="talk" data-has-audio="true"></video></div>`;+ const setup = setupGroupTransport();+ const busOut = withBusOut(setup);+ const video = document.getElementById("talk") as unknown as HTMLMediaElement;++ await setup.transport.scheduleMediaElementPlayback(video, 0, 0, 0, 1, setup.gen, 1);++ expect(setup.mock.gainNodes[0]!.connect).toHaveBeenCalledWith(setup.mock.masterGain);+ expect(setup.mock.masterGain.disconnect).toHaveBeenCalledWith(busOut);+ expect(setup.mock.masterGain.connect).not.toHaveBeenCalledWith(busOut);+ });++ it("leaves the sum wired straight through when the root has no chain", async () => {+ document.body.innerHTML = `<div id="root" data-composition-id="main"></div>`;+ const setup = setupGroupTransport();+ const busOut = withBusOut(setup);++ await scheduleGrouped(setup.transport, setup.gen, "a");++ expect(setup.mock.masterGain.connect).toHaveBeenLastCalledWith(busOut);+ });++ it("ignores a chain on a sub-composition's root", async () => {+ document.body.innerHTML = `<div id="root" data-composition-id="main"><div data-composition-id="inner" data-fx-chain='${GAIN_CHAIN}'></div></div>`;+ const setup = setupGroupTransport();+ const busOut = withBusOut(setup);++ await scheduleGrouped(setup.transport, setup.gen, "a");++ expect(setup.mock.masterGain.connect).toHaveBeenLastCalledWith(busOut);+ });++ it("is built once for the session, not once per member", async () => {+ document.body.innerHTML = `<div id="root" data-composition-id="main" data-fx-chain='${GAIN_CHAIN}'></div>`;+ const setup = setupGroupTransport();+ withBusOut(setup);++ await scheduleGrouped(setup.transport, setup.gen, "a");+ const nodesAfterFirst = setup.mock.gainNodes.length;+ await scheduleGrouped(setup.transport, setup.gen, "b");++ // The second member adds its own element gain and nothing else.+ expect(setup.mock.gainNodes.length).toBe(nodesAfterFirst + 1);+ expect(setup.mock.masterGain.disconnect).toHaveBeenCalledTimes(1);+ });+ });+describe("group mute (B5)", () => {it("a group created with data-hidden already set starts muted (mute gain at 0)", async () => {document.body.innerHTML = `<hf-audio-group id="vo" data-hidden></hf-audio-group>`;diff --git a/packages/core/src/runtime/webAudioTransport.ts b/packages/core/src/runtime/webAudioTransport.tsindex d02770764f..8d90eb4e0d 100644--- a/packages/core/src/runtime/webAudioTransport.ts+++ b/packages/core/src/runtime/webAudioTransport.ts@@ -1,4 +1,9 @@-import { attachElementFxChain, readElementAutomation, type ElementFxHandle } from "./audioFx.js";+import {+ attachElementFxChain,+ readElementAutomation,+ type ElementFxHandle,+ type FxAttributes,+} from "./audioFx.js";import {clearParamLane,scheduleParamLane,@@ -6,7 +11,12 @@ import {type AutomationTiming,} from "../audio/audioFxAutomation.js";import { VOLUME_RANGE } from "../audioAutomation.js";-import { audioGroupOf, readAudioGroupVolume, resolveGroupElement } from "../audioGroups.js";+import {+ audioGroupOf,+ readAudioGroupVolume,+ resolveGroupElement,+ resolveMasterBusElement,+} from "../audioGroups.js";import { swallow } from "./diagnostics";import { createLevelTap, type LevelTap, type StereoLevel } from "./levelTap.js";import { clampAudioGain } from "../audioGain.js";@@ -14,6 +24,8 @@ import { getDebugSurface } from "./globals.js";import { readElementPlaybackRate } from "./media.js";import { classifyWebAudioMediaRoute, reportWebAudioMediaRoute } from "./webAudioRoute.js";+const MASTER_FX_ATTRS: FxAttributes = { automation: null };+function normalizeRate(rate: number): number {if (!Number.isFinite(rate) || rate <= 0) return 1;return rate;@@ -139,6 +151,10 @@ export class WebAudioTransport {private _mediaElementSources = new WeakMap<HTMLMediaElement, MediaElementAudioSourceNode>();private _activeSources: ScheduledSource[] = [];private _masterGain: GainNode | null = null;+ /** Where the master bus chain lands; the program meter taps here. */+ private _busOut: GainNode | null = null;+ /** The chain on the composition root, built on first schedule and kept for the session. */+ private _master: { fx: ElementFxHandle | null; generation: number } | null = null;/** Preview volume and mute. Downstream of `_masterGain`; meters tap the program. */private _monitorGain: GainNode | null = null;private _masterVolume = 1;@@ -190,8 +206,10 @@ export class WebAudioTransport {this._ctx = new AudioContext();this._ctx.onstatechange = () => this.rest();this._masterGain = this._ctx.createGain();+ this._busOut = this._ctx.createGain();this._monitorGain = this._ctx.createGain();- this._masterGain.connect(this._monitorGain);+ this._masterGain.connect(this._busOut);+ this._busOut.connect(this._monitorGain);this._monitorGain.connect(this._ctx.destination);this.applyMasterGain();if (this._metering) this.attachMasterTap();@@ -573,7 +591,7 @@ export class WebAudioTransport {private attachMasterTap(): void {if (this._ctx && this._masterGain && !this._masterTap) {- this._masterTap = createLevelTap(this._ctx, this._masterGain);+ this._masterTap = createLevelTap(this._ctx, this._busOut ?? this._masterGain);}}@@ -601,6 +619,36 @@ export class WebAudioTransport {}}+ /**+ * The master bus chain, between the sum of every clip and group and the monitor.+ * A seek re-anchors it once per play generation; no root yet is retried next schedule.+ */+ private ensureMasterBus(doc: Document, timing: AutomationTiming): void {+ if (!this._ctx || !this._masterGain || !this._busOut) return;+ if (this._master) {+ if (this._master.generation === this._playGeneration) return;+ try {+ this._master.fx?.reanchor(timing);+ this._master.generation = this._playGeneration;+ } catch (err) {+ swallow("webAudioTransport.masterReanchor", err);+ }+ return;+ }+ const root = resolveMasterBusElement(doc);+ if (!root) return;+ this._masterGain.disconnect(this._busOut);+ const fx = attachElementFxChain(+ this._ctx,+ root,+ this._masterGain,+ this._busOut,+ timing,+ MASTER_FX_ATTRS,+ );+ this._master = { fx, generation: this._playGeneration };+ }+/** Master, unless `el` belongs to a group — then that group's bus (built on* first use, per `groupInput`). */private resolveDestination(@@ -610,9 +658,10 @@ export class WebAudioTransport {safeRate: number,): GainNode | null {if (!this._masterGain) return null;+ const groupTiming: AutomationTiming = { scheduledAt, elapsed: compositionTime, rate: safeRate };+ this.ensureMasterBus(el.ownerDocument, groupTiming);const groupId = audioGroupOf(el);if (!groupId) return this._masterGain;- const groupTiming: AutomationTiming = { scheduledAt, elapsed: compositionTime, rate: safeRate };return this.groupInput(groupId, el.ownerDocument, groupTiming) ?? this._masterGain;}@@ -785,17 +834,22 @@ export class WebAudioTransport {swallow("webAudioTransport.setRate", err);}}- // Group buses are not in `_activeSources` — they outlive it — so their FX- // automation needs re-aiming here too, or a rate change leaves a group's- // envelopes running the old plan over audio at the new speed.- for (const group of this._groups.values()) {+ this.setBusRate(safeRate);+ return true;+ }++ // Group buses and the master bus are not in `_activeSources` — they outlive it — so+ // their FX automation needs re-aiming too, or a rate change leaves their envelopes+ // running the old plan over audio at the new speed.+ private setBusRate(rate: number): void {+ const buses = [...this._groups.values(), ...(this._master ? [this._master] : [])];+ for (const bus of buses) {try {- group.fx?.setRate(safeRate);+ bus.fx?.setRate(rate);} catch (err) {- swallow("webAudioTransport.setRate.group", err);+ swallow("webAudioTransport.setRate.bus", err);}}- return true;}// A bounded source's wall-clock duration was baked into start()'s duration@@ -887,6 +941,8 @@ export class WebAudioTransport {this.stopMetering();for (const group of this._groups.values()) group.dispose();this._groups.clear();+ this._master?.fx?.dispose();+ this._master = null;this._bufferCache.clear();this._failedSrcs.clear();this._mediaElementSources = new WeakMap();@@ -903,6 +959,7 @@ export class WebAudioTransport {}this._ctx = null;this._masterGain = null;+ this._busOut = null;this._monitorGain = null;this._masterVolume = 1;this._masterMuted = false;diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.tsindex 8a69146f7a..9a0c01280d 100644--- a/packages/engine/src/index.ts+++ b/packages/engine/src/index.ts@@ -256,6 +256,7 @@ export { createVideoFrameInjector } from "./services/videoFrameInjector.js";export {MIXED_AUDIO_FILENAME,parseAudioElements,+ parseMasterFxChain,processCompositionAudio,} from "./services/audioMixer.js";export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";diff --git a/packages/engine/src/services/audioFxRender.test.ts b/packages/engine/src/services/audioFxRender.test.tsindex be5b6ca67c..6d2c944f97 100644--- a/packages/engine/src/services/audioFxRender.test.ts+++ b/packages/engine/src/services/audioFxRender.test.ts@@ -6,6 +6,12 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";import { applyVolumeEnvelopeToWav } from "./audioVolumeEnvelope.js";import { defaultAudioFxParams, type HfAudioFxChain } from "@hyperframes/core/audio-fx";import { applyAudioFxChain, AudioFxRenderError, readWav, writeWav } from "./audioFxRender.js";+import {+ MIXED_AUDIO_FILENAME,+ parseAudioElements,+ parseMasterFxChain,+ processCompositionAudio,+} from "./audioMixer.js";import { resolveHeadlessShellPath } from "./browserManager.js";import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";@@ -530,3 +536,197 @@ describe("an empty track", () => {expect(existsSync(output)).toBe(false);});});++/** Highest sample level of a file in dBFS, as ffmpeg's volumedetect reports it. */+function maxVolumeDb(path: string): number {+ const result = spawnSync(+ getFfmpegBinary(),+ ["-nostdin", "-hide_banner", "-i", path, "-af", "volumedetect", "-f", "null", "-"],+ { encoding: "utf-8" },+ );+ const match = result.stderr.match(/max_volume:\s*(-?[\d.]+) dB/);+ if (!match?.[1]) throw new Error(`Could not measure ${path}: ${result.stderr}`);+ return Number(match[1]);+}++const chainJson = (...nodes: Record<string, unknown>[]): string =>+ JSON.stringify({+ version: 1,+ nodes: nodes.map((node, i) => ({ id: `n${i + 1}`, enabled: true, ...node })),+ });++describe("master bus: reading it", () => {+ const html = (root: string, inner = ""): string =>+ `<div ${root}>${inner}<audio id="a" src="a.wav" data-start="0" data-duration="1"></audio></div>`;+ const CHAIN = '{"version":1,"nodes":[]}';+ const attr = `data-fx-chain='${CHAIN}'`;++ it("reads the root's chain as the master, not as a clip's own", () => {+ const doc = html(`data-composition-id="main" ${attr}`);+ expect(parseMasterFxChain(doc)).toBe(CHAIN);+ const [a] = parseAudioElements(doc);+ expect(a?.fxChain).toBeUndefined();+ expect(a?.groupFxChain).toBeUndefined();+ });++ it("has none when the root carries none", () => {+ expect(parseMasterFxChain(html(`data-composition-id="main"`))).toBeUndefined();+ });++ it("leaves a sub-composition root's chain as it was: not the master, not its clips' chain", () => {+ const inner = `<div data-composition-id="inner" ${attr}><audio id="b" src="b.wav" data-start="0" data-duration="1"></audio></div>`;+ const doc = html(`data-composition-id="main"`, inner);+ expect(parseMasterFxChain(doc)).toBeUndefined();+ const [a, b] = parseAudioElements(doc);+ for (const el of [a, b]) {+ expect(el?.fxChain).toBeUndefined();+ expect(el?.groupFxChain).toBeUndefined();+ }+ });++ it("takes the master from the top-level root when a sub-composition root carries one too", () => {+ const MASTER = '{"version":1,"nodes":[{"type":"gain","id":"m","params":{"gain":-3}}]}';+ const inner = `<div data-composition-id="inner" ${attr}></div>`;+ expect(+ parseMasterFxChain(html(`data-composition-id="main" data-fx-chain='${MASTER}'`, inner)),+ ).toBe(MASTER);+ });+});++describe.skipIf(!HAS_FFMPEG)("master bus: reporting an unreadable chain", () => {+ it("fails the mix with a failure instead of throwing", async () => {+ writeWav(join(dir, "a.wav"), new Float32Array(SR).fill(0.1), SR);+ const result = await processCompositionAudio(+ [+ {+ id: "a",+ src: "a.wav",+ start: 0,+ end: 1,+ mediaStart: 0,+ layer: 0,+ volume: 1,+ type: "audio",+ },+ ],+ dir,+ join(dir, "work"),+ join(dir, `bad-${MIXED_AUDIO_FILENAME}`),+ 1,+ undefined,+ { masterFxChain: "{not json" },+ );+ expect(result.success).toBe(false);+ expect(result.failures?.[0]?.elementId).toBe("master");+ });+});++describe.skipIf(!HAS_BROWSER || !HAS_FFMPEG)("master bus: rendering it", () => {+ const element = (id: string, extra: Record<string, unknown> = {}) => ({+ id,+ src: `${id}.wav`,+ start: 0,+ end: 1,+ mediaStart: 0,+ layer: 0,+ volume: 1,+ type: "audio" as const,+ ...extra,+ });+ const steady = (peak: number, freq: number): Float32Array =>+ Float32Array.from({ length: SR }, (_, i) => peak * Math.sin((2 * Math.PI * freq * i) / SR));++ it("limits the sum of everything that feeds it", async () => {+ // Two tones at -1 dBFS sum to about +5 dBFS: no clip's own chain can see that.+ writeWav(join(dir, "a.wav"), steady(0.9, 300), SR, 1, true);+ writeWav(join(dir, "b.wav"), steady(0.9, 300), SR, 1, true);+ const master = chainJson({+ type: "truepeak",+ params: { ceiling: -6, lookahead: 3, release: 80 },+ });+ const out = join(dir, `limited-${MIXED_AUDIO_FILENAME}`);+ const flat = join(dir, `flat-${MIXED_AUDIO_FILENAME}`);+ const mix = (path: string, masterFxChain?: string) =>+ processCompositionAudio(+ [element("a"), element("b")],+ dir,+ join(dir, "work"),+ path,+ 1,+ undefined,+ { masterFxChain },+ );+ expect((await mix(flat)).success).toBe(true);+ expect((await mix(out, master)).success).toBe(true);+ // The unprocessed sum has nowhere to go but full scale.+ expect(maxVolumeDb(flat)).toBeGreaterThan(-1);+ expect(maxVolumeDb(out)).toBeLessThanOrEqual(-5.5);+ }, 180_000);++ /** Mix `elements` for one second and read the file's highest level in dBFS. */+ const mixedPeakDb = async (+ name: string,+ elements: Parameters<typeof processCompositionAudio>[0],+ masterFxChain?: string,+ ): Promise<number> => {+ const out = join(dir, `${name}-${MIXED_AUDIO_FILENAME}`);+ const result = await processCompositionAudio(+ elements,+ dir,+ join(dir, "work"),+ out,+ 1,+ undefined,+ { masterFxChain },+ );+ expect(result.success).toBe(true);+ return maxVolumeDb(out);+ };+ const writeTone = (id: string, peak: number): void =>+ writeWav(join(dir, `${id}.wav`), steady(peak, 300), SR, 1, true);++ it("applies the root's data-fx-chain once over the sum, from authored HTML", async () => {+ // Two in-phase 0.3 tones sum to -4.4 dBFS. A -6 dBTP limiter then a -6 dB gain+ // land that at -12. Per clip, neither clip reaches the ceiling and the result is+ // -10.4; applied twice it is -18. A linear chain alone could not tell these apart.+ writeTone("a", 0.3);+ writeTone("b", 0.3);+ const master = chainJson(+ { type: "truepeak", params: { ceiling: -6, lookahead: 3, release: 80 } },+ { type: "gain", params: { gain: -6 } },+ );+ const clip = (id: string) =>+ `<audio id="${id}" src="${id}.wav" data-start="0" data-end="1" data-duration="1"></audio>`;+ const html = `<div data-composition-id="main" data-fx-chain='${master}'>${clip("a")}${clip("b")}</div>`;+ const elements = parseAudioElements(html);+ expect(elements).toHaveLength(2);+ expect(await mixedPeakDb("once", elements, parseMasterFxChain(html))).toBeCloseTo(-12, 0);+ }, 180_000);++ it("keeps the sum in float until the chain has read it", async () => {+ // The sum is +5 dBFS. A -6 dB master gain lands it at -1 if the sum is float; a sum+ // clipped to 16 bits at full scale first would land at -6.+ writeTone("a", 0.9);+ writeTone("b", 0.9);+ const masterFxChain = chainJson({ type: "gain", params: { gain: -6 } });+ const peak = await mixedPeakDb("float", [element("a"), element("b")], masterFxChain);+ expect(peak).toBeGreaterThan(-2);+ }, 180_000);++ it("runs after each group's own chain and fader", async () => {+ // The group limits its 0.5 tone to -20 dBFS, then its fader takes 6 dB off: -26. A+ // +12 dB master gain after both lands at -14. A fader ahead of the limiter would+ // leave -20 and end at -8; a master ahead of the group would be limited away at -26.+ writeTone("g", 0.5);+ const group = {+ groupId: "bus",+ groupFxChain: chainJson({+ type: "truepeak",+ params: { ceiling: -20, lookahead: 3, release: 80 },+ }),+ groupVolume: 0.5,+ };+ const masterFxChain = chainJson({ type: "gain", params: { gain: 12 } });+ expect(await mixedPeakDb("ordered", [element("g", group)], masterFxChain)).toBeCloseTo(-14, 0);+ }, 180_000);+});diff --git a/packages/engine/src/services/audioMixer.test.ts b/packages/engine/src/services/audioMixer.test.tsindex af39c210e2..612e69ebe0 100644--- a/packages/engine/src/services/audioMixer.test.ts+++ b/packages/engine/src/services/audioMixer.test.ts@@ -1,6 +1,6 @@// fallow-ignore-file code-duplicationimport { afterEach, describe, expect, it, vi } from "vitest";-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";import { join } from "node:path";import { tmpdir } from "node:os";@@ -66,6 +66,7 @@ vi.mock("../utils/ffprobe.js", async (importOriginal) => {});import { RATE_RANGE } from "@hyperframes/core/audio-automation";+import { AudioFxRenderError } from "./audioFxRender.js";import { parseAudioElements, processCompositionAudio } from "./audioMixer.js";describe("parseAudioElements strict literal timing", () => {@@ -105,6 +106,10 @@ describe("parseAudioElements — <source> children", () => {});describe("processCompositionAudio", () => {const tempDirs: string[] = [];+ const gainChain = JSON.stringify({+ version: 1,+ nodes: [{ type: "gain", id: "g", params: { gain: -3 } }],+ });afterEach(() => {vi.unstubAllGlobals();@@ -580,6 +585,42 @@ describe("processCompositionAudio", () => {});});+ it.each([+ ["the master pass", {}, { masterFxChain: gainChain }],+ ["a group bus", { groupId: "bus", groupFxChain: gainChain }, {}],+ ])("removes its work directory when %s fails fatally", async (_label, extra, config) => {+ const baseDir = mkdtempSync(join(tmpdir(), "hf-audio-base-"));+ const workDir = mkdtempSync(join(tmpdir(), "hf-audio-work-"));+ tempDirs.push(baseDir, workDir);+ writeFileSync(join(baseDir, "bed.wav"), "stub");+ applyAudioFxChainMock.mockRejectedValueOnce(new AudioFxRenderError("browser would not start"));++ await expect(+ processCompositionAudio(+ [+ {+ id: "bed",+ src: "bed.wav",+ start: 0,+ end: 2,+ mediaStart: 0,+ layer: 0,+ volume: 1,+ type: "audio",+ ...extra,+ },+ ],+ baseDir,+ workDir,+ join(baseDir, "out.m4a"),+ 2,+ undefined,+ config,+ ),+ ).rejects.toThrow(AudioFxRenderError);+ expect(existsSync(workDir)).toBe(false);+ });+it("lets an FX tail run past the clip, still bounded by the composition", async () => {// A reverb is still decaying when the clip's own audio stops. Trimming at// the clip boundary is what cut every tail short in the render.diff --git a/packages/engine/src/services/audioMixer.ts b/packages/engine/src/services/audioMixer.tsindex cdbdaf63e4..7937bf51c7 100644--- a/packages/engine/src/services/audioMixer.ts+++ b/packages/engine/src/services/audioMixer.ts@@ -27,7 +27,11 @@ import type {MixResult,} from "./audioMixer.types.js";import { applyVolumeEnvelopeToWav } from "./audioVolumeEnvelope.js";-import { HF_AUDIO_FX_ATTR, parseAudioFxChain } from "@hyperframes/core/audio-fx";+import {+ HF_AUDIO_FX_ATTR,+ parseAudioFxChain,+ type HfAudioFxChain,+} from "@hyperframes/core/audio-fx";import {HF_AUDIO_AUTOMATION_ATTR,parseAutomation,@@ -49,7 +53,7 @@ import {timeAtSourceTime,type RateSpec,} from "@hyperframes/core";-import { resolveAudioGroups } from "@hyperframes/core/audio-groups";+import { readMasterFxChain, resolveAudioGroups } from "@hyperframes/core/audio-groups";import { applyAudioFxChain, AudioFxRenderError } from "./audioFxRender.js";import type { AudioVolumeKeyframe } from "./audioMixer.types.js";@@ -518,6 +522,15 @@ export function volumeLaneKeyframes(return out;}+/**+ * The top-level root's `data-fx-chain`. It belongs to the composition, not to a clip,+ * so `processCompositionAudio` takes it beside the tracks: a track the render adds+ * itself has no parsed element to carry it.+ */+export function parseMasterFxChain(html: string): string | undefined {+ return readMasterFxChain(parseHTML(unwrapTemplate(html)).document);+}+export function parseAudioElements(html: string): AudioElement[] {const elements: AudioElement[] = [];const { document } = parseHTML(unwrapTemplate(html));@@ -744,6 +757,7 @@ async function mixAudioTracks(totalDuration: number,signal?: AbortSignal,config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">>,+ floatWav = false,): Promise<MixResult> {const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;const masterOutputGain = config?.audioGain ?? DEFAULT_CONFIG.audioGain;@@ -807,10 +821,7 @@ async function mixAudioTracks(scriptPath,"-map","[out]",- "-acodec",- "aac",- "-b:a",- "192k",+ ...(floatWav ? ["-acodec", "pcm_f32le", "-ar", "48000"] : ["-acodec", "aac", "-b:a", "192k"]),"-t",String(totalDuration),"-y",@@ -1027,6 +1038,56 @@ async function mixGroupMembers(return { success: true, degradedAutomation };}+/**+ * Sum the tracks to a float WAV, run the master chain over the sum, then AAC-encode.+ * Groups are already folded into `tracks`, and the sum stays float until the encoder.+ */+async function mixThroughMasterBus(+ tracks: AudioTrack[],+ masterChain: HfAudioFxChain,+ outputPath: string,+ workDir: string,+ totalDuration: number,+ signal?: AbortSignal,+ config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">>,+): Promise<MixResult> {+ const sumPath = join(workDir, "master-sum.wav");+ const sum = await mixAudioTracks(tracks, sumPath, totalDuration, signal, config, true);+ if (!sum.success) return { ...sum, outputPath };++ const fx = await applyAudioFxChain(sumPath, masterChain, join(workDir, "master-fx.wav"), {+ trackId: "master",+ signal,+ });+ const encoded = await runFfmpeg(+ [+ "-i",+ fx.path,+ "-t",+ String(totalDuration),+ "-acodec",+ "aac",+ "-b:a",+ "192k",+ "-y",+ outputPath,+ ],+ { signal, timeout: config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout },+ );+ if (!encoded.success) {+ const failure = ffmpegFailure("mix", encoded);+ return {+ success: false,+ outputPath,+ durationMs: sum.durationMs + encoded.durationMs,+ tracksProcessed: 0,+ error: failure.detail,+ failures: [failure],+ };+ }+ return { ...sum, outputPath, durationMs: sum.durationMs + encoded.durationMs };+}+export async function processCompositionAudio(elements: AudioElement[],baseDir: string,@@ -1034,7 +1095,10 @@ export async function processCompositionAudio(outputPath: string,totalDuration: number,signal?: AbortSignal,- config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">>,+ config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">> & {+ /** Serialised master bus chain, from `parseMasterFxChain`. */+ masterFxChain?: string;+ },compiledDir?: string,): Promise<MixResult> {const startMs = Date.now();@@ -1356,12 +1420,15 @@ export async function processCompositionAudio(// The producer only surfaces audio failures when `success` is false; mixing// the remaining tracks made the omitted cue indistinguishable from a valid// render unless someone manually audited that exact audio window.- const bail = (): MixResult => {+ const removeWorkDir = (): void => {try {rmSync(workDir, { recursive: true, force: true });} catch {/* ignore */}+ };+ const bail = (): MixResult => {+ removeWorkDir();return {success: false,outputPath,@@ -1375,6 +1442,28 @@ export async function processCompositionAudio(};if (failures.length > 0) return bail();+ // Parsed before any group is mixed, so a malformed master chain fails fast and+ // as a failure, the way an unreadable group chain does.+ let masterChain: HfAudioFxChain | undefined;+ const masterFxJson = config?.masterFxChain;+ if (masterFxJson) {+ try {+ masterChain = parseAudioFxChain(masterFxJson);+ } catch (err: unknown) {+ failures.push({+ stage: "mix",+ reason: "internal",+ owner: "user",+ retryable: false,+ elementId: "master",+ detail: boundedDetail(+ `Master bus chain is unreadable: ${err instanceof Error ? err.message : String(err)}`,+ ),+ });+ return bail();+ }+ }+// Sub-mix each group into one processed bus (design doc §1.3), then fold it// into the flat track list as a single AudioTrack — everything downstream// (the final mixAudioTracks call) never has to know groups exist. Group@@ -1479,7 +1568,10 @@ export async function processCompositionAudio(...(bakedEnvelope || !laneKeyframes?.length ? {} : { volumeKeyframes: laneKeyframes }),});} catch (err: unknown) {- if (err instanceof AudioFxRenderError) throw err;+ if (err instanceof AudioFxRenderError) {+ removeWorkDir();+ throw err;+ }failures.push({stage: "mix",reason: "internal",@@ -1496,12 +1588,22 @@ export async function processCompositionAudio(}if (failures.length > 0) return bail();- const mixResult = await mixAudioTracks(tracks, outputPath, totalDuration, signal, config);-+ let mixResult: MixResult;try {- rmSync(workDir, { recursive: true, force: true });- } catch {- /* ignore */+ mixResult =+ masterChain && tracks.length > 0+ ? await mixThroughMasterBus(+ tracks,+ masterChain,+ outputPath,+ workDir,+ totalDuration,+ signal,+ config,+ )+ : await mixAudioTracks(tracks, outputPath, totalDuration, signal, config);+ } finally {+ removeWorkDir();}// A group whose sub-mix had to drop member automation reports it the samediff --git a/packages/producer/scripts/test-classification.mjs b/packages/producer/scripts/test-classification.mjsindex 3c3969bca9..2aa4f1673b 100644--- a/packages/producer/scripts/test-classification.mjs+++ b/packages/producer/scripts/test-classification.mjs@@ -18,6 +18,7 @@ const INTEGRATION_TEST_FILES = new Set(["src/services/distributed/assemble.test.ts","src/services/distributed/chunkBoundary.test.ts","src/services/distributed/crossWorkerIdempotency.test.ts",+ "src/services/distributed/plan.masterBus.test.ts","src/services/distributed/plan.test.ts","src/services/distributed/planSizeCap.test.ts","src/services/distributed/renderChunk.test.ts",diff --git a/packages/producer/src/services/distributed/plan.masterBus.test.ts b/packages/producer/src/services/distributed/plan.masterBus.test.tsnew file mode 100644index 0000000000..1fe95cda02--- /dev/null+++ b/packages/producer/src/services/distributed/plan.masterBus.test.ts@@ -0,0 +1,50 @@+import { afterEach, beforeEach, expect, it, vi } from "vitest";+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { plan } from "./plan.js";++const MASTER_CHAIN = '{"version":1,"nodes":[]}';+const seen = vi.hoisted((): { audioInput?: { masterFxChain?: string } } => ({}));++vi.mock("../render/stages/audioStage.js", () => ({+ runAudioStage: async (input: { masterFxChain?: string; workDir: string }) => {+ seen.audioInput = input;+ return {+ audioOutputPath: `${input.workDir}/audio.m4a`,+ hasAudio: false,+ audioProcessMs: 0,+ };+ },+}));++let runRoot: string;++beforeEach(() => {+ runRoot = mkdtempSync(join(tmpdir(), "hf-plan-master-bus-"));+});++afterEach(() => {+ rmSync(runRoot, { recursive: true, force: true });+});++it("plan() gives the audio stage the composition's master chain", async () => {+ const projectDir = join(runRoot, "project");+ mkdirSync(projectDir, { recursive: true });+ writeFileSync(+ join(projectDir, "index.html"),+ `<!doctype html>+<html><head><meta charset="utf-8"></head><body>+ <div data-composition-id="root" data-width="320" data-height="240" data-duration="1" data-fx-chain='${MASTER_CHAIN}'>+ <p>master bus plan fixture</p>+ </div>+</body></html>`,+ "utf-8",+ );+ const planDir = join(runRoot, "plan");+ mkdirSync(planDir, { recursive: true });++ await plan(projectDir, { fps: 30, width: 320, height: 240, format: "mp4" }, planDir);++ expect(seen.audioInput?.masterFxChain).toBe(MASTER_CHAIN);+});diff --git a/packages/producer/src/services/distributed/plan.ts b/packages/producer/src/services/distributed/plan.tsindex e776e269e7..d6c5e1408c 100644--- a/packages/producer/src/services/distributed/plan.ts+++ b/packages/producer/src/services/distributed/plan.ts@@ -1130,6 +1130,7 @@ export async function buildLocalExecutionPlan(ffmpegProcessTimeout: cfg.ffmpegProcessTimeout,audioGain: cfg.audioGain,audios: composition.audios,+ masterFxChain: composition.masterFxChain,abortSignal,assertNotAborted,});diff --git a/packages/producer/src/services/htmlCompiler.test.ts b/packages/producer/src/services/htmlCompiler.test.tsindex 0e39d2aeeb..85050835b8 100644--- a/packages/producer/src/services/htmlCompiler.test.ts+++ b/packages/producer/src/services/htmlCompiler.test.ts@@ -744,6 +744,25 @@ describe("detectRenderModeHints", () => {expect(document.querySelector("#root")?.getAttribute("src")).toBe("root.png");});+ it("reads the root's data-fx-chain as the composition's master chain, apart from any clip", async () => {+ const projectDir = mkdtempSync(join(tmpdir(), "hf-master-chain-"));+ const chain = '{"version":1,"nodes":[]}';+ writeFileSync(+ join(projectDir, "index.html"),+ `<!doctype html><html><body>+ <div data-composition-id="main" data-width="100" data-height="100" data-duration="1" data-fx-chain='${chain}'>+ <video id="talk" src="talk.mp4" data-start="0" data-duration="1"></video>+ </div>+</body></html>`,+ );++ const compiled = await compileForRender(projectDir, join(projectDir, "index.html"), projectDir);++ expect(compiled.masterFxChain).toBe(chain);+ expect(compiled.audios.map((audio) => audio.id)).toEqual(["talk-audio"]);+ expect(compiled.audios[0]).not.toHaveProperty("fxChain");+ });+// Shared fixture builder for the assertSubCompositionsUsable / EmptyCompositionError// pre-flight tests below. `subCompFiles` is a map of compositions/-relative// filename to raw file content (empty string / malformed text / valid HTML).diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.tsindex f03f109743..1711954b43 100644--- a/packages/producer/src/services/htmlCompiler.ts+++ b/packages/producer/src/services/htmlCompiler.ts@@ -79,6 +79,7 @@ import {analyzeKeyframeIntervals,assertMediaPayload,NotMediaPayloadError,+ parseMasterFxChain,probeMediaProfile,} from "@hyperframes/engine";import {@@ -110,6 +111,7 @@ export interface CompiledComposition {videos: VideoElement[];audios: AudioElement[];images: ImageElement[];+ masterFxChain?: string;unresolvedCompositions: UnresolvedElement[];/** Assets that resolve outside projectDir. Keys are the path used in HTML, values are absolute filesystem paths. */externalAssets: Map<string, string>;@@ -2146,6 +2148,7 @@ export async function compileForRender(// two bare `<video>`s, both auto-numbered `hf-video-0` — collapsed into one// entry and injected frames onto whichever element came first. See #3340.const { videos, audios, images } = collectRenderMedia(html);+ const masterFxChain = parseMasterFxChain(html);// Advisory video checks (sparse keyframes, VFR). Fire-and-forget — these spawn// ffprobe subprocesses and should not block compilation since they only produce warnings.@@ -2198,6 +2201,7 @@ export async function compileForRender(videos,audios,images,+ ...(masterFxChain ? { masterFxChain } : {}),unresolvedCompositions,externalAssets,width,diff --git a/packages/producer/src/services/render/shared.ts b/packages/producer/src/services/render/shared.tsindex 7beb08a99f..9e07ff286e 100644--- a/packages/producer/src/services/render/shared.ts+++ b/packages/producer/src/services/render/shared.ts@@ -47,6 +47,7 @@ export interface CompositionMetadata {videos: VideoElement[];audios: AudioElement[];images: ImageElement[];+ masterFxChain?: string;width: number;height: number;}diff --git a/packages/producer/src/services/render/stages/audioStage.test.ts b/packages/producer/src/services/render/stages/audioStage.test.tsindex 14d7f7a35f..a04db699cf 100644--- a/packages/producer/src/services/render/stages/audioStage.test.ts+++ b/packages/producer/src/services/render/stages/audioStage.test.ts@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";import { mkdtempSync, rmSync } from "node:fs";import { join } from "node:path";import { tmpdir } from "node:os";-import type { AudioElement } from "@hyperframes/engine";+import { parseMasterFxChain, type AudioElement, type VideoElement } from "@hyperframes/engine";const { processCompositionAudioMock } = vi.hoisted(() => ({processCompositionAudioMock: vi.fn(),@@ -14,6 +14,7 @@ vi.mock("@hyperframes/engine", async (importOriginal) => {});import { runAudioStage } from "./audioStage.js";+import { appendAutoDetectedVideoAudio } from "./extractVideosStage.js";import { EncoderInterruptedError } from "../encoderInterruption.js";// Regression: hasAudio flipping to false used to be indistinguishable from@@ -87,6 +88,55 @@ describe("runAudioStage", () => {);});+ it("hands the master chain to the mixer when the only track is the one the render added for a plain video", async () => {+ // A plain <video> has no audio entry at compile time; the render adds one after probing+ // its file. That track is not parsed from HTML, so the chain cannot ride on it.+ const chain = '{"version":1,"nodes":[]}';+ const html = `<div data-composition-id="main" data-fx-chain='${chain}'><video id="talk" src="talk.mp4" data-start="0" data-duration="5"></video></div>`;+ const video: VideoElement = {+ id: "talk",+ src: "talk.mp4",+ start: 0,+ end: 5,+ mediaStart: 0,+ loop: false,+ hasAudio: true,+ };+ const composition = {+ videos: [video],+ audios: [] as AudioElement[],+ masterFxChain: parseMasterFxChain(html),+ };+ appendAutoDetectedVideoAudio(composition, [+ {+ videoId: "talk",+ metadata: { hasAudio: true },+ } as Parameters<typeof appendAutoDetectedVideoAudio>[1][number],+ ]);+ expect(composition.audios.map((audio) => audio.id)).toEqual(["talk-audio"]);+ processCompositionAudioMock.mockResolvedValue({+ success: true,+ outputPath: "audio.m4a",+ durationMs: 1,+ tracksProcessed: 1,+ });++ await runAudioStage(+ makeInput({ audios: composition.audios, masterFxChain: composition.masterFxChain }),+ );++ expect(processCompositionAudioMock).toHaveBeenCalledWith(+ composition.audios,+ expect.any(String),+ expect.any(String),+ expect.any(String),+ 5,+ undefined,+ { ffmpegProcessTimeout: 3_600_000, audioGain: 1, masterFxChain: chain },+ expect.any(String),+ );+ });+it("falls back to a generic message when the mixer fails without an error string", async () => {processCompositionAudioMock.mockResolvedValue({success: false,diff --git a/packages/producer/src/services/render/stages/audioStage.ts b/packages/producer/src/services/render/stages/audioStage.tsindex ff9ea7d4b8..dae085046d 100644--- a/packages/producer/src/services/render/stages/audioStage.ts+++ b/packages/producer/src/services/render/stages/audioStage.ts@@ -40,6 +40,7 @@ export interface AudioStageInput {audioGain: number;/** Read-only view of `composition.audios`. */audios: CompositionMetadata["audios"];+ masterFxChain?: string;abortSignal: AbortSignal | undefined;assertNotAborted: () => void;/** Where a per-track failure's detail goes. Optional so tests need not pass one. */@@ -72,6 +73,7 @@ export async function runAudioStage(input: AudioStageInput): Promise<AudioStageRffmpegProcessTimeout,audioGain,audios,+ masterFxChain,abortSignal,assertNotAborted,log,@@ -99,7 +101,7 @@ export async function runAudioStage(input: AudioStageInput): Promise<AudioStageRaudioOutputPath,duration,abortSignal,- { ffmpegProcessTimeout, audioGain },+ { ffmpegProcessTimeout, audioGain, masterFxChain },compiledDir,);} catch (err) {diff --git a/packages/producer/src/services/render/stages/compileStage.test.ts b/packages/producer/src/services/render/stages/compileStage.test.tsindex 08cef195fd..2132a27405 100644--- a/packages/producer/src/services/render/stages/compileStage.test.ts+++ b/packages/producer/src/services/render/stages/compileStage.test.ts@@ -242,6 +242,40 @@ describe("runCompileStage — forceScreenshot snapshot", () => {});});+const MASTER_CHAIN = '{"version":1,"nodes":[]}';+const MASTER_BUS_HTML = `<!doctype html>+<html>+<head><meta charset="utf-8"></head>+<body>+ <div data-composition-id="root" data-width="1920" data-height="1080" data-duration="1" data-fx-chain='${MASTER_CHAIN}'>+ <p>master bus composition</p>+ </div>+</body>+</html>`;++describe("runCompileStage — master bus", () => {+ it("hands the root's chain to the composition metadata the audio stage reads", async () => {+ const fixture = setupFixture(MASTER_BUS_HTML);+ try {+ const result = await runCompileStage({+ projectDir: join(fixture.workDir, "project"),+ workDir: fixture.workDir,+ htmlPath: fixture.htmlPath,+ entryFile: "index.html",+ job: createJob(),+ cfg: createCfg(),+ needsAlpha: false,+ log: noopLog,+ assertNotAborted: () => {},+ });+ expect(result.compiled.masterFxChain).toBe(MASTER_CHAIN);+ expect(result.composition.masterFxChain).toBe(MASTER_CHAIN);+ } finally {+ fixture.cleanup();+ }+ });+});+describe("runCompileStage — font fetch cancellation", () => {let fixture: CompileFixture | null = null;diff --git a/packages/producer/src/services/render/stages/compileStage.ts b/packages/producer/src/services/render/stages/compileStage.tsindex 30a2eab850..1ab3bd55ae 100644--- a/packages/producer/src/services/render/stages/compileStage.ts+++ b/packages/producer/src/services/render/stages/compileStage.ts@@ -310,6 +310,7 @@ export async function runCompileStage(input: CompileStageInput): Promise<Compilevideos: compiled.videos,audios: compiled.audios,images: compiled.images,+ masterFxChain: compiled.masterFxChain,width: compiled.width,height: compiled.height,};diff --git a/packages/producer/src/services/renderOrchestrator.masterBus.test.ts b/packages/producer/src/services/renderOrchestrator.masterBus.test.tsnew file mode 100644index 0000000000..039c107c47--- /dev/null+++ b/packages/producer/src/services/renderOrchestrator.masterBus.test.ts@@ -0,0 +1,87 @@+import { afterEach, expect, it, vi } from "vitest";+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { createRenderJob, executeRenderJob } from "./renderOrchestrator.js";++const MASTER_CHAIN = '{"version":1,"nodes":[]}';+const seen = vi.hoisted((): { audioInput?: { masterFxChain?: string } } => ({}));++vi.mock("@hyperframes/engine", async (importOriginal) => ({+ ...(await importOriginal<typeof import("@hyperframes/engine")>()),+ assertConfiguredFfmpegBinariesExist: () => {},+}));+vi.mock("./render/stages/compileStage.js", () => ({+ runCompileStage: async () => ({+ compiled: { html: "<div></div>" },+ composition: {+ width: 320,+ height: 180,+ duration: 1,+ videos: [],+ images: [],+ audios: [],+ masterFxChain: '{"version":1,"nodes":[]}',+ },+ deviceScaleFactor: 1,+ outputWidth: 320,+ outputHeight: 180,+ compileOnlyMs: 0,+ forceScreenshot: true,+ }),+}));+vi.mock("./render/stages/probeStage.js", () => ({+ runProbeStage: async ({ compiled }: { compiled: object }) => ({+ compiled,+ fileServer: null,+ probeSession: null,+ lastBrowserConsole: [],+ duration: 1,+ totalFrames: 30,+ browserProbeMs: 0,+ }),+}));+vi.mock("./render/stages/extractVideosStage.js", async (importOriginal) => ({+ ...(await importOriginal<typeof import("./render/stages/extractVideosStage.js")>()),+ runExtractVideosStage: async () => ({+ extractionResult: null,+ frameLookup: null,+ videoReadinessSkipIds: new Set<string>(),+ videoMetadataHints: new Map(),+ nativeHdrVideoIds: new Set<string>(),+ videoTransfers: new Map(),+ nativeHdrImageIds: new Set<string>(),+ imageTransfers: new Map(),+ hdrImageSrcPaths: new Map(),+ imageColorSpaces: [],+ videoExtractMs: 0,+ failureToEnforce: undefined,+ }),+}));+vi.mock("./render/stages/audioStage.js", () => ({+ runAudioStage: async (input: { masterFxChain?: string }) => {+ seen.audioInput = input;+ throw new Error("audio stage reached");+ },+}));++const dirs: string[] = [];+afterEach(() => {+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });+});++it("the local renderer gives the audio stage the composition's master chain", async () => {+ const root = mkdtempSync(join(tmpdir(), "hf-master-bus-orchestrator-"));+ dirs.push(root);+ writeFileSync(join(root, "index.html"), "<div></div>");+ const job = createRenderJob({+ fps: 30,+ quality: "standard",+ hdrMode: "force-sdr",+ logger: { info() {}, warn() {}, error() {}, debug() {} },+ });+ await expect(executeRenderJob(job, root, join(root, "output.mp4"))).rejects.toThrow(+ "audio stage reached",+ );+ expect(seen.audioInput?.masterFxChain).toBe(MASTER_CHAIN);+});diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.tsindex 5c9f49307e..fce6e022ab 100644--- a/packages/producer/src/services/renderOrchestrator.ts+++ b/packages/producer/src/services/renderOrchestrator.ts@@ -3356,6 +3356,7 @@ async function executeRenderPipeline(input: {ffmpegProcessTimeout: cfg.ffmpegProcessTimeout,audioGain: cfg.audioGain,audios: composition.audios,+ masterFxChain: composition.masterFxChain,abortSignal: executionSignal,assertNotAborted,log,diff --git a/packages/studio/src/player/lib/timelineDOM.test.ts b/packages/studio/src/player/lib/timelineDOM.test.tsindex 3b5790b1e0..6e3af94ce3 100644--- a/packages/studio/src/player/lib/timelineDOM.test.ts+++ b/packages/studio/src/player/lib/timelineDOM.test.ts@@ -632,6 +632,61 @@ describe("audio FX attributes on parsed elements", () => {});});+describe("the master chain on parsed elements", () => {+ const CHAIN = '{"version":1,"nodes":[{"type":"truepeak","id":"m1","params":{}}]}';+ const parseVideo = (rootAttrs: string, inner = ""): TimelineElement | undefined => {+ const doc = new DOMParser().parseFromString(+ `<div data-composition-id="main" data-start="0" data-duration="10" ${rootAttrs}>+ <video id="talk" data-start="0" data-duration="10" data-has-audio="true"></video>${inner}+ </div>`,+ "text/html",+ );+ return parseTimelineFromDOM(doc, 10).find((e) => e.domId === "talk");+ };++ it("copies the root's data-fx-chain onto an element that has none of its own", () => {+ const talk = parseVideo(`data-fx-chain='${CHAIN}'`);+ expect(talk?.masterChain).toBe(CHAIN);+ expect(talk?.fxChain).toBeUndefined();+ });++ it("leaves it unset when the root carries none", () => {+ expect(parseVideo("")?.masterChain).toBeUndefined();+ });++ it("ignores a sub-composition root's chain", () => {+ const inner = `<div data-composition-id="inner" data-fx-chain='${CHAIN}'></div>`;+ expect(parseVideo("", inner)?.masterChain).toBeUndefined();+ });++ it("carries it on the manifest path too", () => {+ const doc = makeDoc(`+ <div data-composition-id="main" data-fx-chain='${CHAIN}'>+ <video id="talk" data-has-audio="true"></video>+ </div>+ `);+ const element = createTimelineElementFromManifestClip({+ clip: {+ id: "talk",+ label: "Talk",+ kind: "video",+ tagName: "video",+ start: 0,+ duration: 10,+ track: 0,+ compositionId: null,+ parentCompositionId: "main",+ compositionSrc: null,+ assetUrl: null,+ },+ fallbackIndex: 0,+ doc,+ hostEl: doc.getElementById("talk"),+ });+ expect(element.masterChain).toBe(CHAIN);+ });+});+// A composition clip trimmed by 30 px collapsed to its first nested video's 1.77 s: that length capped the trim.describe("a composition clip's source length", () => {const scene = `diff --git a/packages/studio/src/player/lib/timelineDOM.ts b/packages/studio/src/player/lib/timelineDOM.tsindex 23b8b68ff9..1aa1ae8dbf 100644--- a/packages/studio/src/player/lib/timelineDOM.ts+++ b/packages/studio/src/player/lib/timelineDOM.ts@@ -12,6 +12,7 @@ import type { TimelineElement } from "../store/playerStore";import type { ClipManifestClip, IframeWindow, TimelineLike } from "./playbackTypes";import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";import { readClipTiming } from "@hyperframes/core/composition-contract";+import { readMasterFxChain } from "@hyperframes/core/audio-groups";import { linkScopeOf } from "@hyperframes/core/media-link";import { createRuntimeStartTimeResolver } from "@hyperframes/core/runtime/start-resolver";import { groupInfoFor } from "./timelineGroupInfo";@@ -167,6 +168,8 @@ export function createTimelineElementFromManifestClip(params: {if (info.fxChain) entry.audioGroupFxChain = info.fxChain;if (info.automation) entry.audioGroupAutomation = info.automation;}+ const masterChain = readMasterFxChain(doc ?? hostEl.ownerDocument);+ if (masterChain) entry.masterChain = masterChain;const fxChain = hostEl.getAttribute("data-fx-chain");if (fxChain) entry.fxChain = fxChain;const automation = hostEl.getAttribute("data-automation");@@ -330,6 +333,8 @@ export function parseTimelineFromDOM(// Read from the element, like the manifest path does: without these an audio// clip parsed straight from the DOM reserved no automation height and drew no// lanes, while the property panel still showed its chain.+ const domMasterChain = readMasterFxChain(doc);+ if (domMasterChain) entry.masterChain = domMasterChain;const domFxChain = el.getAttribute("data-fx-chain");if (domFxChain) entry.fxChain = domFxChain;const domAutomation = el.getAttribute("data-automation");diff --git a/packages/studio/src/player/store/timelineElement.ts b/packages/studio/src/player/store/timelineElement.tsindex 459dd08025..68f7d1940f 100644--- a/packages/studio/src/player/store/timelineElement.ts+++ b/packages/studio/src/player/store/timelineElement.ts@@ -62,9 +62,10 @@ export interface TimelineElement {/** Clip-edge fades from `data-fade-in` / `data-fade-out`, seconds; absent means none. */fadeIn?: number;fadeOut?: number;- /** Verbatim `data-fx-chain` / `data-automation`; see automationLaneData. */+ /** Verbatim `data-fx-chain` / `data-automation` (`masterChain`: the root's); see automationLaneData. */fxChain?: string;automation?: string;+ masterChain?: string;/** Path from data-composition-src — identifies sub-composition elements */compositionSrc?: string;/** Set by data-timeline-locked on the host element — disables move and trim in Studio. */diff --git a/packages/studio/src/utils/audioMeterMath.test.ts b/packages/studio/src/utils/audioMeterMath.test.tsindex b5fbfb2518..530efda348 100644--- a/packages/studio/src/utils/audioMeterMath.test.ts+++ b/packages/studio/src/utils/audioMeterMath.test.ts@@ -69,6 +69,15 @@ describe("hasProjectAudio", () => {expect(hasProjectAudio([clip({ tag: "video", hasAudio: true, ...fields })])).toBe(true);});+ it("counts an audible video when the composition root carries a master chain", () => {+ const masterChain = '{"version":1,"nodes":[]}';+ expect(hasProjectAudio([clip({ tag: "video", hasAudio: true, masterChain })])).toBe(true);+ expect(+ hasProjectAudio([clip({ tag: "video", muted: true, hasAudio: true, masterChain })]),+ ).toBe(false);+ expect(hasProjectAudio([clip({ tag: "video", masterChain })])).toBe(false);+ });+it("ignores a muted video even when it carries processing", () => {expect(hasProjectAudio([clip({ tag: "video", hasAudio: true, muted: true, volume: 2 })])).toBe(false,diff --git a/scripts/test-reachability.json b/scripts/test-reachability.jsonindex 9ac2e6c265..86c7aae277 100644--- a/scripts/test-reachability.json+++ b/scripts/test-reachability.json@@ -61,7 +61,7 @@],"sources": {"packages/producer/scripts/run-test-lane.mjs": "638885e14480d03290803389325a655f3749442167d784e07bb3af3404598af7",- "packages/producer/scripts/test-classification.mjs": "5cf0848da08f0fd2c40521d1556cfdb00b5a072cbd0ea0bc54945990abb709e4",+ "packages/producer/scripts/test-classification.mjs": "cdfa4035d0e2c0b1fea4d4c5b4697e0287d48c4474ab105f5e3d1ce839cca500",".github/workflows/ci.yml#job#producer-source-tests": "45da72aa6cf08cdfd5bcf5311e89f12af4842f9eebc6735df19da8c02f4d4864","packages/producer/package.json#script#test:unit": "ae6beda8319d166774be958ea5593cd27dbf7f6c9bce1d787a3fe28dfc3477b1","packages/producer/package.json#script#test:integration": "008589f37d026877595a13501cbb66abd5cbe50e21fdcac6904f45466c3f475d",diff --git a/skills-manifest.json b/skills-manifest.jsonindex 228c680a78..b6ab8e2aac 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -26,7 +26,7 @@"files": 122},"hyperframes-audio": {- "hash": "5dce20c2722a7af2",+ "hash": "780c9d4d8d23ab40","files": 8},"hyperframes-cli": {diff --git a/skills/hyperframes-audio/SKILL.md b/skills/hyperframes-audio/SKILL.mdindex a560e7baa6..1f01987a13 100644--- a/skills/hyperframes-audio/SKILL.md+++ b/skills/hyperframes-audio/SKILL.md@@ -197,9 +197,9 @@ for rumble; a low-pass darkens or muffles deliberately.**Dynamics** (`gain`, `compressor`, `limiter`, `truepeak`, `gate`) decide how a track's levelbehaves over time. Compression narrows the distance between loud and quiet so the-quiet parts can come up. A limiter is a ceiling — it does not shape anything, it-guarantees nothing gets past. `limiter` follows the level, so for a delivery-ceiling use `truepeak`, which looks ahead and measures the inter-sample peak. It+quiet parts can come up. A limiter pulls peaks down toward a ceiling and does not+shape anything else. `limiter` follows the level and has no lookahead, so a fast+or inter-sample peak can pass its ceiling; for a delivery ceiling use `truepeak`, which looks ahead and measures the inter-sample peak. Itholds a 4x estimate at the ceiling, not the waveform itself, so full-band noise canend up to 1.7 dB over: under a hard delivery limit set the ceiling at least 2 dBbelow it. A gate removes what is below a threshold, which is@@ -344,6 +344,13 @@ of, so only the filters survive — and a bus and its members are one signal patso the bed then runs through the bus's filters AND its own. The`audio_group_carve_attr` lint rule catches it.+**One effect across the whole mix: the master bus.** A clip names exactly one+group, so a limiter or EQ over everything cannot be a group. Put it in+`data-fx-chain` on the top-level composition root: it runs once over the sum of all clips and groups, after each+group's chain and fader. A delivery ceiling is the usual use — `truepeak` last in+the master chain. Only the top-level root is read as the master bus; a+sub-composition root's `data-fx-chain` is not applied inside a parent composition. No master automation.+**One clip is not a bus.** A group exists to give several tracks one chain, onefader and one clock. Wrapping a single clip in a bus buys nothing the clip's own`data-fx-chain` does not already do, and it doubles the places a later edit hasdiff --git a/skills/hyperframes-audio/references/attributes.md b/skills/hyperframes-audio/references/attributes.mdindex 8be1d40f21..c2056ab23e 100644--- a/skills/hyperframes-audio/references/attributes.md+++ b/skills/hyperframes-audio/references/attributes.md@@ -110,6 +110,15 @@ cannot move: worklet processor options, a WaveShaper curve and a convolutionimpulse are all set wholesale. `fx-registry.md` marks each parameter; theworklet effects (`compressor`, `limiter`, `truepeak`, `gate`, `bitcrush`) have none at all.+## `data-fx-chain` on the root — the master bus++The `data-fx-chain` JSON on the top-level composition root (the element with+`data-composition-id` that no other composition contains) is the master bus. It+runs once over the sum of every clip and group, after each group's own chain and+fader. On a clip or a group `data-fx-chain` keeps its own meaning, and on a+sub-composition root inside a parent composition it is not applied. The master bus has no+automation lanes.+## `data-fx-carve` — the carve's settings```json