Skip to content

Commit aa78532

Browse files
committed
fix(core): preserve solo bridge through stack
1 parent a2e2884 commit aa78532

4 files changed

Lines changed: 164 additions & 35 deletions

File tree

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,10 @@ import { createColorGradingRuntime, type RuntimeColorGradingApi } from "./colorG
4343
import { TransportClock } from "./clock";
4444
import { WebAudioTransport } from "./webAudioTransport";
4545
import {
46+
audioGroupOf,
4647
ensureAudioGroupInertStyle,
4748
HF_AUDIO_GROUP_TAG,
49+
isAudibleUnderSolo,
4850
isMemberGroupHidden,
4951
} from "../audioGroups";
5052
import { clampNativeMediaVolume } from "../audioGain";
@@ -187,7 +189,15 @@ export function initSandboxRuntimeModular(): void {
187189
void webAudio.init().then((ok) => {
188190
webAudioReady = ok;
189191
});
192+
// Keep Studio's session-only "Hear only this" bridge alive until the solo
193+
// controls are removed later in the stack. It must not be serialized into
194+
// the composition because solo is preview state, not authored state.
195+
let soloedIds: ReadonlySet<string> = new Set();
190196
window.__hf = window.__hf || {};
197+
window.__hf.setAudioSolo = (ids) => {
198+
soloedIds = new Set(ids);
199+
webAudio.setSolo(soloedIds);
200+
};
191201
/** Hidden by an ancestor, or by the BUS this clip belongs to. The bus is
192202
* never an ancestor — membership is on the member's `data-audio-group` — so
193203
* `closest()` alone could not see a muted group, which the render drops. */
@@ -2112,6 +2122,7 @@ export function initSandboxRuntimeModular(): void {
21122122
webAudio.setElementVolume(el, authorVolume),
21132123
isWebAudioOwned: (el) => webAudio.ownsElement(el),
21142124
isWebAudioRouted: (el) => webAudio.routesElement(el),
2125+
isAudibleUnderSolo: (el) => isAudibleUnderSolo(soloedIds, el.id, audioGroupOf(el)),
21152126
onAutoplayBlocked: () => {
21162127
if (state.mediaAutoplayBlockedPosted) return;
21172128
state.mediaAutoplayBlockedPosted = true;

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

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,9 @@ export function syncRuntimeMedia(params: {
224224
/** Native media routed through WebAudio keeps its upstream element volume at
225225
* unity; do not mistake that transport write for an authored volume edit. */
226226
isWebAudioRouted?: (el: HTMLMediaElement) => boolean;
227+
/** "Hear only this" gate for the HTMLMedia fallback path. WebAudio-owned
228+
* sources apply the same predicate on their dedicated solo gain. */
229+
isAudibleUnderSolo?: (el: HTMLMediaElement) => boolean;
227230
forceSync?: boolean;
228231
}): void {
229232
const forceMuteAll = !!(params.outputMuted || params.userMuted);
@@ -340,7 +343,9 @@ export function syncRuntimeMedia(params: {
340343
// fallback played at full level.
341344
const silencedByHidden =
342345
el.closest("[data-hidden]") !== null || isMemberGroupHidden(el.ownerDocument, el);
343-
const effectiveVolume = silencedByHidden ? 0 : clampVolume(authorVolume * userVol);
346+
const silencedBySolo = params.isAudibleUnderSolo ? !params.isAudibleUnderSolo(el) : false;
347+
const effectiveVolume =
348+
silencedByHidden || silencedBySolo ? 0 : clampVolume(authorVolume * userVol);
344349
el.volume = effectiveVolume;
345350
lastRuntimeAppliedVolume.set(el, effectiveVolume);
346351
params.onElementVolume?.(el, effectiveVolume, authorVolume);

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

Lines changed: 83 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,20 @@ function createMockAudioContext(currentTime = 100) {
1818
}),
1919
_fireEnded: () => endedListeners.forEach((cb) => cb()),
2020
};
21-
const gainNode = {
22-
gain: { value: 1 },
23-
connect: vi.fn(),
24-
disconnect: vi.fn(),
21+
// Every createGain call returns a distinct node. Sharing one hides graph
22+
// errors because the solo stage can overwrite the authored-volume stage.
23+
const gainNodes: Array<{
24+
gain: { value: number };
25+
connect: ReturnType<typeof vi.fn>;
26+
disconnect: ReturnType<typeof vi.fn>;
27+
}> = [];
28+
const makeGain = () => {
29+
const node = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
30+
gainNodes.push(node);
31+
return node;
2532
};
33+
const gainNode = makeGain();
34+
let served = 0;
2635
const mediaElementSourceNode = {
2736
connect: vi.fn(),
2837
disconnect: vi.fn(),
@@ -37,11 +46,11 @@ function createMockAudioContext(currentTime = 100) {
3746
resume: vi.fn(),
3847
createBufferSource: vi.fn(() => sourceNode),
3948
createMediaElementSource: vi.fn(() => mediaElementSourceNode),
40-
createGain: vi.fn(() => gainNode),
49+
createGain: vi.fn(() => (served++ === 0 ? gainNode : makeGain())),
4150
destination: {},
4251
close: vi.fn(),
4352
};
44-
return { ctx, sourceNode, mediaElementSourceNode, gainNode, masterGain, startFn };
53+
return { ctx, sourceNode, mediaElementSourceNode, gainNode, gainNodes, masterGain, startFn };
4554
}
4655

4756
function setupTransport(currentTime = 100) {
@@ -112,7 +121,9 @@ describe("WebAudioTransport", () => {
112121
expect(mock.ctx.createMediaElementSource).toHaveBeenCalledWith(mockEl);
113122
expect(mock.ctx.createBufferSource).not.toHaveBeenCalled();
114123
expect(mock.mediaElementSourceNode.connect).toHaveBeenCalled();
115-
expect(mock.gainNode.connect).toHaveBeenCalledWith(mock.masterGain);
124+
const [volumeGain, soloGain] = mock.gainNodes;
125+
expect(volumeGain?.connect).toHaveBeenCalledWith(soloGain);
126+
expect(soloGain?.connect).toHaveBeenCalledWith(mock.masterGain);
116127
expect(mockEl.muted).toBe(false);
117128
expect(mockEl.volume).toBe(1);
118129
expect(mock.gainNode.gain.value).toBe(0.8);
@@ -737,15 +748,15 @@ describe("WebAudioTransport", () => {
737748
document.body.innerHTML = "";
738749
});
739750

740-
it("routes an ungrouped clip straight to master through its own gain", async () => {
751+
it("routes an ungrouped clip to master through its own solo stage", async () => {
741752
const { transport, mock, gen } = setupGroupTransport();
742753

743754
await scheduleGrouped(transport, gen, "lone");
744755

745-
// One gain per clip now that solo is gone — it goes straight to master.
746-
expect(mock.gainNodes).toHaveLength(1);
747-
const [clipGain] = mock.gainNodes;
748-
expect(clipGain!.connect).toHaveBeenCalledWith(mock.masterGain);
756+
expect(mock.gainNodes).toHaveLength(2);
757+
const [clipGain, soloGain] = mock.gainNodes;
758+
expect(clipGain!.connect).toHaveBeenCalledWith(soloGain);
759+
expect(soloGain!.connect).toHaveBeenCalledWith(mock.masterGain);
749760
});
750761

751762
// The media-element transport is the PRIMARY path for audio — the runtime
@@ -790,7 +801,9 @@ describe("WebAudioTransport", () => {
790801
await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
791802

792803
const clipGain = mock.gainNodes[0]!;
793-
expect(clipGain.connect).toHaveBeenCalledWith(firstGroupInput(mock));
804+
const soloGain = mock.gainNodes[5]!;
805+
expect(clipGain.connect).toHaveBeenCalledWith(soloGain);
806+
expect(soloGain.connect).toHaveBeenCalledWith(firstGroupInput(mock));
794807
expect(clipGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
795808
});
796809

@@ -800,8 +813,9 @@ describe("WebAudioTransport", () => {
800813

801814
await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
802815

803-
expect(mock.gainNodes).toHaveLength(1);
804-
expect(mock.gainNodes[0]!.connect).toHaveBeenCalledWith(mock.masterGain);
816+
expect(mock.gainNodes).toHaveLength(2);
817+
expect(mock.gainNodes[0]!.connect).toHaveBeenCalledWith(mock.gainNodes[1]);
818+
expect(mock.gainNodes[1]!.connect).toHaveBeenCalledWith(mock.masterGain);
805819
});
806820

807821
it("two members of the same group land on ONE shared group gain, not master directly", async () => {
@@ -810,20 +824,23 @@ describe("WebAudioTransport", () => {
810824
await scheduleGrouped(transport, gen, "a", "vo");
811825
await scheduleGrouped(transport, gen, "b", "vo");
812826

813-
// Creation order for a: a-gain(0), groupInput(1), groupOutput(2),
814-
// muteGain(3), fader(4) — the group bus is built lazily inside a's
815-
// schedule call. Then b: b-gain(5).
816-
expect(mock.gainNodes.length).toBeGreaterThanOrEqual(6);
827+
// Creation order for a: gain(0), group bus(1–4), solo(5). Then b uses
828+
// gain(6), solo(7); both solo stages feed the one shared group input.
829+
expect(mock.gainNodes.length).toBeGreaterThanOrEqual(8);
817830
const aGain = mock.gainNodes[0]!;
831+
const aSolo = mock.gainNodes[5]!;
818832
const groupInput = firstGroupInput(mock);
819833
const groupOutput = mock.gainNodes[2]!;
820834
const muteGain = mock.gainNodes[3]!;
821835
const fader = mock.gainNodes[4]!;
822-
const bGain = mock.gainNodes[5]!;
823-
824-
// Both members feed the shared bus — neither connects straight to master.
825-
expect(aGain.connect).toHaveBeenCalledWith(groupInput);
826-
expect(bGain.connect).toHaveBeenCalledWith(groupInput);
836+
const bGain = mock.gainNodes[6]!;
837+
const bSolo = mock.gainNodes[7]!;
838+
839+
// Both members feed their own solo stage, then the shared bus.
840+
expect(aGain.connect).toHaveBeenCalledWith(aSolo);
841+
expect(bGain.connect).toHaveBeenCalledWith(bSolo);
842+
expect(aSolo.connect).toHaveBeenCalledWith(groupInput);
843+
expect(bSolo.connect).toHaveBeenCalledWith(groupInput);
827844
expect(aGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
828845
expect(bGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
829846

@@ -843,11 +860,11 @@ describe("WebAudioTransport", () => {
843860
const { transport, mock, gen } = setupGroupTransport();
844861

845862
await scheduleGrouped(transport, gen, "a", "vo");
846-
const gainCountAfterFirst = mock.gainNodes.length; // a-gain + group input/output/mute/fader
863+
const gainCountAfterFirst = mock.gainNodes.length;
847864
await scheduleGrouped(transport, gen, "b", "vo");
848865

849-
// Only b's own gain is new — no second group bus minted.
850-
expect(mock.gainNodes.length).toBe(gainCountAfterFirst + 1);
866+
// Only b's volume and solo gains are new — no second group bus minted.
867+
expect(mock.gainNodes.length).toBe(gainCountAfterFirst + 2);
851868
});
852869

853870
it("a group id with no matching <hf-audio-group> element still gets a flat bus", async () => {
@@ -913,6 +930,45 @@ describe("WebAudioTransport", () => {
913930
expect(mock.gainNodes.filter((n) => n === groupInput)).toHaveLength(1);
914931
});
915932

933+
describe('solo — "Hear only this" compatibility bridge', () => {
934+
it("silences non-soloed members without attenuating their shared group bus", async () => {
935+
const { transport, mock, gen } = setupGroupTransport();
936+
await scheduleGrouped(transport, gen, "a", "vo");
937+
await scheduleGrouped(transport, gen, "b", "vo");
938+
939+
transport.setSolo(new Set(["a"]));
940+
941+
expect(mock.gainNodes[5]!.gain.value).toBe(1);
942+
expect(mock.gainNodes[7]!.gain.value).toBe(0);
943+
expect(firstGroupInput(mock).gain.value).toBe(1);
944+
});
945+
946+
it("soloing a group keeps every member of that group audible", async () => {
947+
const { transport, mock, gen } = setupGroupTransport();
948+
await scheduleGrouped(transport, gen, "a", "vo");
949+
await scheduleGrouped(transport, gen, "b", "vo");
950+
951+
transport.setSolo(new Set(["vo"]));
952+
953+
expect(mock.gainNodes[5]!.gain.value).toBe(1);
954+
expect(mock.gainNodes[7]!.gain.value).toBe(1);
955+
});
956+
957+
it("applies an existing solo to newly scheduled clips and restores them when cleared", async () => {
958+
const { transport, mock, gen } = setupGroupTransport();
959+
transport.setSolo(new Set(["a"]));
960+
await scheduleGrouped(transport, gen, "a");
961+
await scheduleGrouped(transport, gen, "b");
962+
963+
expect(mock.gainNodes[1]!.gain.value).toBe(1);
964+
expect(mock.gainNodes[3]!.gain.value).toBe(0);
965+
966+
transport.setSolo(new Set());
967+
expect(mock.gainNodes[1]!.gain.value).toBe(1);
968+
expect(mock.gainNodes[3]!.gain.value).toBe(1);
969+
});
970+
});
971+
916972
// Surviving stopAll() is the point of the bus — and the trap. Its envelopes
917973
// were booked against the FIRST pass's absolute context times, so a replay
918974
// or a seek left the fader holding that pass's last value: 0 after a

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

Lines changed: 64 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,12 @@ import {
66
type AutomationTiming,
77
} from "../audio/audioFxAutomation.js";
88
import { VOLUME_RANGE } from "../audioAutomation.js";
9-
import { audioGroupOf, readAudioGroupVolume, resolveGroupElement } from "../audioGroups.js";
9+
import {
10+
audioGroupOf,
11+
isAudibleUnderSolo,
12+
readAudioGroupVolume,
13+
resolveGroupElement,
14+
} from "../audioGroups.js";
1015
import { swallow } from "./diagnostics";
1116
import { clampAudioGain } from "../audioGain.js";
1217
import { getDebugSurface } from "./globals.js";
@@ -106,6 +111,8 @@ function scheduleVolumeLane(
106111
type ScheduledSourceBase = {
107112
el: HTMLMediaElement;
108113
gainNode: GainNode;
114+
/** Dedicated solo stage so toggles never overwrite authored volume ramps. */
115+
soloGain: GainNode;
109116
/** FX chain spliced between source and gain, when the element carries one. */
110117
fx?: ElementFxHandle | null;
111118
compositionStart: number;
@@ -169,6 +176,8 @@ export class WebAudioTransport {
169176
private _rate = 1;
170177
private _paused = true;
171178
private _playGeneration = 0;
179+
// Session-only preview state pushed by Studio. Never serialized.
180+
private _soloed: ReadonlySet<string> = new Set();
172181

173182
async init(): Promise<boolean> {
174183
try {
@@ -242,6 +251,26 @@ export class WebAudioTransport {
242251
return this._playGeneration;
243252
}
244253

254+
/** Connect one source through its own solo stage and then into its group bus
255+
* (or master for an ungrouped clip). Resolving the group first preserves one
256+
* shared bus while solo remains strictly per member. */
257+
private connectThroughSolo(
258+
ctx: AudioContext,
259+
masterGain: GainNode,
260+
el: HTMLMediaElement,
261+
gainNode: GainNode,
262+
timing: { scheduledAt: number; compositionTime: number; rate: number },
263+
): GainNode {
264+
const destination =
265+
this.resolveDestination(el, timing.scheduledAt, timing.compositionTime, timing.rate) ??
266+
masterGain;
267+
const soloGain = ctx.createGain();
268+
soloGain.gain.value = isAudibleUnderSolo(this._soloed, el.id, audioGroupOf(el)) ? 1 : 0;
269+
gainNode.connect(soloGain);
270+
soloGain.connect(destination);
271+
return soloGain;
272+
}
273+
245274
/**
246275
* Route the browser's pitch-preserving HTMLMediaElement transport through the
247276
* same FX, automation, element-gain, and master graph used by final audio.
@@ -282,9 +311,11 @@ export class WebAudioTransport {
282311
// its fallback), so routing it at master would have left every grouped
283312
// track bypassing the bus whose whole premise is that a group is one
284313
// signal.
285-
gainNode.connect(
286-
this.resolveDestination(el, scheduledAt, compositionTime, safeRate) ?? this._masterGain,
287-
);
314+
const soloGain = this.connectThroughSolo(this._ctx, this._masterGain, el, gainNode, {
315+
scheduledAt,
316+
compositionTime,
317+
rate: safeRate,
318+
});
288319
scheduleVolumeLane(el, gainNode, timing);
289320

290321
this._rate = safeRate;
@@ -297,6 +328,7 @@ export class WebAudioTransport {
297328
sourceNode,
298329
sourceKind: "media-element",
299330
gainNode,
331+
soloGain,
300332
compositionStart,
301333
mediaStart: _mediaStart,
302334
scheduledAt,
@@ -483,6 +515,7 @@ export class WebAudioTransport {
483515
sourceNode.disconnect();
484516
scheduled.fx?.dispose();
485517
scheduled.gainNode.disconnect();
518+
scheduled.soloGain.disconnect();
486519
} catch {
487520
// Already torn down.
488521
}
@@ -535,9 +568,11 @@ export class WebAudioTransport {
535568
// output — the same order the offline render uses. Preview and render run
536569
// the identical graph builders, so what is heard here is what is written.
537570
const fx = attachElementFxChain(this._ctx, el, sourceNode, gainNode, timing);
538-
gainNode.connect(
539-
this.resolveDestination(el, scheduledAt, compositionTime, safeRate) ?? this._masterGain,
540-
);
571+
const soloGain = this.connectThroughSolo(this._ctx, this._masterGain, el, gainNode, {
572+
scheduledAt,
573+
compositionTime,
574+
rate: safeRate,
575+
});
541576

542577
scheduleVolumeLane(el, gainNode, timing);
543578

@@ -559,6 +594,7 @@ export class WebAudioTransport {
559594
sourceNode.disconnect();
560595
fx?.dispose();
561596
gainNode.disconnect();
597+
soloGain.disconnect();
562598
return null;
563599
}
564600

@@ -572,6 +608,7 @@ export class WebAudioTransport {
572608
sourceNode,
573609
sourceKind: "buffer",
574610
gainNode,
611+
soloGain,
575612
compositionStart,
576613
mediaStart,
577614
scheduledAt,
@@ -653,6 +690,7 @@ export class WebAudioTransport {
653690
source.sourceNode.disconnect();
654691
source.fx?.dispose();
655692
source.gainNode.disconnect();
693+
source.soloGain.disconnect();
656694
} catch {
657695
// already stopped
658696
}
@@ -697,6 +735,25 @@ export class WebAudioTransport {
697735
this.applyMasterGain();
698736
}
699737

738+
/** Update every active source without rebuilding the graph. Group ids solo
739+
* all members through the shared audibility predicate. */
740+
setSolo(soloed: ReadonlySet<string>): void {
741+
this._soloed = soloed;
742+
for (const source of this._activeSources) {
743+
try {
744+
source.soloGain.gain.value = isAudibleUnderSolo(
745+
this._soloed,
746+
source.el.id,
747+
audioGroupOf(source.el),
748+
)
749+
? 1
750+
: 0;
751+
} catch (err) {
752+
swallow("webAudioTransport.setSolo", err);
753+
}
754+
}
755+
}
756+
700757
private applyMasterGain(): void {
701758
if (this._masterGain) this._masterGain.gain.value = this._masterMuted ? 0 : this._masterVolume;
702759
}

0 commit comments

Comments
 (0)