From 2557eb9c66aff1f7b8151ec651e67aec7d15d17b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 13:25:33 -0800 Subject: [PATCH 1/5] chore(quest): claim quest/m3/hls-listing-lag.md Quest-Claim: 9e2cd3ee780200d7 From 8766802d27547d2374c13d54174ecde5395cbcdb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 13:42:50 -0800 Subject: [PATCH 2/5] fix(moq-hls): list a live segment once its last group passes the next line A group off the grid waited for the next group's start before it was placed, so a segment listed only when the group after its successor started, about one extra GOP late. The export now reads the newest group's frames as they arrive, and places the pending group as soon as one of them passes the next line. Numbering, EXTINF and Grid::starts are unchanged. Also gates Client::is_simulated on the features that use it, which broke `-p moq-hls` test builds under deny-warnings. Finishes quest/m3/hls-listing-lag.md. Co-Authored-By: Claude Opus 5.5 --- quest/m3/hls-listing-lag.md | 59 --------------------- rs/moq-hls/src/export/grid.rs | 85 +++++++++++++++++++++++++++--- rs/moq-hls/src/export/mod.rs | 32 +++++++++++ rs/moq-hls/src/export/rendition.rs | 53 ++++++++++++++++++- rs/moq-tokio/src/quic/backend.rs | 1 + 5 files changed, 161 insertions(+), 69 deletions(-) delete mode 100644 quest/m3/hls-listing-lag.md diff --git a/quest/m3/hls-listing-lag.md b/quest/m3/hls-listing-lag.md deleted file mode 100644 index 3564e3048ba..00000000000 --- a/quest/m3/hls-listing-lag.md +++ /dev/null @@ -1,59 +0,0 @@ -# [M] A live HLS segment is listed once its last group is placed - -## Goal - -A live moq-hls media playlist lists a segment as soon as the export can know -the segment is complete, instead of one group later. On a 2 s GOP whose -timestamps fall off the grid lines, a segment is listed within one group of -its end, not two, and segment numbering stays the same on every edge. - -## Plan - -Measured 2026-11-15 on a live 720p30 RTMP source with a 2 s GOP: the newest -segment appeared in the media playlist about 2 s after its end by -`EXT-X-PROGRAM-DATE-TIME`, while MoQ subscribers received the same frames in -about 130 ms. Every HLS player's delay carries that extra group. - -The cause is the grid rule from -[moq-dev/moq#7652](https://github.com/moq-dev/moq/pull/7652) -(`rs/moq-hls/src/export/grid.rs`): a group belongs to the first grid line it -contains, so placing a group needs its end, the next group's pts, and a -segment completes only when a later group is placed in a later segment. -With groups one interval apart and an arbitrary phase, segment N is placed -when group N+1 starts, but only listed when group N+2 starts. Only a group -starting exactly on a line is placed without its end, and wall-clock -timestamps (RTMP ingest) almost never do. - -The 2x `EXT-X-TARGETDURATION` stays as decided on 2026-11-03 (reaffirmed -2026-11-15, maintainer). This quest changes only when a segment is listed. - -Two approaches: - -- **Bound a group's end early.** A pending group whose frames reach the next - grid line contains it, so it is placed in that line's segment, and the - open segment completes then, without waiting for the next group. Grid - rules, numbering and `Grid::starts` stay as they are. It saves the GOP's - phase against the grid, between 0 and one interval (about 1 s on average - for a random phase); a group starting just after a line saves almost - nothing. It needs the pending group's newest frame pts, which the export - does not read today (it reads only each group's first frame), so the cost - of reading frame timestamps per group is part of the work. -- **Number a group by the slot it starts in** (`floor(pts / length)`). A - segment completes as soon as a group starts in a later slot, so it saves - the whole group. It renumbers segments, which breaks URLs across a mixed - fleet during a roll. It also loses `Grid::starts`: an edge or recorder - joining mid-stream can no longer tell that its first segment is whole - without the group before it. - -Decided 2026-11-15 (maintainer, /quest-plan): ✅ bound a group's end early -(rejected: numbering a group by the slot it starts in). Reason: it keeps the -numbering every edge and recording agrees on, and gives back part of the -delay without a wire or URL change. - -Tests (the grid's unit tests, on a controlled clock): a group whose frames -cross the next line completes the open segment before the next group starts; -a short group that ends before the line still joins the open segment; a -segment's `EXTINF` and number are unchanged from today's for the same groups. - -Public API: none expected. Wire: none. - diff --git a/rs/moq-hls/src/export/grid.rs b/rs/moq-hls/src/export/grid.rs index d20855368fc..3c6d0c63fbc 100644 --- a/rs/moq-hls/src/export/grid.rs +++ b/rs/moq-hls/src/export/grid.rs @@ -9,12 +9,14 @@ //! //! A group spans from its first frame's pts to the next group's. It belongs to one segment: the //! first line it contains, so segment N starts at the group containing pts N × length; or, if it -//! contains none, the line it starts after, `floor(pts / length)`. Groups are never split, since a -//! segment starting mid-GOP is not independent. A grid slot no group starts a segment in, because -//! an overrun or a pause skipped it, is listed as a gap, so the numbering never skips: on a 2s grid, -//! a group A = [0s, 7s) is segment 0, slots 1 and 2 are gaps, and a contiguous B = [7s, 7.2s) -//! starts segment 3. An edge joining at B derives that from B's and its successor's timestamps, -//! without A. +//! contains none, the line it starts after, `floor(pts / length)`. A group off the grid is placed +//! once its successor starts, or sooner once one of its own frames passes the next line, since it +//! then contains that line; the segment before it completes then, not a group later. Groups are +//! never split, since a segment starting mid-GOP is not independent. A grid slot no group starts a +//! segment in, because an overrun or a pause skipped it, is listed as a gap, so the numbering never +//! skips: on a 2s grid, a group A = [0s, 7s) is segment 0, slots 1 and 2 are gaps, and a contiguous +//! B = [7s, 7.2s) starts segment 3. An edge joining at B derives that from B's and its successor's +//! timestamps, without A. //! //! A segment starts at its first group's pts, or at its line when that group starts after it, as //! a group resuming from a pause does, and a gap at its line; its `EXTINF` runs to the next @@ -139,7 +141,8 @@ pub(crate) enum Slot { Reset, } -/// A group seen but not yet placed: placing it needs its end, the next group's pts. +/// A group seen but not yet placed: placing it needs its end, the next group's pts, unless one of +/// its frames passes the next line first. #[derive(Clone, Copy, Debug)] struct Group { start: u64, @@ -171,7 +174,7 @@ impl Open { pub(crate) struct Grid { /// The segment length in nanoseconds, at least one. length: u128, - /// The newest group, until the next one bounds it. + /// The newest group, until the next one bounds it or a frame past the next line places it. pending: Option, open: Option, /// The newest group's pts, which the next must not precede. @@ -295,6 +298,29 @@ impl Grid { out } + /// A frame of the newest group starts at `pts`. Once that is past the line after the group's + /// start, the group contains the line, so it is placed in that line's segment now rather than + /// when its successor starts: the same segment its successor's pts would give it, which starts + /// after all of its frames. Returns the segments it completes. + pub fn reach(&mut self, pts: Timestamp) -> Vec { + let mut out = Vec::new(); + let Some(pending) = self.pending else { + return out; + }; + let slot = super::nanos(pending.pts) / self.length; + if super::nanos(pts) > (slot + 1) * self.length { + self.pending = None; + self.place(pending, slot as u64 + 1, &mut out); + } + out + } + + /// Whether the newest group waits for its end to be placed, which [`reach`](Self::reach) may + /// settle early. + pub fn pending(&self) -> bool { + self.pending.is_some() + } + /// A discontinuity marker at `at` stopped the content: the newest group ends there rather than /// where the next group starts. Returns the segments it completes. pub fn stop(&mut self, at: Timestamp) -> Vec { @@ -611,7 +637,21 @@ mod test { slots.extend(grid.group(sequence as u64, ms(*start))); } slots.extend(grid.finish(Some(ms(end - 1)), Some(ms(end)))); + // Frames read before the next group starts, in any order, list the same + // segments, only sooner. + let mut early = Grid::new(Duration::from_millis(length), 256); + let mut early_slots = Vec::new(); + for (sequence, start) in starts.iter().enumerate().skip(join) { + early_slots.extend(early.group(sequence as u64, ms(*start))); + let until = starts.get(sequence + 1).copied().unwrap_or(end); + for _ in 0..3 { + early_slots.extend(early.reach(ms(start + next(until - start)))); + } + } + early_slots.extend(early.finish(Some(ms(end - 1)), Some(ms(end)))); + let early = listed(early_slots); let listed = listed(slots); + assert_eq!(early, listed, "{interval} ms: {starts:?}"); for (index, (segment, _, start, end)) in listed.iter().enumerate() { let extinf = end - start; let fits = ((extinf as f64) / 1_000.0).round() as u64 <= target; @@ -656,6 +696,35 @@ mod test { [(1, 2..3, 2000, 3500)], "3.5s reaches 4s" ); + + // A frame past the next line settles the newest group without its successor. + let mut grid = Grid::new(Duration::from_secs(2), 256); + assert!(grid.group(0, ms(500)).is_empty()); + assert!( + grid.reach(ms(1900)).is_empty(), + "short of the line, it may still end before it" + ); + assert!( + grid.reach(ms(2000)).is_empty(), + "its successor may still start on the line" + ); + assert!( + grid.reach(ms(2033)).is_empty(), + "it opens segment 1, which nothing completes yet" + ); + assert!(!grid.pending()); + assert!(grid.group(1, ms(2500)).is_empty()); + assert_eq!( + listed(grid.reach(ms(4100))), + [(1, 0..1, 500, 2500)], + "listed at 4.1s rather than when group 2 starts at 4.5s" + ); + assert!(grid.reach(ms(4200)).is_empty(), "already placed"); + assert!(grid.group(2, ms(4500)).is_empty()); + assert_eq!( + listed(grid.finish(Some(ms(5000)), Some(ms(5000)))), + [(2, 1..3, 2500, 5000)] + ); } /// A long pause lists only the newest gaps, the ones a playlist window can still hold. diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 73b5874b379..b2b919706b7 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -4014,6 +4014,38 @@ mod tests { assert!(test.drain_failed("video0").await.is_empty()); } + // A live segment lists once a frame of the group after it passes the next line, not once the + // group after that starts: off the grid, that is a whole GOP sooner. + #[tokio::test(start_paused = true)] + async fn a_segment_lists_once_the_next_group_passes_its_line() { + let test = Groups::with(&["video0"], &[]); + let mut video0 = test.publish("video0"); + let frame = |group: &mut moq_net::group::Producer, pts_ms: u64| { + let frame = vp8_frame(pts_ms * 1_000, false); + hang::container::Frame { + timestamp: frame.timestamp, + payload: frame.payload, + } + .write_to(group) + .unwrap(); + }; + // Group 0 holds line 2s, so it is segment 1; group 1 may still end before line 4s. + video0.at(0, 500); + let mut next = video0.open(1, 2_500); + frame(&mut next, 3_900); + kio::clock::sleep(Duration::from_secs(1)).await; + assert!( + test.rendition("video0").snapshot().segments.is_empty(), + "group 1 may still end before 4s and join segment 1" + ); + + frame(&mut next, 4_100); + let snapshot = test.listed("video0", 1).await; + let listed: Vec<_> = snapshot.segments.iter().map(|s| (s.segment, s.duration)).collect(); + assert_eq!(listed, [(1, Duration::from_millis(2_000))], "group 2 never started"); + drop(next); + } + // A recording refuses a listed segment whose media is gone, but reports a grid slot the // rendition holds nothing for (after an overrun) as a gap that keeps its number, so a recorder // can tell it from rows it missed. diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index e0946ae1b64..87826ac2057 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -2048,7 +2048,8 @@ fn poll_retired(claim: &kio::Consumer, waiter: &kio::Waiter) -> Poll<()> /// track ends or fails. /// /// A segment is listed once a later one starts, which bounds its groups and its `EXTINF`, or once -/// the track ends. A watcher joining mid-segment can't know the groups before its first, so it +/// the track ends. A later one starts with the group after it, as soon as a frame of that group +/// passes the next line, so the newest group's frames are read as they arrive. A watcher joining mid-segment can't know the groups before its first, so it /// lists nothing before the first segment it sees start (see [`grid::Grid::starts`]): another edge /// lists that segment whole, and the same URL must name the same bytes everywhere. struct WatchMedia { @@ -2078,7 +2079,7 @@ enum Step { _track: moq_net::track::Consumer, subscribing: moq_net::track::Subscribing, }, - /// Waiting for the next group. + /// Waiting for the next group, reading the newest one's frames as they arrive. Next, /// Reading a group's first frame, which places it. First(moq_net::group::Consumer), @@ -2107,6 +2108,9 @@ struct Follow { spacing: Option, /// Nothing is listed before the first segment this watcher saw start. whole: bool, + /// Whether the newest group's frames are still read as they arrive, which may place it before + /// its successor starts. + reading: bool, } impl Follow { @@ -2122,6 +2126,7 @@ impl Follow { latest: None, spacing: None, whole: false, + reading: false, } } @@ -2143,6 +2148,7 @@ impl Follow { // grid numbers what resumes by its own timestamps, as every edge does. First::Marker(at) => { self.latest = None; + self.reading = false; (self.grid.stop(at), (group.start, None), None) } First::Media(pts, reach, declared) => { @@ -2151,6 +2157,7 @@ impl Follow { self.spacing = pts.checked_sub(*previous).ok().map(super::span).or(self.spacing); } self.latest = Some((group, pts, reach)); + self.reading = true; (self.grid.group(sequence, pts), (sequence, Some(pts)), declared) } }; @@ -2374,6 +2381,29 @@ impl WatchMedia { if retired() { return Poll::Ready(Ok(())); } + // The newest group's frames that are in may place it before its successor starts. + while follow.reading && follow.grid.pending() { + let Some((group, _, reach)) = follow.latest.as_mut() else { + break; + }; + let pts = match group.poll_read_frame(waiter) { + Poll::Pending => break, + Poll::Ready(Ok(Some(frame))) => match frame_reach(&follow.container, frame, reach) { + Some(pts) => pts, + None => continue, + }, + // Ended or failed: its successor places it, and an ended track reads it + // again for its end, failing there if it failed. + Poll::Ready(Ok(None) | Err(_)) => { + follow.reading = false; + break; + } + }; + let slots = follow.grid.reach(pts); + if let Some(done) = follow.list(&self.rendition, slots, None, None, false) { + return Poll::Ready(done); + } + } let groups = self.groups.as_mut().expect("subscribed above"); match ready!(groups.poll_next_group(waiter))? { Some(group) => self.step = Step::First(group), @@ -2560,6 +2590,25 @@ fn first_frame( Some(First::Media(pts, reach, size)) } +/// Count what a frame after its group's first reaches, and return where it starts on the grid: the +/// transport's stamp, or else its newest sample's, as [`first_frame`] reads a group's start. +fn frame_reach( + container: &moq_mux::catalog::hang::Container, + frame: moq_net::frame::Frame, + reach: &mut Reach, +) -> Option { + use moq_mux::container::Container as _; + let stamp = frame.timestamp; + let decoded = container.decode(frame).ok()?; + let newest = decoded + .iter() + .filter(|sample| !sample.payload.is_empty() && sample.timestamp.scale().is_some()) + .map(|sample| sample.timestamp) + .max_by_key(|pts| pts.as_nanos().ok()); + reach.add(decoded); + if stamp.scale().is_some() { Some(stamp) } else { newest } +} + /// The row listing `slot`, starting a new discontinuity when `broken`. fn row(rendition: &Rendition, slot: grid::Slot, broken: bool) -> segments::Row { let (segment, groups, pts, end, content, stop) = match slot { diff --git a/rs/moq-tokio/src/quic/backend.rs b/rs/moq-tokio/src/quic/backend.rs index 88a23c159d5..a1279c7bf07 100644 --- a/rs/moq-tokio/src/quic/backend.rs +++ b/rs/moq-tokio/src/quic/backend.rs @@ -375,6 +375,7 @@ impl Client { } /// Whether each endpoint binds on a simulated host rather than a UDP socket. + #[cfg(any(feature = "sim", feature = "websocket"))] pub fn is_simulated(&self) -> bool { match self.bind { Bind::Udp(_) => false, From b32ca2014c7dfad149c61824f5d4a7df0c6d08f4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 13:56:03 -0800 Subject: [PATCH 3/5] fix(moq-hls): place by the newest sample, first frame included, in bounded memory A group carried whole in one CMAF fragment passes the next line in its first frame, so place it from the first frame's samples too, and from each later frame's samples through the same Reach the track's end reads. Reach now folds all but its newest 64 stamps into the shortest spacing, so a group read as it arrives costs bounded memory however long it runs. Co-Authored-By: Claude Opus 5.5 --- rs/moq-hls/src/export/mod.rs | 33 +++++++++++ rs/moq-hls/src/export/rendition.rs | 94 +++++++++++++++++++++--------- 2 files changed, 100 insertions(+), 27 deletions(-) diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index b2b919706b7..2b89db0829f 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -4044,6 +4044,39 @@ mod tests { let listed: Vec<_> = snapshot.segments.iter().map(|s| (s.segment, s.duration)).collect(); assert_eq!(listed, [(1, Duration::from_millis(2_000))], "group 2 never started"); drop(next); + + // A CMAF group carried whole in one fragment passes the line in its first frame. + let muxer = moq_mux::container::fmp4::Muxer::video(&video_config()).unwrap(); + let mut config = video_config(); + config.container = hang::catalog::Container::Cmaf { + init: muxer.init().unwrap().expect("a VP8 init from the coded size"), + }; + let mut catalog = joined(); + catalog.media.join = hang::catalog::Join::new(INTERVAL); + catalog.video.renditions.insert("video0".to_string(), config); + let broadcast = moq_net::broadcast::Info::new().produce(); + let test = Groups { + renditions: Groups::export(&broadcast, &catalog), + broadcast, + catalog, + }; + let track = test.broadcast.create_track("video0", timed()).unwrap(); + // Samples 100ms apart from `pts_ms` up to `last_ms`, in one fragment. + let fragment = |sequence: u64, pts_ms: u64, last_ms: u64| { + let frames: Vec<_> = (pts_ms..=last_ms) + .step_by(100) + .map(|ms| vp8_frame(ms * 1_000, ms == pts_ms)) + .collect(); + let mut group = track.create_group(moq_net::group::Info { start: sequence }).unwrap(); + let bytes = muxer.fragment(sequence as u32, &frames, None).unwrap(); + group.write_frame(frames[0].timestamp, bytes).unwrap(); + group.close().unwrap(); + }; + fragment(0, 500, 2_400); + fragment(1, 2_500, 4_400); + let snapshot = test.listed("video0", 1).await; + let listed: Vec<_> = snapshot.segments.iter().map(|s| (s.segment, s.duration)).collect(); + assert_eq!(listed, [(1, Duration::from_millis(2_000))], "group 2 never started"); } // A recording refuses a listed segment whose media is gone, but reports a grid slot the diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 87826ac2057..4942ccc9e9b 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -2156,9 +2156,14 @@ impl Follow { if let Some((_, previous, _)) = &self.latest { self.spacing = pts.checked_sub(*previous).ok().map(super::span).or(self.spacing); } + let mut slots = self.grid.group(sequence, pts); + // A fragment carrying the whole group may already pass the next line. + if let Some(newest) = reach.newest() { + slots.extend(self.grid.reach(newest)); + } self.latest = Some((group, pts, reach)); self.reading = true; - (self.grid.group(sequence, pts), (sequence, Some(pts)), declared) + (slots, (sequence, Some(pts)), declared) } }; self.list(rendition, slots, Some(read), size, false) @@ -2386,20 +2391,25 @@ impl WatchMedia { let Some((group, _, reach)) = follow.latest.as_mut() else { break; }; - let pts = match group.poll_read_frame(waiter) { + match group.poll_read_frame(waiter) { Poll::Pending => break, - Poll::Ready(Ok(Some(frame))) => match frame_reach(&follow.container, frame, reach) { - Some(pts) => pts, - None => continue, - }, + Poll::Ready(Ok(Some(frame))) => { + // The container says what a frame holds, as `Step::End` reads it. + if let Ok(decoded) = moq_mux::container::Container::decode(&*follow.container, frame) { + reach.add(decoded); + } + } // Ended or failed: its successor places it, and an ended track reads it // again for its end, failing there if it failed. Poll::Ready(Ok(None) | Err(_)) => { follow.reading = false; break; } + } + let Some(newest) = reach.newest() else { + continue; }; - let slots = follow.grid.reach(pts); + let slots = follow.grid.reach(newest); if let Some(done) = follow.list(&self.rendition, slots, None, None, false) { return Poll::Ready(done); } @@ -2492,8 +2502,10 @@ impl kio::Task for WatchMedia { /// discontinuity marker, read as they are decoded. #[derive(Default)] struct Reach { - /// Each sample's pts, in nanoseconds. + /// The newest samples' pts, in nanoseconds, at most twice [`Reach::KEEP`]. stamps: Vec, + /// The shortest spacing between the samples folded out of `stamps`. + step: Option, /// The latest end a sample states with its own duration, in nanoseconds. ends: Option, /// A frame with no payload: where the publisher says the content stops. @@ -2501,6 +2513,10 @@ struct Reach { } impl Reach { + /// The newest distinct stamps kept when folding, well past any reordering a codec does, so a + /// group read as its frames arrive costs bounded memory however long it runs. + const KEEP: usize = 64; + /// Count every sample `frames` decodes to. fn add(&mut self, frames: Vec) { for frame in frames { @@ -2517,6 +2533,28 @@ impl Reach { self.ends = self.ends.max(Some(pts + duration)); } } + if self.stamps.len() > 2 * Self::KEEP { + self.fold(); + } + } + + /// Fold all but the newest [`Reach::KEEP`] distinct stamps into the shortest spacing. + fn fold(&mut self) { + self.stamps.sort_unstable(); + self.stamps.dedup(); + let older = self.stamps.len().saturating_sub(Self::KEEP); + let step = self.stamps[..(older + 1).min(self.stamps.len())] + .windows(2) + .map(|pair| pair[1] - pair[0]) + .min(); + self.step = self.step.into_iter().chain(step).min(); + self.stamps.drain(..older); + } + + /// The newest sample's pts, which places a pending group once it passes the next line. + fn newest(&self) -> Option { + let newest = self.stamps.iter().max()?; + moq_net::Timestamp::from_nanos(u64::try_from(*newest).ok()?).ok() } /// Where the last sample starts, which places the group on the grid, and where the content @@ -2543,6 +2581,7 @@ impl Reach { .stamps .windows(2) .map(|pair| pair[1] - pair[0]) + .chain(self.step) .min() .or_else(|| spacing.map(|spacing| spacing.min(interval).as_nanos())); let end = self @@ -2590,25 +2629,6 @@ fn first_frame( Some(First::Media(pts, reach, size)) } -/// Count what a frame after its group's first reaches, and return where it starts on the grid: the -/// transport's stamp, or else its newest sample's, as [`first_frame`] reads a group's start. -fn frame_reach( - container: &moq_mux::catalog::hang::Container, - frame: moq_net::frame::Frame, - reach: &mut Reach, -) -> Option { - use moq_mux::container::Container as _; - let stamp = frame.timestamp; - let decoded = container.decode(frame).ok()?; - let newest = decoded - .iter() - .filter(|sample| !sample.payload.is_empty() && sample.timestamp.scale().is_some()) - .map(|sample| sample.timestamp) - .max_by_key(|pts| pts.as_nanos().ok()); - reach.add(decoded); - if stamp.scale().is_some() { Some(stamp) } else { newest } -} - /// The row listing `slot`, starting a new discontinuity when `broken`. fn row(rendition: &Rendition, slot: grid::Slot, broken: bool) -> segments::Row { let (segment, groups, pts, end, content, stop) = match slot { @@ -3180,6 +3200,26 @@ mod tests { millis(reach.finish(None, Duration::from_secs(2))), (Some(500), Some(500)) ); + + // A long group read as it arrives keeps a bounded tail, yet times its end as if whole, + // however its samples are reordered or repeated. + let mut reach = Reach::default(); + for ms in (0..10_000u64).step_by(40) { + let reordered = if ms % 120 == 40 { + ms + 40 + } else if ms % 120 == 80 { + ms - 40 + } else { + ms + }; + reach.add(vec![sample(reordered, None, b"x"), sample(reordered, None, b"x")]); + assert!(reach.stamps.len() <= 2 * Reach::KEEP + 2); + } + assert_eq!(reach.newest().map(|t| t.as_millis().unwrap()), Some(9_960)); + assert_eq!( + millis(reach.finish(None, Duration::from_secs(2))), + (Some(9_960), Some(10_000)) + ); } // A jump in the numbering, from segments skipped across a hand-over, drops the inherited rows From 7320c098c5891f1880a92df952f1f82188ab8697 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 14:11:55 -0800 Subject: [PATCH 4/5] doc(moq-hls): an overlapping keyframe across a line can split one segment across edges Accepted by the maintainer on 2026-11-15, in exchange for listing every off-grid segment up to a group sooner. Co-Authored-By: Claude Opus 5.5 --- doc/bin/hls.md | 2 +- rs/moq-hls/src/export/grid.rs | 9 +++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/bin/hls.md b/doc/bin/hls.md index 6d0576b8149..1f6ff858e0a 100644 --- a/doc/bin/hls.md +++ b/doc/bin/hls.md @@ -58,7 +58,7 @@ What that means for you: - **Every rendition shares the grid.** A group spans from its first frame's timestamp to the next group's and belongs to the first grid line it contains, or, containing none, the line it starts after. Segment N therefore starts at the group containing N times the segment length, every rendition numbers its segments alike, and each cuts its boundaries at its own keyframes. A grid line no group starts a segment at, because a GOP ran past it or the content paused, is listed as an `EXT-X-GAP` so the numbering never skips: on a 2 s grid, a GOP from 0 to 7 s is segment 0, segments 1 and 2 are gaps, and the next GOP starts segment 3. Timestamps that go back start a discontinuity on that rendition alone; `EXT-X-PROGRAM-DATE-TIME`, written after every discontinuity when the catalog has a clock, lets players resync. - **Include media starts on selection.** The HTTP multivariant playlist reads each root `include` entry's catalog and lists its audio and video beside the broadcast's own. An include shares the broadcast's timeline: its renditions are segmented on the broadcast's join interval and clock, whatever its own catalog declares, so publish it on the same timestamps. One not yet routed is listed once its broadcast is announced. Reading its catalog starts no encoding: only a request to one of its rendition URLs subscribes to that rendition's media. Demand lasts through active responses and, after the last one finishes, for three target durations or the playlist window plus one target duration, whichever is longer (20 s by default); a later request starts it again. The broadcast's own renditions stay subscribed. A segment is servable for as long as the relay's [cache](/bin/relay/config#cache) retains it. Keep `--window` (the playlist length, default 16 s) within that retention and within the media's max age (30 s by default), after which a superseded segment's groups are stale. - **Live joins cost the window.** The exporter subscribes 30 s behind the live edge and lists at most 256 segments. One joining partway through a segment lists nothing before the first segment it sees start. -- **Segments are timed by the grid.** A segment is listed once a later one starts or the track ends. It starts at its first group's timestamp, or at its line when that group starts after it (as one resuming from a pause does), or a gap at its line, and lasts until the next segment starts, so a segment's bytes never change with a catalog estimate. A GOP longer than the segment is listed at its first line, so its duration understates its media. +- **Segments are timed by the grid.** A segment is listed once a later one starts or the track ends. A GOP that starts off a line is placed as soon as one of its frames passes the next line, without waiting for the next keyframe, so the segment before it lists then. A keyframe may overlap the previous GOP's last frames (a TS content join does), so when that overlap straddles a line, an edge that saw the earlier GOP lists it in the line's segment, while an edge that joined at the overlapping keyframe lists that segment without it. This one segment differs across edges, for that broadcast only (accepted, 2026-11-15). It starts at its first group's timestamp, or at its line when that group starts after it (as one resuming from a pause does), or a gap at its line, and lasts until the next segment starts, so a segment's bytes never change with a catalog estimate. A GOP longer than the segment is listed at its first line, so its duration understates its media. - **The target duration is twice the segment.** Every media playlist keeps one `EXT-X-TARGETDURATION` while its rendition stays in the catalog, even across a reconfigure: twice the segment length, rounded up to whole seconds (twice the interval for a GOP of a second or more, 2 s for 20 ms audio groups), since the GOP containing a grid line starts at most one interval before it, and a gap ends under two segment lengths after its line. Only a final GOP longer than that is listed past it, against RFC 8216's rule: hls.js plays it, but Apple's `mediastreamvalidator` flags it, so keep keyframe intervals within the declared interval. - **A reconfigure keeps the playlist.** A rendition whose decoder config changes (its resolution, say) keeps its media playlist: the segments already listed stay, under the init they were muxed for, and the new config's segments follow behind an `EXT-X-DISCONTINUITY` and a new `EXT-X-MAP`, as RFC 8216 requires. The old config's segments end at the keyframe declaring the new size, even when that group reaches the export before the catalog update. A resize that opens a segment lists that segment under the new init. One partway through a segment cuts the old config's last segment short there, and the new config lists from the next segment, so the media between them is never listed. The DASH manifest lists only the new config's segments. - **Disabled renditions are hidden.** A rendition the catalog marks `enabled: false` leaves the multivariant playlist and DASH manifest until it re-enables. Its media playlist keeps serving, so a player already on it is not ended with `EXT-X-ENDLIST`. diff --git a/rs/moq-hls/src/export/grid.rs b/rs/moq-hls/src/export/grid.rs index 3c6d0c63fbc..650e893fb29 100644 --- a/rs/moq-hls/src/export/grid.rs +++ b/rs/moq-hls/src/export/grid.rs @@ -11,8 +11,13 @@ //! first line it contains, so segment N starts at the group containing pts N × length; or, if it //! contains none, the line it starts after, `floor(pts / length)`. A group off the grid is placed //! once its successor starts, or sooner once one of its own frames passes the next line, since it -//! then contains that line; the segment before it completes then, not a group later. Groups are -//! never split, since a segment starting mid-GOP is not independent. A grid slot no group starts a +//! then contains that line unless its successor overlaps it; the segment before it completes then, +//! not a group later. A keyframe may overlap the previous group's last frames (a TS content join +//! does), so when that overlap straddles a line, an edge that saw the earlier group lists it in the +//! line's segment while one that joined at the overlapping group lists that segment without it. +//! That one segment differs across edges, for that broadcast alone (accepted by the maintainer, +//! 2026-11-15, for listing every off-grid segment up to a group sooner). Groups are never split, +//! since a segment starting mid-GOP is not independent. A grid slot no group starts a //! segment in, because an overrun or a pause skipped it, is listed as a gap, so the numbering never //! skips: on a 2s grid, a group A = [0s, 7s) is segment 0, slots 1 and 2 are gaps, and a contiguous //! B = [7s, 7.2s) starts segment 3. An edge joining at B derives that from B's and its successor's From c6e0e21a2ab83d50aae166a3b06804d93bc83c4d Mon Sep 17 00:00:00 2001 From: quest fixer Date: Mon, 16 Nov 2026 02:15:20 -0800 Subject: [PATCH 5/5] fix(moq-tokio): remove stale feature gate from simulation query --- rs/moq-tokio/src/quic/backend.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/rs/moq-tokio/src/quic/backend.rs b/rs/moq-tokio/src/quic/backend.rs index 7a1ec0e708e..7112ef0dcb0 100644 --- a/rs/moq-tokio/src/quic/backend.rs +++ b/rs/moq-tokio/src/quic/backend.rs @@ -366,7 +366,6 @@ impl Client { } /// Whether each endpoint binds on a simulated host rather than a UDP socket. - #[cfg(any(feature = "sim", feature = "websocket"))] pub fn is_simulated(&self) -> bool { match self.bind { Bind::Udp(_) => false,