From 008c1c3e2c5f516fbb4d3e531f7579a6391975e8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 21:02:11 -0800 Subject: [PATCH 1/7] chore(quest): claim quest/m2/time-addressing/start-placement.md Quest-Claim: 55644b69c3a2b7fb From d4d2787124f9f7208e475828514250af4496cbad Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 21:12:20 -0800 Subject: [PATCH 2/7] moq-hls: place each group on the grid by its start Co-Authored-By: Claude Opus 5.5 --- rs/moq-hls/src/export/grid.rs | 11 +- rs/moq-hls/src/export/mod.rs | 186 ++++++++++++++++------------- rs/moq-hls/src/export/rendition.rs | 31 +++-- 3 files changed, 125 insertions(+), 103 deletions(-) diff --git a/rs/moq-hls/src/export/grid.rs b/rs/moq-hls/src/export/grid.rs index d0e8a6cfdb5..6f6a4274b37 100644 --- a/rs/moq-hls/src/export/grid.rs +++ b/rs/moq-hls/src/export/grid.rs @@ -7,9 +7,10 @@ //! Every rendition numbers its segments on it, so they share segment numbers while each cuts its //! boundaries at its own groups. //! -//! 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)`. A group off the grid is placed +//! A group spans from its start to the next group's: its key on a timed track, or its first +//! frame's pts where the session carries no timeline. 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(start / 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 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 @@ -23,7 +24,7 @@ //! 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 segment starts at its first group's start, 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 //! segment's start. Every segment then starts after the line before its own and ends at or before //! the next, so every `EXTINF` fits twice the segment length, the target duration. A group overrunning the segment length is listed at its first line, so its @@ -279,7 +280,7 @@ impl Grid { Timestamp::from_nanos(u64::try_from(nanos).unwrap_or(u64::MAX)).unwrap_or(Timestamp::ZERO) } - /// The group keyed `start` has its first frame at `pts`, after every group already fed. Returns + /// The group keyed `start` is placed at `pts`, after every group already fed. Returns /// the segments it completes. pub fn group(&mut self, start: u64, pts: Timestamp) -> Vec { let mut out = Vec::new(); diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 604e3ac7300..cb00cb474fa 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -1506,8 +1506,7 @@ mod tests { // Closed groups follow, and transmuxing one caches the init. for group in 2..5 { - let mut writing = media.create_group(group.into()).unwrap(); - write_keyframe(&mut writing, group); + let writing = keyframe_group(&media, group); writing.finish().unwrap(); } until_listed(&rendition, 4).await; @@ -1580,22 +1579,22 @@ mod tests { sequence: u64, ) -> (moq_net::track::Producer, moq_net::group::Producer) { let media = broadcast.create_track(name, timed()).unwrap(); - let mut open = media.create_group(sequence.into()).unwrap(); - write_keyframe(&mut open, sequence); - let mut next = media.create_group((sequence + 1).into()).unwrap(); - write_keyframe(&mut next, sequence + 1); + let open = keyframe_group(&media, sequence); + let next = keyframe_group(&media, sequence + 1); next.finish().unwrap(); (media, open) } - /// Write one VP8 keyframe at [`Gops::gop`] `sequence`'s pts into `group`. - fn write_keyframe(group: &mut moq_net::group::Producer, sequence: u64) { + /// Open the group of [`Gops::gop`] `index` on `media`, holding one VP8 keyframe at its start. + fn keyframe_group(media: &moq_net::track::Producer, index: u64) -> moq_net::group::Producer { + let mut group = media.create_group((index * 2_000).into()).unwrap(); hang::container::Frame { - timestamp: moq_net::Timestamp::from_millis(sequence * 2_000).unwrap(), + timestamp: moq_net::Timestamp::from_millis(index * 2_000).unwrap(), payload: bytes::Bytes::from_static(KEYFRAME), } - .write_to(group) + .write_to(&mut group) .unwrap(); + group } /// Wait until `rendition` lists at least `count` segments. @@ -1631,12 +1630,10 @@ mod tests { let (origin, broadcast, _catalog, _video0) = inline_sibling().await; let media = broadcast.broadcast().create_track("video1", timed()).unwrap(); for sequence in 0..3 { - let mut group = media.create_group(sequence.into()).unwrap(); - write_keyframe(&mut group, sequence); + let group = keyframe_group(&media, sequence); group.finish().unwrap(); } - let mut open = media.create_group(3u64.into()).unwrap(); - write_keyframe(&mut open, 3); + let open = keyframe_group(&media, 3); let broadcaster = Broadcaster::spawned(crate::resolved(&origin, "live").await, Config::default()); broadcaster.advertised().await; @@ -1870,8 +1867,7 @@ mod tests { ); for sequence in 0..3 { - let mut group = media.create_group(sequence.into()).unwrap(); - write_keyframe(&mut group, sequence); + let group = keyframe_group(&media, sequence); group.finish().unwrap(); } kio::clock::timeout(Duration::from_secs(1), waiting) @@ -1888,8 +1884,7 @@ mod tests { .unwrap(); let media = broadcast.broadcast().create_track("video1", timed()).unwrap(); for sequence in 0..4 { - let mut group = media.create_group(sequence.into()).unwrap(); - write_keyframe(&mut group, sequence); + let group = keyframe_group(&media, sequence); group.finish().unwrap(); } @@ -2789,6 +2784,37 @@ mod tests { drop((audio, catalog, broadcast)); } + // A group is placed on the grid by its start, not its first frame: groups keyed on the lines' + // 500ms multiples whose keyframes land 100ms later still cut 2s segments at the lines. + #[tokio::test] + async fn a_group_is_placed_by_its_start() { + let origin = produce_origin(); + let broadcast = origin + .route("live", moq_net::origin::RouteOptions::default()) + .expect("publish allowed"); + settle().await; + let catalog = hls_catalog(&mut broadcast.broadcast().clone()); + let mut audio = audio(&catalog, broadcast.broadcast(), "audio0", opus()); + for millis in (0..=6_000u64).step_by(500) { + audio.seek(millis).unwrap(); + audio.write(frame((millis + 100) * 1000, true)).unwrap(); + } + audio.cut(None).unwrap(); + + let broadcaster = Broadcaster::spawned(crate::resolved(&origin, "live").await, Config::default()); + let _ = kio::clock::timeout(Duration::from_secs(5), broadcaster.ready()).await; + let rendition = broadcaster.rendition(Kind::Audio, "audio0").expect("audio discovered"); + let _ = kio::clock::timeout(Duration::from_secs(5), rendition.playable()).await; + + let playlist = rendition.snapshot(); + assert_eq!(numbers(&playlist), [0, 1, 2]); + for segment in &playlist.segments { + assert_eq!(segment.duration, Duration::from_secs(2), "segment {}", segment.segment); + } + + drop((audio, catalog, broadcast)); + } + // Audio and video renditions whose groups start on the same grid lines cut the same // boundaries, with no state shared between them. Video is one group per segment; an audio // segment packs every audio group inside the video segment's span. @@ -3624,13 +3650,10 @@ mod tests { } impl Gops { - /// Write group `sequence` with a keyframe at `pts_ms` and, when `frames` is more than one, - /// that many frames a tenth of the interval apart. - fn group(&mut self, sequence: u64, pts_ms: u64, frames: u64) { - let mut group = self - .track - .create_group(moq_net::group::Info { start: sequence }) - .unwrap(); + /// Write the group starting at `pts_ms` with a keyframe there and, when `frames` is more + /// than one, that many frames a tenth of the interval apart. + fn group(&mut self, pts_ms: u64, frames: u64) { + let mut group = self.track.create_group(moq_net::group::Info { start: pts_ms }).unwrap(); for index in 0..frames.max(1) { let micros = (pts_ms + index * INTERVAL.as_millis() as u64 / 10) * 1_000; let frame = vp8_frame(micros, index == 0); @@ -3644,18 +3667,15 @@ mod tests { group.finish().unwrap(); } - /// Write group `sequence` at `pts_ms` with a single keyframe. - fn at(&mut self, sequence: u64, pts_ms: u64) { - self.group(sequence, pts_ms, 1); + /// Write the group at `pts_ms` with a single keyframe. + fn at(&mut self, pts_ms: u64) { + self.group(pts_ms, 1); } - /// Write group `sequence` at `pts_ms` with a single keyframe declaring a `width`x`height` + /// Write the group at `pts_ms` with a single keyframe declaring a `width`x`height` /// picture in band. - fn sized(&mut self, sequence: u64, pts_ms: u64, (width, height): (u16, u16)) { - let mut group = self - .track - .create_group(moq_net::group::Info { start: sequence }) - .unwrap(); + fn sized(&mut self, pts_ms: u64, (width, height): (u16, u16)) { + let mut group = self.track.create_group(moq_net::group::Info { start: pts_ms }).unwrap(); let mut payload = KEYFRAME.to_vec(); payload[6..8].copy_from_slice(&width.to_le_bytes()); payload[8..10].copy_from_slice(&height.to_le_bytes()); @@ -3668,17 +3688,14 @@ mod tests { group.finish().unwrap(); } - /// Write group `sequence` at `2 * sequence` seconds: one GOP per grid line. - fn gop(&mut self, sequence: u64) { - self.at(sequence, sequence * INTERVAL.as_millis() as u64); + /// Write the `index`th GOP at `2 * index` seconds: one GOP per grid line. + fn gop(&mut self, index: u64) { + self.at(index * INTERVAL.as_millis() as u64); } - /// Start group `sequence` at `pts_ms` with a keyframe, leaving it open for more frames. - fn open(&mut self, sequence: u64, pts_ms: u64) -> moq_net::group::Producer { - let mut group = self - .track - .create_group(moq_net::group::Info { start: sequence }) - .unwrap(); + /// Start the group at `pts_ms` with a keyframe, leaving it open for more frames. + fn open(&mut self, pts_ms: u64) -> moq_net::group::Producer { + let mut group = self.track.create_group(moq_net::group::Info { start: pts_ms }).unwrap(); let frame = vp8_frame(pts_ms * 1_000, true); hang::container::Frame { timestamp: frame.timestamp, @@ -4028,8 +4045,8 @@ mod tests { .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); + video0.at(500); + let mut next = video0.open(2_500); frame(&mut next, 3_900); kio::clock::sleep(Duration::from_secs(1)).await; assert!( @@ -4065,7 +4082,7 @@ mod tests { .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 mut group = track.create_group(moq_net::group::Info { start: pts_ms }).unwrap(); let bytes = muxer.fragment(sequence as u32, &frames, None).unwrap(); group.write_frame(frames[0].timestamp, bytes).unwrap(); group.finish().unwrap(); @@ -4085,15 +4102,15 @@ mod tests { let test = Groups::new(); let mut video0 = test.publish("video0"); let mut video1 = test.publish("video1"); - video0.at(0, 0); - video0.at(1, 2_000); - let lost = video0.open(2, 2_500); - video0.at(3, 3_000); - video0.at(4, 4_000); + video0.at(0); + video0.at(2_000); + let lost = video0.open(2_500); + video0.at(3_000); + video0.at(4_000); video0.finish(); // A group running from 0 to 7s overruns slots 1 and 2. - video1.at(0, 0); - video1.at(1, 7_000); + video1.at(0); + video1.at(7_000); video1.finish(); test.finished("video0").await; // Group 2 fails once listed, so segment 1, from groups 1 to 3, can't be served whole. @@ -4140,8 +4157,8 @@ mod tests { for sequence in 0..5 { video0.gop(sequence); } - for (sequence, pts) in [(0, 5_500), (1, 8_000), (2, 10_000)] { - audio0.at(sequence, pts); + for pts in [5_500, 8_000, 10_000] { + audio0.at(pts); } assert_eq!(numbers(&test.listed("video0", 3).await), [0, 1, 2, 3]); let audio = test.listed("audio0", 4).await; @@ -4206,8 +4223,8 @@ mod tests { let mut video0 = test.publish("video0"); video0.gop(0); video0.gop(1); - video0.at(2, 10_000); - video0.at(3, 12_000); + video0.at(10_000); + video0.at(12_000); let snapshot = test.listed("video0", 5).await; assert_eq!(numbers(&snapshot), [0, 1, 2, 3, 4, 5]); @@ -4506,8 +4523,8 @@ mod tests { // The old track ends, completing the segment its rendition was waiting on. records.finish(); let mut fresh = test.publish("video0b"); - for (sequence, gop) in (0..).zip(4..7) { - fresh.at(sequence, gop * INTERVAL.as_millis() as u64); + for gop in 4..7 { + fresh.at(gop * INTERVAL.as_millis() as u64); } let snapshot = test.listed("video0", 5).await; assert_eq!(numbers(&snapshot), [0, 1, 2, 3, 4, 5]); @@ -4524,7 +4541,7 @@ mod tests { let mut media = test.publish("video0"); // Four groups to a two-second slot: 0-3 are segment 0, and 4 and 5 open segment 1. for sequence in 0..6 { - media.at(sequence, sequence * 500); + media.at(sequence * 500); } test.listed("video0", 0).await; kio::clock::sleep(Duration::from_millis(100)).await; @@ -4534,19 +4551,19 @@ mod tests { let new = test.rendition("video0"); // 6 and 7 finish segment 1 past the retire; 8 to 11 are segment 2, which 12 completes. for sequence in 6..13 { - media.at(sequence, sequence * 500); + media.at(sequence * 500); } let snapshot = test.listed("video0", 2).await; assert_eq!(numbers(&snapshot), [0, 1, 2], "no segment is lost to the hand-over"); let tags: Vec<_> = snapshot.segments.iter().map(|s| s.tag.as_str()).collect(); // The predecessor's part is a cut, named by where it ends. - let cut = segments::cut(old.tag(), Some(5), Duration::from_secs(3)); + let cut = segments::cut(old.tag(), Some(2_500), Duration::from_secs(3)); assert_eq!(tags, [old.tag(), &cut, new.tag()]); let durations: Vec<_> = snapshot.segments.iter().map(|s| s.duration.as_millis()).collect(); assert_eq!( durations, [2_000, 1_000, 2_000], - "the predecessor's part ends at group 6" + "the predecessor's part ends at the group at 3s" ); let id = segments::Id { generation: None, @@ -4572,7 +4589,7 @@ mod tests { test.listed("video0", 1).await; let old = test.rendition("video0"); // Group 3 opens segment 3 at 640x480 before the catalog says so. - media.sized(3, 6_000, (640, 480)); + media.sized(6_000, (640, 480)); kio::clock::sleep(Duration::from_millis(100)).await; let config = test.catalog.video.renditions.get_mut("video0").unwrap(); config.coded_width = Some(640); @@ -4580,8 +4597,8 @@ mod tests { test.sync(); let new = test.rendition("video0"); kio::clock::sleep(Duration::from_millis(100)).await; - media.sized(4, 8_000, (640, 480)); - media.sized(5, 10_000, (640, 480)); + media.sized(8_000, (640, 480)); + media.sized(10_000, (640, 480)); let snapshot = test.listed("video0", 4).await; assert_eq!(numbers(&snapshot), [0, 1, 2, 3, 4]); let tags: Vec<_> = snapshot.segments.iter().map(|s| s.tag.as_str()).collect(); @@ -4598,11 +4615,11 @@ mod tests { let mut media = test.publish("video0"); // Four groups to a two-second slot: 0-3 are segment 0, and 4 and 5 open segment 1. for sequence in 0..6 { - media.at(sequence, sequence * 500); + media.at(sequence * 500); } test.listed("video0", 0).await; let old = test.rendition("video0"); - media.sized(6, 3_000, (640, 480)); + media.sized(3_000, (640, 480)); kio::clock::sleep(Duration::from_millis(100)).await; let config = test.catalog.video.renditions.get_mut("video0").unwrap(); config.coded_width = Some(640); @@ -4610,18 +4627,18 @@ mod tests { test.sync(); let new = test.rendition("video0"); for sequence in 7..13 { - media.sized(sequence, sequence * 500, (640, 480)); + media.sized(sequence * 500, (640, 480)); } let snapshot = test.listed("video0", 2).await; assert_eq!(numbers(&snapshot), [0, 1, 2]); let tags: Vec<_> = snapshot.segments.iter().map(|s| s.tag.as_str()).collect(); - let cut = segments::cut(old.tag(), Some(5), Duration::from_secs(3)); + let cut = segments::cut(old.tag(), Some(2_500), Duration::from_secs(3)); assert_eq!(tags, [old.tag(), &cut, new.tag()]); let durations: Vec<_> = snapshot.segments.iter().map(|s| s.duration.as_millis()).collect(); assert_eq!( durations, [2_000, 1_000, 2_000], - "the predecessor's part ends at group 6" + "the predecessor's part ends at the group at 3s" ); } @@ -4631,7 +4648,7 @@ mod tests { async fn a_segment_too_many_groups_long_is_a_gap() { let test = Groups::with(&["video0"], &[]); // Groups a microsecond apart: millisecond ones can't outnumber the cap in one segment. - let mut media = Gops { + let media = Gops { track: test .broadcast .create_track("video0", timed().with_timescale(moq_net::Timescale::MICRO)) @@ -4643,9 +4660,10 @@ mod tests { INTERVAL.as_millis() as u64, "one group per millisecond of the interval" ); - for sequence in 0..=cap { - let mut group = media.track.create_group(sequence.into()).unwrap(); - let frame = vp8_frame(sequence, true); + // Then two groups on the next lines, at 2s and 4s. + for start in (0..=cap).chain([2_000_000, 4_000_000]) { + let mut group = media.track.create_group(start.into()).unwrap(); + let frame = vp8_frame(start, true); hang::container::Frame { timestamp: frame.timestamp, payload: frame.payload, @@ -4654,8 +4672,6 @@ mod tests { .unwrap(); group.finish().unwrap(); } - media.at(cap + 1, 2_000); - media.at(cap + 2, 4_000); let snapshot = test.listed("video0", 1).await; assert_eq!(numbers(&snapshot), [0, 1]); assert_eq!(gaps(&snapshot), [0]); @@ -4668,7 +4684,7 @@ mod tests { let test = Groups::with(&["video0"], &[]); let mut media = test.publish("video0"); media.gop(0); - let last = media.open(1, 2_000); + let last = media.open(2_000); media.finish(); // The track has ended, so the watcher reads the last group for its content's end. kio::clock::sleep(Duration::from_millis(100)).await; @@ -4700,7 +4716,7 @@ mod tests { let mut media = test.publish("audio0"); for sequence in 0..groups { - media.at(sequence, sequence * interval); + media.at(sequence * interval); } let snapshot = test.listed("audio0", 1).await; assert!(gaps(&snapshot).is_empty(), "{interval} ms"); @@ -4720,8 +4736,8 @@ mod tests { // it is segment 2, and gap 1 runs from line 1 to 5990 ms. let test = Groups::joined(&["video0"], &[], Duration::from_millis(999)); let mut media = test.publish("video0"); - for (sequence, pts) in [0, 5_990, 5_994, 7_992].into_iter().enumerate() { - media.at(sequence as u64, pts); + for pts in [0, 5_990, 5_994, 7_992] { + media.at(pts); } let snapshot = test.listed("video0", 3).await; assert_eq!(gaps(&snapshot), [1]); @@ -4762,7 +4778,7 @@ mod tests { let mut records = test.publish("video0"); records.gop(0); // 25 frames 200ms apart: the last starts at 6.8s, so the content runs to 7s. - records.group(1, 2_000, 25); + records.group(2_000, 25); records.finish(); let snapshot = test.finished("video0").await; let durations: Vec<_> = snapshot.segments.iter().map(|s| s.duration.as_millis()).collect(); @@ -4811,18 +4827,18 @@ mod tests { let mut video0 = early.publish("video0"); // Two groups a segment: segment 3 opens at group 6. for sequence in 0..7 { - video0.at(sequence, sequence * 1_000); + video0.at(sequence * 1_000); settle().await; } let retired = [&mut early, &mut late].map(|edge| edge.rendition("video0")); early.catalog.video.renditions.remove("video0"); early.sync(); - video0.at(7, 7_000); + video0.at(7_000); settle().await; late.catalog.video.renditions.remove("video0"); late.sync(); for sequence in 8..10 { - video0.at(sequence, sequence * 1_000); + video0.at(sequence * 1_000); settle().await; } diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 85b0aa45f26..95ae0fc0d16 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -2130,16 +2130,18 @@ impl Follow { } } - /// Place a group by its first frame and list what that places; `Some` once the watch is done. + /// Place a group by its start and list what that places; `Some` once the watch is done. fn first( &mut self, rendition: &Weak, group: moq_net::group::Consumer, first: Option, ) -> Option> { - // A group's place is its first frame's pts: the transport's stamp, or the container's own - // where the session carries none. - let Some(first) = first.and_then(|frame| first_frame(&self.container, frame, self.probe.as_mut())) else { + // A group's place is its start, or its first frame's container pts where the session + // carries no timeline. + let Some(first) = + first.and_then(|frame| first_frame(&self.container, group.start, frame, self.probe.as_mut())) + else { tracing::warn!(track = %self.track, group = group.start, "skipping a group without a timed first frame"); return None; }; @@ -2595,39 +2597,42 @@ impl Reach { /// What a group's first frame holds. enum First { - /// Media: its pts, the transport's stamp or else its first sample's, with what its samples reach + /// Media: its place, the group's start or else its first sample's pts, with what its samples reach /// and the picture size its keyframe declares. Media(moq_net::Timestamp, Reach, Option<(u32, u32)>), /// A discontinuity marker, a frame with no payload: the content stops at its timestamp. Marker(moq_net::Timestamp), } -/// The first frame of a group, or `None` when it can't be read. `probe` reads its picture size; one -/// it can't parse declares none, leaving the hand-over to arrival order. +/// The first frame of the group keyed `start`, or `None` when it can't be read. `probe` reads its +/// picture size; one it can't parse declares none, leaving the hand-over to arrival order. fn first_frame( container: &moq_mux::catalog::hang::Container, + start: u64, frame: moq_net::frame::Frame, probe: Option<&mut Muxer>, ) -> Option { use moq_mux::container::Container as _; + let scale = frame.timestamp.scale(); let stamp = frame.timestamp; let decoded = container.decode(frame).ok()?; let first = decoded.first()?; // A scale-less session carries the group key, not a time, so the container's own is used. - let pts = if stamp.scale().is_some() { - stamp - } else { - first.timestamp - }; + let pts = if scale.is_some() { stamp } else { first.timestamp }; // The grid places only times. pts.scale()?; if first.payload.is_empty() { return Some(First::Marker(pts)); } + // A timed track keys each group by its start, which may sit below its first frame. + let place = match scale { + Some(scale) => moq_net::Timestamp::new(start, scale).ok()?, + None => pts, + }; let size = probe.and_then(|probe| probe.picture_size(first).ok().flatten()); let mut reach = Reach::default(); reach.add(decoded); - Some(First::Media(pts, reach, size)) + Some(First::Media(place, reach, size)) } /// The row listing `slot`, starting a new discontinuity when `broken`. From 38cfd4712646b02aaaaa691c1c3eb7145a3fcd6c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 21:21:35 -0800 Subject: [PATCH 3/7] hang: the last consumers that number groups use their start The JS container consumer judges continuity by declared skips and pts rather than start + 1 adjacency, stale sequence names become starts, and the hang draft follows. Co-Authored-By: Claude Opus 5.5 --- doc/bin/hls.md | 2 +- drafts/draft-lcurley-moq-hang.md | 9 +- .../container/consumer.nonsequential.test.ts | 76 +++++++++++++ js/hang/src/container/consumer.ts | 107 ++++++++---------- js/watch/src/audio/order.ts | 2 +- js/watch/src/text/renderer.ts | 2 +- js/watch/src/video/decoder.ts | 4 +- quest/m2/README.md | 2 +- quest/m2/time-addressing/group-end-whole.md | 4 - quest/m2/time-addressing/start-placement.md | 59 ---------- rs/moq-archive/src/producer/track.rs | 6 +- rs/moq-mux/src/container/mkv/import.rs | 10 +- rs/moq-mux/src/container/ts/import.rs | 44 +++---- rs/moq-mux/src/import/container.rs | 10 +- rs/moq-transcode/src/lib.rs | 4 +- 15 files changed, 169 insertions(+), 172 deletions(-) delete mode 100644 quest/m2/time-addressing/start-placement.md diff --git a/doc/bin/hls.md b/doc/bin/hls.md index d4127ec1dba..17f7166af67 100644 --- a/doc/bin/hls.md +++ b/doc/bin/hls.md @@ -56,7 +56,7 @@ support the publisher's codecs. What that means for you: - **The publisher declares the interval.** Only a broadcast whose catalog carries `sync.interval` gets playlists. Rust publishers built on `moq-mux` (the CLI, the RTMP, SRT, and WebRTC gateways, and the native bindings) declare it: an encoder that knows its GOP passes it as a hint, and an ingest without one measures each track over its first second or group, whichever is longer, then declares the longest. `@moq/publish` declares its encoders' `join`. A `moq-transcode` derivative declares its source's, since its rungs cut where the source does. -- **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. +- **Every rendition shares the grid.** A group spans from its start 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. 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. diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index 275914d7759..54ce7a86032 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -654,7 +654,7 @@ A second group would present a gap as if it were a complete log; ending the trac A consumer MUST NOT skip to the newest group, since a later group does not supersede an earlier one the way a `snapshot` group does. It reads the one group the track carries, and MUST fail the read if the track carries a second, since whatever would have completed the first group is gone and yielding the remainder would present that gap as a continuous log. -This is why a consumer takes groups in arrival order rather than by ascending sequence: groups are separate streams, so a second group MAY arrive with a lower sequence than the first, and skipping it would report a truncated log as a whole one. +This is why a consumer takes groups in arrival order rather than by ascending start: groups are separate streams, so a second group MAY arrive with a lower start than the first, and skipping it would report a truncated log as a whole one. A consumer MUST NOT wait for the first group to end before it looks for a second. A publisher that opens a second group while the first is still open is broken in exactly the way this rule exists to catch, and a consumer that only checks at the group boundary waits forever on a group that publisher may never finish. @@ -914,11 +914,11 @@ A consumer MUST NOT submit the marker to a decoder. Empty groups (zero objects) are permitted and mean nothing. After a discontinuity the timeline continues forward. A publisher that stops producing and may resume on the same track (e.g. an encoder idle for lack of demand) SHOULD publish a discontinuity marker when it stops, so the group before the pause does not reach across the gap and read as live. -The first timestamp of a group MUST NOT be lower than the first timestamp of any group with a lower sequence, and no frame of a group may be lower than the first timestamp of the group before it; a group that breaks either is malformed. +The first timestamp of a group MUST NOT be lower than the first timestamp of any group with a lower start, and no frame of a group may be lower than the first timestamp of the group before it; a group that breaks either is malformed. A group MAY start at the same timestamp as the previous group. Frames MAY present below the previous group's content (B-frames, or a keyframe overlapping the previous group's last frame). A publisher whose source restarts below the previous group's start begins a new broadcast instead. -A delivered sequence hole is a playhead event unless the boundary is contiguous within 1 ms. +A hole between delivered groups is a playhead event unless the publisher declared the starts between them skipped or the boundary is contiguous within 1 ms. A consumer re-applies startup delay and skip at a playhead event; it does not reset codec state. ## legacy @@ -982,7 +982,7 @@ The grid draws a line at every multiple of that segment length in presentation t An edge derives the length from the interval alone, so every edge agrees. A broadcast without `sync.interval` is not served as HLS or DASH. -A group spans from its first frame's timestamp to the next group's. +A group spans from its start to the next group's start, or from its first frame's timestamp where the track has no timescale. It belongs to one segment: the first line it contains, so segment N starts at the group containing N times the segment length, or, when it contains none, the line it starts after. A segment holds whole groups, since one starting mid-group is not independent. Every rendition numbers its segments on the one grid, so they share segment numbers while each cuts its boundaries at its own groups. @@ -1046,6 +1046,7 @@ This document has no IANA actions. ## moq-hang-04 {:numbered="false"} +- An HLS or DASH edge places a group on the segment grid by its start rather than its first frame's timestamp, and a hole between groups whose skipped starts the publisher declared is no playhead event. - A reader refuses a JSON frame in which an object repeats a member name. - A catalog update takes effect at its frame's timestamp on the media timeline, not when a consumer reads it, and a publisher keeps superseded catalog groups as fresh as its media's for consumers behind the live edge; an untimed catalog track's updates apply on arrival. - Removed `catalog.json.z` and the data track `compression` field: compression is a track property the transport carries ({{compression}}), so each compressed track is one name, and the catalog, `stats` and `echo` snapshots, and JSON data tracks SHOULD be compressed. diff --git a/js/hang/src/container/consumer.nonsequential.test.ts b/js/hang/src/container/consumer.nonsequential.test.ts index cce3350b1d0..1620498748f 100644 --- a/js/hang/src/container/consumer.nonsequential.test.ts +++ b/js/hang/src/container/consumer.nonsequential.test.ts @@ -174,3 +174,79 @@ test("Consumer reads one-packet Opus groups at sparse sequences back to back", a track.finish(); track.close(); }); + +// A track at hang's microsecond timescale, whose groups are keyed by their start timestamps. +function micro(): Track.Producer { + return new Track.Producer("test").accept({ timescale: Time.Timescale.MICRO, maxAge: null }); +} + +// Groups keyed by their start timestamps are never consecutive integers. Appending declares the starts +// between them skipped, so a slow head the age skip passes is no loss when the next group follows it, +// even where frames carry no duration to prove the timeline unbroken. +test("Consumer reads on without a gap past an aged group the publisher's skips follow", async () => { + const track = micro(); + const consumer = new Consumer(track.subscribe(), { + format: new LegacyFormat("data"), + delay: { max: Duration.millis(500) }, + }); + const append = (timestamps: number[]) => { + const group = track.appendGroup(Time.Timestamp.fromMicros(timestamps[0])); + for (const timestamp of timestamps) { + group.writeFrame({ + payload: encodeLegacyFrame(timestamp, new Uint8Array([0x01])), + timestamp: Time.Timestamp.fromMicros(timestamp), + }); + } + return group; + }; + + const first = append([0, 100_000, 200_000, 300_000, 400_000]); + for (let i = 0; i < 5; i++) expect((await nextFrame(consumer))?.group).toBe(0n); + first.finish(); + await clock.advance(Duration.ZERO); + // Far past the first group's last frame, and past the age bound, so the age skip passes it. + append([1_000_000, 2_000_000]).finish(); + await clock.advance(Duration.ZERO); + expect(await poll(consumer.next())).toMatchObject({ kind: "frame", group: 1_000_000n }); + + consumer.close(); + track.finish(); + track.close(); +}); + +// A buffered range runs across group boundaries wherever nothing lies between: the starts between were +// declared skipped, or the next group starts where the media before it ends. +test("Consumer buffers groups at sparse starts as one range", async () => { + const opus = AudioConfigSchema.parse({ + codec: "opus", + container: { kind: "legacy" }, + sampleRate: 48_000, + numberOfChannels: 2, + }); + const packet = new Uint8Array([31 << 3, 0]); + for (const [name, format, create] of [ + // No duration: only the declared skips prove nothing is missing. + ["declared", new LegacyFormat("data"), (track: Track.Producer, start: number) => track.appendGroup(Time.Timestamp.fromMicros(start))], + // Nothing declared: each 20 ms packet ends where the next group starts. + ["contiguous", new LegacyFormat(opus), (track: Track.Producer, start: number) => track.createGroup(BigInt(start))], + ] as const) { + const track = micro(); + const delay = { min: Duration.millis(100), max: Duration.millis(5000) }; + // Reaching back past the first group, so the start keeps every one. + const consumer = new Consumer(track.subscribe({ delay }), { format, delay }); + for (const start of [0, 20_000, 40_000]) { + const group = create(track, start); + group.writeFrame({ payload: encodeLegacyFrame(start, packet), timestamp: Time.Timestamp.fromMicros(start) }); + group.finish(); + } + await clock.advance(Duration.ZERO); + expect( + consumer.buffered.peek().map((range) => [range.start.asMicros(), range.end.asMicros()]), + name, + ).toEqual([[0, 40_000]]); + + consumer.close(); + track.finish(); + track.close(); + } +}); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index c1bcb402b85..7d899c74539 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -134,7 +134,7 @@ const GROUP_COST = 256; interface Group { consumer: Moq.Group.Consumer; - // From then on, any sequence missing below this group is late: the earliest arrival among it + // From then on, any start missing below this group is late: the earliest arrival among it // and the groups past it, kept on insert so a hole reads it without scanning the backlog. late: Instant; frames: ReceivedFrame[]; // decode order @@ -180,20 +180,6 @@ function ptsContiguous(end: number | undefined, nextStart: number | undefined): return end !== undefined && nextStart !== undefined && nextStart <= end + CONTIGUITY_TOLERANCE; } -/** - * True when `next` continues `prev`'s presentation timeline, i.e. nothing is missing between them. - * Either its sequence is the very next one, which is the only proof available for containers that - * carry no per-frame duration (Legacy), or the PTS timeline is unbroken across the boundary, which - * is what non-sequential group numbering (e.g. DTS-derived ids) needs. - */ -function continues(prev: Group, next: Group | undefined): next is Group { - if (next === undefined) return false; - return ( - next.consumer.start === prev.consumer.start + 1n || - ptsContiguous(prev.end, next.frames.at(0)?.timestamp.asMicros()) - ); -} - // The max delay in microseconds, infinite when unlimited. function maxMicros(delay: Moq.Track.Delay): number { return delay.max === null ? Number.POSITIVE_INFINITY : (delay.max?.asMicros() ?? 0); @@ -231,11 +217,11 @@ export class Consumer { // Group watchers and the track loop parked on a full max buffer. #room: (() => void)[] = []; #groups: Group[] = []; - #active?: bigint; // the active group sequence number + #active?: bigint; // the cursor: the start of the group being read, or a key just past it // The cursor started at the floor or the publisher's resolved start, rather than at the first // arrival, so a hole at it is waited for like any other. #floored = false; - // When the missing sequence at the cursor became late, while one is. + // When the missing start at the cursor became late, while one is. #hole?: Instant; // Presentation end (max PTS + duration) of the group we most recently advanced past, so next()'s // promotion guard can tell a timeline-continuous next group from one sitting after a gap. @@ -294,7 +280,7 @@ export class Consumer { // estimator the silence is over. Not at the marker itself: the stopped encoder's final packets may // follow it in its own group, and they belong to the speech before the silence. #declared?: bigint; - #mediaSequence?: bigint; + #mediaStart?: bigint; #signals = new Effect(); #closed = new Once(); @@ -443,7 +429,7 @@ export class Consumer { } } - // Buffer a group in sequence order and watch it for frames. + // Buffer a group in start order and watch it for frames. #add(consumer: Moq.Group.Consumer, gap = false): void { const group: Group = { consumer, @@ -459,12 +445,12 @@ export class Consumer { }; this.#charge(group, GROUP_COST); - // Insert into #groups based on the group sequence number (ascending). + // Insert into #groups by group start (ascending). // This is used to cancel old groups. let index = this.#groups.findIndex((other) => other.consumer.start > consumer.start); if (index === -1) index = this.#groups.length; // Each group is late from the earliest arrival among it and the groups past it. A drained - // backlog comes in sequence order, not arrival order, so an arrival can lower those below it. + // backlog comes in start order, not arrival order, so an arrival can lower those below it. const next = this.#groups.at(index); if (next?.late.lt(group.late)) group.late = next.late; for (let i = index - 1; i >= 0 && this.#groups[i].late.gt(group.late); i--) this.#groups[i].late = group.late; @@ -525,14 +511,14 @@ export class Consumer { } } - // Observe one decoded sample of group `sequence` for the arrival estimate: media is observed, + // Observe one decoded sample of the group keyed `start` for the arrival estimate: media is observed, // and a marker ahead of any media (`media` false) declares an end. - #note(sequence: bigint, marker: boolean, media: boolean, timestamp: Duration, arrived: number): void { + #note(start: bigint, marker: boolean, media: boolean, timestamp: Duration, arrived: number): void { // Observed before any gap handling or age budget: a target derived from what survives the // budget would only ever confirm the budget it was cut to. if (!marker) { - if (this.#mediaSequence === undefined || sequence > this.#mediaSequence) this.#mediaSequence = sequence; - if (this.#declared !== undefined && sequence > this.#declared) { + if (this.#mediaStart === undefined || start > this.#mediaStart) this.#mediaStart = start; + if (this.#declared !== undefined && start > this.#declared) { this.#jitter.end(); this.#declared = undefined; } @@ -541,7 +527,7 @@ export class Consumer { if (spread !== this.#spread.peek().asMillis()) this.#spread.set(Duration.millis(spread)); } else if (!media) { // Only a marker ahead of any media declares an end; one after it is a frame's endpoint. - this.#declare(sequence); + this.#declare(start); } } @@ -625,10 +611,10 @@ export class Consumer { return start; } - // Note an end the publisher declared in group `sequence`, which a later group's first frame resumes from. - #declare(sequence: bigint): void { - if (this.#mediaSequence !== undefined && sequence < this.#mediaSequence) return; - if (this.#declared === undefined || sequence > this.#declared) this.#declared = sequence; + // Note an end the publisher declared in the group keyed `start`, which a later group's first frame resumes from. + #declare(start: bigint): void { + if (this.#mediaStart !== undefined && start < this.#mediaStart) return; + if (this.#declared === undefined || start > this.#declared) this.#declared = start; } // Decode one wire frame into `group`, charging what it buffers. A payload that fails to decode sets @@ -741,7 +727,7 @@ export class Consumer { let stamped = 0; // Keep skipping the oldest group while the buffered span exceeds the max delay. - // This also handles gaps in group sequence numbers: if #active points to a missing + // This also handles holes between group starts: if #active points to a missing // group, the span proves the missing content is too old to wait for. while (this.#groups.length >= 2) { const threshold = this.#ageBudget(); @@ -809,8 +795,9 @@ export class Consumer { // or still-open group may have lost its tail. const ended = this.#ended(first); const truncated = ended instanceof Error; - const adjacent = next?.consumer.start === first.consumer.start + 1n; - const continued = (ended === null && adjacent) || ptsContiguous(first.end ?? this.#presentedEnd, nextStart); + // The publisher declares the starts it never produced, so a run it skipped holds no group. + const declared = next !== undefined && this.#track.isSkipped(first.consumer.start + 1n, next.consumer.start); + const continued = (ended === null && declared) || ptsContiguous(first.end ?? this.#presentedEnd, nextStart); if (marker || discarded || truncated || !continued) this.#lost = true; skipped++; if (!this.#discard(first)) break; @@ -1027,15 +1014,11 @@ export class Consumer { // The start may wait for a group covering the reach, the min delay plus the warmup. const starting = this.#reachStart(ended !== undefined); - // If #active points below all buffered groups -- e.g. a finished group's `+ 1` - // fallback fired because no later group was buffered yet, and the real (large-gap, - // non-sequential) next group has since arrived -- promote #active to the first real - // group so delivery resumes instead of stalling on a nonexistent sequence. - // Before any media is delivered there is no timeline hole to wait for, so this exception - // only applies at startup. - // Otherwise promote #active when the first buffered group continues the timeline we left off at, - // when a completed empty group can be walked (empty groups mean nothing), or when the hole - // is proven: everything a missing group could still present ends where the first group past + // When #active points below every buffered group, such as just past a finished group's + // start, promote #active to the first buffered group: at startup, since before any media + // is delivered there is no timeline hole to wait for; when the first buffered group continues + // the timeline we left off at; when a completed empty group can be walked (empty groups mean + // nothing); or when the hole is proven: everything a missing group could still present ends where the first group past // it begins, so once that start falls the max delay behind the newest content, all of it // would arrive too late to play. Mirrors Rust's `aged`. Where presentation left off proves // only the oldest of it stale, and groups go out newest first, so a flush's newest group lands @@ -1043,7 +1026,7 @@ export class Consumer { // Proving it here matters: #checkMaxDelay would instead drop the head, the very group to play // next. // After track termination no missing group can arrive, so drain across any remaining gap. - // A missing sequence also expires on elapsed monotonic time, so timestamp-free markers + // A missing group also expires on elapsed monotonic time, so timestamp-free markers // behind a hole can end a paused track without more arrivals. It is late since a group // past it arrived, not since the cursor got here: once the edge stops moving, a backlog // with every other group missing would otherwise drain one budget per hole. And once the @@ -1109,7 +1092,7 @@ export class Consumer { const head = this.#groups.at(0); if (starting === undefined && head && this.#active !== undefined && head.consumer.start <= this.#active) { - const seq = head.consumer.start; + const key = head.consumer.start; const frame = head.frames.shift(); if (frame) { this.#refund(head, head.costs.shift() ?? 0); @@ -1117,27 +1100,27 @@ export class Consumer { if (end !== undefined) { this.#updateBuffered(); // A trailing endpoint is the last frame's duration: it moves the edge, nothing else. - if (seq === this.#mediaGroup) { + if (key === this.#mediaGroup) { this.#advance(end.asMicros()); continue; } - return this.#emit({ kind: "end", group: seq, end }); + return this.#emit({ kind: "end", group: key, end }); } - this.#mediaGroup = seq; + this.#mediaGroup = key; // A group covering the target began before it, so the reader warms until the target too. const at = frame.timestamp.asMicros(); this.#warmed ??= Math.max(at, this.#target ?? at) + this.#warmup.asMicros(); - if (this.#start === undefined || seq > this.#start.group) { + if (this.#start === undefined || key > this.#start.group) { this.#floor = this.#start?.timestamp; - this.#start = { group: seq, timestamp: at }; + this.#start = { group: key, timestamp: at }; } if (this.#floor !== undefined && at < this.#floor) { this.#abort(new Error("frame timestamp is below the previous group start")); throw this.#error; } this.#updateBuffered(); - return this.#emit({ kind: "frame", group: seq, frame }); + return this.#emit({ kind: "frame", group: key, frame }); } // A payload that failed to decode ends the reader once the frames ahead of it are read. @@ -1153,16 +1136,11 @@ export class Consumer { const settled = this.#ended(head); if (settled !== undefined) { this.#groups.shift(); - if (seq === this.#active) { - // Advance to the next buffered group's actual sequence, but ONLY if it continues this - // group's timeline. Some encoders number groups non-sequentially with large gaps (not - // +1), so a bare `+= 1` would point #active at a nonexistent sequence and stall until - // the hole expired -- every group through the skip path, i.e. constant stutter. A real - // PTS gap is different: an intermediate group may still be in transit, so fall back to - // +1 there (the promotion guard above fixes it up once a continuous group arrives). - const next = this.#groups.at(0); - this.#pass(head, continues(head, next) ? next.consumer.start : seq + 1n); - } + // Step just past this group's start. Starts are timestamps, so the next group rarely + // sits there: the promotion guard above steps to it once the publisher declared the run + // between skipped or its first frame continues this group's timeline, as Rust's + // `poll_continues` does, and otherwise waits for the hole like any other. + if (key === this.#active) this.#pass(head, key + 1n); head.consumer.close(); this.#release(head); const truncated = settled instanceof Error; @@ -1171,7 +1149,7 @@ export class Consumer { // A data track's marker carries no timestamp, so it ends where this reader got to. // Before the first item there is nothing to end. if (head.bare && !truncated && this.#edge !== undefined) { - return this.#emit({ kind: "end", group: seq, end: Duration.micros(this.#edge) }); + return this.#emit({ kind: "end", group: key, end: Duration.micros(this.#edge) }); } continue; } @@ -1359,7 +1337,12 @@ export class Consumer { const first = group.frames.at(0); if (!first || group.latest === undefined) continue; - const contiguous = prev?.consumer.done && prev.consumer.start + 1n === group.consumer.start; + // Nothing lies between a finished group and the next when the publisher declared the starts + // between skipped, or when the next starts where the previous one's media ends. + const contiguous = + prev?.consumer.done && + (this.#track.isSkipped(prev.consumer.start + 1n, group.consumer.start) || + ptsContiguous(prev.end, first.timestamp.asMicros())); if (start !== undefined && (end >= first.timestamp.asMicros() || contiguous)) { end = Math.max(end, group.latest); } else { diff --git a/js/watch/src/audio/order.ts b/js/watch/src/audio/order.ts index 629ab9222fe..aa10e752f39 100644 --- a/js/watch/src/audio/order.ts +++ b/js/watch/src/audio/order.ts @@ -5,7 +5,7 @@ import type { Duration } from "@moq/clock"; * * Groups go out newest-first, so a subscription's head (the groups the publisher still holds) can * arrive after the live edge it was served alongside. The container's ordered read waits for it from - * where the publisher's feed starts and hands groups over in sequence, so the head comes first here; + * where the publisher's feed starts and hands groups over in start order, so the head comes first here; * this keeps the order should it not. Chrome's AudioDecoder stamps every output from its first input, * so decoding the head after the live edge shifts the rest of the track, and the ring, anchored at the * first decoded frame, cannot place the head anyway. diff --git a/js/watch/src/text/renderer.ts b/js/watch/src/text/renderer.ts index 70400ccaa36..8408541f538 100644 --- a/js/watch/src/text/renderer.ts +++ b/js/watch/src/text/renderer.ts @@ -91,7 +91,7 @@ function merge(stored: T[], incoming: T[], key: (value: T) => number): T[] { /** * Add one payload's cues to the store, keeping it sorted by start time. * - * Groups arrive in delivery order rather than sequence order, so a cue can legitimately land + * Groups arrive in delivery order rather than start order, so a cue can legitimately land * before one that is already stored. Each end is clamped to `MAX_CUE` past its start, so a * declared end cannot hold a cue past the prune horizon. Exported for tests. * diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 6c4e2a25e53..5f5714e7455 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -838,7 +838,7 @@ class Rendition { const { frame } = next; // An older keyframe would replace the codec references needed by live deltas. Group - // sequences only grow within a subscription, so neither a hole nor an endpoint + // starts only grow within a subscription, so neither a hole nor an endpoint // resets this guard. Rejected payloads still count as received bytes. const stale = latest !== undefined && next.group < latest; const accepted = !stale && recovery.accept(frame); @@ -916,7 +916,7 @@ class Rendition { const { frame } = next; // An older keyframe would replace the codec references needed by live deltas. Group - // sequences only grow within a subscription, so neither a hole nor an endpoint + // starts only grow within a subscription, so neither a hole nor an endpoint // resets this guard. Rejected payloads still count as received bytes. const stale = latest !== undefined && next.group < latest; const accepted = !stale && recovery.accept(frame); diff --git a/quest/m2/README.md b/quest/m2/README.md index e211eeca350..0ab221ff446 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -285,7 +285,7 @@ what would need a breaking release had it landed right after the cut: returned to m2 on 2026-11-15 (maintainer, on [moq-dev/moq#8832](https://github.com/moq-dev/moq/pull/8832)) and became the request quest of [cache-aware multicast](/quest/m2/multicast/README.md); - media consumers (now [start placement](/quest/m2/time-addressing/start-placement.md)) to m3 (its API + media consumers (later start placement) to m3 (its API breaks ride the model; dropping hang's markers is tolerated by readers), until it returned to m2 on 2026-11-16; [moq-transport time addressing](https://github.com/moq-dev/moq/pull/8918) to m4 diff --git a/quest/m2/time-addressing/group-end-whole.md b/quest/m2/time-addressing/group-end-whole.md index 69fdf78b75f..25b6f0c1c28 100644 --- a/quest/m2/time-addressing/group-end-whole.md +++ b/quest/m2/time-addressing/group-end-whole.md @@ -76,7 +76,3 @@ Run `just test interop --all`. Public API: breaking in Rust and JS (`finish_at` and `end()` on groups). Wire: lite-07-wip only, which is unpublished. - -## Related - -- [Start placement](/quest/m2/time-addressing/start-placement.md) - the by-start conversions the old consumers quest also held diff --git a/quest/m2/time-addressing/start-placement.md b/quest/m2/time-addressing/start-placement.md deleted file mode 100644 index a7101288d10..00000000000 --- a/quest/m2/time-addressing/start-placement.md +++ /dev/null @@ -1,59 +0,0 @@ -# [M] The last consumers that number groups use their start - -## Goal - -Every first-party consumer works by group start, in Rust and JS: the JS -container consumer judges continuity without `start + 1` adjacency, the -HLS/DASH export places each group on the join interval grid by its start -rather than its first frame's pts, and no doc or parameter still calls a -start a sequence. hang keeps writing and reading its duration and -discontinuity markers. - -## Plan - -Decided 2026-11-19 (maintainer, on closed -[moq-dev/moq#9192](https://github.com/moq-dev/moq/pull/9192)): ✅ hang keeps -its in-band group end markers (empty duration frame, discontinuity marker -group) on every transport (rejected: readers infer stops from lite-07's -GROUP_END position). This reverses the 2026-11-16 decision that dropped the -markers before the cut, and GROUP_END's timestamp goes instead (see -[group-end-whole](/quest/m2/time-addressing/group-end-whole.md)). So -`Read::End`, `Producer::discontinuity`, `Container::end`, and -`Container::finish_group` keep their meaning, and the hang draft keeps its -marker rules. - -Still valid from the old consumers quest: convert each consumer that numbers -groups, update the hang draft and the docs each one makes stale, and rename -no CLI flag. [The model](https://github.com/moq-dev/moq/pull/8638) already -converted the Rust consumers whose API named group numbers. Checked on main -2026-11-19: - -- Already by start: the Rust container consumer, moq-mux `seek`, HLS import, - transcode (`moq-transcode/src/feed.rs:208`), archive, relay `/fetch?group=` - and `moq fetch --group`, and `js/watch` (order comparisons only). -- Still adjacency by sequence: the JS container consumer - (`js/hang/src/container/consumer.ts:192` `continues`, `:809` `adjacent` in - `#checkMaxDelay`, `:1349` buffered ranges, and the `seq + 1n` fallback at - `:1157`). It already uses `isSkipped`/`nextInRange` at `:1056` and `:1069`; - judge continuity the way the Rust consumer does (`pts_contiguous`, - declared skips, `next_in_range`). -- Placement: the HLS/DASH export places groups on the grid by their first - frame's pts (`rs/moq-hls/src/export/rendition.rs:2140-2159`, - `export/grid.rs:282-300`); place them by group start without changing the - segment numbers. It also reads discontinuity marker groups - (`First::Marker`, `rendition.rs:2149-2152`), which stay. -- Stale names: transcode's `lib.rs:18` doc ("sequence numbers 1:1"), the TS - import's `seek(sequence)` parameter (`ts/import.rs:1805`, `:2392`, - `:2644`), archive's `sequence` field holding a start - (`moq-archive/src/producer/track.rs:241`, rename only if it is not part of - the stored format), and `js/watch` comments. - -Tests: a JS reader over groups whose starts are not consecutive integers -reads them as continuous where the media is; an HLS export of a track whose -first frame sits above its group start lands in the same segment as before. - -Public API: none expected; a renamed parameter is not a break. Wire: none. - -## Related - -- [GROUP_END is a bare whole marker](/quest/m2/time-addressing/group-end-whole.md) - the wire half of the same re-plan diff --git a/rs/moq-archive/src/producer/track.rs b/rs/moq-archive/src/producer/track.rs index fb216bc5ed5..13e985f96c9 100644 --- a/rs/moq-archive/src/producer/track.rs +++ b/rs/moq-archive/src/producer/track.rs @@ -235,16 +235,16 @@ impl Track { // it last stored whole, keyed below where it resumes: that group is already stored. Event::Next(Ok(Some(group))) if self.next.is_some_and(|next| group.start < next.group) => {} Event::Next(Ok(Some(group))) => { - let sequence = group.start; + let start = group.start; // A resumed group continues after its stored frames. The clamp also starts a // group whose head is held elsewhere at its first frame, rather than lagging // behind it. let stored = self .next - .filter(|next| next.group == sequence) + .filter(|next| next.group == start) .map_or(0, |next| next.frame); let group = Box::new(group.with_range(stored..)); - self.next = Some(Position::new(sequence, group.index())); + self.next = Some(Position::new(start, group.index())); current = Some(group); } Event::Next(Ok(None)) => break, diff --git a/rs/moq-mux/src/container/mkv/import.rs b/rs/moq-mux/src/container/mkv/import.rs index 415a18ae3f2..bcf622071ef 100644 --- a/rs/moq-mux/src/container/mkv/import.rs +++ b/rs/moq-mux/src/container/mkv/import.rs @@ -200,10 +200,10 @@ impl Media { } } - fn seek(&mut self, sequence: u64) -> crate::Result<()> { + fn seek(&mut self, start: u64) -> crate::Result<()> { match self { - Self::Video(track) => track.seek(sequence), - Self::Audio(track) => track.seek(sequence), + Self::Video(track) => track.seek(start), + Self::Audio(track) => track.seek(start), } } @@ -920,8 +920,8 @@ impl Import { } BlockState::Skip => {} } - if let Some(sequence) = self.seek.take() { - self.seek(sequence)?; + if let Some(start) = self.seek.take() { + self.seek(start)?; } Ok(()) } diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 86ea3319667..5507336b7c4 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -1801,13 +1801,13 @@ impl Import { Ok(()) } - /// Close the current group on every track and reopen at `sequence`. - pub fn seek(&mut self, sequence: u64) -> Result<()> { + /// Close the current group on every track and reopen at `start`, in each track's timescale. + pub fn seek(&mut self, start: u64) -> Result<()> { for stream in self.streams.values_mut() { - stream.seek(sequence)?; + stream.seek(start)?; } for section in self.sections.values_mut() { - section.seek(sequence)?; + section.seek(start)?; } Ok(()) } @@ -2389,8 +2389,8 @@ impl SectionStream { Ok(()) } - fn seek(&mut self, sequence: u64) -> Result<()> { - self.track.seek(sequence)?; + fn seek(&mut self, start: u64) -> Result<()> { + self.track.seek(start)?; Ok(()) } @@ -2641,8 +2641,8 @@ impl PesPacketStream { Ok(()) } - fn seek(&mut self, sequence: u64) -> Result<()> { - self.track.seek(sequence)?; + fn seek(&mut self, start: u64) -> Result<()> { + self.track.seek(start)?; Ok(()) } @@ -3306,7 +3306,7 @@ impl Stream { } /// Sync was lost: drop whatever partial unit is held and stop vouching for the next - /// boundary. This is [`seek`](Self::seek) without the group-sequence side effect, for a + /// boundary. This is [`seek`](Self::seek) without reopening the group at a new start, for a /// break the stream recovers from in place. fn desync(&mut self) { match self { @@ -3369,7 +3369,7 @@ impl Stream { } } - fn seek(&mut self, sequence: u64) -> Result<()> { + fn seek(&mut self, start: u64) -> Result<()> { match self { Stream::H264 { split, @@ -3379,7 +3379,7 @@ impl Stream { } => { assembly.reset(); split.reset(); - Ok(import.seek(sequence)?) + Ok(import.seek(start)?) } Stream::H265 { split, @@ -3389,12 +3389,12 @@ impl Stream { } => { assembly.reset(); split.reset(); - Ok(import.seek(sequence)?) + Ok(import.seek(start)?) } - Stream::Aac(stream) => stream.seek(sequence), - Stream::Opus(stream) => stream.seek(sequence), - Stream::Legacy(stream) => stream.seek(sequence), - Stream::PesPacket(stream) => stream.seek(sequence), + Stream::Aac(stream) => stream.seek(start), + Stream::Opus(stream) => stream.seek(start), + Stream::Legacy(stream) => stream.seek(start), + Stream::PesPacket(stream) => stream.seek(start), Stream::Clock | Stream::Ignored => Ok(()), } } @@ -4056,11 +4056,11 @@ impl AacStream { Ok(()) } - fn seek(&mut self, sequence: u64) -> Result<()> { + fn seek(&mut self, start: u64) -> Result<()> { // A seek is a discontinuity like any other. self.desync(); if let Some(import) = &mut self.import { - import.seek(sequence)?; + import.seek(start)?; } Ok(()) } @@ -4160,8 +4160,8 @@ impl OpusStream { Ok(()) } - fn seek(&mut self, sequence: u64) -> Result<()> { - Ok(self.import.seek(sequence)?) + fn seek(&mut self, start: u64) -> Result<()> { + Ok(self.import.seek(start)?) } fn finish(&mut self) -> Result<()> { @@ -4663,11 +4663,11 @@ impl LegacyStream { Ok(()) } - fn seek(&mut self, sequence: u64) -> Result<()> { + fn seek(&mut self, start: u64) -> Result<()> { // A seek is a discontinuity like any other. self.desync(); if let Some(import) = &mut self.import { - import.seek(sequence)?; + import.seek(start)?; } Ok(()) } diff --git a/rs/moq-mux/src/import/container.rs b/rs/moq-mux/src/import/container.rs index 8dd6d7f092d..14335d4efd4 100644 --- a/rs/moq-mux/src/import/container.rs +++ b/rs/moq-mux/src/import/container.rs @@ -82,12 +82,12 @@ impl ContainerImpl { } } - fn seek(&mut self, sequence: u64) -> Result<()> { + fn seek(&mut self, start: u64) -> Result<()> { match self { - ContainerImpl::Fmp4(decoder) => decoder.seek(sequence), - ContainerImpl::Mkv(decoder) => decoder.seek(sequence), - ContainerImpl::Ts(decoder) => decoder.seek(sequence).map_err(Into::into), - ContainerImpl::Flv(decoder) => decoder.seek(sequence), + ContainerImpl::Fmp4(decoder) => decoder.seek(start), + ContainerImpl::Mkv(decoder) => decoder.seek(start), + ContainerImpl::Ts(decoder) => decoder.seek(start).map_err(Into::into), + ContainerImpl::Flv(decoder) => decoder.seek(start), } } } diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index 80e6fa68502..d9dee34f99b 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -15,8 +15,8 @@ //! - Fetching a specific group fetches that same group from the source and //! transcodes just that group, unless every caller leaves before the //! request is accepted, in which case nothing is encoded. Output groups -//! mirror source sequence numbers 1:1, so group N of every rung is the same -//! content as source group N. +//! mirror source group starts 1:1, so the group starting at N on every rung +//! is the same content as the source group starting at N. //! //! The codec work is `moq-video`: hardware where available (NVDEC + NVENC on //! Linux, VideoToolbox on macOS, Media Foundation on Windows), with the opt-in From d3d25c4aabc688ab310aaf3fabcc84f429dfd648 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 21:25:29 -0800 Subject: [PATCH 4/7] fmt Co-Authored-By: Claude Opus 5.5 --- .../container/consumer.nonsequential.test.ts | 17 ++++++++++++++--- js/hang/src/container/consumer.ts | 3 ++- rs/moq-hls/src/export/rendition.rs | 3 +-- 3 files changed, 17 insertions(+), 6 deletions(-) diff --git a/js/hang/src/container/consumer.nonsequential.test.ts b/js/hang/src/container/consumer.nonsequential.test.ts index 1620498748f..1cfdfcf972d 100644 --- a/js/hang/src/container/consumer.nonsequential.test.ts +++ b/js/hang/src/container/consumer.nonsequential.test.ts @@ -226,9 +226,17 @@ test("Consumer buffers groups at sparse starts as one range", async () => { const packet = new Uint8Array([31 << 3, 0]); for (const [name, format, create] of [ // No duration: only the declared skips prove nothing is missing. - ["declared", new LegacyFormat("data"), (track: Track.Producer, start: number) => track.appendGroup(Time.Timestamp.fromMicros(start))], + [ + "declared", + new LegacyFormat("data"), + (track: Track.Producer, start: number) => track.appendGroup(Time.Timestamp.fromMicros(start)), + ], // Nothing declared: each 20 ms packet ends where the next group starts. - ["contiguous", new LegacyFormat(opus), (track: Track.Producer, start: number) => track.createGroup(BigInt(start))], + [ + "contiguous", + new LegacyFormat(opus), + (track: Track.Producer, start: number) => track.createGroup(BigInt(start)), + ], ] as const) { const track = micro(); const delay = { min: Duration.millis(100), max: Duration.millis(5000) }; @@ -236,7 +244,10 @@ test("Consumer buffers groups at sparse starts as one range", async () => { const consumer = new Consumer(track.subscribe({ delay }), { format, delay }); for (const start of [0, 20_000, 40_000]) { const group = create(track, start); - group.writeFrame({ payload: encodeLegacyFrame(start, packet), timestamp: Time.Timestamp.fromMicros(start) }); + group.writeFrame({ + payload: encodeLegacyFrame(start, packet), + timestamp: Time.Timestamp.fromMicros(start), + }); group.finish(); } await clock.advance(Duration.ZERO); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 7d899c74539..10ca9c2e231 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -796,7 +796,8 @@ export class Consumer { const ended = this.#ended(first); const truncated = ended instanceof Error; // The publisher declares the starts it never produced, so a run it skipped holds no group. - const declared = next !== undefined && this.#track.isSkipped(first.consumer.start + 1n, next.consumer.start); + const declared = + next !== undefined && this.#track.isSkipped(first.consumer.start + 1n, next.consumer.start); const continued = (ended === null && declared) || ptsContiguous(first.end ?? this.#presentedEnd, nextStart); if (marker || discarded || truncated || !continued) this.#lost = true; skipped++; diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 95ae0fc0d16..0ebc98baf87 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -2139,8 +2139,7 @@ impl Follow { ) -> Option> { // A group's place is its start, or its first frame's container pts where the session // carries no timeline. - let Some(first) = - first.and_then(|frame| first_frame(&self.container, group.start, frame, self.probe.as_mut())) + let Some(first) = first.and_then(|frame| first_frame(&self.container, group.start, frame, self.probe.as_mut())) else { tracing::warn!(track = %self.track, group = group.start, "skipping a group without a timed first frame"); return None; From 0b78eb23a37dfe35421496af56609fc5c48df0b6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 21:33:41 -0800 Subject: [PATCH 5/7] quest: a WHEP re-offer flakes under load Co-Authored-By: Claude Opus 5.5 --- quest/m0/test-flakes-3/webrtc-reoffer-load.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 quest/m0/test-flakes-3/webrtc-reoffer-load.md diff --git a/quest/m0/test-flakes-3/webrtc-reoffer-load.md b/quest/m0/test-flakes-3/webrtc-reoffer-load.md new file mode 100644 index 00000000000..9e3648a9b13 --- /dev/null +++ b/quest/m0/test-flakes-3/webrtc-reoffer-load.md @@ -0,0 +1,12 @@ +# [S] A WHEP re-offer plays under load + +## Goal + +`moq-webrtc`'s `tests::a_reoffer_from_the_same_address_plays` passes however loaded the host is. + +## Plan + +It failed once in a loaded `just check` on 2026-11-19 (while building [moq-dev/moq#9222](https://github.com/moq-dev/moq/pull/9222), which touches no WebRTC code): `received` hit its 10s `TIMEOUT` ("the viewer neither received nor closed", `rs/moq-webrtc/src/lib.rs:300`) after 10.18s, and it passed alone in 0.9s. +The panic does not say which `received` call timed out: the first viewer's packet, or the re-offered session's loop that pushes a packet every 20ms. +Reproduce first under CPU pressure, such as `cargo nextest run -p moq-webrtc a_reoffer --stress-count 50` inside `systemd-run --user --scope -p CPUQuota=100%`, then find which wait stalls and why: ICE over real sockets racing the 20ms push loop, or the new session joining past the delay budget so every pushed packet ages out before it reads. +Keep the epic's rules: no longer timeout, no retry. From 0b03f09506eacd6a087da6369d1ad3c02e5b8674 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 21:42:47 -0800 Subject: [PATCH 6/7] moq-hls: a group placed at its start still ends the content before it at its first frame Co-Authored-By: Claude Opus 5.5 --- rs/moq-hls/src/export/grid.rs | 75 +++++++++++++++++------------- rs/moq-hls/src/export/rendition.rs | 12 ++--- 2 files changed, 48 insertions(+), 39 deletions(-) diff --git a/rs/moq-hls/src/export/grid.rs b/rs/moq-hls/src/export/grid.rs index 6f6a4274b37..e8c7a013817 100644 --- a/rs/moq-hls/src/export/grid.rs +++ b/rs/moq-hls/src/export/grid.rs @@ -129,8 +129,8 @@ pub(crate) enum Slot { start: Timestamp, /// Where its `EXTINF` ends: the next segment's start. end: Timestamp, - /// Where its last group's content ends, the next group's pts, when known: a fallback for - /// timing its last sample. + /// Where its last group's content ends, the next group's first frame, when known: a + /// fallback for timing its last sample. content: Option, }, /// A grid slot no group starts a segment in (`EXT-X-GAP`). @@ -152,7 +152,10 @@ pub(crate) enum Slot { #[derive(Clone, Copy, Debug)] struct Group { start: u64, + /// Where the grid places it. pts: Timestamp, + /// Its first frame's pts, where the media before it ends. + media: Timestamp, } /// The segment collecting groups, completed once a group lands in a later one. @@ -280,9 +283,9 @@ impl Grid { Timestamp::from_nanos(u64::try_from(nanos).unwrap_or(u64::MAX)).unwrap_or(Timestamp::ZERO) } - /// The group keyed `start` is placed at `pts`, after every group already fed. Returns - /// the segments it completes. - pub fn group(&mut self, start: u64, pts: Timestamp) -> Vec { + /// The group keyed `start` is placed at `pts`, after every group already fed, and its first + /// frame is at `media`, which ends the content before it. Returns the segments it completes. + pub fn group(&mut self, start: u64, pts: Timestamp, media: Timestamp) -> Vec { let mut out = Vec::new(); // A group starting before the one before it, even within one slot, can't share a segment // or a numbering with what came before, since its media would run backwards. @@ -295,7 +298,7 @@ impl Grid { let segment = self.segment(pending.pts, Some(pts)).expect("bounded"); self.place(pending, segment, &mut out); } - let group = Group { start, pts }; + let group = Group { start, pts, media }; // A group starting on a line needs no end to place, so the segment before it completes now. match self.segment(pts, None) { Some(segment) => self.place(group, segment, &mut out), @@ -399,7 +402,7 @@ impl Grid { pts: open.pts, start: self.start(open.segment, open.pts), end: start(open.segment + 1), - content: Some(open.stop.unwrap_or(group.pts)), + content: Some(open.stop.unwrap_or(group.media)), }); let first = (open.segment + 1).max(segment.saturating_sub(self.max_gaps)); for gap in first..segment { @@ -469,7 +472,7 @@ mod test { let mut grid = Grid::new(Duration::from_millis(length_ms), 256); let mut slots = Vec::new(); for (sequence, start) in starts.iter().enumerate() { - slots.extend(grid.group(sequence as u64, ms(*start))); + slots.extend(grid.group(sequence as u64, ms(*start), ms(*start))); } slots.extend(grid.finish(Some(ms(end)), Some(ms(end)))); listed(slots) @@ -640,7 +643,7 @@ mod test { let mut grid = Grid::new(Duration::from_millis(length), 256); let mut slots = Vec::new(); for (sequence, start) in starts.iter().enumerate().skip(join) { - slots.extend(grid.group(sequence as u64, ms(*start))); + slots.extend(grid.group(sequence as u64, ms(*start), 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 @@ -648,7 +651,7 @@ mod test { 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))); + early_slots.extend(early.group(sequence as u64, ms(*start), 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)))); @@ -679,8 +682,8 @@ mod test { fn a_late_join_numbers_like_an_early_one() { let early = run(2000, &[0, 7000, 7200], 7400); let mut grid = Grid::new(Duration::from_secs(2), 256); - let mut late = grid.group(1, ms(7000)); - late.extend(grid.group(2, ms(7200))); + let mut late = grid.group(1, ms(7000), ms(7000)); + late.extend(grid.group(2, ms(7200), ms(7200))); late.extend(grid.finish(Some(ms(7400)), Some(ms(7400)))); assert_eq!(listed(late), [(3, 1..3, 6000, 7400)]); assert_eq!(early.last(), Some(&(3, 1..3, 6000, 7400))); @@ -690,22 +693,22 @@ mod test { #[test] fn a_segment_completes_once_a_later_one_starts() { let mut grid = Grid::new(Duration::from_secs(2), 256); - assert!(grid.group(0, ms(0)).is_empty()); + assert!(grid.group(0, ms(0), ms(0)).is_empty()); assert!( - grid.group(1, ms(1000)).is_empty(), + grid.group(1, ms(1000), ms(1000)).is_empty(), "its successor may still reach the next line" ); - assert_eq!(listed(grid.group(2, ms(2000))), [(0, 0..2, 0, 2000)]); - assert!(grid.group(3, ms(3500)).is_empty()); + assert_eq!(listed(grid.group(2, ms(2000), ms(2000))), [(0, 0..2, 0, 2000)]); + assert!(grid.group(3, ms(3500), ms(3500)).is_empty()); assert_eq!( - listed(grid.group(4, ms(4500))), + listed(grid.group(4, ms(4500), ms(4500))), [(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.group(0, ms(500), ms(500)).is_empty()); assert!( grid.reach(ms(1900)).is_empty(), "short of the line, it may still end before it" @@ -719,14 +722,14 @@ mod test { "it opens segment 1, which nothing completes yet" ); assert!(!grid.pending()); - assert!(grid.group(1, ms(2500)).is_empty()); + assert!(grid.group(1, ms(2500), 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!(grid.group(2, ms(4500), ms(4500)).is_empty()); assert_eq!( listed(grid.finish(Some(ms(5000)), Some(ms(5000)))), [(2, 1..3, 2500, 5000)] @@ -737,8 +740,8 @@ mod test { #[test] fn a_long_pause_lists_at_most_the_newest_gaps() { let mut grid = Grid::new(Duration::from_secs(2), 3); - grid.group(0, ms(0)); - let slots = listed(grid.group(1, ms(3_600_000))); + grid.group(0, ms(0), ms(0)); + let slots = listed(grid.group(1, ms(3_600_000), ms(3_600_000))); assert_eq!(slots.len(), 4); assert_eq!(slots[0], (0, 0..1, 0, 2000)); assert_eq!(slots[1].0, 1797); @@ -749,8 +752,8 @@ mod test { #[test] fn a_rewind_within_a_slot_resets() { let mut grid = Grid::new(Duration::from_secs(2), 256); - assert!(grid.group(0, ms(10_500)).is_empty()); - assert_eq!(grid.group(1, ms(10_200)), [Slot::Reset]); + assert!(grid.group(0, ms(10_500), ms(10_500)).is_empty()); + assert_eq!(grid.group(1, ms(10_200), ms(10_200)), [Slot::Reset]); assert_eq!( listed(grid.finish(Some(ms(10_400)), Some(ms(10_400)))), [(5, 1..2, 10_000, 10_400)], @@ -772,31 +775,37 @@ mod test { .collect() }; let mut grid = Grid::new(Duration::from_secs(2), 256); - grid.group(0, ms(0)); - grid.group(1, ms(1000)); + grid.group(0, ms(0), ms(0)); + grid.group(1, ms(1000), ms(1000)); assert!(content(grid.stop(ms(1500))).is_empty(), "the slot is still open"); - assert_eq!(content(grid.group(2, ms(8000))), [Some(1500)]); + assert_eq!(content(grid.group(2, ms(8000), ms(8000))), [Some(1500)]); // The track ending after a marker ends at the marker. let mut grid = Grid::new(Duration::from_secs(2), 256); - grid.group(0, ms(0)); + grid.group(0, ms(0), ms(0)); grid.stop(ms(700)); assert_eq!(listed(grid.finish(None, None)), [(0, 0..1, 0, 700)]); // Content resuming within the slot runs on to whatever ends it. let mut grid = Grid::new(Duration::from_secs(2), 256); - grid.group(0, ms(0)); + grid.group(0, ms(0), ms(0)); grid.stop(ms(300)); - grid.group(1, ms(1000)); - assert_eq!(content(grid.group(2, ms(2000))), [Some(2000)]); + grid.group(1, ms(1000), ms(1000)); + assert_eq!(content(grid.group(2, ms(2000), ms(2000))), [Some(2000)]); + + // A group placed at a start below its first frame ends the content before it at that frame, + // not at its start: the last sample keeps its whole duration. + let mut grid = Grid::new(Duration::from_secs(2), 256); + grid.group(0, ms(0), ms(100)); + assert_eq!(content(grid.group(2000, ms(2000), ms(2100))), [Some(2100)]); } /// A group going back past the open slot resets the numbering. #[test] fn a_rewind_resets() { let mut grid = Grid::new(Duration::from_secs(2), 256); - grid.group(0, ms(10_000)); - assert_eq!(grid.group(1, ms(0)), [Slot::Reset]); + grid.group(0, ms(10_000), ms(10_000)); + assert_eq!(grid.group(1, ms(0), ms(0)), [Slot::Reset]); assert_eq!( listed(grid.finish(Some(ms(2000)), Some(ms(2000)))), [(0, 1..2, 0, 2000)] diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 0ebc98baf87..6e705fdc5c1 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -2152,12 +2152,12 @@ impl Follow { self.reading = false; (self.grid.stop(at), (group.start, None), None) } - First::Media(pts, reach, declared) => { + First::Media(pts, media, reach, declared) => { let sequence = group.start; 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); + let mut slots = self.grid.group(sequence, pts, media); // A fragment carrying the whole group may already pass the next line. if let Some(newest) = reach.newest() { slots.extend(self.grid.reach(newest)); @@ -2596,9 +2596,9 @@ impl Reach { /// What a group's first frame holds. enum First { - /// Media: its place, the group's start or else its first sample's pts, with what its samples reach - /// and the picture size its keyframe declares. - Media(moq_net::Timestamp, Reach, Option<(u32, u32)>), + /// Media: its place, the group's start or else its first sample's pts, then its first sample's + /// pts, with what its samples reach and the picture size its keyframe declares. + Media(moq_net::Timestamp, moq_net::Timestamp, Reach, Option<(u32, u32)>), /// A discontinuity marker, a frame with no payload: the content stops at its timestamp. Marker(moq_net::Timestamp), } @@ -2631,7 +2631,7 @@ fn first_frame( let size = probe.and_then(|probe| probe.picture_size(first).ok().flatten()); let mut reach = Reach::default(); reach.add(decoded); - Some(First::Media(place, reach, size)) + Some(First::Media(place, pts, reach, size)) } /// The row listing `slot`, starting a new discontinuity when `broken`. From 025cafe8c74c959c06f9e77f8107a5711a2c5bc6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 00:56:45 -0800 Subject: [PATCH 7/7] fix(moq-hls): a hand-over and a lone last frame time media by its first frame, not its group start A retired rendition's cut ended its last sample at the replacement's group start, and the fallback spacing for a lone last frame measured group starts. Both now use the first frame's pts, keeping the start for grid placement. Co-Authored-By: Claude Opus 5.5 --- quest/m0/test-flakes-3/webrtc-reoffer-load.md | 2 +- rs/moq-hls/src/export/mod.rs | 39 ++++++++++++++- rs/moq-hls/src/export/rendition.rs | 48 ++++++++++++------- 3 files changed, 70 insertions(+), 19 deletions(-) diff --git a/quest/m0/test-flakes-3/webrtc-reoffer-load.md b/quest/m0/test-flakes-3/webrtc-reoffer-load.md index 9e3648a9b13..2b46389691e 100644 --- a/quest/m0/test-flakes-3/webrtc-reoffer-load.md +++ b/quest/m0/test-flakes-3/webrtc-reoffer-load.md @@ -8,5 +8,5 @@ It failed once in a loaded `just check` on 2026-11-19 (while building [moq-dev/moq#9222](https://github.com/moq-dev/moq/pull/9222), which touches no WebRTC code): `received` hit its 10s `TIMEOUT` ("the viewer neither received nor closed", `rs/moq-webrtc/src/lib.rs:300`) after 10.18s, and it passed alone in 0.9s. The panic does not say which `received` call timed out: the first viewer's packet, or the re-offered session's loop that pushes a packet every 20ms. -Reproduce first under CPU pressure, such as `cargo nextest run -p moq-webrtc a_reoffer --stress-count 50` inside `systemd-run --user --scope -p CPUQuota=100%`, then find which wait stalls and why: ICE over real sockets racing the 20ms push loop, or the new session joining past the delay budget so every pushed packet ages out before it reads. +Reproduce first under CPU pressure like the failing run's: a one-core scope alone starves only the test's own threads, so also keep the other cores busy, such as `cargo nextest run -p moq-webrtc a_reoffer --stress-count 50` inside `systemd-run --user --scope -p CPUQuota=100%` while a workspace build runs beside it, then find which wait stalls and why: ICE over real sockets racing the 20ms push loop, or the new session joining past the delay budget so every pushed packet ages out before it reads. Keep the epic's rules: no longer timeout, no retry. diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index cb00cb474fa..f1530aabde0 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -3672,6 +3672,22 @@ mod tests { self.group(pts_ms, 1); } + /// Write the group starting at `start_ms` with a single keyframe at `pts_ms`. + fn keyed(&mut self, start_ms: u64, pts_ms: u64) { + let mut group = self + .track + .create_group(moq_net::group::Info { start: start_ms }) + .unwrap(); + let frame = vp8_frame(pts_ms * 1_000, true); + hang::container::Frame { + timestamp: frame.timestamp, + payload: frame.payload, + } + .write_to(&mut group) + .unwrap(); + group.finish().unwrap(); + } + /// Write the group at `pts_ms` with a single keyframe declaring a `width`x`height` /// picture in band. fn sized(&mut self, pts_ms: u64, (width, height): (u16, u16)) { @@ -4550,7 +4566,9 @@ mod tests { test.sync(); let new = test.rendition("video0"); // 6 and 7 finish segment 1 past the retire; 8 to 11 are segment 2, which 12 completes. - for sequence in 6..13 { + // Group 6 starts at 3s with its keyframe 100ms later. + media.keyed(3_000, 3_100); + for sequence in 7..13 { media.at(sequence * 500); } let snapshot = test.listed("video0", 2).await; @@ -4565,6 +4583,11 @@ mod tests { [2_000, 1_000, 2_000], "the predecessor's part ends at the group at 3s" ); + assert_eq!( + old.rows().last().and_then(|row| row.content), + Some(Duration::from_millis(3_100)), + "its last sample runs to the replacement's first frame" + ); let id = segments::Id { generation: None, tag: cut, @@ -4642,6 +4665,20 @@ mod tests { ); } + // A lone last frame borrows the gap between the first frames before it, not between the group + // starts: groups keyed below their keyframes by different amounts space their media apart. + #[tokio::test(start_paused = true)] + async fn a_lone_last_frame_borrows_the_media_spacing() { + let test = Groups::with(&["video0"], &[]); + let mut media = test.publish("video0"); + media.keyed(0, 1_900); + media.keyed(2_000, 2_100); + media.finish(); + let snapshot = test.listed("video0", 1).await; + let durations: Vec<_> = snapshot.segments.iter().map(|s| s.duration.as_millis()).collect(); + assert_eq!(durations, [2_000, 300], "the last frame at 2.1s runs 200ms"); + } + // A segment spanning more groups than one request fetches is listed as a gap, never as a // segment that every request refuses. #[tokio::test(start_paused = true)] diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 6e705fdc5c1..60862f651d1 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -333,8 +333,8 @@ struct Claim { /// [`handover`](Rendition::handover): the groups this instance still lists are those up to it, /// and a replacement on the same track lists only groups past it. boundary: Option, - /// Retired, where the replacement's media starts: the first group past the boundary. - theirs_at: Option, + /// Retired, where the replacement starts: the first group past the boundary. + theirs_at: Option, /// The oldest group no completed segment holds, and the open segment if one is: what a retire /// can still hand over. unplaced: Option<(u64, Option)>, @@ -349,10 +349,18 @@ struct Claim { #[derive(Clone, Copy)] struct Resize { group: u64, - pts: moq_net::Timestamp, + at: At, size: (u32, u32), } +/// Where a group goes on the grid, and where its first frame's media starts: they differ when its +/// start is below its keyframe. +#[derive(Clone, Copy, Debug)] +struct At { + place: moq_net::Timestamp, + media: moq_net::Timestamp, +} + /// A single HLS rendition: master-playlist metadata, its window over its media track's groups /// numbered on the broadcast's grid (which renders its media playlist), and on-demand segment /// fetching. @@ -803,7 +811,7 @@ impl Rendition { claim.boundary = claim.seen; if let Some(resized) = self.handover(&claim, successor) { claim.boundary = resized.group.checked_sub(1); - claim.theirs_at = Some(resized.pts); + claim.theirs_at = Some(resized.at); // No group of the open segment is this instance's, so it lists nothing more. if let Some((first, open)) = claim.unplaced && first == resized.group @@ -1985,6 +1993,11 @@ impl kio::Task for InitBuild { #[cfg(test)] impl Rendition { + /// The rows this instance lists itself, oldest first. + pub(crate) fn rows(&self) -> Vec { + self.live.window().segments + } + /// The current CMAF init segment, whatever its hash, built on first request and cached. pub(crate) async fn latest_init(&self) -> Result> { let mut load = LoadInit::default(); @@ -2087,8 +2100,8 @@ enum Step { End(moq_net::group::Consumer, Option), } -/// A group read, and its first pts unless it is a marker. -type Read = (u64, Option); +/// A group read, and where it starts unless it is a marker. +type Read = (u64, Option); /// What a [`WatchMedia`] numbers its groups with, and how far it got. struct Follow { @@ -2102,7 +2115,7 @@ struct Follow { /// The last group a predecessor on the same track read: only later ones are this instance's. after: Option, grid: grid::Grid, - /// The newest group, its first pts, and what its first frame reached, read again for its + /// The newest group, its first frame's pts, and what that frame reached, read again for its /// content's end if the track ends after it, and the gap from the group before it. latest: Option<(moq_net::group::Consumer, moq_net::Timestamp, Reach)>, spacing: Option, @@ -2155,16 +2168,16 @@ impl Follow { First::Media(pts, media, reach, declared) => { let sequence = group.start; if let Some((_, previous, _)) = &self.latest { - self.spacing = pts.checked_sub(*previous).ok().map(super::span).or(self.spacing); + self.spacing = media.checked_sub(*previous).ok().map(super::span).or(self.spacing); } let mut slots = self.grid.group(sequence, pts, media); // 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.latest = Some((group, media, reach)); self.reading = true; - (slots, (sequence, Some(pts)), declared) + (slots, (sequence, Some(At { place: pts, media })), declared) } }; self.list(rendition, slots, Some(read), size, false) @@ -2200,10 +2213,10 @@ impl Follow { let boundary = claim.boundary; let theirs = |last: Option| boundary.is_none_or(|boundary| last.is_some_and(|last| last > boundary)); if claim.retired - && let Some((sequence, Some(pts))) = read + && let Some((sequence, Some(at))) = read && theirs(Some(sequence)) { - claim.theirs_at = claim.theirs_at.or(Some(pts)); + claim.theirs_at = claim.theirs_at.or(Some(at)); } let theirs_at = claim.theirs_at; for slot in slots { @@ -2226,15 +2239,16 @@ impl Follow { .. } if claim.retired && theirs(groups.last()) => match (boundary, theirs_at) { // The replacement can't list this segment's number again, so this instance - // lists the groups it had read, ending where the replacement's media starts. + // lists the groups it had read, ending where the replacement's group starts, with + // its last sample running to the replacement's first frame. (Some(boundary), Some(at)) if groups.first().is_some_and(|first| first <= boundary) => { let slot = grid::Slot::Media { segment, groups: groups.through(boundary), pts, start, - end: at, - content: Some(at), + end: at.place, + content: Some(at.media), }; (slot, true) } @@ -2276,11 +2290,11 @@ impl Follow { if let Some((sequence, _)) = read { claim.seen = Some(sequence); } - if let (Some((group, Some(pts))), Some(size)) = (read, size) + if let (Some((group, Some(at))), Some(size)) = (read, size) && claim.size != Some(size) { claim.size = Some(size); - claim.resized = Some(Resize { group, pts, size }); + claim.resized = Some(Resize { group, at, size }); } claim.unplaced = grid.unplaced().map(|first| (first, grid.open())); if !claim.retired