diff --git a/js/watch/src/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index 3591fc93a72..8e82ce475ef 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -361,6 +361,8 @@ async function play(initial: Delay, buffered = false, cmaf = false) { context: decoder.out.context, stalled: () => decoder.out.stalled.peek(), stats: () => decoder.out.stats.peek(), + timestamp: () => decoder.out.timestamp.peek(), + feedback: () => decoder.feedback(Moq.Path.from("watched")), arrivals: () => decoder.arrivals(), error: decoder.out.error, play, @@ -1000,6 +1002,93 @@ for (const cmaf of [false, true]) { }); } +describe("Decoder stalls", () => { + // Play a quantum, so the rendition is playing, then end it the given way and run the ring dry. + async function stopAfterPlaying(stop: (playback: Awaited>) => void) { + const playback = await play(Milli(100)); + try { + await playback.play(12); + const [ring] = playback.rings(); + expect(ring.read([new Float32Array(128), new Float32Array(128)])).toBe(128); + await microtasks(); + expect(playback.stalled()).toBe(false); + + stop(playback); + await microtasks(); + drain(ring); + await microtasks(); + return { stalls: playback.stats()?.stalls ?? 0, feedback: playback.feedback().audio?.stalls ?? 0 }; + } finally { + playback.close(); + } + } + + it("counts a playing rendition that runs dry", async () => { + expect(await stopAfterPlaying(() => {})).toEqual({ stalls: 1, feedback: 1 }); + }); + + it("counts nothing once the rendition leaves the catalog", async () => { + expect(await stopAfterPlaying((playback) => playback.remove())).toEqual({ stalls: 0, feedback: 0 }); + }); + + it("counts nothing once the rendition fails to decode", async () => { + const counts = await stopAfterPlaying(() => codecErrors.at(-1)?.(new DOMException("bad", "EncodingError"))); + expect(counts).toEqual({ stalls: 0, feedback: 0 }); + }); + + it("counts nothing after a switch to instant", async () => { + expect(await stopAfterPlaying((playback) => playback.delay.set("instant"))).toEqual({ stalls: 0, feedback: 0 }); + }); + + it("counts nothing while the decoder is disabled", async () => { + expect(await stopAfterPlaying((playback) => playback.decoding.set(false))).toEqual({ stalls: 0, feedback: 0 }); + }); + + it("treats the return from instant as a startup", async () => { + const playback = await play(Milli(100)); + try { + await playback.play(12); + const [ring] = playback.rings(); + ring.read([new Float32Array(128), new Float32Array(128)]); + await microtasks(); + playback.delay.set("instant"); + await microtasks(); + // The worklet keeps rendering the flushed ring, which reports it stalled. + ring.read([new Float32Array(128), new Float32Array(128)]); + await microtasks(); + expect(playback.stalled()).toBe(true); + // The ring waits for the returning rendition's first audio, which is no stall. + playback.delay.set(Milli(100)); + await microtasks(); + await playback.play(12); + ring.read([new Float32Array(128), new Float32Array(128)]); + await microtasks(); + expect(playback.stats()?.stalls ?? 0).toBe(0); + } finally { + playback.close(); + } + }); + + it("clears the playhead and stall state with the ring that reported them", async () => { + const playback = await play(Milli(100)); + try { + await playback.play(12); + const [ring] = playback.rings(); + ring.read([new Float32Array(128), new Float32Array(128)]); + await microtasks(); + expect(playback.timestamp()).toBeDefined(); + expect(playback.stalled()).toBe(false); + + playback.enabled.set(false); + await microtasks(); + expect(playback.timestamp()).toBeUndefined(); + expect(playback.stalled()).toBe(true); + } finally { + playback.close(); + } + }); +}); + describe("fatal decoder errors", () => { // A failure in the read loop, not a WebCodecs callback, must still reach `error` and release the // subscription, instead of leaving the player apparently live. diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 2fdc33a3b1f..748ca269d7c 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -116,6 +116,18 @@ const EMPTY: Stats = { bytesReceived: 0, underruns: 0, late: 0, errors: 0, stall // What a decode attempt reads, and where its counts go. type Attempt = { config: DecoderConfig; failure: Signal; path: Moq.Path.Valid; key: Key }; +// The newest container consumer, the path it reads, and its codec, whose estimate a replacement +// continues. +type Consumed = { path: Moq.Path.Valid; codec: string; consumer: Container.Consumer }; + +// What the decoder does with the selected rendition. Only a running rendition counts a stall. +type Phase = + | { kind: "stopped" } + // Decoding the rendition at `key` into the ring, which an underrun or a stall is counted against. + | { kind: "running"; key: Key; consumer?: Consumed } + // The source failed to decode, and stays failed until another source is selected. + | { kind: "failed"; failure: Failure }; + /** * Downloads audio from a track and emits it to an AudioContext. * @@ -164,10 +176,6 @@ export class Decoder { // The container consumer's arrival estimate, unset while nothing is subscribed. #measured = new Signal(undefined); - // The newest container consumer, the path it reads, and its codec, whose estimate a replacement - // continues. - #consumer?: { path: Moq.Path.Valid; codec: string; consumer: Container.Consumer }; - // The subscription's max delay: the shared budget, raised to the estimator's ceiling in "auto". #subscribeMaxDelay = new Signal(Milli.zero); // The container consumer's delay: the playout delay to start at and the shared budget. Its warmup @@ -187,14 +195,11 @@ export class Decoder { #arrivals = new ArrivalProducer(); #signals = new Effect(); - #failed?: Failure; + #phase = new Signal({ kind: "stopped" }); + readonly #running: Computed; // What each rendition delivered, for the feedback a viewer reports. #tally = new Tally(); - // The rendition decoding into the ring, which an underrun or a stall is counted against. - #playing?: Key; - // Whether audio played since the decoder was enabled, so the wait for the first is no stall. - #played = false; // The catalog fields that require a replacement subscription or decoder. readonly #identity: Computed; @@ -239,6 +244,7 @@ export class Decoder { const config = effect.get(this.source.out.config); return config ? playbackIdentity(config) : undefined; }); + this.#running = this.#signals.computed((effect) => effect.get(this.#phase).kind === "running"); this.#idle = this.#signals.computed((effect) => { if (effect.get(this.source.out.config) !== undefined) return false; const ring = effect.get(this.#ring); @@ -281,25 +287,26 @@ export class Decoder { })); } - // Count each stall once audio has played, and how long it lasted. A disabled decoder waits for - // audio again: resuming is a startup, not a stall. + // Count each stall once audio has played, and how long it lasted. Each run of the decoder waits + // for its first audio, which is a startup, not a stall; a rendition swap keeps the run going. #runStalls(effect: Effect): void { - if (!effect.get(this.in.enabled)) { - this.#played = false; - return; - } - if (!effect.get(this.#out.stalled)) { - this.#played = true; - return; - } - const key = this.#playing; - if (!this.#played || !key) return; - - const end = this.#tally.stall(key); - this.#count(undefined, {}, (stats) => ({ stalls: stats.stalls + 1 })); - effect.cleanup(() => { - const duration = end(); - this.#count(undefined, {}, (stats) => ({ stalled: Milli(stats.stalled + duration) })); + if (!effect.get(this.#running)) return; + + let played = false; + effect.run((inner) => { + if (!inner.get(this.#out.stalled)) { + played = true; + return; + } + const phase = this.#phase.peek(); + if (!played || phase.kind !== "running") return; + + const end = this.#tally.stall(phase.key); + this.#count(undefined, {}, (stats) => ({ stalls: stats.stalls + 1 })); + inner.cleanup(() => { + const duration = end(); + this.#count(undefined, {}, (stats) => ({ stalled: Milli(stats.stalled + duration) })); + }); }); } @@ -395,15 +402,17 @@ export class Decoder { if (end !== undefined) ring.end((end - this.#terminal.delay) as Micro); effect.set(this.#ring, ring); - // Mirror ring state (timestamp/stalled) onto our public signals. + // Mirror ring state (timestamp/stalled) onto our public signals, until the ring closes. effect.run((inner) => { const ts = Milli.fromMicro(inner.get(ring.timestamp)); this.#out.timestamp.set(ts); this.#trimDecodeBuffered(ts); }); + effect.cleanup(() => this.#out.timestamp.set(undefined)); effect.run((inner) => { this.#out.stalled.set(inner.get(ring.stalled) && !inner.get(ring.silent)); }); + effect.cleanup(() => this.#out.stalled.set(true)); // Each ring counts from zero, so add only what this one counted to the cumulative stats. let counted = 0; effect.run((inner) => { @@ -411,7 +420,9 @@ export class Decoder { const added = underruns - counted; counted = underruns; if (added <= 0) return; - this.#count(this.#playing, { underruns: added }, (stats) => ({ underruns: stats.underruns + added })); + const phase = this.#phase.peek(); + const key = phase.kind === "running" ? phase.key : undefined; + this.#count(key, { underruns: added }, (stats) => ({ underruns: stats.underruns + added })); }); effect.set(this.#out.root, worklet); @@ -465,55 +476,52 @@ export class Decoder { // Honor a per-rendition `broadcast` override: subscribe on the resolved source // broadcast instead of the catalog's own broadcast. A stopped decoder resolves it only to // tell whether a failure's source is still selected. + const phase = this.#phase.peek(); const active = - broadcast && track && identity && (running || this.#failed) + broadcast && track && identity && (running || phase.kind === "failed") ? broadcast.relativeBroadcast(effect, identity.broadcast, identity.instance) : undefined; const key = identity && JSON.stringify(identity); // A failure belongs to its source: selecting another clears it, even while muted or paused. - const failed = this.#failed; - const selected = broadcast && failed ? effect.get(broadcast.out.active)?.closed : undefined; - if (failed && failureMoved(failed, { broadcast: selected, media: active?.closed, track, identity: key })) { - this.#failed = undefined; - this.#out.error.set(undefined); + if (phase.kind === "failed") { + const selected = broadcast ? effect.get(broadcast.out.active)?.closed : undefined; + if (failureMoved(phase.failure, { broadcast: selected, media: active?.closed, track, identity: key })) { + this.#phase.set({ kind: "stopped" }); + this.#out.error.set(undefined); + } } - if (!running || !broadcast || !track || !identity) { + // A source that already failed waits for another. + if (!running || !broadcast || !track || !identity || !active || !key || this.#phase.peek().kind === "failed") { this.#retire(); return; } const config = identity.decoder; - if (!active || !key) { - this.#retire(); - return; - } - - // This source already failed; wait for another. - if (this.#failed) { - this.#retire(); - return; - } // Closing this effect releases both its container reader and track subscription. const failure = new Signal(undefined); const rendition: Key = { path: broadcast.in.name.peek(), id: track }; - this.#playing = rendition; + // A swap keeps the outgoing consumer, whose estimate the replacement may continue. + this.#phase.set({ + kind: "running", + key: rendition, + consumer: phase.kind === "running" ? phase.consumer : undefined, + }); let attempt: Effect | undefined; effect.run((inner) => { const error = inner.get(failure); if (!error) return; this.#count(rendition, { errors: 1 }, (stats) => ({ errors: stats.errors + 1 })); - this.#failed = { + this.#out.error.set(error); + attempt?.close(); + this.#retire({ broadcast: broadcast.out.active.peek()?.closed, media: active.closed, track, identity: key, - }; - this.#out.error.set(error); - attempt?.close(); - this.#retire(); + }); }); // Another broadcast (a new name, or a republish) brings its own timeline, which a ring and a @@ -795,7 +803,9 @@ export class Decoder { format: Container.Format, { config, path }: { config: DecoderConfig; path: Moq.Path.Valid }, ): { consumer: Container.Consumer; read: Signal } { - const outgoing = this.#consumer; + const phase = this.#phase.peek(); + if (phase.kind !== "running") throw new Error("audio: a consumer opened outside a running rendition"); + const outgoing = phase.consumer; const continues = outgoing?.path === path; const consumer = new Container.Consumer(sub, { format, @@ -804,7 +814,7 @@ export class Decoder { predecessor: continues ? outgoing.consumer : undefined, }); effect.cleanup(() => consumer.close()); - this.#consumer = { path, codec: config.codec, consumer }; + this.#phase.set({ ...phase, consumer: { path, codec: config.codec, consumer } }); // Opus states its duration only per packet, so the same codec continuing keeps the outgoing // one until the first packet refines it. Anything else starts from the codec's own constant. @@ -843,9 +853,11 @@ export class Decoder { return { consumer, read }; } - // No consumer replaces the outgoing one, so its estimate stops holding the buffer open. - #retire(): void { - this.#consumer = undefined; + // Leave the running phase, failed or stopped; a stop keeps an earlier failure. No consumer + // replaces the outgoing one, so its estimate stops holding the buffer open. + #retire(failure?: Failure): void { + if (failure) this.#phase.set({ kind: "failed", failure }); + else if (this.#phase.peek().kind === "running") this.#phase.set({ kind: "stopped" }); this.#measured.set(undefined); // Its arrivals stop holding the clock's reference. this.#track.reset(); diff --git a/js/watch/src/sync.test.ts b/js/watch/src/sync.test.ts index 18ceb9d7357..23731cb6ff8 100644 --- a/js/watch/src/sync.test.ts +++ b/js/watch/src/sync.test.ts @@ -411,6 +411,32 @@ describe("buffered startup", () => { installed.close(); } }); + // A video track's startup span opens at the first picture of its timeline, which a live stream + // played long ago. Turning lookahead on mid-stream must not anchor playback back there. + it("keeps playing when lookahead turns on mid-stream", async () => { + const clock = new Manual(); + const installed = clock.install(); + const lookahead = new Signal(Milli.zero); + const sync = new Sync({ delay: Milli(100), lookahead }); + const span = new Signal<{ start: Milli; end: Milli } | null>({ start: Milli(0), end: Milli(200) }); + const video = sync.track({ target: new Signal(Milli(100)), startup: span }); + try { + await clock.advance(Nano.zero); + video.received(Milli(0)); + await clock.advance(Nano.fromMilli(Milli(10_000))); + video.received(Milli(10_000)); + expect(sync.now()).toBe(Milli(9900)); + + lookahead.set(Milli(1000)); + await clock.advance(Nano.zero); + expect(sync.playing.peek()).toBe(true); + expect(sync.now()).toBe(Milli(9900)); + } finally { + video.close(); + sync.close(); + installed.close(); + } + }); it("removes a disabled track from the floor and leaves live pacing unchanged", async () => { const clock = new Manual(); const installed = clock.install(); diff --git a/js/watch/src/sync.ts b/js/watch/src/sync.ts index f88eb9623fa..9529a364f46 100644 --- a/js/watch/src/sync.ts +++ b/js/watch/src/sync.ts @@ -1,5 +1,5 @@ import { Milli, Nano, now, sleep } from "@moq/clock"; -import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; +import { Derived, Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; /** * How far playback trails the live edge. @@ -84,6 +84,14 @@ export type Part = { floor?: number; }; +/** + * Where the clock's current timeline stands. `idle` has not played and holds nothing back: it is + * unanchored, or anchored with no buffered startup. `starting` holds the media consumers until every + * startup span fills. `playing` has played, so turning on a lookahead does not start it over. + * @internal + */ +export type Phase = "idle" | "starting" | "playing"; + const wall = (): Milli => Nano.toMilli(Nano(now())); /** The state a {@link Sync} and its track handles share. @internal */ @@ -99,8 +107,9 @@ export class Clock { }; readonly parts = new Signal([]); - readonly playing = new Signal(true); - started = false; + readonly phase = new Signal("idle"); + // Whether the media consumers are released. + readonly playing = new Derived([this.phase], (phase) => phase !== "starting"); // 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. @@ -208,9 +217,8 @@ export class Clock { unanchor(): void { this.epoch.update((epoch) => epoch + 1); this.floor = undefined; - this.started = false; this.owner = undefined; - this.playing.set(!this.out.buffered.peek()); + this.phase.set(this.out.buffered.peek() ? "starting" : "idle"); this.out.reference.set(undefined); } @@ -290,7 +298,7 @@ export class Clock { this.out.reference.changed(wake), this.epoch.changed(wake), this.closed.changed(wake), - this.playing.changed(wake), + this.phase.changed(wake), part.epoch.changed(wake), ]; if (signal) { @@ -401,23 +409,22 @@ export class Sync { return span === undefined ? [] : [{ part, span }]; }); if (!buffered || spans.length === 0) { - clock.playing.set(true); + clock.phase.set(reference === undefined ? "idle" : "playing"); return; } - if (clock.started) return; + if (clock.phase.peek() === "playing") return; const ready = spans.flatMap(({ part, span }) => (span ? [{ part, span }] : [])); if ( reference === undefined || ready.length !== spans.length || ready.some(({ span }) => span.end - span.start < delay) ) { - clock.playing.set(false); + clock.phase.set("starting"); return; } // The track with the earliest opening holds the reference it anchors. const earliest = ready.reduce((a, b) => (b.span.start < a.span.start ? b : a)); const first = earliest.span.start; - clock.started = true; clock.owner = earliest.part; // Anchor at the retained opening, not at its arrival: startup may have waited on another track. // Every track's own anchor moves by the same offset, keeping the gaps between tracks that @@ -427,7 +434,7 @@ export class Sync { if (part.anchor !== undefined) part.anchor += anchored - reference; } clock.out.reference.set(anchored); - clock.playing.set(true); + clock.phase.set("playing"); } #runInstant(effect: Effect): void { diff --git a/js/watch/src/video/decoder.test.ts b/js/watch/src/video/decoder.test.ts index bbdc36e5084..13747c0f444 100644 --- a/js/watch/src/video/decoder.test.ts +++ b/js/watch/src/video/decoder.test.ts @@ -870,6 +870,23 @@ for (const kind of ["legacy", "cmaf"] as const) { } }); + it(`clears an outgoing ${kind} failure once the source changes before the replacement plays`, async () => { + const playback = await guardedPlayback(kind, [sample(1n, 100_000)]); + try { + playback.switchRendition(); + await microtasks(); + const failure = new DOMException("outgoing decoder failed", "EncodingError"); + playback.fail(failure, 0); + await microtasks(); + expect(playback.decoder.out.error.peek()).toBe(failure); + playback.catalog.set({}); + await microtasks(); + expect(playback.decoder.out.error.peek()).toBeUndefined(); + } finally { + playback.close(); + } + }); + it(`keeps a failed pending ${kind} rendition out of the active slot`, async () => { const playback = await guardedPlayback(kind, [sample(1n, 100_000)]); try { @@ -1166,6 +1183,62 @@ it("a video track read from another path does not inherit the outgoing delay", a }); // The first picture is useful before the startup floor, but elapsed wall time is not buffered media. +describe("Decoder stalls", () => { + // A second of delay, past the buffering timeout, so the poster waits longer than a stall takes. + async function cold() { + const clock = manualAt(1000); + const feeds = new Feeds(); + const playback = await guardedPlayback("legacy", [], [], false, 0, { initial: Milli(1000), feeds }); + const stalls = () => playback.decoder.out.stats.peek()?.stalls ?? 0; + const feedback = () => playback.decoder.feedback(Moq.Path.from("watched")).video?.stalls ?? 0; + const close = async () => { + playback.close(); + await microtasks(); + clock.installed.close(); + }; + return { clock, feeds, playback, stalls, feedback, close }; + } + + it("counts only a picture that played and then froze, not the poster's wait", async () => { + const { clock, feeds, playback, stalls, feedback, close } = await cold(); + try { + // Frames arrive in real time, each presenting a second after it arrives. + feeds.push(0, sample(0n, 0)); + await microtasks(); + expect(playback.decoder.out.frame.peek()?.timestamp).toBe(0); + for (let ms = 100; ms <= 2000; ms += 100) { + await clock.advance(100); + feeds.push(0, sample(0n, ms * 1000, false)); + await microtasks(); + // The poster waits a second for its turn, which is a startup. + if (ms === 900) expect(playback.decoder.out.stalled.peek()).toBe(true); + } + expect(playback.decoder.out.frame.peek()?.timestamp).toBe(1_000_000); + expect(stalls()).toBe(0); + + // The frames stop, and the last picture freezes past the buffering timeout. + for (let i = 0; i < 16; i++) await clock.advance(100); + expect(playback.decoder.out.stalled.peek()).toBe(true); + expect(stalls()).toBe(1); + expect(feedback()).toBe(1); + } finally { + await close(); + } + }); + + it("clears the buffering state while disabled", async () => { + const { playback, close } = await cold(); + try { + expect(playback.decoder.out.stalled.peek()).toBe(true); + playback.enabled.set(false); + await microtasks(); + expect(playback.decoder.out.stalled.peek()).toBe(false); + } finally { + await close(); + } + }); +}); + it("buffered video holds its poster until its own span reaches the floor", async () => { const clock = manualAt(0); const playback = await guardedPlayback("legacy", [], [], true, 1000); diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 3dbc465e68b..39be38bbbd2 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -36,6 +36,14 @@ function startupSpan(ranges: Container.BufferedRanges, first: Milli): { start: M return { start: first, end: Milli(first + duration) }; } +// The rendition #runPending chose, or the failure that stopped its source until another is selected. +// A selected rendition is pending until it replaces the active one, and stays selected on screen. +type Selection = { kind: "none" } | { kind: "selected"; rendition: Rendition } | { kind: "failed"; failure: Failure }; + +// One run of the active rendition's playback. A poster may show while it starts, and only a picture +// that played and then froze is a stall. +type Playback = "starting" | "playing" | "stalled"; + /** Signals the decoder reads. */ export type DecoderInput = { /** Whether to download the video track. Defaults to true; the parent may wire it from the renderer's output. */ @@ -128,12 +136,9 @@ export class Decoder { /** The derived outputs, read-only. */ readonly out = readonlys(this.#out); - // The current track running, held so we can cancel it when the new track is ready. + // The rendition on screen, held so we can cancel it when the selected one is ready. #active = new Signal(undefined); - // The rendition preparing to replace the active one, with the catalog of the broadcast it - // subscribed to. One value so a later source that reuses the track name still notifies: - // the name alone would compare equal, and the jitter effect would keep the previous catalog. - #pending = new Signal<{ track: string; catalog: Getter } | undefined>(undefined); + #selection = new Signal({ kind: "none" }); // The active track's arrival estimate from its container consumer. #spread = new Signal(undefined); // The path of the media the last rendition read, and its instance. Every handle to one instance @@ -142,13 +147,9 @@ export class Decoder { readonly #identity: Computed; #signals = new Effect(); - #selected?: Rendition; - #failed?: Failure; // What each rendition delivered, for the feedback a viewer reports. #tally = new Tally(); - // Whether a picture played since the decoder was enabled, so the wait for the first one is no stall. - #played = false; #clearCurrentFrame(): void { this.#out.frame.update((prev) => { @@ -224,36 +225,50 @@ export class Decoder { }; const activeTrack = effect.get(this.#active); const active = floor(activeTrack?.track, activeTrack?.catalog); - const pendingTrack = effect.get(this.#pending); + const pendingTrack = this.#pending(effect.get(this.#selection), activeTrack); const pending = floor(pendingTrack?.track, pendingTrack?.catalog); effect.set(this.#out.jitter, switchJitter({ active, pending })); } + // The selected rendition still preparing to replace `active`. + #pending(selection: Selection, active: Rendition | undefined): Rendition | undefined { + return selection.kind === "selected" && selection.rendition !== active ? selection.rendition : undefined; + } + #runPending(effect: Effect): void { - this.#selected = undefined; const enabled = effect.get(this.in.enabled); const broadcast = effect.get(this.source.in.broadcast); const track = effect.get(this.source.out.track); const identity = effect.get(this.#identity); + const selection = this.#selection.peek(); // Honor a per-rendition `broadcast` override: subscribe on the resolved source // broadcast instead of the catalog's own broadcast. A disabled decoder resolves it only to // tell whether a failure's source is still selected. const active: Moq.Broadcast.Consumer | undefined = - broadcast && track && identity && (enabled || this.#failed) + broadcast && track && identity && (enabled || selection.kind === "failed") ? broadcast.relativeBroadcast(effect, identity.broadcast, identity.instance) : undefined; const key = identity && JSON.stringify(identity); - // A failure belongs to its source: selecting another clears it, even while disabled. - const failed = this.#failed; - const selected = broadcast && failed ? effect.get(broadcast.out.active)?.closed : undefined; - if (failed && failureMoved(failed, { broadcast: selected, media: active?.closed, track, identity: key })) { - this.#failed = undefined; + // A failure belongs to its source: selecting another clears it, even while disabled. Without a + // latched failure, any error shown is an outgoing rendition's, which a selection change clears. + if (selection.kind !== "failed") { this.#out.error.set(undefined); + } else { + const selected = broadcast ? effect.get(broadcast.out.active)?.closed : undefined; + if (failureMoved(selection.failure, { broadcast: selected, media: active?.closed, track, identity: key })) { + this.#selection.set({ kind: "none" }); + this.#out.error.set(undefined); + } } + // Nothing is selected without a source, but a failure stays latched. + const deselect = () => { + if (this.#selection.peek().kind === "selected") this.#selection.set({ kind: "none" }); + }; if (!enabled || !broadcast || !track || !identity) { + deselect(); // Close the active track when disabled (e.g. paused or not visible). // The pending cleanup won't do this because it was already promoted to #active. this.#active.set(undefined); @@ -269,6 +284,7 @@ export class Decoder { } if (!active || !key) { + deselect(); // Going offline should clear the last rendered frame. this.#active.set(undefined); this.#clock.reset(); @@ -278,7 +294,7 @@ export class Decoder { } // This source already failed; wait for another. - if (this.#failed) return; + if (this.#selection.peek().kind === "failed") return; // A republish of the media this rendition reads (the catalog's own broadcast, or the one a // `broadcast` override names) is another instance, whose timeline starts over. Waiting for @@ -294,8 +310,7 @@ export class Decoder { const outgoing = this.#active.peek(); const predecessor = outgoing?.broadcast.path === active.path ? outgoing : undefined; - // Start a new pending effect. - let pending: Rendition | undefined = new Rendition({ + const rendition = new Rendition({ sync: this.sync, clock: this.#clock, broadcast: active, @@ -309,27 +324,30 @@ export class Decoder { catalog: broadcast.out.catalog, predecessor, }); - this.#selected = pending; + this.#selection.set({ kind: "selected", rendition }); + // Whether the rendition is still waiting to replace the active one: neither promoted nor failed. + const pending = () => this.#pending(this.#selection.peek(), this.#active.peek()) === rendition; + effect.run((inner) => { - if (!pending) { + if (!pending()) { inner.close(); // Promoted tracks are observed by their active lifetime. return; } - const error = inner.get(pending.error); + const error = inner.get(rendition.error); if (!error) return; - this.#recordError(pending, error); - pending.close(); - pending = undefined; - this.#pending.set(undefined); + this.#recordError(rendition, error); + rendition.close(); // With no active rendition left, nothing holds video's timeline. if (!this.#active.peek()) this.#clock.reset(); }); - effect.set(this.#pending, { track, catalog: broadcast.out.catalog }); - effect.cleanup(() => pending?.close()); + // Once promoted, #runActive closes it. + effect.cleanup(() => { + if (this.#active.peek() !== rendition) rendition.close(); + }); effect.run((effect) => { - if (!pending) { + if (!pending()) { effect.close(); return; } @@ -337,18 +355,15 @@ export class Decoder { const current = effect.get(this.#active); if (current && !republished) { // A zero timestamp is a rendered frame, not a missing one. - const pendingTimestamp = effect.get(pending.timestamp); + const pendingTimestamp = effect.get(rendition.timestamp); if (pendingTimestamp === undefined) return; // Hold off until the new rendition has caught up to the picture it's replacing. if (!caughtUp({ playhead: pendingTimestamp, active: effect.get(current.timestamp) })) return; } - // Upgrade the pending track to active. - // #runActive will be in charge of it now. - this.#active.set(pending); - this.#pending.set(undefined); - pending = undefined; + // Promote the rendition; #runActive will be in charge of it now. + this.#active.set(rendition); // This effect is done; close it to avoid a useless re-run. effect.close(); @@ -372,7 +387,7 @@ export class Decoder { this.#recordError(active, error); this.#active.set(undefined); // A pending replacement carries video's timeline on; its parked frames must stay. - if (!this.#pending.peek()) this.#clock.reset(); + if (!this.#pending(this.#selection.peek(), undefined)) this.#clock.reset(); this.#clearCurrentFrame(); }); @@ -382,11 +397,9 @@ export class Decoder { const frame = inner.get(active.frame); if (!frame) return; // A promoted track holds the previous picture until its first frame. if (active.error.peek()) return; - this.#played = true; - if (this.#selected === active) { - this.#failed = undefined; - this.#out.error.set(undefined); - } + // The selected rendition playing clears an outgoing one's failure. + const selection = this.#selection.peek(); + if (selection.kind === "selected" && selection.rendition === active) this.#out.error.set(undefined); this.#out.timestamp.set(Milli.fromMicro(frame.timestamp as Micro)); this.#out.interlaced.set(active.config.interlaced); this.#out.frame.update((prev) => { @@ -398,17 +411,22 @@ export class Decoder { effect.proxy(this.#spread, active.spread); } + // Only the selected rendition's failure stops its source. An outgoing one's shows until the + // selected rendition plays, and never replaces the selected one's. #recordError(track: Rendition, error: Error): void { this.#tally.count(track.key, { errors: 1 }); this.#out.stats.update((stats) => ({ ...(stats ?? EMPTY), errors: (stats?.errors ?? 0) + 1 })); - // An outgoing failure must not replace the selected rendition's failure latch. - if (track !== this.#selected && this.#selected?.error.peek()) return; - this.#failed = { - broadcast: this.source.in.broadcast.peek()?.out.active.peek()?.closed, - media: track.broadcast.closed, - track: track.track, - identity: track.identity, - }; + const selection = this.#selection.peek(); + if (selection.kind === "failed") return; + if (selection.kind === "selected" && selection.rendition === track) { + const failure: Failure = { + broadcast: this.source.in.broadcast.peek()?.out.active.peek()?.closed, + media: track.broadcast.closed, + track: track.track, + identity: track.identity, + }; + this.#selection.set({ kind: "failed", failure }); + } this.#out.error.set(error); } @@ -432,8 +450,11 @@ export class Decoder { } #runBuffering(effect: Effect): void { - const enabled = effect.get(this.in.enabled); - if (!enabled) return; + // A disabled decoder is not waiting for anything. + if (!effect.get(this.in.enabled)) { + this.#out.stalled.set(false); + return; + } const frame = effect.get(this.#out.frame); if (!frame) { @@ -448,25 +469,34 @@ export class Decoder { }, Nano.fromMilli(BUFFERING)); } - // Count each stall once a picture has played, and how long it lasted, against the rendition on - // screen. A disabled decoder waits for a new picture again: resuming is a startup, not a stall. + // Count each stall, and how long it lasted, against the rendition on screen. Each active rendition + // starts a run, and disabling the decoder clears it: the wait for its first picture on the clock + // is a startup even while a poster shows, and so is a restarted timeline's. #runStalls(effect: Effect): void { - if (!effect.get(this.in.enabled)) { - this.#played = false; - return; - } - if (!effect.get(this.#out.stalled) || !this.#played) return; - const active = this.#active.peek(); + const active = effect.get(this.#active); if (!active) return; - const end = this.#tally.stall(active.key); - this.#out.stats.update((stats) => ({ ...(stats ?? EMPTY), stalls: (stats?.stalls ?? 0) + 1 })); - effect.cleanup(() => { - const duration = end(); - this.#out.stats.update((stats) => ({ - ...(stats ?? EMPTY), - stalled: Milli((stats?.stalled ?? 0) + duration), - })); + const playback = new Signal("starting"); + effect.run((inner) => { + // Undefined while the picture is only a poster, as it is again once the timeline restarts. + if (inner.get(active.timestamp) === undefined) { + playback.set("starting"); + return; + } + playback.set("playing"); + inner.timer(() => playback.set("stalled"), Nano.fromMilli(BUFFERING)); + }); + effect.run((inner) => { + if (inner.get(playback) !== "stalled") return; + const end = this.#tally.stall(active.key); + this.#out.stats.update((stats) => ({ ...(stats ?? EMPTY), stalls: (stats?.stalls ?? 0) + 1 })); + inner.cleanup(() => { + const duration = end(); + this.#out.stats.update((stats) => ({ + ...(stats ?? EMPTY), + stalled: Milli((stats?.stalled ?? 0) + duration), + })); + }); }); } diff --git a/quest/m1/explicit-state/README.md b/quest/m1/explicit-state/README.md index 2850e41ae87..fd4d2d6bab2 100644 --- a/quest/m1/explicit-state/README.md +++ b/quest/m1/explicit-state/README.md @@ -72,7 +72,6 @@ which collapses that state and waits on [Drop set](/quest/m1/drop-set.md). - [moq-boy pause state](/quest/m1/explicit-state/boy-pause.md) - a new viewer always wakes a paused emulator - [Transport close](/quest/m1/explicit-state/transport-close.md) - connection status ends with its error, and every Rust QUIC backend agrees when a connection is closed - [Video codec drains](/quest/m1/explicit-state/video-drain.md) - a hardware codec whose drain fails is ready for input again or terminally failed, never left stuck -- [Watch playback phases](/quest/m1/explicit-state/watch-playback.md) - watch counts a stall only while a rendition plays - [Publish capture phases](/quest/m1/explicit-state/publish-capture.md) - dismissing the screen-share picker turns sharing off - [js/qmux close](/quest/m1/explicit-state/qmux-close.md) - a graceful remote close ends qmux streams cleanly - [FFI handle state](/quest/m1/explicit-state/ffi-state.md) - FFI handles hold one state each: video follow under one lock, requests answered once, drivers Cancelled after shutdown diff --git a/quest/m1/explicit-state/watch-playback.md b/quest/m1/explicit-state/watch-playback.md deleted file mode 100644 index 222e3eaa205..00000000000 --- a/quest/m1/explicit-state/watch-playback.md +++ /dev/null @@ -1,59 +0,0 @@ -# [M] Watch playback phases - -## Goal - -`` counts audio and video stalls, stalled time, and the echo -feedback that grades a viewer as stalled only for a rendition that was -playing and then ran dry. None of these count: - -- a retired, failed, or removed audio rendition; -- a switch to `delay="instant"`; -- a video poster waiting for the clock; -- a disabled decoder. - -Each decoder's playback and rendition-switching phase is one value. - -## Plan - -The shared decisions are in the [epic](/quest/m1/explicit-state/README.md). - -Bugs to reproduce and fix: - -- **Audio** (`js/watch/src/audio/decoder.ts`): - - `#retire()` clears the consumer but keeps `#playing` (the rendition key) - and `#played`. - - `#runStalls` counts whenever the ring reports stalled and - `#played && #playing`. So switching to instant mode, a decode failure, or - the rendition leaving the catalog each count a stall that keeps growing - for as long as the state lasts. - - `#out.timestamp` and `#out.stalled` also outlive the ring that fed them. - - Recommended: `{ kind: "stopped" } | { kind: "running", key, consumer } | - { kind: "failed", failure }`, counting only in `running`. -- **Video** (`js/watch/src/video/decoder.ts`): - - The min-delay `DecoderTrack` posts a poster frame before the clock - reaches it, and `#runActive` sets `#played` for any frame, poster - included. - - With a delay over the 500 ms buffering timer, every cold start or resume - counts as a stall, which contradicts the comment that the wait for the - first picture is no stall. - - `#runBuffering` also returns early when the decoder is disabled and - leaves `stalled` set, so the buffering spinner can stay on with - `visible="never"`. - - Recommended: separate poster and playing phases, counting only the move - from playing to stalled. - -Also sweep the video decoder's rendition switching (`#active`, `#pending`, a -closure-local `pending`, `#selected`, `#failed`), which keeps two copies of -"pending". - -Check whether turning on `lookahead` mid-stream re-enters cold startup -anchored at the stream's first picture (`js/watch/src/sync.ts`, `started` is -only kept in buffered mode). If it does, fix it with the sync clock's phase. - -[moq-dev/moq#8058](https://github.com/moq-dev/moq/pull/8058) (audio -time-stretch) rewrites much of the audio decoder. This child doesn't wait on -it, so expect a merge conflict. - -## Related - -- [Zero steady-state audio underruns](/quest/m1/audio-jitter-target/watch.md) - edits the same audio decoder and reads its stall counter