Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 43 additions & 3 deletions js/watch/src/sync.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -147,15 +147,55 @@ describe("wait", () => {
sync.close();
});

it("wakes a sleeping wait on reset", async () => {
it("holds a sleeping wait across a reset until the next frame re-anchors", async () => {
const sync = new Sync({ delay: 10_000 as Time.Milli });
await flush();
sync.received(Time.Milli.now());
const timestamp = Time.Milli.now();
sync.received(timestamp);

let woke = false;
const waiting = sync.wait(timestamp).then(() => {
woke = true;
});
await flush();
sync.reset();
await flush();
expect(woke).toBe(false);

// The next frame anchors far enough ahead that this one is overdue.
sync.received(Time.Milli.add(timestamp, Time.Milli(20_000)));
await waiting;
expect(woke).toBe(true);
sync.close();
});

const waiting = sync.wait(Time.Milli.now());
it("releases a wait parked across a reset when its signal aborts", async () => {
const sync = new Sync({ delay: 10_000 as Time.Milli });
await flush();
const timestamp = Time.Milli.now();
sync.received(timestamp);

const controller = new AbortController();
const waiting = sync.wait(timestamp, controller.signal);
await flush();
sync.reset();
await flush();
controller.abort();
await waiting;
sync.close();
});

it("releases a wait parked across a reset when closed", async () => {
const sync = new Sync({ delay: 10_000 as Time.Milli });
await flush();
const timestamp = Time.Milli.now();
sync.received(timestamp);

const waiting = sync.wait(timestamp);
await flush();
sync.reset();
await flush();
sync.close();
await waiting;
});
});
53 changes: 42 additions & 11 deletions js/watch/src/sync.ts
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,11 @@ export class Sync {

#media = new Signal<{ target: Getter<Time.Milli | undefined> }[]>([]);

#epoch = 0;

// Releases parked waits, which may otherwise sleep forever on a reference that never returns.
#closed = new Signal(false);

#signals = new Effect();

constructor(props?: Inputs<SyncInput>) {
Expand Down Expand Up @@ -197,10 +202,20 @@ export class Sync {
// in buffered mode (typically alongside flushing the audio buffer) so the new content
// plays from its own first frame instead of inheriting the previous reference.
reset(): void {
this.#epoch++;
this.#out.reference.set(undefined);
this.#late.clear();
}

/**
* Bumped by every `reset()`. A frame that waited across a bump belongs to the previous
* timeline, even when the next frame restores the same reference value.
* @internal
*/
get epoch(): number {
return this.#epoch;
}

// The PTS that should be rendering right now, derived from the reference + buffer.
// Returns undefined if no frames have been received yet.
now(): Time.Milli | undefined {
Expand All @@ -209,8 +224,13 @@ export class Sync {
return Time.Milli.sub(Time.Milli.sub(Time.Milli.now(), reference), this.#out.delay.peek());
}

// Sleep until it's time to render this frame.
async wait(timestamp: Time.Milli): Promise<void> {
/**
* Sleep until it's time to render this frame, or until `signal` aborts.
*
* A reset holds the wait until the next frame re-anchors the clock, then measures the frame
* against that new reference. Aborting resolves the wait early and releases it.
*/
async wait(timestamp: Time.Milli, signal?: AbortSignal): Promise<void> {
// A zero delay still sleeps: the sleep comes from the reference, which holds an early frame
// until its timestamp comes up. "instant" is the only thing that skips the wait itself.
// Peek the input, not `out.instant`, which lags a same-turn change until effects flush.
Expand All @@ -222,43 +242,53 @@ export class Sync {
}

for (;;) {
// Switching to "instant" wakes the sleep below, so frames parked here leave.
if (this.in.delay.peek() === "instant") return;
// Switching to "instant", closing, or aborting wakes the sleep below, so frames parked here leave.
if (this.in.delay.peek() === "instant" || this.#closed.peek() || signal?.aborted) return;

// Sleep until it's time to decode the next frame.
// NOTE: This function runs in parallel for each frame.
const now = Time.Milli.now();
const ref = Time.Milli.sub(now, timestamp);

const currentRef = this.#out.reference.peek();
if (currentRef === undefined) return;
if (currentRef === undefined) {
await this.#sleep(undefined, signal);
continue;
Comment on lines +254 to +256

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Cancel reference-less waits when Sync closes

If reset() is followed by teardown or end-of-stream before another frame calls received(), every parked wait enters this parameterless sleep and can never settle: Sync.close() only closes #signals, while effect.race cancels its race listener rather than the underlying sync.wait() promise. Each orphaned sleep retains three changed callbacks, and externally owned player inputs can keep the closed Sync rooted, so repeated reset/close cycles accumulate listeners; make this wait observe scoped teardown or another explicit close signal.

AGENTS.md reference: js/AGENTS.md:L16-L17

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 3def6f3: Sync.close() now sets a private closed signal that wakes every parked sleep, releasing its listeners. A regression test parks a wait across a reset and closes. Without the fix it times out.

(Written by Claude Opus 5.5)

}

const sleep = Time.Milli.add(Time.Milli.sub(currentRef, ref), this.#out.delay.peek());
if (sleep <= 0) return;

// Skip setTimeout for small sleeps; the timer resolution (~4ms) would overshoot.
if (sleep < 5) return;

if (await this.#sleep(sleep)) return;
if (await this.#sleep(sleep, signal)) return;
}
}

// Sleeps for `ms`, or returns false early once anything the sleep was computed from changes.
// Releases every listener either way: frames sleep once each, so a listener left on a signal
// that never changes would pile up for the life of the player.
#sleep(ms: number): Promise<boolean> {
// Sleeps for `ms` (forever if undefined), or returns false early once anything the sleep was
// computed from changes or `signal` aborts. Releases every listener either way: frames sleep
// once each, so a listener left on a signal that never changes would pile up for the life of
// the player.
#sleep(ms: number | undefined, signal?: AbortSignal): Promise<boolean> {
return new Promise((resolve) => {
const wake = (ok: boolean) => {
clearTimeout(timer);
for (const dispose of disposes) dispose();
resolve(ok);
};
const timer = setTimeout(() => wake(true), ms);
const timer = ms === undefined ? undefined : setTimeout(() => wake(true), ms);
const disposes = [
this.in.delay.changed(() => wake(false)),
this.#out.delay.changed(() => wake(false)),
this.#out.reference.changed(() => wake(false)),
this.#closed.changed(() => wake(false)),
];
if (signal) {
const abort = () => wake(false);
signal.addEventListener("abort", abort, { once: true });
disposes.push(() => signal.removeEventListener("abort", abort));
}
});
}

Expand All @@ -272,6 +302,7 @@ export class Sync {
}

close() {
this.#closed.set(true);
this.#signals.close();
}
}
115 changes: 113 additions & 2 deletions js/watch/src/video/decoder.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import * as Moq from "@moq/net";
import { Time } from "@moq/net";
import { type Effect, Signal } from "@moq/signals";
import type { Broadcast } from "../broadcast";
import { Sync } from "../sync";
import { type Delay, Sync } from "../sync";
import { Decoder } from "./decoder";
import { Source } from "./source";

Expand Down Expand Up @@ -270,12 +270,14 @@ async function guardedPlayback(kind: "legacy" | "cmaf", reads: Read[], hold: rea
mediaProducer.close();
};
const source = new Source({ broadcast, supported: async () => true });
const sync = new Sync({ delay: "instant" });
const delay = new Signal<Delay>("instant");
const sync = new Sync({ delay });
const enabled = new Signal(true);
const decoder = new Decoder({ source, sync, enabled });
await microtasks();
return {
decoder,
delay,
fail: (error: DOMException, index = -1) => errors.at(index)?.(error),
emit: (timestamp: number, index = -1) => frames.at(index)?.(new Picture(timestamp) as unknown as VideoFrame),
get codecs() {
Expand Down Expand Up @@ -588,3 +590,112 @@ for (const kind of ["legacy", "cmaf"] as const) {
}
});
}

it("a shared audio clock reset cannot present a parked video frame", async () => {
const now = spyOn(Time.Milli, "now").mockReturnValue(Time.Milli(1000));
const timer = spyOn(globalThis, "setTimeout").mockImplementation(
(() => 1 as unknown as ReturnType<typeof setTimeout>) as unknown as typeof setTimeout,
);
const clear = spyOn(globalThis, "clearTimeout").mockImplementation(() => {});
const reads: Read[] = [];
const playback = await guardedPlayback("legacy", reads);
try {
playback.enabled.set(false);
playback.delay.set(Time.Milli(1000));
await microtasks();
reads.push(sample(0, 0), sample(0, 100_000, 0, false));
playback.enabled.set(true);
await microtasks();
expect(playback.submitted).toEqual([0, 100_000]);
expect(playback.decoder.out.timestamp.peek()).toBe(Time.Milli(0));
// Audio can reset the shared reference while this video's own container
// discontinuity remains unchanged.
playback.sync.reset();
await microtasks();
expect(playback.decoder.out.timestamp.peek()).toBe(Time.Milli(0));
// The next utterance anchors the clock past the parked frame's deadline.
playback.sync.received(Time.Milli(2000));
await microtasks();
expect(playback.decoder.out.timestamp.peek()).toBe(Time.Milli(0));
} finally {
playback.close();
await microtasks();
clear.mockRestore();
timer.mockRestore();
now.mockRestore();
}
});

it("closing the track releases a video wait parked across a reset", async () => {
const now = spyOn(Time.Milli, "now").mockReturnValue(Time.Milli(1000));
const timer = spyOn(globalThis, "setTimeout").mockImplementation(
(() => 1 as unknown as ReturnType<typeof setTimeout>) as unknown as typeof setTimeout,
);
const clear = spyOn(globalThis, "clearTimeout").mockImplementation(() => {});
const reads: Read[] = [];
const playback = await guardedPlayback("legacy", reads);
const waits: Promise<void>[] = [];
const original = playback.sync.wait.bind(playback.sync);
const wait = spyOn(playback.sync, "wait").mockImplementation((timestamp, signal) => {
const waiting = original(timestamp, signal);
waits.push(waiting);
return waiting;
});
try {
playback.enabled.set(false);
playback.delay.set(Time.Milli(1000));
await microtasks();
reads.push(sample(0, 0), sample(0, 100_000, 0, false));
playback.enabled.set(true);
await microtasks();
expect(playback.submitted).toEqual([0, 100_000]);
playback.sync.reset();
await microtasks();
expect(waits.map((waiting) => Bun.peek.status(waiting))).toContain("pending");
// No frame re-anchors the shared clock, but the closed track must not leave its wait behind.
playback.enabled.set(false);
await microtasks();
expect(waits.map((waiting) => Bun.peek.status(waiting))).not.toContain("pending");
} finally {
wait.mockRestore();
playback.close();
await microtasks();
clear.mockRestore();
timer.mockRestore();
now.mockRestore();
}
});

it("a reset drops a parked video frame even when the next anchor restores the reference", async () => {
const now = spyOn(Time.Milli, "now").mockReturnValue(Time.Milli(1000));
const timers: Array<() => void> = [];
const timer = spyOn(globalThis, "setTimeout").mockImplementation(((fn: () => void) => {
timers.push(fn);
return timers.length as unknown as ReturnType<typeof setTimeout>;
}) as unknown as typeof setTimeout);
const clear = spyOn(globalThis, "clearTimeout").mockImplementation(() => {});
const reads: Read[] = [];
const playback = await guardedPlayback("legacy", reads);
try {
playback.enabled.set(false);
playback.delay.set(Time.Milli(1000));
await microtasks();
reads.push(sample(0, 0), sample(0, 100_000, 0, false));
playback.enabled.set(true);
await microtasks();
expect(playback.submitted).toEqual([0, 100_000]);
// In one turn, so the reference never visibly changes and the parked sleep keeps its timer.
playback.sync.reset();
playback.sync.received(Time.Milli(0));
await microtasks();
for (const fn of timers.splice(0)) fn();
await microtasks();
expect(playback.decoder.out.timestamp.peek()).toBe(Time.Milli(0));
} finally {
playback.close();
await microtasks();
clear.mockRestore();
timer.mockRestore();
now.mockRestore();
}
});
23 changes: 12 additions & 11 deletions js/watch/src/video/decoder.ts
Original file line number Diff line number Diff line change
Expand Up @@ -410,9 +410,7 @@ class DecoderTrack {
// Decoded frames waiting to be rendered.
#buffered = new Signal<Container.BufferedRanges>([]);

// The last discontinuity count seen from the container consumer. An output callback
// captures it when the frame comes out, so a picture already parked in sync.wait
// can be dropped after the playhead moves.
// The last discontinuity count seen from the container consumer.
#discontinuity = 0;

// Codec description from the last configure, reused after a playhead reset.
Expand Down Expand Up @@ -447,9 +445,10 @@ class DecoderTrack {
const decoder = new VideoDecoder({
output: async (frame: VideoFrame) => {
try {
// The generation this frame was decoded in. If the playhead bumps while we wait
// below, this frame belongs to the previous generation and must be dropped.
const generation = this.#discontinuity;
// The clock epoch this frame was decoded in. A reset while we wait below (this
// track's playhead moving, or a shared reset such as audio's at an utterance
// boundary) means the frame belongs to the previous timeline and must be dropped.
const epoch = this.sync.epoch;

const timestamp = Time.Milli.fromMicro(frame.timestamp as Time.Micro);
if (timestamp < (this.timestamp.peek() ?? 0)) {
Expand All @@ -468,10 +467,12 @@ class DecoderTrack {
this.frame.set(frame.clone());
}

// Returns immediately when the latency is "instant".
const ok = await effect.race(this.sync.wait(timestamp).then(() => true));
if (!ok) return;
if (generation !== this.#discontinuity) return; // the playhead moved while waiting
// Returns immediately when the latency is "instant". Closing the track releases it.
// Capture the signal: a rerun replaces `effect.abort` before this continuation runs.
const signal = effect.abort;
await this.sync.wait(timestamp, signal);
if (signal.aborted) return;
if (epoch !== this.sync.epoch) return;

if (timestamp < (this.timestamp.peek() ?? 0)) {
// Late frame, don't render it.
Expand Down Expand Up @@ -684,7 +685,7 @@ class DecoderTrack {
// otherwise come out above the new keyframe and late-reject it. A delta continues a group the
// bump interrupted (a stale marker or a max-delay hole), so it keeps the decoder's references;
// a reset would make WebCodecs require a key chunk and throw. `reset()` cannot cancel an
// output callback that already holds a frame; the generation it captured rejects that one.
// output callback that already holds a frame; the clock epoch it captured rejects that one.
#resetAtKeyframe(decoder: VideoDecoder, keyframe: boolean): void {
if (!this.#resetPending) return;
this.#resetPending = false;
Expand Down
Loading
Loading