From 2d0f0004270bed7fb6cf50ff698b227d82f39aef Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 12:29:08 -0800 Subject: [PATCH 1/4] chore(quest): claim quest/m1/audio-jitter-target/delay-ceiling.md Quest-Claim: 250482ab39008458 From 8048684a33d5b52f5cfa7860941c2c3fa5623cef Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 12:37:04 -0800 Subject: [PATCH 2/4] refactor!: one exported 10 s playout ceiling, moq_mux::container::DELAY_MAX Co-Authored-By: Claude Opus 5.5 --- js/hang/api/container.api.md | 2 ++ js/hang/src/container/consumer.ts | 6 ++++ js/hang/src/container/index.ts | 2 +- js/watch/src/sync.ts | 9 ++--- quest/m1/audio-jitter-target/delay-ceiling.md | 34 ------------------- rs/moq-audio/src/decode/consumer.rs | 6 ++-- rs/moq-audio/src/playback/sink.rs | 18 ++++------ rs/moq-cli/src/play/args.rs | 12 +------ rs/moq-cli/src/play/media.rs | 14 ++++---- rs/moq-gst/src/source/imp.rs | 4 +-- rs/moq-mux/src/container/consumer.rs | 14 ++++---- rs/moq-mux/src/container/mod.rs | 2 +- rs/moq-video/src/decode/consumer.rs | 4 +-- 13 files changed, 41 insertions(+), 86 deletions(-) delete mode 100644 quest/m1/audio-jitter-target/delay-ceiling.md diff --git a/js/hang/api/container.api.md b/js/hang/api/container.api.md index 69cafe41f27..f8c64c1839a 100644 --- a/js/hang/api/container.api.md +++ b/js/hang/api/container.api.md @@ -30,6 +30,8 @@ export interface ConsumerProps { warmup?: Net.Clock.Duration; } +export const DELAY_MAX: Net.Clock.Duration; + export interface Format { decode(payload: Uint8Array, timestamp: Net.Time.Timestamp | undefined): Frame[]; end?(frame: Frame): Net.Clock.Duration | undefined; diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index a3427ca3ddf..d230a946b08 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -5,6 +5,12 @@ import type { Format } from "./format"; import { Jitter } from "./jitter"; import type { BufferedRanges, Frame, ReceivedFrame } from "./types"; +/** + * The longest playout delay: it caps a reader's latency and how far catalog `warmup` reaches back, + * so a publisher cannot hold a reader's media without bound. Mirrors `moq_mux::container::DELAY_MAX`. + */ +export const DELAY_MAX = Duration.secs(10); + /** Options for constructing a {@link Consumer}. */ export interface ConsumerProps { /** The container format used to decode each MoQ frame. */ diff --git a/js/hang/src/container/index.ts b/js/hang/src/container/index.ts index 7ae22670d60..cac63feafac 100644 --- a/js/hang/src/container/index.ts +++ b/js/hang/src/container/index.ts @@ -7,7 +7,7 @@ /** Re-export of {@link https://www.npmjs.com/package/@moq/loc | @moq/loc}, the LOC container. */ export * as Loc from "@moq/loc"; -export { Consumer, type ConsumerProps, type Read } from "./consumer"; +export { Consumer, type ConsumerProps, DELAY_MAX, type Read } from "./consumer"; export type { Format } from "./format"; /** The legacy varint container. */ export * as Legacy from "./legacy"; diff --git a/js/watch/src/sync.ts b/js/watch/src/sync.ts index c91e6a4b84f..176a7fb6d66 100644 --- a/js/watch/src/sync.ts +++ b/js/watch/src/sync.ts @@ -1,4 +1,5 @@ import { Duration, Instant, now, sleep } from "@moq/clock"; +import { Container } from "@moq/hang"; import { Derived, Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; /** @@ -18,12 +19,8 @@ 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); +/** The most an `"auto"` delay holds, and how far catalog `warmup` reaches back. @internal */ +export const DELAY_MAX = Container.DELAY_MAX; /** Signals the sync reads. */ export type SyncInput = { diff --git a/quest/m1/audio-jitter-target/delay-ceiling.md b/quest/m1/audio-jitter-target/delay-ceiling.md deleted file mode 100644 index 2808fdd655b..00000000000 --- a/quest/m1/audio-jitter-target/delay-ceiling.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] One exported 10 s playout ceiling - -## Goal - -The 10 s ceiling on playout delay, latency and catalog `warmup` is one -exported constant in Rust, mirrored by name in JS, and every other copy reuses -it. Today it is four constants under three names, kept equal by a test in one -case and by comments in the rest: - -- `@moq/watch`'s `DELAY_MAX` (`js/watch/src/sync.ts`, internal to the package). -- `moq_audio::playback::Input::LATENCY_MAX` (public, `rs/moq-audio/src/playback/sink.rs`). -- moq-cli's private `DELAY_MAX` (`rs/moq-cli/src/play/args.rs`), duplicated - because that module builds without the `play` feature and so without - moq-audio; a test pins it to `LATENCY_MAX`. -- `moq_mux::container::WARMUP_MAX` (public, added by - [moq-dev/moq#8549](https://github.com/moq-dev/moq/pull/8549)). - -## Plan - -Decided 2026-11-12 by the maintainer (coordinator session): ✅ unify the -ceiling, and keep clamping an oversized catalog `warmup` rather than rejecting -the rendition (rejected: leave the four constants as merged; reject an -oversized warmup). - -Recommendation: define it in `moq_mux::container`, which moq-cli always -depends on and moq-audio already imports for `WARMUP_MAX`, and mirror it in -`@moq/hang`'s container module (`js/hang/src/container`), which mirrors -`moq_mux::container`. Pick one name for what it bounds (playout delay), such -as `DELAY_MAX`, replacing `WARMUP_MAX` and `Input::LATENCY_MAX`, and have -`@moq/watch` import it. Removing two public Rust constants is breaking: mark -the title with `!` and give the migration in the PR's Impact section. - -Public API: one constant replaces `moq_mux::container::WARMUP_MAX` and -`moq_audio::playback::Input::LATENCY_MAX`, plus its JS export. Wire: none. diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 76d98efa7ac..5c17c3bcb2e 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().min(moq_mux::container::WARMUP_MAX); + let warmup = catalog.warmup.unwrap_or_default().min(moq_mux::container::DELAY_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 @@ -1378,7 +1378,7 @@ mod tests { 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; + let ceiling = moq_mux::container::DELAY_MAX.as_micros() as u64; // Contiguous, so no gap re-arms the warmup. for micros in (0..=ceiling).step_by(20_000) { producer @@ -1394,7 +1394,7 @@ mod tests { let _finished = producer.finish().unwrap(); let options = Options { delay: Delay { - max: Some(moq_mux::container::WARMUP_MAX), + max: Some(moq_mux::container::DELAY_MAX), ..Delay::default() }, ..Options::new() diff --git a/rs/moq-audio/src/playback/sink.rs b/rs/moq-audio/src/playback/sink.rs index 9874a4dd1ab..988b22c18c3 100644 --- a/rs/moq-audio/src/playback/sink.rs +++ b/rs/moq-audio/src/playback/sink.rs @@ -71,12 +71,6 @@ impl Default for Input { } impl Input { - /// The longest [`latency`](Self::latency) a sink accepts. Well past any - /// playout delay worth presenting, and it bounds the ring the device thread - /// walks. Public so a caller taking the depth from its own configuration can - /// refuse an impossible one before it opens a device. - pub const LATENCY_MAX: Duration = Duration::from_secs(10); - fn validate(&self) -> Result<(), Error> { if self.sample_rate == 0 { return Err(Error::Unsupported("sample rate must be > 0".into())); @@ -87,10 +81,10 @@ impl Input { self.layout ))); } - if self.latency.is_zero() || self.latency > Self::LATENCY_MAX { + if self.latency.is_zero() || self.latency > moq_mux::container::DELAY_MAX { return Err(Error::Unsupported(format!( "playback latency must be non-zero and at most {:?} (got {:?})", - Self::LATENCY_MAX, + moq_mux::container::DELAY_MAX, self.latency ))); } @@ -261,7 +255,7 @@ impl Sink { /// what it holds runs short of it, and speeds up past it only to catch up /// with the clock [`due`](Self::due) anchors it to. /// - /// Must be non-zero, at most [`Input::LATENCY_MAX`], and fit in the current + /// Must be non-zero, at most [`moq_mux::container::DELAY_MAX`], and fit in the current /// ring. Each device open or rebuild allocates the then-current target plus /// three seconds, less a 30 ms processing window reserved as headroom. /// Does not resize or reset the device. @@ -980,7 +974,7 @@ mod tests { /// device could ever drain is a delay nobody asked for. #[test] fn rejects_a_latency_it_cannot_buffer() { - for latency in [Duration::ZERO, Input::LATENCY_MAX + Duration::from_secs(1)] { + for latency in [Duration::ZERO, moq_mux::container::DELAY_MAX + Duration::from_secs(1)] { let input = Input { latency, ..Default::default() @@ -989,7 +983,7 @@ mod tests { } Input { - latency: Input::LATENCY_MAX, + latency: moq_mux::container::DELAY_MAX, ..Default::default() } .validate() @@ -1006,7 +1000,7 @@ mod tests { for latency in [ Duration::ZERO, Duration::from_secs(4), - Input::LATENCY_MAX + Duration::from_secs(1), + moq_mux::container::DELAY_MAX + Duration::from_secs(1), ] { assert!(sink.set_latency(latency).is_err()); assert_eq!(sink.input().latency, LATENCY); diff --git a/rs/moq-cli/src/play/args.rs b/rs/moq-cli/src/play/args.rs index e3de1852f87..62e16704adf 100644 --- a/rs/moq-cli/src/play/args.rs +++ b/rs/moq-cli/src/play/args.rs @@ -9,12 +9,7 @@ use moq_mux::catalog::CatalogFormat; use crate::subscribe::{CatalogFormatArg, Mode, SelectArgs}; -/// The longest delay the speaker can hold, which is what bounds `--delay`. -/// -/// Duplicated from `moq_audio::playback::Input::LATENCY_MAX` because this module -/// compiles without the `play` feature, and so without that crate. The test -/// below pins the two together in a build that has both. -const DELAY_MAX: Duration = Duration::from_secs(10); +use moq_mux::container::DELAY_MAX; /// How far playback trails the live edge under `auto` while audio holds no /// estimate, as when there is none: video has no estimator of its own. @@ -307,11 +302,6 @@ mod tests { assert!(err.contains("--delay must be at most"), "{err}"); parse(&["--delay", "10s"]).validate().unwrap(); parse(&["--delay", "auto"]).validate().unwrap(); - - // The bound has to be the sink's own, which only a build carrying the sink - // can say. - #[cfg(feature = "play")] - assert_eq!(DELAY_MAX, moq_audio::playback::Input::LATENCY_MAX); } /// The suffix picks the format, and the flag overrides it. diff --git a/rs/moq-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index b727b48594c..288c2a7f465 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().min(moq_mux::container::WARMUP_MAX); + let warmup = config.warmup.unwrap_or_default().min(moq_mux::container::DELAY_MAX); let refresh = if warmup.is_zero() { None } else { @@ -531,7 +531,7 @@ impl Demand { // playback retain media without bound. let delay = delay .filter(|_| args.fixed_delay().is_none()) - .map(|delay| delay.min(moq_audio::playback::Input::LATENCY_MAX)); + .map(|delay| delay.min(moq_mux::container::DELAY_MAX)); self.delay.send_if_modified(|held| { let raised = delay > *held; if raised { @@ -635,7 +635,7 @@ async fn play_audio( let cap = max_delay .max(AUDIO_BUFFER_MIN) .min(latency + SINK_ROOM) - .min(moq_audio::playback::Input::LATENCY_MAX); + .min(moq_mux::container::DELAY_MAX); // The longest hole worth playing through, in samples. A hole this player would // rather sit through is one it is already willing to buffer, which is what the @@ -719,7 +719,7 @@ async fn play_audio( // 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) + (jitter + delay.unwrap_or_default()).min(moq_mux::container::DELAY_MAX) }; let retarget = |delay: Option| { let Some(jitter) = *jitter.lock().unwrap() else { return }; @@ -1011,7 +1011,7 @@ async fn play_audio( // make playback retain media without bound. let held = latency .max(delay.max(AUDIO_BUFFER_MIN)) - .min(moq_audio::playback::Input::LATENCY_MAX); + .min(moq_mux::container::DELAY_MAX); *jitter.lock().unwrap() = Some(held); moved |= role.set_target(capped(held, *stated.borrow())); // The consumer releases media due further out than the sink holds only @@ -1246,7 +1246,7 @@ mod tests { /// jitter's, holds the clock at that depth instead. #[tokio::test] async fn audio_caps_a_target_past_the_deepest_delay() { - let latency = moq_audio::playback::Input::LATENCY_MAX; + let latency = moq_mux::container::DELAY_MAX; assert_on_time( first_sound(Duration::from_secs(20), Duration::from_secs(5), None, None).await, latency, @@ -1257,7 +1257,7 @@ mod tests { /// 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 latency = moq_mux::container::DELAY_MAX; let hour = Duration::from_secs(3600); assert_on_time(first_sound(latency, latency, Some(hour), None).await, latency); } diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 2b9f087862c..593a27bc18b 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -2060,7 +2060,7 @@ impl OpusClip { .unwrap_or(0); // 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 = warmup.min(moq_mux::container::DELAY_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, @@ -2436,7 +2436,7 @@ mod tests { let hour = super::OpusClip::new(&bare, Duration::from_secs(3600)).unwrap(); assert_eq!( hour.warmup, - moq_mux::container::WARMUP_MAX.as_secs() * 48_000, + moq_mux::container::DELAY_MAX.as_secs() * 48_000, "an hour of warmup clips only up to the ceiling" ); diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 5e4f73bbd0d..460e0025466 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 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); +/// The longest playout delay: it caps a reader's latency and how far catalog `warmup` reaches back, +/// so a publisher cannot hold a reader's media without bound. Mirrored by `@moq/hang`'s `DELAY_MAX`. +pub const DELAY_MAX: std::time::Duration = std::time::Duration::from_secs(10); impl Playout { /// Play at `delay`, starting `warmup` further back. @@ -361,9 +361,9 @@ impl Playout { .with_max(self.delay.max.map(|max| max.saturating_add(self.reach()))) } - /// The warmup, capped at [`WARMUP_MAX`]. + /// The warmup, capped at [`DELAY_MAX`]. fn reach(&self) -> std::time::Duration { - self.warmup.min(WARMUP_MAX) + self.warmup.min(DELAY_MAX) } } @@ -3946,9 +3946,9 @@ mod tests { ); assert_eq!( subscribed(&consumer).subscription().delay.max, - Some(Duration::from_millis(200) + WARMUP_MAX) + Some(Duration::from_millis(200) + DELAY_MAX) ); - assert_eq!(consumer.warmup, WARMUP_MAX); + assert_eq!(consumer.warmup, DELAY_MAX); } /// An unlimited max delay keeps the subscription unlimited, and the min delay still sets the diff --git a/rs/moq-mux/src/container/mod.rs b/rs/moq-mux/src/container/mod.rs index 1ecbfd2d75f..cfebb38e2c4 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, WARMUP_MAX}; +pub use consumer::{Consumer, DELAY_MAX, Playout}; 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 ed779a11503..93ff65f7138 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().min(moq_mux::container::WARMUP_MAX); + let warmup = catalog.warmup.unwrap_or_default().min(moq_mux::container::DELAY_MAX); let max = if warmup.is_zero() { None } else { @@ -1296,7 +1296,7 @@ mod tests { .unwrap(); assert_eq!( published.subscription().and_then(|sub| sub.delay.max), - Some(moq_mux::container::WARMUP_MAX) + Some(moq_mux::container::DELAY_MAX) ); } From 49cd5c1e3d3f3f792660a7138a05c26df9276248 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 12:49:00 -0800 Subject: [PATCH 3/4] fix: clamp @moq/hang's warmup to DELAY_MAX; point MIGRATE at the new constant Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.ts | 2 +- rs/moq-audio/MIGRATE.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index d230a946b08..87efbe4db7e 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -265,7 +265,7 @@ export class Consumer { this.#delay = getter(props.delay ?? {}); this.#wait = getter(props.wait); this.#maxBuffer = props.maxBuffer ?? DEFAULT_MAX_BUFFER; - this.#warmup = props.warmup ?? Duration.ZERO; + this.#warmup = (props.warmup ?? Duration.ZERO).min(DELAY_MAX); this.#jitter = props.predecessor ? props.predecessor.#jitter.fork() : new Jitter(); this.#spread = new Signal(Duration.millis(this.#jitter.measured)); this.spread = this.#spread; diff --git a/rs/moq-audio/MIGRATE.md b/rs/moq-audio/MIGRATE.md index 9d12aa62f7f..ee1d6d3e225 100644 --- a/rs/moq-audio/MIGRATE.md +++ b/rs/moq-audio/MIGRATE.md @@ -27,7 +27,7 @@ before the first frame after it. Existing callers need no change. `Sink::set_latency(duration)?` updates the device callback's playout target without replacing the sink. The duration must fit the current ring (the target at the last device open or rebuild plus three seconds, less a 30 ms window) and -remain within `Input::LATENCY_MAX`. Existing callers need no change: sinks +remain within `moq_mux::container::DELAY_MAX` (formerly `Input::LATENCY_MAX`). Existing callers need no change: sinks stretch toward `Input::latency` by default. `buffered()` includes output staged by the stretcher, and `finish()` drains it. Missing input still plays silence; this adds no packet loss concealment. From 13187c5d605e0064656f8caf0cbedc28f933ed81 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 12:51:29 -0800 Subject: [PATCH 4/4] chore: leave MIGRATE.md to the release cut Co-Authored-By: Claude Opus 5.5 --- rs/moq-audio/MIGRATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/moq-audio/MIGRATE.md b/rs/moq-audio/MIGRATE.md index ee1d6d3e225..9d12aa62f7f 100644 --- a/rs/moq-audio/MIGRATE.md +++ b/rs/moq-audio/MIGRATE.md @@ -27,7 +27,7 @@ before the first frame after it. Existing callers need no change. `Sink::set_latency(duration)?` updates the device callback's playout target without replacing the sink. The duration must fit the current ring (the target at the last device open or rebuild plus three seconds, less a 30 ms window) and -remain within `moq_mux::container::DELAY_MAX` (formerly `Input::LATENCY_MAX`). Existing callers need no change: sinks +remain within `Input::LATENCY_MAX`. Existing callers need no change: sinks stretch toward `Input::latency` by default. `buffered()` includes output staged by the stretcher, and `finish()` drains it. Missing input still plays silence; this adds no packet loss concealment.