From 08ee958f533874660b6fa84267c46250d2311622 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 01:23:43 -0800 Subject: [PATCH 1/6] chore(quest): claim quest/m1/audio-jitter-target/delay-cap.md Quest-Claim: 12a51e1aea168373 From d323ffb18adf341aeae800718f53f10ffb936767 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 01:33:14 -0800 Subject: [PATCH 2/6] fix(watch): an auto delay stops at 10 s The browser held whatever the catalog advertised as jitter and delay, so an hour of either delayed playback and buffered media by an hour. Cap the resolved "auto" delay at DELAY_MAX, the moq play ceiling, once in Sync so audio and video stay on one clock. A fixed delay is still taken literally. Co-Authored-By: Claude Haiku 5.5 --- doc/lib/js/watch.md | 2 +- js/watch/src/sync.test.ts | 22 +++++++++ js/watch/src/sync.ts | 16 +++++-- quest/m1/audio-jitter-target/delay-cap.md | 57 +++++++++++++++++------ 4 files changed, 78 insertions(+), 19 deletions(-) diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index 1993c1067a8..7ed0fd69b1f 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -32,7 +32,7 @@ in sync at the latency you ask for. | `url`, `name` | Relay URL (with `?jwt=` if needed) and broadcast name. | | `versions` | Protocol versions to offer, most preferred first, comma-separated like `moq-transport-18,moq-lite-06`. Every stable version by default. | | `paused`, `muted`, `volume` | The usual player controls. | -| `delay` | How far playback trails the live edge: `"auto"` (the default, sized from how late frames arrive; see [audio jitter](/concept/audio-jitter)), a duration like `"300ms"`, or `"instant"` to paint video as it decodes, with no audio. | +| `delay` | How far playback trails the live edge: `"auto"` (the default, sized from how late frames arrive, at most 10 s; see [audio jitter](/concept/audio-jitter)), a duration like `"300ms"`, or `"instant"` to paint video as it decodes, with no audio. | | `lookahead` | How far ahead of the live edge media may run; see [buffered playback](#buffered-playback). | | `stretch` | How far audio may trail the clock before it skips ahead: a duration like `"2s"` (the default), or `"0"` to turn the time stretch off; see [catching up](#catching-up). | | `captions` | The caption track to show. | diff --git a/js/watch/src/sync.test.ts b/js/watch/src/sync.test.ts index dcfa6f8ac87..4a6056993cc 100644 --- a/js/watch/src/sync.test.ts +++ b/js/watch/src/sync.test.ts @@ -5,6 +5,7 @@ import { Duration, type Installed, Instant, Manual, now, yieldNow } from "@moq/c const at = (ms: number) => Instant.ZERO.saturatingAdd(Duration.millis(ms)); import { Signal } from "@moq/signals"; +import { target } from "./audio/latency"; import { type Delay, Sync } from "./sync"; // Effects in @moq/signals flush on a microtask, so let pending updates drain before asserting. @@ -117,6 +118,27 @@ describe("auto delay", () => { sync.close(); }); + it("caps an auto delay that a catalog advertises past the ceiling", async () => { + // An hour of advertised jitter and catalog delay, through the audio target the decoder builds. + const hour = Duration.secs(3600); + const audio = new Signal( + target({ measured: Duration.millis(0), advertised: hour, frame: Duration.millis(20), delay: hour }), + ); + const sync = new Sync(); + sync.track({ target: audio }); + await flush(); + expect(sync.out.delay.peek()).toEqual(Duration.secs(10)); + expect(sync.out.maxDelay.peek()).toEqual(Duration.secs(10)); + sync.close(); + }); + + it("takes a fixed delay past the ceiling literally, since the viewer chose it", async () => { + const sync = new Sync({ delay: Duration.secs(20) }); + await flush(); + expect(sync.out.delay.peek()).toEqual(Duration.secs(20)); + sync.close(); + }); + it("takes a fixed delay literally, ignoring the measured targets", async () => { const media = new Signal(Duration.millis(250)); const sync = new Sync({ delay: Duration.millis(100) }); diff --git a/js/watch/src/sync.ts b/js/watch/src/sync.ts index 87f6e378795..c91e6a4b84f 100644 --- a/js/watch/src/sync.ts +++ b/js/watch/src/sync.ts @@ -5,8 +5,8 @@ import { Derived, Effect, type Getter, getter, type Inputs, type Readonlys, read * How far playback trails the live edge. * * `"auto"` (the default) holds the largest playout target the registered decoders measure from how - * late their frames arrive (see doc/concept/audio-jitter.md). A `Duration` fixes the delay at - * exactly that value and disables adaptation. + * late their frames arrive (see doc/concept/audio-jitter.md), at most 10 s. A `Duration` fixes the + * delay at exactly that value and disables adaptation. * * `"instant"` drops the buffer and the pacing together: nothing is held, and the wait before * presenting a frame never sleeps, so it presents as soon as it exists. It also overrides @@ -18,6 +18,13 @@ export type Delay = "instant" | "auto" | Duration; /** The default {@link SyncInput.stretch}: how far live audio may trail the clock before it skips. @internal */ export const STRETCH = Duration.secs(2); +/** + * The most an `"auto"` delay holds. The publisher advertises the jitter and delay it is measured + * from, so the clock bounds them here, whatever the catalog says. Matches + * `moq_audio::playback::Input::LATENCY_MAX`, which bounds `moq play`'s `--delay`. @internal + */ +export const DELAY_MAX = Duration.secs(10); + /** Signals the sync reads. */ export type SyncInput = { /** How far playback trails the live edge. See {@link Delay}. */ @@ -66,7 +73,7 @@ export type SyncOutput = { reference: Signal; // The resolved delay from the live edge to the playhead: the configured number, or in "auto" the - // largest registered playout target. Zero for "instant". + // largest registered playout target, at most DELAY_MAX. Zero for "instant". delay: Signal; // The media timestamp of the most recently received frame. @@ -488,6 +495,9 @@ export class Sync { for (const { props } of effect.get(this.#clock.parts)) { delay = delay.max(effect.get(props.target) ?? Duration.ZERO); } + // Capped once, on the resolved delay, so audio and video stay on one clock. The + // subscription's max delay follows it. + delay = delay.min(DELAY_MAX); } this.#clock.out.delay.set(delay); diff --git a/quest/m1/audio-jitter-target/delay-cap.md b/quest/m1/audio-jitter-target/delay-cap.md index f54b0247238..302eb2c1b9c 100644 --- a/quest/m1/audio-jitter-target/delay-cap.md +++ b/quest/m1/audio-jitter-target/delay-cap.md @@ -4,9 +4,9 @@ A publisher that advertises a huge `jitter` or catalog `delay` cannot hold a `` viewer's playback, or the media it buffers, past a fixed -ceiling. The browser caps the `"auto"` delay at the same 10 s `moq play` -uses, so a misbehaving publisher costs its viewers bounded latency and -memory, as AGENTS.md requires. +ceiling. The browser caps the resolved `"auto"` delay at 10 s, so a +misbehaving publisher costs its viewers bounded latency and memory, as +AGENTS.md requires. ## Plan @@ -16,8 +16,8 @@ in m1 (rejected: m3 or later; not tracking it). #8532 capped `moq play`'s clock at `moq_audio::playback::Input::LATENCY_MAX` (10 s), which also bounds the catalog `delay` and `--delay` there. The -browser has no cap. In `"auto"`, `js/watch` `Sync#runDelay` holds the deepest -part's target, so an hour of advertised delay delays playback by an hour: +browser had no cap. In `"auto"`, `js/watch` `Sync#runDelay` holds the deepest +part's target, so an hour of advertised delay delayed playback by an hour: - Audio's target is `max(measured, jitter) + frame + delay` (`js/watch/src/audio/latency.ts` `target`). - Video's target is `spread + delay`, floored by the rendition's `jitter` @@ -26,15 +26,42 @@ part's target, so an hour of advertised delay delays playback by an hour: The subscription's max delay (`delay + lookahead`) follows the same delay, so the container consumer keeps that much encoded media. -Recommendations: +Recommendations, as implemented: -- Cap the resolved `"auto"` delay in `Sync#runDelay` at one exported - constant equal to `LATENCY_MAX`, rather than capping each term, so audio - and video stay on one clock. -- Leave a fixed delay alone: the viewer chose it, not the publisher. -- Test that a catalog advertising an hour of `jitter` and `delay` resolves - to the cap. -- Check that `moq_mux::sync` and `moq play` cap the same `"auto"` delay, and - say where the two constants are pinned together. +- The resolved `"auto"` delay is capped once in `Sync#runDelay` at an internal + constant equal to `LATENCY_MAX`, rather than capping each term, so audio and + video stay on one clock. +- A fixed delay is left alone: the viewer chose it, not the publisher. +- A catalog advertising an hour of `jitter` and `delay` resolves to the cap. -Public API: possibly one exported constant in `@moq/watch`. Wire: none. +Findings: + +- The premise that `moq play` caps at the same 10 s does not hold. It caps + each term on its own, the held jitter target and the catalog delay, each at + `LATENCY_MAX`, so its audio target can reach 20 s + (`rs/moq-cli/src/play/media.rs`). `moq_mux::sync` caps nothing itself: its + delay is the largest target its callers set. +- The constants are pinned together in one place only: the `play` feature's + test in `rs/moq-cli/src/play/args.rs` pins `DELAY_MAX` to + `moq_audio::playback::Input::LATENCY_MAX`. The browser constant is pinned to + it by its comment alone, since no test builds both. +- Catalog `warmup` is added to the subscription's max delay in the browser + with no cap (`js/watch/src/audio/decoder.ts`, `js/watch/src/video/decoder.ts`). + It is not one of the `jitter` or `delay` fields the Goal names. + +Public API: none. The constant stays internal to `@moq/watch`. Wire: none. + +## Waiting + +- Maintainer: pick the ceiling for `moq play`'s audio target, which reaches 20 s + while the browser stops at 10 s. Options: (a) cap `moq play`'s target sum at + `LATENCY_MAX` too, recommended, so one ceiling holds everywhere; (b) raise + the browser to 20 s to match `moq play`'s worst case; (c) keep the mismatch. + Check: the answer is recorded here, and a follow-up quest exists for `moq play`. +- Maintainer: pick how a catalog `warmup` above 10 s is bounded. Options: (a) + clamp it at `LATENCY_MAX` where the browser reads it, and in `rs/hang`'s + playout for parity, recommended, since only the publisher's own picture + suffers; (b) reject a rendition whose `warmup` exceeds it, which fails loud + but drops that rendition; (c) leave it unbounded, which misses this quest's + Goal for `warmup`. Check: the answer is recorded here, and a follow-up quest + exists for it. From d1e07c964f4eab6c408141793f650d595d0c6fa7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 02:13:01 -0800 Subject: [PATCH 3/6] fix(watch,moq-cli,moq-mux): one 10 s ceiling for moq play's target and a catalog warmup Co-Authored-By: Claude Opus 5.5 --- js/watch/src/audio/decoder.test.ts | 37 +++++++++++++++++- js/watch/src/audio/decoder.ts | 6 +-- js/watch/src/video/decoder.test.ts | 9 +++-- js/watch/src/video/decoder.ts | 5 ++- quest/m1/audio-jitter-target/delay-cap.md | 47 +++++++++-------------- rs/moq-cli/src/play/media.rs | 18 ++++++++- rs/moq-mux/src/container/consumer.rs | 32 +++++++++++++-- 7 files changed, 111 insertions(+), 43 deletions(-) diff --git a/js/watch/src/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index 04ce8de8471..d1bcb753f71 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -7,7 +7,7 @@ import * as Moq from "@moq/net"; import { Effect, Signal } from "@moq/signals"; import type { Broadcast } from "../broadcast"; import { supportCacheKey } from "../support-probe"; -import { type Delay, STRETCH, Sync } from "../sync"; +import { DELAY_MAX, type Delay, STRETCH, Sync } from "../sync"; import { Decoder as VideoDecoder } from "../video/decoder"; import { Source as VideoSource } from "../video/source"; import { decoderConfigKey } from "./config"; @@ -634,6 +634,41 @@ describe("Decoder across a broadcast disable", () => { }); describe("Decoder across a delay change", () => { + it("reaches back for a catalog warmup no further than the delay cap", async () => { + // The max delay each subscribe and update asked the publisher for, in order. + const asked: (Duration | null | undefined)[] = []; + const subscribe = Moq.Track.Consumer.prototype.subscribe; + const update = Moq.Track.Subscriber.prototype.update; + const subscribes = spyOn(Moq.Track.Consumer.prototype, "subscribe").mockImplementation(function ( + this: Moq.Track.Consumer, + ...args: Parameters + ) { + asked.push(args[0]?.delay?.max); + return subscribe.apply(this, args); + }); + const updates = spyOn(Moq.Track.Subscriber.prototype, "update").mockImplementation(function ( + this: Moq.Track.Subscriber, + ...args: Parameters + ) { + asked.push(args[0]?.delay?.max); + return update.apply(this, args); + }); + const playback = await play(Duration.millis(100)); + try { + await playback.play(); + const base = asked.at(-1); + if (!base) throw new Error("no subscription"); + playback.restore({ warmup: 3_600_000 }); + await microtasks(); + await playback.play(); + expect(asked.at(-1)).toEqual(base.add(DELAY_MAX)); + } finally { + subscribes.mockRestore(); + updates.mockRestore(); + playback.close(); + } + }); + for (const initial of [Duration.millis(100), "auto"] as const) { it(`keeps the subscription and ring when ${initial} becomes a number`, async () => { const playback = await play(initial); diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index ce58b23bcbd..4c7e0d355b1 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -18,7 +18,7 @@ import { hosted } from "../assets"; import { base64ToBytes } from "../base64"; import { arrivedAt, type Counter, type Key, type Received, Tally } from "../feedback"; import { type Failure, failureMoved, nextMedia, subscribeMedia } from "../media"; -import type { Sync, Track } from "../sync"; +import { DELAY_MAX, type Sync, type Track } from "../sync"; import { AudioBuffer } from "./buffer"; import { type DecoderConfig, frameDuration, type PlaybackIdentity, packetDuration, playbackIdentity } from "./config"; import { Handover } from "./handover"; @@ -333,7 +333,7 @@ export class Decoder { const budget = this.#budget(effect); const delay = budget.delay; const max = maxDelay(budget); - const warmup = Duration.millis(effect.get(this.source.out.config)?.warmup ?? 0); + const warmup = Duration.millis(effect.get(this.source.out.config)?.warmup ?? 0).min(DELAY_MAX); this.#delay.set({ min: delay, max }); this.#subscribeMaxDelay.set(max.add(warmup)); } @@ -858,7 +858,7 @@ export class Decoder { format, delay: this.#delay, wait: this.sync.out.maxDelay, - warmup: Duration.millis(config.warmup ?? 0), + warmup: Duration.millis(config.warmup ?? 0).min(DELAY_MAX), predecessor: continues ? outgoing.consumer : undefined, }); effect.cleanup(() => consumer.close()); diff --git a/js/watch/src/video/decoder.test.ts b/js/watch/src/video/decoder.test.ts index 1109a586823..dc50964bdcf 100644 --- a/js/watch/src/video/decoder.test.ts +++ b/js/watch/src/video/decoder.test.ts @@ -8,7 +8,7 @@ import { Effect, Signal } from "@moq/signals"; import { ringSamples } from "../audio/latency"; import { AudioRingBuffer } from "../audio/ring-buffer"; import type { Broadcast } from "../broadcast"; -import { type Delay, Sync, Track } from "../sync"; +import { DELAY_MAX, type Delay, Sync, Track } from "../sync"; import { Decoder, insertRecoveryPoint } from "./decoder"; import { Source } from "./source"; @@ -1643,6 +1643,8 @@ describe("Decoder with a warmup rendition", () => { [{}, 1], [{ warmup: Catalog.u53(0) }, 1], [{ warmup: WARMUP }, 2], + // An hour of warmup reaches back only as far as the delay cap. + [{ warmup: Catalog.u53(3_600_000) }, 2], ] as const) { const subscribe = spyOn(Moq.Track.Consumer.prototype, "subscribe"); const run = await refresh(fields); @@ -1650,9 +1652,8 @@ describe("Decoder with a warmup rendition", () => { expect(run.playback.codecs).toBe(decoders); const budgets = subscribe.mock.calls.map(([options]) => options?.delay?.max); // The max-delay decoder tolerates one sweep more; js/net merges the two upstream. - expect(budgets).toEqual( - decoders === 1 ? [Duration.millis(0)] : [Duration.millis(0), Duration.millis(WARMUP)], - ); + const warmup = Duration.millis(fields.warmup ?? 0).min(DELAY_MAX); + expect(budgets).toEqual(decoders === 1 ? [Duration.millis(0)] : [Duration.millis(0), warmup]); } finally { subscribe.mockRestore(); await run.close(); diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index f80cd940023..07dd75b0e41 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -19,7 +19,7 @@ import { rotateVideoDimensions } from "@moq/video"; import { base64ToBytes } from "../base64"; import { arrivedAt, type Counter, type Key, type Received, Tally } from "../feedback"; import { type Failure, failureMoved, nextMedia, subscribeMedia } from "../media"; -import type { Sync, Track } from "../sync"; +import { DELAY_MAX, type Sync, type Track } from "../sync"; import { type DecoderConfig, hardwareAcceleration, type PlaybackIdentity, playbackIdentity } from "./config"; import { caughtUp, renditionJitter, switchJitter } from "./playhead"; import { Recovery } from "./recovery"; @@ -1194,7 +1194,8 @@ class Rendition { this.#signals.run((effect) => { const config = effect.get(props.catalog)?.video?.renditions?.[props.track]; - warmup.set(Duration.millis(config?.warmup ?? 0)); + // Capped like the delay, so a catalog `warmup` cannot hold the viewer without bound. + warmup.set(Duration.millis(config?.warmup ?? 0).min(DELAY_MAX)); dual.set(!warmup.peek().isZero()); }); this.#signals.run((effect) => { diff --git a/quest/m1/audio-jitter-target/delay-cap.md b/quest/m1/audio-jitter-target/delay-cap.md index 302eb2c1b9c..8aee1563f62 100644 --- a/quest/m1/audio-jitter-target/delay-cap.md +++ b/quest/m1/audio-jitter-target/delay-cap.md @@ -1,4 +1,4 @@ -# [XS] A publisher's advertised delay cannot hold a browser viewer without bound +# [S] A publisher's advertised delay cannot hold a browser viewer without bound ## Goal @@ -34,34 +34,25 @@ Recommendations, as implemented: - A fixed delay is left alone: the viewer chose it, not the publisher. - A catalog advertising an hour of `jitter` and `delay` resolves to the cap. +Decided 2026-11-12 (coordinator, on the maintainer's behalf while away, from +the PR's recommendations): + +- ✅ (a) cap `moq play`'s audio target sum, the held jitter target plus the + catalog delay, at `LATENCY_MAX` too, so one 10 s ceiling holds everywhere + (rejected: (b) raise the browser to 20 s; (c) keep the mismatch). +- ✅ (a) clamp catalog `warmup` at `LATENCY_MAX` where the browser reads it, + and in Rust's `moq_mux::container::Playout` for parity (rejected: (b) reject + the rendition; (c) leave unbounded). + Findings: -- The premise that `moq play` caps at the same 10 s does not hold. It caps - each term on its own, the held jitter target and the catalog delay, each at - `LATENCY_MAX`, so its audio target can reach 20 s - (`rs/moq-cli/src/play/media.rs`). `moq_mux::sync` caps nothing itself: its - delay is the largest target its callers set. - The constants are pinned together in one place only: the `play` feature's test in `rs/moq-cli/src/play/args.rs` pins `DELAY_MAX` to - `moq_audio::playback::Input::LATENCY_MAX`. The browser constant is pinned to - it by its comment alone, since no test builds both. -- Catalog `warmup` is added to the subscription's max delay in the browser - with no cap (`js/watch/src/audio/decoder.ts`, `js/watch/src/video/decoder.ts`). - It is not one of the `jitter` or `delay` fields the Goal names. - -Public API: none. The constant stays internal to `@moq/watch`. Wire: none. - -## Waiting - -- Maintainer: pick the ceiling for `moq play`'s audio target, which reaches 20 s - while the browser stops at 10 s. Options: (a) cap `moq play`'s target sum at - `LATENCY_MAX` too, recommended, so one ceiling holds everywhere; (b) raise - the browser to 20 s to match `moq play`'s worst case; (c) keep the mismatch. - Check: the answer is recorded here, and a follow-up quest exists for `moq play`. -- Maintainer: pick how a catalog `warmup` above 10 s is bounded. Options: (a) - clamp it at `LATENCY_MAX` where the browser reads it, and in `rs/hang`'s - playout for parity, recommended, since only the publisher's own picture - suffers; (b) reject a rendition whose `warmup` exceeds it, which fails loud - but drops that rendition; (c) leave it unbounded, which misses this quest's - Goal for `warmup`. Check: the answer is recorded here, and a follow-up quest - exists for it. + `moq_audio::playback::Input::LATENCY_MAX`. The browser's `DELAY_MAX` and + `moq-mux`'s `WARMUP_MAX` are pinned to it by comment alone, since no test + builds them together. +- The warmup cap bounds what a reader buffers. A decoder's trim of a huge + `warmup` still discards that much of the publisher's own audio, which hurts + only its broadcast. + +Public API: none. The constants stay internal. Wire: none. diff --git a/rs/moq-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index e4bc90e4e31..115abf61f20 100644 --- a/rs/moq-cli/src/play/media.rs +++ b/rs/moq-cli/src/play/media.rs @@ -716,9 +716,14 @@ async fn play_audio( // The jitter target the last write held, so a rise in the stated delay applies // at once rather than waiting on the next write. let jitter = Mutex::new(None); + // The jitter target and the catalog delay are each capped, and so is their sum, + // so one ceiling bounds the clock however the publisher splits its advertisement. + let capped = |jitter: Duration, delay: Option| { + (jitter + delay.unwrap_or_default()).min(moq_audio::playback::Input::LATENCY_MAX) + }; let retarget = |delay: Option| { let Some(jitter) = *jitter.lock().unwrap() else { return }; - if role.set_target(jitter + delay.unwrap_or_default()) { + if role.set_target(capped(jitter, delay)) { changed.notify_one(); output.send(Event::Wake); } @@ -1008,7 +1013,7 @@ async fn play_audio( .max(delay.max(AUDIO_BUFFER_MIN)) .min(moq_audio::playback::Input::LATENCY_MAX); *jitter.lock().unwrap() = Some(held); - moved |= role.set_target(held + stated.borrow().unwrap_or_default()); + moved |= role.set_target(capped(held, *stated.borrow())); // The consumer releases media due further out than the sink holds only // when its timeline ends before the media behind it covers the hold, so // that little waits here instead of overflowing the sink. @@ -1248,6 +1253,15 @@ mod tests { ); } + /// A capped jitter target plus a capped catalog delay still holds the clock at + /// one ceiling, the same the browser holds. + #[tokio::test] + async fn audio_caps_a_target_plus_catalog_delay_at_the_deepest_delay() { + let latency = moq_audio::playback::Input::LATENCY_MAX; + let hour = Duration::from_secs(3600); + assert_on_time(first_sound(latency, latency, Some(hour), None).await, latency); + } + /// A target past what the sink's ring was sized for, under a budget longer /// still, holds the excess encoded rather than failing the sink. #[tokio::test] diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 52918cdabad..06c4347613a 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -324,10 +324,14 @@ fn gap(edge: std::time::Duration, resume: Timestamp) -> Item { pub struct Playout { /// The delay the consumer plays at, and skips past. pub delay: Delay, - /// How much further back than [`Delay::min`] the start reaches. + /// How much further back than [`Delay::min`] the start reaches, at most 10 s. pub warmup: std::time::Duration, } +/// The most warmup a [`Playout`] reaches back for, so a catalog `warmup` cannot hold a reader's +/// media without bound. Matches `moq_audio::playback::Input::LATENCY_MAX` and `@moq/watch`'s cap. +const WARMUP_MAX: std::time::Duration = std::time::Duration::from_secs(10); + impl Playout { /// Play at `delay`, starting `warmup` further back. pub fn new(delay: Delay, warmup: std::time::Duration) -> Self { @@ -346,7 +350,7 @@ impl Playout { /// set to that delay here, widened or narrowed. pub fn consumer(&self, track: moq_net::track::Subscriber, format: F) -> Consumer { let mut consumer = Consumer::new(track, format); - consumer.warmup = self.warmup; + consumer.warmup = self.reach(); consumer.set_delay(self.delay); consumer } @@ -354,7 +358,12 @@ impl Playout { /// The delay the subscription carries. fn subscribed(&self) -> Delay { self.delay - .with_max(self.delay.max.map(|max| max.saturating_add(self.warmup))) + .with_max(self.delay.max.map(|max| max.saturating_add(self.reach()))) + } + + /// The warmup, capped at [`WARMUP_MAX`]. + fn reach(&self) -> std::time::Duration { + self.warmup.min(WARMUP_MAX) } } @@ -3925,6 +3934,23 @@ mod tests { assert_eq!(consumer.warmup, Duration::from_millis(300)); } + /// A catalog warmup past the cap reaches back, and widens the subscription, by the cap alone. + #[tokio::test] + async fn the_playout_caps_a_huge_warmup() { + let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let delay = Delay::default().with_max(Some(Duration::from_millis(200))); + let playout = Playout::new(delay, Duration::from_secs(3600)); + let consumer = playout.consumer( + track.subscribe(playout.subscription(moq_net::track::Subscription::default())), + Container::Legacy(crate::container::Kind::Data), + ); + assert_eq!( + subscribed(&consumer).subscription().delay.max, + Some(Duration::from_millis(200) + WARMUP_MAX) + ); + assert_eq!(consumer.warmup, WARMUP_MAX); + } + /// An unlimited max delay keeps the subscription unlimited, and the min delay still sets the /// start's reach. #[tokio::test] From 51fca3b216bf4d0aea0949cbb11778d77463c63e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 02:44:25 -0800 Subject: [PATCH 4/6] fix(video): cap the catalog warmup on the refresh decoder's delay moq_video::decode::Consumer and moq play's refresh lane added a catalog warmup to the delay raw. Both now clamp it with moq_mux::container::WARMUP_MAX, the cap Playout holds. Co-Authored-By: Claude Opus 5.5 --- rs/moq-cli/src/play/media.rs | 2 +- rs/moq-mux/src/container/consumer.rs | 6 +++--- rs/moq-mux/src/container/mod.rs | 2 +- rs/moq-video/src/decode/consumer.rs | 32 +++++++++++++++++++++++++++- 4 files changed, 36 insertions(+), 6 deletions(-) diff --git a/rs/moq-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index 115abf61f20..b727b48594c 100644 --- a/rs/moq-cli/src/play/media.rs +++ b/rs/moq-cli/src/play/media.rs @@ -316,7 +316,7 @@ impl Media { // An intra-refresh rendition also runs a decoder with one more sweep // of budget, joining a group earlier so its pictures stay clean, as // `moq_video::decode::Consumer` does. Both share one upstream request. - let warmup = config.warmup.unwrap_or_default(); + let warmup = config.warmup.unwrap_or_default().min(moq_mux::container::WARMUP_MAX); let refresh = if warmup.is_zero() { None } else { diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 06c4347613a..5e4f73bbd0d 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -328,9 +328,9 @@ pub struct Playout { pub warmup: std::time::Duration, } -/// The most warmup a [`Playout`] reaches back for, so a catalog `warmup` cannot hold a reader's -/// media without bound. Matches `moq_audio::playback::Input::LATENCY_MAX` and `@moq/watch`'s cap. -const WARMUP_MAX: std::time::Duration = std::time::Duration::from_secs(10); +/// The most catalog `warmup` a reader reaches back for, so a publisher cannot hold a reader's media +/// without bound. Matches `moq_audio::playback::Input::LATENCY_MAX` and `@moq/watch`'s cap. +pub const WARMUP_MAX: std::time::Duration = std::time::Duration::from_secs(10); impl Playout { /// Play at `delay`, starting `warmup` further back. diff --git a/rs/moq-mux/src/container/mod.rs b/rs/moq-mux/src/container/mod.rs index c903ee3b5ba..1ecbfd2d75f 100644 --- a/rs/moq-mux/src/container/mod.rs +++ b/rs/moq-mux/src/container/mod.rs @@ -32,7 +32,7 @@ pub mod mkv; pub mod mp4; pub mod ts; -pub use consumer::{Consumer, Playout}; +pub use consumer::{Consumer, Playout, WARMUP_MAX}; pub use group::GroupConsumer; pub(crate) use input::Input; pub use producer::{Finished, Guard, Producer}; diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index fb6a00db244..ed779a11503 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -173,7 +173,7 @@ impl Consumer { let name = name.into(); let min = Reader::open(broadcast, catalog, &name, &options, options.delay, 0).await?; - let warmup = catalog.warmup.unwrap_or_default(); + let warmup = catalog.warmup.unwrap_or_default().min(moq_mux::container::WARMUP_MAX); let max = if warmup.is_zero() { None } else { @@ -1270,6 +1270,36 @@ mod tests { } } + /// A catalog warmup past the cap widens the max-delay decoder's subscription by the cap alone. + #[tokio::test] + async fn a_huge_warmup_reaches_back_by_the_cap() { + let (broadcast, mut track) = live_track(); + let published = track.clone(); + group(&mut track, 0, &[0]).finish().unwrap(); + let _consumer = Consumer::new( + &broadcast.consume(), + &warmup_catalog(Some(std::time::Duration::from_secs(3600))), + "video", + Options { + decoder: Config { + kind: Kind::Named(probe::IMMEDIATE_NAME.into()), + ..Config::new() + }, + start: Start::Latest, + delay: Delay { + max: Some(std::time::Duration::ZERO), + ..Delay::default() + }, + }, + ) + .await + .unwrap(); + assert_eq!( + published.subscription().and_then(|sub| sub.delay.max), + Some(moq_mux::container::WARMUP_MAX) + ); + } + /// On a cold network join the live edge's stream often lands first. The /// max-delay decoder still starts at the group before it, and takes over. #[tokio::test] From 37cee3a65676c914359d92dafac4ae76cd553256 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 06:43:23 -0800 Subject: [PATCH 5/6] quest: record where the warmup ceiling landed and its one export Co-Authored-By: Claude Opus 5.5 --- quest/m1/audio-jitter-target/delay-cap.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/quest/m1/audio-jitter-target/delay-cap.md b/quest/m1/audio-jitter-target/delay-cap.md index 8aee1563f62..228bfc6c09f 100644 --- a/quest/m1/audio-jitter-target/delay-cap.md +++ b/quest/m1/audio-jitter-target/delay-cap.md @@ -41,8 +41,10 @@ the PR's recommendations): catalog delay, at `LATENCY_MAX` too, so one 10 s ceiling holds everywhere (rejected: (b) raise the browser to 20 s; (c) keep the mismatch). - ✅ (a) clamp catalog `warmup` at `LATENCY_MAX` where the browser reads it, - and in Rust's `moq_mux::container::Playout` for parity (rejected: (b) reject - the rendition; (c) leave unbounded). + and in Rust for parity: `moq_mux::container::Playout`, `moq_video`'s + decode `Consumer`, and `moq play`'s video refresh, all through one + `moq_mux::container::WARMUP_MAX` (rejected: (b) reject the rendition; (c) + leave unbounded). Findings: @@ -55,4 +57,6 @@ Findings: `warmup` still discards that much of the publisher's own audio, which hurts only its broadcast. -Public API: none. The constants stay internal. Wire: none. +Public API: `moq_mux::container::WARMUP_MAX` (10 s) is exported so every +Rust reader of catalog `warmup` shares one ceiling; the browser's `DELAY_MAX` +stays internal. Wire: none. From b068948595ba5038ff6e28f23d83325093d75b0e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 06:58:40 -0800 Subject: [PATCH 6/6] fix(watch,moq-audio,moq-gst): cap each decoder's warmup join trim at the ceiling Co-Authored-By: Claude Opus 5.5 --- js/watch/src/audio/decoder.test.ts | 6 ++- js/watch/src/audio/decoder.ts | 14 ++++++- quest/m1/audio-jitter-target/delay-cap.md | 7 ++-- rs/moq-audio/src/decode/consumer.rs | 50 ++++++++++++++++++++++- rs/moq-gst/src/source/imp.rs | 10 ++++- 5 files changed, 79 insertions(+), 8 deletions(-) diff --git a/js/watch/src/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index d1bcb753f71..d2028a5eebe 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -14,6 +14,7 @@ import { decoderConfigKey } from "./config"; import type { Message, State, Terms } from "./render"; import { AudioRingBuffer } from "./ring-buffer"; import { Source } from "./source"; +import { Terminal } from "./terminal"; // Bun cannot load the blob-URL worklet import. mock.module("./render-worklet.ts?worklet", () => ({ default: async () => "blob:fake-render" })); @@ -634,7 +635,8 @@ describe("Decoder across a broadcast disable", () => { }); describe("Decoder across a delay change", () => { - it("reaches back for a catalog warmup no further than the delay cap", async () => { + it("reaches back and trims the join for a catalog warmup no further than the delay cap", async () => { + const trims = spyOn(Terminal.prototype, "clear"); // The max delay each subscribe and update asked the publisher for, in order. const asked: (Duration | null | undefined)[] = []; const subscribe = Moq.Track.Consumer.prototype.subscribe; @@ -662,7 +664,9 @@ describe("Decoder across a delay change", () => { await microtasks(); await playback.play(); expect(asked.at(-1)).toEqual(base.add(DELAY_MAX)); + expect(trims.mock.calls.at(-1)?.[1]).toBe(DELAY_MAX.asMicros()); } finally { + trims.mockRestore(); subscribes.mockRestore(); updates.mockRestore(); playback.close(); diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 4c7e0d355b1..2a07d2f0383 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -619,7 +619,12 @@ export class Decoder { #runLegacyDecoder(effect: Effect, sub: Moq.Track.Subscriber, { config, failure, path, key }: Attempt): void { const preSkip = config.codec === "opus" && config.description ? Util.Opus.preSkip(Util.Hex.toBytes(config.description)) : 0; - this.#terminal.clear(preSkip, (config.warmup ?? 0) * 1000); + this.#terminal.clear( + preSkip, + Duration.millis(config.warmup ?? 0) + .min(DELAY_MAX) + .asMicros(), + ); const format = config.container.kind === "loc" ? new Container.Loc.Format("audio") : new Container.Legacy.Format(config); // Create consumer with slightly less latency than the render worklet to avoid underflowing. @@ -705,7 +710,12 @@ export class Decoder { const init = Cmaf.decodeInitSegment(initSegment); const opusDescription = config.description ? Util.Hex.toBytes(config.description) : init.description; const preSkip = config.codec === "opus" && opusDescription ? Util.Opus.preSkip(opusDescription) : 0; - this.#terminal.clear(preSkip, (config.warmup ?? 0) * 1000); + this.#terminal.clear( + preSkip, + Duration.millis(config.warmup ?? 0) + .min(DELAY_MAX) + .asMicros(), + ); // Opus in CMAF uses raw packets (not OGG-wrapped), so description must be omitted. // The dOps box from the init segment is not a valid OGG Identification Header. const description = diff --git a/quest/m1/audio-jitter-target/delay-cap.md b/quest/m1/audio-jitter-target/delay-cap.md index 228bfc6c09f..eeeb6c24513 100644 --- a/quest/m1/audio-jitter-target/delay-cap.md +++ b/quest/m1/audio-jitter-target/delay-cap.md @@ -53,9 +53,10 @@ Findings: `moq_audio::playback::Input::LATENCY_MAX`. The browser's `DELAY_MAX` and `moq-mux`'s `WARMUP_MAX` are pinned to it by comment alone, since no test builds them together. -- The warmup cap bounds what a reader buffers. A decoder's trim of a huge - `warmup` still discards that much of the publisher's own audio, which hurts - only its broadcast. +- The warmup cap also bounds each decoder's join trim (the browser's audio + terminal, `moq-audio`'s decoder, `moq-gst`'s Opus clip): the subscription + reaches back only the ceiling, so trimming further would hold playback + silent past it. Public API: `moq_mux::container::WARMUP_MAX` (10 s) is exported so every Rust reader of catalog `warmup` shares one ceiling; the browser's `DELAY_MAX` diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index fbedf4f0098..76d98efa7ac 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -219,7 +219,7 @@ impl Consumer { } let name = name.into(); - let warmup = catalog.warmup.unwrap_or_default(); + let warmup = catalog.warmup.unwrap_or_default().min(moq_mux::container::WARMUP_MAX); let playout = moq_mux::container::Playout::new(options.delay, warmup); let track = broadcast.track(hang::catalog::Reference::track(catalog, &name))?; // The whole delay from the start, as the container keeps it: the transport enforces the @@ -1365,6 +1365,54 @@ mod tests { assert_eq!(stamps, expected, "the burst reached the decoder whole"); } + #[tokio::test(start_paused = true)] + async fn the_join_trim_stops_at_the_warmup_ceiling() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 48_000, 1); + catalog.warmup = Some(Duration::from_secs(3600)); + let mut producer = moq_mux::container::Producer::new( + track, + moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Audio), + ); + producer.seek(1).unwrap(); + let ceiling = moq_mux::container::WARMUP_MAX.as_micros() as u64; + // Contiguous, so no gap re-arms the warmup. + for micros in (0..=ceiling).step_by(20_000) { + producer + .write(moq_mux::container::Frame { + timestamp: Timestamp::from_micros(micros).unwrap(), + duration: None, + payload: vec![0; 960 * size_of::()].into(), + keyframe: true, + }) + .unwrap(); + producer.cut(None).unwrap(); + } + let _finished = producer.finish().unwrap(); + let options = Options { + delay: Delay { + max: Some(moq_mux::container::WARMUP_MAX), + ..Delay::default() + }, + ..Options::new() + }; + let mut consumer = Consumer::new(&broadcast.consume(), &catalog, "audio", options) + .await + .unwrap(); + let mut stamps = Vec::new(); + while let Some(frame) = next_frame(&mut consumer).await.unwrap() { + stamps.push(frame.timestamp.as_micros()); + } + assert_eq!( + stamps, + [ceiling as u128], + "an hour of warmup trims only up to the ceiling" + ); + } + #[tokio::test(start_paused = true)] async fn warmup_trims_the_join_without_trimming_groups_or_declared_returns() { let (stamps, frames) = warmup_output(true).await; diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 630b5761424..c80a83cf9e3 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -2058,7 +2058,9 @@ impl OpusClip { Some(u64::from(config.pre_skip)) }) .unwrap_or(0); - // Rounded up, so presentation never starts inside the warmup. + // Rounded up, so presentation never starts inside the warmup. Capped like the delay it widens, + // so an advertised warmup can't hold playback silent past the ceiling. + let warmup = warmup.min(moq_mux::container::WARMUP_MAX); let warmup = u64::try_from((warmup.as_nanos() * 48_000).div_ceil(1_000_000_000)).unwrap_or(u64::MAX); (total > 0 || warmup > 0).then_some(Self { total, @@ -2431,6 +2433,12 @@ mod tests { ); let headed = super::audio_caps(&config).unwrap(); assert!(super::OpusClip::new(&gst::Caps::new_empty_simple("video/x-h264"), warmup).is_none()); + let hour = super::OpusClip::new(&bare, Duration::from_secs(3600)).unwrap(); + assert_eq!( + hour.warmup, + moq_mux::container::WARMUP_MAX.as_secs() * 48_000, + "an hour of warmup clips only up to the ceiling" + ); // 20 ms (960-sample) CELT packets: (clipped samples, pts in microseconds) for each, after a // join, and from the track's first packet.