Skip to content

Commit 9742073

Browse files
feat(studio): audio level meters at the timeline's right edge (#4193)
* feat(studio): audio level meters at the timeline's right edge * test(core): cover metering started before the audio context finishes init * fix(studio): keep meter follow after a dead preview and start bars at silence * fix(studio): keep the 0 dB peak tick inside the meter * fix(studio): keep the 0 dB peak tick visible without calc() * fix(core): tap meters on the program bus, mute on a monitor gain * style(core): wrap applyMasterGain to satisfy oxfmt
1 parent badf49b commit 9742073

14 files changed

Lines changed: 784 additions & 34 deletions

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2743,6 +2743,11 @@ export function initSandboxRuntimeModular(): void {
27432743
};
27442744
window.__hf.leasePausedMedia = leasePausedMedia;
27452745
window.__hf.releasePausedMedia = releasePausedMedia;
2746+
window.__hf.audioMeter = {
2747+
start: () => webAudio.startMetering(),
2748+
stop: () => webAudio.stopMetering(),
2749+
read: () => webAudio.readLevels(),
2750+
};
27462751

27472752
// Same predicate the media cache uses, so the paused side sees exactly the
27482753
// media the transport drives. Reads attributes only; no cache rebuild.
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
export interface StereoLevel {
2+
l: number;
3+
r: number;
4+
}
5+
6+
export interface LevelTap {
7+
/** Peak of the last analyser window per channel, linear 0..1+. */
8+
read(): StereoLevel;
9+
dispose(): void;
10+
}
11+
12+
const WINDOW = 2048;
13+
14+
function peak(analyser: AnalyserNode, buf: Float32Array<ArrayBuffer>): number {
15+
analyser.getFloatTimeDomainData(buf);
16+
let max = 0;
17+
for (let i = 0; i < buf.length; i++) max = Math.max(max, Math.abs(buf[i] ?? 0));
18+
return max;
19+
}
20+
21+
/** A side branch off `source`; the explicit-stereo gain up-mixes mono to both channels. */
22+
export function createLevelTap(ctx: BaseAudioContext, source: AudioNode): LevelTap {
23+
const mix = ctx.createGain();
24+
mix.channelCount = 2;
25+
mix.channelCountMode = "explicit";
26+
const splitter = ctx.createChannelSplitter(2);
27+
const left = ctx.createAnalyser();
28+
const right = ctx.createAnalyser();
29+
left.fftSize = right.fftSize = WINDOW;
30+
source.connect(mix);
31+
mix.connect(splitter);
32+
splitter.connect(left, 0);
33+
splitter.connect(right, 1);
34+
const bufL = new Float32Array(new ArrayBuffer(WINDOW * 4));
35+
const bufR = new Float32Array(new ArrayBuffer(WINDOW * 4));
36+
return {
37+
read: () => ({ l: peak(left, bufL), r: peak(right, bufR) }),
38+
dispose: () => {
39+
try {
40+
source.disconnect(mix);
41+
mix.disconnect();
42+
splitter.disconnect();
43+
} catch {
44+
// Source already torn down.
45+
}
46+
},
47+
};
48+
}

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

Lines changed: 129 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ function createMockAudioContext(currentTime = 100) {
3131
gain: { value: 1 },
3232
connect: vi.fn(),
3333
};
34+
const monitorGain = {
35+
gain: { value: 1 },
36+
connect: vi.fn(),
37+
};
3438
const ctx = {
3539
currentTime,
3640
state: "running",
@@ -41,14 +45,15 @@ function createMockAudioContext(currentTime = 100) {
4145
destination: {},
4246
close: vi.fn(),
4347
};
44-
return { ctx, sourceNode, mediaElementSourceNode, gainNode, masterGain, startFn };
48+
return { ctx, sourceNode, mediaElementSourceNode, gainNode, masterGain, monitorGain, startFn };
4549
}
4650

4751
function setupTransport(currentTime = 100) {
4852
const transport = new WebAudioTransport();
4953
const mock = createMockAudioContext(currentTime);
5054
(transport as unknown as { _ctx: unknown })._ctx = mock.ctx;
5155
(transport as unknown as { _masterGain: unknown })._masterGain = mock.masterGain;
56+
(transport as unknown as { _monitorGain: unknown })._monitorGain = mock.monitorGain;
5257
const gen = transport.startGeneration();
5358
return { transport, mock, gen };
5459
}
@@ -87,12 +92,12 @@ describe("WebAudioTransport author gain vs user volume", () => {
8792

8893
it("keeps the user's master volume spec-clamped — it is a fader, not a gain", () => {
8994
const transport = new WebAudioTransport();
90-
const master = { gain: { value: 1 }, connect: vi.fn() };
91-
(transport as unknown as { _masterGain: unknown })._masterGain = master;
95+
const monitor = { gain: { value: 1 }, connect: vi.fn() };
96+
(transport as unknown as { _monitorGain: unknown })._monitorGain = monitor;
9297

9398
transport.setVolume(99);
9499

95-
expect(master.gain.value).toBe(1);
100+
expect(monitor.gain.value).toBe(1);
96101
});
97102
});
98103

