Skip to content

Commit 6d02056

Browse files
miguel-heygenclaude
andcommitted
fix(runtime): address re-review — mute restore, tests, buffer-stall, race guard
Addresses all open review items: - Fix el.muted leak: WebAudioTransport now tracks priorMuted and restores it in stopAll(). Prevents silent audio when falling back to HTMLMediaElement after WebAudio detaches. - Fix async race: play generation counter prevents stale decode→schedule callbacks from firing after a rapid pause/play cycle. - Fix buffer-stall: when audio.paused && readyState < HAVE_FUTURE_DATA, freeze visuals at current position instead of falling through to monotonic (which runs ahead of buffering audio). - Fix synthetic HTMLMediaElement: replaced brittle cast with typed { currentTimeSeconds } discriminated union on AudioClockSource. - Add webAudioTransport.test.ts: 6 tests covering generation tracking, mute restore, destroy cleanup. - Add media.test.ts integration tests: strict-sync consecutive samples, buffering guard, forceSync immediate correction. 53 tests total, all passing. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
1 parent 71db034 commit 6d02056

5 files changed

Lines changed: 166 additions & 27 deletions

File tree

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

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,15 @@ export type TransportClockSnapshot = {
66
source: "monotonic" | "audio";
77
};
88

9-
export type AudioClockSource = {
10-
el: HTMLMediaElement;
11-
compositionStart: number;
12-
mediaStart: number;
13-
};
9+
export type AudioClockSource =
10+
| {
11+
el: HTMLMediaElement;
12+
compositionStart: number;
13+
mediaStart: number;
14+
}
15+
| {
16+
currentTimeSeconds: number;
17+
};
1418

