From f4e1d914b37e8ac20f1fa7902f0273ad5e96a13e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 18:56:59 -0800 Subject: [PATCH 1/5] chore(quest): claim quest/m2/time-addressing/branch-salvage.md Quest-Claim: 6ebcc17f775b3af1 From 56b120b093fca98cfc036218f78e69a773c4f459 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 19:37:52 -0800 Subject: [PATCH 2/5] fix(moq-mux): a TS export keeps the clock on a retagged rendition's PID A rendition the source reopens (a language retag) can retire before the one replacing it on the same PID lists with its first frame. The export moved the clock to its own PID in that gap; it now keeps the clock while a cataloged track holds the PID. Co-Authored-By: Claude Opus 5.5 --- quest/m2/time-addressing/branch-salvage.md | 43 ------------ quest/m2/time-addressing/group-end-whole.md | 1 - rs/moq-mux/src/container/ts/export.rs | 10 ++- rs/moq-mux/src/container/ts/revision_test.rs | 74 +++++++++++++------- 4 files changed, 52 insertions(+), 76 deletions(-) delete mode 100644 quest/m2/time-addressing/branch-salvage.md diff --git a/quest/m2/time-addressing/branch-salvage.md b/quest/m2/time-addressing/branch-salvage.md deleted file mode 100644 index 4dd74f5d9f..0000000000 --- a/quest/m2/time-addressing/branch-salvage.md +++ /dev/null @@ -1,43 +0,0 @@ -# [S] Land what stands alone from the closed declared-ends branch - -## Goal - -The fixes and tests on closed -[moq-dev/moq#9192](https://github.com/moq-dev/moq/pull/9192)'s branch -(`quest/m2/time-addressing/consumers`, kept for reference) that do not depend -on reading GROUP_END's position land on main, each with a test that fails -without it. - -## Plan - -Decided 2026-11-19 (maintainer, closing #9192): salvage the TS export's PCR -PID fix, the Opus import's per-packet durations, and the end and loss tests -worth keeping. Research on the branch (head `20c13b1308`) found: - -- PCR PID fix, commit `1ca5b60cac`: `revise()` in - `rs/moq-mux/src/container/ts/export.rs` (main `:3405-3418`) keeps the PCR - PID when the track on it is `cataloged`, not only `listed`. It uses only - fields on main. It has no dedicated test: it surfaced under that commit's - `revision_test.rs` harness change (AAC frames back to back), guarding - `a_descriptor_change_revises_the_entry_and_keeps_the_clock` - (`revision_test.rs:364`). Write a test that fails on main without the fix - first; if main cannot hit the race, say so and drop it. -- Legacy test, commit `095cdea03a`: - `an_old_publishers_marker_group_reads_as_an_end` in - `rs/moq-mux/tests/legacy_audio.rs` writes a marker by hand on lite-05/06 - with main's APIs and should pass as is. -- Opus per-packet durations, commits `c4ad9643f3` and `7bb71b0710`: - `decode()` in `rs/moq-mux/src/codec/opus/import.rs` sets `Frame.duration` - from `packet_samples`. On main that gives `cut(None)` an exact - `estimated_end`, so each Opus group finishes whole at its packet's end; - on the branch that aging is why the WHEP tests changed - (`rs/moq-webrtc/src/lib.rs` `flowing!`, and `cd42c40e49`). Recommended: - land it only if something still reads the duration once - [GROUP_END has no End](/quest/m2/time-addressing/group-end-whole.md), such - as hang's duration marker or the HLS export, and say in the PR either way. - -The rest of the branch (its end and loss tests, `read_breaks`, the HLS -`whole_end` reader, the webrtc ingest expectations) rests on reading -GROUP_END's position and stays behind. - -Public API: none. Wire: none. diff --git a/quest/m2/time-addressing/group-end-whole.md b/quest/m2/time-addressing/group-end-whole.md index dd0941f52d..69fdf78b75 100644 --- a/quest/m2/time-addressing/group-end-whole.md +++ b/quest/m2/time-addressing/group-end-whole.md @@ -80,4 +80,3 @@ 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 -- [Salvage from #9192](/quest/m2/time-addressing/branch-salvage.md) - pieces of the closed branch that stand alone diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 8e8fbd7b85..016159c679 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -3403,18 +3403,16 @@ where } /// Rebuild the PMT from the listed tracks, leading the next frame muxed when it changed. The - /// clock stays on its PID unless the stream carrying it retired. + /// clock stays on its PID unless the stream carrying it retired with no track the catalog + /// lists taking the PID over: a rendition the source reopens (a language retag) can retire + /// before the one replacing it lists with its first frame. fn revise(&mut self) -> Result<()> { let Some(psi) = self.program.psi.as_ref() else { return Ok(()); }; let current = psi.pcr_pid().context("PMT without a clock")?; let kept = psi.own_clock() == Some(current) - || self - .program - .tracks - .values() - .any(|track| track.listed && track.pid == current); + || (self.program.tracks.values()).any(|track| track.pid == current && (track.listed || track.cataloged)); let pcr_pid = match kept { true => current, false => self.pick_clock()?, diff --git a/rs/moq-mux/src/container/ts/revision_test.rs b/rs/moq-mux/src/container/ts/revision_test.rs index 61f53a5524..ee7e30a06d 100644 --- a/rs/moq-mux/src/container/ts/revision_test.rs +++ b/rs/moq-mux/src/container/ts/revision_test.rs @@ -45,10 +45,10 @@ struct Span<'a> { } /// Import `spans` one by one, each opened by a PAT and a PMT at the next version and running -/// for `intervals` PCRs 40 ms apart (the first for three seconds), with an AAC frame on each -/// audio stream and a PES on each private one every interval. The export polls after each, -/// as a live one keeps up with the catalog, and runs to its end after the last. Returns -/// every PMT it wrote, each run of repeats once. +/// for `intervals` PCRs 40 ms apart (the first for three seconds), with a PES of AAC frames on +/// each audio stream, back to back across them, and a PES on each private one every interval. +/// The export polls after each, as a live one keeps up with the catalog, and runs to its end +/// after the last. Returns every PMT it wrote, each run of repeats once. async fn reexport(spans: &[Span<'_>], intervals: u64) -> Vec { let spans: Vec<_> = spans.iter().map(|span| (PMT_PID, span)).collect(); tables(&reexport_frames(&spans, intervals).await, PMT_PID) @@ -67,6 +67,8 @@ async fn reexport_frames(spans: &[(u16, &Span<'_>)], intervals: u64) -> Vec)], intervals: u64) -> Vec aac(ticks / 300 + 9_000, pid as u8), - PRIVATE => pes(0xbd, pid as u8), - _ => pes(0xfc, pid as u8), - }; - mux.whole(pid, &payload); + match stream_type { + // Back to back, so the stream ends only where the span drops it: a gap between + // frames would end each PES's group short of the next. + AUDIO => { + let next: &mut u64 = audio.entry(pid).or_insert(start); + *next = (*next).max(start); + let frames = (end - *next).div_ceil(AAC_TICKS); + mux.whole(pid, &aac(*next, pid as u8, frames as usize)); + *next += frames * AAC_TICKS; + } + PRIVATE => { + mux.whole(pid, &pes(0xbd, pid as u8)); + } + _ => { + mux.whole(pid, &pes(0xfc, pid as u8)); + } + } } ticks += 40 * MS; } @@ -142,10 +156,15 @@ where } } -/// An ADTS AAC frame presenting at `pts`, its payload filled with `fill`. -fn aac(pts: u64, fill: u8) -> Vec { +/// How long an AAC frame of 1024 samples at 48 kHz lasts, in 90 kHz ticks. +const AAC_TICKS: u64 = 1024 * 90_000 / 48_000; + +/// A PES of `count` ADTS AAC frames back to back, the first presenting at `pts`, their payload +/// filled with `fill`. +fn aac(pts: u64, fill: u8, count: usize) -> Vec { let mut frame = super::adts::write_header(2, 48_000, 2, 64).unwrap().to_vec(); frame.resize(7 + 64, fill); + let frame = frame.repeat(count); let field = [ 0x21 | ((pts >> 29) & 0x0e) as u8, (pts >> 22) as u8, @@ -359,23 +378,26 @@ async fn a_retyped_stream_revises_its_entry_in_place() { assert_eq!(tables[1].streams[1].2, KLV); } -/// An audio language retag reopens the rendition, which takes the PID and the clock over. +/// An audio language retag reopens the rendition, which takes the PID and the clock over: the +/// clock stays on the PID through the gap between the old rendition retiring and the new one +/// listing with its first frame. #[tokio::test(start_paused = true)] async fn a_descriptor_change_revises_the_entry_and_keeps_the_clock() { - let tables = reexport( - &[ - Span { - streams: &[(AUDIO, AUDIO_PID, ENG)], - }, - Span { - streams: &[(AUDIO, AUDIO_PID, FRA)], - }, - ], - 25, - ) - .await; + let eng = Span { + streams: &[(AUDIO, AUDIO_PID, ENG)], + }; + let fra = Span { + streams: &[(AUDIO, AUDIO_PID, FRA)], + }; + let frames = reexport_frames(&[(PMT_PID, &eng), (PMT_PID, &fra)], 25).await; + let clocks: Vec = packets(&frames) + .filter(|packet| packet[3] & 0x20 != 0 && packet[4] > 0 && packet[5] & 0x10 != 0) + .map(pid) + .collect(); + assert!(!clocks.is_empty()); + assert!(clocks.iter().all(|&clock| clock == AUDIO_PID), "the clock left its PID"); assert_eq!( - tables, + tables(&frames, PMT_PID), vec![ Table { program: 1, From 6e94ff0b0961fd6f377eef80448ebe4cc856df17 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 19:37:56 -0800 Subject: [PATCH 3/5] test(moq-mux): a lite-05/06 session reads an old publisher's marker group as an end Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/tests/legacy_audio.rs | 59 ++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/rs/moq-mux/tests/legacy_audio.rs b/rs/moq-mux/tests/legacy_audio.rs index 6a9b6c188c..fbd62d3284 100644 --- a/rs/moq-mux/tests/legacy_audio.rs +++ b/rs/moq-mux/tests/legacy_audio.rs @@ -174,3 +174,62 @@ async fn a_dropped_run_waits_for_the_next_groups_first_packet() { } } } + +/// A publisher from before moq-lite-07 declared a pause with a marker group, an empty payload at +/// the end. A wire without group ends still carries one, and a reader still reads it as the end. +#[tokio::test(start_paused = true)] +async fn an_old_publishers_marker_group_reads_as_an_end() { + for version in ["moq-lite-05", "moq-lite-06"] { + let (publisher, subscriber, _sessions) = connect(version.parse().unwrap()).await; + let config = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); + let container = Container::try_from(&config).unwrap(); + let route = publisher.route("live", Default::default()).expect("route"); + let track = route + .broadcast() + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .expect("track"); + + let remote = kio::clock::timeout(TIMEOUT, subscriber.consume().follow("live", None).unwrap().available()) + .await + .expect("announced") + .expect("remote broadcast") + .unwrap(); + let subscription = moq_net::track::Subscription::default() + .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(5))); + let subscribed = kio::clock::timeout(TIMEOUT, remote.track("audio").expect("track").subscribe(subscription)) + .await + .expect("subscribed") + .expect("subscription"); + let mut reader = Consumer::new(subscribed, Container::try_from(&config).unwrap()); + + // A packet, the marker at its end, then speech a second later. + for (start, payload) in [(0, &PACKET[..]), (20_000, &[][..]), (1_000_000, &PACKET[..])] { + let timestamp = moq_net::Timestamp::from_micros(start).unwrap(); + let mut group = track.append_group(timestamp).unwrap(); + let frame = Frame { + timestamp, + payload: Bytes::copy_from_slice(payload), + keyframe: true, + duration: None, + }; + container.write(&mut group, &[frame]).unwrap(); + group.finish().unwrap(); + } + + // These wires report the run the pause skipped as dropped, so a gap may follow the end. + let mut reads = Vec::new(); + while reads.len() < 3 { + let read = kio::clock::timeout(TIMEOUT, reader.read()) + .await + .unwrap_or_else(|_| panic!("{version}: stalled after {reads:?}")) + .unwrap() + .expect("a read"); + reads.push(match read { + Read::Frame { frame, .. } => format!("frame {}", frame.timestamp.as_micros().unwrap()), + Read::End { end, .. } => format!("end {}", end.as_micros().unwrap()), + Read::Gap { .. } => continue, + }); + } + assert_eq!(reads, ["frame 0", "end 20000", "frame 1000000"], "{version}"); + } +} From 38b52138450c220468f60402d1883a4602728da3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 19:37:58 -0800 Subject: [PATCH 4/5] fix(moq-mux): the Opus import times each packet from its TOC byte A pause's marker now lands where the last packet's audio stops rather than where that packet starts, which cut the last 20 ms short. Each packet's group also ends whole there, so a paused source's last group ages out of a live subscription's delay budget; the WHEP re-offer test now keeps its source live. Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/codec/opus/import.rs | 55 +++++++++++++++++++++++++++-- rs/moq-webrtc/src/lib.rs | 17 +++++++-- 2 files changed, 68 insertions(+), 4 deletions(-) diff --git a/rs/moq-mux/src/codec/opus/import.rs b/rs/moq-mux/src/codec/opus/import.rs index cbf45b5e58..2f1cbc0e66 100644 --- a/rs/moq-mux/src/codec/opus/import.rs +++ b/rs/moq-mux/src/codec/opus/import.rs @@ -109,11 +109,15 @@ impl Import { // Only the first frame of each group is a keyframe, so the group spans until the caller cuts // instead of opening one group (one QUIC stream) per packet. let keyframe = self.track.needs_keyframe(); + let payload = frame.into_bytes(); + // The packet states its own duration, so a pause's marker lands where its audio stops. + let duration = super::packet_samples(&payload) + .and_then(|samples| moq_net::Timestamp::from_scale(samples.into(), 48_000).ok()); self.track.write(Frame { timestamp, - payload: frame.into_bytes(), + payload, keyframe, - duration: None, + duration, })?; Ok(()) } @@ -227,4 +231,51 @@ mod tests { let _finished = import.finish().unwrap(); } + + /// A pause ends where the last packet's audio does, as its TOC byte says, not where the packet + /// starts: hang's marker is the only place a reader learns where a group's audio stops. + #[tokio::test(start_paused = true)] + async fn a_pause_ends_where_the_last_packet_does() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let track = broadcast + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + // Delayed, so the reader starts from the first group rather than the newest. + let subscriber = track.subscribe( + moq_net::track::Subscription::default() + .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(5))), + ); + let config: hang::catalog::AudioConfig = crate::codec::opus::Config::new(48_000, 2).into(); + let wire = crate::catalog::hang::Container::try_from(&config).unwrap(); + let mut import = super::Import::new(track, catalog.reserve(), config).unwrap(); + + // Two 20 ms CELT packets, then a pause. + for start in [0, 20_000] { + import + .decode(&[31 << 3, 0][..], Some(Timestamp::from_micros(start).unwrap())) + .unwrap(); + } + import.discontinuity().unwrap(); + let _finished = import.finish().unwrap(); + + let mut media = crate::container::Consumer::new(subscriber, wire); + let mut reads = Vec::new(); + while let Some(read) = kio::clock::timeout(Duration::from_secs(1), media.read()) + .await + .unwrap() + .unwrap() + { + reads.push(match read { + crate::container::Read::Frame { frame, .. } => { + format!("frame {}", frame.timestamp.as_micros().unwrap()) + } + crate::container::Read::End { end, .. } => format!("end {}", end.as_micros().unwrap()), + crate::container::Read::Gap { .. } => continue, + }); + } + // The marker sits one unit of the track's timescale before the packet's end, so what resumes + // right there still starts after it. + assert_eq!(reads, ["frame 0", "frame 20000", "end 39999"]); + } } diff --git a/rs/moq-webrtc/src/lib.rs b/rs/moq-webrtc/src/lib.rs index d60de64956..b280725fd1 100644 --- a/rs/moq-webrtc/src/lib.rs +++ b/rs/moq-webrtc/src/lib.rs @@ -427,8 +427,21 @@ mod tests { let _ = old.await; let (_new, mut viewer) = raw_view_on(url, udp).await; let _new_session = sessions.recv().await.unwrap(); - push(&mut *bridge, 40_000, NEW_PACKET); - let played = received(&mut viewer).await.expect("the new session never played"); + // The source keeps sending, as a live one does: each packet's group ends whole where the + // packet does, so a paused source's last one ages out before a session arriving past its + // delay budget reads it. + let read = received(&mut viewer); + tokio::pin!(read); + let mut at = 40_000; + let played = loop { + push(&mut *bridge, at, NEW_PACKET); + at += 20_000; + tokio::select! { + played = &mut read => break played, + _ = kio::clock::sleep(Duration::from_millis(20)) => {} + } + }; + let played = played.expect("the new session never played"); assert!([OPUS_PACKET, NEW_PACKET].contains(&played.as_slice()), "{played:?}"); http.abort(); } From f03141a16a6499b764e46aade44d0b98f718c626 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 20:06:23 -0800 Subject: [PATCH 5/5] fix(moq-mux): a catalog update leaves a waiting replacement the clock's PID While a retag's replacement waits to list, the clock keeps its PID with no stream on it, which read as the clock's own PID and pushed the replacement elsewhere on the next snapshot. That PID is now reserved for the track holding it. Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/ts/export.rs | 17 +++++++- rs/moq-mux/src/container/ts/revision_test.rs | 45 ++++++++++++++++++++ 2 files changed, 60 insertions(+), 2 deletions(-) diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 016159c679..8c07a1e795 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -2540,7 +2540,19 @@ where let pmt_pid = self.pmt_pid(); let mut taken: Vec = vec![0x0000, 0x1FFF]; taken.extend(self.pmt_pids()); - taken.extend(self.program.psi.as_ref().and_then(|psi| psi.own_clock())); + // The clock's own PID is taken, unless it waits for the track on it to list (a retag's + // replacement, [`Self::revise`]): that track alone may keep it. + let clock = self.program.psi.as_ref().and_then(|psi| psi.own_clock()); + let holder = clock.and_then(|pid| { + (self.program.tracks.iter()) + .find(|(_, track)| track.cataloged && !track.listed && track.pid == pid) + .map(|(name, _)| name.clone()) + }); + let reserved = + |name: &str, pid: u16| holder.as_deref().is_some_and(|holder| holder != name) && Some(pid) == clock; + if holder.is_none() { + taken.extend(clock); + } taken.extend( self.program .tracks @@ -2563,6 +2575,7 @@ where for &name in &joining { if let Some(pid) = mpegts.tracks.get(name).map(|t| t.pid) && !taken.contains(&pid) + && !reserved(name, pid) { taken.push(pid); pids.insert(name.clone(), pid); @@ -2571,7 +2584,7 @@ where for &name in &joining { if !pids.contains_key(name) { let mut pid = FIRST_ES_PID; - while taken.contains(&pid) || draining.contains(&pid) { + while taken.contains(&pid) || draining.contains(&pid) || reserved(name, pid) { pid += 1; } taken.push(pid); diff --git a/rs/moq-mux/src/container/ts/revision_test.rs b/rs/moq-mux/src/container/ts/revision_test.rs index ee7e30a06d..83ce64a5d9 100644 --- a/rs/moq-mux/src/container/ts/revision_test.rs +++ b/rs/moq-mux/src/container/ts/revision_test.rs @@ -417,6 +417,51 @@ async fn a_descriptor_change_revises_the_entry_and_keeps_the_clock() { ); } +/// A catalog update between a retagged rendition retiring and its replacement listing leaves +/// the replacement its recorded PID, which the clock kept waiting for it. +#[tokio::test(start_paused = true)] +async fn a_catalog_update_before_the_replacement_lists_keeps_its_pid() { + let (mut broadcast, consumer, mut catalog) = broadcast(); + let (name, mut old) = aac_track(&mut broadcast, &mut catalog, Some(AUDIO_PID)); + let mut frames = Vec::new(); + let start = kio::clock::now(); + let mut export = export_of(&consumer).await; + live(&mut export, &mut frames, start, &mut [(&mut old, 0x21)], 0, 3_000).await; + + // The retag: the old rendition leaves and ends, the new one is cataloged on its PID. + remove(&mut catalog, &name); + let (_, mut new) = aac_track(&mut broadcast, &mut catalog, Some(AUDIO_PID)); + let _finished = old.finish().unwrap(); + kio::clock::sleep(DELAY * 2).await; + settle(&mut export, &mut frames).await; + // Another snapshot before the new rendition's first frame. + let (_, mut other) = aac_track(&mut broadcast, &mut catalog, None); + settle(&mut export, &mut frames).await; + live( + &mut export, + &mut frames, + start, + &mut [(&mut new, 0x22), (&mut other, 0x23)], + 6_000, + 8_000, + ) + .await; + let _finished = new.finish().unwrap(); + let _finished = other.finish().unwrap(); + catalog.finish().unwrap(); + drain(&mut export, &mut frames).await; + + assert!( + !marks(&frames, AUDIO_PID, &[0x22]).is_empty(), + "the replacement left its PID" + ); + let clocks: Vec = packets(&frames) + .filter(|packet| packet[3] & 0x20 != 0 && packet[4] > 0 && packet[5] & 0x10 != 0) + .map(pid) + .collect(); + assert!(clocks.iter().all(|&clock| clock == AUDIO_PID), "the clock left its PID"); +} + /// A listed track keeps the descriptors its packets went out under: a catalog revising them /// under the same name revises nothing, as a revised stream comes under a new name. #[tokio::test(start_paused = true)]