From 2a5739682561fb48c659e0a3243f4e174ab53640 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 20:00:48 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m2/ts-passthrough-splice.md Quest-Claim: 53543784383be7b2 From db0b251d4b50e76e956bd527352ed593bf0a61c3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 21:09:12 -0800 Subject: [PATCH 2/3] feat(mux)!: a passthrough TS import splices a clock step instead of ending A PCR step back, flagged or not, or an unflagged step forward of more than 10 s, now continues the count from where the rate before it puts the PCR and starts the next group behind a break marker. The bytes stay verbatim. moq_mux::Error::PcrRewind and PcrRestart are removed. A group behind a break now starts past the marker, which could take the microsecond after the newest group's start and refuse it as a rewind. Co-Authored-By: Claude Opus 5.5 --- doc/bin/ts.md | 11 +- drafts/draft-lcurley-moq-mpegts.md | 11 +- quest/m1/ts-step-damage.md | 2 +- quest/m2/ts-passthrough-splice.md | 71 ----------- rs/moq-mux/src/container/ts/passthrough.rs | 59 +++++---- .../src/container/ts/passthrough_test.rs | 120 ++++++++++++++---- rs/moq-mux/src/container/ts/release.rs | 6 +- rs/moq-mux/src/container/ts/release_test.rs | 117 ++++++++++------- rs/moq-mux/src/container/ts/step.rs | 2 +- rs/moq-mux/src/error.rs | 28 ---- 10 files changed, 217 insertions(+), 210 deletions(-) delete mode 100644 quest/m2/ts-passthrough-splice.md diff --git a/doc/bin/ts.md b/doc/bin/ts.md index e0c8bf27b6b..7e9bb4c6053 100644 --- a/doc/bin/ts.md +++ b/doc/bin/ts.md @@ -137,9 +137,12 @@ are refused rather than reframed. `--pcr-pid` paces on another PID's PCR. Each frame is a run of packets that ends at the next PCR on the clock PID or at the next group start, stamped with the PCR time of its first byte. A group starts at a `random_access_indicator` on the video PID (or the clock PID with -no video), at a flagged PCR jump forward, after a second without either, or -where the next frame would take the group past the relay's cache bound. Any -step back ends the import. +no video), at a PCR clock break, after a second without either, or where the +next frame would take the group past the relay's cache bound. A flagged PCR +jump forward carries its step into the timestamps. A step back, flagged or +not, or an unflagged one more than 10 s forward, such as a switch between two +unlocked encoders, is spliced instead: the timestamps carry on from where the +clock was, and the bytes still go out unchanged, step and all. `export ts --passthrough` writes each run `--delay` after its time on the source clock, so two exporters emit the same bytes. It takes neither @@ -243,7 +246,7 @@ details each grader and its negative controls. | Byte identity from the first group; nothing before PMT and PCR; off-grid junk dropped | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) `a_broadcast_capture_is_byte_identical_from_the_first_group`, `nothing_is_published_before_the_pmt_and_a_pcr`, `leading_junk_does_not_hide_the_grid` | PR | | Scrambled input groups and paces like its clear twin | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) `a_scrambled_twin_groups_and_paces_the_same` | PR | | `randomAccess` false for several programs or video streams | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) `two_programs_on_one_clock_publish_no_random_access`, `two_video_streams_in_one_program_publish_no_random_access` | PR | -| Clock: wrap, flagged jump, step back refused, 192/204-byte packets refused | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) | PR | +| Clock: wrap, flagged jump, steps spliced, 192/204-byte packets refused | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) | PR | | Export releases each run byte-identical on its own PCR, whatever the delivery skew | [`release_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/release_test.rs) `a_capture_is_released_byte_identical_on_its_own_pcr`, `releases_fed_with_different_skew_write_the_same_bytes` | PR | ### Acquisition and loss diff --git a/drafts/draft-lcurley-moq-mpegts.md b/drafts/draft-lcurley-moq-mpegts.md index e5a1c299197..3f399bf1935 100644 --- a/drafts/draft-lcurley-moq-mpegts.md +++ b/drafts/draft-lcurley-moq-mpegts.md @@ -311,7 +311,7 @@ From the first group on, the frames of consecutive groups concatenate to the inp A group starts at: - a packet with `random_access_indicator` set on the video PID of the clock's program (the first PID its PMT declares with a video `stream_type`), or on the clock PID when that program has no video; -- a PCR on the clock PID with `discontinuity_indicator` set that steps forward ({{m2ts-timestamps}}), since a group MUST NOT contain a PCR discontinuity; +- a PCR on the clock PID that breaks the count ({{m2ts-timestamps}}), since a group MUST NOT contain a PCR discontinuity; - otherwise, the first PCR at least one second of PCR time after the group's start; - the frame that would take a group past a size bound the publisher chooses below what a relay caches of one group; frames are never split to meet it. @@ -328,9 +328,10 @@ A PCR gives the time of the byte holding the last bit of its `program_clock_refe A byte between two PCRs is placed at the rate between them; a byte past the last PCR of a timebase takes the rate of the interval before it, and one before the first PCR of a timebase takes the rate of the interval after it. PCRs are unwrapped into a 64-bit count of 27 MHz ticks, and timestamps never decrease. -A step forward of at most half the 2^33 × 300 tick period adds to the count, across the wrap included, so a wrap is not a discontinuity. -A PCR with `discontinuity_indicator` set whose step is forward by that measure adds its step too, after the bytes before it are timed at the rate before it, and the group it starts MUST follow hang's discontinuity marker ({{hang}}). -A PCR that steps backwards MUST end the track with an error, flagged or not: a flagged one is a restart, which is new content, so a publisher that carries on publishes it as a new broadcast. +A step forward of at most half the 2^33 × 300 tick period adds to the count, across the wrap included, so a wrap is not a discontinuity, unless it exceeds 10 seconds without `discontinuity_indicator`. +A PCR with `discontinuity_indicator` set whose step is forward by that measure breaks the count and adds its step. +Any other step, backwards with or without the flag or that unflagged leap forward, breaks the count and is spliced: the count continues from the time the rate before the PCR gives its byte, raised to at least the last frame's. +At a break, the bytes before the PCR are timed at the rate before it, and the group it starts MUST follow hang's discontinuity marker ({{hang}}). The timeline depends only on the bytes since the publisher's first PCR, so two publishers that start at the same packet of one input publish identical frames. @@ -460,7 +461,7 @@ A broadcast demultiplexed from a DVB transport stream: video and audio described - MPEG-1/2 video and LATM AAC are named among `pesPacket` streams, and the DSM-CC types 0x0A to 0x0D among section-framed `verbatim` ones. A rebuilt PAT lists the network entry when the NIT is carried. - MPEG-1/2 video `pesPacket` frames group from one sequence header to the next, rather than one PES per group. - A flagged PCR jump on an `m2ts` track follows hang's discontinuity marker rather than a skipped group sequence. -- An `m2ts` track unwraps PCRs from its history, clamps extrapolated object times at a forward discontinuity, and cuts a fallback group after one second. `randomAccess` covers every published group; `muxRate` follows the measured source rate. +- An `m2ts` track unwraps PCRs from its history, clamps extrapolated object times at a forward discontinuity, splices a PCR step back or an unflagged one over 10 seconds forward rather than ending, and cuts a fallback group after one second. `randomAccess` covers every published group; `muxRate` follows the measured source rate. - A `tracks` entry is never changed in place: a stream the PMT revises continues under a new name, and one it drops leaves the section. `programDescriptors` follows the PMT; `program`'s `transportStreamId` and `programNumber` do not change. - A consumer rebuilding a stream follows the catalog's revisions at the next PMT `version_number`, and carries a stream only while a PMT lists it. - `pmtPid` follows a PAT that moves the PMT, and a consumer rebuilding a stream moves the PMT behind a PAT at the next `version_number`. diff --git a/quest/m1/ts-step-damage.md b/quest/m1/ts-step-damage.md index 447e3fae6fa..30694b4b047 100644 --- a/quest/m1/ts-step-damage.md +++ b/quest/m1/ts-step-damage.md @@ -48,4 +48,4 @@ Caused by, for the fix PR's `## Caused by`: ## Related -- [moq-dev/moq#9035](https://github.com/moq-dev/moq/pull/9035) - plans `quest/m2/ts-passthrough-splice.md`, which handles a whole-source PCR step on the passthrough lane; this quest is the lone-stream step on the import +- [moq-dev/moq#9069](https://github.com/moq-dev/moq/pull/9069) - splices a whole-source PCR step on the passthrough lane; this quest is the lone-stream step on the import diff --git a/quest/m2/ts-passthrough-splice.md b/quest/m2/ts-passthrough-splice.md deleted file mode 100644 index 456e6b9bcd3..00000000000 --- a/quest/m2/ts-passthrough-splice.md +++ /dev/null @@ -1,71 +0,0 @@ -# [S] A passthrough TS import splices a clock step instead of ending - -## Goal - -`moq import ts --passthrough` keeps its broadcast across every PCR step that -is not elapsed time: an unflagged step back, a flagged step back, and an -unflagged step forward of more than 10 s. Its `moq export ts --passthrough` -subscribers keep playing, and the bytes they get stay identical to the -input. `PcrRewind` and `PcrRestart` are gone. - -## Plan - -Decided 2026-11-17 (maintainer, `/quest-import` of -[moq-dev/moq#8911](https://github.com/moq-dev/moq/issues/8911)): - -- ✅ Splice in place (rejected: won't fix, leaving the source to flag - the switch or lock its encoders; republish under a new instance on the - import and teach the passthrough release to follow it; republish on the - import only). The passthrough promises byte-identical carriage, as an - SRT hop does, and decoders ride through the step. It reads no PES, its - catalog describes no codecs, and its one reader (`ts::Release`) already - re-anchors its jitter buffer on a step. The reasons the media-aware import - republishes ([moq-dev/moq#7144](https://github.com/moq-dev/moq/pull/7144): - it rewrites PES timestamps and describes codecs) do not apply. Republishing - would also drop the input until the new source's PAT, PMT, and keyframe, - and a stitched passthrough output would carry the same unflagged step. -- ✅ Splice every step that is not elapsed time, forward included - (rejected: back only). Today an unflagged forward step under half the - wrap is added to the timeline with no marker - (`rs/moq-mux/src/container/ts/passthrough.rs`, `ticks = last + step`), so - switching back between the reported encoders would push the timeline - 4.7 h past the wall clock. Use the media-aware judge's 10 s bound - (`LEAP`, `rs/moq-mux/src/container/ts/step.rs`). -- ✅ m2 (rejected: m1). The fix deletes two public error variants, and - nothing here is on `release` to backport. - -The splice rule: at such a PCR, time the bytes before it at the rate before -it, continue the count from there (raised to at least the last written -time), and start the next group behind hang's discontinuity marker, as the -flagged forward jump already does. It depends only on the bytes, so two -publishers starting at the same packet still publish identical frames. -Amend `drafts/draft-lcurley-moq-mpegts.md`'s Timestamps section ("a PCR -that steps backwards MUST end the track") and `doc/bin/ts.md`. The -passthrough's module comment ("a signalled restart is new content and -needs a new broadcast") goes with it. - -The reported step is real: it is the feed from -[moq-dev/moq#7102](https://github.com/moq-dev/moq/issues/7102), two -encoders 16,844.5 s apart behind a switch that sets no -`discontinuity_indicator`. The logged PCRs (1,642 s → 80,241 s) are that -step back across the 33-bit wrap, not an overflow. - -A single corrupt PCR now costs two splices instead of the broadcast. - -Tests: an unflagged step back, a flagged step back, and an unflagged step -forward past 10 s, each at a GOP boundary and mid-GOP: the import keeps -running, timestamps keep rising, the output bytes equal the input, and the -release plays through without holding. The reporter offered to run the -branch on the same feed. - -Public API: breaking, `moq_mux::Error::PcrRewind` and `PcrRestart` are -removed. Wire: the MPEG-TS draft's passthrough timestamp rule changes; the -existing reader handles the result. - -## Closes - -- [#8911](https://github.com/moq-dev/moq/issues/8911) - `import ts --passthrough` ends at an unflagged clock step back - -## Related - -- [A transport stream carried whole is listed under the mpegts section](/quest/m2/hang04/m2ts.md) - also edits the passthrough import and release diff --git a/rs/moq-mux/src/container/ts/passthrough.rs b/rs/moq-mux/src/container/ts/passthrough.rs index 9f4b182bfbc..8c93300195e 100644 --- a/rs/moq-mux/src/container/ts/passthrough.rs +++ b/rs/moq-mux/src/container/ts/passthrough.rs @@ -16,6 +16,13 @@ pub(super) const PCR_HZ: u64 = 27_000_000; /// PCR ticks: one second. const FALLBACK_TICKS: u64 = PCR_HZ; +/// PCR ticks in a microsecond, the unit of an object's timestamp. +const TICKS_PER_MICRO: u64 = PCR_HZ / 1_000_000; + +/// The longest unflagged step forward taken as elapsed time, in PCR ticks: the media-aware +/// import's [`LEAP`](super::step::LEAP). +const LEAP_TICKS: u64 = super::step::LEAP.as_secs() * PCR_HZ; + /// The most bytes a group holds before its next object starts another, so a source with sparse /// random access points still gives a joiner a group it can take whole. pub(super) const GROUP_BYTES_MAX: u64 = 16 * 1024 * 1024; @@ -68,8 +75,8 @@ const VIDEO_STREAM_TYPES: &[u8] = &[ /// /// - a packet with `random_access_indicator` on the video PID, or on the clock PID when the /// program has no video; -/// - a PCR with `discontinuity_indicator` that jumps forward, since no group may hold a PCR -/// discontinuity; +/// - a PCR that breaks the count (see Timestamps): one with `discontinuity_indicator`, or a +/// step not taken as elapsed time, since no group may hold a PCR discontinuity; /// - the first PCR at least one second after the group's start, for a source that never marks /// random access; /// - the first object that would take the group past half of what `moq-net` caches of one group, @@ -98,12 +105,14 @@ const VIDEO_STREAM_TYPES: &[u8] = &[ /// that object places the clock, and otherwise whatever lands it at now on a clock already in use. /// /// PCRs are unwrapped into a 64-bit count of 27 MHz ticks that never goes back. A step forward of -/// at most half the 2^33 * 300 tick period adds to the count, across the wrap included. A PCR with -/// `discontinuity_indicator` whose step is forward by that measure adds the step too, after the -/// bytes before it are timed at the rate before it, and starts a group behind a break marker. Any -/// step back ends the import: [`PcrRewind`](crate::Error::PcrRewind) without the flag, -/// [`PcrRestart`](crate::Error::PcrRestart) with it, since a signalled restart is new content and -/// needs a new broadcast. The timeline therefore depends only on the bytes since the importer's +/// at most half the 2^33 * 300 tick period adds to the count, across the wrap included, unless it +/// is more than 10 s without `discontinuity_indicator`. A PCR with the flag whose step is forward +/// adds the step too. Every other step, back with or without the flag or that unflagged leap, is +/// another timeline, such as a switch between two encoders whose clocks were never locked, and is +/// spliced: the count carries on from the time the rate before the PCR gives it. Either way the +/// bytes before it are timed at the rate before it, and the next group starts behind a break +/// marker. The bytes still go out verbatim, so a decoder downstream sees the step as the source +/// sent it. The timeline therefore depends only on the bytes since the importer's /// first PCR and its shift, and two importers of one feed started at the same packet each placing /// its own catalog's clock publish identical objects. pub struct Passthrough { @@ -228,7 +237,7 @@ enum Groups { Writing(Group), } -/// The PCRs since the importer's first, or since the last flagged jump. +/// The PCRs since the importer's first, or since the last break. struct Timebase { /// The last PCR, raw. raw: u64, @@ -460,7 +469,7 @@ impl Passthrough { } if let Some(raw) = pcr(pkt) { clock = true; - start = self.clock(pid, raw, at)?; + start = self.clock(raw, at)?; discontinuity = start == Some(Start::Discontinuity); } } @@ -502,7 +511,7 @@ impl Passthrough { /// A PCR at `at` on the clock PID: close the object it ends, time everything waiting on it, /// and say whether its packet starts a group. - fn clock(&mut self, pid: u16, raw: u64, at: u64) -> crate::Result> { + fn clock(&mut self, raw: u64, at: u64) -> crate::Result> { let at = at + PCR_OFFSET; self.close_object(); let flagged = std::mem::take(&mut self.pending_break); @@ -529,20 +538,16 @@ impl Passthrough { // A retransmitted break (the same flagged PCR again) declares nothing new. let flagged = flagged && !(timebase.samples.len() == 1 && timebase.raw == raw); let step = (raw + PCR_WRAP - timebase.raw) % PCR_WRAP; - if step > PCR_WRAP / 2 { - let from = timebase.raw; - return Err(match flagged { - true => crate::Error::PcrRestart { pid, from, to: raw }, - false => crate::Error::PcrRewind { pid, from, to: raw }, - }); - } let last = timebase.samples.back().expect("a timebase has a sample").ticks; + // A step back, or one forward too far to be elapsed time, is another timeline: the + // count carries on from where the rate before it puts this PCR, ignoring the step. + let spliced = (step > PCR_WRAP / 2 || (!flagged && step > LEAP_TICKS)).then(|| locate(at, &timebase.samples)); - if flagged { + if flagged || spliced.is_some() { // No PCR on the old side is coming: what waits on one is timed by the rate before it, // and the new side carries on from there. self.drain_queue()?; - let ticks = (last + step).max(self.written); + let ticks = spliced.unwrap_or(last + step).max(self.written); // The object before was closed and the queue drained, so both start empty. self.timing = Clock::Seen { timebase: Timebase { @@ -621,10 +626,18 @@ impl Passthrough { } fn write(&mut self, object: Object, ticks: u64) -> crate::Result<()> { - // Extrapolating past the last PCR before a small flagged jump can overshoot the jump. - let ticks = ticks.max(self.written); + // Extrapolating past the last PCR before a break can overshoot where the count resumes. + let mut ticks = ticks.max(self.written); + if object.discontinuity + && let Groups::Writing(group) = &self.groups + { + // The break's marker may take the microsecond past the newest group's start, as when a + // second break follows a one-PCR timebase that gave no rate, and the group behind it + // has to start past the marker. + ticks = ticks.max((group.ticks / TICKS_PER_MICRO + 2) * TICKS_PER_MICRO); + } self.written = ticks; - let timestamp = moq_net::Timestamp::from_micros(ticks / (PCR_HZ / 1_000_000))?; + let timestamp = moq_net::Timestamp::from_micros(ticks / TICKS_PER_MICRO)?; // The first object, which starts a group, anchors the shift and is live on arrival. let timestamp = self.shift.shift(timestamp)?; let size = object.payload.len() as u64; diff --git a/rs/moq-mux/src/container/ts/passthrough_test.rs b/rs/moq-mux/src/container/ts/passthrough_test.rs index ffe15ab644d..683eaa64d3d 100644 --- a/rs/moq-mux/src/container/ts/passthrough_test.rs +++ b/rs/moq-mux/src/container/ts/passthrough_test.rs @@ -659,22 +659,103 @@ async fn an_import_shifts_onto_a_clock_already_in_use() { assert_eq!(markers, [offset], "the break moves with the timeline"); } -/// A flagged step back is a restart: new content, which a timeline cannot step back into. +/// The clock steps that are not elapsed time: back with or without the flag, and forward more +/// than ten seconds without it. +const SPLICES: [(&str, u64, bool); 3] = [ + ("unflagged back", 2_000 * MS, false), + ("flagged back", 2_000 * MS, true), + ("unflagged leap", 60_000 * MS, false), +]; + +/// A step that is not elapsed time, as a switch between two unlocked encoders makes, is spliced: +/// the import carries on, the count resumes where the rate before the step puts it, and the next +/// group starts behind a break marker, whether the step lands on a random access point or not. #[tokio::test(start_paused = true)] -async fn a_flagged_step_back_is_a_restart() { +async fn a_step_that_is_not_elapsed_time_is_spliced() { + for (name, to, flagged) in SPLICES { + for mid_gop in [false, true] { + let mut mux = Mux::default(); + program(&mut mux, 0x100); + paced(&mut mux, 0x100, 10_000 * MS, if mid_gop { 25 } else { 30 }, 10, 2); + let mut step = Flags::pcr(to); + step.random_access = !mid_gop; + if flagged { + step = step.discontinuity(); + } + mux.packet(0x100, step); + mux.fill(0x101, 2); + paced(&mut mux, 0x100, to + 40 * MS, 30, 10, 2); + let data = mux.bytes(); + let case = format!("{name}, mid-GOP {mid_gop}"); + + let imported = import(&data, 188 * 7, None).await.expect(&case); + assert_suffix(&data, &imported); + let micros: Vec = imported.objects.iter().map(|object| object.micros).collect(); + assert!(micros.windows(2).all(|pair| pair[0] <= pair[1]), "{case}: {micros:?}"); + + let groups = imported.groups(); + let jump = groups + .iter() + .position(|group| header(&group[0].payload).pcr == Some(to)) + .unwrap_or_else(|| panic!("{case}: the step starts a group")); + let before = groups[jump - 1].last().unwrap().micros; + let after = groups[jump][0].micros; + assert!( + (before..before + 50_000).contains(&after), + "{case}: the count carries on past the step: {before} {after}" + ); + // Everything after carries on at the source's pace from there. + let last = imported.objects.last().unwrap().micros; + assert!( + (after + 1_150_000..after + 1_250_000).contains(&last), + "{case}: {after} {last}" + ); + let [marker] = imported.markers[..] else { + panic!("{case}: one marker: {:?}", imported.markers); + }; + assert!( + groups[jump - 1][0].group < marker && marker < groups[jump][0].group, + "{case}: a marker group between them declares the break" + ); + assert_eq!(imported.holes, [], "{case}"); + assert_eq!(imported.section().random_access, !mid_gop, "{case}"); + } + } +} + +/// An unflagged step forward of up to ten seconds is elapsed time, such as a stall at the source: +/// the count takes the step and no break is declared. +#[tokio::test(start_paused = true)] +async fn an_unflagged_step_within_ten_seconds_is_elapsed_time() { let mut mux = Mux::default(); program(&mut mux, 0x100); paced(&mut mux, 0x100, 10_000 * MS, 30, 10, 2); - mux.packet(0x100, Flags::pcr(2_000 * MS).discontinuity()); + paced(&mut mux, 0x100, 20_000 * MS, 30, 10, 2); let data = mux.bytes(); - let err = match import(&data, data.len(), None).await { - Ok(_) => panic!("a restart was carried on one timeline"), - Err(err) => err, - }; - assert!( - matches!(&err, crate::Error::PcrRestart { pid: 0x100, to, .. } if *to == 2_000 * MS), - "{err:?}" - ); + let imported = import(&data, data.len(), None).await.unwrap(); + assert_suffix(&data, &imported); + assert_eq!(imported.markers, Vec::::new()); + let last = imported.objects.last().unwrap().micros; + assert!((21_150_000..21_200_000).contains(&last), "{last}"); +} + +/// One corrupt PCR costs two splices, out to its value and back from it, rather than the import. +#[tokio::test(start_paused = true)] +async fn a_lone_corrupt_pcr_splices_twice() { + let mut mux = Mux::default(); + program(&mut mux, 0x100); + paced(&mut mux, 0x100, 10_000 * MS, 30, 10, 2); + mux.packet(0x100, Flags::pcr(40_000_000 * MS)); + mux.fill(0x101, 2); + paced(&mut mux, 0x100, 11_240 * MS, 30, 10, 2); + let data = mux.bytes(); + let imported = import(&data, data.len(), None).await.unwrap(); + assert_suffix(&data, &imported); + assert_eq!(imported.markers.len(), 2, "{:?}", imported.markers); + let micros: Vec = imported.objects.iter().map(|object| object.micros).collect(); + assert!(micros.windows(2).all(|pair| pair[0] <= pair[1]), "{micros:?}"); + let last = *micros.last().unwrap(); + assert!((12_300_000..12_450_000).contains(&last), "{last}"); } /// A break before any group has started is no group start, so the first group still waits for a @@ -693,23 +774,6 @@ async fn a_break_before_the_first_group_does_not_start_it() { assert!(imported.section().random_access); } -#[tokio::test(start_paused = true)] -async fn an_unflagged_rewind_is_refused() { - let mut mux = Mux::default(); - program(&mut mux, 0x100); - paced(&mut mux, 0x100, 10_000 * MS, 30, 10, 2); - mux.packet(0x100, Flags::pcr(9_000 * MS)); - let data = mux.bytes(); - let err = match import(&data, data.len(), None).await { - Ok(_) => panic!("a rewind was accepted"), - Err(err) => err, - }; - assert!( - matches!(&err, crate::Error::PcrRewind { pid: 0x100, to, .. } if *to == 9_000 * MS), - "{err:?}" - ); -} - #[tokio::test(start_paused = true)] async fn a_retransmitted_break_declares_one_jump() { let mut mux = Mux::default(); diff --git a/rs/moq-mux/src/container/ts/release.rs b/rs/moq-mux/src/container/ts/release.rs index 5fd720fc395..66f0d2984a5 100644 --- a/rs/moq-mux/src/container/ts/release.rs +++ b/rs/moq-mux/src/container/ts/release.rs @@ -23,9 +23,9 @@ use crate::jitter::{self, Arrival, Push}; /// source's, so the output keeps the source's PCR pacing whatever the arrival jitter, and two /// releases fed the same objects write the same bytes. An object that arrives past its /// deadline is dropped and counted; the output shows a continuity error there, since nothing -/// is rewritten, and carries on with the next object. A flagged forward jump, which the -/// importer declares with a discontinuity marker, opens a new clock, so the output does not -/// wait it out; the bytes carry the jump. +/// is rewritten, and carries on with the next object. A PCR clock break, which the importer +/// declares with a discontinuity marker, opens a new clock, so the output does not wait out a +/// jump; the bytes carry the break as the source sent it. pub struct Release { source: crate::Source, catalog: Option>, diff --git a/rs/moq-mux/src/container/ts/release_test.rs b/rs/moq-mux/src/container/ts/release_test.rs index 9ad5c650e97..98acd454585 100644 --- a/rs/moq-mux/src/container/ts/release_test.rs +++ b/rs/moq-mux/src/container/ts/release_test.rs @@ -244,11 +244,10 @@ async fn a_capture_is_released_byte_identical_on_its_own_pcr() { } } -#[tokio::test(start_paused = true)] -async fn a_flagged_jump_crosses_without_holding_the_output() { - // The capture twice, the second copy's clock twenty seconds ahead, its first PCR flagged - // as the discontinuity. - const STEP: u64 = 20 * 90_000; +/// The capture, then the capture again with its PCRs moved by `step` 90 kHz ticks around the +/// 33-bit wrap and its first PCR flagged as a discontinuity when `flagged`. +fn stepped(step: i64, flagged: bool) -> Vec { + const WRAP: i64 = 1 << 33; let mut second = KYRION.to_vec(); let mut pcrs = second .as_chunks_mut::<188>() @@ -256,53 +255,79 @@ async fn a_flagged_jump_crosses_without_holding_the_output() { .iter_mut() .filter(|pkt| pkt[3] & 0x20 != 0 && pkt[4] > 0 && pkt[5] & 0x10 != 0) .peekable(); - pcrs.peek_mut().expect("a PCR")[5] |= 0x80; + if flagged { + pcrs.peek_mut().expect("a PCR")[5] |= 0x80; + } for pkt in pcrs { let base = pkt[6..11].iter().fold(0u64, |base, byte| base << 8 | u64::from(*byte)) >> 7; - let base = ((base + STEP) & ((1 << 33) - 1)) << 7 | u64::from(pkt[10] & 0x7f); + let base = ((base as i64 + step).rem_euclid(WRAP) as u64) << 7 | u64::from(pkt[10] & 0x7f); pkt[6..11].copy_from_slice(&base.to_be_bytes()[3..]); } - let input = [KYRION, &second].concat(); - let objects = import(&input).await.objects; - assert!( - objects.iter().any(|object| object.payload.is_empty()), - "a marker declares the break" - ); + [KYRION, &second].concat() +} - // The bytes keep coming at the source's pace across the jump: only the PCR leaps. - let mut arrivals = vec![Duration::from_millis(40)]; - for pair in objects.windows(2) { - let step = Duration::from_micros(pair[1].micros - pair[0].micros).min(Duration::from_millis(100)); - arrivals.push(*arrivals.last().unwrap() + step); - } - let republished = republish(objects.clone(), move |i, _| arrivals[i]); - let source = crate::source::announced(&republished.consumer).await; - let release = Release::new(source, CatalogFormat::Hang, Duration::from_millis(500)) - .await - .unwrap(); - let delay = Duration::from_millis(500); - let (released, release) = drain(release).await; +/// Every clock break crosses the release without holding the output: a flagged jump forward, +/// which the timestamps carry, and the steps the importer splices, which they don't. The capture +/// repeated unchanged is an encoder restarting, its clock stepping back by the capture's length. +#[tokio::test(start_paused = true)] +async fn a_clock_break_crosses_without_holding_the_output() { + for (name, step, flagged, carried) in [ + ("flagged jump", 20 * 90_000, true, true), + ("unflagged back", 0, false, false), + ("flagged back", -90_000, true, false), + ("unflagged leap", 20 * 90_000, false, false), + ] { + let input = stepped(step, flagged); + let objects = import(&input).await.objects; + assert_eq!( + objects.iter().filter(|object| object.payload.is_empty()).count(), + 1, + "{name}: a marker declares the break" + ); - let out = bytes(released.iter().map(|(_, frame)| &frame.payload)); - assert!( - out == bytes(objects.iter().map(|object| &object.payload)), - "both sides of the jump go out, byte for byte" - ); - assert_eq!(release.dropped(), 0); - let (jump, step) = released - .windows(2) - .enumerate() - .map(|(i, pair)| { - ( - i, - pair[1].1.timestamp.as_micros().unwrap() as i128 - pair[0].1.timestamp.as_micros().unwrap() as i128, - ) - }) - .max_by_key(|(_, step)| *step) - .unwrap(); - assert!(step > 10_000_000, "the timestamps carry the jump"); - let pause = released[jump + 1].0.duration_since(released[jump].0); - assert!(pause <= delay, "the output paused {pause:?} at the jump"); + // The bytes keep coming at the source's pace across the break: only the PCR moves. + let mut arrivals = vec![Duration::from_millis(40)]; + for pair in objects.windows(2) { + let step = Duration::from_micros(pair[1].micros - pair[0].micros).min(Duration::from_millis(100)); + arrivals.push(*arrivals.last().unwrap() + step); + } + let republished = republish(objects.clone(), move |i, _| arrivals[i]); + let source = crate::source::announced(&republished.consumer).await; + let delay = Duration::from_millis(500); + let release = Release::new(source, CatalogFormat::Hang, delay).await.unwrap(); + let (released, release) = drain(release).await; + + assert!( + payloads(&released) == bytes(objects.iter().map(|object| &object.payload)), + "{name}: both sides of the break go out, byte for byte" + ); + assert!( + payloads(&released) == input[input.len() - payloads(&released).len()..], + "{name}: the output is the input" + ); + assert_eq!(release.dropped(), 0, "{name}"); + let (jump, step) = released + .windows(2) + .enumerate() + .map(|(i, pair)| { + ( + i, + pair[1].1.timestamp.as_micros().unwrap() as i128 - pair[0].1.timestamp.as_micros().unwrap() as i128, + ) + }) + .max_by_key(|(_, step)| *step) + .unwrap(); + match carried { + true => assert!(step > 10_000_000, "{name}: the timestamps carry the jump"), + false => assert!( + (0..100_000).contains(&step), + "{name}: the timestamps carry on past the splice: {step}" + ), + } + let pauses = released.windows(2).map(|pair| pair[1].0.duration_since(pair[0].0)); + let pause = pauses.max().unwrap(); + assert!(pause <= delay, "{name}: the output paused {pause:?} at {jump}"); + } } #[tokio::test(start_paused = true)] diff --git a/rs/moq-mux/src/container/ts/step.rs b/rs/moq-mux/src/container/ts/step.rs index edb6236a5a4..f83c95fbacd 100644 --- a/rs/moq-mux/src/container/ts/step.rs +++ b/rs/moq-mux/src/container/ts/step.rs @@ -33,7 +33,7 @@ use super::passthrough::PCR_HZ; use super::psi::{Pat, PesStart}; /// A forward step beyond this is another timeline: ffmpeg's `dts_delta_threshold`. -const LEAP: Duration = Duration::from_secs(10); +pub(super) const LEAP: Duration = Duration::from_secs(10); const PTS_HZ: u64 = 90_000; const PTS_WRAP: u64 = 1 << 33; diff --git a/rs/moq-mux/src/error.rs b/rs/moq-mux/src/error.rs index 0b7337c53cb..a162f001816 100644 --- a/rs/moq-mux/src/error.rs +++ b/rs/moq-mux/src/error.rs @@ -256,34 +256,6 @@ pub enum Error { #[error("transport stream uses {0}-byte packets; passthrough carries 188-byte packets only")] TsPacketSize(usize), - /// The clock PID's PCR went backwards without `discontinuity_indicator`. - /// - /// The source broke its own timebase without saying so, which leaves no timestamp that both - /// follows the PCR and stays on one timeline. - #[error("PCR on PID {pid} went back from {from} to {to} without a discontinuity_indicator")] - PcrRewind { - /// The clock PID. - pid: u16, - /// The previous PCR, raw 27 MHz ticks. - from: u64, - /// The PCR that stepped back, raw 27 MHz ticks. - to: u64, - }, - - /// The clock PID's PCR went backwards with `discontinuity_indicator`: the source restarted. - /// - /// What follows is new content, which belongs in a new broadcast rather than on a timeline that - /// steps back, so the import ends here. - #[error("PCR on PID {pid} restarted from {from} back to {to}; a restart needs a new broadcast")] - PcrRestart { - /// The clock PID. - pid: u16, - /// The previous PCR, raw 27 MHz ticks. - from: u64, - /// The flagged PCR, raw 27 MHz ticks. - to: u64, - }, - /// The clock PID carried no PCR across more bytes than a group may hold. /// /// Those bytes cannot be timed, and holding them for a PCR that may never come is unbounded. From 0a644abdc0ec010009dab0476a7a7aca4d485aeb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 20 Nov 2026 12:18:03 -0800 Subject: [PATCH 3/3] fix(mux): a splice starts past the marker's microsecond, and LEAP keeps sub-second precision Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/container/ts/passthrough.rs | 13 +++++---- .../src/container/ts/passthrough_test.rs | 29 +++++++++++++++++++ 2 files changed, 37 insertions(+), 5 deletions(-) diff --git a/rs/moq-mux/src/container/ts/passthrough.rs b/rs/moq-mux/src/container/ts/passthrough.rs index 264086b224f..9f68bfff440 100644 --- a/rs/moq-mux/src/container/ts/passthrough.rs +++ b/rs/moq-mux/src/container/ts/passthrough.rs @@ -21,7 +21,7 @@ const TICKS_PER_MICRO: u64 = PCR_HZ / 1_000_000; /// The longest unflagged step forward taken as elapsed time, in PCR ticks: the media-aware /// import's [`LEAP`](super::step::LEAP). -const LEAP_TICKS: u64 = super::step::LEAP.as_secs() * PCR_HZ; +const LEAP_TICKS: u64 = super::step::LEAP.as_micros() as u64 * TICKS_PER_MICRO; /// The most bytes a group holds before its next object starts another, so a source with sparse /// random access points still gives a joiner a group it can take whole. @@ -659,10 +659,13 @@ impl Passthrough { if object.discontinuity && let Groups::Writing(group) = &self.groups { - // The break's marker may take the microsecond past the newest group's start, as when a - // second break follows a one-PCR timebase that gave no rate, and the group behind it - // has to start past the marker. - ticks = ticks.max((group.ticks / TICKS_PER_MICRO + 2) * TICKS_PER_MICRO); + // The break's marker sits on the last object's microsecond, or the one past the newest + // group's start when that is later, and the group behind it has to start past the + // marker. A splice can resume on either, as after a PCR repeated or a one-PCR timebase, + // neither of which gives a rate. + let past_object = (self.written / TICKS_PER_MICRO + 1) * TICKS_PER_MICRO; + let past_group = (group.ticks / TICKS_PER_MICRO + 2) * TICKS_PER_MICRO; + ticks = ticks.max(past_object).max(past_group); } self.written = ticks; let timestamp = moq_net::Timestamp::from_micros(ticks / TICKS_PER_MICRO)?; diff --git a/rs/moq-mux/src/container/ts/passthrough_test.rs b/rs/moq-mux/src/container/ts/passthrough_test.rs index d2c44463f8a..f32537e722f 100644 --- a/rs/moq-mux/src/container/ts/passthrough_test.rs +++ b/rs/moq-mux/src/container/ts/passthrough_test.rs @@ -784,6 +784,35 @@ async fn a_lone_corrupt_pcr_splices_twice() { assert!((12_300_000..12_450_000).contains(&last), "{last}"); } +/// A repeated PCR gives the interval before a step no rate, so the splice resumes on the last +/// object's microsecond, where the marker sits: the group behind it still starts past it. +#[tokio::test(start_paused = true)] +async fn a_splice_after_a_repeated_pcr_starts_past_the_marker() { + let mut mux = Mux::default(); + program(&mut mux, 0x100); + paced(&mut mux, 0x100, 10_000 * MS, 30, 10, 2); + mux.packet(0x100, Flags::pcr(11_160 * MS)); + mux.fill(0x101, 2); + mux.packet(0x100, Flags::pcr(2_000 * MS)); + mux.fill(0x101, 2); + paced(&mut mux, 0x100, 2_040 * MS, 30, 10, 2); + let data = mux.bytes(); + let imported = import(&data, data.len(), None).await.unwrap(); + assert_suffix(&data, &imported); + let [marker] = imported.markers[..] else { + panic!("one marker: {:?}", imported.markers); + }; + let groups = imported.groups(); + let jump = groups + .iter() + .position(|group| header(&group[0].payload).pcr == Some(2_000 * MS)) + .expect("the step starts a group"); + let before = groups[jump - 1].last().unwrap().micros; + let after = groups[jump][0].micros; + assert!(groups[jump - 1][0].group < marker && marker < groups[jump][0].group); + assert!(before < after && after < before + 50_000, "{before} {after}"); +} + /// A break before any group has started is no group start, so the first group still waits for a /// random access point. #[tokio::test(start_paused = true)]