From 8ba196262f1e63eadefd3fb72ba7daf35d25f232 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 12:31:55 -0700 Subject: [PATCH 1/2] chore(quest): claim quest/m1/cut-audit/jitter-admission.md Quest-Claim: 7ce2ef0beaf06fbc From f4f0e004e6a67649006bb727fb3627bec57924d4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 23:27:02 -0700 Subject: [PATCH 2/2] fix(mux): a skip no longer opens a generation on its own The export clock's leapt arm opened a new generation for any frame held past the bound after a skip or during an acquisition. After a stall drains the queue, a frame merely less queued than the clock's anchor is held past that bound too, so a skip could cost the TS output a spurious discontinuity. The unmarked forward step already opens a generation for a real leap, so the arm and the jitter buffer's skip counter go. Finishes quest/m1/cut-audit/jitter-admission.md: the knockout of every other candidate rule is recorded in the PR. Co-Authored-By: Claude Opus 5.5 --- quest/m1/cut-audit/README.md | 1 - quest/m1/cut-audit/jitter-admission.md | 43 ---------- rs/moq-mux/benches/jitter.rs | 4 - rs/moq-mux/src/container/flv/export.rs | 3 - rs/moq-mux/src/container/mkv/export.rs | 1 - rs/moq-mux/src/container/ts/export.rs | 5 +- rs/moq-mux/src/container/ts/release.rs | 1 - rs/moq-mux/src/jitter.rs | 105 ++++++++++++------------- 8 files changed, 52 insertions(+), 111 deletions(-) delete mode 100644 quest/m1/cut-audit/jitter-admission.md diff --git a/quest/m1/cut-audit/README.md b/quest/m1/cut-audit/README.md index b1682a48e53..465a28a2bb6 100644 --- a/quest/m1/cut-audit/README.md +++ b/quest/m1/cut-audit/README.md @@ -57,7 +57,6 @@ leaving JS-only redesigns of `js/net` to [rs2ts](/quest/m2/rs2ts/README.md). - [Counted field-less `trun` entries](/quest/m1/cut-audit/fmp4-sample-resolver.md) - a moof of field-less runs cannot materialize millions of sample entries - [A reserved group survives a route returning](/quest/m1/cut-audit/reserved-route-return.md) - a route flip A to B to A no longer panics a peeked reader - [A description-less AAC rendition means one thing](/quest/m1/cut-audit/aac-description-less.md) - every player and exporter agrees on the frame format -- [The export clock keeps only the rules admission still needs](/quest/m1/cut-audit/jitter-admission.md) - the clock rules the time and byte admission bound made redundant are measured and removed - [Stream-accept loops yield on a per-poll budget](/quest/m1/cut-audit/accept-budget.md) - a peer opening many streams cannot monopolize a session driver - [Rust and JS accept the same catalogs](/quest/m1/cut-audit/catalog-parity.md) - one strictness, per rendition, with a shared fixture corpus - [Every relay runtime honors or refuses each listen setting](/quest/m1/cut-audit/uring-listen-config.md) - io_uring stops ignoring preferred addresses diff --git a/quest/m1/cut-audit/jitter-admission.md b/quest/m1/cut-audit/jitter-admission.md deleted file mode 100644 index 36ebbc85ecd..00000000000 --- a/quest/m1/cut-audit/jitter-admission.md +++ /dev/null @@ -1,43 +0,0 @@ -# [M] The export clock keeps only the rules admission still needs - -## Goal - -The TS, MKV, and FLV exports' jitter buffer is bounded by admission alone -(time once a clock exists, bytes throughout), and the export clock sheds -each rule about which frames count that this invariant made redundant. -Land what the measurement supports; record what it does not. - -## Plan - -About a dozen fixes to the export clock (f85547ffd0, 5d5974f083, -3fdf46160b, e84ffb3de3, a1465d0d00, 11bfa30461, 3cf978cdbf, 493d8eee99, -7a3890cd30, 3b77d23015, 7c4c48d08b, 41f3087e3c) each added a rule about -which frames count. With admission as the single invariant, check whether -acquisition, the leapt/lagging arms, and some of the nine tuning constants -in `rs/moq-mux/src/jitter.rs` can go. - -Landed in [moq-dev/moq#7012](https://github.com/moq-dev/moq/pull/7012): - -- Admission is time-bounded once a clock exists: a track is full once its - newest queued frame is due past the delay plus its lead. Leads are seeded - from acquisition, and a per-track wake reopens a future tail before it is - due. A 120-second feed with audio at 1x and video at 3x held 4,938 frames - before and at most 54 after. -- Admission is byte-bounded throughout: a track is full while its queued and - acquiring frames hold the per-track budget (`MAX_CACHE_BYTES`, as the - container consumer's default max buffer). Before a - clock exists, the budget alone bounds acquisition; acquisition still - anchors on the freshest frame of what it read. -- A backpressured reader still receives group handles (`poll_received`), so - a finite tail is recognized only after track FIN and every group's FIN, and - never-decoded evicted handles are reaped by amortized doubling compaction. - -A time bound on acquisition (stopping at a delay's worth of backlog) was not -taken: it changes the freshest-frame anchor and the lead of a track sampled -after it, while the byte budget already bounds memory. - -Public API: none. Wire: none. - -## Related - -- [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - the import side's state ownership diff --git a/rs/moq-mux/benches/jitter.rs b/rs/moq-mux/benches/jitter.rs index 5c85145f1fd..d5185674bde 100644 --- a/rs/moq-mux/benches/jitter.rs +++ b/rs/moq-mux/benches/jitter.rs @@ -28,7 +28,6 @@ async fn steer(tracks: u16, floors: u64) -> u64 { read: at, decode: Timestamp::from_millis(second * 1_000).unwrap().into(), restart: 0, - skip: 0, sync: true, leading: false, bytes: 0, @@ -90,7 +89,6 @@ fn acquisition(c: &mut Criterion) { read: start, decode: Timestamp::from_millis(frame * 20).unwrap().into(), restart: 0, - skip: 0, sync: frame % 15 == 0, leading: false, bytes: 0, @@ -148,7 +146,6 @@ fn handoff(c: &mut Criterion) { .unwrap() .into(), restart: 0, - skip: 0, sync: frame % 15 == 0, leading: false, bytes: 0, @@ -198,7 +195,6 @@ fn admission(c: &mut Criterion) { read: moq_clock::now(), decode: Timestamp::from_millis(decode).unwrap().into(), restart: 0, - skip: 0, sync: true, leading: false, bytes: 0, diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index a4f4d6884dc..6eb0bd94244 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -285,7 +285,6 @@ impl FlvTrack { arrived, read, restart, - skip, sync, leading, bytes, @@ -299,7 +298,6 @@ impl FlvTrack { read, decode: moq_net::Timestamp::from_millis(u64::from(timestamp))?.into(), restart, - skip, sync, leading, bytes, @@ -514,7 +512,6 @@ impl Export { read: moq_clock::now(), decode: frame.timestamp.into(), restart: track.source.markers(), - skip: track.source.skips(), sync: kind == 1 || frame.keyframe, leading: false, bytes: frame.payload.len(), diff --git a/rs/moq-mux/src/container/mkv/export.rs b/rs/moq-mux/src/container/mkv/export.rs index 7cbd91d6e46..4ae587d6fd4 100644 --- a/rs/moq-mux/src/container/mkv/export.rs +++ b/rs/moq-mux/src/container/mkv/export.rs @@ -538,7 +538,6 @@ impl Export { read: moq_clock::now(), decode: frame.timestamp.into(), restart: track.source.markers(), - skip: track.source.skips(), sync: track.kind == TrackKind::Audio || frame.keyframe, leading: false, bytes: frame.payload.len() + name.len(), diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 7f7f10f7646..b0cbd2ce5f1 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -254,7 +254,8 @@ struct Pending { /// How many marker groups had declared a break in the track's timeline when the frame /// was read. restart: u64, - /// How many times its playhead had jumped, markers included ([`jitter::Arrival::skip`]). + /// How many times its playhead had jumped (a skipped group, or a restart) when the frame + /// was read. skip: u64, /// How many of those jumps cut a group short ([`ExportSource::cuts`]). cut: u64, @@ -741,7 +742,6 @@ impl Track { let Pending { frame, restart, - skip, arrived, read, .. @@ -780,7 +780,6 @@ impl Track { read: read - ahead, decode: key.into(), restart, - skip, sync, leading, bytes: frame.payload.len() + self.key.name.len(), diff --git a/rs/moq-mux/src/container/ts/release.rs b/rs/moq-mux/src/container/ts/release.rs index 42687d2142a..7c354563594 100644 --- a/rs/moq-mux/src/container/ts/release.rs +++ b/rs/moq-mux/src/container/ts/release.rs @@ -162,7 +162,6 @@ impl Release { read: moq_clock::now(), decode: frame.timestamp.into(), restart: track.markers(), - skip: track.skips(), // The output opens on a group, at a random access point; from then on every // object goes out on its own, so one dropped late is a gap of its packets only. sync: frame.keyframe || self.released, diff --git a/rs/moq-mux/src/jitter.rs b/rs/moq-mux/src/jitter.rs index 8bd95a0174e..726f7663995 100644 --- a/rs/moq-mux/src/jitter.rs +++ b/rs/moq-mux/src/jitter.rs @@ -388,9 +388,6 @@ pub(crate) struct Arrival { pub decode: Decode, /// How many times the source had restarted its timeline when the frame was read. pub restart: u64, - /// How many times the source's playhead had jumped (a skipped group, or a restart) - /// when the frame was read. - pub skip: u64, /// Whether the frame decodes without the track's earlier frames. pub sync: bool, /// Whether it presents before the track's last sync frame, so it also references frames @@ -466,10 +463,8 @@ pub(crate) enum Push { /// late are dropped like any other. A source that restarts its timeline (a declared /// marker) has moved it, so once frames have gone out the restart opens a new generation, /// whose clock is acquired the same way, though never ahead of a deadline already given -/// out. So does a skip after which a frame would be held more than a delay past everything -/// queued, beyond how far ahead of the others its track is sent: its timeline jumped ahead, -/// as when the skipped groups held a marker the publisher shed. So does a step with no marker -/// at all, as a changeover between two encoders whose clocks disagree, once the delay cannot +/// out. So does a step with no marker at all, as a changeover between two encoders whose clocks +/// disagree, or skipped groups that held a marker the publisher shed, once the delay cannot /// absorb it: read as drift it would fail [`Buffer::push`], and steering on it would let the /// step's span of decode time slew the drift in one go. A smaller one is a move in latency. /// How far ahead of its decode time the source sends each track belongs to its mux and @@ -735,10 +730,8 @@ struct Track { read_timer: Option>>, /// What its queued frames hold against the byte budget. bytes: usize, - /// The source's restart and skip counters at the last frame, when it decodes, and when it - /// arrived. + /// The source's restart counter at the last frame, when it decodes, and when it arrived. restart: u64, - skip: u64, decode: Decode, arrived: Instant, /// The generation of the last frame. @@ -874,12 +867,15 @@ impl Engine { /// Whether a frame moves its track off the clock: a restart, unless the track is crossing /// one another track already opened a generation for and the frame lands on its clock, or - /// a frame held past [`Self::bound`] after a skip, or while a generation is acquired, or a - /// step in its timeline with no marker that the delay cannot absorb. The second is a track - /// reaching the new timeline without a marker of its own, which belongs to that generation, - /// not far ahead on the old clock. + /// a step in its timeline with no marker that the delay cannot absorb. A track reaching the + /// new timeline without a marker of its own makes such a step, and so does one whose skipped + /// groups held a marker the publisher shed: either belongs to a new generation, not far + /// ahead on the old clock. /// - /// An unmarked step is told apart from drift and queueing by size. Forward, a frame is held + /// An unmarked step is told apart from drift and queueing by size, not by a skip: after a + /// stall drains the queue, a frame that is merely less queued than the one the clock + /// anchored on is held past [`Self::bound`] too, and a new generation for it would cost the + /// output a discontinuity. Forward, a frame is held /// past [`Self::bound`] and reached us more than a delay earlier against its decode time /// than its track's last: no clock within [`MAX_DRIFT`] moves it that far in the time /// between them, and frames reach us in the order they are sent, so neither a backlog @@ -896,14 +892,13 @@ impl Engine { let restarted = track.restart != arrival.restart && (track.generation == clock.generation || !self.lands(key, deadline, arrival.arrived)); let held = deadline.is_some_and(|deadline| deadline > self.bound(key, arrival.arrived)); - let leapt = (track.skip != arrival.skip || self.acquire.is_some()) && held; let unmarked = !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; let forward = held && ahead > self.delay.as_nanos() as i128 + drift; let back = elapsed < 0 && deadline.is_none_or(|deadline| deadline < arrival.arrived); - restarted || leapt || (unmarked && (forward || back)) + restarted || (unmarked && (forward || back)) } /// Hold a frame for the generation being acquired, starting one if none is, and anchor it @@ -1007,7 +1002,6 @@ impl Engine { read_timer: None, bytes: 0, restart: arrival.restart, - skip: arrival.skip, decode: arrival.decode, arrived: arrival.arrived, generation, @@ -1016,7 +1010,6 @@ impl Engine { started: false, }); track.restart = arrival.restart; - track.skip = arrival.skip; track.decode = arrival.decode; track.arrived = arrival.arrived; track.generation = generation; @@ -1790,7 +1783,6 @@ mod tests { read: now, decode: ms(u64::from(key) * 100_000 + (now - start).as_millis() as u64).into(), restart: 0, - skip: 0, sync: true, leading: false, bytes: 0, @@ -1924,7 +1916,6 @@ mod tests { read: arrived, decode: ms(decode).into(), restart: 0, - skip: 0, sync: true, leading: false, bytes: 0, @@ -1934,11 +1925,7 @@ mod tests { /// The same frame, read after its source restarted its timeline `restart` times. fn after(restart: u64, arrival: Arrival<&'static str>) -> Arrival<&'static str> { - Arrival { - restart, - skip: restart, - ..arrival - } + Arrival { restart, ..arrival } } /// Every frame due by now, in order, with its generation. @@ -2373,19 +2360,15 @@ mod tests { // Group 1 is skipped: frames from 100 ms on arrive after a 250 ms stall. let stalled = start + Duration::from_millis(350); tokio::time::advance(stalled - moq_clock::now()).await; - let skipped = |decode, item| Arrival { - skip: 1, - ..arrival(stalled, decode, item) - }; - assert_eq!(buffer.push(1, skipped(200, "a200")).unwrap(), Push::Late); - assert_eq!(buffer.push(1, skipped(300, "a300")).unwrap(), Push::Queued); + assert_eq!(buffer.push(1, arrival(stalled, 200, "a200")).unwrap(), Push::Late); + assert_eq!(buffer.push(1, arrival(stalled, 300, "a300")).unwrap(), Push::Queued); tokio::time::advance(Duration::from_millis(100)).await; assert_eq!(released(&mut buffer), [("a300", 0)]); } - /// A skip after which a frame would be held more than a delay past everything queued - /// followed a timeline that leapt ahead, as when the skipped groups held a marker the - /// publisher shed, so it opens a generation. + /// A skip after which a frame is due more than a delay further ahead of its arrival than + /// its track's last followed a timeline that leapt ahead, as when the skipped groups held a + /// marker the publisher shed, so it opens a generation. #[tokio::test(start_paused = true)] async fn a_skip_that_leaps_ahead_opens_a_generation() { let start = moq_clock::now(); @@ -2395,15 +2378,32 @@ mod tests { assert_eq!(due(&mut buffer), ["a0"]); let now = moq_clock::now(); - let leapt = Arrival { - skip: 1, - ..arrival(now, 5_000, "a5000") - }; - assert_eq!(buffer.push(1, leapt).unwrap(), Push::Queued); + assert_eq!(buffer.push(1, arrival(now, 5_000, "a5000")).unwrap(), Push::Queued); tokio::time::advance(DELAY).await; assert_eq!(released(&mut buffer), [("a5000", 1)]); } + /// A skip after which a frame arrives a little fresher than the frame the clock anchored on, + /// with nothing queued, keeps the clock: the timeline did not move, and a new generation + /// would cost the output a discontinuity. + #[tokio::test(start_paused = true)] + async fn a_fresher_frame_after_a_skip_keeps_the_clock() { + let start = moq_clock::now(); + let mut buffer = Buffer::new(DELAY); + buffer.expect([1]); + buffer.push(1, arrival(start, 0, "a0")).unwrap(); + tokio::time::advance(DELAY).await; + assert_eq!(released(&mut buffer), [("a0", 0)]); + + // A second on, past a skipped group, the next frame is 20 ms less queued than the first. + let resume = start + Duration::from_secs(1); + tokio::time::advance(resume - moq_clock::now()).await; + assert_eq!(buffer.push(1, arrival(resume, 1_020, "a1020")).unwrap(), Push::Queued); + tokio::time::advance(Duration::from_secs(1)).await; + assert_eq!(released(&mut buffer), [("a1020", 0)]); + assert_eq!(buffer.dropped(), 0); + } + /// A track sent ahead of the others is held its lead past the delay. Once a skip of its own /// leaves only theirs queued, its next frame is due that lead past them, and keeps the clock. #[tokio::test(start_paused = true)] @@ -2420,12 +2420,11 @@ mod tests { // Track 2 is sent LEAD ahead, and skips a second of its own. let decode = at + LEAD; if !(8_000..9_000).contains(&decode) { - let skip = u64::from(decode >= 9_000); - let frame = Arrival { - skip, - ..arrival(now, decode, "a") - }; - assert_eq!(buffer.push(2, frame).unwrap(), Push::Queued, "at {at} ms"); + assert_eq!( + buffer.push(2, arrival(now, decode, "a")).unwrap(), + Push::Queued, + "at {at} ms" + ); } out.extend(released(&mut buffer)); } @@ -2523,7 +2522,6 @@ mod tests { read: arrived, decode: Timestamp::from_micros(decode.as_micros() as u64).unwrap().into(), restart: 0, - skip: 0, sync: true, leading: false, bytes: 0, @@ -2711,7 +2709,6 @@ mod tests { read: arrived, decode: Timestamp::from_micros(decode.as_micros() as u64).unwrap().into(), restart: 0, - skip: 0, sync: true, leading: false, bytes: 0, @@ -2820,7 +2817,7 @@ mod tests { /// Feed `secs` of 10 fps frames of `shape`'s tracks through its buffer from a source on our /// clock, each sent as it decodes with a few ms of jitter that changes every steering step, - /// whose timeline steps by `step` seconds at `at` s with no restart or skip marker. + /// whose timeline steps by `step` seconds at `at` s with no restart marker. async fn unmarked(shape: &Shape, at: f64, step: f64, secs: f64) -> Stepped { // Where the timeline starts, so a step back stays on it. const BASE: f64 = 20_000.0; @@ -2851,7 +2848,6 @@ mod tests { read: arrived, decode: Timestamp::from_micros((decode * 1e6).round() as u64).unwrap().into(), restart: 0, - skip: 0, sync: true, leading: false, bytes: 0, @@ -3050,17 +3046,16 @@ mod tests { if replay { buffer = buffer.replay(); } - let video = |decode, sync, skip, item| Arrival { + let video = |decode, sync, item| Arrival { sync, - skip, ..arrival(moq_clock::now(), decode, item) }; - buffer.push(1, video(0, true, 0, "v0")).unwrap(); + buffer.push(1, video(0, true, "v0")).unwrap(); tokio::time::advance(Duration::from_millis(40)).await; - buffer.push(1, video(40, false, 0, "v40")).unwrap(); + buffer.push(1, video(40, false, "v40")).unwrap(); // The rest of the group never arrives: the source cuts it short. tokio::time::advance(Duration::from_millis(80)).await; - buffer.push(1, video(120, true, 1, "v120")).unwrap(); + buffer.push(1, video(120, true, "v120")).unwrap(); tokio::time::advance(2 * DELAY).await; assert_eq!(due(&mut buffer), ["v0", "v40", "v120"], "replay {replay}"); assert_eq!((buffer.dropped(), buffer.trimmed()), (0, 0), "replay {replay}");