Files
hyperframes/packages/core/src/runtime/webAudioTransport.test.ts
T
Miguel Ángel cb8e02e826 fix(core): a decoded buffer's handover leaves the routed element silent (#7309)
* fix(core): a decoded buffer's handover leaves the routed element silent

* fix(core): a handed-over element sounds again when playback stops
2026-11-06 10:17:47 +00:00

2083 lines
86 KiB
TypeScript

// fallow-ignore-file code-duplication complexity
import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
import { MAX_AUDIO_GAIN } from "../audioGain.js";
import { mediaElementTime } from "./mediaClock";
import { WebAudioTransport } from "./webAudioTransport";
function createMockAudioContext(currentTime = 100) {
const startFn = vi.fn();
const endedListeners: (() => void)[] = [];
const sourceNode = {
buffer: null as AudioBuffer | null,
playbackRate: { value: 1 },
start: startFn,
stop: vi.fn(),
disconnect: vi.fn(),
connect: vi.fn(),
addEventListener: vi.fn((event: string, cb: () => void) => {
if (event === "ended") endedListeners.push(cb);
}),
_fireEnded: () => endedListeners.forEach((cb) => cb()),
};
const gainNode = {
gain: { value: 1 },
connect: vi.fn(),
disconnect: vi.fn(),
};
const mediaElementSourceNode = {
connect: vi.fn(),
disconnect: vi.fn(),
};
const masterGain = {
gain: { value: 1 },
connect: vi.fn(),
};
const monitorGain = {
gain: { value: 1 },
connect: vi.fn(),
};
const ctx = {
currentTime,
state: "running",
resume: vi.fn(),
suspend: vi.fn(() => Promise.resolve()),
createBufferSource: vi.fn(() => sourceNode),
createMediaElementSource: vi.fn(() => mediaElementSourceNode),
// The element gain is the first one a schedule creates; its lane and clip gains get their own.
createGain: vi.fn(() =>
ctx.createGain.mock.calls.length === 1
? gainNode
: { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() },
),
destination: {},
close: vi.fn(),
};
return { ctx, sourceNode, mediaElementSourceNode, gainNode, masterGain, monitorGain, startFn };
}
function setupTransport(currentTime = 100) {
const transport = new WebAudioTransport();
const mock = createMockAudioContext(currentTime);
(transport as unknown as { _ctx: unknown })._ctx = mock.ctx;
(transport as unknown as { _masterGain: unknown })._masterGain = mock.masterGain;
(transport as unknown as { _monitorGain: unknown })._monitorGain = mock.monitorGain;
const gen = transport.startGeneration();
return { transport, mock, gen };
}
const mockBuffer = {} as AudioBuffer;
const mockEl = {
muted: false,
volume: 0.4,
paused: true,
addEventListener: () => {},
removeEventListener: () => {},
getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
} as unknown as HTMLMediaElement;
describe("WebAudioTransport author gain vs user volume", () => {
it("carries a static above-unity author gain onto the element gain node", () => {
// The regression this ceiling exists to prevent: a static `data-volume`
// above unity was capped at 1 here while the render honoured it, so preview
// and render disagreed on every boosted clip. Automation lanes hid it —
// they schedule ramps onto the param directly and never pass through here.
const { transport, mock } = setupTransport();
const el = { muted: false } as HTMLMediaElement;
transport["_activeSources"] = [
{ el, gainNode: mock.gainNode, clipGainNode: { gain: { value: 1 } }, sourceKind: "buffer" },
] as never;
transport.setElementVolume(el, 1.949845);
expect(mock.gainNode.gain.value).toBeCloseTo(1.949845, 6);
});
it("still refuses a gain beyond the shared ceiling", () => {
const { transport, mock } = setupTransport();
const el = { muted: false } as HTMLMediaElement;
transport["_activeSources"] = [
{ el, gainNode: mock.gainNode, clipGainNode: { gain: { value: 1 } }, sourceKind: "buffer" },
] as never;
transport.setElementVolume(el, 99);
expect(mock.gainNode.gain.value).toBeCloseTo(MAX_AUDIO_GAIN, 6);
});
it("keeps the user's master volume spec-clamped — it is a fader, not a gain", () => {
const transport = new WebAudioTransport();
const monitor = { gain: { value: 1 }, connect: vi.fn() };
(transport as unknown as { _monitorGain: unknown })._monitorGain = monitor;
transport.setVolume(99);
expect(monitor.gain.value).toBe(1);
});
});
describe("WebAudioTransport", () => {
beforeEach(() => {
mockEl.muted = false;
mockEl.volume = 0.4;
});
describe("pitch-preserving media-element source route", () => {
it("routes native media through WebAudio without decoding, resampling, or muting it", async () => {
const { transport, mock, gen } = setupTransport(100);
const scheduled = await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 0.8, gen, 2);
expect(scheduled).not.toBeNull();
expect(mock.ctx.createMediaElementSource).toHaveBeenCalledWith(mockEl);
expect(mock.ctx.createBufferSource).not.toHaveBeenCalled();
expect(mock.mediaElementSourceNode.connect).toHaveBeenCalled();
expect(mock.gainNode.connect).toHaveBeenCalledWith(mock.masterGain);
expect(mockEl.muted).toBe(false);
expect(mockEl.volume).toBe(1);
expect(mock.gainNode.gain.value).toBe(0.8);
expect(transport.ownsElement(mockEl)).toBe(false);
expect(transport.routesElement(mockEl)).toBe(true);
});
it("leaves the clock to a routed element, which keeps its own time", async () => {
const { transport, gen } = setupTransport(100);
await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
expect(transport.routesElement(mockEl)).toBe(true);
expect(transport.ownsClock()).toBe(false);
});
it("drops a schedule still waiting on resume() when stopAll comes first", async () => {
const { transport, mock, gen } = setupTransport(100);
let resume!: () => void;
mock.ctx.state = "suspended";
mock.ctx.resume = vi.fn(() => new Promise<void>((r) => (resume = r)));
const pending = transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
transport.stopAll();
resume();
expect(await pending).toBeNull();
expect(transport.routesElement(mockEl)).toBe(false);
});
it("stops what plays from media gone from the page without sending it to the destination", async () => {
const { transport, mock, gen } = setupTransport(100);
const nodes: Array<{
connect: ReturnType<typeof vi.fn>;
disconnect: ReturnType<typeof vi.fn>;
}> = [];
mock.ctx.createMediaElementSource = vi.fn(() => {
nodes.push({ connect: vi.fn(), disconnect: vi.fn() });
return nodes.at(-1)!;
}) as never;
const media = () =>
({ ...mockEl, isConnected: true }) as HTMLMediaElement & { isConnected: boolean };
const [gone, kept] = [media(), media()];
for (const el of [gone, kept])
await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
for (const node of nodes) {
node.connect.mockClear();
node.disconnect.mockClear();
}
gone.isConnected = false;
transport.releaseDetached();
const touched = nodes.map((n) => [
n.disconnect.mock.calls.length > 0,
n.connect.mock.calls.length > 0,
]);
expect(touched).toEqual([
[true, false],
[false, false],
]);
expect([transport.routesElement(gone), transport.routesElement(kept)]).toEqual([false, true]);
});
it("keeps a routed element silent once a decoded buffer plays in its place", async () => {
const { transport, mock, gen } = setupTransport(100);
const node = { connect: vi.fn(), disconnect: vi.fn() };
mock.ctx.createMediaElementSource = vi.fn(() => node) as never;
await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
node.connect.mockClear();
node.disconnect.mockClear();
transport.releaseRouted(mockEl);
expect(node.disconnect).toHaveBeenCalled();
expect(node.connect).not.toHaveBeenCalled();
});
it("sounds a handed-over element through the output again once playback stops", async () => {
const { transport, mock, gen } = setupTransport(100);
const node = { connect: vi.fn(), disconnect: vi.fn() };
mock.ctx.createMediaElementSource = vi.fn(() => node) as never;
await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
transport.releaseRouted(mockEl);
node.connect.mockClear();
transport.stopAll();
expect(node.connect).toHaveBeenCalledWith(mock.ctx.destination);
});
it("creates one MediaElementAudioSourceNode per element and context", async () => {
const { transport, mock } = setupTransport(100);
let gen = transport.startGeneration();
await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
transport.stopAll();
gen = transport.startGeneration();
await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 2);
expect(mock.ctx.createMediaElementSource).toHaveBeenCalledTimes(1);
});
it("does not resample the native source on a global-rate change", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 1);
transport.setRate(2);
expect(mock.ctx.createBufferSource).not.toHaveBeenCalled();
});
it("disconnects the transient graph on stop but keeps the cached native source reusable", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 1, gen, 2);
transport.stopAll();
expect(mock.mediaElementSourceNode.disconnect).toHaveBeenCalled();
expect(mockEl.muted).toBe(false);
expect(mockEl.volume).toBe(0.4);
expect(transport.ownsClock()).toBe(false);
});
// #3458. `createMediaElementSource` over a CORS-cross-origin resource does
// not throw — the Web Audio spec asks the node for SILENCE — so the
// `try/catch` around it never fires and the composition plays through
// perfectly with no sound. The node also permanently steals the element's
// native output, so the only possible defence is to not build it.
it("never builds a source node over cross-origin media with no CORS opt-in", async () => {
const { transport, mock, gen } = setupTransport(100);
const el = document.createElement("audio");
el.setAttribute("src", "https://cdn.example.com/track.mp3");
vi.spyOn(console, "info").mockImplementation(() => {});
const scheduled = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
expect(scheduled).toBeNull();
expect(mock.ctx.createMediaElementSource).not.toHaveBeenCalled();
// Untouched: the caller falls back, and a muted or re-levelled element
// would take the fallback's audio down with it.
expect(el.muted).toBe(false);
expect(transport.routesElement(el)).toBe(false);
});
it("still routes cross-origin media that carries the crossorigin opt-in", async () => {
const { transport, mock, gen } = setupTransport(100);
const el = document.createElement("audio");
el.setAttribute("src", "https://cdn.example.com/track.mp3");
el.setAttribute("crossorigin", "anonymous");
const scheduled = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
expect(scheduled).not.toBeNull();
expect(mock.ctx.createMediaElementSource).toHaveBeenCalledWith(el);
});
it("still routes same-origin media", async () => {
const { transport, mock, gen } = setupTransport(100);
const el = document.createElement("audio");
el.setAttribute("src", "/assets/vo.mp3");
const scheduled = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
expect(scheduled).not.toBeNull();
expect(mock.ctx.createMediaElementSource).toHaveBeenCalledWith(el);
});
// R2 finding: `_mediaElementSources` is keyed by element identity, not by
// asset. A cache hit alone said nothing about the element's CURRENT
// resource, so a pooled element reused for a new clip kept handing back
// the OLD (same-origin) node — and its stale `web-audio` verdict — after
// `src` moved to a cross-origin asset with no `crossorigin` opt-in. Only
// `destroy()` ever cleared the cache, so this silenced the element for the
// rest of the session.
it("stops returning the cached node once the same element's src moves cross-origin", async () => {
const { transport, mock, gen: gen1 } = setupTransport(100);
vi.spyOn(console, "info").mockImplementation(() => {});
const el = document.createElement("audio");
el.setAttribute("src", "/assets/vo.mp3");
const first = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen1, 1);
expect(first).not.toBeNull();
expect(mock.ctx.createMediaElementSource).toHaveBeenCalledTimes(1);
transport.stopAll();
// `stopAll()` itself disconnects the transient graph (see "disconnects
// the transient graph on stop but keeps the cached native source
// reusable" above) without evicting the cache — clear the spy so the
// assertion below is about the FIX's own eviction, not that call.
mock.mediaElementSourceNode.disconnect.mockClear();
el.setAttribute("src", "https://cdn.example.com/reused-clip.mp3");
const gen2 = transport.startGeneration();
const second = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen2, 1);
expect(second).toBeNull();
// The one-way door means a fresh node can't be built either — the
// fix's job is to stop HANDING BACK the stale one, not to conjure a
// new node over a src that was never eligible.
expect(mock.ctx.createMediaElementSource).toHaveBeenCalledTimes(1);
expect(mock.mediaElementSourceNode.disconnect).toHaveBeenCalledTimes(1);
});
it("keeps returning the cached node when a reused element's src stays eligible", async () => {
const { transport, mock, gen: gen1 } = setupTransport(100);
const el = document.createElement("audio");
el.setAttribute("src", "/assets/vo.mp3");
await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen1, 1);
transport.stopAll();
el.setAttribute("src", "/assets/other-same-origin-clip.mp3");
const gen2 = transport.startGeneration();
const second = await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen2, 1);
expect(second).not.toBeNull();
expect(mock.ctx.createMediaElementSource).toHaveBeenCalledTimes(1);
});
});
it("tracks play generation for async race prevention", () => {
const transport = new WebAudioTransport();
expect(transport.currentGeneration()).toBe(0);
const gen1 = transport.startGeneration();
expect(gen1).toBe(1);
const gen2 = transport.startGeneration();
expect(gen2).toBe(2);
expect(transport.currentGeneration()).toBe(2);
});
it("getTime returns -1 when paused", () => {
const transport = new WebAudioTransport();
expect(transport.getTime()).toBe(-1);
});
it("ownsClock returns false initially", () => {
const transport = new WebAudioTransport();
expect(transport.ownsClock()).toBe(false);
});
it("stopAll restores el.muted to prior value", () => {
const transport = new WebAudioTransport();
const mockEl = { muted: false } as HTMLMediaElement;
const mockSource = {
el: mockEl,
sourceKind: "buffer" as const,
sourceNode: { stop: vi.fn(), disconnect: vi.fn() } as unknown as AudioBufferSourceNode,
gainNode: { disconnect: vi.fn() } as unknown as GainNode,
compositionStart: 0,
mediaStart: 0,
scheduledAt: 0,
priorMuted: false,
};
// Simulate WebAudio taking over: el.muted was set to true
mockEl.muted = true;
(transport as unknown as { _activeSources: (typeof mockSource)[] })._activeSources = [
mockSource,
];
(transport as unknown as { _paused: boolean })._paused = false;
expect(transport.ownsClock()).toBe(true);
transport.stopAll();
expect(mockEl.muted).toBe(false);
expect(transport.ownsClock()).toBe(false);
});
it("stopAll restores el.muted=true when element was already muted", () => {
const transport = new WebAudioTransport();
const mockEl = { muted: true } as HTMLMediaElement;
const mockSource = {
el: mockEl,
sourceKind: "buffer" as const,
sourceNode: { stop: vi.fn(), disconnect: vi.fn() } as unknown as AudioBufferSourceNode,
gainNode: { disconnect: vi.fn() } as unknown as GainNode,
compositionStart: 0,
mediaStart: 0,
scheduledAt: 0,
priorMuted: true,
};
(transport as unknown as { _activeSources: (typeof mockSource)[] })._activeSources = [
mockSource,
];
transport.stopAll();
expect(mockEl.muted).toBe(true);
});
it("stopAll called multiple times is safe (idempotent)", () => {
const transport = new WebAudioTransport();
transport.stopAll();
transport.stopAll();
expect(transport.ownsClock()).toBe(false);
});
it("destroy clears buffer cache and nulls context", () => {
const transport = new WebAudioTransport();
transport.destroy();
expect(transport.context).toBeNull();
expect(transport.ownsClock()).toBe(false);
});
it("restores the configured master volume after user mute then unmute", () => {
const { transport, mock } = setupTransport();
transport.setVolume(0.4);
transport.setMuted(true);
expect(mock.monitorGain.gain.value).toBe(0);
expect(mock.masterGain.gain.value).toBe(1);
transport.setMuted(false);
expect(mock.monitorGain.gain.value).toBe(0.4);
expect(mock.masterGain.gain.value).toBe(1);
});
it("applies author and user volume once in separate gain layers", async () => {
const { transport, mock, gen } = setupTransport();
await transport.scheduleMediaElementPlayback(mockEl, 0, 0, 0, 0.8, gen, 1);
transport.setVolume(0.5);
expect(mock.gainNode.gain.value).toBe(0.8);
expect(mock.masterGain.gain.value).toBe(1);
expect(mock.monitorGain.gain.value).toBe(0.5);
expect(
mock.gainNode.gain.value * mock.masterGain.gain.value * mock.monitorGain.gain.value,
).toBeCloseTo(0.4);
});
describe("ownsElement (per-element mute gate)", () => {
function withSource(el: HTMLMediaElement) {
const transport = new WebAudioTransport();
const source = {
el,
sourceKind: "buffer" as const,
sourceNode: { stop: vi.fn(), disconnect: vi.fn() } as unknown as AudioBufferSourceNode,
gainNode: { disconnect: vi.fn() } as unknown as GainNode,
compositionStart: 0,
mediaStart: 0,
scheduledAt: 0,
priorMuted: false,
};
(transport as unknown as { _activeSources: (typeof source)[] })._activeSources = [source];
(transport as unknown as { _paused: boolean })._paused = false;
return transport;
}
it("returns true for an element the transport plays", () => {
const el = {
muted: false,
getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
} as unknown as HTMLMediaElement;
expect(withSource(el).ownsElement(el)).toBe(true);
});
it("returns false for an element the transport does not play", () => {
const el = {
muted: false,
getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
} as unknown as HTMLMediaElement;
const other = { muted: false } as HTMLMediaElement;
expect(withSource(el).ownsElement(other)).toBe(false);
});
it("returns false after stopAll releases the element", () => {
const el = { muted: false } as HTMLMediaElement;
const transport = withSource(el);
transport.stopAll();
expect(transport.ownsElement(el)).toBe(false);
});
});
describe("schedulePlayback timing", () => {
it("keeps author boost above unity on the per-element gain node", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 0, 0, () => 0, 1, gen);
transport.setElementVolume(mockEl, 3.98);
expect(mock.gainNode.gain.value).toBeCloseTo(3.98, 5);
});
it("starts in-progress clips immediately with correct buffer offset", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen);
expect(mock.startFn).toHaveBeenCalledWith(0, 3);
});
it("starts in-progress clips with mediaStart offset", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 2, () => 8, 1, gen);
expect(mock.startFn).toHaveBeenCalledWith(0, 5);
});
it("schedules future clips with delay instead of playing immediately", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 10, 0, () => 2, 1, gen);
expect(mock.startFn).toHaveBeenCalledWith(108, 0);
});
it("schedules future clips with correct mediaStart", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 10, 1.5, () => 2, 1, gen);
expect(mock.startFn).toHaveBeenCalledWith(108, 1.5);
});
it("starts clips at exact composition start time immediately", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 5, 1, gen);
expect(mock.startFn).toHaveBeenCalledWith(0, 0);
});
});
describe("clip duration bound (trim)", () => {
it("bounds an in-progress clip to its remaining authored window", async () => {
const { transport, mock, gen } = setupTransport(100);
// compStart=5, mediaStart=0, compTime=8 → elapsed=3; clipDuration=10 → 7 left
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 1, 10);
expect(mock.startFn).toHaveBeenCalledWith(0, 3, 7);
});
it("bounds a future clip to its full authored window", async () => {
const { transport, mock, gen } = setupTransport(100);
// compStart=10, mediaStart=1.5, compTime=2 → elapsed=-8 → delay 8; clipDuration=4
await transport.schedulePlayback(mockEl, mockBuffer, 10, 1.5, () => 2, 1, gen, 1, 4);
expect(mock.startFn).toHaveBeenCalledWith(108, 1.5, 4);
});
it("holds a clip whose head an in-point cut until its window opens, at that point's source", async () => {
const { transport, mock, gen } = setupTransport(100);
// The clip's own t=0 is 1, its window opens at 2 and ends at 5: from comp time 0, wait 2 s, then
// play source 1 to 4; from comp time 1.5, the same.
await transport.schedulePlayback(mockEl, mockBuffer, 1, 0, () => 0, 1, gen, 1, 4, 2);
expect(mock.startFn).toHaveBeenLastCalledWith(102, 1, 3);
await transport.schedulePlayback(mockEl, mockBuffer, 1, 0, () => 1.5, 1, gen, 1, 4, 2);
expect(mock.startFn).toHaveBeenLastCalledWith(100.5, 1, 3);
});
it("does not schedule a clip whose window has already elapsed", async () => {
const { transport, mock, gen } = setupTransport(100);
// elapsed=15 > clipDuration=10 → nothing to play
const result = await transport.schedulePlayback(
mockEl,
mockBuffer,
5,
0,
() => 20,
1,
gen,
1,
10,
);
expect(result).toBeNull();
expect(mock.startFn).not.toHaveBeenCalled();
});
it("keeps source bounds in authored media time when global rate changes", async () => {
const { transport, mock, gen } = setupTransport(100);
// Global rate=2 changes wallclock speed, not source-time span.
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2, 10);
expect(mock.startFn).toHaveBeenCalledWith(0, 3, 7);
});
it("plays unbounded when clipDuration is omitted (legacy behavior)", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen);
expect(mock.startFn).toHaveBeenCalledWith(0, 3);
});
});
describe("playback rate", () => {
it("combines authored media rate with global rate without corrupting source seek or clock", async () => {
const { transport, mock, gen } = setupTransport(100);
const el = {
muted: false,
getAttribute: (name: string) => (name === "data-playback-rate" ? "2" : null),
} as unknown as HTMLMediaElement;
// At composition t=0.5 with mediaStart=1, authored 2x has consumed one
// source second. Global 0.5x makes the source node's wallclock rate 1x,
// but the composition clock must still advance at global 0.5x.
await transport.schedulePlayback(el, mockBuffer, 0, 1, () => 0.5, 1, gen, 0.5, 2);
expect(mock.sourceNode.playbackRate.value).toBe(1);
expect(mock.startFn).toHaveBeenCalledWith(0, 2, 3);
mock.ctx.currentTime = 101;
expect(transport.getTime()).toBe(1);
transport.setRate(1);
expect(mock.sourceNode.playbackRate.value).toBe(2);
});
it("sets sourceNode.playbackRate.value when rate is provided", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);
expect(mock.sourceNode.playbackRate.value).toBe(2);
});
it("defaults rate to 1 when not provided", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen);
expect(mock.sourceNode.playbackRate.value).toBe(1);
});
it("scales delay by rate for future clips so they fire at the right wallclock", async () => {
const { transport, mock, gen } = setupTransport(100);
// compStart=10, compositionTime=2, rate=2 → 8s of comp time = 4s wallclock
await transport.schedulePlayback(mockEl, mockBuffer, 10, 0, () => 2, 1, gen, 2);
expect(mock.startFn).toHaveBeenCalledWith(104, 0);
});
it("keeps in-progress buffer offset at elapsed + mediaStart regardless of rate", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);
expect(mock.startFn).toHaveBeenCalledWith(0, 3);
});
it("setRate updates active sources in place", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 1);
expect(mock.sourceNode.playbackRate.value).toBe(1);
transport.setRate(2);
expect(mock.sourceNode.playbackRate.value).toBe(2);
});
it("setRate re-aims each source's FX automation, not just its playback rate", async () => {
// The lanes are committed to absolute context times when the source is
// scheduled, so bumping playbackRate alone left every automated parameter
// running its original plan over audio moving at a different speed.
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 1);
const active = (transport as unknown as { _activeSources: { fx?: unknown }[] })
._activeSources;
const setRate = vi.fn();
active[0]!.fx = { dispose: vi.fn(), setRate };
transport.setRate(2);
expect(setRate).toHaveBeenCalledWith(2);
expect(mock.sourceNode.playbackRate.value).toBe(2);
});
it("setRate before any sources are scheduled does not throw", () => {
const transport = new WebAudioTransport();
expect(() => transport.setRate(2)).not.toThrow();
});
it("setRate is a no-op when the rate is unchanged", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);
mock.ctx.currentTime = 100.5;
const timeBefore = transport.getTime();
transport.setRate(2);
const timeAfter = transport.getTime();
expect(timeAfter).toBe(timeBefore);
// No re-anchor, so the next 0.5s of wallclock still maps to 1s of comp time.
mock.ctx.currentTime = 101;
expect(transport.getTime()).toBeCloseTo(10, 10);
});
it("setRate clamps non-finite or non-positive values to 1", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);
expect(mock.sourceNode.playbackRate.value).toBe(2);
transport.setRate(Number.NaN);
expect(mock.sourceNode.playbackRate.value).toBe(1);
transport.setRate(2);
transport.setRate(0);
expect(mock.sourceNode.playbackRate.value).toBe(1);
transport.setRate(2);
transport.setRate(-1);
expect(mock.sourceNode.playbackRate.value).toBe(1);
});
it("getTime advances at the configured rate", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 2);
// At schedule time, ctx.currentTime=100, compositionTime=8.
expect(transport.getTime()).toBeCloseTo(8, 10);
// Advance the audio-context clock by 0.5 wallclock seconds; at rate=2,
// composition time should have advanced 1s.
mock.ctx.currentTime = 100.5;
expect(transport.getTime()).toBeCloseTo(9, 10);
});
it("getTime tracks composition time after a mid-playback setRate", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, () => 8, 1, gen, 1);
expect(transport.getTime()).toBeCloseTo(8, 10);
// 0.5s passes at rate=1 → composition time = 8.5
mock.ctx.currentTime = 100.5;
expect(transport.getTime()).toBeCloseTo(8.5, 10);
// Bump rate to 2 — composition time should NOT jump.
transport.setRate(2);
expect(transport.getTime()).toBeCloseTo(8.5, 10);
// Another 0.5s wallclock at rate=2 → composition time = 9.5
mock.ctx.currentTime = 101;
expect(transport.getTime()).toBeCloseTo(9.5, 10);
});
});
describe("onended cleanup (audio dropout fix)", () => {
it("cleans up _activeSources when AudioBufferSourceNode ends naturally", async () => {
const { transport, mock, gen } = setupTransport(100);
const el = {
muted: false,
getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
} as unknown as HTMLMediaElement;
await transport.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen);
expect(transport.ownsClock()).toBe(true);
expect(el.muted).toBe(true);
mock.sourceNode._fireEnded();
expect(transport.ownsClock()).toBe(false);
expect(el.muted).toBe(false);
});
it("restores priorMuted=true when element was already muted", async () => {
const { transport, mock, gen } = setupTransport(100);
const el = {
muted: true,
getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
} as unknown as HTMLMediaElement;
await transport.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen);
expect(el.muted).toBe(true);
mock.sourceNode._fireEnded();
expect(el.muted).toBe(true);
expect(transport.ownsClock()).toBe(false);
});
it("disposes the FX graph when a clip ends naturally", async () => {
// stopAll() disposes by walking _activeSources, and the splice above had
// already removed this entry — so the handle, its MutationObserver and any
// running LFO survived the clip for the rest of the session.
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 0, 0, () => 0, 1, gen);
mock.sourceNode._fireEnded();
expect(mock.sourceNode.disconnect).toHaveBeenCalled();
expect(mock.gainNode.disconnect).toHaveBeenCalled();
});
it("registers onended listener on the sourceNode", async () => {
const { transport, mock, gen } = setupTransport(100);
await transport.schedulePlayback(mockEl, mockBuffer, 0, 0, () => 0, 1, gen);
expect(mock.sourceNode.addEventListener).toHaveBeenCalledWith("ended", expect.any(Function));
});
it("onended after stopAll is a no-op — does not clobber restored state", async () => {
const { transport, mock, gen } = setupTransport(100);
const el = {
muted: false,
getAttribute: (name: string) => (name === "data-playback-rate" ? "1" : null),
} as unknown as HTMLMediaElement;
await transport.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen);
expect(el.muted).toBe(true);
transport.stopAll();
expect(el.muted).toBe(false);
expect(transport.ownsClock()).toBe(false);
el.muted = true;
mock.sourceNode._fireEnded();
expect(el.muted).toBe(true);
expect(transport.ownsClock()).toBe(false);
});
});
describe("group routing (preview)", () => {
// Real jsdom elements — `groupInput` looks the group up via
// `el.ownerDocument.getElementById`, and `audioGroupOf` reads `tagName` /
// `getAttribute`, neither of which the plain-object mocks above implement.
function createGroupMockAudioContext(currentTime = 100) {
const gainNodes: {
gain: { value: number };
connect: ReturnType<typeof vi.fn>;
disconnect: ReturnType<typeof vi.fn>;
}[] = [];
const analysers: {
fftSize: number;
connect: ReturnType<typeof vi.fn>;
disconnect: ReturnType<typeof vi.fn>;
getFloatTimeDomainData: ReturnType<typeof vi.fn>;
}[] = [];
const masterGain = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
const monitorGain = { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
const mediaElementSource = { connect: vi.fn(), disconnect: vi.fn() };
const ctx = {
currentTime,
state: "running",
resume: vi.fn(),
suspend: vi.fn(() => Promise.resolve()),
createBufferSource: vi.fn(() => ({
buffer: null as AudioBuffer | null,
playbackRate: { value: 1 },
start: vi.fn(),
stop: vi.fn(),
disconnect: vi.fn(),
connect: vi.fn(),
addEventListener: vi.fn(),
})),
createGain: vi.fn(() => {
// The AudioParam scheduling surface is part of the contract the group
// bus uses (`clearParamLane` cancels before re-seeding a reused bus).
// A bare `{ value }` made any such call throw, and `schedulePlayback`
// swallows throws into `return null` — so the mock's own gap read as
// "the member did not play" rather than as a missing stub.
const node = {
gain: {
value: 1,
cancelScheduledValues: vi.fn(),
cancelAndHoldAtTime: vi.fn(),
setValueAtTime: vi.fn(),
linearRampToValueAtTime: vi.fn(),
exponentialRampToValueAtTime: vi.fn(),
setValueCurveAtTime: vi.fn(),
},
connect: vi.fn(),
disconnect: vi.fn(),
};
gainNodes.push(node);
return node;
}),
createAnalyser: vi.fn(() => {
const node = {
fftSize: 2048,
connect: vi.fn(),
disconnect: vi.fn(),
getFloatTimeDomainData: vi.fn(),
};
analysers.push(node);
return node;
}),
createChannelSplitter: vi.fn(() => ({ connect: vi.fn(), disconnect: vi.fn() })),
// The media-element route needs this as much as the decoded one: without
// it `scheduleMediaElementPlayback` throws and its catch returns null,
// which reads as "the member did not play" rather than a missing stub.
createMediaElementSource: vi.fn(() => mediaElementSource),
destination: {},
close: vi.fn(),
};
return { ctx, gainNodes, analysers, masterGain, monitorGain, mediaElementSource };
}
function setupGroupTransport(currentTime = 100) {
const transport = new WebAudioTransport();
const mock = createGroupMockAudioContext(currentTime);
(transport as unknown as { _ctx: unknown })._ctx = mock.ctx;
(transport as unknown as { _masterGain: unknown })._masterGain = mock.masterGain;
(transport as unknown as { _monitorGain: unknown })._monitorGain = mock.monitorGain;
const gen = transport.startGeneration();
return { transport, mock, gen };
}
function groupedAudioEl(id: string, groupId?: string): HTMLMediaElement {
const el = document.createElement("audio");
el.id = id;
if (groupId) el.setAttribute("data-audio-group", groupId);
document.body.appendChild(el);
return el as unknown as HTMLMediaElement;
}
/** Create a grouped member and schedule it in one step — the shape every
* test below needs, differing only in id/group/generation. */
async function scheduleGrouped(
transport: WebAudioTransport,
gen: number,
id: string,
groupId?: string,
): Promise<HTMLMediaElement> {
const el = groupedAudioEl(id, groupId);
await transport.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen);
return el;
}
/** The group's own input gain is built lazily on the first member — index
* 1 in creation order (that member's own gain is 0). */
const firstGroupInput = (mock: ReturnType<typeof createGroupMockAudioContext>) =>
mock.gainNodes[1]!;
beforeEach(() => {
document.body.innerHTML = "";
});
it.each([
[
"decoded",
(t: WebAudioTransport, el: HTMLMediaElement, gen: number) =>
t.schedulePlayback(el, mockBuffer, 0, 0, () => 0, 1, gen),
],
[
"media-element",
(t: WebAudioTransport, el: HTMLMediaElement, gen: number) =>
t.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen),
],
])(
"keeps a %s clip's volume lane off the gain each tick rewrites",
async (_route, schedule) => {
const { transport, mock, gen } = setupGroupTransport();
const el = groupedAudioEl("voice");
const points = [
{ t: 0, v: 0 },
{ t: 3, v: 1 },
{ t: 6, v: 0 },
];
el.setAttribute(
"data-automation",
JSON.stringify({ version: 1, lanes: [{ target: "volume", points }] }),
);
expect(await schedule(transport, el, gen)).not.toBeNull();
type Ramps = { linearRampToValueAtTime: ReturnType<typeof vi.fn> };
const laneGains = mock.gainNodes.filter(
(node) => (node.gain as unknown as Ramps).linearRampToValueAtTime.mock.calls.length > 0,
);
expect(laneGains).toHaveLength(1);
const laneValue = laneGains[0]!.gain.value;
transport.setElementVolume(el, 0.5);
expect(laneGains[0]!.gain.value).toBe(laneValue);
expect(mock.gainNodes.filter((node) => node.gain.value === 0.5)).toHaveLength(1);
},
);
describe("volume lanes follow the transport mid-play", () => {
const lane = (points: { t: number; v: number }[]) =>
JSON.stringify({ version: 1, lanes: [{ target: "volume", points }] });
const FADE = lane([
{ t: 0, v: 0 },
{ t: 3, v: 1 },
{ t: 6, v: 0 },
]);
type Param = Record<
"linearRampToValueAtTime" | "cancelScheduledValues",
ReturnType<typeof vi.fn>
>;
const param = (node: { gain: unknown }) => node.gain as Param;
const rampsAfter = (node: { gain: unknown }, from: number) =>
param(node).linearRampToValueAtTime.mock.calls.slice(from);
/** Let the MutationObserver's microtask run. */
const settle = () => new Promise((r) => setTimeout(r, 0));
// An unbounded media-element clip: the runtime does not stopAll and reschedule it on a rate change.
// Its gains in creation order: element gain, seek dip, lane, clip gain (then fades, when it has them).
async function playBed(automation?: string, volume?: string) {
const setup = setupGroupTransport();
const el = groupedAudioEl("bed");
if (automation) el.setAttribute("data-automation", automation);
if (volume) el.setAttribute("data-volume", volume);
await setup.transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, setup.gen);
expect(setup.transport.hasBoundedActiveSources()).toBe(false);
return { ...setup, el, laneGain: setup.mock.gainNodes[2]! };
}
// Gain 2 times a 0 -> 3 ramp crosses the ceiling at 6.635 s; the product holds there after.
const CROSSING = lane([
{ t: 0, v: 0 },
{ t: 10, v: 3 },
]);
const crossAt = 100 + (MAX_AUDIO_GAIN / 2 / 3) * 10;
it("caps the routed graph's product when gain 2 and a constant lane 3 would make 6", async () => {
const { transport, el, mock, laneGain } = await playBed(lane([{ t: 0, v: 3 }]), "2");
transport.setElementVolume(el, 1, 2);
const booked = (laneGain.gain as unknown as { setValueAtTime: ReturnType<typeof vi.fn> })
.setValueAtTime.mock.calls;
expect(mock.gainNodes[3]!.gain.value * booked[0]![0]).toBeCloseTo(MAX_AUDIO_GAIN, 9);
});
it("holds a clip's gain times its lane under the ceiling, with data-volume played ahead", async () => {
const { laneGain } = await playBed(CROSSING, "2");
expect(rampsAfter(laneGain, 0)).toContainEqual([
expect.closeTo(MAX_AUDIO_GAIN / 2, 6),
expect.closeTo(crossAt, 6),
]);
expect(rampsAfter(laneGain, 0)).toContainEqual([
expect.closeTo(MAX_AUDIO_GAIN / 2, 6),
110,
]);
});
it("re-books a clip's lane when its data-volume changes", async () => {
const { el, laneGain } = await playBed(CROSSING, "2");
const before = param(laneGain).linearRampToValueAtTime.mock.calls.length;
el.setAttribute("data-volume", "1");
await settle();
expect(rampsAfter(laneGain, before)).toContainEqual([3, 110]);
});
it("restores unity after a playing clip's volume lane is removed", async () => {
const { el, laneGain, transport, mock } = await playBed(lane([{ t: 0, v: 0.25 }]), "2");
transport.setElementVolume(el, 1, 2);
el.removeAttribute("data-automation");
await Promise.resolve();
const booked = (laneGain.gain as unknown as { setValueAtTime: ReturnType<typeof vi.fn> })
.setValueAtTime.mock.calls;
expect(booked.at(-1)).toEqual([1, 100]);
expect(mock.gainNodes[3]!.gain.value * booked.at(-1)![0]).toBe(2);
});
it("restores the static group gain after its playing volume lane is removed", async () => {
document.body.innerHTML = `<hf-audio-group id="vo" data-volume="2"></hf-audio-group>`;
const group = document.getElementById("vo")!;
group.setAttribute("data-automation", lane([{ t: 0, v: 0.25 }]));
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const fader = mock.gainNodes[4]!;
group.removeAttribute("data-automation");
await Promise.resolve();
const booked = (fader.gain as unknown as { setValueAtTime: ReturnType<typeof vi.fn> })
.setValueAtTime.mock.calls;
expect(booked.at(-1)).toEqual([2, 100]);
});
it("holds a group's gain times its lane under the ceiling, through a ramp", async () => {
document.body.innerHTML = `<hf-audio-group id="vo" data-volume="2"></hf-audio-group>`;
document.getElementById("vo")!.setAttribute("data-automation", CROSSING);
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const fader = mock.gainNodes[4]!;
expect(rampsAfter(fader, 0)).toContainEqual([
expect.closeTo(MAX_AUDIO_GAIN, 6),
expect.closeTo(crossAt, 6),
]);
});
it("re-aims a clip's lane at a new rate when its element takes it, not before", async () => {
const { transport, el, laneGain } = await playBed(FADE);
expect(rampsAfter(laneGain, 0)).toContainEqual([1, 103]);
const before = param(laneGain).linearRampToValueAtTime.mock.calls.length;
transport.setRate(2);
expect(rampsAfter(laneGain, before)).toEqual([]);
Object.defineProperties(el, {
paused: { value: false, configurable: true },
playbackRate: { value: 2, configurable: true },
});
el.dispatchEvent(new Event("ratechange"));
expect(rampsAfter(laneGain, before)).toContainEqual([1, 101.5]);
});
it("re-books a clip's lane when it is edited", async () => {
const { el, laneGain } = await playBed(FADE);
const before = param(laneGain).linearRampToValueAtTime.mock.calls.length;
el.setAttribute(
"data-automation",
lane([
{ t: 0, v: 0 },
{ t: 2, v: 0.5 },
]),
);
await settle();
expect(rampsAfter(laneGain, before)).toContainEqual([0.5, 102]);
});
it("clears a clip's lane when it is removed", async () => {
const { el, laneGain } = await playBed(FADE);
const ramps = param(laneGain).linearRampToValueAtTime.mock.calls.length;
const cancels = param(laneGain).cancelScheduledValues.mock.calls.length;
el.removeAttribute("data-automation");
await settle();
expect(param(laneGain).cancelScheduledValues.mock.calls.slice(cancels)).toContainEqual([0]);
expect(rampsAfter(laneGain, ramps)).toEqual([]);
});
it("books a lane added to a playing clip", async () => {
const { el, laneGain } = await playBed();
expect(laneGain).toBeDefined();
el.setAttribute("data-automation", FADE);
await settle();
expect(rampsAfter(laneGain, 0)).toContainEqual([1, 103]);
});
it("books a group's lane times its data-volume, at a new rate and on an edit", async () => {
document.body.innerHTML = `<hf-audio-group id="vo" data-volume="0.5"></hf-audio-group>`;
document.getElementById("vo")!.setAttribute("data-automation", FADE);
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const fader = mock.gainNodes[4]!;
expect(rampsAfter(fader, 0)).toContainEqual([0.5, 103]);
let before = param(fader).linearRampToValueAtTime.mock.calls.length;
transport.setRate(2);
expect(rampsAfter(fader, before)).toContainEqual([0.5, 101.5]);
before = param(fader).linearRampToValueAtTime.mock.calls.length;
document.getElementById("vo")!.setAttribute(
"data-automation",
lane([
{ t: 0, v: 0 },
{ t: 4, v: 0.5 },
]),
);
await settle();
expect(rampsAfter(fader, before)).toContainEqual([0.25, 102]);
});
describe("a routed clip's lane and fades follow its element", () => {
// Routed at context 100, 0.1 s before its window opens at timeline 4 and source 8.
async function routeTake(extra: Record<string, string> = {}) {
const setup = setupGroupTransport();
const el = groupedAudioEl("take");
el.setAttribute("data-automation", FADE);
for (const [name, value] of Object.entries(extra)) el.setAttribute(name, value);
await setup.transport.scheduleMediaElementPlayback(el, 4, 8, 3.9, 1, setup.gen, 1, 2);
const [laneGain, fadeGain] = [setup.mock.gainNodes[2]!, setup.mock.gainNodes[4]];
const at = (ctxTime: number, currentTime: number, playbackRate = 1, paused = false) => {
setup.mock.ctx.currentTime = ctxTime;
Object.defineProperties(el, {
currentTime: { value: currentTime, configurable: true },
playbackRate: { value: playbackRate, configurable: true },
paused: { value: paused, configurable: true },
});
};
return { ...setup, el, laneGain, fadeGain, at };
}
const peakAfter = (node: { gain: unknown }, from: number) =>
rampsAfter(node, from).find(([value]) => value === 1)?.[1];
it("books the lane where the element starts sounding, not where the clock put it", async () => {
const { el, laneGain, at } = await routeTake();
expect(peakAfter(laneGain, 0)).toBeCloseTo(103.1, 9);
const before = param(laneGain).linearRampToValueAtTime.mock.calls.length;
at(100.155, 8);
el.dispatchEvent(new Event("playing"));
expect(peakAfter(laneGain, before)).toBeCloseTo(103.155, 9);
});
it("re-books the fades from the element too", async () => {
const { el, fadeGain, at } = await routeTake({ "data-fade-out": "0.03" });
expect(rampsAfter(fadeGain!, 0).at(-1)).toEqual([0, expect.closeTo(102.1, 9)]);
const before = param(fadeGain!).linearRampToValueAtTime.mock.calls.length;
at(100.155, 8);
el.dispatchEvent(new Event("playing"));
expect(rampsAfter(fadeGain!, before).at(-1)).toEqual([0, expect.closeTo(102.155, 9)]);
});
it("re-books the lane after the element is seeked and when its rate is steered", async () => {
const { el, laneGain, at } = await routeTake();
let before = param(laneGain).linearRampToValueAtTime.mock.calls.length;
at(100.2, 8.2);
el.dispatchEvent(new Event("seeked"));
expect(peakAfter(laneGain, before)).toBeCloseTo(103, 9);
before = param(laneGain).linearRampToValueAtTime.mock.calls.length;
at(100.3, 8.3, 1.03);
el.dispatchEvent(new Event("ratechange"));
expect(peakAfter(laneGain, before)).toBeCloseTo(100.3 + 2.7 / 1.03, 9);
});
it("books a looping element's lane on the pass the transport is in", async () => {
const { el, laneGain, at } = await routeTake();
Object.defineProperties(el, {
loop: { value: true, configurable: true },
duration: { value: 10, configurable: true },
});
const before = param(laneGain).linearRampToValueAtTime.mock.calls.length;
at(102.2, 8.1);
el.dispatchEvent(new Event("playing"));
expect(peakAfter(laneGain, before)).toBeCloseTo(103.1, 9);
});
it("leaves the lane alone while the element is paused and once the clip is stopped", async () => {
const { transport, el, laneGain, fadeGain, at } = await routeTake({
"data-fade-out": "0.03",
});
const booked = () =>
[laneGain, fadeGain!].map(
(node) => param(node).linearRampToValueAtTime.mock.calls.length,
);
const before = booked();
at(100.2, 8, 1, true);
el.dispatchEvent(new Event("seeked"));
transport.stopAll();
at(100.3, 8.1);
el.dispatchEvent(new Event("playing"));
expect(booked()).toEqual(before);
});
describe("a seek while it sounds", () => {
beforeEach(() => vi.useFakeTimers());
afterEach(() => vi.useRealTimers());
type Dip = Record<"linearRampToValueAtTime", ReturnType<typeof vi.fn>>;
const dipRamps = (node: { gain: unknown }) =>
(node.gain as Dip).linearRampToValueAtTime.mock.calls;
it("dips, seeks once the dip is down, and comes back up when the element lands", async () => {
const { transport, el, mock, at } = await routeTake();
const dip = mock.gainNodes[1]!;
at(100.5, 8.35);
const seek = vi.fn();
Object.defineProperty(el, "currentTime", {
get: () => 8.35,
set: seek,
configurable: true,
});
expect(transport.seekUnderDip(el, 8.5)).toBe(true);
expect(dipRamps(dip)).toEqual([[0, expect.closeTo(100.515, 9)]]);
expect(transport.seekUnderDip(el, 8.51)).toBe(true);
vi.advanceTimersByTime(14);
expect(seek).not.toHaveBeenCalled();
vi.advanceTimersByTime(1);
expect(seek).toHaveBeenCalledExactlyOnceWith(mediaElementTime(8.5 + 0.015));
mock.ctx.currentTime = 100.54;
el.dispatchEvent(new Event("seeked"));
expect(dipRamps(dip).at(-1)).toEqual([1, expect.closeTo(100.555, 9)]);
el.dispatchEvent(new Event("seeked"));
expect(dipRamps(dip)).toHaveLength(2);
});
it("leaves the element alone when the clip is stopped during the dip", async () => {
const { transport, el, at } = await routeTake();
at(100.5, 8.35);
const seek = vi.fn();
Object.defineProperty(el, "currentTime", {
get: () => 8.35,
set: seek,
configurable: true,
});
transport.seekUnderDip(el, 8.5);
transport.stopAll();
vi.advanceTimersByTime(15);
expect(seek).not.toHaveBeenCalled();
});
it("has no dip for an element it does not route", () => {
const { transport } = setupGroupTransport();
expect(transport.seekUnderDip(groupedAudioEl("loose"), 1)).toBe(false);
});
});
});
});
it("routes an ungrouped clip straight to master through its own gain", async () => {
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "lone");
// Clip gain (data-volume, ahead of the FX), then the lane, then the per-tick gain to master.
expect(mock.gainNodes).toHaveLength(3);
const [gain, laneGain, clipGain] = mock.gainNodes;
expect(gain!.connect).toHaveBeenCalledWith(mock.masterGain);
expect(laneGain!.connect).toHaveBeenCalledWith(gain);
expect(clipGain!.connect).toHaveBeenCalledWith(laneGain);
});
// The media-element transport is the PRIMARY path for audio — the runtime
// tries it first and only falls back to a decoded buffer. It has to reach
// the same bus, or grouping silently applies to nothing that actually plays.
// The render clamps a track volume with `clampAudioGain` (ceiling ~3.98),
// so an over-unity bus previewed at 1.0 exported up to 12 dB louder than
// it auditioned.
it("previews an over-unity bus fader at the render's ceiling, not unity", async () => {
const { transport, mock, gen } = setupGroupTransport();
document.body.innerHTML = `<hf-audio-group id="vo" data-volume="10"></hf-audio-group>`;
await scheduleGrouped(transport, gen, "a", "vo");
// Creation order: a-gain(0), groupInput(1), groupOutput(2), muteGain(3), fader(4).
expect(mock.gainNodes[4]!.gain.value).toBeCloseTo(3.9811, 3);
});
it("still floors a negative bus fader at zero", async () => {
const { transport, mock, gen } = setupGroupTransport();
document.body.innerHTML = `<hf-audio-group id="vo" data-volume="-1"></hf-audio-group>`;
await scheduleGrouped(transport, gen, "a", "vo");
expect(mock.gainNodes[4]!.gain.value).toBe(0);
});
// A bare getElementById read a member's own fader and chain as the bus's.
it("ignores a non-<hf-audio-group> element sharing the group id", async () => {
const { transport, mock, gen } = setupGroupTransport();
document.body.innerHTML = `<div id="vo" data-volume="0.25" data-hidden></div>`;
await scheduleGrouped(transport, gen, "a", "vo");
// Flat bus: unity fader, unmuted — the documented "group with no element"
// degradation, not the stranger's settings.
expect(mock.gainNodes[4]!.gain.value).toBe(1);
expect(mock.gainNodes[3]!.gain.value).toBe(1);
});
it("routes a grouped clip's MEDIA-ELEMENT playback to the group bus, not master", async () => {
const { transport, mock, gen } = setupGroupTransport();
const el = groupedAudioEl("vo-1", "vo");
await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
const clipGain = mock.gainNodes[0]!;
expect(clipGain.connect).toHaveBeenCalledWith(firstGroupInput(mock));
expect(clipGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
});
it("plays a routed clip's data-volume on its clip gain, ahead of its effects", async () => {
const { transport, mock, gen } = setupGroupTransport();
const el = groupedAudioEl("lone");
await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
transport.setElementVolume(el, 0.8, 0.5);
const [gain, , , clipGain] = mock.gainNodes;
expect(clipGain!.gain.value).toBe(0.5);
expect(gain!.gain.value).toBe(0.8);
});
it("routes an UNGROUPED clip's media-element playback straight to master", async () => {
const { transport, mock, gen } = setupGroupTransport();
const el = groupedAudioEl("lone");
await transport.scheduleMediaElementPlayback(el, 0, 0, 0, 1, gen, 1);
// Element gain to master, seek dip, lane into the element gain, clip gain into the lane.
const [gain, dip, lane, clipGain] = mock.gainNodes;
expect(mock.gainNodes).toHaveLength(4);
expect(gain!.connect).toHaveBeenCalledWith(mock.masterGain);
expect(lane!.connect).toHaveBeenCalledWith(gain);
expect(clipGain!.connect).toHaveBeenCalledWith(lane);
expect(mock.mediaElementSource.connect).toHaveBeenCalledWith(dip);
expect(dip!.connect).toHaveBeenCalledWith(clipGain);
});
it("two members of the same group land on ONE shared group gain, not master directly", async () => {
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
await scheduleGrouped(transport, gen, "b", "vo");
// Creation order for a: a-gain(0), groupInput(1), groupOutput(2),
// muteGain(3), fader(4) — the group bus is built lazily inside a's
// schedule call — then a's lane(5) and clip gain(6). Then b: b-gain(7), lane(8), clip gain(9).
expect(mock.gainNodes.length).toBeGreaterThanOrEqual(10);
const aGain = mock.gainNodes[0]!;
const groupInput = firstGroupInput(mock);
const groupOutput = mock.gainNodes[2]!;
const muteGain = mock.gainNodes[3]!;
const fader = mock.gainNodes[4]!;
const bGain = mock.gainNodes[7]!;
// Both members feed the shared bus — neither connects straight to master.
expect(aGain.connect).toHaveBeenCalledWith(groupInput);
expect(bGain.connect).toHaveBeenCalledWith(groupInput);
expect(aGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
expect(bGain.connect).not.toHaveBeenCalledWith(mock.masterGain);
// The bus's input never reaches master directly. It runs through the
// chain (dry here — neither member's group has a chain-bearing
// `<hf-audio-group>`) onto the FADER, then the mute gain (B5), then the
// output gain, then master. The fader sits POST-FX because that is where
// the render bakes group volume in.
expect(groupInput.connect).not.toHaveBeenCalledWith(mock.masterGain);
expect(groupInput.connect).toHaveBeenCalledWith(fader);
expect(fader.connect).toHaveBeenCalledWith(muteGain);
expect(muteGain.connect).toHaveBeenCalledWith(groupOutput);
expect(groupOutput.connect).toHaveBeenCalledWith(mock.masterGain);
});
it("a second member of an already-open group does not rebuild the group bus", async () => {
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const gainCountAfterFirst = mock.gainNodes.length; // a's gains + group input/output/mute/fader
await scheduleGrouped(transport, gen, "b", "vo");
// Only b's own gain, lane and clip gain are new — no second group bus minted.
expect(mock.gainNodes.length).toBe(gainCountAfterFirst + 3);
});
it("a group id with no matching <hf-audio-group> element still gets a flat bus", async () => {
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "orphan-group"); // no matching element
const muteGain = mock.gainNodes[3]!;
const groupOutput = mock.gainNodes[2]!;
const fader = mock.gainNodes[4]!;
expect(firstGroupInput(mock).connect).toHaveBeenCalledWith(fader);
expect(fader.connect).toHaveBeenCalledWith(muteGain);
expect(muteGain.connect).toHaveBeenCalledWith(groupOutput);
expect(groupOutput.connect).toHaveBeenCalledWith(mock.masterGain);
// No element to read, so the fader sits at unity.
expect(fader.gain.value).toBe(1);
});
// The old assertion here was `resolves.not.toBeNull()` — it was named for
// group volume and checked only that scheduling did not throw, so the bus
// sitting at unity while the render applied data-volume went unseen. The
// export was ~8 dB quieter than what had been auditioned.
it("puts the group's own data-volume on the bus fader", async () => {
document.body.innerHTML = `<hf-audio-group id="vo" data-label="Voiceover" data-volume="0.4"></hf-audio-group>`;
const { transport, mock, gen } = setupGroupTransport();
await expect(scheduleGrouped(transport, gen, "a", "vo")).resolves.not.toBeNull();
expect(mock.gainNodes[4]!.gain.value).toBeCloseTo(0.4, 6);
});
it("leaves the fader at unity when the group carries no data-volume", async () => {
document.body.innerHTML = `<hf-audio-group id="vo" data-label="Voiceover"></hf-audio-group>`;
const { transport, mock, gen } = setupGroupTransport();
// No throw wiring the group's automation reader against a real
// <hf-audio-group> element that carries no fx/automation attrs.
await expect(scheduleGrouped(transport, gen, "a", "vo")).resolves.not.toBeNull();
expect(mock.gainNodes[4]!.gain.value).toBe(1);
});
it("destroy() disposes every group bus", async () => {
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const groupInput = firstGroupInput(mock);
transport.destroy();
expect(groupInput.disconnect).toHaveBeenCalled();
});
it("stopAll() does NOT dispose group buses — replaying the group does not rebuild it", async () => {
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const groupInput = firstGroupInput(mock);
transport.stopAll();
expect(groupInput.disconnect).not.toHaveBeenCalled();
const gen2 = transport.startGeneration();
await scheduleGrouped(transport, gen2, "a", "vo");
// Still only one group-input gain ever created for "vo".
expect(mock.gainNodes.filter((n) => n === groupInput)).toHaveLength(1);
});
// Surviving stopAll() is the point of the bus — and the trap. Its envelopes
// were booked against the FIRST pass's absolute context times, so a replay
// or a seek left the fader holding that pass's last value: 0 after a
// fade-out, i.e. silent for the rest of the session.
it("re-anchors the reused bus once per play generation, and only once", async () => {
document.body.innerHTML = `<hf-audio-group id="vo" data-volume="0.5"></hf-audio-group>`;
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const fader = mock.gainNodes[4]!;
// Something moved the fader mid-pass (a ramp reaching its last point).
fader.gain.value = 0;
transport.stopAll();
const gen2 = transport.startGeneration();
await scheduleGrouped(transport, gen2, "a", "vo");
expect(fader.gain.value).toBeCloseTo(0.5, 6);
// A second member in the SAME pass must not re-book on top of the first.
fader.gain.value = 0;
await scheduleGrouped(transport, gen2, "b", "vo");
expect(fader.gain.value).toBe(0);
});
// reanchor runs inside schedulePlayback, whose catch turns any throw into
// `return null` — so a bus that fails to re-anchor would silently take the
// MEMBER out of the pass, and a generation stamped before the attempt would
// stop every later member retrying.
it("keeps the member playing when re-anchoring the bus throws", async () => {
document.body.innerHTML = `<hf-audio-group id="vo" data-volume="0.5"></hf-audio-group>`;
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const fader = mock.gainNodes[4]!;
fader.gain.cancelScheduledValues = vi.fn(() => {
throw new Error("param is not schedulable");
});
transport.stopAll();
const gen2 = transport.startGeneration();
await expect(scheduleGrouped(transport, gen2, "a", "vo")).resolves.not.toBeNull();
// Generation not consumed by the failed attempt, so a sibling still tries.
fader.gain.cancelScheduledValues = vi.fn();
await scheduleGrouped(transport, gen2, "b", "vo");
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, lane and clip gain, and nothing else.
expect(setup.mock.gainNodes.length).toBe(nodesAfterFirst + 3);
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>`;
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const muteGain = mock.gainNodes[3]!;
expect(muteGain.gain.value).toBe(0);
});
it("setGroupMuted toggles the mute gain on an active group bus", async () => {
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const muteGain = mock.gainNodes[3]!;
expect(muteGain.gain.value).toBe(1);
transport.setGroupMuted("vo", true);
expect(muteGain.gain.value).toBe(0);
transport.setGroupMuted("vo", false);
expect(muteGain.gain.value).toBe(1);
});
it("setGroupMuted on a group with no active member is a no-op, not a throw", () => {
const { transport } = setupGroupTransport();
expect(() => transport.setGroupMuted("never-played", true)).not.toThrow();
});
});
describe("level metering", () => {
const addGroup = (id: string) => {
document.body.insertAdjacentHTML(
"beforeend",
`<hf-audio-group id="${id}"></hf-audio-group>`,
);
};
const setLevel = (analyser: { getFloatTimeDomainData: unknown }, peak: number) => {
(analyser.getFloatTimeDomainData as ReturnType<typeof vi.fn>).mockImplementation(
(buf: Float32Array) => buf.fill(0).fill(-peak, 3, 4),
);
};
it("creates nothing until startMetering", async () => {
addGroup("vo");
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
expect(mock.ctx.createAnalyser).not.toHaveBeenCalled();
expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
});
it("attaches the master tap once init() lands, even when startMetering ran while the context was still warming up", async () => {
const mock = createGroupMockAudioContext();
class MockAudioContext {
constructor() {
return mock.ctx as unknown as MockAudioContext;
}
}
vi.stubGlobal("AudioContext", MockAudioContext);
const transport = new WebAudioTransport();
transport.startMetering();
expect(mock.ctx.createAnalyser).not.toHaveBeenCalled();
expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
const ok = await transport.init();
expect(ok).toBe(true);
expect(mock.ctx.createAnalyser).toHaveBeenCalled();
expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
vi.unstubAllGlobals();
});
it("taps master and each group as side branches, once however often it starts", async () => {
addGroup("vo");
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
const groupOutput = mock.gainNodes[2]!;
const connectsBefore = groupOutput.connect.mock.calls.length;
transport.startMetering();
transport.startMetering();
expect(mock.analysers).toHaveLength(4);
expect(groupOutput.connect).toHaveBeenCalledTimes(connectsBefore + 1);
expect(groupOutput.connect).toHaveBeenCalledWith(mock.masterGain);
expect(mock.masterGain.connect).toHaveBeenCalledTimes(1);
expect(mock.monitorGain.connect).not.toHaveBeenCalled();
});
it("keeps program taps off the monitor fader", async () => {
addGroup("vo");
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
transport.startMetering();
transport.setVolume(0.5);
transport.setMuted(true);
const groupOutput = mock.gainNodes.find((n) =>
n.connect.mock.calls.some((call) => call[0] === mock.masterGain),
);
expect(mock.masterGain.gain.value).toBe(1);
expect(groupOutput?.gain.value).toBe(1);
expect(mock.monitorGain.gain.value).toBe(0);
});
it("reads the peak per channel and stops cleanly", async () => {
addGroup("vo");
const { transport, mock, gen } = setupGroupTransport();
await scheduleGrouped(transport, gen, "a", "vo");
transport.startMetering();
const [masterL, , groupL, groupR] = mock.analysers;
setLevel(masterL!, 0.5);
setLevel(groupL!, 0.25);
setLevel(groupR!, 0.125);
const levels = transport.readLevels();
expect(levels.master).toEqual({ l: 0.5, r: 0 });
expect(levels.groups.vo).toEqual({ l: 0.25, r: 0.125 });
transport.stopMetering();
expect(transport.readLevels()).toEqual({ master: { l: 0, r: 0 }, groups: {} });
expect(mock.gainNodes[2]!.disconnect).toHaveBeenCalled();
});
it("a group built after start is metered, and one removed from the document leaves the read", async () => {
const { transport, mock, gen } = setupGroupTransport();
transport.startMetering();
addGroup("late");
await scheduleGrouped(transport, gen, "a", "late");
expect(Object.keys(transport.readLevels().groups)).toEqual(["late"]);
document.querySelector("hf-audio-group")!.remove();
expect(transport.readLevels().groups).toEqual({});
expect(mock.analysers).toHaveLength(4);
});
});
});
describe("decode budget", () => {
const audio = (src: string, duration: number) =>
({
tagName: "AUDIO",
getAttribute: (name: string) => (name === "src" ? src : null),
currentSrc: "",
duration,
}) as unknown as HTMLMediaElement;
const transport = () => {
const t = new WebAudioTransport();
(t as unknown as { _ctx: unknown })._ctx = { sampleRate: 48000, decodeAudioData: vi.fn() };
return t;
};
it("takes a ten minute source and refuses a one hour one", () => {
const t = transport();
expect(t.fitsDecodeBudget(audio("a.mp4", 600))).toBe(true);
expect(t.fitsDecodeBudget(audio("b.mp4", 3600))).toBe(false);
});
it("counts a source that is decoding against the next one", async () => {
const t = transport();
vi.stubGlobal(
"fetch",
vi.fn(() => new Promise(() => {})),
);
void t.decodeAudioElement(audio("a.mp4", 600));
expect(t.fitsDecodeBudget(audio("a.mp4", 600))).toBe(true);
expect(t.fitsDecodeBudget(audio("b.mp4", 100))).toBe(false);
expect(t.fitsDecodeBudget(audio("c.mp4", 10))).toBe(true);
vi.unstubAllGlobals();
});
it("leaves a clip that has not loaded to its source", () => {
expect(transport().fitsDecodeBudget(audio("a.mp4", Number.NaN))).toBe(false);
});
});
describe("decodeAudioElement retry policy (late-asset self-heal)", () => {
function transportWithDecode(decodeImpl: () => Promise<AudioBuffer>) {
const transport = new WebAudioTransport();
const ctx = { state: "running", decodeAudioData: vi.fn(decodeImpl) };
(transport as unknown as { _ctx: unknown })._ctx = ctx;
return transport;
}
const el = (src: string) =>
({
tagName: "AUDIO",
getAttribute: (name: string) => (name === "src" ? src : null),
currentSrc: "",
}) as unknown as HTMLMediaElement;
const failedSrcs = (t: WebAudioTransport) =>
(t as unknown as { _failedSrcs: Set<string> })._failedSrcs;
// Keys are resolved against the document, so one asset has one key however it is written.
const key = (src: string) => new URL(src, document.baseURI).href;
it("does NOT blacklist a transient fetch failure — a later play retries and succeeds", async () => {
const transport = transportWithDecode(async () => ({}) as AudioBuffer);
const fetchMock = vi
.fn()
.mockResolvedValueOnce({ ok: false, status: 404 }) // asset not uploaded yet
.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
vi.stubGlobal("fetch", fetchMock);
const first = await transport.decodeAudioElement(el("tts.wav"));
expect(first).toBeNull();
expect(failedSrcs(transport).has(key("tts.wav"))).toBe(false); // not permanently silenced
const second = await transport.decodeAudioElement(el("tts.wav"));
expect(second).not.toBeNull(); // self-heals once the asset is available
expect(fetchMock).toHaveBeenCalledTimes(2);
vi.unstubAllGlobals();
});
it("DOES blacklist genuinely undecodable bytes — not retried", async () => {
const transport = transportWithDecode(async () => {
throw new Error("unsupported codec");
});
const fetchMock = vi
.fn()
.mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
vi.stubGlobal("fetch", fetchMock);
const first = await transport.decodeAudioElement(el("corrupt.wav"));
expect(first).toBeNull();
expect(failedSrcs(transport).has(key("corrupt.wav"))).toBe(true); // bad data is permanent
const second = await transport.decodeAudioElement(el("corrupt.wav"));
expect(second).toBeNull();
expect(fetchMock).toHaveBeenCalledTimes(1); // short-circuited, no re-fetch
vi.unstubAllGlobals();
});
it("hands a clip that decodes short to its element, and keeps one short only by its priming", async () => {
// Measured in Chromium 156 and WebKit 27.2: a 4 s AAC file whose mdhd timescale says 44.1 kHz over a
// 48 kHz stream decodes to 3.669 s; Apple's HE-AAC of the same tone decodes to 4.0 s under a 4.133 s element.
const withDuration = (src: string, duration: number) =>
Object.assign(el(src), { duration }) as HTMLMediaElement;
const transport = transportWithDecode(async () => ({ duration: 3.669 }) as AudioBuffer);
const fetchMock = vi
.fn()
.mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
vi.stubGlobal("fetch", fetchMock);
expect(await transport.decodeAudioElement(withDuration("vo.m4a", 4))).toBeNull();
expect(failedSrcs(transport).has(key("vo.m4a"))).toBe(true);
const primed = transportWithDecode(async () => ({ duration: 4 }) as AudioBuffer);
expect(await primed.decodeAudioElement(withDuration("he.m4a", 4.133))).not.toBeNull();
expect(await primed.decodeAudioElement(withDuration("rec.webm", Infinity))).not.toBeNull();
vi.unstubAllGlobals();
});
it("fetches and decodes a source once when a play and a seek both ask before it decodes", async () => {
const decoded = {} as AudioBuffer;
const transport = transportWithDecode(async () => decoded);
const fetchMock = vi.fn(async () => ({
ok: true,
arrayBuffer: async () => new ArrayBuffer(8),
}));
vi.stubGlobal("fetch", fetchMock);
const both = await Promise.all([
transport.decodeAudioElement(el("sfx.wav")),
transport.decodeAudioElement(el("sfx.wav")),
]);
expect(both).toEqual([decoded, decoded]);
expect(fetchMock).toHaveBeenCalledTimes(1);
vi.unstubAllGlobals();
});
it("keeps a listed clip's decoded audio while its load is between resources", async () => {
// An in-place sub-composition reload resets the root voiceover's resource selection, so
// `currentSrc` reads empty and the relative attribute behind it keyed a second cache slot:
// the release pass then dropped the buffer of a clip it was handed as live.
const transport = transportWithDecode(async () => ({}) as AudioBuffer);
const fetchMock = vi
.fn()
.mockResolvedValue({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
vi.stubGlobal("fetch", fetchMock);
const vo = document.createElement("audio");
vo.setAttribute("src", "vo.mp3");
let currentSrc = new URL("vo.mp3", document.baseURI).href;
Object.defineProperty(vo, "currentSrc", { configurable: true, get: () => currentSrc });
expect(await transport.decodeAudioElement(vo)).not.toBeNull();
currentSrc = "";
transport.releaseDecodedExcept([vo]);
currentSrc = new URL("vo.mp3", document.baseURI).href;
expect(await transport.decodeAudioElement(vo)).not.toBeNull();
expect(fetchMock).toHaveBeenCalledTimes(1); // the buffer it was told to keep is still there
vi.unstubAllGlobals();
});
it("keys a clip whose src cannot be read as a URL without throwing", () => {
const transport = transportWithDecode(async () => ({}) as AudioBuffer);
const bad = document.createElement("audio");
bad.setAttribute("src", "http://localhost:PORT/vo.mp3");
expect(() => transport.releaseDecodedExcept([bad])).not.toThrow();
});
});
});
describe("WebAudioTransport clip fades on the audio clock", () => {
type Param = {
value: number;
setValueAtTime: ReturnType<typeof vi.fn>;
linearRampToValueAtTime: ReturnType<typeof vi.fn>;
cancelScheduledValues: ReturnType<typeof vi.fn>;
};
const param = (): Param => ({
value: 1,
setValueAtTime: vi.fn(),
linearRampToValueAtTime: vi.fn(),
cancelScheduledValues: vi.fn(),
});
/** A context whose gains record their automation; the element gain is the first one made. */
function setup(currentTime = 100) {
const { transport, mock, gen } = setupTransport(currentTime);
const gains: {
gain: Param;
connect: ReturnType<typeof vi.fn>;
disconnect: ReturnType<typeof vi.fn>;
}[] = [];
mock.ctx.createGain = vi.fn(() => {
const node = { gain: param(), connect: vi.fn(), disconnect: vi.fn() };
gains.push(node);
return node;
}) as never;
const booked = () => gains.find((g) => g.gain.setValueAtTime.mock.calls.length > 0)?.gain;
return { transport, mock, gen, gains, booked };
}
const faded = (fadeIn = "0.02", fadeOut = "0.02") =>
({
muted: false,
volume: 1,
paused: true,
addEventListener: () => {},
getAttribute: (name: string) =>
({ "data-playback-rate": "1", "data-fade-in": fadeIn, "data-fade-out": fadeOut })[name] ??
null,
}) as unknown as HTMLMediaElement;
it("a decoded clip ramps in over its fade-in from its start and out to silence at its end", async () => {
const { transport, gen, booked } = setup(100);
await transport.schedulePlayback(faded(), mockBuffer, 5, 0, () => 5, 1, gen, 1, 1);
const gain = booked();
expect(gain?.setValueAtTime.mock.calls).toEqual([
[0, 100],
[1, expect.closeTo(100.98, 9)],
]);
expect(gain?.linearRampToValueAtTime.mock.calls).toEqual([
[1, expect.closeTo(100.02, 9)],
[0, expect.closeTo(101, 9)],
]);
});
it("a clip started halfway through its fade-in starts at half level", async () => {
const { transport, gen, booked } = setup(100);
await transport.schedulePlayback(faded(), mockBuffer, 5, 0, () => 5.01, 1, gen, 1, 1);
const gain = booked();
expect(gain?.setValueAtTime.mock.calls[0]).toEqual([expect.closeTo(0.5, 9), 100]);
expect(gain?.linearRampToValueAtTime.mock.calls[0]).toEqual([1, expect.closeTo(100.01, 9)]);
});
it("a captured media element books its fades the same way", async () => {
const { transport, gen, booked } = setup(100);
await transport.scheduleMediaElementPlayback(faded(), 5, 0, 5, 1, gen, 1, 1);
expect(booked()?.linearRampToValueAtTime.mock.calls).toEqual([
[1, expect.closeTo(100.02, 9)],
[0, expect.closeTo(101, 9)],
]);
});
it("a clip scheduled ahead of its start holds its fade-in's first level until it starts", async () => {
const { transport, gen, booked } = setup(100);
await transport.schedulePlayback(faded(), mockBuffer, 5, 0, () => 4.9, 1, gen, 1, 1);
const gain = booked();
expect(gain?.value).toBe(0);
expect(gain?.setValueAtTime.mock.calls[0]).toEqual([0, expect.closeTo(100.1, 9)]);
});
it("a fade-out with no clip end books nothing, so the per-tick volume keeps the fade", async () => {
const { transport, gen, gains, booked } = setup(100);
const el = faded("0.02", "2");
await transport.scheduleMediaElementPlayback(el, 5, 0, 5, 1, gen, 1);
expect(booked()).toBeUndefined();
transport.setElementVolume(el, 0.4, 1, 0.8);
expect(gains[0]!.gain.value).toBeCloseTo(0.4, 9);
});
it("a rate change rebooks a decoded clip's fades on the new rate from where the clip is", async () => {
const { transport, mock, gen, booked } = setup(100);
await transport.schedulePlayback(faded("0.02", "1"), mockBuffer, 5, 0, () => 5, 1, gen, 2, 10);
const gain = booked()!;
mock.ctx.currentTime = 101;
transport.setRate(1);
expect(gain.cancelScheduledValues).toHaveBeenCalled();
expect(gain.linearRampToValueAtTime.mock.calls.at(-1)).toEqual([
0,
expect.closeTo(101 + (10 - 2), 9),
]);
});
it("a clip without fades books nothing", async () => {
const { transport, gen, booked } = setup(100);
await transport.schedulePlayback(faded("", ""), mockBuffer, 5, 0, () => 5, 1, gen, 1, 1);
expect(booked()).toBeUndefined();
});
it("the per-tick volume leaves out the fade where it is booked, and keeps it where it is not", async () => {
const { transport, gen, gains } = setup(100);
const withFades = faded();
await transport.schedulePlayback(withFades, mockBuffer, 5, 0, () => 5, 1, gen, 1, 1);
const elementGain = gains[0]!.gain;
transport.setElementVolume(withFades, 0.4, 1, 0.8);
expect(elementGain.value).toBeCloseTo(0.8, 9);
const second = setup(100);
const plain = faded("", "");
await second.transport.schedulePlayback(plain, mockBuffer, 5, 0, () => 5, 1, second.gen, 1, 1);
second.transport.setElementVolume(plain, 0.4, 1, 0.8);
expect(second.gains[0]!.gain.value).toBeCloseTo(0.4, 9);
});
});