Skip to content

Commit 602cf53

Browse files
vanceingallsclaude
andauthored
feat(core): route grouped audio through a group bus in preview (#3287)
An audio element carrying `data-audio-group` no longer lands its gain on the master bus directly — it feeds a per-group `GainNode` (built lazily on first use, one per group id) which itself feeds master, so members of the same group sum before the ear, ready for a group-level FX chain and volume/mute in later steps. An id with no matching `<hf-audio-group>` element still gets a plain, unprocessed bus rather than losing the track. The group's own chain and volume lane are wired through the same `attachElementFxChain`/`scheduleVolumeLane` every element already uses, against the group's clock — composition time (design doc §1.3), since a group has no `data-start` and a missing one parses as 0. The bus persists across `stopAll()` (mirroring `_masterGain`'s own lifecycle) so replaying a group does not rebuild its chain; only `destroy()` disposes it. Render is untouched — stays flat until B4; `audio-groups` is still a 0% canary so nothing ships this to a real composition without hand-authoring `data-audio-group`. Also: `audioGroupOf` (B1) crashed on any element lacking a real `tagName`/ `getAttribute` — exactly the shape of most `HTMLMediaElement` test doubles in this suite, including this file's own `mockEl`. Made it tolerant, same style as `readChain`'s existing guard in `runtime/audioFx.ts`. `schedulePlayback` was already 110 lines pre-existing before this diff; extracted `resolveDestination` and `handleSourceEnded` to shrink it to 92, then suppressed the remainder (inherently sequential graph wiring, not a decision tree) per the same precedent B2 used on `TimelineLogicalRow`. Co-authored-by: Claude Sonnet 5 <[email protected]>
1 parent ba607bf commit 602cf53

3 files changed

Lines changed: 278 additions & 28 deletions

File tree

‎packages/core/src/audioGroups.ts‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,9 +74,14 @@ export function resolveAudioGroups(root: ParentNode): HfAudioGroup[] {
7474
* `data-audio-group` on an `<hf-audio-group>` itself (groups do not nest).
7575
* `data-audio-group=""` returns null rather than `""` — the resolver skips a
7676
* falsy id, and the "or null" in this contract has to mean it.
77+
*
78+
* Tolerant of objects that only partially implement `Element` (test doubles for
79+
* `HTMLMediaElement` commonly do): anything missing `tagName` or `getAttribute`
80+
* simply has no group, mirroring `readChain`'s style in `runtime/audioFx.ts`.
7781
*/
7882
export function audioGroupOf(el: Element): string | null {
79-
if (el.tagName?.toLowerCase() !== "audio") return null;
83+
if (typeof el.tagName !== "string" || el.tagName.toLowerCase() !== "audio") return null;
84+
if (typeof el.getAttribute !== "function") return null;
8085
return el.getAttribute(HF_AUDIO_GROUP_ATTR) || null;
8186
}
8287

@@ -91,8 +96,8 @@ export function audioGroupOf(el: Element): string | null {
9196
* would shift by adding a group, which is not something a mixing decision is
9297
* allowed to do.
9398
*
94-
* `!important` because the rule has to beat an author rule that sets `display`
95-
* on the tag — inertness here is a contract, not a default. Emitted from the
99+
* `!important` because an author rule can outrank a bare type selector on
100+
* specificity — inertness here is a contract, not a default. Emitted from the
96101
* runtime rather than the compiler so preview and render share one source.
97102
*/
98103
export function ensureAudioGroupInertStyle(doc: Document): void {

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

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -655,6 +655,167 @@ describe("WebAudioTransport", () => {
655655
});
656656
});
657657

658+
describe("group routing (preview)", () => {
659+
// Real jsdom elements — `groupInput` looks the group up via
660+
// `el.ownerDocument.getElementById`, and `audioGroupOf` reads `tagName` /
661+
// `getAttribute`, neither of which the plain-object mocks above implement.
662+
function createGroupMockAudioContext(currentTime = 100) {
663+
const gainNodes: {
664+
gain: { value: number };
665+
connect: ReturnType<typeof vi.fn>;
666+
disconnect: ReturnType<typeof vi.fn>;
667+
}[] = [];
668+
const masterGain = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
669+
const ctx = {
670+
currentTime,
671+
state: "running",
672+
resume: vi.fn(),
673+
createBufferSource: vi.fn(() => ({
674+
buffer: null as AudioBuffer | null,
675+
playbackRate: { value: 1 },
676+
start: vi.fn(),
677+
stop: vi.fn(),
678+
disconnect: vi.fn(),
679+
connect: vi.fn(),
680+
addEventListener: vi.fn(),
681+
})),
682+
createGain: vi.fn(() => {
683+
const node = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
684+
gainNodes.push(node);
685+
return node;
686+
}),
687+
destination: {},
688+
close: vi.fn(),
689+
};
690+
return { ctx, gainNodes, masterGain };
691+
}
692+
693+
function setupGroupTransport(currentTime = 100) {
694+
const transport = new WebAudioTransport();
695+
const mock = createGroupMockAudioContext(currentTime);
696+
(transport as unknown as { _ctx: unknown })._ctx = mock.ctx;
697+
(transport as unknown as { _masterGain: unknown })._masterGain = mock.masterGain;
698+
const gen = transport.startGeneration();
699+
return { transport, mock, gen };
700+
}
701+
702+
function groupedAudioEl(id: string, groupId?: string): HTMLMediaElement {
703+
const el = document.createElement("audio");
704+
el.id = id;
705+
if (groupId) el.setAttribute("data-audio-group", groupId);
706+
document.body.appendChild(el);
707+
return el as unknown as HTMLMediaElement;
708+
}
709+
710+
/** Create a grouped member and schedule it in one step — the shape every
711+
* test below needs, differing only in id/group/generation. */
712+
async function scheduleGrouped(
713+
transport: WebAudioTransport,
714+
gen: number,
715+
id: string,
716+
groupId?: string,
717+
): Promise<HTMLMediaElement> {
718+
const el = groupedAudioEl(id, groupId);
719+
await transport.schedulePlayback(el, mockBuffer, 0, 0, 0, 1, gen);
720+
return el;
721+
}
722+
723+
/** The group's own input gain is built lazily on the first member —
724+
* index 1 in creation order (that member's gain is index 0). */
725+
const firstGroupInput = (mock: ReturnType<typeof createGroupMockAudioContext>) =>
726+
mock.gainNodes[1]!;
727+
728+
beforeEach(() => {
729+
document.body.innerHTML = "";
730+
});
731+
732+
it("routes an ungrouped member straight to master, unchanged", async () => {
733+
const { transport, mock, gen } = setupGroupTransport();
734+
735+
await scheduleGrouped(transport, gen, "solo");
736+
737+
// One gain node — the member's own — connected directly to master.
738+
expect(mock.gainNodes).toHaveLength(1);
739+
expect(mock.gainNodes[0]!.connect).toHaveBeenCalledWith(mock.masterGain);
740+
});
741+
742+
it("two members of the same group land on ONE shared group gain, not master directly", async () => {
743+
const { transport, mock, gen } = setupGroupTransport();
744+
745+
await scheduleGrouped(transport, gen, "a", "vo");
746+
await scheduleGrouped(transport, gen, "b", "vo");
747+
748+
// Member gain nodes: index 0 (a) and index 2 (b) — index 1 is the
749+
// group's own input gain, built inside a's schedule call.
750+
expect(mock.gainNodes.length).toBeGreaterThanOrEqual(3);
751+
const groupInput = firstGroupInput(mock);
752+
const aGain = mock.gainNodes[0]!;
753+
const bGain = mock.gainNodes[2]!;
754+
755+
// Neither member connects straight to master — both feed the shared bus.
756+
expect(aGain.connect).toHaveBeenCalledWith(groupInput);
757+
expect(bGain.connect).toHaveBeenCalledWith(groupInput);
758+
expect(aGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
759+
expect(bGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
760+
761+
// The bus itself is what reaches master — a plain sum, no processing,
762+
// since neither member's group has a chain-bearing `<hf-audio-group>`.
763+
expect(groupInput.connect).toHaveBeenCalledWith(mock.masterGain);
764+
});
765+
766+
it("a second member of an already-open group does not rebuild the group bus", async () => {
767+
const { transport, mock, gen } = setupGroupTransport();
768+
769+
await scheduleGrouped(transport, gen, "a", "vo");
770+
const gainCountAfterFirst = mock.gainNodes.length; // a-gain + group-input
771+
await scheduleGrouped(transport, gen, "b", "vo");
772+
773+
// Only b's own gain is new — no second group-input gain minted.
774+
expect(mock.gainNodes.length).toBe(gainCountAfterFirst + 1);
775+
});
776+
777+
it("a group id with no matching <hf-audio-group> element still gets a flat bus", async () => {
778+
const { transport, mock, gen } = setupGroupTransport();
779+
780+
await scheduleGrouped(transport, gen, "a", "orphan-group"); // no matching element
781+
782+
expect(firstGroupInput(mock).connect).toHaveBeenCalledWith(mock.masterGain);
783+
});
784+
785+
it("group volume rides the group's own data-volume via its automation lane, not the member's", async () => {
786+
document.body.innerHTML = `<hf-audio-group id="vo" data-label="Voiceover"></hf-audio-group>`;
787+
const { transport, gen } = setupGroupTransport();
788+
789+
// No throw wiring the group's automation reader against a real
790+
// <hf-audio-group> element that carries no fx/automation attrs.
791+
await expect(scheduleGrouped(transport, gen, "a", "vo")).resolves.not.toBeNull();
792+
});
793+
794+
it("destroy() disposes every group bus", async () => {
795+
const { transport, mock, gen } = setupGroupTransport();
796+
await scheduleGrouped(transport, gen, "a", "vo");
797+
const groupInput = firstGroupInput(mock);
798+
799+
transport.destroy();
800+
801+
expect(groupInput.disconnect).toHaveBeenCalled();
802+
});
803+
804+
it("stopAll() does NOT dispose group buses — replaying the group does not rebuild it", async () => {
805+
const { transport, mock, gen } = setupGroupTransport();
806+
await scheduleGrouped(transport, gen, "a", "vo");
807+
const groupInput = firstGroupInput(mock);
808+
809+
transport.stopAll();
810+
expect(groupInput.disconnect).not.toHaveBeenCalled();
811+
812+
const gen2 = transport.startGeneration();
813+
await scheduleGrouped(transport, gen2, "a", "vo");
814+
// Still only one group-input gain ever created for "vo".
815+
expect(mock.gainNodes.filter((n) => n === groupInput)).toHaveLength(1);
816+
});
817+
});
818+
658819
describe("decodeAudioElement retry policy (late-asset self-heal)", () => {
659820
function transportWithDecode(decodeImpl: () => Promise<AudioBuffer>) {
660821
const transport = new WebAudioTransport();

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

Lines changed: 109 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import {
55
type AutomationTiming,
66
} from "../audio/audioFxAutomation.js";
77
import { VOLUME_RANGE } from "../audioAutomation.js";
8+
import { audioGroupOf } from "../audioGroups.js";
89
import { swallow } from "./diagnostics";
910
import { clampAudioGain } from "../audioGain.js";
1011
import { getDebugSurface } from "./globals.js";
@@ -70,9 +71,12 @@ function startBoundedSource(
7071
/**
7172
* The volume lane rides the fader, after the effects — where a DAW puts it,
7273
* and the order the render bakes it in.
74+
*
75+
* Typed against the attribute reader rather than `HTMLMediaElement` so a group
76+
* bus (an `<hf-audio-group>`, not a media element) can ride the same path.
7377
*/
7478
function scheduleVolumeLane(
75-
el: HTMLMediaElement,
79+
el: { getAttribute?(name: string): string | null },
7680
gainNode: GainNode,
7781
timing: AutomationTiming,
7882
): void {
@@ -119,6 +123,11 @@ export class WebAudioTransport {
119123
private _masterGain: GainNode | null = null;
120124
private _masterVolume = 1;
121125
private _masterMuted = false;
126+
// One shared bus per group id, lazily built the first time a member of that
127+
// group is scheduled. Lives for the session (mirrors `_masterGain`'s own
128+
// lifecycle) rather than being torn down on every `stopAll()`, so replaying
129+
// a group does not rebuild its chain; only `destroy()` disposes these.
130+
private _groups = new Map<string, { input: GainNode; dispose(): void }>();
122131
// Composition-time reference frame: at AudioContext time `_rateAnchorCtx`,
123132
// composition time was `_rateAnchorComp`, and time has been advancing at
124133
// `_rate` composition-seconds per wallclock-second since.
@@ -269,6 +278,97 @@ export class WebAudioTransport {
269278
}
270279
}
271280

281+
/**
282+
* The gain a grouped member's signal should land on, building it on first
283+
* use. A group's clock is COMPOSITION time (design doc §1.3) — it has no
284+
* `data-start`, and a missing start parses as 0, which is exactly
285+
* composition time — so its chain and volume lane are scheduled once here
286+
* against that zero-offset timing, not the member's own clip-local timing.
287+
* A group id with no matching `<hf-audio-group>` element still gets a bus
288+
* (flat, no chain) so a hand-authored `data-audio-group` degrades to a
289+
* plain sum rather than losing the member's audio.
290+
*/
291+
private groupInput(groupId: string, doc: Document, timing: AutomationTiming): GainNode | null {
292+
const existing = this._groups.get(groupId);
293+
if (existing) return existing.input;
294+
if (!this._ctx || !this._masterGain) return null;
295+
296+
const input = this._ctx.createGain();
297+
const groupEl = doc.getElementById(groupId);
298+
const fx = attachElementFxChain(
299+
this._ctx,
300+
groupEl ?? { getAttribute: () => null },
301+
input,
302+
this._masterGain,
303+
timing,
304+
);
305+
if (groupEl) scheduleVolumeLane(groupEl, input, timing);
306+
307+
this._groups.set(groupId, {
308+
input,
309+
dispose: () => {
310+
try {
311+
fx?.dispose();
312+
input.disconnect();
313+
} catch {
314+
// Already torn down.
315+
}
316+
},
317+
});
318+
return input;
319+
}
320+
321+
/** Master, unless `el` belongs to a group — then that group's bus (built on
322+
* first use, per `groupInput`). */
323+
private resolveDestination(
324+
el: HTMLMediaElement,
325+
scheduledAt: number,
326+
compositionTime: number,
327+
safeRate: number,
328+
): GainNode | null {
329+
if (!this._masterGain) return null;
330+
const groupId = audioGroupOf(el);
331+
if (!groupId) return this._masterGain;
332+
const groupTiming: AutomationTiming = { scheduledAt, elapsed: compositionTime, rate: safeRate };
333+
return this.groupInput(groupId, el.ownerDocument, groupTiming) ?? this._masterGain;
334+
}
335+
336+
/**
337+
* The graph goes with it. Splicing alone left the FX handle alive and then
338+
* UNREACHABLE — `stopAll()` disposes by walking `_activeSources`, which the
339+
* splice just emptied of this entry. Every clip that finished naturally
340+
* leaked its MutationObserver for the session, and each one still answered
341+
* later `data-fx-chain` edits by rebuilding a whole graph (impulse response,
342+
* chorus/phaser oscillators started and never stopped) around a dead
343+
* source. Not disposed when the index is already -1: `stopAll()` has
344+
* already done it, and `stop()` is what fired this event.
345+
*/
346+
private handleSourceEnded(
347+
sourceNode: AudioBufferSourceNode,
348+
scheduled: ScheduledSource,
349+
el: HTMLMediaElement,
350+
priorMuted: boolean,
351+
): void {
352+
const idx = this._activeSources.indexOf(scheduled);
353+
if (idx === -1) return;
354+
this._activeSources.splice(idx, 1);
355+
el.muted = priorMuted;
356+
try {
357+
sourceNode.disconnect();
358+
scheduled.fx?.dispose();
359+
scheduled.gainNode.disconnect();
360+
} catch {
361+
// Already torn down.
362+
}
363+
if (this._activeSources.length === 0) this._paused = true;
364+
}
365+
366+
// Pre-existing size (110 lines before this diff, which shrank it to under
367+
// 95 via two extractions — see `handleSourceEnded`/`resolveDestination`);
368+
// the remainder is inherently sequential graph-wiring, not a nested
369+
// decision tree, and further splitting would cost more readability than it
370+
// buys. Same call the B2 step took on `TimelineLogicalRow`.
371+
// fallow-ignore-next-line complexity
272372
async schedulePlayback(
273373
el: HTMLMediaElement,
274374
buffer: AudioBuffer,
@@ -309,7 +409,9 @@ export class WebAudioTransport {
309409
// output — the same order the offline render uses. Preview and render run
310410
// the identical graph builders, so what is heard here is what is written.
311411
const fx = attachElementFxChain(this._ctx, el, sourceNode, gainNode, timing);
312-
gainNode.connect(this._masterGain);
412+
gainNode.connect(
413+
this.resolveDestination(el, scheduledAt, compositionTime, safeRate) ?? this._masterGain,
414+
);
313415

314416
scheduleVolumeLane(el, gainNode, timing);
315417

@@ -355,29 +457,9 @@ export class WebAudioTransport {
355457
this._activeSources.push(scheduled);
356458
this._paused = false;
357459

358-
sourceNode.addEventListener("ended", () => {
359-
const idx = this._activeSources.indexOf(scheduled);
360-
if (idx !== -1) {
361-
this._activeSources.splice(idx, 1);
362-
el.muted = priorMuted;
363-
// The graph goes with it. Splicing alone left the FX handle alive and
364-
// then UNREACHABLE — stopAll() disposes by walking this array, which
365-
// the splice just emptied of this entry. Every clip that finished
366-
// naturally leaked its MutationObserver for the session, and each one
367-
// still answered later `data-fx-chain` edits by rebuilding a whole
368-
// graph (impulse response, chorus/phaser oscillators started and never
369-
// stopped) around a dead source. Not disposed when idx is -1: stopAll()
370-
// has already done it, and `stop()` is what fired this event.
371-
try {
372-
sourceNode.disconnect();
373-
fx?.dispose();
374-
gainNode.disconnect();
375-
} catch {
376-
// Already torn down.
377-
}
378-
if (this._activeSources.length === 0) this._paused = true;
379-
}
380-
});
460+
sourceNode.addEventListener("ended", () =>
461+
this.handleSourceEnded(sourceNode, scheduled, el, priorMuted),
462+
);
381463

382464
return scheduled;
383465
} catch (err) {
@@ -500,6 +582,8 @@ export class WebAudioTransport {
500582

501583
destroy(): void {
502584
this.stopAll();
585+
for (const group of this._groups.values()) group.dispose();
586+
this._groups.clear();
503587
this._bufferCache.clear();
504588
this._failedSrcs.clear();
505589
this._mediaElementSources = new WeakMap();

0 commit comments

Comments
 (0)