From 6369e3615db112545d918c74548b04350685e7a6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 19:00:36 -0800 Subject: [PATCH 1/6] chore(quest): claim quest/m1/ts-small-step-back.md Quest-Claim: 05e92913be6f210d From 58176010284a4a72091e3eb280e01d2f9eee5bfa Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 19:11:15 -0800 Subject: [PATCH 2/6] fix(mux): restart TS clocks on small proven backward steps Co-Authored-By: GPT-6.1 Sol --- quest/m1/README.md | 1 - quest/m1/ts-small-step-back.md | 27 ------------- rs/moq-mux/benches/export.rs | 37 +++++++++++++++--- rs/moq-mux/src/container/ts/export.rs | 38 +++++++++---------- .../src/container/ts/export_timing_test.rs | 34 ++++++++++++----- 5 files changed, 74 insertions(+), 63 deletions(-) delete mode 100644 quest/m1/ts-small-step-back.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 3fe2ed0bf93..b7cf8b1c346 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -146,7 +146,6 @@ per-frame CPU growth since #5926. - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [Datagram tracks](/quest/m1/datagram-tracks/README.md) - a track is datagrams or streams; datagram tracks have their own request and sequence, no ranges, no cache, and map to object ID 0 on moq-transport -- [A step back smaller than the delay keeps the TS export](/quest/m1/ts-small-step-back.md) - audio restarts instead of regressing; video stays within its declared depth - [Taking control of a CARLA truck starts from neutral pedals](/quest/m1/carla-takeover-neutral.md) - a viewer's takeover releases the autopilot's throttle instead of driving off the road on it - [A wedged CARLA truck nobody drives respawns after the stuck timeout](/quest/m1/carla-stuck-handback.md) - find what kept the 300 s stuck respawn off for a truck wedged after a handback, and fix it - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it diff --git a/quest/m1/ts-small-step-back.md b/quest/m1/ts-small-step-back.md deleted file mode 100644 index b03670bfc40..00000000000 --- a/quest/m1/ts-small-step-back.md +++ /dev/null @@ -1,27 +0,0 @@ -# [S] A step back smaller than the delay keeps the TS export - -## Goal - -An unmarked timestamp step back smaller than the export's delay no longer -fails the MPEG-TS export. Audio restarts its clock instead of regressing within -one clock period. Declared-reorder video stays within its declared depth. - -## Plan - -Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Found by [moq-dev/moq#7221](https://github.com/moq-dev/moq/pull/7221), which -fixed steps larger than the delay. With a −300 ms step at lag 0, audio -regresses within one clock period, and declared-reorder video fails with -"video reorders past its declared depth 2". - -- The threshold differs by track type: any regression for audio, and the - declared depth for video. -- #7221's `Track::steps_back` (`rs/moq-mux/src/container/ts/export.rs`) is - where it goes. -- Video that declares no `reorder` stays untouched, so a slow, deep B-frame - stream is never mistaken for a step (decided 2026-11-03, maintainer, in - #7221). -- Extend `an_unmarked_step_keeps_the_export_rendering`. - -## Related - -- [TS reliability](/quest/m1/ts-reliability/README.md) - the epic whose step-back fix this extends diff --git a/rs/moq-mux/benches/export.rs b/rs/moq-mux/benches/export.rs index db05677b0fc..959c7da736d 100644 --- a/rs/moq-mux/benches/export.rs +++ b/rs/moq-mux/benches/export.rs @@ -258,20 +258,29 @@ async fn prepare_video( let mut video = catalog.video(track, Container::Legacy(Kind::Video), config).unwrap(); for index in 0..count { let pts = match pattern { - "pyramid" => ((index / 9 * 9 + [0, 4, 2, 1, 3, 8, 6, 5, 7][index % 9]) * 3_600) as u64, + "pyramid" | "step-back" => { + let pts = ((index / 9 * 9 + [0, 4, 2, 1, 3, 8, 6, 5, 7][index % 9]) * 3_600) as u64; + if pattern == "step-back" && index >= count / 2 { + // A 300 ms rewind within a group, followed by more groups to recover on. + pts - 300 * 90 + } else { + pts + } + } "flat" => 90_000, "backward" => 90_000 - index as u64, _ => unreachable!(), }; + let keyframe = index == 0 || (pattern == "step-back" && index.is_multiple_of(9)); let mut payload = vec![0; size]; payload[..4].copy_from_slice(&((size - 4) as u32).to_be_bytes()); - payload[4] = if index == 0 { 0x65 } else { 0x41 }; + payload[4] = if keyframe { 0x65 } else { 0x41 }; video .write(Frame { timestamp: Timestamp::from_scale(pts, 90_000).unwrap(), duration: None, payload: payload.into(), - keyframe: index == 0, + keyframe, }) .unwrap(); } @@ -300,14 +309,30 @@ fn video_reorder(c: &mut Criterion) { group.sample_size(10); group.warm_up_time(Duration::from_millis(50)); group.measurement_time(Duration::from_millis(200)); - for pattern in ["pyramid", "flat", "backward"] { + for (format, pattern) in [ + ("mkv", "pyramid"), + ("mkv", "flat"), + ("mkv", "backward"), + ("ts", "pyramid"), + ("ts", "step-back"), + ] { + let name = if format == "ts" { + format!("ts/{pattern}") + } else { + pattern.into() + }; for count in [64, 256, 1024] { for size in [256, 16_384] { - group.bench_function(BenchmarkId::new(pattern, format!("{count}x{size}")), |b| { + group.bench_function(BenchmarkId::new(&name, format!("{count}x{size}")), |b| { b.iter_batched( || runtime.block_on(prepare_video(count, size, pattern)), |(source, stream, fixture)| { let refused = runtime.block_on(async { + if format == "ts" { + let opened = moq_mux::container::ts::Export::new(source, stream); + assert!(export(Export::Ts(Box::new(opened))).await > 0); + return false; + } let mut export = moq_mux::container::mkv::Export::new(source, stream) .with_fragment_duration(Duration::ZERO); loop { @@ -320,7 +345,7 @@ fn video_reorder(c: &mut Criterion) { } } }); - assert_eq!(refused, pattern != "pyramid"); + assert_eq!(refused, format == "mkv" && pattern != "pyramid"); fixture }, BatchSize::PerIteration, diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index fafe9ba9400..2c18e8fc23d 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -523,8 +523,7 @@ impl Track { self.release(name, jitter, false) } - /// Count a frame that steps the track's timeline back with no marker as a marker of its own: - /// presented further below the highest PTS read on the timeline than the export's `delay`, + /// Count a frame that steps the track's timeline back with no marker as a marker of its own, /// where a reorder bound proves no valid reordering explains it. /// /// Audio presents in decode order, so any frame below one read before it is out of order. @@ -538,17 +537,14 @@ impl Track { /// and fail the export, and audio with slack left would decode before the frames ahead of it /// on the same clock, which the output's buffers cannot carry. As a marker, the step restarts /// the decode clock and opens a new generation, as one the source declared would. A placed - /// frame's timestamp is its arrival rather than its decode time, so it never steps. Without a - /// delay nothing is late, so a step costs nothing there. - fn steps_back(&mut self, pending: &mut Pending, delay: Duration) { + /// frame's timestamp is its arrival rather than its decode time, so it never steps. + fn steps_back(&mut self, pending: &mut Pending) { if self.kind.placed() { return; } let pts = pending.frame.timestamp; let high = (self.high).and_then(|(restart, high)| (restart == pending.restart).then_some(high)); - let delay = u64::try_from(delay.as_micros() * 90_000 / 1_000_000).unwrap_or(u64::MAX); - let below = delay > 0 && high.is_some_and(|high| to_ticks(pts).saturating_add(delay) < to_ticks(high)); - let stepped = below + let stepped = high.is_some_and(|high| pts < high) && match self.kind { Kind::Video(_) => (self.declared) .as_ref() @@ -605,7 +601,7 @@ impl Track { arrived, read: kio::clock::now(), }; - self.steps_back(&mut pending, input.jitter.delay()); + self.steps_back(&mut pending); // A new timeline must reach the reset before tune-in alignment can drop it. if let Some(start) = input.video_start && aligned && pending.restart == self.restart @@ -5077,7 +5073,7 @@ mod tests { arrived, read: arrived, }; - track.steps_back(&mut pending, Duration::from_millis(500)); + track.steps_back(&mut pending); if pending.restart != track.restart { track.restart = pending.restart; track.clock = DecodeClock::default(); @@ -5122,16 +5118,18 @@ mod tests { 0, "in-bound reordering" ); - assert_eq!( - video_steps(Some(2), &pyramid(10_000, 560, 4)).await, - 1, - "a step within a group" - ); - assert_eq!( - video_steps(Some(2), &pyramid(10_000, 560, 0)).await, - 1, - "a group stepped whole" - ); + for step in [300, 560] { + assert_eq!( + video_steps(Some(2), &pyramid(10_000, step, 4)).await, + 1, + "a {step} ms step within a group" + ); + assert_eq!( + video_steps(Some(2), &pyramid(10_000, step, 0)).await, + 1, + "a group stepped whole by {step} ms" + ); + } // Two frames back is within the declared depth, however far back they are presented. let deep = [(10_000, true), (11_000, false), (11_040, false), (10_040, false)]; assert_eq!( diff --git a/rs/moq-mux/src/container/ts/export_timing_test.rs b/rs/moq-mux/src/container/ts/export_timing_test.rs index c21574ca408..a14eb885bb0 100644 --- a/rs/moq-mux/src/container/ts/export_timing_test.rs +++ b/rs/moq-mux/src/container/ts/export_timing_test.rs @@ -529,6 +529,8 @@ async fn end_waits_for_catalog_and_media() { #[derive(Debug, Clone, Copy)] struct Unit { pid: u16, + /// PCR clock period, advanced by a flagged PCR. + period: u64, /// Decode time (DTS, else PTS), 90 kHz, as carried. decode: u64, /// Decode time less the PCR of the slot carrying the PES start, in milliseconds: how long @@ -559,10 +561,14 @@ fn units(out: &[(Instant, Frame)]) -> Vec { let mut reader = TsPacketReader::new(Cursor::new(bytes)); let mut units = Vec::new(); let mut pcr: Option = None; + let mut period = 0; for sent in &slot_of { let packet = reader.read_ts_packet().unwrap().expect("a packet per slot entry"); - if let Some(clock) = packet.adaptation_field.as_ref().and_then(|af| af.pcr) { + if let Some(af) = packet.adaptation_field.as_ref() + && let Some(clock) = af.pcr + { pcr = Some(clock.as_u64() / 300); + period += u64::from(af.discontinuity_indicator); } if let Some(TsPayload::PesStart(pes)) = &packet.payload && let Some(pts) = pes.header.pts @@ -571,6 +577,7 @@ fn units(out: &[(Instant, Frame)]) -> Vec { let decode = pes.header.dts.unwrap_or(pts).as_u64(); units.push(Unit { pid: packet.header.pid.as_u16(), + period, decode, lead: diff90(decode, pcr) as f64 / 90.0, sent: *sent, @@ -741,15 +748,17 @@ async fn a_track_sent_later_than_the_delay_loses_nothing() { /// A changeover between two encoders whose clocks started hours apart steps the whole timeline /// forward with no marker, mid-group, as in the field. The export re-acquires its clock as at /// startup, rather than read the step as drift and end, and renders on without a drop. So it -/// does for a step back of more than the delay that lands within the group before its own, on -/// video that declares its `reorder`, which proves the step is no reordering, rather than clamp -/// the video onto the old timeline and drop it as late until the timeline catches up, or fail on -/// a frame reordered deeper than declared. Video that declares none is left as it is. (A step -/// back further than that never reaches it: the reader refuses it.) +/// does for a step back, even smaller than the delay: audio never regresses on one clock, and +/// video that declares its `reorder` restarts when the step exceeds that depth. Video that +/// declares none is left as it is. A step back into an earlier group never reaches the export: +/// the reader refuses it. #[tokio::test(start_paused = true)] async fn an_unmarked_step_keeps_the_export_rendering() { let forward = [16_844_500_000, 2_000_000].map(|step| [(step, false), (step, true)]); - let cases = forward.into_iter().flatten().chain([(-560_000, true)]); + let cases = forward + .into_iter() + .flatten() + .chain([(-300_000, false), (-300_000, true), (-560_000, true)]); for (step, declared) in cases { for lag in [0, LAGS[0], LAGS[1]] { let mut live = Live::new(1.0, lag).await; @@ -764,8 +773,15 @@ async fn an_unmarked_step_keeps_the_export_rendering() { let case = format!("{} s step, declared {declared}, lag {lag}", step as f64 / 1e6); assert_eq!(leg.export.dropped(), 0, "{case}"); - let video = leg - .units() + let units = leg.units(); + let audio: Vec<_> = units.iter().filter(|unit| unit.pid == AUDIO_PID).collect(); + for pair in audio.windows(2) { + assert!( + pair[0].period != pair[1].period || diff90(pair[1].decode, pair[0].decode) >= 0, + "{case}: audio regressed on one clock: {pair:?}" + ); + } + let video = units .into_iter() .filter(|unit| unit.pid == VIDEO_PID && unit.sent >= stepped) .count() as u64; From 8d4451efb890610e39f203adf2f033f1277ee13f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 19:18:37 -0800 Subject: [PATCH 3/6] fix(mux): honor queued backward markers before the first release Co-Authored-By: GPT-6.1 Sol --- rs/moq-mux/src/container/ts/export_test.rs | 19 +++++++-------- rs/moq-mux/src/jitter.rs | 27 +++++++++++++++------- 2 files changed, 27 insertions(+), 19 deletions(-) diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index d511e8587ca..45f5eee2313 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -1392,8 +1392,8 @@ async fn trimmed_leading_pictures_keep_their_slots() { assert_eq!(joined.iter().collect::>(), shared); } -/// A declared depth of zero decodes every frame at its presentation, and refuses a frame that -/// reorders, rather than inferring a decode delay. +/// A declared depth of zero decodes every frame at its presentation. A regression proves a +/// timeline step and starts a new clock period instead of inferring a decode delay. #[tokio::test(start_paused = true)] async fn export_declared_zero_reorder_decodes_at_presentation() { let (mut export, _keep) = export_declared(0, &[&[0, 40, 80, 120]]).await; @@ -1406,15 +1406,12 @@ async fn export_declared_zero_reorder_decodes_at_presentation() { assert_eq!(timing.len(), 4); assert!(timing.iter().all(|(pts, dts)| pts == dts), "{timing:?}"); - let (mut export, _keep) = export_declared(0, &[&[0, 80, 40, 120]]).await; - let err = loop { - match kio::clock::timeout(DRAIN, export.next()).await { - Ok(Ok(Some(_))) => {} - Ok(Ok(None)) | Err(_) => panic!("a frame reordered past the declared depth was exported"), - Ok(Err(err)) => break err, - } - }; - assert!(err.to_string().contains("declared depth"), "{err}"); + let (mut export, _keep) = export_declared(0, &[&[0, 80, 40, 120], &[160, 200]]).await; + let frames = drain_frames(&mut export).await; + let bytes: Vec = frames.iter().flat_map(|frame| frame.payload.iter().copied()).collect(); + let timing = video_pes_timing(&bytes); + assert_eq!(timing, [0, 80, 40, 120, 160, 200].map(|ms| (ms * 90, ms * 90))); + assert_eq!(count_discontinuity(&frames), 1, "the step opens one clock period"); } /// #2937: the PCR must be a uniform bounded-interval ramp, not a sample of the diff --git a/rs/moq-mux/src/jitter.rs b/rs/moq-mux/src/jitter.rs index 207655ec82d..d7d39b38a24 100644 --- a/rs/moq-mux/src/jitter.rs +++ b/rs/moq-mux/src/jitter.rs @@ -815,10 +815,7 @@ impl Engine { .acquire .as_ref() .is_some_and(|acquire| acquire.tracks.contains_key(&key)); - let Some(clock) = self - .clock - .filter(|_| !held && !(self.released.is_some() && self.jumps(&key, &arrival))) - else { + let Some(clock) = self.clock.filter(|_| !held && !self.jumps(&key, &arrival)) else { self.hold(key, arrival); return Ok(Push::Queued); }; @@ -890,17 +887,19 @@ impl Engine { /// draining nor a track whose frames are sparse does. Back, a frame decodes before its /// track's last and is late: a stall only delays what comes next. It is a step on the /// clock's own generation, since a track still on an earlier one is on that timeline. - /// Held for the next generation, the frame never steers the old clock. Without a delay - /// nothing is held or late, so a step costs nothing there. + /// Held for the next generation, the frame never steers the old clock. A marker before the + /// first release keeps the clock unless it regresses behind frames already queued. Without + /// a delay nothing is held or late, so an unmarked step costs nothing there. fn jumps(&self, key: &K, arrival: &Arrival) -> bool { let (Some(clock), Some(track)) = (self.clock, self.tracks.get(key)) else { return false; }; let deadline = self.deadline(&clock, arrival.decode); let restarted = track.restart != arrival.restart + && (self.released.is_some() || arrival.decode < track.decode) && (track.generation == clock.generation || !self.lands(key, deadline, arrival.arrived)); let held = deadline.is_some_and(|deadline| deadline > self.bound(key, arrival.arrived)); - let unmarked = !self.delay.is_zero() && track.generation == clock.generation; + let unmarked = self.released.is_some() && !self.delay.is_zero() && track.generation == clock.generation; let elapsed = arrival.decode.as_nanos() - track.decode.as_nanos(); let ahead = elapsed - since(track.arrived, arrival.arrived); let drift = (elapsed.abs() as f64 * MAX_DRIFT) as i128; @@ -2166,7 +2165,7 @@ mod tests { assert_eq!(due(&mut buffer), ["v200", "v280", "v320", "v360"]); } - /// A restart before anything went out keeps the clock, so the tracks stay on one. + /// A forward restart before anything went out keeps the clock, so the tracks stay on one. #[tokio::test(start_paused = true)] async fn a_skip_before_the_first_release_keeps_one_clock() { let start = kio::clock::now(); @@ -2193,6 +2192,18 @@ mod tests { ); } + /// A marked regression is a new timeline even while every frame is still queued: the + /// frames before and after it cannot decode in order on one clock. + #[tokio::test(start_paused = true)] + async fn a_marked_regression_before_the_first_release_opens_a_clock() { + let start = kio::clock::now(); + let mut buffer = Buffer::new(DELAY).replay(); + buffer.push(1, arrival(start, 80, "before")).unwrap(); + buffer.push(1, after(1, arrival(start, 40, "after"))).unwrap(); + tokio::time::advance(DELAY).await; + assert_eq!(released(&mut buffer), [("before", 0), ("after", 1)]); + } + /// A restart after frames went out opens a new generation, and every track's next frame /// runs on it, whether or not that track saw the restart. #[tokio::test(start_paused = true)] From dbc33d72535288b0ac09b731294fda19abc6394e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 19:20:40 -0800 Subject: [PATCH 4/6] bench(mux): exercise TS steps inside the subscribed group Co-Authored-By: GPT-6.1 Sol --- rs/moq-mux/benches/export.rs | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/rs/moq-mux/benches/export.rs b/rs/moq-mux/benches/export.rs index 959c7da736d..cb2b073bf16 100644 --- a/rs/moq-mux/benches/export.rs +++ b/rs/moq-mux/benches/export.rs @@ -261,7 +261,7 @@ async fn prepare_video( "pyramid" | "step-back" => { let pts = ((index / 9 * 9 + [0, 4, 2, 1, 3, 8, 6, 5, 7][index % 9]) * 3_600) as u64; if pattern == "step-back" && index >= count / 2 { - // A 300 ms rewind within a group, followed by more groups to recover on. + // Keep the 300 ms rewind in the one group every subscription reads. pts - 300 * 90 } else { pts @@ -271,16 +271,15 @@ async fn prepare_video( "backward" => 90_000 - index as u64, _ => unreachable!(), }; - let keyframe = index == 0 || (pattern == "step-back" && index.is_multiple_of(9)); let mut payload = vec![0; size]; payload[..4].copy_from_slice(&((size - 4) as u32).to_be_bytes()); - payload[4] = if keyframe { 0x65 } else { 0x41 }; + payload[4] = if index == 0 { 0x65 } else { 0x41 }; video .write(Frame { timestamp: Timestamp::from_scale(pts, 90_000).unwrap(), duration: None, payload: payload.into(), - keyframe, + keyframe: index == 0, }) .unwrap(); } @@ -329,8 +328,14 @@ fn video_reorder(c: &mut Criterion) { |(source, stream, fixture)| { let refused = runtime.block_on(async { if format == "ts" { - let opened = moq_mux::container::ts::Export::new(source, stream); - assert!(export(Export::Ts(Box::new(opened))).await > 0); + let mut opened = moq_mux::container::ts::Export::new(source, stream); + let mut chunks = 0; + while let Some(frame) = opened.next().await.unwrap() { + std::hint::black_box(frame); + chunks += 1; + } + assert!(chunks > 0); + assert_eq!(opened.discontinuity(), u64::from(pattern == "step-back")); return false; } let mut export = moq_mux::container::mkv::Export::new(source, stream) From f12c0150a5ce79cff2cc54f343d81d9c45eb318f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 19:30:36 -0800 Subject: [PATCH 5/6] fix(mux): retain declared video depth across timeline restarts Co-Authored-By: GPT-6.1 Sol --- rs/moq-mux/src/container/declared.rs | 5 +++++ rs/moq-mux/src/container/ts/export.rs | 5 +++-- rs/moq-mux/src/container/ts/export_test.rs | 6 +++--- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/rs/moq-mux/src/container/declared.rs b/rs/moq-mux/src/container/declared.rs index f60fd4e7956..c48134b61e0 100644 --- a/rs/moq-mux/src/container/declared.rs +++ b/rs/moq-mux/src/container/declared.rs @@ -64,6 +64,11 @@ impl DeclaredClock { } } + /// Restart the clock at the same declared depth. + pub(crate) fn restart(self) -> Self { + Self::new(self.depth) + } + /// How many frames are held. #[cfg(test)] pub(crate) fn len(&self) -> usize { diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 2c18e8fc23d..b70465b0802 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -442,7 +442,8 @@ impl Track { self.release(name, jitter, true)?; self.restart = pending.restart; self.clock = DecodeClock::default(); - self.declared = None; + // The step changes the timeline, not the group's declared reorder bound. + self.declared = self.declared.take().map(DeclaredClock::restart); self.keyframe = None; self.leading_floor = None; } @@ -5077,7 +5078,7 @@ mod tests { if pending.restart != track.restart { track.restart = pending.restart; track.clock = DecodeClock::default(); - track.declared = None; + track.declared = track.declared.take().map(super::DeclaredClock::restart); } if keyframe { track.declared = reorder.map(super::DeclaredClock::new); diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 45f5eee2313..c993776ea8a 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -1406,12 +1406,12 @@ async fn export_declared_zero_reorder_decodes_at_presentation() { assert_eq!(timing.len(), 4); assert!(timing.iter().all(|(pts, dts)| pts == dts), "{timing:?}"); - let (mut export, _keep) = export_declared(0, &[&[0, 80, 40, 120], &[160, 200]]).await; + let (mut export, _keep) = export_declared(0, &[&[0, 80, 40, 120, 80, 160], &[200, 240]]).await; let frames = drain_frames(&mut export).await; let bytes: Vec = frames.iter().flat_map(|frame| frame.payload.iter().copied()).collect(); let timing = video_pes_timing(&bytes); - assert_eq!(timing, [0, 80, 40, 120, 160, 200].map(|ms| (ms * 90, ms * 90))); - assert_eq!(count_discontinuity(&frames), 1, "the step opens one clock period"); + assert_eq!(timing, [0, 80, 40, 120, 80, 160, 200, 240].map(|ms| (ms * 90, ms * 90))); + assert_eq!(count_discontinuity(&frames), 2, "each step opens a clock period"); } /// #2937: the PCR must be a uniform bounded-interval ramp, not a sample of the From 9e657e8c670354ecdeca28da8e48380da2f08b23 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 22:54:29 -0800 Subject: [PATCH 6/6] fix(mux): split an acquisition at a regressing restart A live buffer still acquiring its clock held every frame of a track in one acquisition, then queued them all under one generation, ignoring their restart counters. A marked step back (or one the TS export inferred) during read-ahead released the regressed frame on the same clock as the frames before it, so audio decoded backward within one PCR period. Track each held track's last restart and decode, and end the acquisition when a frame regresses behind them across a restart, so the frame opens the next generation through the existing restart path. Forward restarts while acquiring still keep one clock. Covered with non-replay jitter tests and a live TS export that steps back during read-ahead. Co-Authored-By: Claude Opus 5.5 --- .../src/container/ts/export_timing_test.rs | 35 ++++++ rs/moq-mux/src/jitter.rs | 100 +++++++++++++++--- 2 files changed, 119 insertions(+), 16 deletions(-) diff --git a/rs/moq-mux/src/container/ts/export_timing_test.rs b/rs/moq-mux/src/container/ts/export_timing_test.rs index a14eb885bb0..d819e860a01 100644 --- a/rs/moq-mux/src/container/ts/export_timing_test.rs +++ b/rs/moq-mux/src/container/ts/export_timing_test.rs @@ -790,6 +790,41 @@ async fn an_unmarked_step_keeps_the_export_rendering() { } } +/// The same step back, smaller than the delay, while the export is still acquiring its first +/// clock: what it read before the step and what it reads after cannot share one clock, so +/// audio still never regresses within a clock period, and the export renders on. +#[tokio::test(start_paused = true)] +async fn an_unmarked_step_while_acquiring_keeps_the_export_rendering() { + for declared in [false, true] { + for lag in [0, LAGS[0], LAGS[1]] { + let mut live = Live::new(1.0, lag).await; + // Far enough into the timeline that the step stays on it. + live.offset = 10_000_000; + if declared { + live.reorder(); + } + let mut leg = live.join(Duration::ZERO).await; + live.run(4, &mut [&mut leg], |_| false); + let case = format!("declared {declared}, lag {lag}"); + assert!(leg.units().is_empty(), "{case}: output began before the step"); + live.offset -= 300_000; + live.run(live.tick + 8 * GOP, &mut [&mut leg], |_| false); + + assert_eq!(leg.export.dropped(), 0, "{case}"); + let units = leg.units(); + let audio: Vec<_> = units.iter().filter(|unit| unit.pid == AUDIO_PID).collect(); + for pair in audio.windows(2) { + assert!( + pair[0].period != pair[1].period || diff90(pair[1].decode, pair[0].decode) >= 0, + "{case}: audio regressed on one clock: {pair:?}" + ); + } + let video = units.iter().filter(|unit| unit.pid == VIDEO_PID).count() as u64; + assert!(video >= 6 * GOP, "{case}: only {video} video units"); + } + } +} + // A publisher that dies leaves the last video frames it sent held for their DTS, and nothing // settles them until frames come again. Where the receiver is not told the source changed (a // replacement on a protocol under another instance, or the other half of a 1+1 pair), those come on the diff --git a/rs/moq-mux/src/jitter.rs b/rs/moq-mux/src/jitter.rs index d7d39b38a24..df593cc6f26 100644 --- a/rs/moq-mux/src/jitter.rs +++ b/rs/moq-mux/src/jitter.rs @@ -476,8 +476,10 @@ pub(crate) enum Push { /// One crossing the same restart joins the new generation when the frame lands on its /// clock, neither late nor held more than a delay past everything queued, and opens another /// otherwise. Before anything has gone out there is nothing to keep in step with, so a -/// restart there keeps the clock. Generations go out in turn, so no two tracks are ever on -/// different clocks at once. +/// restart there keeps the clock when it moves the timeline forward. One that regresses behind +/// what its track already holds, queued or still acquiring, opens a generation all the same: +/// frames decoding out of order cannot share a clock. Generations go out in turn, so no two +/// tracks are ever on different clocks at once. /// /// The clock follows the source's: a source clock running slower than ours would make /// every frame late in the end, and a faster one would hold more and more. So the clock @@ -590,15 +592,23 @@ struct Acquire { since: Instant, /// Its frames, in arrival order. frames: Vec<(K, Arrival)>, - /// Its tracks, and whether each is partway through a group, so its next sync frame - /// starts the next one. - tracks: BTreeMap, - /// What each track holds of its frames. - bytes: BTreeMap, + /// Its tracks, and what each holds of its frames. + tracks: BTreeMap, /// A track crossed a group boundary while these frames were being read. grouped: bool, } +/// What one track holds of an acquisition. +struct Held { + /// Whether it is partway through a group, so its next sync frame starts the next one. + mid: bool, + /// What its frames hold against the byte budget. + bytes: usize, + /// The source's restart counter at its last frame, and when that frame decodes. + restart: u64, + decode: Decode, +} + impl Acquire { /// The frame to anchor on: each track's freshest frame (the one read least behind its /// decode time) is that track's slack less its queueing, and of those, the one with the least @@ -811,6 +821,12 @@ impl Engine { /// Queue a frame, or drop it if it cannot make its deadline. Fails once the source's clock /// runs further off ours than the clock may follow. pub fn push(&mut self, key: K, arrival: Arrival) -> anyhow::Result { + let held = self.acquire.as_ref().and_then(|acquire| acquire.tracks.get(&key)); + // A restart behind what the track already holds cannot decode in order on the clock the + // acquisition would anchor, so the acquisition ends at it and the frame opens the next. + if held.is_some_and(|held| held.restart != arrival.restart && arrival.decode < held.decode) { + self.acquired(); + } let held = self .acquire .as_ref() @@ -888,7 +904,8 @@ impl Engine { /// track's last and is late: a stall only delays what comes next. It is a step on the /// clock's own generation, since a track still on an earlier one is on that timeline. /// Held for the next generation, the frame never steers the old clock. A marker before the - /// first release keeps the clock unless it regresses behind frames already queued. Without + /// first release keeps the clock unless it regresses behind frames already queued; one that + /// regresses behind frames still acquiring ends that acquisition first ([`Self::push`]). Without /// a delay nothing is held or late, so an unmarked step costs nothing there. fn jumps(&self, key: &K, arrival: &Arrival) -> bool { let (Some(clock), Some(track)) = (self.clock, self.tracks.get(key)) else { @@ -918,13 +935,19 @@ impl Engine { since: arrival.read, frames: Vec::new(), tracks: BTreeMap::new(), - bytes: BTreeMap::new(), grouped: false, }); - let mid = acquire.tracks.entry(key.clone()).or_default(); - acquire.grouped |= arrival.sync && *mid; - *mid |= !arrival.sync; - *acquire.bytes.entry(key.clone()).or_default() += arrival.cost(); + let held = acquire.tracks.entry(key.clone()).or_insert(Held { + mid: false, + bytes: 0, + restart: arrival.restart, + decode: arrival.decode, + }); + acquire.grouped |= arrival.sync && held.mid; + held.mid |= !arrival.sync; + held.bytes += arrival.cost(); + held.restart = arrival.restart; + held.decode = arrival.decode; acquire.frames.push((key, arrival)); // A live fill must read every track's available frames before choosing the clock. // Otherwise the first track crossing a group boundary anchors on a partial backlog. @@ -1457,9 +1480,8 @@ impl Engine { let acquiring = self .acquire .as_ref() - .and_then(|acquire| acquire.bytes.get(key)) - .copied() - .unwrap_or(0); + .and_then(|acquire| acquire.tracks.get(key)) + .map_or(0, |held| held.bytes); if acquiring >= self.max_bytes { return true; } @@ -2204,6 +2226,52 @@ mod tests { assert_eq!(released(&mut buffer), [("before", 0), ("after", 1)]); } + /// So it is while the first clock is still being acquired: the frames before the regression + /// anchor one clock and the frames after it the next, rather than share one. + #[tokio::test(start_paused = true)] + async fn a_marked_regression_while_acquiring_opens_a_clock() { + let start = kio::clock::now(); + let mut buffer = Buffer::new(DELAY); + assert_eq!(buffer.push(1, arrival(start, 80, "before")).unwrap(), Push::Queued); + assert_eq!( + buffer.push(1, after(1, arrival(start, 40, "after"))).unwrap(), + Push::Queued + ); + assert_eq!( + buffer.push(1, after(1, arrival(start, 60, "next"))).unwrap(), + Push::Queued + ); + tokio::time::advance(4 * DELAY).await; + assert_eq!(released(&mut buffer), [("before", 0), ("after", 1), ("next", 1)]); + assert_eq!(buffer.dropped() + buffer.trimmed(), 0); + } + + /// A forward restart while the first clock is acquired keeps it, as before a release. + #[tokio::test(start_paused = true)] + async fn a_forward_restart_while_acquiring_keeps_one_clock() { + let start = kio::clock::now(); + let mut buffer = Buffer::new(DELAY); + buffer.push(1, arrival(start, 0, "v0")).unwrap(); + buffer.push(1, after(1, arrival(start, 40, "v40"))).unwrap(); + tokio::time::advance(4 * DELAY).await; + assert_eq!(released(&mut buffer), [("v0", 0), ("v40", 0)]); + } + + /// A regression while a later generation's clock is acquired opens the one after it, too. + #[tokio::test(start_paused = true)] + async fn a_marked_regression_while_reacquiring_opens_a_clock() { + let start = kio::clock::now(); + let mut buffer = Buffer::new(DELAY); + buffer.push(1, arrival(start, 0, "v0")).unwrap(); + tokio::time::advance(4 * DELAY).await; + assert_eq!(released(&mut buffer), [("v0", 0)]); + let now = kio::clock::now(); + buffer.push(1, after(1, arrival(now, 5_000, "v5000"))).unwrap(); + buffer.push(1, after(2, arrival(now, 4_000, "v4000"))).unwrap(); + tokio::time::advance(4 * DELAY).await; + assert_eq!(released(&mut buffer), [("v5000", 1), ("v4000", 2)]); + } + /// A restart after frames went out opens a new generation, and every track's next frame /// runs on it, whether or not that track saw the restart. #[tokio::test(start_paused = true)]