Skip to content

Commit e1925d4

Browse files
feat(audio): composition master bus (data-fx-chain on the root) (#5420)
* feat(audio): composition master bus (data-fx-chain on the root) A clip can belong to only one audio group, so there was no way to put one effect, such as a limiter, across the whole mix. The data-fx-chain on the top-level composition root now runs once over the sum of every clip and every group, after each group's own chain and fader. No new attribute: a sub-composition root's data-fx-chain was never applied to anything and still is not. Render: when a master chain exists, mixAudioTracks writes a float WAV instead of AAC, applyAudioFxChain runs the chain over it, and ffmpeg encodes AAC last, so the chain reads unclipped samples. An unreadable chain is a mix failure, as for a group. Preview: the transport splices the chain between the clips' sum and the monitor, re-anchored per play generation and watched for edits. Only the top-level root is read. No master automation: the root's data-automation is not read as the bus's. No lint rule: data-fx-chain is valid on clips, groups and roots, and the one place it does nothing (a sub-composition root) has always been silent. — Jerrai * fix(core): preview routes every audible video through the master bus A root data-fx-chain is attached only inside the Web Audio graph, but a plainly audible <video> joined that graph only for its own chain, group, automation or a volume over 1. So preview limited the music and left the talking head dry, and a composition whose only audio is video got no master chain at all, while export sums every audible element into the master. A master chain on the top-level composition root is now a reason to join, the same as a video's own chain. Elements under a root with no chain keep native output. Sub-composition roots are still ignored. — Jerrai * fix(audio): master bus review round 2 (temp dir, tests, docs, Studio meter) - audioMixer: a fatal FX error in the master pass or a group bus left the work directory (the full float sum, about 1.4 GB an hour) on disk. The final mix now runs in try/finally and the group rethrow removes it first. - Tests: the "once over the sum" case now uses a limiter then a gain, so a per-clip chain (-10.4) and a doubled one (-18) both fail it; a new case proves the sum stays float until the chain reads it; the fader case uses a group volume of 0.5 so the fader's position is exercised; the work-dir removal is covered for both paths. - Docs: "Three rules exist" (the master-bus lint rule is gone), a bad master chain stops the render with audio_processing_failed, a sub-composition file opened on its own has its root chain as the master bus, and a seek clears a group or master limiter. - Studio: TimelineElement.masterChain carries the root's data-fx-chain, so the program meter shows for a video-only composition whose only audio routing is the master chain, as preview now plays it. - Comment blocks over four lines cut; webAudioTransport.setRate split so its CRAP score is under the Fallow threshold. — Jerrai * fix(audio): master chain reaches tracks the render adds; honest plain-limiter copy - Master chain: it was carried on each parsed AudioElement, so a track the producer adds itself (appendAutoDetectedVideoAudio, the browser-discovered audio in probeStage) never had it, and a composition whose only audio was such a track exported with no master chain, no ceiling and no warning. It is now a composition property: parseMasterFxChain(html) at compile, carried on CompiledComposition and CompositionMetadata, passed to processCompositionAudio by runAudioStage (in-process and distributed plan). AudioElement.masterFxChain is removed so there is one source. Each forward (compile stage, local orchestrator, distributed plan) has a test that fails when it is dropped. - Plain limiter: it follows the level with no lookahead and Level after is applied past the ceiling, so it cannot promise "nothing gets past" or "never clips". Studio copy (description, panel text, knob label, summary) and the hyperframes-audio skill now say a fast or inter-sample peak can pass it and point to the true-peak limiter for a delivery limit. A copy test guards it. — Jerrai * fix(producer): keep master bus comments within the ratchet; run the plan test with the ffmpeg tests Drop three one-line field comments that raised their files' comment share, and list plan.masterBus.test.ts with the integration tests because plan() reads the ffmpeg version. — Jerrai * chore(ci): repin the producer test-classification source in the reachability map The reachability map pins the hash of test-classification.mjs, which now lists one more integration test. The map's producer lane command already covers every test under src, in both the unit and integration matrix lanes. — Jerrai
1 parent bf881bf commit e1925d4

38 files changed

Lines changed: 1072 additions & 57 deletions

‎docs/reference/audio-effects.mdx‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,41 @@ dangles.
180180
preview never lays it out.
181181
- Group ids and element ids share one namespace.
182182

183+
### The master bus: `data-fx-chain` on the composition root
184+
185+
```html
186+
<div id="root" data-composition-id="main" data-width="1920" data-height="1080"
187+
data-fx-chain="{&quot;version&quot;:1,&quot;nodes&quot;:[
188+
{&quot;type&quot;:&quot;truepeak&quot;,&quot;id&quot;:&quot;m1&quot;,&quot;label&quot;:&quot;Delivery ceiling&quot;,
189+
&quot;params&quot;:{&quot;ceiling&quot;:-1.5,&quot;lookahead&quot;:3,&quot;release&quot;:80}}
190+
]}"
191+
>
192+
```
193+
194+
The master bus is the `data-fx-chain` on the top-level composition root. It runs
195+
once over the sum of every clip and every group, after each group's own chain and
196+
fader, so a limiter here sees the peak of the whole mix. A clip can belong to
197+
only one group, so this is the way to put one effect across everything.
198+
199+
- Only the **top-level** composition root is read as the master bus. On a clip or
200+
a group `data-fx-chain` keeps its own meaning, and on a sub-composition's root
201+
it is not applied while a parent composition contains it. A sub-composition file
202+
previewed or rendered on its own is the top-level root, so its chain is the
203+
master bus there.
204+
- There is no master automation: `data-automation` on the root is not read as
205+
the master's.
206+
- The render sums the tracks to a float WAV, runs the chain, and only then
207+
encodes AAC, so the chain reads unclipped samples. Preview inserts the chain
208+
between the clips' sum and the monitor.
209+
- With a master chain on the root, preview plays every audible `<video>` through
210+
that bus too, as the render does. Without one, a video at volume 1 with no
211+
chain, group or automation of its own stays on native output.
212+
- An unreadable master chain **fails the whole mix**: the render stops with an
213+
`audio_processing_failed` error under every strictness setting, and exports
214+
nothing. Preview plays dry with no message, and no lint rule checks a chain's
215+
contents, so one typo on the root blocks every export of that composition.
216+
Check a master chain in preview before rendering.
217+
183218
## Effect registry
184219

185220
Sixteen 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 one
223258
gain. It delays its output by `lookahead` plus about 0.3 ms (3.3 to 10.3 ms across
224259
the range): the offline render trims that delay, live preview plays it, so the
225260
sound is that much behind the picture. A seek clears the limiter's delay line and
226-
held gain on a group bus. Changing `lookahead` rebuilds the node.
261+
held gain on a group or master bus. Changing `lookahead` rebuilds the node.
227262

228263
The ceiling is held against that 4x estimate, not against the waveform itself. A
229264
4x interpolator cannot see the peaks of content close to Nyquist, so the true peak

‎packages/core/src/audibleVideo.test.ts‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -50,14 +50,19 @@ describe("AUDIBLE_MEDIA_SELECTOR", () => {
5050
describe("audibleVideoNeedsWebAudio", () => {
5151
it("keeps a unity, unprocessed video on native output", () => {
5252
expect(audibleVideoNeedsWebAudio({})).toBe(false);
53+
expect(audibleVideoNeedsWebAudio({ volume: 1, masterChain: null })).toBe(false);
54+
expect(audibleVideoNeedsWebAudio({ masterChain: "" })).toBe(false);
5355
expect(audibleVideoNeedsWebAudio({ volume: 1, fxChain: "", automation: null })).toBe(false);
5456
expect(audibleVideoNeedsWebAudio({ volume: Number.NaN })).toBe(false);
5557
});
5658

57-
it.each([{ volume: 1.5 }, { fxChain: "[]" }, { automation: "{}" }, { audioGroup: "music" }])(
58-
"routes a video carrying %o",
59-
(fields) => {
60-
expect(audibleVideoNeedsWebAudio(fields)).toBe(true);
61-
},
62-
);
59+
it.each([
60+
{ volume: 1.5 },
61+
{ fxChain: "[]" },
62+
{ automation: "{}" },
63+
{ audioGroup: "music" },
64+
{ volume: 1, masterChain: '{"version":1,"nodes":[]}' },
65+
])("routes a video carrying %o", (fields) => {
66+
expect(audibleVideoNeedsWebAudio(fields)).toBe(true);
67+
});
6368
});

‎packages/core/src/audibleVideo.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,10 @@ export function audibleVideoNeedsWebAudio(fields: {
1818
fxChain?: string | null;
1919
automation?: string | null;
2020
audioGroup?: string | null;
21+
masterChain?: string | null;
2122
}): boolean {
2223
return (
23-
(fields.volume ?? 1) > 1 || Boolean(fields.fxChain || fields.automation || fields.audioGroup)
24+
(fields.volume ?? 1) > 1 ||
25+
Boolean(fields.fxChain || fields.automation || fields.audioGroup || fields.masterChain)
2426
);
2527
}

‎packages/core/src/audioFx.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,8 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
288288
id: "limiter",
289289
label: "Limiter",
290290
group: "dynamics",
291-
description: "Hard ceiling: nothing gets past the limit.",
291+
description:
292+
"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.",
292293
params: [
293294
{
294295
kind: "number",

‎packages/core/src/audioFxCopy.test.ts‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { describe, expect, it } from "vitest";
2-
import { defaultAudioFxParams, HF_AUDIO_FX } from "./audioFx.js";
2+
import { defaultAudioFxParams, getAudioFxDef, HF_AUDIO_FX } from "./audioFx.js";
33
import { HF_AUDIO_FX_PRESETS } from "./audioFxPresets.js";
44
import { audioBandAt, BANDS, EFFECT_COPY, PRESET_PROBLEM, SUMMARY } from "./audioFxCopy.js";
55

@@ -197,3 +197,25 @@ describe("the true-peak copy does not promise a hard ceiling", () => {
197197
expect(hint).toMatch(/headroom/);
198198
});
199199
});
200+
201+
describe("the plain limiter copy does not promise a hard ceiling", () => {
202+
// The limiter follows the signal's level with no lookahead, and Level after is applied past
203+
// the ceiling, so a fast or inter-sample peak can end above it.
204+
it("says nothing about never clipping or nothing getting past", () => {
205+
const copy = EFFECT_COPY.limiter;
206+
const summary = SUMMARY.limiter;
207+
const description = getAudioFxDef("limiter")?.description;
208+
if (!copy || !summary || !description) throw new Error("limiter copy is missing");
209+
const shown = [
210+
description,
211+
copy.does,
212+
copy.reachFor,
213+
copy.params.limit?.label,
214+
summary({}),
215+
].join("\n");
216+
expect(shown).not.toMatch(
217+
/never|nothing|guarantee|hard ceiling|no louder|must not|cannot exceed/i,
218+
);
219+
expect(shown).toMatch(/can (still )?(get )?pass|get past/i);
220+
});
221+
});

‎packages/core/src/audioFxCopy.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -152,13 +152,13 @@ export const EFFECT_COPY: Record<string, EffectCopy> = {
152152
},
153153
limiter: {
154154
title: "Peak Ceiling",
155-
does: "Nothing gets louder than this, ever. A safety net at the end of the chain.",
156-
reachFor: "You want to be sure it never clips or spikes.",
155+
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.",
156+
reachFor: "You want peaks held down and can accept a small overshoot.",
157157
primary: "limit",
158158
primaryEnds: { low: "A lot of headroom", high: "Right up to the edge" },
159159
params: {
160160
limit: {
161-
label: "Never exceed",
161+
label: "Ceiling",
162162
ends: { low: "A lot of headroom", high: "Right up to the edge" },
163163
},
164164
attack: { label: "How fast it catches" },
@@ -411,7 +411,7 @@ export const SUMMARY: Record<string, (p: P) => string> = {
411411
: `${n(p.gain) > 0 ? "More" : "Less"} sparkle above ${hz(p.frequency)}`,
412412
compressor: (p) =>
413413
`Evening out, ${strength(Math.min(1, (n(p.ratio, 3) - 1) / 7), ["gentle", "moderate", "firm"])}`,
414-
limiter: (p) => `Nothing louder than ${n(p.limit, -1)} dB`,
414+
limiter: (p) => `Peaks pulled down toward ${n(p.limit, -1)} dB`,
415415
truepeak: (p) => `Peaks pulled down toward ${n(p.ceiling, -1)} dBTP`,
416416
gate: (p) => `Closing gaps quieter than ${n(p.threshold, -45)} dB`,
417417
saturate: (p) =>

‎packages/core/src/audioGroups.test.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import {
44
ensureAudioGroupInertStyle,
55
HF_AUDIO_GROUP_ATTR,
66
isMemberGroupHidden,
7+
readMasterFxChain,
78
resolveAudioGroups,
89
resolveCarveSourceIds,
910
resolveGroupElement,
@@ -305,3 +306,27 @@ describe("ensureAudioGroupInertStyle", () => {
305306
expect(document.querySelectorAll("#__hf-audio-group-inert")).toHaveLength(1);
306307
});
307308
});
309+
310+
describe("readMasterFxChain", () => {
311+
const CHAIN = `{&quot;version&quot;:1,&quot;nodes&quot;:[]}`;
312+
313+
it("reads the chain off the top-level composition root", () => {
314+
document.body.innerHTML = `<div data-composition-id="main" data-fx-chain="${CHAIN}"></div>`;
315+
expect(readMasterFxChain(document)).toBe('{"version":1,"nodes":[]}');
316+
});
317+
318+
it("is undefined when the root carries none", () => {
319+
document.body.innerHTML = `<div data-composition-id="main"><audio id="a"></audio></div>`;
320+
expect(readMasterFxChain(document)).toBeUndefined();
321+
});
322+
323+
it("ignores a chain on a nested composition root", () => {
324+
document.body.innerHTML = `<div data-composition-id="main"><div data-composition-id="inner" data-fx-chain="${CHAIN}"></div></div>`;
325+
expect(readMasterFxChain(document)).toBeUndefined();
326+
});
327+
328+
it("ignores a chain on a clip", () => {
329+
document.body.innerHTML = `<div data-composition-id="main"><audio id="a" data-fx-chain="${CHAIN}"></audio></div>`;
330+
expect(readMasterFxChain(document)).toBeUndefined();
331+
});
332+
});

‎packages/core/src/audioGroups.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,22 @@ export function isMemberGroupHidden(
128128
return resolveGroupElement(doc, groupId)?.hasAttribute("data-hidden") ?? false;
129129
}
130130

131+
/**
132+
* The top-level composition root, the only element the master bus is read from;
133+
* a sub-composition's root is skipped, so repeating one cannot stack chains.
134+
*/
135+
export function resolveMasterBusElement(root: ParentNode): Element | null {
136+
for (const el of root.querySelectorAll("[data-composition-id]")) {
137+
if (!el.parentElement?.closest("[data-composition-id]")) return el;
138+
}
139+
return null;
140+
}
141+
142+
/** The master bus chain: the top-level root's `data-fx-chain`, if it carries one. */
143+
export function readMasterFxChain(root: ParentNode): string | undefined {
144+
return resolveMasterBusElement(root)?.getAttribute(HF_AUDIO_FX_ATTR) || undefined;
145+
}
146+
131147
export function resolveAudioGroups(root: ParentNode): HfAudioGroup[] {
132148
const membersByGroup = new Map<string, string[]>();
133149
const candidates = root.querySelectorAll(

‎packages/core/src/runtime/audioFx.test.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// @vitest-environment happy-dom
22
import { describe, expect, it } from "vitest";
3-
import { attachElementFxChain } from "./audioFx.js";
3+
import { attachElementFxChain, type FxAttributes } from "./audioFx.js";
44
import { defaultAudioFxParams, HF_AUDIO_FX, HF_AUDIO_FX_ATTR } from "../audioFx.js";
55

66
/**
@@ -435,7 +435,7 @@ describe("attachElementFxChain", () => {
435435
],
436436
});
437437

438-
const build = () => {
438+
const build = (attrs?: FxAttributes) => {
439439
const clock = { currentTime: 0 };
440440
const made: { frequency: TimedParam }[] = [];
441441
class TimedNode extends Node {
@@ -461,6 +461,7 @@ describe("attachElementFxChain", () => {
461461
new Node() as never,
462462
new Node() as never,
463463
{ scheduledAt: 0, elapsed: 0, rate: 1 },
464+
attrs,
464465
);
465466
return { clock, node, handle, param: () => made[0]?.frequency as unknown as TimedParam };
466467
};
@@ -495,6 +496,14 @@ describe("attachElementFxChain", () => {
495496
expect(param().last()).toEqual({ time: 4, duration: 1 });
496497
});
497498

499+
it("books no lane for a chain told its element carries none (the master bus)", () => {
500+
// The root's `data-automation` belongs to the composition, not to the bus.
501+
const { param } = build({ automation: null });
502+
expect(param().last()).toBeUndefined();
503+
const { param: ownParam } = build();
504+
expect(ownParam().last()).toEqual({ time: 0, duration: 8 });
505+
});
506+
498507
it("ignores a rate that is not a rate", () => {
499508
const { clock, handle, param } = build();
500509
clock.currentTime = 2;

‎packages/core/src/runtime/audioFx.ts‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,9 @@ const NO_AUTOMATION: HfAutomation = { version: 1, lanes: [] };
3838
function readAutomation(
3939
el: { getAttribute?(name: string): string | null },
4040
chain: HfAudioFxChain,
41+
attr: string | null = HF_AUDIO_AUTOMATION_ATTR,
4142
): HfAutomation {
42-
const raw =
43-
(typeof el.getAttribute === "function" ? el.getAttribute(HF_AUDIO_AUTOMATION_ATTR) : null) ??
44-
"";
43+
const raw = (attr && typeof el.getAttribute === "function" ? el.getAttribute(attr) : null) ?? "";
4544
if (!raw) return NO_AUTOMATION;
4645
try {
4746
return resolveAutomation(parseAutomation(raw), chain);
@@ -119,12 +118,18 @@ export interface ElementFxHandle {
119118
setRate(rate: number): void;
120119
}
121120

121+
/** The attribute a chain's lanes are read from; the master bus has none. */
122+
export interface FxAttributes {
123+
automation: string | null;
124+
}
125+
122126
export function attachElementFxChain(
123127
ctx: BaseAudioContext,
124128
el: { getAttribute?(name: string): string | null },
125129
source: AudioNode,
126130
destination: AudioNode,
127131
timing?: AutomationTiming,
132+
attrs: FxAttributes = { automation: HF_AUDIO_AUTOMATION_ATTR },
128133
): ElementFxHandle | null {
129134
const { chain } = readChain(el);
130135

@@ -202,7 +207,13 @@ export function attachElementFxChain(
202207
const scheduleFor = (next: HfAudioFxChain, at: AutomationTiming | null): void => {
203208
automated =
204209
at && handle
205-
? scheduleChainAutomation(readAutomation(el, next), next, handle.nodes, at, handle.presets)
210+
? scheduleChainAutomation(
211+
readAutomation(el, next, attrs.automation),
212+
next,
213+
handle.nodes,
214+
at,
215+
handle.presets,
216+
)
206217
: [];
207218
};
208219

@@ -282,7 +293,7 @@ export function attachElementFxChain(
282293
});
283294
observer.observe(target, {
284295
attributes: true,
285-
attributeFilter: [HF_AUDIO_FX_ATTR, HF_AUDIO_AUTOMATION_ATTR],
296+
attributeFilter: attrs.automation ? [HF_AUDIO_FX_ATTR, attrs.automation] : [HF_AUDIO_FX_ATTR],
286297
});
287298
}
288299

0 commit comments

Comments
 (0)