diff --git a/quest/m2/time-addressing/branch-salvage.md b/quest/m2/time-addressing/branch-salvage.md deleted file mode 100644 index 4dd74f5d9f2..00000000000 --- 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 dd0941f52de..69fdf78b75f 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/codec/opus/import.rs b/rs/moq-mux/src/codec/opus/import.rs index cbf45b5e58e..2f1cbc0e665 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-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 8e8fbd7b851..8c07a1e795b 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); @@ -3403,18 +3416,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 61f53a55243..83ce64a5d96 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, @@ -395,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)] diff --git a/rs/moq-mux/tests/legacy_audio.rs b/rs/moq-mux/tests/legacy_audio.rs index 6a9b6c188cd..fbd62d32847 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}"); + } +} diff --git a/rs/moq-webrtc/src/lib.rs b/rs/moq-webrtc/src/lib.rs index d60de649562..b280725fd1c 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(); }