From 146878b9e603a0f7f71f0b529226da4c702c3a57 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:18:59 -0700 Subject: [PATCH 1/7] chore(quest): claim quest/m1/cut-audit/catalog-parity.md Quest-Claim: 5cc56306d4c15795 From 786c325f0cd3bee159575198ea5557d52e83f142 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:36:55 -0700 Subject: [PATCH 2/7] wip(mux): prototype the browser's backlog start in the Rust consumer A prototype for the maintainer's decision, reverted in the next commit. Until the first item, the Rust container consumer's start moves past every group whose first frame trails the newest content by more than the max delay, the measure @moq/hang uses, so the quest's backlog starts at the 4 s group in both. Once reading begins, only a blocking group is skipped, as before. Paired tests in both consumers, and eight moq-mux tests that wrote a backlog before the first read now read first. It breaks two moq-video dual-decoder tests on main (the_tail_drains_from_both_decoders, a_max_delay_decode_error_fails_the_read): the warmup decoder's earlier group is fresh by its reach but its first frame trails the newest by more than max + warmup, so the start drops the group the warmup needs. moq-dev/moq#7311 adds the container warmup that would protect it. Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.skips.test.ts | 41 +++ rs/moq-mux/CHANGELOG.md | 1 + rs/moq-mux/src/container/consumer.rs | 266 ++++++++++++++----- 3 files changed, 241 insertions(+), 67 deletions(-) diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index 3592cfbd6dd..71de5a1cc4c 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -50,3 +50,44 @@ for (const count of [1, 16, 256]) { } }); } + +// Pairs `rs/moq-mux`'s `a_buffered_backlog_starts_within_the_budget`: a backlog that lands whole before +// the first read starts at the first group whose first frame is within the budget of the newest one. +// Five one-second groups of ten frames and a one-frame sixth at 5 s, with a 1.5 s budget, start at the +// 4 s group, whether the sixth is open or finished. +for (const open of [true, false]) { + test(`a buffered backlog starts within the budget (sixth group ${open ? "open" : "finished"})`, async () => { + const warn = spyOn(console, "warn").mockImplementation(() => {}); + const track = new Track.Producer("backlog"); + const consumer = new Consumer(track.subscribe({ maxDelay: Milli(30_000) }), { + format: new Format("data"), + maxDelay: Milli(1500), + }); + const frame = (micros: number) => ({ payload: Varint.encode(micros), timestamp: Time.Timestamp.now() }); + try { + for (let g = 0; g < 5; g++) { + const group = track.createGroup(g); + for (let f = 0; f < 10; f++) group.writeFrame(frame(g * 1_000_000 + f * 100_000)); + group.finish(); + } + const last = track.createGroup(5); + last.writeFrame(frame(5_000_000)); + if (!open) last.finish(); + while (consumer.buffered.peek().at(-1)?.end !== 5000) await consumer.buffered.changed(); + + const read: number[] = []; + for (let i = 0; i < 11; i++) { + const next = await consumer.next(); + if (next?.kind !== "frame") throw new Error(`unexpected read: ${JSON.stringify(next)}`); + read.push(next.frame.timestamp); + } + const expected = [...Array.from({ length: 10 }, (_, f) => 4_000_000 + f * 100_000), 5_000_000]; + expect(read).toEqual(expected); + } finally { + consumer.close(); + track.finish(); + track.close(); + warn.mockRestore(); + } + }); +} diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index a850cefe1a5..9ef9dc9f5ee 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- `container::Consumer` no longer plays a backlog that landed before its first read from the oldest group: until the first item, the start moves past every group whose first frame trails the newest content by more than the max delay, as `@moq/hang`'s consumer does, so a join starts at the same group in Rust and the browser. Once reading begins, only a blocking group is skipped, as before. - fMP4 import applies each track's edit list to its frame timestamps and drops the samples before the edit, such as AAC priming, along with the video samples decoding from a dropped sync sample, and a passthrough init no longer carries the `edts`. A consumer that offsets AAC priming itself must stop, or it shifts the track twice. An edit list it can't reduce to one shift (several media edits, or a rate other than 1) is refused with `Error::UnsupportedEditList`. ## [0.10.11](https://github.com/moq-dev/moq/compare/moq-mux-v0.10.10...moq-mux-v0.10.11) - 2026-10-05 diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 3f566a91a93..f6ea441e2f9 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -73,7 +73,10 @@ pub(crate) enum Item { /// /// Delivery starts at the lowest absolute start among the /// [`Subscription::ranges`](moq_net::track::Subscription::ranges) when every range names one, waiting for that group under the budget; without one it -/// starts wherever the publisher does, adopted from the first served groups. From there +/// starts wherever the publisher does, adopted from the first served groups. Until the first +/// item is read, the start also moves past every group whose first frame trails the newest +/// content by more than the budget, as `@moq/hang`'s consumer measures: a backlog that landed +/// whole would otherwise play from its oldest group, since nothing blocks. From there /// the same budget is the one rule that catches the consumer up to the live edge, and /// history the publisher no longer serves expires like any other gap, since its reach /// sits a full budget behind the newest content. @@ -466,6 +469,23 @@ impl Consumer { self.hole_timer = None; } + // Until the first item, the start is still open: a backlog that already landed would + // otherwise play from its oldest group, since nothing blocks, and stay that far behind + // for good. So the start moves past every group whose first frame trails the newest + // content by more than the budget, as `js/hang`'s consumer measures, keeping the join + // within the budget. Once reading begins, only a blocking group is skipped, below. + if self.edge.is_none() + && self.pending.len() > 1 + && self.pending[0].sequence <= self.current + && let Some(first) = self.poll_first_unread(waiter) + && self.poll_newest(waiter).saturating_sub(first) > self.max_delay + { + let next_start = self.pending[1].min_timestamp.map(std::time::Duration::from); + let current_end = self.pending[0].max_end; + self.skip_to(1, next_start, current_end)?; + continue; + } + // Return the next frame from the current group if possible. // If the current group is finished or errored, advance to the next group. if let Some(group) = self.pending.front_mut() @@ -581,31 +601,9 @@ impl Consumer { None }; - // Find the first newer group with data (our skip target) and where it starts. - let mut next_group = None; - for (i, group) in self.pending.iter_mut().enumerate() { - if group.sequence <= self.current { - continue; - } - - if let Poll::Ready(Some(ts)) = group.poll_min_timestamp(waiter, &self.format, false) { - next_group = Some((i, std::time::Duration::from(ts))); - break; - } - } - - // Find the max timestamp across all newer groups. - let mut max_timestamp = std::time::Duration::ZERO; - for group in self.pending.iter_mut().rev() { - if group.sequence <= self.current { - break; - } - - if let Poll::Ready(Some(ts)) = group.poll_max_timestamp(waiter, &self.format) { - max_timestamp = max_timestamp.max(ts.into()); - break; // We know older groups won't be newer than this. - } - } + // The first newer group with data (our skip target) and where it starts. + let next_group = self.poll_next_group(waiter); + let max_timestamp = self.poll_newest(waiter); // Walk the cursor over missing sequences below the first arrived group. // Groups race on independent QUIC streams (newer ones at higher priority), @@ -685,26 +683,7 @@ impl Consumer { }; if let Some((new_idx, next_start)) = target { - // Without a start read yet, nothing proves the timeline continues. - let hole = next_start.is_none_or(|start| !pts_contiguous(current_end.or(self.presented_end), start)); - let had_marker = self.pending.iter().take(new_idx).any(GroupBuffer::marker); - // Buffered frames are thrown away, and `current_end` counts them, so contiguity alone would hide them. - let discarded = self - .pending - .iter() - .take(new_idx) - .any(|group| !group.buffered.is_empty()); - let target = self.pending[new_idx].sequence; - self.discard(|group| group.sequence < target)?; - if hole || had_marker || discarded { - self.lose(); - } - let new_current = self.pending.front().map(|g| g.sequence).unwrap(); - - tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); - - self.current = new_current; - self.note_group_edge(); + self.skip_to(new_idx, next_start, current_end)?; continue; } @@ -721,6 +700,74 @@ impl Consumer { } } + // The timestamp of the current group's first unread frame, buffering one if it can. + fn poll_first_unread(&mut self, waiter: &kio::Waiter) -> Option { + let group = self.pending.front_mut()?; + let _ = group.poll_min_timestamp(waiter, &self.format, true); + let (frame, ..) = group.buffered.front()?; + Some(frame.timestamp.into()) + } + + // The first group past the cursor with a timestamp, the skip target, and where it starts. + fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Option<(usize, std::time::Duration)> { + for (i, group) in self.pending.iter_mut().enumerate() { + if group.sequence <= self.current { + continue; + } + + if let Poll::Ready(Some(ts)) = group.poll_min_timestamp(waiter, &self.format, false) { + return Some((i, ts.into())); + } + } + None + } + + // The max timestamp across the groups past the cursor, or zero without one. + fn poll_newest(&mut self, waiter: &kio::Waiter) -> std::time::Duration { + for group in self.pending.iter_mut().rev() { + if group.sequence <= self.current { + break; + } + + // Older groups won't be newer than this. + if let Poll::Ready(Some(ts)) = group.poll_max_timestamp(waiter, &self.format) { + return ts.into(); + } + } + std::time::Duration::ZERO + } + + // Move the cursor to the pending group at `new_idx`, dropping what lies below it. `next_start` is + // where that group begins, if read, and `current_end` how far the group left behind presented. + fn skip_to( + &mut self, + new_idx: usize, + next_start: Option, + current_end: Option, + ) -> Result<(), F::Error> { + // Without a start read yet, nothing proves the timeline continues. + let hole = next_start.is_none_or(|start| !pts_contiguous(current_end.or(self.presented_end), start)); + let had_marker = self.pending.iter().take(new_idx).any(GroupBuffer::marker); + // Buffered frames are thrown away, and `current_end` counts them, so contiguity alone would hide them. + let discarded = self + .pending + .iter() + .take(new_idx) + .any(|group| !group.buffered.is_empty()); + let target = self.pending[new_idx].sequence; + self.discard(|group| group.sequence < target)?; + if hole || had_marker || discarded { + self.lose(); + } + let new_current = self.pending.front().map(|g| g.sequence).unwrap(); + + tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); + + self.current = new_current; + self.note_group_edge(); + Ok(()) + } + // The subscription, which only an error ending the reader drops. fn subscriber(&mut self) -> &mut moq_net::track::Subscriber { self.track.as_mut().expect("read only until an error ends the reader") @@ -1787,10 +1834,23 @@ mod tests { track.subscribe(moq_net::track::Subscription::default().with_max_delay(Duration::from_secs(10))); let mut reader = Consumer::new(subscription, Container::Legacy(crate::container::Kind::Audio)); reader.max_delay = Duration::ZERO; - write_group(&mut track, 0, &[ts(0)]); + let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); + Container::Legacy(crate::container::Kind::Audio) + .write( + &mut group, + &[Frame { + timestamp: ts(0), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + // Read before the newer group lands, so the skip comes after the start. + assert!(matches!(reader.read().await.unwrap(), Some(Read::Frame { .. }))); write_group(&mut track, 3, &[ts(1_000_000)]); track.finish().unwrap(); - assert_eq!(items(&mut reader).await, ["0", "gap 0+1000000", "1000000"]); + assert_eq!(items(&mut reader).await, ["gap 0+1000000", "1000000"]); } /// A video group's trailing duration marker is that frame's end, not a declared stop. @@ -1937,11 +1997,24 @@ mod tests { // Keep transport filtering out of this test so it isolates the mux skip logic. consumer.max_delay = Duration::ZERO; - write_group(&mut track, 0, &[ts(0)]); + // Group 0 stays open, and is read before the newer group lands: the skip comes after the start. + let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); + Container::Legacy(crate::container::Kind::Audio) + .write( + &mut group, + &[Frame { + timestamp: ts(0), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + assert!(matches!(consumer.read().await.unwrap(), Some(Read::Frame { .. }))); write_group(&mut track, 3, &[ts(1_000_000)]); track.finish().unwrap(); - assert_eq!(items(&mut consumer).await, ["0", "gap 0+1000000", "1000000"]); + assert_eq!(items(&mut consumer).await, ["gap 0+1000000", "1000000"]); } #[tokio::test] @@ -2047,6 +2120,11 @@ mod tests { ) .unwrap(); + // Read group 0's frame before the later groups land, so they skip a stalled group rather + // than move the start. + let first = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(first.timestamp, ts(0)); + for g in 1..10u64 { let timestamps: Vec<_> = (0..3).map(|f| ts(g * 50_000 + f * 5_000)).collect(); write_group(&mut track, g, ×tamps); @@ -2059,7 +2137,7 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 28, "Expected group 0 frame + groups 1-9"); + assert_eq!(frames.len(), 27, "Expected groups 1-9 after group 0's frame"); assert!(!frames.is_empty(), "Expected at least some frames"); finisher.await.expect("finisher task panicked"); } @@ -2084,6 +2162,11 @@ mod tests { ) .unwrap(); + // Read group 0's frame before the later groups land, so they skip a stalled group rather + // than move the start. + let first = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(first.timestamp, ts(0)); + for g in 1..10u64 { write_group(&mut track, g, &[ts(g * 30_000)]); } @@ -2095,20 +2178,17 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert!(!frames.is_empty(), "Expected at least some frames"); - assert_eq!(frames.len(), 10, "Expected group 0 frame + groups 1-9"); - assert_eq!(frames[0].timestamp, ts(0)); - - for i in 1..10u64 { - assert_eq!(frames[i as usize].timestamp, ts(i * 30_000)); + assert_eq!(frames.len(), 9, "Expected groups 1-9 after group 0's frame"); + for (i, frame) in (1..10u64).zip(&frames) { + assert_eq!(frame.timestamp, ts(i * 30_000)); } finisher.await.expect("finisher task panicked"); } /// A group longer than the budget that blocks for a moment behind a newer group is /// not cut short while what it could still present (up to where the newer group - /// begins) is within the budget. A join's backlog does exactly this: the newer group - /// races ahead on its own stream while the older one is still arriving. + /// begins) is within the budget: the newer group races ahead on its own stream while + /// the older one is still arriving. #[test] fn a_long_group_blocked_behind_a_newer_one_is_not_cut_short() { let waiter = kio::Waiter::noop(); @@ -2134,15 +2214,16 @@ mod tests { } }; - // A 2.5 s group, half arrived, and the next one already 0.5 s in. + // A 2.5 s group, half arrived, and the next one already 0.5 s in. The reader started + // before the next one landed, so this is a stall, not a join's backlog. let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); write(&mut group0, ts(0)); write(&mut group0, ts(500_000)); + assert_eq!(read(&mut consumer), Some(ts(0))); let mut group1 = track.create_group(moq_net::group::Info { sequence: 1 }).unwrap(); write(&mut group1, ts(2_500_000)); write(&mut group1, ts(3_000_000)); - assert_eq!(read(&mut consumer), Some(ts(0))); assert_eq!(read(&mut consumer), Some(ts(500_000))); // Group 0's reach (2.5 s) is 0.5 s behind the newest frame: wait for it. assert_eq!(read(&mut consumer), None, "cut group 0 short"); @@ -2161,6 +2242,52 @@ mod tests { group2.finish().unwrap(); } + /// A backlog that lands whole before the first read starts at the first group whose first + /// frame is within the budget of the newest one, though nothing blocks. Five one-second + /// groups of ten frames and a one-frame sixth at 5 s, with a 1.5 s budget, start at the 4 s + /// group, whether the sixth is open or finished. `js/hang`'s `consumer.skips.test.ts` pairs + /// this case. + #[test] + fn a_buffered_backlog_starts_within_the_budget() { + for open in [true, false] { + let waiter = kio::Waiter::noop(); + let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let mut consumer = container_max_delay_only(track.subscribe(None), Duration::from_millis(1500)); + for g in 0..5u64 { + let timestamps: Vec<_> = (0..10).map(|f| ts(g * 1_000_000 + f * 100_000)).collect(); + write_group(&mut track, g, ×tamps); + } + let mut last = track.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); + Container::Legacy(crate::container::Kind::Data) + .write( + &mut last, + &[Frame { + timestamp: ts(5_000_000), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + if !open { + last.finish().unwrap(); + } + + let mut read = Vec::new(); + while let Poll::Ready(Ok(Some(item))) = consumer.poll_read(&waiter) { + match item { + Read::Frame { frame, .. } => read.push(frame.timestamp), + other => panic!("unexpected read: {other:?}"), + } + } + let expected: Vec<_> = (0..10) + .map(|f| ts(4_000_000 + f * 100_000)) + .chain([ts(5_000_000)]) + .collect(); + assert_eq!(read, expected, "sixth group open: {open}"); + } + } + // ---- Malformed rewind ---- /// The track refuses a group whose first frame rewinds, but not a later frame that does, @@ -3523,13 +3650,14 @@ mod tests { ); // Group 9 pushes the newest content a full budget past what group 5 could still - // present (bounded by group 7's start), expiring it. - write_group(&mut track, 9, &[ts(800_000)]); + // present (bounded by group 7's start), expiring it. Exactly a budget, so group 7's + // first frame is not past it and the start stays there. + write_group(&mut track, 9, &[ts(710_000)]); track.finish().unwrap(); let frames = read_all(&mut consumer).await.unwrap(); let micros: Vec = frames.iter().map(|f| f.timestamp.as_micros()).collect(); - assert_eq!(micros, vec![210_000, 800_000], "the expired frameless group is skipped"); + assert_eq!(micros, vec![210_000, 710_000], "the expired frameless group is skipped"); } /// An aborted frameless group beyond a sequence gap is reaped rather than parked on @@ -3797,6 +3925,9 @@ mod tests { ) .unwrap(); + // Read before group 1 lands, so the skip comes after the start. + assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); + // Group 1: finished, 200ms ahead (well beyond the 100ms max delay) write_group(&mut track, 1, &[ts(200_000)]); track.finish().unwrap(); @@ -3807,7 +3938,7 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 2, "Expected group 0 frame + group 1 frame"); + assert_eq!(frames.len(), 1, "Expected group 1's frame after group 0's"); finisher.await.unwrap(); } @@ -3821,14 +3952,15 @@ mod tests { let consumer_track = track.subscribe(None); let mut consumer = container_max_delay_only(consumer_track, Duration::from_millis(100)); - // Group 0: finished normally + // Group 0: finished normally, its first frame read before group 2 lands. write_group(&mut track, 0, &[ts(0), ts(20_000)]); + assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); // Group 2: finished (group 1 is missing — sequence gap) write_group(&mut track, 2, &[ts(200_000)]); track.finish().unwrap(); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 3, "Expected group 0 (2 frames) + group 2 (1 frame)"); + assert_eq!(frames.len(), 2, "Expected group 0's second frame + group 2 (1 frame)"); } #[tokio::test] From 64b525926133120f303e40f4e616ddcd6ba822b2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:39:03 -0700 Subject: [PATCH 3/7] docs(quest): record the backlog-start options and leave the pick to the maintainer Reverts the prototype in the previous commit, which breaks moq-video's dual-decoder warmup on main, and rewrites the quest with what the attempt found: the wire judges a group by its reach, JS by its first frame, and Rust skips only a blocking group. It lists the two start measures with their test fallout and recommends the browser's measure at the start, after moq-dev/moq#7311 lands the container warmup the Rust start needs. Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.skips.test.ts | 41 --- quest/m1/cut-audit/catalog-parity.md | 45 +++- rs/moq-mux/CHANGELOG.md | 1 - rs/moq-mux/src/container/consumer.rs | 266 +++++-------------- 4 files changed, 109 insertions(+), 244 deletions(-) diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index 71de5a1cc4c..3592cfbd6dd 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -50,44 +50,3 @@ for (const count of [1, 16, 256]) { } }); } - -// Pairs `rs/moq-mux`'s `a_buffered_backlog_starts_within_the_budget`: a backlog that lands whole before -// the first read starts at the first group whose first frame is within the budget of the newest one. -// Five one-second groups of ten frames and a one-frame sixth at 5 s, with a 1.5 s budget, start at the -// 4 s group, whether the sixth is open or finished. -for (const open of [true, false]) { - test(`a buffered backlog starts within the budget (sixth group ${open ? "open" : "finished"})`, async () => { - const warn = spyOn(console, "warn").mockImplementation(() => {}); - const track = new Track.Producer("backlog"); - const consumer = new Consumer(track.subscribe({ maxDelay: Milli(30_000) }), { - format: new Format("data"), - maxDelay: Milli(1500), - }); - const frame = (micros: number) => ({ payload: Varint.encode(micros), timestamp: Time.Timestamp.now() }); - try { - for (let g = 0; g < 5; g++) { - const group = track.createGroup(g); - for (let f = 0; f < 10; f++) group.writeFrame(frame(g * 1_000_000 + f * 100_000)); - group.finish(); - } - const last = track.createGroup(5); - last.writeFrame(frame(5_000_000)); - if (!open) last.finish(); - while (consumer.buffered.peek().at(-1)?.end !== 5000) await consumer.buffered.changed(); - - const read: number[] = []; - for (let i = 0; i < 11; i++) { - const next = await consumer.next(); - if (next?.kind !== "frame") throw new Error(`unexpected read: ${JSON.stringify(next)}`); - read.push(next.frame.timestamp); - } - const expected = [...Array.from({ length: 10 }, (_, f) => 4_000_000 + f * 100_000), 5_000_000]; - expect(read).toEqual(expected); - } finally { - consumer.close(); - track.finish(); - track.close(); - warn.mockRestore(); - } - }); -} diff --git a/quest/m1/cut-audit/catalog-parity.md b/quest/m1/cut-audit/catalog-parity.md index d78e3a4ea54..3ebd3319c38 100644 --- a/quest/m1/cut-audit/catalog-parity.md +++ b/quest/m1/cut-audit/catalog-parity.md @@ -29,6 +29,45 @@ group, while Rust starts at 0 and plays the whole backlog, whether the sixth group is open or finished. Rust's skip only runs while the current group blocks, so a fully buffered backlog never triggers it. -Decide which start is right (likely JS's, which keeps the join within the -budget), align the other consumer, and keep the scenario as a paired test in -both. +What the 2026-11-01 attempt +([moq-dev/moq#7518](https://github.com/moq-dev/moq/pull/7518)) found, with +prototypes on main at `a3440aa239`: + +- Rust's measure is the wire's: `Subscription::max_delay` in moq-net and + `#staleAt` in js/net judge a group by its reach, where its successor + begins. By reach the scenario starts at the 3.0 s group, so neither + consumer's start matches the other's or the wire's. +- The reach is a transport measure: a backlog bursts faster than real time, + so trailing is survivable there. A player plays a buffered backlog at real + time, so a reach start trails by up to the budget plus one group, and Rust + never catches up, since it skips only a blocking group. +- Skipping buffered groups at any time, not only at the start, changes + steady-state behavior that other code relies on. 12 moq-mux tests fail, + including TS release and export tests whose own deadline accounting + expects the consumer to never drop a frame it already buffered. +- Restricting it to the start, until the first item is read, leaves the + steady state alone: + - **JS's first-frame measure at the start** (prototype in + [786c325f0c](https://github.com/moq-dev/moq/commit/786c325f0cd3bee159575198ea5557d52e83f142)): + both start at 4.0 s. Eight moq-mux tests that wrote a backlog before + the first read need to read first. Two moq-video dual-decoder tests + break (`the_tail_drains_from_both_decoders`, + `a_max_delay_decode_error_fails_the_read`): the warmup decoder's earlier + group is fresh by its reach, but its first frame trails the newest by + more than max + warmup, so the start drops the group the warmup needs. + [moq-dev/moq#7311](https://github.com/moq-dev/moq/pull/7311) adds the + container `with_warmup` and, in JS, keeps the group covering the start's + reach through the warmup. The Rust start needs the same protection. + - **The reach at the start in both**: both start at 3.0 s. Rust passes + moq-mux, moq-video, and moq-audio with the same eight test edits. JS's + `#checkMaxDelay` changes to the reach, which fails two existing hang + tests (`Consumer raises a malformed group an age skip passes after the + track finished`, `Consumer reads a gap when retiring an open group`). + +Pending the maintainer's pick (see the PR's `## Decisions needed`), the +recommendation is JS's measure at the start, landed after +[moq-dev/moq#7311](https://github.com/moq-dev/moq/pull/7311), with the Rust +start keeping the group covering the start's reach through the warmup as +that PR's JS does. Keep the scenario as a paired test in both (the +prototype's `a_buffered_backlog_starts_within_the_budget` and +`consumer.skips.test.ts` case). diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index 9ef9dc9f5ee..a850cefe1a5 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -19,7 +19,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- `container::Consumer` no longer plays a backlog that landed before its first read from the oldest group: until the first item, the start moves past every group whose first frame trails the newest content by more than the max delay, as `@moq/hang`'s consumer does, so a join starts at the same group in Rust and the browser. Once reading begins, only a blocking group is skipped, as before. - fMP4 import applies each track's edit list to its frame timestamps and drops the samples before the edit, such as AAC priming, along with the video samples decoding from a dropped sync sample, and a passthrough init no longer carries the `edts`. A consumer that offsets AAC priming itself must stop, or it shifts the track twice. An edit list it can't reduce to one shift (several media edits, or a rate other than 1) is refused with `Error::UnsupportedEditList`. ## [0.10.11](https://github.com/moq-dev/moq/compare/moq-mux-v0.10.10...moq-mux-v0.10.11) - 2026-10-05 diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index f6ea441e2f9..3f566a91a93 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -73,10 +73,7 @@ pub(crate) enum Item { /// /// Delivery starts at the lowest absolute start among the /// [`Subscription::ranges`](moq_net::track::Subscription::ranges) when every range names one, waiting for that group under the budget; without one it -/// starts wherever the publisher does, adopted from the first served groups. Until the first -/// item is read, the start also moves past every group whose first frame trails the newest -/// content by more than the budget, as `@moq/hang`'s consumer measures: a backlog that landed -/// whole would otherwise play from its oldest group, since nothing blocks. From there +/// starts wherever the publisher does, adopted from the first served groups. From there /// the same budget is the one rule that catches the consumer up to the live edge, and /// history the publisher no longer serves expires like any other gap, since its reach /// sits a full budget behind the newest content. @@ -469,23 +466,6 @@ impl Consumer { self.hole_timer = None; } - // Until the first item, the start is still open: a backlog that already landed would - // otherwise play from its oldest group, since nothing blocks, and stay that far behind - // for good. So the start moves past every group whose first frame trails the newest - // content by more than the budget, as `js/hang`'s consumer measures, keeping the join - // within the budget. Once reading begins, only a blocking group is skipped, below. - if self.edge.is_none() - && self.pending.len() > 1 - && self.pending[0].sequence <= self.current - && let Some(first) = self.poll_first_unread(waiter) - && self.poll_newest(waiter).saturating_sub(first) > self.max_delay - { - let next_start = self.pending[1].min_timestamp.map(std::time::Duration::from); - let current_end = self.pending[0].max_end; - self.skip_to(1, next_start, current_end)?; - continue; - } - // Return the next frame from the current group if possible. // If the current group is finished or errored, advance to the next group. if let Some(group) = self.pending.front_mut() @@ -601,9 +581,31 @@ impl Consumer { None }; - // The first newer group with data (our skip target) and where it starts. - let next_group = self.poll_next_group(waiter); - let max_timestamp = self.poll_newest(waiter); + // Find the first newer group with data (our skip target) and where it starts. + let mut next_group = None; + for (i, group) in self.pending.iter_mut().enumerate() { + if group.sequence <= self.current { + continue; + } + + if let Poll::Ready(Some(ts)) = group.poll_min_timestamp(waiter, &self.format, false) { + next_group = Some((i, std::time::Duration::from(ts))); + break; + } + } + + // Find the max timestamp across all newer groups. + let mut max_timestamp = std::time::Duration::ZERO; + for group in self.pending.iter_mut().rev() { + if group.sequence <= self.current { + break; + } + + if let Poll::Ready(Some(ts)) = group.poll_max_timestamp(waiter, &self.format) { + max_timestamp = max_timestamp.max(ts.into()); + break; // We know older groups won't be newer than this. + } + } // Walk the cursor over missing sequences below the first arrived group. // Groups race on independent QUIC streams (newer ones at higher priority), @@ -683,7 +685,26 @@ impl Consumer { }; if let Some((new_idx, next_start)) = target { - self.skip_to(new_idx, next_start, current_end)?; + // Without a start read yet, nothing proves the timeline continues. + let hole = next_start.is_none_or(|start| !pts_contiguous(current_end.or(self.presented_end), start)); + let had_marker = self.pending.iter().take(new_idx).any(GroupBuffer::marker); + // Buffered frames are thrown away, and `current_end` counts them, so contiguity alone would hide them. + let discarded = self + .pending + .iter() + .take(new_idx) + .any(|group| !group.buffered.is_empty()); + let target = self.pending[new_idx].sequence; + self.discard(|group| group.sequence < target)?; + if hole || had_marker || discarded { + self.lose(); + } + let new_current = self.pending.front().map(|g| g.sequence).unwrap(); + + tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); + + self.current = new_current; + self.note_group_edge(); continue; } @@ -700,74 +721,6 @@ impl Consumer { } } - // The timestamp of the current group's first unread frame, buffering one if it can. - fn poll_first_unread(&mut self, waiter: &kio::Waiter) -> Option { - let group = self.pending.front_mut()?; - let _ = group.poll_min_timestamp(waiter, &self.format, true); - let (frame, ..) = group.buffered.front()?; - Some(frame.timestamp.into()) - } - - // The first group past the cursor with a timestamp, the skip target, and where it starts. - fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Option<(usize, std::time::Duration)> { - for (i, group) in self.pending.iter_mut().enumerate() { - if group.sequence <= self.current { - continue; - } - - if let Poll::Ready(Some(ts)) = group.poll_min_timestamp(waiter, &self.format, false) { - return Some((i, ts.into())); - } - } - None - } - - // The max timestamp across the groups past the cursor, or zero without one. - fn poll_newest(&mut self, waiter: &kio::Waiter) -> std::time::Duration { - for group in self.pending.iter_mut().rev() { - if group.sequence <= self.current { - break; - } - - // Older groups won't be newer than this. - if let Poll::Ready(Some(ts)) = group.poll_max_timestamp(waiter, &self.format) { - return ts.into(); - } - } - std::time::Duration::ZERO - } - - // Move the cursor to the pending group at `new_idx`, dropping what lies below it. `next_start` is - // where that group begins, if read, and `current_end` how far the group left behind presented. - fn skip_to( - &mut self, - new_idx: usize, - next_start: Option, - current_end: Option, - ) -> Result<(), F::Error> { - // Without a start read yet, nothing proves the timeline continues. - let hole = next_start.is_none_or(|start| !pts_contiguous(current_end.or(self.presented_end), start)); - let had_marker = self.pending.iter().take(new_idx).any(GroupBuffer::marker); - // Buffered frames are thrown away, and `current_end` counts them, so contiguity alone would hide them. - let discarded = self - .pending - .iter() - .take(new_idx) - .any(|group| !group.buffered.is_empty()); - let target = self.pending[new_idx].sequence; - self.discard(|group| group.sequence < target)?; - if hole || had_marker || discarded { - self.lose(); - } - let new_current = self.pending.front().map(|g| g.sequence).unwrap(); - - tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); - - self.current = new_current; - self.note_group_edge(); - Ok(()) - } - // The subscription, which only an error ending the reader drops. fn subscriber(&mut self) -> &mut moq_net::track::Subscriber { self.track.as_mut().expect("read only until an error ends the reader") @@ -1834,23 +1787,10 @@ mod tests { track.subscribe(moq_net::track::Subscription::default().with_max_delay(Duration::from_secs(10))); let mut reader = Consumer::new(subscription, Container::Legacy(crate::container::Kind::Audio)); reader.max_delay = Duration::ZERO; - let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); - Container::Legacy(crate::container::Kind::Audio) - .write( - &mut group, - &[Frame { - timestamp: ts(0), - payload: Bytes::from_static(&[0xDE, 0xAD]), - keyframe: false, - duration: None, - }], - ) - .unwrap(); - // Read before the newer group lands, so the skip comes after the start. - assert!(matches!(reader.read().await.unwrap(), Some(Read::Frame { .. }))); + write_group(&mut track, 0, &[ts(0)]); write_group(&mut track, 3, &[ts(1_000_000)]); track.finish().unwrap(); - assert_eq!(items(&mut reader).await, ["gap 0+1000000", "1000000"]); + assert_eq!(items(&mut reader).await, ["0", "gap 0+1000000", "1000000"]); } /// A video group's trailing duration marker is that frame's end, not a declared stop. @@ -1997,24 +1937,11 @@ mod tests { // Keep transport filtering out of this test so it isolates the mux skip logic. consumer.max_delay = Duration::ZERO; - // Group 0 stays open, and is read before the newer group lands: the skip comes after the start. - let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); - Container::Legacy(crate::container::Kind::Audio) - .write( - &mut group, - &[Frame { - timestamp: ts(0), - payload: Bytes::from_static(&[0xDE, 0xAD]), - keyframe: false, - duration: None, - }], - ) - .unwrap(); - assert!(matches!(consumer.read().await.unwrap(), Some(Read::Frame { .. }))); + write_group(&mut track, 0, &[ts(0)]); write_group(&mut track, 3, &[ts(1_000_000)]); track.finish().unwrap(); - assert_eq!(items(&mut consumer).await, ["gap 0+1000000", "1000000"]); + assert_eq!(items(&mut consumer).await, ["0", "gap 0+1000000", "1000000"]); } #[tokio::test] @@ -2120,11 +2047,6 @@ mod tests { ) .unwrap(); - // Read group 0's frame before the later groups land, so they skip a stalled group rather - // than move the start. - let first = consumer.read_frame().await.unwrap().unwrap(); - assert_eq!(first.timestamp, ts(0)); - for g in 1..10u64 { let timestamps: Vec<_> = (0..3).map(|f| ts(g * 50_000 + f * 5_000)).collect(); write_group(&mut track, g, ×tamps); @@ -2137,7 +2059,7 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 27, "Expected groups 1-9 after group 0's frame"); + assert_eq!(frames.len(), 28, "Expected group 0 frame + groups 1-9"); assert!(!frames.is_empty(), "Expected at least some frames"); finisher.await.expect("finisher task panicked"); } @@ -2162,11 +2084,6 @@ mod tests { ) .unwrap(); - // Read group 0's frame before the later groups land, so they skip a stalled group rather - // than move the start. - let first = consumer.read_frame().await.unwrap().unwrap(); - assert_eq!(first.timestamp, ts(0)); - for g in 1..10u64 { write_group(&mut track, g, &[ts(g * 30_000)]); } @@ -2178,17 +2095,20 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 9, "Expected groups 1-9 after group 0's frame"); - for (i, frame) in (1..10u64).zip(&frames) { - assert_eq!(frame.timestamp, ts(i * 30_000)); + assert!(!frames.is_empty(), "Expected at least some frames"); + assert_eq!(frames.len(), 10, "Expected group 0 frame + groups 1-9"); + assert_eq!(frames[0].timestamp, ts(0)); + + for i in 1..10u64 { + assert_eq!(frames[i as usize].timestamp, ts(i * 30_000)); } finisher.await.expect("finisher task panicked"); } /// A group longer than the budget that blocks for a moment behind a newer group is /// not cut short while what it could still present (up to where the newer group - /// begins) is within the budget: the newer group races ahead on its own stream while - /// the older one is still arriving. + /// begins) is within the budget. A join's backlog does exactly this: the newer group + /// races ahead on its own stream while the older one is still arriving. #[test] fn a_long_group_blocked_behind_a_newer_one_is_not_cut_short() { let waiter = kio::Waiter::noop(); @@ -2214,16 +2134,15 @@ mod tests { } }; - // A 2.5 s group, half arrived, and the next one already 0.5 s in. The reader started - // before the next one landed, so this is a stall, not a join's backlog. + // A 2.5 s group, half arrived, and the next one already 0.5 s in. let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); write(&mut group0, ts(0)); write(&mut group0, ts(500_000)); - assert_eq!(read(&mut consumer), Some(ts(0))); let mut group1 = track.create_group(moq_net::group::Info { sequence: 1 }).unwrap(); write(&mut group1, ts(2_500_000)); write(&mut group1, ts(3_000_000)); + assert_eq!(read(&mut consumer), Some(ts(0))); assert_eq!(read(&mut consumer), Some(ts(500_000))); // Group 0's reach (2.5 s) is 0.5 s behind the newest frame: wait for it. assert_eq!(read(&mut consumer), None, "cut group 0 short"); @@ -2242,52 +2161,6 @@ mod tests { group2.finish().unwrap(); } - /// A backlog that lands whole before the first read starts at the first group whose first - /// frame is within the budget of the newest one, though nothing blocks. Five one-second - /// groups of ten frames and a one-frame sixth at 5 s, with a 1.5 s budget, start at the 4 s - /// group, whether the sixth is open or finished. `js/hang`'s `consumer.skips.test.ts` pairs - /// this case. - #[test] - fn a_buffered_backlog_starts_within_the_budget() { - for open in [true, false] { - let waiter = kio::Waiter::noop(); - let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); - let mut consumer = container_max_delay_only(track.subscribe(None), Duration::from_millis(1500)); - for g in 0..5u64 { - let timestamps: Vec<_> = (0..10).map(|f| ts(g * 1_000_000 + f * 100_000)).collect(); - write_group(&mut track, g, ×tamps); - } - let mut last = track.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); - Container::Legacy(crate::container::Kind::Data) - .write( - &mut last, - &[Frame { - timestamp: ts(5_000_000), - payload: Bytes::from_static(&[0xDE, 0xAD]), - keyframe: false, - duration: None, - }], - ) - .unwrap(); - if !open { - last.finish().unwrap(); - } - - let mut read = Vec::new(); - while let Poll::Ready(Ok(Some(item))) = consumer.poll_read(&waiter) { - match item { - Read::Frame { frame, .. } => read.push(frame.timestamp), - other => panic!("unexpected read: {other:?}"), - } - } - let expected: Vec<_> = (0..10) - .map(|f| ts(4_000_000 + f * 100_000)) - .chain([ts(5_000_000)]) - .collect(); - assert_eq!(read, expected, "sixth group open: {open}"); - } - } - // ---- Malformed rewind ---- /// The track refuses a group whose first frame rewinds, but not a later frame that does, @@ -3650,14 +3523,13 @@ mod tests { ); // Group 9 pushes the newest content a full budget past what group 5 could still - // present (bounded by group 7's start), expiring it. Exactly a budget, so group 7's - // first frame is not past it and the start stays there. - write_group(&mut track, 9, &[ts(710_000)]); + // present (bounded by group 7's start), expiring it. + write_group(&mut track, 9, &[ts(800_000)]); track.finish().unwrap(); let frames = read_all(&mut consumer).await.unwrap(); let micros: Vec = frames.iter().map(|f| f.timestamp.as_micros()).collect(); - assert_eq!(micros, vec![210_000, 710_000], "the expired frameless group is skipped"); + assert_eq!(micros, vec![210_000, 800_000], "the expired frameless group is skipped"); } /// An aborted frameless group beyond a sequence gap is reaped rather than parked on @@ -3925,9 +3797,6 @@ mod tests { ) .unwrap(); - // Read before group 1 lands, so the skip comes after the start. - assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); - // Group 1: finished, 200ms ahead (well beyond the 100ms max delay) write_group(&mut track, 1, &[ts(200_000)]); track.finish().unwrap(); @@ -3938,7 +3807,7 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 1, "Expected group 1's frame after group 0's"); + assert_eq!(frames.len(), 2, "Expected group 0 frame + group 1 frame"); finisher.await.unwrap(); } @@ -3952,15 +3821,14 @@ mod tests { let consumer_track = track.subscribe(None); let mut consumer = container_max_delay_only(consumer_track, Duration::from_millis(100)); - // Group 0: finished normally, its first frame read before group 2 lands. + // Group 0: finished normally write_group(&mut track, 0, &[ts(0), ts(20_000)]); - assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); // Group 2: finished (group 1 is missing — sequence gap) write_group(&mut track, 2, &[ts(200_000)]); track.finish().unwrap(); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 2, "Expected group 0's second frame + group 2 (1 frame)"); + assert_eq!(frames.len(), 3, "Expected group 0 (2 frames) + group 2 (1 frame)"); } #[tokio::test] From 7f681fa8081006a8a43d4701972c88b2b092914d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 14:47:54 -0800 Subject: [PATCH 4/7] fix(mux,hang): a backlog join starts within the max delay in Rust and JS The maintainer picked option A on 2026-11-01: a backlog join takes JS's first-frame measure at the start, so it begins within the budget, with moq-dev/moq#7311's warmup protection. Until the first item, both container consumers move the start past each group whose first frame trails the newest content by more than the max delay plus the warmup, unless that group covers the live edge less the min delay and the warmup. The quest's scenario (five one-second groups and a sixth at 5 s, 1.5 s budget) now starts at the 4 s group in both; #7311 had moved JS to the 3 s group and Rust still played from 0. - Rust: a start skip in Consumer::poll_event_once, with the skip and lookahead loops factored into skip_to, poll_next_group, poll_newest. - JS: #checkMaxDelay keeps only the group covering the start's target before the first item; after it, #7311's warming rule is unchanged. - Paired tests: a_buffered_backlog_starts_within_the_budget and the_start_keeps_a_group_that_began_before_the_reach_but_covers_it in Rust, matching consumer.skips.test.ts and consumer.warmup.test.ts. - Eight moq-mux tests that wrote a backlog before the first read now read first, and moq-video's tail-drain test uses a budget past its backlog. - Delete the finished quest quest/m1/cut-audit/catalog-parity.md. Co-Authored-By: Claude Opus 5.5 --- doc/lib/rs/hang.md | 4 +- js/hang/MIGRATE.md | 2 +- js/hang/src/container/consumer.skips.test.ts | 41 +++ js/hang/src/container/consumer.ts | 20 +- quest/m1/cut-audit/README.md | 1 - quest/m1/cut-audit/catalog-parity.md | 73 ----- rs/moq-mux/CHANGELOG.md | 1 + rs/moq-mux/MIGRATE.md | 2 +- rs/moq-mux/src/container/consumer.rs | 323 ++++++++++++++----- rs/moq-video/src/decode/consumer.rs | 5 +- 10 files changed, 317 insertions(+), 155 deletions(-) delete mode 100644 quest/m1/cut-audit/catalog-parity.md diff --git a/doc/lib/rs/hang.md b/doc/lib/rs/hang.md index d56435f89b7..1350f66a161 100644 --- a/doc/lib/rs/hang.md +++ b/doc/lib/rs/hang.md @@ -27,7 +27,9 @@ the live edge to play: it skips groups that fall past `max`, and starts at the group covering the live edge less `min` (your playout delay), plus a rendition's catalog `warmup` passed to `with_warmup`, waiting up to that long for it when the newest group arrives first. Both default to zero, which starts at the newest -group at once; `max` never moves the start. +group at once. A backlog that landed before the first read starts within `max` +of the newest content, keeping the group covering the live edge less `min` and +the warmup. [`moq-video`](/lib/rs/moq-video) and [`moq-audio`](/lib/rs/moq-audio) publish from a device. Examples: [`video.rs`](https://github.com/moq-dev/moq/blob/main/rs/hang/examples/video.rs) diff --git a/js/hang/MIGRATE.md b/js/hang/MIGRATE.md index ba441db6466..c54c268de42 100644 --- a/js/hang/MIGRATE.md +++ b/js/hang/MIGRATE.md @@ -8,7 +8,7 @@ How to update your code for each breaking change, newest first. `ConsumerProps.maxDelay` is `delay: GetterInit`, where `Delay` is `{ min?: Milli; max?: Milli | null }` and an omitted field is zero. Replace `maxDelay: d` with `delay: { max: d }`, or derive it from a signal. `max: null` is no limit. -`min` is the playout delay: the consumer starts at the group covering the live edge less `min` plus any `warmup`, waiting for it when the newest group arrives first. `max` never moves the start. +`min` is the playout delay: the consumer starts at the group covering the live edge less `min` plus any `warmup`, waiting for it when the newest group arrives first. Before the first read, a backlog that already landed starts at the first group whose first frame is within `max`, plus the warmup, of the newest content, keeping the group covering the live edge less `min` and the warmup. ### The catalog rendition cap is removed diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index 33a29afae63..266645272f8 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -50,3 +50,44 @@ for (const count of [1, 16, 256]) { } }); } + +// Pairs `rs/moq-mux`'s `a_buffered_backlog_starts_within_the_budget`: a backlog that lands whole before +// the first read starts at the first group whose first frame is within the budget of the newest one. +// Five one-second groups of ten frames and a one-frame sixth at 5 s, with a 1.5 s budget, start at the +// 4 s group, whether the sixth is open or finished. +for (const open of [true, false]) { + test(`a buffered backlog starts within the budget (sixth group ${open ? "open" : "finished"})`, async () => { + const warn = spyOn(console, "warn").mockImplementation(() => {}); + const track = new Track.Producer("backlog"); + const consumer = new Consumer(track.subscribe({ maxDelay: Milli(30_000) }), { + format: new Format("data"), + delay: { max: Milli(1500) }, + }); + const frame = (micros: number) => ({ payload: Varint.encode(micros), timestamp: Time.Timestamp.now() }); + try { + for (let g = 0; g < 5; g++) { + const group = track.createGroup(g); + for (let f = 0; f < 10; f++) group.writeFrame(frame(g * 1_000_000 + f * 100_000)); + group.finish(); + } + const last = track.createGroup(5); + last.writeFrame(frame(5_000_000)); + if (!open) last.finish(); + while (consumer.buffered.peek().at(-1)?.end !== 5000) await consumer.buffered.changed(); + + const read: number[] = []; + for (let i = 0; i < 11; i++) { + const next = await consumer.next(); + if (next?.kind !== "frame") throw new Error(`unexpected read: ${JSON.stringify(next)}`); + read.push(next.frame.timestamp); + } + const expected = [...Array.from({ length: 10 }, (_, f) => 4_000_000 + f * 100_000), 5_000_000]; + expect(read).toEqual(expected); + } finally { + consumer.close(); + track.finish(); + track.close(); + warn.mockRestore(); + } + }); +} diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index d89bfae392d..2836e9c254a 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -23,7 +23,9 @@ export interface Delay { * late group is waited for. A missing sequence also expires this much monotonic time after * the first group past it arrived, even when the next group is a marker on a paused track. * The local half of the subscription's `maxDelay`; both measure the same budget, one on the wire - * and one as frames are read. It bounds lateness only: it never moves the start. + * and one as frames are read. It bounds a join's lateness too: a backlog that landed before the + * first read starts at the first group whose first frame is within it, plus any warmup, of the + * newest content, though the start keeps the group covering the live edge less `min` and the warmup. */ max?: Milli | null; } @@ -511,11 +513,21 @@ export class Consumer { const age = max - min; if (age <= threshold) break; - // Until the reader warms, a group may cover the start's reach though it began before it: it is - // stale only once its successor starts a whole budget behind the newest content. + // Until the reader warms, a group may cover the start's reach though it began before it. if (this.#warming()) { const nextStart = this.#groups[1].start; - if (nextStart === undefined || max - nextStart < threshold) break; + if (nextStart === undefined) break; + if (this.#edge === undefined) { + // Before the first item, a backlog that landed whole starts within the budget, so only + // the group covering the live edge less the reach is kept: one whose successor starts + // past that point. Rust's start skip, in `Consumer::poll_event_once`, measures the same. + const target = this.#startTarget(this.#reach(this.#delay.peek())); + if (target !== undefined && nextStart > target) break; + } else if (max - nextStart < threshold) { + // Once reading began, it is stale only once its successor starts a whole budget behind + // the newest content. + break; + } } this.#groups.shift(); diff --git a/quest/m1/cut-audit/README.md b/quest/m1/cut-audit/README.md index 7b71567913c..c944b27ed38 100644 --- a/quest/m1/cut-audit/README.md +++ b/quest/m1/cut-audit/README.md @@ -54,7 +54,6 @@ leaving JS-only redesigns of `js/net` to [rs2ts](/quest/m2/rs2ts-js.md). ## Required -- [Rust and JS skip a backlog by the same measure](/quest/m1/cut-audit/catalog-parity.md) - a backlog join starts at the same group in every player - [Text and data sections keep a prototype-named ID](/quest/m1/cut-audit/catalog-proto-ids.md) - text and data entries keep the ID JS's `z.record` drops ## Related diff --git a/quest/m1/cut-audit/catalog-parity.md b/quest/m1/cut-audit/catalog-parity.md deleted file mode 100644 index 3ebd3319c38..00000000000 --- a/quest/m1/cut-audit/catalog-parity.md +++ /dev/null @@ -1,73 +0,0 @@ -# [S] Rust and JS skip a backlog by the same measure - -## Goal - -A player joining a backlog starts at the same group in moq-cli, moqsrc, and -the browser. If they start at different groups, align the two container -consumers' skip measurements, with a test in each. - -## Plan - -Found by the 2026-10-24 pre-cut audit at 151a529670. The catalog half of -this quest (Rust and JS accept the same catalogs) landed separately in -[moq-dev/moq#7035](https://github.com/moq-dev/moq/pull/7035): any malformed -rendition refuses the whole catalog in both languages (maintainer, -2026-10-30). - -Rust measures newest content minus the next group's start -(`rs/moq-mux/src/container/consumer.rs`, the `should_skip` check in the -blocking-group path). JS measures from the oldest unread frame -(`js/hang/src/container/consumer.ts`, `#checkMaxDelay`). The Rust comment -argues for its measure: a group's own first frame is no bound, since a group -longer than the budget would be cut short whenever it blocks behind a newer -one, as a join's backlog does. - -They diverge, reproduced by a throwaway probe in each consumer: five -finished one-second groups of ten frames plus a one-frame sixth group, all -landing before the first read, with a 1500 ms budget. JS starts at the 4.0 s -group, while Rust starts at 0 and plays the whole backlog, whether the sixth -group is open or finished. Rust's skip only runs while the current group -blocks, so a fully buffered backlog never triggers it. - -What the 2026-11-01 attempt -([moq-dev/moq#7518](https://github.com/moq-dev/moq/pull/7518)) found, with -prototypes on main at `a3440aa239`: - -- Rust's measure is the wire's: `Subscription::max_delay` in moq-net and - `#staleAt` in js/net judge a group by its reach, where its successor - begins. By reach the scenario starts at the 3.0 s group, so neither - consumer's start matches the other's or the wire's. -- The reach is a transport measure: a backlog bursts faster than real time, - so trailing is survivable there. A player plays a buffered backlog at real - time, so a reach start trails by up to the budget plus one group, and Rust - never catches up, since it skips only a blocking group. -- Skipping buffered groups at any time, not only at the start, changes - steady-state behavior that other code relies on. 12 moq-mux tests fail, - including TS release and export tests whose own deadline accounting - expects the consumer to never drop a frame it already buffered. -- Restricting it to the start, until the first item is read, leaves the - steady state alone: - - **JS's first-frame measure at the start** (prototype in - [786c325f0c](https://github.com/moq-dev/moq/commit/786c325f0cd3bee159575198ea5557d52e83f142)): - both start at 4.0 s. Eight moq-mux tests that wrote a backlog before - the first read need to read first. Two moq-video dual-decoder tests - break (`the_tail_drains_from_both_decoders`, - `a_max_delay_decode_error_fails_the_read`): the warmup decoder's earlier - group is fresh by its reach, but its first frame trails the newest by - more than max + warmup, so the start drops the group the warmup needs. - [moq-dev/moq#7311](https://github.com/moq-dev/moq/pull/7311) adds the - container `with_warmup` and, in JS, keeps the group covering the start's - reach through the warmup. The Rust start needs the same protection. - - **The reach at the start in both**: both start at 3.0 s. Rust passes - moq-mux, moq-video, and moq-audio with the same eight test edits. JS's - `#checkMaxDelay` changes to the reach, which fails two existing hang - tests (`Consumer raises a malformed group an age skip passes after the - track finished`, `Consumer reads a gap when retiring an open group`). - -Pending the maintainer's pick (see the PR's `## Decisions needed`), the -recommendation is JS's measure at the start, landed after -[moq-dev/moq#7311](https://github.com/moq-dev/moq/pull/7311), with the Rust -start keeping the group covering the start's reach through the warmup as -that PR's JS does. Keep the scenario as a paired test in both (the -prototype's `a_buffered_backlog_starts_within_the_budget` and -`consumer.skips.test.ts` case). diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index a850cefe1a5..b2e93a15cb5 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- `container::Consumer` no longer plays a backlog that landed before its first read from the oldest group: until the first item, the start moves past each group whose first frame trails the newest content by more than the max delay plus the warmup, as `@moq/hang`'s consumer does, keeping the group covering the live edge less `Delay::min` and the warmup. A join starts at the same group in Rust and the browser. Once reading begins, only a blocking group is skipped, as before. - fMP4 import applies each track's edit list to its frame timestamps and drops the samples before the edit, such as AAC priming, along with the video samples decoding from a dropped sync sample, and a passthrough init no longer carries the `edts`. A consumer that offsets AAC priming itself must stop, or it shifts the track twice. An edit list it can't reduce to one shift (several media edits, or a rate other than 1) is refused with `Error::UnsupportedEditList`. ## [0.10.11](https://github.com/moq-dev/moq/compare/moq-mux-v0.10.10...moq-mux-v0.10.11) - 2026-10-05 diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index 9abb9fd4679..92d25498a72 100644 --- a/rs/moq-mux/MIGRATE.md +++ b/rs/moq-mux/MIGRATE.md @@ -8,7 +8,7 @@ How to update your code for each breaking change, newest first. `container::Consumer::set_max_delay(Duration)` is `set_delay(Delay)`, and `with_delay(Delay)` is its builder. `container::Delay { min, max }` defaults to zero for both: `max` (`None` for no limit) is the max delay that `set_max_delay` took, and the subscription still carries it. -`min` is the playout delay. An unfloored consumer starts at the group covering the live edge less `min` plus any `with_warmup`, waiting for it when the newest group arrives first; the max delay never moves the start. +`min` is the playout delay. An unfloored consumer starts at the group covering the live edge less `min` plus any `with_warmup`, waiting for it when the newest group arrives first. Before the first read, a backlog that already landed starts at the first group whose first frame is within the max delay, plus the warmup, of the newest content, keeping the group covering the live edge less `min` and the warmup. Replace `consumer.set_max_delay(d)` with `consumer.set_delay(Delay { max: Some(d), ..Delay::default() })`, and set `min` to your playout delay. Call `with_warmup` before `with_delay`. ### Compression moves to the track diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 2481abd1063..4e98574b010 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -75,7 +75,11 @@ pub(crate) enum Item { /// [`Subscription::ranges`](moq_net::track::Subscription::ranges) when every range names one, waiting for that group under the budget; without one it /// starts at the lowest group that arrived, waiting for one covering the live edge less /// [`Delay::min`] plus any [`with_warmup`](Self::with_warmup). Both default to zero, so it waits -/// for nothing. The max delay never moves the start. From there +/// for nothing. Until the first item, the start also moves past each group whose first frame +/// trails the newest content by more than the max delay plus the warmup, as `@moq/hang`'s +/// consumer measures, unless that group covers the live edge less the min delay and the warmup: +/// a backlog that landed whole would otherwise play from its oldest group, since nothing +/// blocks, and stay that far behind. From there /// the same budget is the one rule that catches the consumer up to the live edge, and /// history the publisher no longer serves expires like any other gap, since its reach /// sits a full budget behind the newest content. @@ -220,8 +224,10 @@ pub struct Delay { pub min: std::time::Duration, /// How far a group may fall behind the live edge before it is skipped, or `None` for no limit. /// - /// The subscription carries it as [`moq_net::track::Subscription::max_delay`]. It bounds - /// lateness only: it never moves the start. + /// The subscription carries it as [`moq_net::track::Subscription::max_delay`]. It bounds a + /// join's lateness too: a backlog that landed before the first read starts at the first group + /// whose first frame is within it, plus any warmup, of the newest content, though the start + /// keeps the group covering the live edge less [`min`](Self::min) and the warmup. pub max: Option, } @@ -562,6 +568,15 @@ impl Consumer { self.hole_timer = None; } + // Until the first item, a backlog that landed whole starts within the budget: nothing + // blocks, so the skip below would play it from its oldest group and stay that far behind + // for good. The start moves past each group whose first frame trails the newest content + // by more than the budget, as `@moq/hang`'s consumer measures, unless that group covers + // the live edge less the reach (see `with_warmup`), which the start promises. + if self.edge.is_none() && self.start_skip(waiter)? { + continue; + } + // Return the next frame from the current group if possible. // If the current group is finished or errored, advance to the next group. if let Some(group) = self.pending.front_mut() @@ -681,31 +696,10 @@ impl Consumer { None }; - // Find the first newer group with data (our skip target) and where it starts. - let mut next_group = None; - for (i, group) in self.pending.iter_mut().enumerate() { - if group.sequence <= self.current { - continue; - } - - if let Poll::Ready(Some(ts)) = group.poll_min_timestamp(waiter, &self.format, false) { - next_group = Some((i, std::time::Duration::from(ts))); - break; - } - } - - // Find the max timestamp across all newer groups. - let mut max_timestamp = std::time::Duration::ZERO; - for group in self.pending.iter_mut().rev() { - if group.sequence <= self.current { - break; - } - - if let Poll::Ready(Some(ts)) = group.poll_max_timestamp(waiter, &self.format) { - max_timestamp = max_timestamp.max(ts.into()); - break; // We know older groups won't be newer than this. - } - } + // The first newer group with data (our skip target) and where it starts, and the newest + // content past the cursor. + let next_group = self.poll_next_group(waiter); + let max_timestamp = self.poll_newest(waiter); // Walk the cursor over missing sequences below the first arrived group. // Groups race on independent QUIC streams (newer ones at higher priority), @@ -762,9 +756,9 @@ impl Consumer { // The current group is blocking. Everything it could still present ends // where the next group begins, so skip once that reach falls a full budget // behind the newest content, the same measure as a missing group. Its own - // first frame is no bound: a group longer than the budget would be cut - // short whenever it blocks behind a newer one, as a join's backlog does - // while the newer groups race ahead on their own streams. Skip early too + // first frame is no bound once reading began: a group longer than the budget + // would be cut short whenever it blocks behind a newer one racing ahead on its + // own stream. Only the start, above, measures the first frame. Skip early too // once it has presented up to where the next group begins (duration // coverage), since nothing is left worth waiting for. // While the reader warms, the start reached the warmup further back than the max delay. @@ -789,26 +783,7 @@ impl Consumer { }; if let Some((new_idx, next_start)) = target { - // Without a start read yet, nothing proves the timeline continues. - let hole = next_start.is_none_or(|start| !pts_contiguous(current_end.or(self.presented_end), start)); - let had_marker = self.pending.iter().take(new_idx).any(GroupBuffer::marker); - // Buffered frames are thrown away, and `current_end` counts them, so contiguity alone would hide them. - let discarded = self - .pending - .iter() - .take(new_idx) - .any(|group| !group.buffered.is_empty()); - let target = self.pending[new_idx].sequence; - self.discard(|group| group.sequence < target)?; - if hole || had_marker || discarded { - self.lose(); - } - let new_current = self.pending.front().map(|g| g.sequence).unwrap(); - - tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); - - self.current = new_current; - self.note_group_edge(); + self.skip_to(new_idx, next_start, current_end)?; continue; } @@ -825,6 +800,99 @@ impl Consumer { } } + // Before the first item, move the cursor past its group when that group's first frame trails the + // newest content by more than the budget and the next group with data still starts at or before + // the live edge less the reach, so it is not what the start covers. Returns whether it moved. + fn start_skip(&mut self, waiter: &kio::Waiter) -> Result { + let Some(group) = self.pending.front_mut() else { + return Ok(false); + }; + if group.sequence > self.current { + return Ok(false); + } + let _ = group.poll_min_timestamp(waiter, &self.format, true); + let Some((frame, ..)) = group.buffered.front() else { + return Ok(false); + }; + let first = std::time::Duration::from(frame.timestamp); + let current_end = group.max_end; + let Some((idx, next_start)) = self.poll_next_group(waiter) else { + return Ok(false); + }; + let newest = self.poll_newest(waiter); + // Nothing has been read, so the reader still warms. + if newest.saturating_sub(first) <= self.max_delay.saturating_add(self.warmup) { + return Ok(false); + } + // The group the start reaches back to is kept: the next one begins past that point. + let reach = self.min_delay.min(self.max_delay).saturating_add(self.warmup); + if !reach.is_zero() && next_start > newest.saturating_sub(reach) { + return Ok(false); + } + self.skip_to(idx, Some(next_start), current_end)?; + Ok(true) + } + + // The first group past the cursor with a timestamp, the skip target, and where it starts. + fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Option<(usize, std::time::Duration)> { + for (i, group) in self.pending.iter_mut().enumerate() { + if group.sequence <= self.current { + continue; + } + + if let Poll::Ready(Some(ts)) = group.poll_min_timestamp(waiter, &self.format, false) { + return Some((i, ts.into())); + } + } + None + } + + // The max timestamp across the groups past the cursor, or zero without one. + fn poll_newest(&mut self, waiter: &kio::Waiter) -> std::time::Duration { + for group in self.pending.iter_mut().rev() { + if group.sequence <= self.current { + break; + } + + // Older groups won't be newer than this. + if let Poll::Ready(Some(ts)) = group.poll_max_timestamp(waiter, &self.format) { + return ts.into(); + } + } + std::time::Duration::ZERO + } + + // Move the cursor to the pending group at `new_idx`, dropping what lies below it. `next_start` is + // where that group begins, if read, and `current_end` how far the group left behind presented. + fn skip_to( + &mut self, + new_idx: usize, + next_start: Option, + current_end: Option, + ) -> Result<(), F::Error> { + // Without a start read yet, nothing proves the timeline continues. + let hole = next_start.is_none_or(|start| !pts_contiguous(current_end.or(self.presented_end), start)); + let had_marker = self.pending.iter().take(new_idx).any(GroupBuffer::marker); + // Buffered frames are thrown away, and `current_end` counts them, so contiguity alone would hide them. + let discarded = self + .pending + .iter() + .take(new_idx) + .any(|group| !group.buffered.is_empty()); + let target = self.pending[new_idx].sequence; + self.discard(|group| group.sequence < target)?; + if hole || had_marker || discarded { + self.lose(); + } + let new_current = self.pending.front().map(|g| g.sequence).unwrap(); + + tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); + + self.current = new_current; + self.note_group_edge(); + Ok(()) + } + // Where an unfloored start begins, the lowest group that arrived, or `None` while it waits for // one covering the reach (see `with_warmup`), registering the waiter on whatever would end the wait. fn reach_start(&mut self, waiter: &kio::Waiter, finished: bool) -> Option { @@ -1970,10 +2038,23 @@ mod tests { track.subscribe(moq_net::track::Subscription::default().with_max_delay(Duration::from_secs(10))); let mut reader = Consumer::new(subscription, Container::Legacy(crate::container::Kind::Audio)); reader.max_delay = Duration::ZERO; - write_group(&mut track, 0, &[ts(0)]); + // Group 0 stays open, and is read before the newer group lands: the skip comes after the start. + let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); + Container::Legacy(crate::container::Kind::Audio) + .write( + &mut group, + &[Frame { + timestamp: ts(0), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + assert!(matches!(reader.read().await.unwrap(), Some(Read::Frame { .. }))); write_group(&mut track, 3, &[ts(1_000_000)]); track.finish().unwrap(); - assert_eq!(items(&mut reader).await, ["0", "gap 0+1000000", "1000000"]); + assert_eq!(items(&mut reader).await, ["gap 0+1000000", "1000000"]); } /// A video group's trailing duration marker is that frame's end, not a declared stop. @@ -2120,11 +2201,24 @@ mod tests { // Keep transport filtering out of this test so it isolates the mux skip logic. consumer.max_delay = Duration::ZERO; - write_group(&mut track, 0, &[ts(0)]); + // Group 0 stays open, and is read before the newer group lands: the skip comes after the start. + let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); + Container::Legacy(crate::container::Kind::Audio) + .write( + &mut group, + &[Frame { + timestamp: ts(0), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + assert!(matches!(consumer.read().await.unwrap(), Some(Read::Frame { .. }))); write_group(&mut track, 3, &[ts(1_000_000)]); track.finish().unwrap(); - assert_eq!(items(&mut consumer).await, ["0", "gap 0+1000000", "1000000"]); + assert_eq!(items(&mut consumer).await, ["gap 0+1000000", "1000000"]); } #[tokio::test] @@ -2230,6 +2324,11 @@ mod tests { ) .unwrap(); + // Read group 0's frame before the later groups land, so they skip a stalled group rather + // than move the start. + let first = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(first.timestamp, ts(0)); + for g in 1..10u64 { let timestamps: Vec<_> = (0..3).map(|f| ts(g * 50_000 + f * 5_000)).collect(); write_group(&mut track, g, ×tamps); @@ -2242,7 +2341,7 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 28, "Expected group 0 frame + groups 1-9"); + assert_eq!(frames.len(), 27, "Expected groups 1-9 after group 0's frame"); assert!(!frames.is_empty(), "Expected at least some frames"); finisher.await.expect("finisher task panicked"); } @@ -2267,6 +2366,11 @@ mod tests { ) .unwrap(); + // Read group 0's frame before the later groups land, so they skip a stalled group rather + // than move the start. + let first = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(first.timestamp, ts(0)); + for g in 1..10u64 { write_group(&mut track, g, &[ts(g * 30_000)]); } @@ -2278,20 +2382,17 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert!(!frames.is_empty(), "Expected at least some frames"); - assert_eq!(frames.len(), 10, "Expected group 0 frame + groups 1-9"); - assert_eq!(frames[0].timestamp, ts(0)); - - for i in 1..10u64 { - assert_eq!(frames[i as usize].timestamp, ts(i * 30_000)); + assert_eq!(frames.len(), 9, "Expected groups 1-9 after group 0's frame"); + for (i, frame) in (1..10u64).zip(&frames) { + assert_eq!(frame.timestamp, ts(i * 30_000)); } finisher.await.expect("finisher task panicked"); } /// A group longer than the budget that blocks for a moment behind a newer group is /// not cut short while what it could still present (up to where the newer group - /// begins) is within the budget. A join's backlog does exactly this: the newer group - /// races ahead on its own stream while the older one is still arriving. + /// begins) is within the budget: the newer group races ahead on its own stream while + /// the older one is still arriving. #[test] fn a_long_group_blocked_behind_a_newer_one_is_not_cut_short() { let waiter = kio::Waiter::noop(); @@ -2317,15 +2418,17 @@ mod tests { } }; - // A 2.5 s group, half arrived, and the next one already 0.5 s in. + // A 2.5 s group, half arrived, and the next one already 0.5 s in. The reader started + // before the next one landed, so this is a stall, not a join's backlog, which starts + // within the budget instead (see `a_buffered_backlog_starts_within_the_budget`). let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); write(&mut group0, ts(0)); write(&mut group0, ts(500_000)); + assert_eq!(read(&mut consumer), Some(ts(0))); let mut group1 = track.create_group(moq_net::group::Info { sequence: 1 }).unwrap(); write(&mut group1, ts(2_500_000)); write(&mut group1, ts(3_000_000)); - assert_eq!(read(&mut consumer), Some(ts(0))); assert_eq!(read(&mut consumer), Some(ts(500_000))); // Group 0's reach (2.5 s) is 0.5 s behind the newest frame: wait for it. assert_eq!(read(&mut consumer), None, "cut group 0 short"); @@ -2344,6 +2447,52 @@ mod tests { group2.finish().unwrap(); } + /// A backlog that lands whole before the first read starts at the first group whose first + /// frame is within the budget of the newest one, though nothing blocks. Five one-second + /// groups of ten frames and a one-frame sixth at 5 s, with a 1.5 s budget, start at the 4 s + /// group, whether the sixth is open or finished. `js/hang`'s `consumer.skips.test.ts` pairs + /// this case. + #[test] + fn a_buffered_backlog_starts_within_the_budget() { + for open in [true, false] { + let waiter = kio::Waiter::noop(); + let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let mut consumer = container_max_delay_only(track.subscribe(None), Duration::from_millis(1500)); + for g in 0..5u64 { + let timestamps: Vec<_> = (0..10).map(|f| ts(g * 1_000_000 + f * 100_000)).collect(); + write_group(&mut track, g, ×tamps); + } + let mut last = track.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); + Container::Legacy(crate::container::Kind::Data) + .write( + &mut last, + &[Frame { + timestamp: ts(5_000_000), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + if !open { + last.finish().unwrap(); + } + + let mut read = Vec::new(); + while let Poll::Ready(Ok(Some(item))) = consumer.poll_read(&waiter) { + match item { + Read::Frame { frame, .. } => read.push(frame.timestamp), + other => panic!("unexpected read: {other:?}"), + } + } + let expected: Vec<_> = (0..10) + .map(|f| ts(4_000_000 + f * 100_000)) + .chain([ts(5_000_000)]) + .collect(); + assert_eq!(read, expected, "sixth group open: {open}"); + } + } + // ---- Malformed rewind ---- /// The track refuses a group whose first frame rewinds, but not a later frame that does, @@ -3272,6 +3421,31 @@ mod tests { assert_eq!(micros, vec![4_950_000, 5_000_000], "the warmup is not skipped as stale"); } + /// The start keeps the group covering the reach though its first frame trails the newest + /// content by more than the max delay plus the warmup. `js/hang`'s + /// `consumer.warmup.test.ts` pairs this case. + #[tokio::test] + async fn the_start_keeps_a_group_that_began_before_the_reach_but_covers_it() { + tokio::time::pause(); + let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let mut consumer = reach_consumer( + &mut track, + Duration::from_millis(200), + Duration::from_millis(200), + Duration::from_millis(300), + ); + + write_group(&mut track, 5, &[ts(5_000_000)]); + // Group 4 begins 600ms before the newest content, past the 500ms reach, yet covers its 4.5s target. + write_group(&mut track, 4, &[ts(4_400_000), ts(4_600_000), ts(4_900_000)]); + let frame = kio::clock::timeout(Duration::from_millis(50), consumer.read_frame()) + .await + .expect("group 4 covers the reach") + .unwrap() + .unwrap(); + assert_eq!(frame.timestamp, ts(4_400_000)); + } + /// The warmup is carved out of the requested budget before the retention clamp, so a max delay /// the track can keep stays whole. #[tokio::test] @@ -4104,13 +4278,14 @@ mod tests { ); // Group 9 pushes the newest content a full budget past what group 5 could still - // present (bounded by group 7's start), expiring it. - write_group(&mut track, 9, &[ts(800_000)]); + // present (bounded by group 7's start), expiring it. Exactly a budget, so group 7's + // first frame is not past it and the start stays there. + write_group(&mut track, 9, &[ts(710_000)]); track.finish().unwrap(); let frames = read_all(&mut consumer).await.unwrap(); let micros: Vec = frames.iter().map(|f| f.timestamp.as_micros()).collect(); - assert_eq!(micros, vec![210_000, 800_000], "the expired frameless group is skipped"); + assert_eq!(micros, vec![210_000, 710_000], "the expired frameless group is skipped"); } /// An aborted frameless group beyond a sequence gap is reaped rather than parked on @@ -4378,6 +4553,9 @@ mod tests { ) .unwrap(); + // Read before group 1 lands, so the skip comes after the start. + assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); + // Group 1: finished, 200ms ahead (well beyond the 100ms max delay) write_group(&mut track, 1, &[ts(200_000)]); track.finish().unwrap(); @@ -4388,7 +4566,7 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 2, "Expected group 0 frame + group 1 frame"); + assert_eq!(frames.len(), 1, "Expected group 1's frame after group 0's"); finisher.await.unwrap(); } @@ -4402,14 +4580,15 @@ mod tests { let consumer_track = track.subscribe(None); let mut consumer = container_max_delay_only(consumer_track, Duration::from_millis(100)); - // Group 0: finished normally + // Group 0: finished normally, its first frame read before group 2 lands. write_group(&mut track, 0, &[ts(0), ts(20_000)]); + assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); // Group 2: finished (group 1 is missing — sequence gap) write_group(&mut track, 2, &[ts(200_000)]); track.finish().unwrap(); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 3, "Expected group 0 (2 frames) + group 2 (1 frame)"); + assert_eq!(frames.len(), 2, "Expected group 0's second frame + group 2 (1 frame)"); } #[tokio::test] diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index 32deba77a08..70b285e6889 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -1390,8 +1390,9 @@ mod tests { group(&mut track, 1, &[4, 5]).finish().unwrap(); track.finish().unwrap(); - // A budget that keeps every cached group, so both decoders read them all. - let mut consumer = dual(&broadcast, Start::Oldest, WARMUP, probe::BUFFERED_NAME).await; + // A budget past the whole 5 s backlog, so the start keeps every cached group and both + // decoders read them all. + let mut consumer = dual(&broadcast, Start::Oldest, 2 * WARMUP, probe::BUFFERED_NAME).await; let mut shown = Vec::new(); while let Some(frame) = consumer.next_frame().await.unwrap() { shown.push(u64::try_from(frame.timestamp.as_micros()).unwrap() / SECOND); From e9ca4d0e19905fadeb84cd7ceaddf993b9d3a1cc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:39:58 -0800 Subject: [PATCH 5/7] fix(mux): a backlog start waits on its next group's first frame The start skip targeted the first later group with a frame, so a group that had arrived with its first frame still in flight was skipped and discarded, even when that frame would land within the budget. It now looks only at the cursor's immediate successor and skips nothing until that group's start is known, as @moq/hang's consumer waits on its successor's start. Paired tests in Rust and JS cover the case; the Rust one drops the whole fifth group without the fix. Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.skips.test.ts | 48 ++++++++++++++++ rs/moq-mux/src/container/consumer.rs | 60 +++++++++++++++++++- 2 files changed, 105 insertions(+), 3 deletions(-) diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index 266645272f8..a7316087d1b 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -91,3 +91,51 @@ for (const open of [true, false]) { } }); } + +// The start waits on the next group's first frame, which may land within the budget, rather than +// dropping that group. Here the fifth group (4 s) arrived with its frames still in flight, so the start +// keeps the fourth and plays on into the fifth. Rust's +// `a_backlog_start_waits_on_a_successor_without_frames` pairs this case. +test("a backlog start waits on a successor without frames", async () => { + const warn = spyOn(console, "warn").mockImplementation(() => {}); + const track = new Track.Producer("backlog"); + const consumer = new Consumer(track.subscribe({ maxDelay: Milli(30_000) }), { + format: new Format("data"), + delay: { max: Milli(1500) }, + }); + const frame = (micros: number) => ({ payload: Varint.encode(micros), timestamp: Time.Timestamp.now() }); + const frames = (g: number) => Array.from({ length: 10 }, (_, f) => g * 1_000_000 + f * 100_000); + const read: number[] = []; + const readN = async (n: number) => { + for (let i = 0; i < n; i++) { + const next = await consumer.next(); + if (next?.kind !== "frame") throw new Error(`unexpected read: ${JSON.stringify(next)}`); + read.push(next.frame.timestamp); + } + }; + try { + for (let g = 0; g < 4; g++) { + const group = track.createGroup(g); + for (const micros of frames(g)) group.writeFrame(frame(micros)); + group.finish(); + } + const fifth = track.createGroup(4); + // The fifth group's frames left before the sixth's, though they land after it. + const sent = Time.Timestamp.now(); + const last = track.createGroup(5); + last.writeFrame(frame(5_000_000)); + last.finish(); + while (consumer.buffered.peek().at(-1)?.end !== 5000) await consumer.buffered.changed(); + + await readN(10); + for (const micros of frames(4)) fifth.writeFrame({ payload: Varint.encode(micros), timestamp: sent }); + fifth.finish(); + await readN(11); + expect(read).toEqual([...frames(3), ...frames(4), 5_000_000]); + } finally { + consumer.close(); + track.finish(); + track.close(); + warn.mockRestore(); + } +}); diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 4e98574b010..1543fd011a5 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -801,8 +801,8 @@ impl Consumer { } // Before the first item, move the cursor past its group when that group's first frame trails the - // newest content by more than the budget and the next group with data still starts at or before - // the live edge less the reach, so it is not what the start covers. Returns whether it moved. + // newest content by more than the budget and the next group still starts at or before the live + // edge less the reach, so it is not what the start covers. Returns whether it moved. fn start_skip(&mut self, waiter: &kio::Waiter) -> Result { let Some(group) = self.pending.front_mut() else { return Ok(false); @@ -816,9 +816,17 @@ impl Consumer { }; let first = std::time::Duration::from(frame.timestamp); let current_end = group.max_end; - let Some((idx, next_start)) = self.poll_next_group(waiter) else { + // The next group that arrived, even one whose first frame is still in flight: that frame may + // land within the budget, so skipping on to a later group could drop the one the start + // belongs on. Until it lands, nothing is skipped, as `@moq/hang`'s consumer waits on its + // successor's start. + let Some(idx) = self.pending.iter().position(|group| group.sequence > self.current) else { return Ok(false); }; + let Poll::Ready(Some(next_start)) = self.pending[idx].poll_min_timestamp(waiter, &self.format, false) else { + return Ok(false); + }; + let next_start = std::time::Duration::from(next_start); let newest = self.poll_newest(waiter); // Nothing has been read, so the reader still warms. if newest.saturating_sub(first) <= self.max_delay.saturating_add(self.warmup) { @@ -2493,6 +2501,52 @@ mod tests { } } + /// A backlog join's start skip waits on the next group's first frame, which may land within the + /// budget, rather than skipping on to a later group with data and dropping it. Here the fifth + /// group (4.0 s) arrived with its frames still in flight, so the start keeps the fourth and + /// plays on into the fifth. `js/hang`'s `consumer.skips.test.ts` pairs this case. + #[test] + fn a_backlog_start_waits_on_a_successor_without_frames() { + let waiter = kio::Waiter::noop(); + let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let mut consumer = container_max_delay_only(track.subscribe(None), Duration::from_millis(1500)); + let frames = |g: u64| -> Vec<_> { (0..10).map(|f| ts(g * 1_000_000 + f * 100_000)).collect() }; + for g in 0..4u64 { + write_group(&mut track, g, &frames(g)); + } + let mut fifth = track.create_group(moq_net::group::Info { sequence: 4 }).unwrap(); + write_group(&mut track, 5, &[ts(5_000_000)]); + + let mut read = Vec::new(); + let mut drain = |consumer: &mut Consumer| { + while let Poll::Ready(Ok(Some(item))) = consumer.poll_read(&waiter) { + match item { + Read::Frame { frame, .. } => read.push(frame.timestamp), + other => panic!("unexpected read: {other:?}"), + } + } + }; + drain(&mut consumer); + for frame in frames(4) { + Container::Legacy(crate::container::Kind::Data) + .write( + &mut fifth, + &[Frame { + timestamp: frame, + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + } + fifth.finish().unwrap(); + drain(&mut consumer); + + let expected: Vec<_> = frames(3).into_iter().chain(frames(4)).chain([ts(5_000_000)]).collect(); + assert_eq!(read, expected); + } + // ---- Malformed rewind ---- /// The track refuses a group whose first frame rewinds, but not a later frame that does, From 5f06574a0908133be6473c8c310080db66880712 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:44:48 -0800 Subject: [PATCH 6/7] perf(mux): a skip drops only the pending prefix below its target skip_to discarded through `retain_mut`, which visits every pending group, so a start that skips a long backlog one group at a time was quadratic in one poll. `pending` is in sequence order, so the groups below the target are its prefix: `discard_front` drains just those, with the same fault check `discard` makes. Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/consumer.rs | 40 +++++++++++++++++++++------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 1543fd011a5..cdca87042eb 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -887,8 +887,8 @@ impl Consumer { .iter() .take(new_idx) .any(|group| !group.buffered.is_empty()); - let target = self.pending[new_idx].sequence; - self.discard(|group| group.sequence < target)?; + // `pending` is in sequence order, so what lies below the target is its prefix. + self.discard_front(new_idx)?; if hole || had_marker || discarded { self.lose(); } @@ -1097,17 +1097,37 @@ impl Consumer { return true; } if fault.is_none() { - fault = match (start, group.min_timestamp) { - (Some((prev, floor)), Some(min)) - if group.sequence > prev && min.as_micros() < floor.as_micros() => - { - Some(TimestampRewind { timestamp: min, floor }.into()) - } - _ => group.fault.take(), - }; + fault = Self::discard_fault(start, group); } false }); + self.discarded(fault) + } + + // `discard` of the lowest `count` pending groups, in time proportional to them rather than to every + // pending group, so a start that skips a long backlog one group at a time stays linear. + fn discard_front(&mut self, count: usize) -> Result<(), F::Error> { + let start = self.start; + let mut fault = None; + for mut group in self.pending.drain(..count) { + if fault.is_none() { + fault = Self::discard_fault(start, &mut group); + } + } + self.discarded(fault) + } + + // The fault a discarded group would hide: its own, or frames below the latest delivered start. + fn discard_fault(start: Option<(u64, Timestamp)>, group: &mut GroupBuffer) -> Option { + match (start, group.min_timestamp) { + (Some((prev, floor)), Some(min)) if group.sequence > prev && min.as_micros() < floor.as_micros() => { + Some(TimestampRewind { timestamp: min, floor }.into()) + } + _ => group.fault.take(), + } + } + + fn discarded(&self, fault: Option) -> Result<(), F::Error> { match fault { Some(err) => { tracing::warn!(track = &*self.name, error = ?err, "discarded a malformed group; ending the reader"); From 103e448a3752fc38efabf6d82581c774660b2dbf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:46:51 -0800 Subject: [PATCH 7/7] perf(mux): a backlog start reads the newest content once `start_skip` now walks the whole backlog in one call and reads the newest content once, rather than once per skipped group. Trailing groups whose frames are still in flight no longer make each skip rescan them. The newest content lies in the highest group with a timestamp, which a start skip never drops, so one read serves every skip. Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/consumer.rs | 76 +++++++++++++++------------- 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index cdca87042eb..13a04065fa5 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -802,43 +802,49 @@ impl Consumer { // Before the first item, move the cursor past its group when that group's first frame trails the // newest content by more than the budget and the next group still starts at or before the live - // edge less the reach, so it is not what the start covers. Returns whether it moved. + // edge less the reach, so it is not what the start covers, and repeat for the group it lands on. + // Returns whether it moved. fn start_skip(&mut self, waiter: &kio::Waiter) -> Result { - let Some(group) = self.pending.front_mut() else { - return Ok(false); - }; - if group.sequence > self.current { - return Ok(false); - } - let _ = group.poll_min_timestamp(waiter, &self.format, true); - let Some((frame, ..)) = group.buffered.front() else { - return Ok(false); - }; - let first = std::time::Duration::from(frame.timestamp); - let current_end = group.max_end; - // The next group that arrived, even one whose first frame is still in flight: that frame may - // land within the budget, so skipping on to a later group could drop the one the start - // belongs on. Until it lands, nothing is skipped, as `@moq/hang`'s consumer waits on its - // successor's start. - let Some(idx) = self.pending.iter().position(|group| group.sequence > self.current) else { - return Ok(false); - }; - let Poll::Ready(Some(next_start)) = self.pending[idx].poll_min_timestamp(waiter, &self.format, false) else { - return Ok(false); - }; - let next_start = std::time::Duration::from(next_start); - let newest = self.poll_newest(waiter); - // Nothing has been read, so the reader still warms. - if newest.saturating_sub(first) <= self.max_delay.saturating_add(self.warmup) { - return Ok(false); - } - // The group the start reaches back to is kept: the next one begins past that point. - let reach = self.min_delay.min(self.max_delay).saturating_add(self.warmup); - if !reach.is_zero() && next_start > newest.saturating_sub(reach) { - return Ok(false); + // The newest content lies in the highest group with a timestamp, which a skip never drops, so + // one read serves every skip and a long backlog is walked once. + let mut newest = None; + let mut moved = false; + while let Some(group) = self.pending.front_mut() { + if group.sequence > self.current { + break; + } + let _ = group.poll_min_timestamp(waiter, &self.format, true); + let Some((frame, ..)) = group.buffered.front() else { + break; + }; + let first = std::time::Duration::from(frame.timestamp); + let current_end = group.max_end; + // The next group that arrived, even one whose first frame is still in flight: that frame + // may land within the budget, so skipping on to a later group could drop the one the start + // belongs on. Until it lands, nothing is skipped, as `@moq/hang`'s consumer waits on its + // successor's start. + let Some(idx) = self.pending.iter().position(|group| group.sequence > self.current) else { + break; + }; + let Poll::Ready(Some(next_start)) = self.pending[idx].poll_min_timestamp(waiter, &self.format, false) + else { + break; + }; + let next_start = std::time::Duration::from(next_start); + let newest = *newest.get_or_insert_with(|| self.poll_newest(waiter)); + // Nothing has been read, so the reader still warms. + if newest.saturating_sub(first) <= self.max_delay.saturating_add(self.warmup) { + break; + } + // The group the start reaches back to is kept: the next one begins past that point. + let reach = self.min_delay.min(self.max_delay).saturating_add(self.warmup); + if !reach.is_zero() && next_start > newest.saturating_sub(reach) { + break; + } + self.skip_to(idx, Some(next_start), current_end)?; + moved = true; } - self.skip_to(idx, Some(next_start), current_end)?; - Ok(true) + Ok(moved) } // The first group past the cursor with a timestamp, the skip target, and where it starts.