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/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index 04ce8de8471..d2028a5eebe 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -7,13 +7,14 @@ 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"; 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,6 +635,44 @@ describe("Decoder across a broadcast disable", () => { }); describe("Decoder across a delay change", () => { + 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; + 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)); + expect(trims.mock.calls.at(-1)?.[1]).toBe(DELAY_MAX.asMicros()); + } finally { + trims.mockRestore(); + 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..2a07d2f0383 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)); } @@ -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 = @@ -858,7 +868,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/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/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 f54b0247238..eeeb6c24513 100644 --- a/quest/m1/audio-jitter-target/delay-cap.md +++ b/quest/m1/audio-jitter-target/delay-cap.md @@ -1,12 +1,12 @@ -# [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 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,38 @@ 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: - -- 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. - -Public API: possibly one exported constant in `@moq/watch`. Wire: none. +Recommendations, as implemented: + +- 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. + +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 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: + +- 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'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 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` +stays internal. Wire: none. 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-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index e4bc90e4e31..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 { @@ -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-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. diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 52918cdabad..5e4f73bbd0d 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 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. 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] 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]