1519
export class TransportClock {
1620
private _baseTime = 0;
@@ -35,17 +39,23 @@ export class TransportClock {
3539
now(): number {
3640
if (this._playStartMs === null) return this._baseTime;
3741

38-
// Audio-master: when an audio element is attached and playing,
39-
// derive time from its currentTime. Drift is impossible because
40-
// audio IS the clock.
42+
// Audio-master: when an audio source is attached, derive time
43+
// from it. Drift is impossible because audio IS the clock.
4144
if (this._audioSource) {
42-
const { el, compositionStart, mediaStart } = this._audioSource;
43-
if (!el.paused && Number.isFinite(el.currentTime)) {
44-
const t = (el.currentTime - mediaStart) / this._rate + compositionStart;
45-
if (Number.isFinite(this._duration) && t >= this._duration) {
45+
let audioTime: number | null = null;
46+
if ("currentTimeSeconds" in this._audioSource) {
47+
audioTime = this._audioSource.currentTimeSeconds;
48+
} else {
49+
const { el, compositionStart, mediaStart } = this._audioSource;
50+
if (!el.paused && Number.isFinite(el.currentTime)) {
51+
audioTime = (el.currentTime - mediaStart) / this._rate + compositionStart;
52+
}
53+
}
54+
if (audioTime !== null) {
55+
if (Number.isFinite(this._duration) && audioTime >= this._duration) {
4656
return this._duration;
4757
}
48-
return Math.max(0, t);
58+
return Math.max(0, audioTime);
4959
}
5060
}
5161

@@ -128,6 +138,7 @@ export class TransportClock {
128138

129139
getSource(): "monotonic" | "audio" {
130140
if (this._audioSource && this._playStartMs !== null) {
141+
if ("currentTimeSeconds" in this._audioSource) return "audio";
131142
const { el } = this._audioSource;
132143
if (!el.paused && Number.isFinite(el.currentTime)) return "audio";
133144
}

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

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1736,11 +1736,7 @@ export function initSandboxRuntimeModular(): void {
17361736
if (webAudio.isActive() && webAudio.context) {
17371737
const webAudioTime = webAudio.getTime();
17381738
if (webAudioTime >= 0) {
1739-
clock.attachAudioSource({
1740-
el: { currentTime: webAudioTime, paused: false } as HTMLMediaElement,
1741-
compositionStart: 0,
1742-
mediaStart: 0,
1743-
});
1739+
clock.attachAudioSource({ currentTimeSeconds: webAudioTime });
17441740
}
17451741
} else {
17461742
const audioEls = document.querySelectorAll("audio[data-start]");
@@ -1753,14 +1749,16 @@ export function initSandboxRuntimeModular(): void {
17531749
const mediaStart =
17541750
Number.parseFloat(rawEl.dataset.playbackStart ?? rawEl.dataset.mediaStart ?? "0") ||
17551751
0;
1756-
if (
1757-
Number.isFinite(start) &&
1758-
state.currentTime >= start &&
1759-
state.currentTime < end &&
1760-
!rawEl.paused
1761-
) {
1762-
clock.attachAudioSource({ el: rawEl, compositionStart: start, mediaStart });
1763-
foundActive = true;
1752+
if (Number.isFinite(start) && state.currentTime >= start && state.currentTime < end) {
1753+
if (!rawEl.paused) {
1754+
clock.attachAudioSource({ el: rawEl, compositionStart: start, mediaStart });
1755+
foundActive = true;
1756+
} else if (rawEl.readyState < HTMLMediaElement.HAVE_FUTURE_DATA) {
1757+
// Audio is buffering — freeze visuals at last known position
1758+
// instead of falling through to monotonic (which runs ahead).
1759+
clock.attachAudioSource({ currentTimeSeconds: state.currentTime });
1760+
foundActive = true;
1761+
}
17641762
break;
17651763
}
17661764
}
@@ -1850,6 +1848,7 @@ export function initSandboxRuntimeModular(): void {
18501848
// Falls back to HTMLMediaElement playback if WebAudio isn't ready
18511849
// or decoding fails (the syncRuntimeMedia path handles that).
18521850
if (webAudioReady) {
1851+
const gen = webAudio.startGeneration();
18531852
const audioEls = document.querySelectorAll("audio[data-start]");
18541853
for (const rawEl of audioEls) {
18551854
if (!(rawEl instanceof HTMLMediaElement) || !rawEl.isConnected) continue;
@@ -1868,6 +1867,7 @@ export function initSandboxRuntimeModular(): void {
18681867
mediaStart,
18691868
clock.now(),
18701869
vol * state.bridgeVolume,
1870+
gen,
18711871
);
18721872
});
18731873
}

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -642,6 +642,42 @@ describe("syncRuntimeMedia", () => {
642642
expect(posted).toBe(1);
643643
});
644644

645+
it("corrects stable sub-0.5s drift after consecutive over-threshold ticks", () => {
646+
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
647+
Object.defineProperty(clip.el, "currentTime", { value: 5.4, writable: true });
648+
syncRuntimeMedia({ clips: [clip], timeSeconds: 5.4, playing: true, playbackRate: 1 });
649+
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
650+
expect(clip.el.currentTime).toBe(5.4);
651+
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
652+
expect(clip.el.currentTime).toBe(5.4);
653+
syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
654+
expect(clip.el.currentTime).toBe(5);
655+
});
656+
657+
it("does not force audio forward while it's still buffering (gradual drift growth)", () => {
658+
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
659+
Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
660+
syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
661+
for (let t = 0.016; t < 0.7; t += 0.016) {
662+
syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
663+
}
664+
expect(clip.el.currentTime).toBe(0);
665+
});
666+
667+
it("forceSync corrects any drift above 20ms immediately", () => {
668+
const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
669+
Object.defineProperty(clip.el, "currentTime", { value: 5.1, writable: true });
670+
syncRuntimeMedia({ clips: [clip], timeSeconds: 5.1, playing: true, playbackRate: 1 });
671+
syncRuntimeMedia({
672+
clips: [clip],
673+
timeSeconds: 5,
674+
playing: true,
675+
playbackRate: 1,
676+
forceSync: true,
677+
});
678+
expect(clip.el.currentTime).toBe(5);
679+
});
680+
645681
it("mutes when either outputMuted OR userMuted is true (OR invariant)", () => {
646682
// Explicit validation of the combined-flag contract: setting one to
647683
// false while the other is true must keep the element muted.
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
import { describe, it, expect, vi } from "vitest";
2+
import { WebAudioTransport } from "./webAudioTransport";
3+
4+
describe("WebAudioTransport", () => {
5+
it("tracks play generation for async race prevention", () => {
6+
const transport = new WebAudioTransport();
7+
expect(transport.currentGeneration()).toBe(0);
8+
const gen1 = transport.startGeneration();
9+
expect(gen1).toBe(1);
10+
const gen2 = transport.startGeneration();
11+
expect(gen2).toBe(2);
12+
expect(transport.currentGeneration()).toBe(2);
13+
});
14+
15+
it("getTime returns -1 when paused", () => {
16+
const transport = new WebAudioTransport();
17+
expect(transport.getTime()).toBe(-1);
18+
});
19+
20+
it("isActive returns false initially", () => {
21+
const transport = new WebAudioTransport();
22+
expect(transport.isActive()).toBe(false);
23+
});
24+
25+
it("stopAll restores el.muted to prior value", () => {
26+
const transport = new WebAudioTransport();
27+
const mockEl = { muted: false } as HTMLMediaElement;
28+
const mockSource = {
29+
el: mockEl,
30+
sourceNode: { stop: vi.fn(), disconnect: vi.fn() } as unknown as AudioBufferSourceNode,
31+
gainNode: { disconnect: vi.fn() } as unknown as GainNode,
32+
compositionStart: 0,
33+
mediaStart: 0,
34+
scheduledAt: 0,
35+
priorMuted: false,
36+
};
37+
// Simulate WebAudio taking over: el.muted was set to true
38+
mockEl.muted = true;
39+
(transport as unknown as { _activeSources: (typeof mockSource)[] })._activeSources = [
40+
mockSource,
41+
];
42+
(transport as unknown as { _paused: boolean })._paused = false;
43+
44+
expect(transport.isActive()).toBe(true);
45+
transport.stopAll();
46+
expect(mockEl.muted).toBe(false);
47+
expect(transport.isActive()).toBe(false);
48+
});
49+
50+
it("stopAll restores el.muted=true when element was already muted", () => {
51+
const transport = new WebAudioTransport();
52+
const mockEl = { muted: true } as HTMLMediaElement;
53+
const mockSource = {
54+
el: mockEl,
55+
sourceNode: { stop: vi.fn(), disconnect: vi.fn() } as unknown as AudioBufferSourceNode,
56+
gainNode: { disconnect: vi.fn() } as unknown as GainNode,
57+
compositionStart: 0,
58+
mediaStart: 0,
59+
scheduledAt: 0,
60+
priorMuted: true,
61+
};
62+
(transport as unknown as { _activeSources: (typeof mockSource)[] })._activeSources = [
63+
mockSource,
64+
];
65+
66+
transport.stopAll();
67+
expect(mockEl.muted).toBe(true);
68+
});
69+
70+
it("destroy clears buffer cache and nulls context", () => {
71+
const transport = new WebAudioTransport();
72+
transport.destroy();
73+
expect(transport.context).toBeNull();
74+
expect(transport.isActive()).toBe(false);
75+
});
76+
});

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ export type ScheduledSource = {
77
compositionStart: number;
88
mediaStart: number;
99
scheduledAt: number;
10+
priorMuted: boolean;
1011
};
1112

1213
export class WebAudioTransport {
@@ -16,6 +17,7 @@ export class WebAudioTransport {
1617
private _masterGain: GainNode | null = null;
1718
private _scheduleOffset = 0;
1819
private _paused = true;
20+
private _playGeneration = 0;
1921

2022
async init(): Promise<boolean> {
2123
try {
@@ -54,20 +56,32 @@ export class WebAudioTransport {
5456
}
5557
}
5658

59+
startGeneration(): number {
60+
this._playGeneration += 1;
61+
return this._playGeneration;
62+
}
63+
64+
currentGeneration(): number {
65+
return this._playGeneration;
66+
}
67+
5768
async schedulePlayback(
5869
el: HTMLMediaElement,
5970
buffer: AudioBuffer,
6071
compositionStart: number,
6172
mediaStart: number,
6273
compositionTime: number,
6374
volume: number,
75+
generation: number,
6476
): Promise<ScheduledSource | null> {
6577
if (!this._ctx || !this._masterGain) return null;
78+
if (generation !== this._playGeneration) return null;
6679

6780
try {
6881
if (this._ctx.state === "suspended") {
6982
await this._ctx.resume();
7083
}
84+
if (generation !== this._playGeneration) return null;
7185

7286
const sourceNode = this._ctx.createBufferSource();
7387
sourceNode.buffer = buffer;
@@ -82,7 +96,7 @@ export class WebAudioTransport {
8296
this._scheduleOffset = scheduledAt - compositionTime;
8397
sourceNode.start(0, offset);
8498

85-
// Mute the original element — WebAudio handles output
99+
const priorMuted = el.muted;
86100
el.muted = true;
87101

88102
const scheduled: ScheduledSource = {
@@ -92,6 +106,7 @@ export class WebAudioTransport {
92106
compositionStart,
93107
mediaStart,
94108
scheduledAt,
109+
priorMuted,
95110
};
96111
this._activeSources.push(scheduled);
97112
this._paused = false;
@@ -111,6 +126,7 @@ export class WebAudioTransport {
111126
} catch {
112127
// already stopped
113128
}
129+
source.el.muted = source.priorMuted;
114130
}
115131
this._activeSources = [];
116132
this._paused = true;

0 commit comments

Comments
 (0)