@@ -341,11 +346,13 @@ describe("WebAudioTransport", () => {
341346
const { transport, mock } = setupTransport();
342347
transport.setVolume(0.4);
343348
transport.setMuted(true);
344-
expect(mock.masterGain.gain.value).toBe(0);
349+
expect(mock.monitorGain.gain.value).toBe(0);
350+
expect(mock.masterGain.gain.value).toBe(1);
345351

346352
transport.setMuted(false);
347353

348-
expect(mock.masterGain.gain.value).toBe(0.4);
354+
expect(mock.monitorGain.gain.value).toBe(0.4);
355+
expect(mock.masterGain.gain.value).toBe(1);
349356
});
350357

351358
it("applies author and user volume once in separate gain layers", async () => {
@@ -354,8 +361,11 @@ describe("WebAudioTransport", () => {
354361
transport.setVolume(0.5);
355362

356363
expect(mock.gainNode.gain.value).toBe(0.8);
357-
expect(mock.masterGain.gain.value).toBe(0.5);
358-
expect(mock.gainNode.gain.value * mock.masterGain.gain.value).toBeCloseTo(0.4);
364+
expect(mock.masterGain.gain.value).toBe(1);
365+
expect(mock.monitorGain.gain.value).toBe(0.5);
366+
expect(
367+
mock.gainNode.gain.value * mock.masterGain.gain.value * mock.monitorGain.gain.value,
368+
).toBeCloseTo(0.4);
359369
});
360370

361371
describe("ownsElement (per-element mute gate)", () => {
@@ -738,6 +748,7 @@ describe("WebAudioTransport", () => {
738748
getFloatTimeDomainData: ReturnType<typeof vi.fn>;
739749
}[] = [];
740750
const masterGain = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
751+
const monitorGain = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
741752
const mediaElementSource = { connect: vi.fn(), disconnect: vi.fn() };
742753
const ctx = {
743754
currentTime,
@@ -784,21 +795,23 @@ describe("WebAudioTransport", () => {
784795
analysers.push(node);
785796
return node;
786797
}),
798+
createChannelSplitter: vi.fn(() => ({ connect: vi.fn(), disconnect: vi.fn() })),
787799
// The media-element route needs this as much as the decoded one: without
788800
// it `scheduleMediaElementPlayback` throws and its catch returns null,
789801
// which reads as "the member did not play" rather than a missing stub.
790802
createMediaElementSource: vi.fn(() => mediaElementSource),
791803
destination: {},
792804
close: vi.fn(),
793805
};
794-
return { ctx, gainNodes, analysers, masterGain, mediaElementSource };
806+
return { ctx, gainNodes, analysers, masterGain, monitorGain, mediaElementSource };
795807
}
796808

797809
function setupGroupTransport(currentTime = 100) {
798810
const transport = new WebAudioTransport();
799811
const mock = createGroupMockAudioContext(currentTime);
800812
(transport as unknown as { _ctx: unknown })._ctx = mock.ctx;
801813
(transport as unknown as { _masterGain: unknown })._masterGain = mock.masterGain;
814+
(transport as unknown as { _monitorGain: unknown })._monitorGain = mock.monitorGain;
802815
const gen = transport.startGeneration();
803816
return { transport, mock, gen };
804817
}
@@ -1085,6 +1098,113 @@ describe("WebAudioTransport", () => {
10851098
expect(() => transport.setGroupMuted("never-played", true)).not.toThrow();
10861099
});
10871100
});
1101+
1102+
describe("level metering", () => {
1103+
const addGroup = (id: string) => {
1104+
document.body.insertAdjacentHTML(
1105+
"beforeend",
1106+
`<hf-audio-group id="${id}"></hf-audio-group>`,
1107+
);
1108+
};
1109+
const setLevel = (analyser: { getFloatTimeDomainData: unknown }, peak: number) => {
1110+
(analyser.getFloatTimeDomainData as ReturnType<typeof vi.fn>).mockImplementation(
1111+
(buf: Float32Array) => buf.fill(0).fill(-peak, 3, 4),
1112+
);
1113+
};
1114+
1115+
it("creates nothing until startMetering", async () => {
1116+
addGroup("vo");
1117+
const { transport, mock, gen } = setupGroupTransport();
1118+
await scheduleGrouped(transport, gen, "a", "vo");
1119+
expect(mock.ctx.createAnalyser).not.toHaveBeenCalled();
1120+
expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
1121+
});
1122+
1123+
it("attaches the master tap once init() lands, even when startMetering ran while the context was still warming up", async () => {
1124+
const mock = createGroupMockAudioContext();
1125+
class MockAudioContext {
1126+
constructor() {
1127+
return mock.ctx as unknown as MockAudioContext;
1128+
}
1129+
}
1130+
vi.stubGlobal("AudioContext", MockAudioContext);
1131+
const transport = new WebAudioTransport();
1132+
1133+
transport.startMetering();
1134+
expect(mock.ctx.createAnalyser).not.toHaveBeenCalled();
1135+
expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
1136+
1137+
const ok = await transport.init();
1138+
1139+
expect(ok).toBe(true);
1140+
expect(mock.ctx.createAnalyser).toHaveBeenCalled();
1141+
expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
1142+
vi.unstubAllGlobals();
1143+
});
1144+
1145+
it("taps master and each group as side branches, once however often it starts", async () => {
1146+
addGroup("vo");
1147+
const { transport, mock, gen } = setupGroupTransport();
1148+
await scheduleGrouped(transport, gen, "a", "vo");
1149+
const groupOutput = mock.gainNodes[2]!;
1150+
const connectsBefore = groupOutput.connect.mock.calls.length;
1151+
1152+
transport.startMetering();
1153+
transport.startMetering();
1154+
1155+
expect(mock.analysers).toHaveLength(4);
1156+
expect(groupOutput.connect).toHaveBeenCalledTimes(connectsBefore + 1);
1157+
expect(groupOutput.connect).toHaveBeenCalledWith(mock.masterGain);
1158+
expect(mock.masterGain.connect).toHaveBeenCalledTimes(1);
1159+
expect(mock.monitorGain.connect).not.toHaveBeenCalled();
1160+
});
1161+
1162+
it("keeps program taps off the monitor fader", async () => {
1163+
addGroup("vo");
1164+
const { transport, mock, gen } = setupGroupTransport();
1165+
await scheduleGrouped(transport, gen, "a", "vo");
1166+
transport.startMetering();
1167+
transport.setVolume(0.5);
1168+
transport.setMuted(true);
1169+
const groupOutput = mock.gainNodes.find((n) =>
1170+
n.connect.mock.calls.some((call) => call[0] === mock.masterGain),
1171+
);
1172+
expect(mock.masterGain.gain.value).toBe(1);
1173+
expect(groupOutput?.gain.value).toBe(1);
1174+
expect(mock.monitorGain.gain.value).toBe(0);
1175+
});
1176+
1177+
it("reads the peak per channel and stops cleanly", async () => {
1178+
addGroup("vo");
1179+
const { transport, mock, gen } = setupGroupTransport();
1180+
await scheduleGrouped(transport, gen, "a", "vo");
1181+
transport.startMetering();
1182+
const [masterL, , groupL, groupR] = mock.analysers;
1183+
setLevel(masterL!, 0.5);
1184+
setLevel(groupL!, 0.25);
1185+
setLevel(groupR!, 0.125);
1186+
1187+
const levels = transport.readLevels();
1188+
expect(levels.master).toEqual({ l: 0.5, r: 0 });
1189+
expect(levels.groups.vo).toEqual({ l: 0.25, r: 0.125 });
1190+
1191+
transport.stopMetering();
1192+
expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
1193+
expect(mock.gainNodes[2]!.disconnect).toHaveBeenCalled();
1194+
});
1195+
1196+
it("a group built after start is metered, and one removed from the document leaves the read", async () => {
1197+
const { transport, mock, gen } = setupGroupTransport();
1198+
transport.startMetering();
1199+
addGroup("late");
1200+
await scheduleGrouped(transport, gen, "a", "late");
1201+
expect(Object.keys(transport.readLevels().groups)).toEqual(["late"]);
1202+
1203+
document.querySelector("hf-audio-group")!.remove();
1204+
expect(transport.readLevels().groups).toEqual({});
1205+
expect(mock.analysers).toHaveLength(4);
1206+
});
1207+
});
10881208
});
10891209

10901210
describe("decodeAudioElement retry policy (late-asset self-heal)", () => {

0 commit comments

Comments
 (0)