From aab629645e6f734b8849eb42ffed5a4482a374ff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 04:40:54 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m1/ts-mux-rate-hold.md Quest-Claim: 7c7a1b9d77321959 From 7c3457b0f4baab29cd65b7d63ab2da9d16873401 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 06:40:48 -0800 Subject: [PATCH 2/3] feat(moq-mux): a TS import's catalog goes out with the first media, and only an export that may pad waits for the mux rate Co-Authored-By: Claude Sonnet 5.5 --- doc/bin/ts.md | 13 +- quest/m1/ts-mux-rate-hold.md | 31 --- quest/m1/ts-republish.md | 4 +- rs/moq-cli/src/publish.rs | 10 +- rs/moq-cli/tests/integration/import.rs | 6 +- rs/moq-mux/CHANGELOG.md | 1 + rs/moq-mux/src/container/ts/export.rs | 64 ++++- rs/moq-mux/src/container/ts/export_test.rs | 119 ++++++++- rs/moq-mux/src/container/ts/import.rs | 297 +++------------------ rs/moq-mux/src/container/ts/mux_rate.rs | 16 +- rs/moq-srt/src/ts.rs | 13 +- 11 files changed, 240 insertions(+), 334 deletions(-) delete mode 100644 quest/m1/ts-mux-rate-hold.md diff --git a/doc/bin/ts.md b/doc/bin/ts.md index daa351a2626..20c8839c158 100644 --- a/doc/bin/ts.md +++ b/doc/bin/ts.md @@ -148,11 +148,14 @@ track, so an `.msf` broadcast needs `--catalog-format hang`. The encoding is in An importer joining a live feed waits for what it needs before publishing. -- **Semantic:** the import waits for the PAT, PMT, and a PCR, and holds the - catalog until two seconds of PCR have measured a constant mux rate or shown - the input to be variable-rate. A subscriber joins at a keyframe, and the - export puts a PAT and PMT ahead of it. From there a late exporter writes the - same packets as a running one, but for continuity counters. +- **Semantic:** the import waits for the PAT, PMT, and a PCR, and publishes the + catalog with the first media. A constant mux rate follows as a catalog update + once two seconds of PCR have measured it; a variable-rate source never records + one. An export without `--mux-rate` waits up to those two seconds for the rate + before it starts, so a variable-rate source costs it one wait. A subscriber + joins at a keyframe, and the export puts a PAT and PMT ahead of it. From + there a late exporter writes the same packets as a running one, but for + continuity counters. - **Passthrough:** nothing is published until the PAT, the clock program's PMT, a PCR, and a group start. Bytes before that, and bytes off the 188-byte grid, are dropped: the output equals the input over the *admitted interval*, diff --git a/quest/m1/ts-mux-rate-hold.md b/quest/m1/ts-mux-rate-hold.md deleted file mode 100644 index 084af98b3c3..00000000000 --- a/quest/m1/ts-mux-rate-hold.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] Only a padded TS export waits for the mux rate - -## Goal - -No TS import withholds its catalog to measure a mux rate. The catalog goes out -with the first media and gains `muxRate` as an update once a PCR window -measures it; a padded (CBR) export that has no `--mux-rate` waits for that -update instead. - -## Plan - -Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). -Since [moq-dev/moq#5287](https://github.com/moq-dev/moq/pull/5287), every -import whose catalog carries the `mpegts` section holds it for a full 2 s PCR -window, CBR or VBR alike (asserted by a test in -`rs/moq-mux/src/container/ts/import.rs`), though only a padded export reads -the rate. Every new SRT connection and every `ffmpeg -f mpegts | moq import -ts` pays it, and ffmpeg's default VBR output never yields a rate. A -contributor measured the hold as about 2 s of the 2.8 s lost per restart -([moq-dev/moq#7102](https://github.com/moq-dev/moq/issues/7102)). The hold is -not on `release`, so moving it breaks nothing shipped. Padded export drew a -line of fixes ([moq-dev/moq#7967](https://github.com/moq-dev/moq/pull/7967), -[moq-dev/moq#8449](https://github.com/moq-dev/moq/pull/8449)). - -Then only an export joining in the first window pays. - -Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) the padded export waits up to one window for the rate (rejected: (b) pad only to an explicit `--mux-rate`; (c) keep the import's hold). - -Public API: none. Wire: the catalog's `muxRate` may arrive in a later catalog -update than the first. - diff --git a/quest/m1/ts-republish.md b/quest/m1/ts-republish.md index 2bb189033ea..58e39064b4f 100644 --- a/quest/m1/ts-republish.md +++ b/quest/m1/ts-republish.md @@ -15,8 +15,8 @@ CLI's `Republish` (`rs/moq-cli/src/publish.rs`), and moq-srt's `Instance` (`rs/moq-srt/src/ts.rs`). [moq-dev/moq#7293](https://github.com/moq-dev/moq/pull/7293) and [moq-dev/moq#7780](https://github.com/moq-dev/moq/pull/7780) fixed only the CLI copy, so moq-srt's `Instance::publish` builds a default catalog on a -default, visible route, and `Import::new` re-arms the 2 s mux-rate hold on -every step. The guide (`doc/bin/ts.md`, Programs and changes) says a +default, visible route, and its catalog carries no mux rate, so an export of +the new instance waits a window for one on every step. The guide (`doc/bin/ts.md`, Programs and changes) says a republished stream "keeps the measured mux rate", which is false for SRT, the path a live contributor uses. Both callers also find the step by `err.downcast::()`, which AGENTS.md's "never match on errors" diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index 47d1d079fa9..1f5f0dc84e6 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -813,7 +813,7 @@ impl Republish { /// A new instance of the broadcast under a new instance, announced once its catalog goes out. /// /// `mux_rate` is the previous instance's measurement of the same multiplex, which the new - /// catalog carries from its first media rather than waiting on a fresh window. + /// catalog carries from its first media, so an export of it needn't wait on a fresh window. fn instance(&self, mux_rate: Option) -> anyhow::Result { let control = self .origin @@ -2212,7 +2212,7 @@ pub(crate) mod tests { /// resolves the broadcast the moment it is announced finds them (#4352). #[tokio::test(start_paused = true)] async fn an_import_announces_once_its_input_declares_its_tracks() { - // Longer than the two seconds a live TS catalog waits on to measure its mux rate. + // Longer than the two seconds a live TS import takes to measure its mux rate. const TS: &[u8] = include_bytes!("../../moq-mux/src/container/ts/test_data/scte35/bbb5s.ts"); const FMP4: &[u8] = include_bytes!("../../moq-mux/src/container/fmp4/test_data/av1.mp4"); for (format, input) in [ @@ -2330,13 +2330,13 @@ pub(crate) mod tests { /// A source whose clock steps back republishes the path under a new instance, announced once /// its catalog goes out, with the sections the first instance's catalog carried. The new - /// catalog reuses the first instance's mux rate, so it goes out with the first media rather - /// than after a fresh two-second measurement window. + /// catalog reuses the first instance's mux rate, so an export of it needn't wait on a fresh + /// measurement window. #[tokio::test(start_paused = true)] async fn a_clock_step_republishes_under_a_new_instance() { // 5 s of H.264 and AAC at a constant 400 kb/s, its clock on PID 0x100. const CLIP: &[u8] = include_bytes!("../../moq-mux/src/container/ts/test_data/bbb5s_cbr.ts"); - // Its first 1.5 s: short of a measurement window, so only a reused rate releases a catalog. + // Its first 1.5 s: short of a measurement window, so only a reused rate is in the catalog. const HEAD: &[u8] = CLIP.split_at(400 * 188).0; let mut flag = vec![0x47, 0x01, 0x00, 0x20, 183, 0x80]; flag.resize(188, 0xff); diff --git a/rs/moq-cli/tests/integration/import.rs b/rs/moq-cli/tests/integration/import.rs index d1815f44166..89e5daf334d 100644 --- a/rs/moq-cli/tests/integration/import.rs +++ b/rs/moq-cli/tests/integration/import.rs @@ -68,7 +68,6 @@ async fn import_delivers_the_catalog_finish_at_eof() { let mut child = import(fixture.url.as_str(), &fixture.fingerprint); let mut stdin = child.stdin.take().expect("stdin"); - // A live TS catalog waits for its initial two-second PCR rate measurement. stdin.write_all(BBB).await.expect("write stdin"); let origin = moq_tokio::origin::spawn(); @@ -128,14 +127,13 @@ async fn import_delivers_the_catalog_finish_at_eof() { } /// About one second of CBR HEVC and Opus: shorter than the two-second mux-rate window, so -/// the catalog is only released at EOF. +/// the import ends before it records a rate. const SHORT: &[u8] = include_bytes!("../../../moq-mux/src/container/ts/test_data/bbb_cbr.ts") .split_at(256 * 188) .0; /// A subscriber already waiting when a short import ends still receives its media: the -/// import announces at the finish, once its catalog lists the tracks, and keeps them servable -/// for the linger after EOF. +/// import keeps its tracks servable for the linger after EOF. #[tokio::test] async fn a_short_import_drains_its_media_to_a_waiting_subscriber() { moq_tokio::crypto::install_default().unwrap(); diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index 06322f35fa7..b29d7afae04 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- A TS import's catalog goes out with the first media instead of waiting two seconds to measure `mpegts.muxRate`, which arrives as a catalog update once a PCR window measures it. An export with no `with_mux_rate` waits up to one window for it before it subscribes the tracks, so a padded export still starts padded; a variable-rate source costs it that one wait. - [**breaking**] Declare per-track archive durations from GOP hints or the first completed record. - [**breaking**] Update the re-exported `mp4_atom` to 0.17, whose `Trun.entries` is now `Trun.samples`: a run without per-sample fields decodes as a count, so a moof of field-less runs no longer materializes an entry per sample before import refuses it. Read entries with `trun.samples.iter()` and build them with `samples: entries.into()`. `TrunEntry::cts` widens to `i64` (a version 0 offset is unsigned), `EsDescriptor` gains its optional fields, and `Dref.urls` becomes typed `entries`. `Dops` gains `channel_mapping: Option` (`None` for family 0). diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index d397e5fc0a4..ac5a702a87e 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -211,6 +211,14 @@ where /// none and the output is unpadded ([`Schedule`]). mux_rate: Option, mux_rate_override: Option, + /// The newest catalog snapshot while the export waits for the rate a TS import has yet to + /// measure: the tracks are subscribed once it ends, so the export joins the media as it is + /// then, not on frames that went stale during the wait. + held_catalog: Option>, + /// Until when that wait lasts, set by the first snapshot that records no rate. + rate_until: Option, + rate_wait: Duration, + rate_timer: Option>>, /// Tune-in point: the first video keyframe's timestamp, captured when the program /// tables are built. Non-video frames before it are dropped so the keyframe leads /// the stream. @@ -1639,6 +1647,10 @@ where trimmed: 0, mux_rate: None, mux_rate_override: None, + held_catalog: None, + rate_until: None, + rate_wait: super::mux_rate::WAIT, + rate_timer: None, } } } @@ -1713,6 +1725,13 @@ where self } + /// Start at once on a catalog that records no rate, for a test whose clock a wait would move. + #[cfg(test)] + pub(super) fn without_rate_wait(mut self) -> Self { + self.program.rate_wait = Duration::ZERO; + self + } + /// Read each track from the oldest group the delay still reaches instead of the live /// edge, and anchor the clock on the first frame instead of acquiring it, for a test that /// writes a broadcast whole before exporting it. @@ -2132,7 +2151,7 @@ where match catalog.poll_next(waiter)? { Poll::Ready(Some(snapshot)) => { self.program.cataloged = true; - self.update_catalog(snapshot)? + self.program.held_catalog = Some(snapshot); } Poll::Ready(None) => { self.program.feed = Feed::Ended; @@ -2141,6 +2160,13 @@ where Poll::Pending => break, } } + if let Some(mut snapshot) = self.program.held_catalog.take() { + if self.awaiting_rate(&mut snapshot, waiter) { + self.program.held_catalog = Some(snapshot); + } else { + self.update_catalog(snapshot)?; + } + } // 1b. Drive the SI subscriptions. Ordinary SI updates its active set; clock // revisions wait for their stamped media position in `mux`. @@ -2232,6 +2258,41 @@ where Ok(true) } + /// Whether the first catalog waits for the rate a TS import is still measuring, which only a + /// padded output reads. The wait ends with the rate or at its deadline, whichever comes first. + fn awaiting_rate(&mut self, catalog: &mut Catalog, waiter: &kio::Waiter) -> bool { + let program = &mut self.program; + // A catalog that ended gains no rate. + if program.mux_rate_override.is_some() + || program.psi.is_some() + || !program.tracks.is_empty() + || !matches!(program.feed, Feed::Live) + { + return false; + } + // A catalog without the section came from no TS import. + let measuring = catalog + .ext + .mpegts_mut() + .is_some_and(|mpegts| mpegts.mux_rate.is_none() && !mpegts.is_empty()); + if !measuring { + program.rate_timer = None; + return false; + } + let until = *program + .rate_until + .get_or_insert_with(|| kio::clock::now().saturating_add(program.rate_wait)); + if kio::clock::now() >= until { + program.rate_timer = None; + return false; + } + let timer = program + .rate_timer + .get_or_insert_with(|| Box::pin(kio::clock::sleep_until(until))); + let _ = waiter.poll_future(timer.as_mut()); + true + } + /// The program playing failed with `err`. Only a publisher that left is survivable: its /// input stops at once, as a follow that runs out stops it, but what it already buffered /// goes out on schedule. Without a replacement, the export then reports `err`, so a @@ -3003,6 +3064,7 @@ where self.next_program += 1; next.replay = self.program.replay; next.mux_rate_override = self.program.mux_rate_override; + next.rate_wait = self.program.rate_wait; next } diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index fd35db0f592..90493d18f9b 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -31,14 +31,15 @@ pub(super) async fn open_export( Ok(Export::new(source, catalog, delay)) } -/// Open an export with the MPEG-TS catalog extension and explicit encoding. +/// Open an export with the MPEG-TS catalog extension and explicit encoding, which starts at once +/// whether or not the catalog records a rate. pub(super) async fn open_ts( source: crate::Source, format: crate::catalog::CatalogFormat, delay: Duration, ) -> crate::Result>> { let catalog = source.catalog::(format).await?; - Ok(Export::new(source, catalog, delay)) + Ok(Export::new(source, catalog, delay).without_rate_wait()) } /// A millisecond track: the frames written here carry timestamps. @@ -7969,6 +7970,120 @@ async fn export_without_a_mux_rate_is_unpadded() { assert_eq!(Clocked::of(&ts).nulls, 0, "null packets in an unpadded export"); } +/// A TS source arriving in real time, written to an import 100 ms of data a step, and an export +/// that has not been told to start at once. It joins before the import's first PCR window +/// completes: `head` bytes are all the import has read. +struct Joined { + data: &'static [u8], + read: usize, + import: crate::container::ts::Import, + export: Export>, + _broadcast: moq_net::broadcast::Consumer, + started: kio::clock::Instant, + /// What the export wrote, and when its first output came. + out: BytesMut, + first: Option, +} + +/// How much the source and the clock advance in a step. +const STEP: Duration = Duration::from_millis(100); + +impl Joined { + async fn new(data: &'static [u8], head: usize) -> Self { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = crate::catalog::Producer::new( + &mut broadcast, + crate::catalog::Config::default().with_catalog(crate::catalog::hang::Catalog::::default()), + ) + .unwrap(); + let mut import = crate::container::ts::Import::new(broadcast, catalog.reserve()); + import.decode(&data[..head]).unwrap(); + let source = crate::source::announced(&consumer).await; + let stream = source + .catalog::(crate::catalog::CatalogFormat::Hang) + .await + .unwrap(); + Self { + data, + read: head, + import, + export: Export::new(source, stream, Duration::from_millis(500)), + _broadcast: consumer, + started: kio::clock::now(), + out: BytesMut::new(), + first: None, + } + } + + /// Run for `steps`, the source writing a step's worth of its data each. + async fn run(&mut self, steps: usize) { + // The bytes a step of a five-second source carries, in whole packets. + let chunk = self.data.len() / 50 / 188 * 188; + for _ in 0..steps { + let end = (self.read + chunk).min(self.data.len()); + self.import.decode(&self.data[self.read..end]).unwrap(); + self.read = end; + let until = kio::clock::now().saturating_add(STEP); + while let Ok(frame) = kio::clock::timeout_at(until, self.export.next()).await { + let Some(frame) = frame.expect("exporter error") else { + break; + }; + self.first.get_or_insert(self.started.elapsed()); + self.out.extend_from_slice(&frame.payload); + } + } + } +} + +/// A padded export joining inside the first PCR window waits for the rate the import is still +/// measuring, then pads to it. +#[tokio::test(start_paused = true)] +async fn export_waits_for_the_rate_a_window_is_measuring() { + // The first 0.4 s of a 400 kb/s constant-rate source: its catalog is out, its rate not yet. + let mut joined = Joined::new(include_bytes!("test_data/bbb5s_cbr.ts"), 188 * 100).await; + joined.run(15).await; + assert_eq!( + joined.first, None, + "the export started before the import measured a rate" + ); + + joined.run(25).await; + joined.first.expect("the rate arrived and the export started"); + assert_packet_aligned(&joined.out); + assert!( + Clocked::of(&joined.out).nulls > 0, + "the export joined a window early without padding" + ); +} + +/// A source that records no rate costs an export one wait, and its output is unpadded. +#[tokio::test(start_paused = true)] +async fn export_stops_waiting_for_a_rate_that_never_comes() { + let mut joined = Joined::new(include_bytes!("test_data/scte35/bbb5s.ts"), 188 * 100).await; + joined.run(40).await; + let first = joined.first.expect("the export gave up on the rate"); + assert!( + first >= super::mux_rate::WAIT, + "the export started {first:?} in, before its wait ran out" + ); + assert_eq!( + Clocked::of(&joined.out).nulls, + 0, + "null packets in an export with no rate" + ); +} + +/// A rate given on the command line stands in for the one being measured. +#[tokio::test(start_paused = true)] +async fn export_with_a_rate_override_does_not_wait() { + let mut joined = Joined::new(include_bytes!("test_data/bbb5s_cbr.ts"), 188 * 100).await; + joined.export = joined.export.with_mux_rate(2_000_000); + joined.run(30).await; + let first = joined.first.expect("an export with a rate override started"); + assert!(first < STEP * 5, "the export started {first:?} in"); +} + /// 1 Mb/s is 16.62 packets per 25 ms slot. The fractional remainder carries across slots /// instead of rounding each one, and each PCR is the time of its own byte at the rate, so /// every PCR is within a system clock tick of its byte position: far inside the ±500 ns diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 62b19008ec0..0a37f113941 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -95,14 +95,11 @@ mod video; /// fails is dropped and counted in [`stats::Snapshot::crc_error`]; the last good table stays /// in force. /// -/// With the `mpegts` catalog extension, the initial catalog waits for a two-second PCR -/// measurement window. This hold applies to every subscriber of the broadcast. -/// A variable-rate window publishes without a rate, as does four seconds of media without a -/// complete PCR window; EOF releases a shorter input too. -/// Imports without that extension do not wait for a rate measurement. -/// Neither does a catalog that already records `mpegts.muxRate`, such as a restarted import's -/// carrying its predecessor's measurement of the same multiplex ([`Restart`](super::Restart)): -/// it goes out with that rate, which the measurement then refines as usual. +/// With the `mpegts` catalog extension, the catalog goes out with the first media and gains +/// `mpegts.muxRate` as an update once a two-second PCR window measures a constant rate, which +/// a variable-rate source never does. An export that pads waits for that update. A restarted +/// import's catalog carries its predecessor's measurement of the same multiplex +/// ([`Restart`](super::Restart)), which the measurement then refines as usual. /// /// The selected container applies only to decoded media renditions. Verbatim tracks in the /// `mpegts` catalog section continue to use the legacy Hang container. @@ -119,14 +116,6 @@ pub struct Import { /// final. A one-shot muxer (fMP4, TS re-export) sees the complete track list in the first /// snapshot rather than a half-converged one. See [`Reserved`](crate::catalog::Reserved). initial_reservation: Option>, - /// Hold the whole catalog until one PCR measurement window completes, or enough media time - /// passes without one, independently of decoder readiness. - mux_rate_reservation: Option>, - /// Media time seen while that hold is active, summed across time-base breaks so a source - /// that keeps resetting its clock still reaches the bound. - held: std::time::Duration, - /// The newest 90 kHz PTS of the current time base counted into `held`. - held_edge: Option, /// Whether the current PMT declares a media stream that can anchor the program clock. media_clock: bool, @@ -269,7 +258,6 @@ impl Import { catalog.count_ext_tracks(|ext: &mut E| ext.mpegts_mut().is_some_and(|mpegts| mpegts.has_track())); } let si = super::si::Capture::new(broadcast.clone(), catalog.clone()); - let mux_rate_reservation = (supports_mpegts && measured.is_none()).then(|| reserved.clone()); Self { broadcast, catalog, @@ -278,9 +266,6 @@ impl Import { has_video: false, timebase: reserved.timebase(), initial_reservation: Some(reserved), - mux_rate_reservation, - held: std::time::Duration::ZERO, - held_edge: None, demux: Demux::new(supports_mpegts), steps: Default::default(), restarts: Vec::new(), @@ -639,17 +624,8 @@ impl Import { self.place_pcr(pcr, offset)?; self.liveness.pcr(pcr); self.si.pcr(pcr, packet.count); - if self.supports_mpegts { - let ready = self.mux_rate.ready(); - if self.mux_rate.pcr(pcr, packet.count) { - self.record_mux_rate()?; - } - if self.mux_rate.ready() { - self.mux_rate_reservation = None; - } else if ready { - // A backwards clock voided the measurement. - self.rearm_mux_rate(); - } + if self.supports_mpegts && self.mux_rate.pcr(pcr, packet.count) { + self.record_mux_rate()?; } } } @@ -1329,9 +1305,6 @@ impl Import { // the program timeline, including streams discovered after a wrap. let (pts, offset) = match pes.pts { Some(raw) => { - if self.mux_rate_reservation.is_some() { - self.hold_media(raw); - } // Only a stream still behind a wrap the first PTS crossed reads as negative. let Ok(ticks) = u64::try_from(self.pts.unwrap(raw)) else { *self.unplaced.entry(pid.as_u16()).or_default() += 1; @@ -1533,9 +1506,6 @@ impl Import { let ticks = u64::try_from(self.pts.pcr(raw))?; self.timebase.anchor(Timestamp::from_scale(ticks, PCR_HZ)?)?; self.initial_reservation = None; - if self.mux_rate_reservation.is_some() { - self.hold_media(raw / 300); - } } let sample = self.placement.pcr(raw, offset + PCR_OFFSET); let generation = self.placement.generation; @@ -1685,12 +1655,6 @@ impl Import { /// PCR/PTS rollover sets nothing and only moves the next PTS into the next era; neither is /// a program break and neither reaches here. fn timebase_break(&mut self) -> anyhow::Result<()> { - // A leading flag starts this instance's clock; it cannot invalidate a window not begun. - // Otherwise hold before salvage, which may resolve the final stream config. - let clocked = self.mux_rate.started(); - if clocked { - self.rearm_mux_rate(); - } // The bytes still accumulating belong to the old clock, and their continuation is // stamped on the new one, so cut every PES here rather than splicing across. This // runs before the marker so a salvaged tail lands in the closing group, which the @@ -1720,57 +1684,26 @@ impl Import { section.discontinuity(self.published)?; } self.last_pts = None; - self.held_edge = None; self.published = false; self.liveness.discontinuity(); self.si.discontinuity(); - if clocked && self.mux_rate.discontinuity() { - self.record_mux_rate()?; - } + self.reset_mux_rate()?; tracing::debug!("MPEG-TS system time-base discontinuity"); Ok(()) } - /// The program clock changed, so the measured rate no longer holds. + /// The program clock changed, so the measured rate no longer holds. A leading flag starts this + /// instance's clock and cannot invalidate a window not begun. fn reset_mux_rate(&mut self) -> anyhow::Result<()> { if !self.mux_rate.started() { return Ok(()); } - self.rearm_mux_rate(); if self.mux_rate.discontinuity() { self.record_mux_rate()?; } Ok(()) } - /// A clock change voids the startup measurement, so until the first catalog publishes - /// (while the initial reservation still holds it), hold it again for a window on the new - /// clock. - fn rearm_mux_rate(&mut self) { - if self.supports_mpegts && self.mux_rate_reservation.is_none() { - self.mux_rate_reservation = self.initial_reservation.clone(); - } - } - - /// Count `pts` toward the startup hold. A source without a usable PCR never completes a - /// measurement window, so enough media time releases its catalog without a rate. - fn hold_media(&mut self, pts: u64) { - const WRAP: u64 = 1 << 33; - if let Some(edge) = self.held_edge { - // Modulo the 33-bit wrap, so the hold counts across a rollover. A step past half the - // range is a frame behind the edge (reordered, or another stream), not a jump forward. - let step = pts.wrapping_sub(edge) % WRAP; - if step >= WRAP / 2 { - return; - } - self.held += std::time::Duration::from_nanos(step * 1_000_000_000 / 90_000); - } - self.held_edge = Some(pts); - if self.held >= super::mux_rate::UNMEASURED { - self.mux_rate_reservation = None; - } - } - /// Copy the measured multiplex rate into the `mpegts` section, publishing the /// catalog. Called only when the measurement changed, so a steady source republishes /// only when a window sets a new high, ever more rarely. @@ -1960,8 +1893,7 @@ impl Import { self.streams.values().all(Stream::placed), "TS private PES reached end of input without a media timestamp" ); - // EOF releases an unmeasured short source as well as its decoder reservations. - self.mux_rate_reservation = None; + // EOF releases the decoder reservations of a short source. self.initial_reservation = None; for pid in self.streams.keys().copied().collect::>() { let units = self.finish_stream(pid)?; @@ -2073,7 +2005,6 @@ impl Import { super::si::Capture::new(self.broadcast.clone(), self.catalog.clone()), ); si.abort(err); - self.mux_rate_reservation = None; self.initial_reservation = None; } } @@ -8128,9 +8059,9 @@ pub(super) mod test { assert_eq!(run(&[p1, p2, p3, p4]), vec![CUE.to_vec()]); } - /// A private-data-only program retains the PES clock while waiting for rate measurement or EOF. + /// A private-data-only program publishes its PES clock with its first media, with no PCR to wait for. #[tokio::test] - async fn private_pes_only_program_retains_its_pes_clock_until_catalog_release() { + async fn private_pes_only_program_publishes_its_pes_clock_with_the_first_media() { use crate::catalog::hang::Catalog; use crate::container::ts::catalog::Ext; @@ -8158,11 +8089,10 @@ pub(super) mod test { .unwrap(); let anchored = catalog.snapshot().media.clock.expect("a clock"); assert_ne!(anchored, provisional, "the first PES anchors the clock"); - assert!(clocks.drain().is_empty(), "rate measurement still holds the catalog"); - let _finished = import.finish().unwrap(); let published = clocks.drain(); - assert!(!published.is_empty(), "EOF releases a program without PCR samples"); + assert!(!published.is_empty(), "the first PES releases the catalog"); assert!(published.iter().all(|clock| *clock == Some(anchored)), "{published:?}"); + let _finished = import.finish().unwrap(); } /// A TS packet on `pid` carrying only an adaptation field (no payload) that sets @@ -10684,8 +10614,10 @@ pub(super) mod test { p } + /// The catalog goes out with the first media, and a constant-rate source gains its `muxRate` as + /// an update once a window measures it; a variable-rate one never does. #[test] - fn first_ts_catalog_waits_for_the_mux_rate_window() { + fn first_ts_catalog_gains_the_mux_rate_as_an_update() { use crate::catalog::hang::Catalog; use crate::container::ts::catalog::Ext; @@ -10703,10 +10635,10 @@ pub(super) mod test { .unwrap(); import.decode(&pes_packet(PCR_PID, 90_000)).unwrap(); let waiter = kio::Waiter::noop(); - assert!( - updates.poll_next(&waiter).is_pending(), - "catalog preceded rate measurement" - ); + let std::task::Poll::Ready(Ok(Some(first))) = updates.poll_next(&waiter) else { + panic!("the catalog waited for a rate measurement"); + }; + assert_eq!(first.ext.mpegts.mux_rate, None); for i in 0..=50 { let mut bytes = pcr_packet(PCR_PID, i * 27_000_000 / 25); @@ -10715,17 +10647,16 @@ pub(super) mod test { bytes.extend_from_slice(&super::super::export::NULL_PACKET); } import.decode(&bytes).unwrap(); - if i < 50 { - assert!( - updates.poll_next(&waiter).is_pending(), - "catalog before a full PCR window" - ); - } } - let std::task::Poll::Ready(Ok(Some(first))) = updates.poll_next(&waiter) else { - panic!("catalog did not release at the end of the first window"); - }; - assert_eq!(first.ext.mpegts.mux_rate, cbr.then_some(3_760_000)); + let mut latest = None; + while let std::task::Poll::Ready(Ok(Some(update))) = updates.poll_next(&waiter) { + latest = Some(update); + } + assert_eq!( + latest.map(|update| update.ext.mpegts.mux_rate), + cbr.then_some(Some(3_760_000)), + "a window's rate arrives as an update, a variable one publishes nothing" + ); } } @@ -10768,172 +10699,6 @@ pub(super) mod test { ); } - /// A live source with no PCR never completes a window, so media time releases its catalog. - #[test] - fn a_ts_without_pcr_releases_its_catalog_after_four_seconds_of_media() { - use crate::catalog::hang::Catalog; - use crate::container::ts::catalog::Ext; - let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new( - &mut broadcast, - crate::catalog::Config::default().with_catalog(Catalog::::default()), - ) - .unwrap(); - let mut updates = catalog.consume().unwrap(); - let mut import = super::Import::new(broadcast, catalog.reserve()); - import - .decode(&synth_pmt(&[(StreamType::Mpeg2PacketizedData, PCR_PID)], false)) - .unwrap(); - let waiter = kio::Waiter::noop(); - for frame in 0..100 { - import.decode(&pes_packet(PCR_PID, 90_000 + frame * 3_600)).unwrap(); - assert!(updates.poll_next(&waiter).is_pending(), "catalog after frame {frame}"); - } - import.decode(&pes_packet(PCR_PID, 90_000 + 100 * 3_600)).unwrap(); - let std::task::Poll::Ready(Ok(Some(first))) = updates.poll_next(&waiter) else { - panic!("four seconds of media did not release the catalog"); - }; - assert_eq!(first.ext.mpegts.mux_rate, None); - } - - /// A source whose clock keeps resetting before a window completes still releases its - /// catalog once enough media time has passed in total. - #[test] - fn a_ts_resetting_its_clock_does_not_release_without_a_configured_track() { - use crate::catalog::hang::Catalog; - use crate::container::ts::catalog::Ext; - let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new( - &mut broadcast, - crate::catalog::Config::default().with_catalog(Catalog::::default()), - ) - .unwrap(); - let mut updates = catalog.consume().unwrap(); - let mut import = super::Import::new(broadcast, catalog.reserve()); - import - .decode(&synth_pmt(&[(StreamType::H264, PCR_PID)], false)) - .unwrap(); - let waiter = kio::Waiter::noop(); - // Each epoch carries 0.96 s of media, then a flagged PCR restarts the clock, which the - // media leaps forward from: a rewind would end the instance. - for epoch in 0..6 { - for frame in 0..25 { - import - .decode(&pes_packet(PCR_PID, 90_000 + epoch * 60 * 90_000 + frame * 3_600)) - .unwrap(); - } - import.decode(&flag_discontinuity(pcr_packet(PCR_PID, 0))).unwrap(); - assert!( - updates.poll_next(&waiter).is_pending(), - "metadata-only catalog released after epoch {epoch}" - ); - } - } - - /// A clock break after a measured window but before the first catalog publishes voids the - /// measurement, so the catalog waits for a window on the new clock and carries its rate. - #[test] - fn a_break_before_the_first_catalog_waits_for_a_new_window() { - use crate::catalog::hang::Catalog; - use crate::container::ts::catalog::Ext; - let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new( - &mut broadcast, - crate::catalog::Config::default().with_catalog(Catalog::::default()), - ) - .unwrap(); - let mut updates = catalog.consume().unwrap(); - let mut import = super::Import::new(broadcast, catalog.reserve()); - import - .decode(&synth_pmt(&[(StreamType::Mpeg1Audio, PCR_PID)], false)) - .unwrap(); - let window = |import: &mut super::Import, stuffing: usize| { - for i in 0..=50 { - let mut bytes = pcr_packet(PCR_PID, i * 27_000_000 / 25); - for _ in 0..stuffing { - bytes.extend_from_slice(&super::super::export::NULL_PACKET); - } - import.decode(&bytes).unwrap(); - } - }; - let waiter = kio::Waiter::noop(); - - // A full window before any PES, then a break, then the first PES. - window(&mut import, 99); - import.decode(&flag_discontinuity(pcr_packet(PCR_PID, 0))).unwrap(); - import.decode(&mp2_pes(PCR_PID, 0, 90_000, [0xaa, 0xbb])).unwrap(); - assert!( - updates.poll_next(&waiter).is_pending(), - "the catalog published on a voided measurement" - ); - - window(&mut import, 49); - let std::task::Poll::Ready(Ok(Some(first))) = updates.poll_next(&waiter) else { - panic!("the new clock's window did not release the catalog"); - }; - assert_eq!(first.ext.mpegts.mux_rate, Some(1_880_000)); - } - - /// The hold counts media time across a 33-bit PTS rollover. - #[test] - fn a_ts_without_pcr_releases_its_catalog_across_a_pts_rollover() { - use crate::catalog::hang::Catalog; - use crate::container::ts::catalog::Ext; - let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new( - &mut broadcast, - crate::catalog::Config::default().with_catalog(Catalog::::default()), - ) - .unwrap(); - let mut updates = catalog.consume().unwrap(); - let mut import = super::Import::new(broadcast, catalog.reserve()); - import - .decode(&synth_pmt(&[(StreamType::Mpeg2PacketizedData, PCR_PID)], false)) - .unwrap(); - let waiter = kio::Waiter::noop(); - // Starts two seconds before the rollover. - let start = (1 << 33) - 180_000; - for frame in 0..100 { - import - .decode(&pes_packet(PCR_PID, (start + frame * 3_600) % (1 << 33))) - .unwrap(); - assert!(updates.poll_next(&waiter).is_pending(), "catalog after frame {frame}"); - } - import - .decode(&pes_packet(PCR_PID, (start + 100 * 3_600) % (1 << 33))) - .unwrap(); - assert!( - updates.poll_next(&waiter).is_ready(), - "four seconds across the rollover did not release the catalog" - ); - } - - #[test] - fn finishing_a_short_ts_releases_its_catalog_without_a_rate() { - use crate::catalog::hang::Catalog; - use crate::container::ts::catalog::Ext; - let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new( - &mut broadcast, - crate::catalog::Config::default().with_catalog(Catalog::::default()), - ) - .unwrap(); - let mut updates = catalog.consume().unwrap(); - let mut import = super::Import::new(broadcast, catalog.reserve()); - import - .decode(&synth_pmt(&[(StreamType::Mpeg2PacketizedData, PCR_PID)], false)) - .unwrap(); - import.decode(&pes_packet(PCR_PID, 90_000)).unwrap(); - import.decode(&pcr_packet(PCR_PID, 0)).unwrap(); - let waiter = kio::Waiter::noop(); - assert!(updates.poll_next(&waiter).is_pending()); - let _finished = import.finish().unwrap(); - let std::task::Poll::Ready(Ok(Some(first))) = updates.poll_next(&waiter) else { - panic!("short recording finished without a catalog"); - }; - assert_eq!(first.ext.mpegts.mux_rate, None); - } - /// The catalog follows the clock: a stable multiplex rate is recorded, a source that /// stops holding it clears the record, a fresh stable window records it again, and a /// declared time-base break clears it at once. diff --git a/rs/moq-mux/src/container/ts/mux_rate.rs b/rs/moq-mux/src/container/ts/mux_rate.rs index f28af7378aa..c7a98c7aa92 100644 --- a/rs/moq-mux/src/container/ts/mux_rate.rs +++ b/rs/moq-mux/src/container/ts/mux_rate.rs @@ -16,9 +16,10 @@ pub(super) const PACKET_BITS: u64 = 188 * 8; pub(super) const PCR_WRAP: u64 = (1 << 33) * 300; /// How much PCR time one window spans before it is judged. const WINDOW: u64 = 2 * PCR_HZ; -/// Media time after which a source that has not completed a window publishes without a rate: -/// twice the window, so a usable PCR clock always completes one first. -pub(super) const UNMEASURED: std::time::Duration = std::time::Duration::from_secs(2 * WINDOW / PCR_HZ); +/// How long a consumer that needs the rate waits for one to be recorded: the window that measures +/// it. A source that has not recorded one by then has none, or the consumer takes it up when it +/// does. +pub(super) const WAIT: std::time::Duration = std::time::Duration::from_nanos(WINDOW * 1_000_000_000 / PCR_HZ); /// Intervals are pooled into samples this long before they are compared. One /// packet of rounding, or a clock a hardware muxer stamps at half-millisecond /// granularity, is a few percent of one 25 ms interval but well inside the @@ -76,8 +77,6 @@ pub(super) struct Meter { window: Vec, /// The rate recorded in the catalog, if any. published: Option, - /// Whether a window has completed since the last discontinuity, even for VBR. - ready: bool, } impl Meter { @@ -100,11 +99,6 @@ impl Meter { self.last.is_some() } - /// Whether a PCR measurement window has completed on the current clock. - pub fn ready(&self) -> bool { - self.ready - } - /// A PCR arrived on the clock PID, carried by packet number `packets` of the input, /// counting every PID and null stuffing. Returns whether [`published`](Self::published) /// changed. @@ -135,7 +129,6 @@ impl Meter { /// itself changed. The window is worthless and so is a rate measured before it. /// Returns whether [`published`](Self::published) changed. pub fn discontinuity(&mut self) -> bool { - self.ready = false; self.last = None; self.sample = Interval::default(); self.window.clear(); @@ -144,7 +137,6 @@ impl Meter { /// Judge the full window and discard it. fn judge(&mut self) -> bool { - self.ready = true; let window = std::mem::take(&mut self.window); let mut whole = Interval::default(); window.iter().for_each(|s| whole.add(*s)); diff --git a/rs/moq-srt/src/ts.rs b/rs/moq-srt/src/ts.rs index 2bd24354791..754b41dda66 100644 --- a/rs/moq-srt/src/ts.rs +++ b/rs/moq-srt/src/ts.rs @@ -640,7 +640,7 @@ mod tests { } /// A two-program multiplex, each program carrying one private PES stream (carried - /// verbatim) and its first PES plus a complete PCR measurement window: + /// verbatim) and its first PES plus a PCR window on each program's clock: /// program 1's on PID 0x101, program 2's on 0x201. fn two_programs() -> Bytes { let mut ts = psi_packet(0x0000, &pat(&[(1, 0x0100), (2, 0x0200)])); @@ -648,7 +648,7 @@ mod tests { ts.extend_from_slice(&psi_packet(0x0200, &pmt(2, 0x06, 0x0201))); ts.extend_from_slice(&pes_packet(0x0101, 90_000)); ts.extend_from_slice(&pes_packet(0x0201, 90_000)); - // Complete the startup rate window before expecting a live catalog. + // A clock for each program. for index in 0..=8u64 { let base = index * 22_500; for pid in [0x0101u16, 0x0201] { @@ -928,10 +928,11 @@ mod tests { let expected_cue = cue.payload; assert_eq!(expected_cue[0], 0xFC, "a verbatim splice_info_section (table_id 0xFC)"); - // The egress joins the clip's last group, read at once and two seconds long. Under the - // default delay its keyframe is stale, and the egress waits on the next one. + // The egress joins the clip's last group, read at once and two seconds long, once it has + // waited a mux-rate window on a catalog that records no rate. Under a shorter delay the + // keyframe is stale by then, and the egress waits on the next one. let options = Options { - latency: Duration::from_secs(3), + latency: Duration::from_secs(5), ..Default::default() }; let mut subscriber = Subscriber::new(&origin.consume(), "ingest", options) @@ -940,7 +941,7 @@ mod tests { .expect("the ingest broadcast is available for SRT egress"); let mut output = Vec::new(); loop { - match timeout(Duration::from_secs(5), subscriber.next()).await { + match timeout(Duration::from_secs(10), subscriber.next()).await { Ok(Ok(Some(frame))) => output.extend_from_slice(&frame.payload), Ok(Ok(None)) => break, Ok(Err(err)) => panic!("SRT egress failed: {err}"), From c40404bcd6a507d7591c0fe5342c789035077a15 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 13:35:15 -0800 Subject: [PATCH 3/3] docs(moq-mux): the switch-before-first-catalog test no longer cites the mux-rate hold Co-Authored-By: Claude Sonnet 5.5 --- rs/moq-mux/src/container/ts/republish.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rs/moq-mux/src/container/ts/republish.rs b/rs/moq-mux/src/container/ts/republish.rs index 49b1a093b1d..9bbdb13d73a 100644 --- a/rs/moq-mux/src/container/ts/republish.rs +++ b/rs/moq-mux/src/container/ts/republish.rs @@ -375,11 +375,11 @@ mod tests { } } - /// A source that steps within the mux rate's measurement window, before its first catalog went + /// A source that steps in the same chunk as its first media, before its first catalog went /// out, republishes rather than failing: only the last instance has to declare a track. #[test] fn a_switch_before_the_first_catalog_republishes() { - // 1.5 s: short of the two-second window that holds the first catalog. + // 1.5 s of input, then the step, all in one chunk. let mut data = CLIP[..400 * 188].to_vec(); data.extend(shift(CLIP, |_| -SWITCH)); let origin = crate::source::produce_origin();