From 303e226337e1a1b773298fc0ff2f6c66e6a4f094 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Fri, 16 Oct 2026 22:17:33 -0700 Subject: [PATCH 1/2] quest: claim quest/m2/ts-passthrough-export From 78ae2c8091b3f6717f1cc49428c20ba6bb089283 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Fri, 16 Oct 2026 22:59:35 -0700 Subject: [PATCH 2/2] test(ts): grade the passthrough export packet by packet against its source A reusable oracle places every object a raw TS release writes at its exact position in the admitted source interval and checks it goes out on the source's PCR schedule, so a missing object leaves its time behind. Fixtures cover null and unknown PIDs, tables, adaptation stuffing, a split PES, the PCR wrap and an MPTS with unaligned recovery points, plus skipped and cut groups. The TS harness gains a --passthrough arm (and --mpts) graded by passthrough.py: every captured packet must be the source's in place, and every compliance check must grade the capture as it grades that interval of the source. CI runs it on the generated clip, a T-STD-passing capture and an MPTS, and nightly over 1% loss. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ts.yml | 35 +++ quest/m1/ts-reliability/README.md | 1 - quest/m1/ts-reliability/recovery.md | 8 + quest/m2/README.md | 1 - quest/m2/ts-hitless.md | 1 - quest/m2/ts-passthrough-epoch-cuts.md | 1 - quest/m2/ts-passthrough-export.md | 92 ------ rs/moq-mux/src/container/ts/fixture.rs | 271 ++++++++++++++++++ rs/moq-mux/src/container/ts/mod.rs | 4 + rs/moq-mux/src/container/ts/oracle.rs | 143 +++++++++ .../src/container/ts/passthrough_test.rs | 167 +---------- rs/moq-mux/src/container/ts/release_test.rs | 229 ++++++++++----- test/justfile | 6 + test/ts/README.md | 57 +++- test/ts/passthrough.py | 180 ++++++++++++ test/ts/passthrough.test.py | 71 +++++ test/ts/run.sh | 74 ++++- 17 files changed, 1008 insertions(+), 333 deletions(-) delete mode 100644 quest/m2/ts-passthrough-export.md create mode 100644 rs/moq-mux/src/container/ts/fixture.rs create mode 100644 rs/moq-mux/src/container/ts/oracle.rs create mode 100644 test/ts/passthrough.py create mode 100644 test/ts/passthrough.test.py diff --git a/.github/workflows/ts.yml b/.github/workflows/ts.yml index 669f0ee79a2..ac34aa39d36 100644 --- a/.github/workflows/ts.yml +++ b/.github/workflows/ts.yml @@ -91,6 +91,34 @@ jobs: MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs shell: bash -leo pipefail {0} + # `import/export ts --passthrough`: from its first packet the capture is the source's + # packets in place, and every compliance check grades it as it grades that interval of + # the source. The generated clip fails the T-STD model on its own; the capture must too. + - name: TS passthrough + if: ${{ !cancelled() }} + run: nix develop --command just test ts --passthrough + env: + MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + shell: bash -leo pipefail {0} + + # The same over a hardware encoder's capture the T-STD model passes, with a dirty start + # the importer acquires past. + - name: TS passthrough of a broadcast capture + if: ${{ !cancelled() }} + run: nix develop --command just test ts-passthrough-capture + env: + MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + shell: bash -leo pipefail {0} + + # The same over a whole MPTS: two programs on their own PCR PIDs, whose recovery points + # rarely line up. + - name: TS passthrough of an MPTS + if: ${{ !cancelled() }} + run: nix develop --command just test ts --passthrough --mpts + env: + MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + shell: bash -leo pipefail {0} + # The same round-trip at 2 Mb/s, where every keyframe outgrows a 25 ms PCR slot, # so the export has to spread it over the slots before its DTS and still keep # the constant-rate schedule. @@ -189,6 +217,13 @@ jobs: env: MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + # The passthrough over the same path: retransmission must leave no packet missing or moved. + - name: TS passthrough lossy path + if: ${{ !cancelled() && github.event_name != 'pull_request' }} + run: nix develop --command just test ts --passthrough --loss 1 --duration 120 + env: + MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + - name: Upload failure artifacts if: ${{ failure() }} uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 diff --git a/quest/m1/ts-reliability/README.md b/quest/m1/ts-reliability/README.md index f54585bfe89..36598354197 100644 --- a/quest/m1/ts-reliability/README.md +++ b/quest/m1/ts-reliability/README.md @@ -114,4 +114,3 @@ remain with their current quests. - [TS health counters](/quest/m2/ts-health-stats.md) - ingress and egress evidence need distinct monitoring points - [MSFTS mapping](/quest/m3/msfts-convergence.md) - document the exact equivalence and differences between the carriage modes -- [TS passthrough export](/quest/m2/ts-passthrough-export.md) - a new mode that does not gate correctness of existing TS modes diff --git a/quest/m1/ts-reliability/recovery.md b/quest/m1/ts-reliability/recovery.md index 6b906453149..f28e7241834 100644 --- a/quest/m1/ts-reliability/recovery.md +++ b/quest/m1/ts-reliability/recovery.md @@ -30,6 +30,14 @@ around PAT/PMT or catalog acquisition, codec configuration and recovery points, audio/video skew, PCR/PTS wrap and declared clock discontinuity. Choose fixtures from declared supported profiles, not an unbounded matrix. +The raw passthrough lane already has the packet/position and release-schedule +oracle (`rs/moq-mux/src/container/ts/oracle.rs`, `test/ts/passthrough.py`) +with skipped-group, cut-group and late-object regressions in `release_test.rs`; +extend it rather than build a second harness. Assert there that each omission +shows in the release's counters: `dropped` counts late objects, and the +skipped and cut groups need the `gaps` count +[#5849](https://github.com/moq-dev/moq/pull/5849) adds to `Release::stats`. + Use mocked time for the Rust scheduling regressions. Integration captures record exactly which content was delivered, omitted or late, so the oracle does not explain every output gap as acceptable loss. Decode surviving diff --git a/quest/m2/README.md b/quest/m2/README.md index b4d37384ae7..64eb5cfa64f 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -79,7 +79,6 @@ ranked just below deterministic TS legs, which it requires. - [Time stretch](/quest/m2/watch-audio-time-stretch.md) - js/watch: the audio ring converges by time-stretching instead of skipping or going silent - [Native audio quality](/quest/m2/audio-quality-native.md) - the browser lane's profiles, budgets, and metric schema run against `moq play` on a dummy device - [TTML caption import](/quest/m2/captions-ttml.md) - fMP4 `stpp` tracks within a supported TTML/IMSC profile import as `ttml` renditions on the shared clock instead of being skipped -- [TS passthrough export](/quest/m2/ts-passthrough-export.md) - `export ts --passthrough` writes the `m2ts` track back byte-identical (less late drops) on a fixed delay - [Bindings size profile](/quest/m2/ffi-size-profile.md) - a benchmark decides whether the moq-ffi builds ship at opt-level "s", which halves the dylib - [Zero-copy byte returns](/quest/m2/ffi-bytes-return.md) - returned payloads reach the host without a copy, if the payload numbers justify it - [Namespaced external types](/quest/m2/uniffi-namespaces.md) - the UniFFI fork lets two crates export the same type name, reopening the per-layer crate split diff --git a/quest/m2/ts-hitless.md b/quest/m2/ts-hitless.md index 8e438ec2b4b..1ea6cfee2b7 100644 --- a/quest/m2/ts-hitless.md +++ b/quest/m2/ts-hitless.md @@ -87,4 +87,3 @@ Public API: `moq export ts --sync`. - [TS over RTP legs](/quest/m2/ts-rtp-egress.md) - packetizes these slots with matching RTP headers for ST 2022-7 - [Same-epoch importers](/quest/m2/hop-aligned-import.md) - extends the coordinate to legs fed by different importers -- [TS passthrough export](/quest/m2/ts-passthrough-export.md) - identical packets for common objects by construction, in its own lane diff --git a/quest/m2/ts-passthrough-epoch-cuts.md b/quest/m2/ts-passthrough-epoch-cuts.md index f969421b4c3..3f109700691 100644 --- a/quest/m2/ts-passthrough-epoch-cuts.md +++ b/quest/m2/ts-passthrough-epoch-cuts.md @@ -65,4 +65,3 @@ Public API: none. ## Related - [Same-epoch importers](/quest/m2/hop-aligned-import.md) - group sequences and the end-to-end pair -- [TS passthrough export](/quest/m2/ts-passthrough-export.md) - identical objects export as identical packets diff --git a/quest/m2/ts-passthrough-export.md b/quest/m2/ts-passthrough-export.md deleted file mode 100644 index e3879d57c2c..00000000000 --- a/quest/m2/ts-passthrough-export.md +++ /dev/null @@ -1,92 +0,0 @@ -# [M] TS passthrough export writes the multiplex back byte-identical on a fixed delay - -## Goal - -`moq export ts --passthrough --delay ` reads the track a broadcast's -`m2ts` catalog section names and writes the same bytes back out, paced on the -source's own PCR and released at a fixed delay like an SRT receiver. From the -first group it releases, the output is byte-identical to the input, less any -object dropped late. On a complete path, validate preservation of the source -schedule as well as the bytes. Missing bytes can break a decoder's acquisition -or buffers; packet identity alone does not preserve T-STD conformance under loss. -There is no JS player for it. - -## Plan - -For raw fallback, reuse the passthrough quest's packet/position and schedule -oracle. Extend its fault coverage to compare surviving packets against their exact positions -in the admitted source interval, including null packets, tables, unknown -PIDs and adaptation bytes. Assert preserved gaps in the release schedule, -no rewriting or duplication, and observed loss counters. A dropped object -may contain part of a PES or the next acquisition information; record when -decode is unavailable rather than claiming an unchanged-byte proof also -proves decoder conformance. Whole MPTS coverage includes programs with -unaligned recovery points and clocks. - -Decided (2026-10-01), from a discussion with t0ms, and split from the TS -passthrough quest on #5003, whose import half it completes: - -Confirmed in the 2026-10-11 audit: carry either one supplied SPTS or the whole -MPTS unchanged. Do not extract programs or split PIDs in this mode. Separate -SPTS inputs have separate raw broadcasts/tracks under the existing one-multiplex -catalog contract; extracting a program from an MPTS changes -the packet sequence and is not the byte-identical fallback. This matches the -distinction between `unmodified-program`, `unmodified-multiplex` and -`per-program` in [MSFTS](https://datatracker.ietf.org/doc/html/draft-gregoire-moq-msfts). - -The exactness boundary is the admitted source interval, starting at the first -released group. Account for the importer's current acquisition prefix and -188-byte framing restrictions explicitly; do not call this whole-file identity. -Test group acquisition without inserting synthetic tables or configuration -into the output. A periodic group boundary or one program's RAI does not -promise immediate decode for every program in an MPTS. - -- The export reuses the TS export's jitter buffer (`rs/moq-mux/src/jitter.rs`), - keyed on each object's PCR time instead of a DTS, which also spreads each - object's bytes at the PCR-implied rate. It must pace on the source's PCR, - not on arrival: a pacer that re-clocks on arrival moves the PCR-to-PTS - offset over a long capture and fails the decoder buffers, even though every - byte is intact. -- An object that misses its deadline is dropped and counted, as the release - stage does. The output shows a continuity error there; passthrough never - rewrites continuity counters. -- Source clock drift is handled by the fixed-delay release's clock recovery, - shared with the demultiplexed export, not here. -- A flagged forward jump arrives as a break marker before the group it - starts; the release keeps the jump in the output, since the bytes carry it. -- Passthrough gives 1+1 identity for free: two exporters fed the same objects - emit identical TS packets for every object both release, continuity - counters included; an object one leg drops late is a gap in that leg only. - That is TS identity, not ST 2022-7 recovery, which also needs matching RTP - headers from [RTP egress](/quest/m2/ts-rtp-egress.md). -- Rust only. - -This quest owns the reusable raw packet/position and release-schedule oracle -and its basic omission fixtures; the recovery quest extends it with the wider -fault matrix rather than building a second harness. - -Automated tests in CI: an export of a supported capture is byte-identical to -the admitted input interval on a complete path, and the applicable T-STD check -gives the same verdict on output and input. Assert packet order and release -schedule as well as bytes. Two exporters fed the same objects with different arrival -skew emit identical bytes; when only one misses a deadline, its output is the -other's less that object's packets. A dropped object is counted, and the rest -still go out on their original schedule, leaving the missing time intact. -Use deterministic object/group omissions as well as a nightly real-network -impairment test: IP packet loss may be retransmitted and is not proof of -missing MoQ content. Fixtures include null/unknown PIDs, tables, adaptation -bytes, split PES, clock wrap, and MPTS with unaligned program recovery points. -Run TSDuck and FFmpeg automatically for profiles where their assertions apply; -record expected decode outages under loss separately from byte preservation. - -Update `doc/bin/cli.md` for the flag, which today says `export ts` does not -read the passthrough track. - -Public API: a new export mode; nothing existing breaks. - -## Related - -- [Deterministic TS legs](/quest/m2/ts-hitless.md) - the demultiplexed lane's common packet identity under `--sync` -- [TS validation](/test/ts/README.md) - shared automatic graders and controls -- [Loss and recovery](/quest/m1/ts-reliability/recovery.md) - actual missing content and reacquisition proof -- [Same-epoch importers](/quest/m2/hop-aligned-import.md) - identical common objects do not prove independent importers publish identical groups diff --git a/rs/moq-mux/src/container/ts/fixture.rs b/rs/moq-mux/src/container/ts/fixture.rs new file mode 100644 index 00000000000..e4c494e24e1 --- /dev/null +++ b/rs/moq-mux/src/container/ts/fixture.rs @@ -0,0 +1,271 @@ +//! Builds transport streams packet by packet for the passthrough and release tests, covering +//! what the in-repo captures don't carry (several programs, a wrap, a flagged jump, ...). + +use std::collections::HashMap; + +use super::psi; + +/// Builds a transport stream packet by packet. +#[derive(Default)] +pub(super) struct Mux { + pub(super) out: Vec, + cc: HashMap, +} + +#[derive(Clone, Copy, Default)] +pub(super) struct Flags { + pub(super) pcr: Option, + pub(super) random_access: bool, + pub(super) discontinuity: bool, +} + +impl Flags { + pub(super) fn pcr(ticks: u64) -> Self { + Self { + pcr: Some(ticks), + ..Default::default() + } + } + + pub(super) fn random_access(mut self) -> Self { + self.random_access = true; + self + } + + pub(super) fn discontinuity(mut self) -> Self { + self.discontinuity = true; + self + } +} + +pub(super) const ACCESS: Flags = Flags { + pcr: None, + random_access: true, + discontinuity: false, +}; + +impl Mux { + fn cc(&mut self, pid: u16) -> u8 { + let cc = self.cc.entry(pid).or_default(); + let out = *cc; + *cc = (*cc + 1) & 0x0f; + out + } + + /// One packet on `pid`, its payload filled with the PID's low byte. + pub(super) fn packet(&mut self, pid: u16, flags: Flags) -> &mut Self { + let cc = self.cc(pid); + let mut pkt = vec![0x47, (pid >> 8) as u8 & 0x1f, pid as u8]; + let marked = flags.pcr.is_some() || flags.random_access || flags.discontinuity; + if marked { + pkt.push(0x30 | cc); + let mut field = vec![ + u8::from(flags.discontinuity) << 7 + | u8::from(flags.random_access) << 6 + | u8::from(flags.pcr.is_some()) << 4, + ]; + if let Some(pcr) = flags.pcr { + let (base, ext) = (pcr / 300, pcr % 300); + field.extend_from_slice(&[ + (base >> 25) as u8, + (base >> 17) as u8, + (base >> 9) as u8, + (base >> 1) as u8, + ((base & 1) << 7) as u8 | 0x7e | (ext >> 8) as u8, + ext as u8, + ]); + } + pkt.push(field.len() as u8); + pkt.extend_from_slice(&field); + } else { + pkt.push(0x10 | cc); + } + pkt.resize(188, pid as u8); + self.out.extend_from_slice(&pkt); + self + } + + /// `n` plain packets on `pid`. + pub(super) fn fill(&mut self, pid: u16, n: usize) -> &mut Self { + for _ in 0..n { + self.packet(pid, Flags::default()); + } + self + } + + /// A packet on `pid` that is all adaptation field: no flags, then stuffing to the end. + pub(super) fn stuffing(&mut self, pid: u16) -> &mut Self { + // An adaptation-only packet repeats the counter of the packet before it. + let cc = self.cc.get(&pid).map_or(0, |next| next.wrapping_sub(1) & 0x0f); + let mut pkt = vec![0x47, (pid >> 8) as u8 & 0x1f, pid as u8, 0x20 | cc, 183, 0x00]; + pkt.resize(188, 0xff); + self.out.extend_from_slice(&pkt); + self + } + + /// The first packet of a PES on `pid`, carrying `flags` and a header with a PTS of `pts` + /// (90 kHz); the PES continues in whatever packets on `pid` follow. + pub(super) fn pes(&mut self, pid: u16, flags: Flags, pts: u64) -> &mut Self { + let at = self.out.len(); + self.packet(pid, flags); + let pkt = &mut self.out[at..]; + pkt[1] |= 0x40; + let payload = match pkt[3] & 0x20 != 0 { + true => 5 + usize::from(pkt[4]), + false => 4, + }; + let pts = [ + 0x21 | ((pts >> 29) & 0x0e) as u8, + (pts >> 22) as u8, + 0x01 | ((pts >> 14) & 0xfe) as u8, + (pts >> 7) as u8, + 0x01 | ((pts << 1) & 0xfe) as u8, + ]; + let stream_id = if pid == 0x100 { 0xe0 } else { 0xc0 }; + let header = [0, 0, 1, stream_id, 0, 0, 0x80, 0x80, 5]; + pkt[payload..payload + header.len()].copy_from_slice(&header); + pkt[payload + header.len()..payload + header.len() + pts.len()].copy_from_slice(&pts); + self + } + + /// A section on `pid`, split across as many packets as it needs. + pub(super) fn section(&mut self, pid: u16, section: &[u8]) -> &mut Self { + let mut payload = vec![0u8]; + payload.extend_from_slice(section); + for (i, chunk) in payload.chunks(184).enumerate() { + let cc = self.cc(pid); + let pusi = if i == 0 { 0x40 } else { 0 }; + let mut pkt = vec![0x47, pusi | (pid >> 8) as u8 & 0x1f, pid as u8, 0x10 | cc]; + pkt.extend_from_slice(chunk); + pkt.resize(188, 0xff); + self.out.extend_from_slice(&pkt); + } + self + } + + pub(super) fn pat(&mut self, programs: &[(u16, u16)]) -> &mut Self { + let body: Vec = programs + .iter() + .flat_map(|&(number, pmt)| [(number >> 8) as u8, number as u8, 0xe0 | (pmt >> 8) as u8, pmt as u8]) + .collect(); + self.section(0, &psi::section(psi::PAT_TABLE_ID, 1, 0, 0, 0, &body)) + } + + /// A PMT whose `program_info` holds `info` bytes of private descriptors, so a large one + /// spans packets. + pub(super) fn pmt( + &mut self, + pid: u16, + program: u16, + pcr_pid: u16, + streams: &[(u8, u16)], + info: usize, + ) -> &mut Self { + let mut descriptors = Vec::new(); + while descriptors.len() < info { + let len = (info - descriptors.len()).clamp(2, 200) - 2; + descriptors.push(0x80); + descriptors.push(len as u8); + descriptors.extend(std::iter::repeat_n(0xaa, len)); + } + let mut body = vec![ + 0xe0 | (pcr_pid >> 8) as u8, + pcr_pid as u8, + 0xf0 | (descriptors.len() >> 8) as u8, + descriptors.len() as u8, + ]; + body.extend_from_slice(&descriptors); + for &(stream_type, es) in streams { + body.extend_from_slice(&[stream_type, 0xe0 | (es >> 8) as u8, es as u8, 0xf0, 0x00]); + } + self.section(pid, &psi::section(psi::PMT_TABLE_ID, program, 0, 0, 0, &body)) + } + + pub(super) fn bytes(&self) -> Vec { + self.out.clone() + } +} + +/// 27 MHz ticks per millisecond. +pub(super) const MS: u64 = 27_000; + +/// A single program: PMT on 0x20, H.264 video on 0x100, audio on 0x101, the clock on `pcr_pid`. +pub(super) fn program(mux: &mut Mux, pcr_pid: u16) { + mux.pat(&[(1, 0x20)]) + .pmt(0x20, 1, pcr_pid, &[(0x1b, 0x100), (0x0f, 0x101)], 0); +} + +/// `seconds` of a stream paced 40 ms per PCR on `pcr_pid`, starting at `start` ticks, with a +/// video random access point every `gop` PCRs (none when zero). Each PCR interval is the PCR +/// packet then `fill` packets alternating video and audio. +pub(super) fn paced(mux: &mut Mux, pcr_pid: u16, start: u64, intervals: u64, gop: u64, fill: usize) { + for i in 0..intervals { + mux.packet(pcr_pid, Flags::pcr(start + i * 40 * MS)); + if gop != 0 && i % gop == 0 { + mux.packet(0x100, ACCESS); + } + for j in 0..fill { + mux.fill(if j % 2 == 0 { 0x100 } else { 0x101 }, 1); + } + } +} + +/// 2^33 PCR bases, where the clock wraps, in 27 MHz ticks. +pub(super) const WRAP: u64 = (1 << 33) * 300; + +/// One program carrying everything a raw passthrough has to leave untouched, `intervals` PCRs +/// 40 ms apart from `start` ticks, wrapping at [`WRAP`]: the clock alone on PID 0x1ff, PSI and +/// an SDT before each random access point, a video PES started mid-interval so it is split +/// across the next PCR, audio PES, adaptation stuffing, null packets, and a PID no table lists. +pub(super) fn assorted(start: u64, intervals: u64, gop: u64) -> Vec { + let mut mux = Mux::default(); + let sdt = psi::section(0x42, 1, 0, 0, 0, &[0x00, 0x01, 0xff, 0x00, 0x01, 0xfc, 0x80, 0x00]); + for i in 0..intervals { + let ticks = (start + i * 40 * MS) % WRAP; + if i % gop == 0 { + mux.pat(&[(1, 0x20)]) + .pmt(0x20, 1, 0x1ff, &[(0x1b, 0x100), (0x0f, 0x101)], 0) + .section(0x11, &sdt); + } + mux.packet(0x1ff, Flags::pcr(ticks)); + mux.fill(0x100, 2); + let pts = (ticks / 300 + 90 * 100) % (1 << 33); + match i % gop { + 0 => mux.pes(0x100, ACCESS, pts), + _ => mux.pes(0x100, Flags::default(), pts), + }; + mux.fill(0x100, 2).pes(0x101, Flags::default(), pts).stuffing(0x101); + mux.fill(0x1fff, 2); + if i % 5 == 0 { + mux.fill(0x1abc, 1); + } + } + mux.bytes() +} + +/// Two programs on clocks of their own, `intervals` of program 1's PCRs 40 ms apart, each with +/// a random access point every `gop` intervals but never at the same time as the other's. +pub(super) fn mpts(intervals: u64, gop: u64) -> Vec { + let mut mux = Mux::default(); + // Program 2's clock is unrelated to program 1's and ticks on its own cadence. + let other = WRAP / 3; + for i in 0..intervals { + if i % gop == 0 { + mux.pat(&[(1, 0x20), (2, 0x30)]) + .pmt(0x20, 1, 0x100, &[(0x1b, 0x100), (0x0f, 0x101)], 0) + .pmt(0x30, 2, 0x200, &[(0x1b, 0x200), (0x0f, 0x201)], 0); + } + let mut flags = Flags::pcr(i * 40 * MS); + flags.random_access = i % gop == 0; + mux.pes(0x100, flags, i * 3_600); + mux.fill(0x100, 3).fill(0x101, 1); + if i % 3 == 1 { + mux.packet(0x200, Flags::pcr(other + i * 40 * MS + 17 * MS)); + } + if i % gop == gop / 2 + 1 { + mux.pes(0x200, ACCESS, i * 3_600); + } + mux.fill(0x200, 3).fill(0x201, 1).fill(0x1fff, 1); + } + mux.bytes() +} diff --git a/rs/moq-mux/src/container/ts/mod.rs b/rs/moq-mux/src/container/ts/mod.rs index b342a3f513e..f5adb45bc98 100644 --- a/rs/moq-mux/src/container/ts/mod.rs +++ b/rs/moq-mux/src/container/ts/mod.rs @@ -57,8 +57,12 @@ mod export_test; #[cfg(test)] mod export_timing_test; #[cfg(test)] +mod fixture; +#[cfg(test)] mod import_test; #[cfg(test)] +mod oracle; +#[cfg(test)] mod passthrough_test; #[cfg(test)] mod release_test; diff --git a/rs/moq-mux/src/container/ts/oracle.rs b/rs/moq-mux/src/container/ts/oracle.rs new file mode 100644 index 00000000000..14affc55677 --- /dev/null +++ b/rs/moq-mux/src/container/ts/oracle.rs @@ -0,0 +1,143 @@ +//! Grades a raw TS release against the source it was imported from. +//! +//! The admitted interval is the source from the first packet of the first group the release +//! writes to the end. Every packet the release writes must sit at its exact position in that +//! interval: nothing rewritten, duplicated or reordered, null packets, tables, unknown PIDs and +//! adaptation bytes included. Each object must go out on the source's PCR schedule, so a missing +//! object leaves its time in the output instead of pulling the rest forward. The bytes the +//! importer withheld while acquiring, before its first group, are [`Admitted::prefix`], not part +//! of the claim. +//! +//! Identity is not decodability: a missing object can hold part of a PES or the next table, so a +//! gap is reported as [`Loss`] and never graded as decodable here. + +use std::time::Duration; + +use bytes::Bytes; +use tokio::time::Instant; + +use crate::container::Frame; + +const PACKET: usize = 188; + +/// One object as published: its group, the PCR time of its first byte, and its packets. +#[derive(Clone, Debug, PartialEq)] +pub(super) struct Object { + pub group: u64, + pub micros: u64, + pub payload: Bytes, +} + +/// The published objects, placed on the source they came from. +pub(super) struct Admitted<'a> { + source: &'a [u8], + objects: &'a [Object], + /// Where each object's first packet sits in `source`. + offsets: Vec, +} + +/// What a release left out of its admitted interval. +#[derive(Debug, Default, PartialEq)] +pub(super) struct Loss { + /// The published object the release opened on. + pub first: usize, + /// The published objects from `first` on that it never wrote. + pub missing: Vec, +} + +impl<'a> Admitted<'a> { + /// Place `objects` on `source`, checking they are its packets verbatim, in order, from the + /// first published group to the end. + pub fn new(source: &'a [u8], objects: &'a [Object]) -> Self { + assert!(!objects.is_empty(), "nothing was published"); + let published: usize = objects.iter().map(|object| object.payload.len()).sum(); + assert!(published <= source.len(), "more was published than the source holds"); + let start = source.len() - published; + assert_eq!(start % PACKET, 0, "the first group starts on the packet grid"); + let mut offsets = Vec::with_capacity(objects.len()); + let mut offset = start; + for (i, object) in objects.iter().enumerate() { + assert!( + !object.payload.is_empty() && object.payload.len() % PACKET == 0, + "object {i} is whole packets" + ); + assert!( + source[offset..offset + object.payload.len()] == object.payload[..], + "object {i} is the source's packets {}.. verbatim", + offset / PACKET + ); + offsets.push(offset); + offset += object.payload.len(); + } + Self { + source, + objects, + offsets, + } + } + + /// Bytes of the source before the first published group, which acquisition withheld. + pub fn prefix(&self) -> usize { + self.offsets[0] + } + + /// Grade what a release wrote, and when, against the admitted interval it opened. + /// + /// The release must open on the first object of a group, write every object at its exact + /// position after that in order and stamped as published, and write each within `tolerance` + /// of its PCR time on the clock its first object set. + pub fn grade(&self, released: &[(Instant, Frame)], tolerance: Duration) -> Loss { + let Some((start, opened)) = released.first() else { + panic!("the release wrote nothing"); + }; + let mut matched = Vec::with_capacity(released.len()); + let mut next = 0; + for (i, (_, frame)) in released.iter().enumerate() { + let micros = frame.timestamp.as_micros() as u64; + let Some(found) = (next..self.objects.len()).find(|&j| self.objects[j].micros == micros) else { + panic!("released object {i} at {micros} us is no published object after the one before it"); + }; + let offset = self.offsets[found]; + assert!( + self.source[offset..].starts_with(&frame.payload) && frame.payload == self.objects[found].payload, + "released object {i} is not the source's packets {}.. verbatim", + offset / PACKET + ); + matched.push(found); + next = found + 1; + } + + let first = matched[0]; + assert!( + first == 0 || self.objects[first - 1].group != self.objects[first].group, + "the release opens on object {first}, inside group {}", + self.objects[first].group + ); + + let origin = opened.timestamp.as_micros() as i128; + for ((at, frame), j) in released.iter().zip(&matched) { + let out = at.duration_since(*start).as_micros() as i128; + let lag = out - (frame.timestamp.as_micros() as i128 - origin); + assert!( + lag.unsigned_abs() <= tolerance.as_micros(), + "object {j} goes out {lag} us off its PCR time" + ); + } + + let mut written = matched.into_iter().peekable(); + let missing = (first..self.objects.len()) + .filter(|j| written.next_if_eq(j).is_none()) + .collect(); + Loss { first, missing } + } + + /// The admitted interval from `loss.first`, less the objects it is missing: what the release + /// must have written. + pub fn expected(&self, loss: &Loss) -> Vec { + let mut missing = loss.missing.iter().peekable(); + (loss.first..self.objects.len()) + .filter(|j| missing.next_if_eq(&j).is_none()) + .flat_map(|j| self.objects[j].payload.iter().copied()) + .collect() + } +} diff --git a/rs/moq-mux/src/container/ts/passthrough_test.rs b/rs/moq-mux/src/container/ts/passthrough_test.rs index ad2260e65d1..6c862b8e78a 100644 --- a/rs/moq-mux/src/container/ts/passthrough_test.rs +++ b/rs/moq-mux/src/container/ts/passthrough_test.rs @@ -5,15 +5,14 @@ //! captures don't carry (scrambling, several programs, a wrap, a flagged jump, oversized groups) //! is built by [`Mux`]. -use std::collections::HashMap; use std::time::Duration; use bytes::Bytes; +use super::fixture::{ACCESS, Flags, MS, Mux, WRAP, paced, program}; use super::passthrough::{ GROUP_BYTES_MAX, GROUP_OBJECTS_MAX, PacketSizeError, Passthrough, PcrGapError, PcrRestartError, PcrRewindError, }; -use super::psi; /// A delay budget no test timeline comes close to, so the reader sees every group. const RECORDING_MAX_DELAY: Duration = Duration::from_secs(30); @@ -138,169 +137,6 @@ fn header(pkt: &[u8]) -> Header { header } -/// Builds a transport stream packet by packet. -#[derive(Default)] -struct Mux { - out: Vec, - cc: HashMap, -} - -#[derive(Clone, Copy, Default)] -struct Flags { - pcr: Option, - random_access: bool, - discontinuity: bool, -} - -impl Flags { - fn pcr(ticks: u64) -> Self { - Self { - pcr: Some(ticks), - ..Default::default() - } - } - - fn random_access(mut self) -> Self { - self.random_access = true; - self - } - - fn discontinuity(mut self) -> Self { - self.discontinuity = true; - self - } -} - -const ACCESS: Flags = Flags { - pcr: None, - random_access: true, - discontinuity: false, -}; - -impl Mux { - fn cc(&mut self, pid: u16) -> u8 { - let cc = self.cc.entry(pid).or_default(); - let out = *cc; - *cc = (*cc + 1) & 0x0f; - out - } - - /// One packet on `pid`, its payload filled with the PID's low byte. - fn packet(&mut self, pid: u16, flags: Flags) -> &mut Self { - let cc = self.cc(pid); - let mut pkt = vec![0x47, (pid >> 8) as u8 & 0x1f, pid as u8]; - let marked = flags.pcr.is_some() || flags.random_access || flags.discontinuity; - if marked { - pkt.push(0x30 | cc); - let mut field = vec![ - u8::from(flags.discontinuity) << 7 - | u8::from(flags.random_access) << 6 - | u8::from(flags.pcr.is_some()) << 4, - ]; - if let Some(pcr) = flags.pcr { - let (base, ext) = (pcr / 300, pcr % 300); - field.extend_from_slice(&[ - (base >> 25) as u8, - (base >> 17) as u8, - (base >> 9) as u8, - (base >> 1) as u8, - ((base & 1) << 7) as u8 | 0x7e | (ext >> 8) as u8, - ext as u8, - ]); - } - pkt.push(field.len() as u8); - pkt.extend_from_slice(&field); - } else { - pkt.push(0x10 | cc); - } - pkt.resize(188, pid as u8); - self.out.extend_from_slice(&pkt); - self - } - - /// `n` plain packets on `pid`. - fn fill(&mut self, pid: u16, n: usize) -> &mut Self { - for _ in 0..n { - self.packet(pid, Flags::default()); - } - self - } - - /// A section on `pid`, split across as many packets as it needs. - fn section(&mut self, pid: u16, section: &[u8]) -> &mut Self { - let mut payload = vec![0u8]; - payload.extend_from_slice(section); - for (i, chunk) in payload.chunks(184).enumerate() { - let cc = self.cc(pid); - let pusi = if i == 0 { 0x40 } else { 0 }; - let mut pkt = vec![0x47, pusi | (pid >> 8) as u8 & 0x1f, pid as u8, 0x10 | cc]; - pkt.extend_from_slice(chunk); - pkt.resize(188, 0xff); - self.out.extend_from_slice(&pkt); - } - self - } - - fn pat(&mut self, programs: &[(u16, u16)]) -> &mut Self { - let body: Vec = programs - .iter() - .flat_map(|&(number, pmt)| [(number >> 8) as u8, number as u8, 0xe0 | (pmt >> 8) as u8, pmt as u8]) - .collect(); - self.section(0, &psi::section(psi::PAT_TABLE_ID, 1, 0, 0, 0, &body)) - } - - /// A PMT whose `program_info` holds `info` bytes of private descriptors, so a large one - /// spans packets. - fn pmt(&mut self, pid: u16, program: u16, pcr_pid: u16, streams: &[(u8, u16)], info: usize) -> &mut Self { - let mut descriptors = Vec::new(); - while descriptors.len() < info { - let len = (info - descriptors.len()).clamp(2, 200) - 2; - descriptors.push(0x80); - descriptors.push(len as u8); - descriptors.extend(std::iter::repeat_n(0xaa, len)); - } - let mut body = vec![ - 0xe0 | (pcr_pid >> 8) as u8, - pcr_pid as u8, - 0xf0 | (descriptors.len() >> 8) as u8, - descriptors.len() as u8, - ]; - body.extend_from_slice(&descriptors); - for &(stream_type, es) in streams { - body.extend_from_slice(&[stream_type, 0xe0 | (es >> 8) as u8, es as u8, 0xf0, 0x00]); - } - self.section(pid, &psi::section(psi::PMT_TABLE_ID, program, 0, 0, 0, &body)) - } - - fn bytes(&self) -> Vec { - self.out.clone() - } -} - -/// 27 MHz ticks per millisecond. -const MS: u64 = 27_000; - -/// A single program: PMT on 0x20, H.264 video on 0x100, audio on 0x101, the clock on `pcr_pid`. -fn program(mux: &mut Mux, pcr_pid: u16) { - mux.pat(&[(1, 0x20)]) - .pmt(0x20, 1, pcr_pid, &[(0x1b, 0x100), (0x0f, 0x101)], 0); -} - -/// `seconds` of a stream paced 40 ms per PCR on `pcr_pid`, starting at `start` ticks, with a -/// video random access point every `gop` PCRs (none when zero). Each PCR interval is the PCR -/// packet then `fill` packets alternating video and audio. -fn paced(mux: &mut Mux, pcr_pid: u16, start: u64, intervals: u64, gop: u64, fill: usize) { - for i in 0..intervals { - mux.packet(pcr_pid, Flags::pcr(start + i * 40 * MS)); - if gop != 0 && i % gop == 0 { - mux.packet(0x100, ACCESS); - } - for j in 0..fill { - mux.fill(if j % 2 == 0 { 0x100 } else { 0x101 }, 1); - } - } -} - /// Where in `data` the packet starting the first object sits, checking every packet from there on /// arrived verbatim. fn assert_suffix(data: &[u8], imported: &Imported) -> usize { @@ -674,7 +510,6 @@ async fn the_section_goes_with_the_importer() { #[tokio::test(start_paused = true)] async fn the_pcr_wrap_continues_the_timeline() { - const WRAP: u64 = (1 << 33) * 300; let mut mux = Mux::default(); program(&mut mux, 0x100); let start = WRAP - 2_000 * MS; diff --git a/rs/moq-mux/src/container/ts/release_test.rs b/rs/moq-mux/src/container/ts/release_test.rs index 4e99f00d9f5..c1d2493df75 100644 --- a/rs/moq-mux/src/container/ts/release_test.rs +++ b/rs/moq-mux/src/container/ts/release_test.rs @@ -1,14 +1,16 @@ //! Tests for [`Release`](super::Release). //! -//! Each imports a hardware encoder's capture with [`Passthrough`] and releases the track it -//! publishes, either replayed whole or republished object by object on a paused clock. +//! Each imports a hardware encoder's capture or a [fixture](super::fixture) with [`Passthrough`] +//! and releases the track it publishes, either replayed whole or republished object by object on +//! a paused clock, and grades the output with the [oracle](super::oracle). use std::time::Duration; use bytes::Bytes; use tokio::time::Instant; -use super::{Passthrough, Release}; +use super::oracle::{Admitted, Loss, Object}; +use super::{Passthrough, Release, fixture}; use crate::catalog::CatalogFormat; use crate::container::Frame; @@ -20,13 +22,8 @@ const RECORDING: Duration = Duration::from_secs(30); /// How long a drain waits for the next object before taking the release to have stalled. const STALL: Duration = RECORDING.saturating_mul(2); -/// One object as published. -#[derive(Clone, Debug, PartialEq)] -struct Object { - group: u64, - micros: u64, - payload: Bytes, -} +/// How far off its PCR time a release may write an object. +const TOLERANCE: Duration = Duration::from_millis(1); /// A capture imported whole, with what keeps its broadcast up. struct Imported { @@ -80,6 +77,17 @@ async fn import(data: &[u8]) -> Imported { /// each once `at` says it is due after the start and not before the one ahead of it, as a relay /// delivering them would. fn republish(objects: Vec, at: impl Fn(usize, &Object) -> Duration + Send + 'static) -> Republished { + republish_cut(objects, &[], at) +} + +/// [`republish`], aborting each group in `cut` once its last object in `objects` is out, as a +/// relay that evicts a group partway does. +fn republish_cut( + objects: Vec, + cut: &[u64], + at: impl Fn(usize, &Object) -> Duration + Send + 'static, +) -> Republished { + let cut = cut.to_vec(); let mut broadcast = moq_net::broadcast::Info::new().produce(); let mut catalog = crate::catalog::Producer::new(&mut broadcast, Default::default()).unwrap(); let track = broadcast @@ -99,8 +107,8 @@ fn republish(objects: Vec, at: impl Fn(usize, &Object) -> Duration + Sen due = due.max(at(i, &object)); tokio::time::sleep_until(start + due).await; if group.as_ref().map(|(sequence, _)| *sequence) != Some(object.group) { - if let Some((_, group)) = group.take() { - group.finish().unwrap(); + if let Some((sequence, group)) = group.take() { + end(sequence, group, &cut); } let info = moq_net::group::Info { sequence: object.group }; group = Some((object.group, track.create_group(info).unwrap())); @@ -111,8 +119,8 @@ fn republish(objects: Vec, at: impl Fn(usize, &Object) -> Duration + Sen }; frame.write_to(&mut group.as_mut().unwrap().1).unwrap(); } - if let Some((_, group)) = group { - group.finish().unwrap(); + if let Some((sequence, group)) = group { + end(sequence, group, &cut); } track.finish().unwrap(); std::future::pending::<()>().await; @@ -120,6 +128,14 @@ fn republish(objects: Vec, at: impl Fn(usize, &Object) -> Duration + Sen Republished { consumer, task } } +/// Finish `group`, or abort it as evicted if it is one of the `cut`. +fn end(sequence: u64, group: moq_net::group::Producer, cut: &[u64]) { + match cut.contains(&sequence) { + true => group.abort(moq_net::Error::Old).unwrap(), + false => group.finish().unwrap(), + } +} + struct Republished { consumer: moq_net::broadcast::Consumer, task: tokio::task::JoinHandle<()>, @@ -161,16 +177,9 @@ fn bytes<'a>(payloads: impl IntoIterator) -> Vec { .collect() } -/// How much later than the first object each one went out, less how much later its PCR time is. -fn lag(released: &[(Instant, Frame)]) -> Vec { - let (start, first) = &released[0]; - released - .iter() - .map(|(at, frame)| { - let out = at.duration_since(*start).as_micros() as i128; - out - (frame.timestamp.as_micros() as i128 - first.timestamp.as_micros() as i128) - }) - .collect() +/// Every byte `released` wrote, in order. +fn payloads(released: &[(Instant, Frame)]) -> Vec { + bytes(released.iter().map(|(_, frame)| &frame.payload)) } #[tokio::test(start_paused = true)] @@ -185,16 +194,9 @@ async fn a_capture_is_released_byte_identical_on_its_own_pcr() { .with_replay(); let (released, release) = drain(release).await; - let out = bytes(released.iter().map(|(_, frame)| &frame.payload)); - assert!( - out == bytes(imported.objects.iter().map(|object| &object.payload)), - "every published object goes out, in order" - ); - assert!(data.ends_with(&out), "the output is the input from the first group on"); + let admitted = Admitted::new(data, &imported.objects); + assert_eq!(admitted.grade(&released, TOLERANCE), Loss::default()); assert_eq!(release.dropped(), 0); - for (i, lag) in lag(&released).into_iter().enumerate() { - assert!(lag.abs() < 1_000, "object {i} goes out {lag} us off its PCR time"); - } } } @@ -276,17 +278,10 @@ async fn releases_fed_with_different_skew_write_the_same_bytes() { assert_eq!(steady_release.dropped(), 0); assert_eq!(skewed_release.dropped(), 0); - let payloads = |released: &[(Instant, Frame)]| bytes(released.iter().map(|(_, frame)| &frame.payload)); + let admitted = Admitted::new(KYRION, &objects); + assert_eq!(admitted.grade(&steady_out, TOLERANCE), Loss::default()); + assert_eq!(admitted.grade(&skewed_out, TOLERANCE), Loss::default()); assert!(payloads(&steady_out) == payloads(&skewed_out), "the same bytes go out"); - assert!( - payloads(&steady_out) == bytes(objects.iter().map(|object| &object.payload)), - "from the first group" - ); - for released in [&steady_out, &skewed_out] { - for (i, lag) in lag(released).into_iter().enumerate() { - assert!(lag.abs() < 1_000, "object {i} goes out {lag} us off its PCR time"); - } - } } #[tokio::test(start_paused = true)] @@ -311,36 +306,142 @@ async fn an_object_past_its_deadline_is_a_gap_in_that_release_only() { let (stalled_out, stalled_release) = stalled_task.await.unwrap(); assert_eq!(steady_release.dropped(), 0); - let dropped = stalled_release.dropped() as usize; - assert!(dropped > 0, "the stall makes objects late"); + let admitted = Admitted::new(KYRION, &objects); + assert_eq!(admitted.grade(&steady_out, TOLERANCE), Loss::default()); + + // The stalled release writes the steady one's objects less a run of the late ones, each + // counted, and the rest on the same clock as before the stall. + let loss = admitted.grade(&stalled_out, TOLERANCE); + assert_eq!(loss.first, 0); + assert!(!loss.missing.is_empty(), "the stall makes objects late"); assert_eq!( - stalled_out.len() + dropped, - steady_out.len(), + loss.missing.len() as u64, + stalled_release.dropped(), "every late object is counted" ); + assert!( + loss.missing.windows(2).all(|pair| pair[1] == pair[0] + 1), + "one run is missing: {:?}", + loss.missing + ); + assert!(payloads(&stalled_out) == admitted.expected(&loss)); +} - // The stalled release writes the steady one's objects less a run of the late ones. - let gap = steady_out +/// The published capture, republished at its PCR pace, less the objects `omit` picks; groups in +/// `cut` end aborted, as the path evicting them partway would. +async fn release_omitting(cut: &[u64], omit: impl Fn(usize, &Object) -> bool) -> (Loss, Release) { + let objects = import(KYRION).await.objects; + let first = objects[0].micros; + let delivered = objects .iter() - .zip(&stalled_out) - .position(|((_, steady), (_, stalled))| steady.payload != stalled.payload) - .expect("a gap"); - let frames = |released: &[(Instant, Frame)]| -> Vec<(u64, Bytes)> { - released - .iter() - .map(|(_, frame)| (frame.timestamp.as_micros() as u64, frame.payload.clone())) - .collect() - }; - let mut expected = frames(&steady_out); - expected.drain(gap..gap + dropped); - assert!(frames(&stalled_out) == expected, "only the late objects are missing"); + .enumerate() + .filter(|(i, object)| !omit(*i, object)) + .map(|(_, object)| object.clone()) + .collect(); + let republished = republish_cut(delivered, cut, move |_, object| { + Duration::from_micros(object.micros - first) + Duration::from_millis(40) + }); + let (released, release) = spawn_release(&republished).await.unwrap(); + let loss = Admitted::new(KYRION, &objects).grade(&released, TOLERANCE); + (loss, release) +} + +/// A group the path never delivers, as a relay that drops it whole: the rest go out on their +/// PCR time, leaving its time empty, and it is not late. +#[tokio::test(start_paused = true)] +async fn a_group_never_delivered_leaves_its_time_out() { + let objects = import(KYRION).await.objects; + let skipped = objects[objects.len() / 2].group; + let (loss, release) = release_omitting(&[], |_, object| object.group == skipped).await; + let expected: Vec = (0..objects.len()).filter(|&i| objects[i].group == skipped).collect(); + assert_eq!( + loss, + Loss { + first: 0, + missing: expected + } + ); + assert_eq!(release.dropped(), 0, "nothing arrived late"); +} - // The rest still go out on time: on the same clock as before the stall. - for (i, lag) in lag(&stalled_out).into_iter().enumerate() { - assert!(lag.abs() < 1_000, "object {i} goes out {lag} us off its PCR time"); +/// A group cut short loses the objects after the cut alone. +#[tokio::test(start_paused = true)] +async fn a_group_cut_short_loses_only_its_tail() { + let objects = import(KYRION).await.objects; + let cut = objects[objects.len() / 2].group; + let members: Vec = (0..objects.len()).filter(|&i| objects[i].group == cut).collect(); + assert!(members.len() > 2, "a group of several objects"); + let tail = members[members.len() / 2..].to_vec(); + let (loss, release) = release_omitting(&[cut], |i, _| tail.contains(&i)).await; + assert_eq!( + loss, + Loss { + first: 0, + missing: tail + } + ); + assert_eq!(release.dropped(), 0, "nothing arrived late"); +} + +/// What the captures don't carry goes out at its exact position too: null packets, tables, a PID +/// no table lists, adaptation stuffing, a PES split across objects, the clock's wrap, and an MPTS +/// whose programs keep clocks and random access points of their own. +#[tokio::test(start_paused = true)] +async fn fixtures_are_released_at_their_exact_positions() { + const GOP: u64 = 25; + let fixtures = [ + ( + "assorted", + fixture::assorted(fixture::WRAP - 2_000 * fixture::MS, 150, GOP), + ), + ("mpts", fixture::mpts(150, GOP)), + ]; + for (name, data) in fixtures { + let objects = import(&data).await.objects; + let groups = objects.last().unwrap().group - objects[0].group + 1; + assert!( + groups >= 5, + "{name}: {groups} groups, one per random access point of program 1" + ); + let admitted = Admitted::new(&data, &objects); + assert!( + admitted.prefix() < data.len() / 150 * GOP as usize, + "{name}: acquisition withholds {} bytes, more than a group", + admitted.prefix() + ); + + let first = objects[0].micros; + let skewed = republish(objects.clone(), move |i, object| { + Duration::from_micros(object.micros - first) + Duration::from_millis(40 + 30 * (i as u64 % 3)) + }); + let (released, release) = spawn_release(&skewed).await.unwrap(); + assert_eq!(admitted.grade(&released, TOLERANCE), Loss::default(), "{name}"); + assert_eq!(release.dropped(), 0, "{name}"); + + let pids = pids(&payloads(&released)); + for pid in [0x0000, 0x1fff] { + assert!(pids.contains(&pid), "{name}: the output carries PID {pid:#x}"); + } + if name == "assorted" { + assert!( + pids.contains(&0x0011) && pids.contains(&0x1abc), + "{name}: the SDT and the unlisted PID" + ); + let last = released.last().unwrap().1.timestamp.as_micros() as u64; + assert!(last > fixture::WRAP / 27, "{name}: the release crosses the wrap"); + } } } +/// Every PID `data`'s packets carry. +fn pids(data: &[u8]) -> std::collections::BTreeSet { + data.as_chunks::<188>() + .0 + .iter() + .map(|pkt| u16::from_be_bytes([pkt[1] & 0x1f, pkt[2]])) + .collect() +} + /// The MSF catalog never names the `m2ts` track, so a release reading it would wait forever. #[tokio::test(start_paused = true)] async fn an_msf_catalog_is_refused() { diff --git a/test/justfile b/test/justfile index 4064c44288f..040901ebb12 100644 --- a/test/justfile +++ b/test/justfile @@ -134,8 +134,14 @@ ts *args: python3 ./ts/pcr-timing.test.py python3 ./ts/open-gop.test.py python3 ./ts/holes.test.py + python3 ./ts/passthrough.test.py ./ts/run.sh "$@" +# Carry a hardware encoder's capture, which the T-STD model passes, whole through the round-trip. +[positional-arguments] +ts-passthrough-capture *args: + ./ts/run.sh --passthrough --source ../rs/moq-mux/src/container/ts/test_data/scte35/kyrion_dirtystart.ts "$@" + # Table-placement grader: acquisition, interleave, phase, drift and missing-table controls. ts-pair-controls: python3 ./ts/table-anchor.test.py diff --git a/test/ts/README.md b/test/ts/README.md index e9bd32da319..df35945431f 100644 --- a/test/ts/README.md +++ b/test/ts/README.md @@ -22,6 +22,8 @@ software profiles below; it does not certify a hardware IRD or every TS layout. against its source. - `holes.py` finds media missing from a generated clip's capture, from its timestamps against the source's. +- `passthrough.py` places every packet of an `export ts --passthrough` capture + at its source position and compares the compliance verdicts. ## Running @@ -43,6 +45,9 @@ just test ts --full # the same with two audio PIDs, filling its mult just test ts --fragment-pes # legal headers split across packets, with FFmpeg/TSDuck grading just test ts --delay 2s # pass the exporter's --delay just test ts --hrd --loss 1 # drop 1% of the relay's datagrams to the subscriber +just test ts --passthrough # carry the multiplex whole, grade it packet by packet +just test ts --passthrough --mpts # the same with two programs on their own clocks +just test ts-passthrough-capture # the same over an in-repo capture the T-STD model passes ``` `--fragment-pes` shifts generated audio/video PES bursts into their following @@ -587,6 +592,51 @@ out while they wait. CUBIC (`loss`) fared worse at 10 %: no output at all. With and PCR accuracy, though 1.56 s of video still missed the 1 s delay. The 10 % case belongs to the [BBR media study](/quest/m2/quic-bbr-natural-drain.md). +## Passthrough (`--passthrough`, `passthrough.py`) + +`--passthrough` publishes with `import ts --passthrough` and captures with +`export ts --passthrough`, so the capture should be the source's own packets. +`passthrough.py` grades it against the source alone: + +- The admitted interval is the source from the capture's first packet to the + end. What comes before it is the acquisition prefix, which the importer + withholds until its first group, plus whatever the export joined after; the + grader reports its size and does not count it as loss. +- Every captured packet must be the source packet at its exact position in that + interval, null packets, tables, unknown PIDs and adaptation bytes included. + A position is only claimed for a run of 16 matching packets, so a duplicated + null or table packet fails rather than passing as an identical later one. + Packets the capture skips are gaps, reported by position and PID. +- On a complete capture, every `compliance.py` check (TSDuck's structure, the + T-STD and system buffer models) must give the capture the verdict it gives + the admitted interval. The export carries whatever the source is, so a source + that fails a check must fail it the same way: the generated clip's AAC + overflows its T-STD buffer on its own, and the Kyrion capture CI also runs + passes. `decode.py` then compares the generated clip's decoded content. + +`--mpts` generates two programs with their own PCR PIDs and keyframes every 25 +and 40 frames, so the importer's groups, which open on program 1's random +access points, mostly open mid-GOP for program 2. The capture is still the +source in place: a group boundary promises no immediate decode for every +program, and passthrough neither inserts tables nor extracts a program. + +A gap fails the run, `--loss` included, since QUIC retransmits what the path +drops. To grade a capture from a path that loses content, run the grader with +`--loss-ok`: gaps are reported and the checks run on the capture alone, since a +gap can take part of a PES or the next table with it. + +```bash +./passthrough.py source.ts capture.ts [--loss-ok] +``` + +Release timing is the Rust tests' job +(`rs/moq-mux/src/container/ts/release_test.rs`, on a paused clock), with the +packet and schedule oracle in `oracle.rs` and the fixtures it cannot get from a +capture in `fixture.rs`. On a loaded host, `--passthrough --loss 5` left 77 % of +the packets missing in 30 gaps with one object counted late; the rest were +groups the relay aged out, the congestion ceiling described under +[Lossy path](#lossy-path---loss). + ## EIT fixtures No capture in this repository carries EIT (PID 0x0012), so nothing exercises the @@ -732,13 +782,14 @@ outcomes deterministically in Rust CI, without retries or implicit `--stitch`. [`.github/workflows/ts.yml`](../../.github/workflows/ts.yml) is independent of browser interop. Relevant mux, Hang, CLI, transport, harness and toolchain PRs run `just test ts-controls`, `just test ts-pair-controls`, the default and 2 Mb/s round trips, HRD, leak, full, headroom, -open-GOP, EIT, and T-STD controls. Each step runs even after another test fails. +open-GOP, passthrough (generated, Kyrion and MPTS), EIT, and T-STD controls. Each step runs even after another test fails. All recipes use the same pinned Nix FFmpeg and TSDuck locally and in CI. Nightly and manual runs also invoke `just test ts --pair`, -`just test ts --live --duration 120` and `just test ts --hrd --loss 1 --duration 120`. +`just test ts --live --duration 120`, `just test ts --hrd --loss 1 --duration 120` +and `just test ts --passthrough --loss 1 --duration 120`. The pair exercises late-joining subscribers; the live window distinguishes ongoing -clock drift from initial buffer filling; the lossy path proves T-STD and media +clock drift from initial buffer filling; the lossy paths prove T-STD and media continuity through QUIC retransmission. These are actual test invocations, not optional tools installed on a runner. diff --git a/test/ts/passthrough.py b/test/ts/passthrough.py new file mode 100644 index 00000000000..21f5777fdeb --- /dev/null +++ b/test/ts/passthrough.py @@ -0,0 +1,180 @@ +#!/usr/bin/env python3 +"""Grade an `export ts --passthrough` capture against the source `import ts --passthrough` read. + + ./passthrough.py source.ts capture.ts [--loss-ok] [--report-json report.json] + +The admitted interval is the source from the capture's first packet to the end: the importer +withholds what comes before its first group while it acquires (the prefix), and the export +opens on whichever group it joins. Every captured packet must be the source packet at its exact +position in that interval, in order: null packets, tables, unknown PIDs and adaptation bytes +included, nothing rewritten or duplicated. Where the capture skips source packets, that is a +gap: objects the export dropped late or the path never delivered. + +A position is only claimed for a run of RUN packets that matches the source there, so a +duplicated null or table packet cannot pass as the identical one a gap later. + +On a complete path (no gap, nothing missing at the end) the capture is the admitted interval +byte for byte, and every compliance.py check, TSDuck's structure and the T-STD and system +buffer models included, must give it the verdict it gives that interval. The export carries +whatever the source is, so it is graded against the source, not against an absolute bar. Under +`--loss-ok` gaps are reported rather than failed, and the checks report on the capture alone: +a gap can take part of a PES or the next table with it, so the bytes being the source's says +nothing about whether the rest decodes. + +Exit status is 0 when the capture passes, 1 otherwise. +""" + +import argparse +import json +import sys +import tempfile +from collections import Counter, defaultdict +from dataclasses import dataclass, field +from pathlib import Path + +PACKET = 188 +# Matching packets a position needs before it is claimed. +RUN = 16 + + +@dataclass +class Placement: + """Where a capture's packets sit in its source.""" + + start: int # source packet the capture opens on + total: int # source packets + gaps: list[tuple[int, int]] = field(default_factory=list) # (source packet, length) + tail: int = 0 # source packets after the capture's last one + missing_pids: Counter = field(default_factory=Counter) + + @property + def complete(self) -> bool: + return not self.gaps and not self.tail + + +class Mismatch(Exception): + """A captured packet that is not the source's at any position after the one before it.""" + + +def packets(data: bytes) -> list[bytes]: + if len(data) % PACKET: + raise Mismatch(f"{len(data)} bytes is not whole {PACKET}-byte packets") + return [data[i : i + PACKET] for i in range(0, len(data), PACKET)] + + +def pid(pkt: bytes) -> int: + return (pkt[1] & 0x1F) << 8 | pkt[2] + + +def place(source: list[bytes], capture: list[bytes]) -> Placement: + """Map every captured packet onto its source position, or raise Mismatch.""" + if not capture: + raise Mismatch("the capture is empty") + positions = defaultdict(list) + for i, pkt in enumerate(source): + positions[pkt].append(i) + + def runs(i: int, after: int) -> list[int]: + n = min(RUN, len(capture) - i) + return [j for j in positions.get(capture[i], ()) if j >= after and source[j : j + n] == capture[i : i + n]] + + starts = runs(0, 0) + if not starts: + raise Mismatch("the capture's first packets are nowhere in the source") + if len(starts) > 1: + raise Mismatch(f"the capture's first {RUN} packets match the source at packets {starts[:4]}: ambiguous") + placement = Placement(start=starts[0], total=len(source)) + + j = placement.start + for i, pkt in enumerate(capture): + if j < len(source) and source[j] == pkt: + j += 1 + continue + found = runs(i, j) + if not found: + raise Mismatch( + f"captured packet {i} (PID {pid(pkt):#x}) is not the source's at or after packet {j}: " + "rewritten, duplicated or reordered" + ) + placement.gaps.append((j, found[0] - j)) + placement.missing_pids.update(pid(p) for p in source[j : found[0]]) + j = found[0] + 1 + placement.tail = len(source) - j + placement.missing_pids.update(pid(p) for p in source[j:]) + return placement + + +def verdicts(path: Path) -> dict[str, list[str]]: + """Every compliance.py check's status and detail for `path`.""" + import compliance + + return {c.name: [c.status.value, c.detail] for c in compliance.analyze(str(path))} + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("source", type=Path) + parser.add_argument("capture", type=Path) + parser.add_argument("--loss-ok", action="store_true", help="report gaps instead of failing on them") + parser.add_argument("--report-json", type=Path) + args = parser.parse_args() + + source_data = args.source.read_bytes() + capture_data = args.capture.read_bytes() + try: + placement = place(packets(source_data), packets(capture_data)) + except Mismatch as err: + print(f"passthrough: FAIL: {err}", file=sys.stderr) + return 1 + + lost = sum(n for _, n in placement.gaps) + placement.tail + admitted = placement.total - placement.start + print("### passthrough packet positions") + print(f" prefix: {placement.start} source packets before the capture's first ({placement.start * PACKET} bytes)") + print(f" admitted: {admitted} packets, {admitted - lost} captured at their exact positions") + print(f" gaps: {len(placement.gaps)}, {lost} packets missing ({placement.tail} at the end)") + if lost: + print(" missing by PID: " + ", ".join(f"{p:#x}={n}" for p, n in sorted(placement.missing_pids.items()))) + + report = { + "prefix_packets": placement.start, + "admitted_packets": admitted, + "gaps": placement.gaps, + "tail_packets": placement.tail, + "missing_by_pid": {f"{p:#x}": n for p, n in placement.missing_pids.items()}, + } + code = 0 + if placement.complete: + with tempfile.NamedTemporaryFile(suffix=".ts") as interval: + interval.write(source_data[placement.start * PACKET :]) + interval.flush() + expected = verdicts(Path(interval.name)) + actual = verdicts(args.capture) + report["compliance"] = {"admitted": expected, "capture": actual} + print("### compliance.py, capture against the admitted interval") + for name in sorted(expected.keys() | actual.keys()): + same = actual.get(name) == expected.get(name) + status = (actual.get(name) or ["-"])[0] + print(f" {'same' if same else 'DIFF'} {name}: {status} {(actual.get(name) or ['', ''])[1]}") + if not same: + print(f"passthrough: FAIL: {name} grades the capture {actual.get(name)}, its source {expected.get(name)}", + file=sys.stderr) + code = 1 + else: + report["compliance"] = {"capture": verdicts(args.capture)} + print("### compliance.py on the capture (report only: it has gaps)") + for name, (status, detail) in report["compliance"]["capture"].items(): + print(f" {name}: {status} {detail}") + if not args.loss_ok: + print("passthrough: FAIL: the capture is missing source packets; --loss-ok reports gaps instead", file=sys.stderr) + code = 1 + + if args.report_json: + args.report_json.write_text(json.dumps(report, indent=2)) + if code == 0: + print("passthrough: PASS" + (" (with gaps)" if lost else "")) + return code + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/test/ts/passthrough.test.py b/test/ts/passthrough.test.py new file mode 100644 index 00000000000..22582dd89a5 --- /dev/null +++ b/test/ts/passthrough.test.py @@ -0,0 +1,71 @@ +import importlib.util +import pathlib +import unittest + +spec = importlib.util.spec_from_file_location("passthrough", pathlib.Path(__file__).with_name("passthrough.py")) +passthrough = importlib.util.module_from_spec(spec) +spec.loader.exec_module(passthrough) + +NULL = bytes([0x47, 0x1F, 0xFF, 0x10]) + bytes(184) + + +def packet(pid, n): + """A packet on `pid` whose payload says which one it is.""" + return bytes([0x47, pid >> 8, pid & 0xFF, 0x10 | n & 0x0F]) + n.to_bytes(4, "big") + bytes(180) + + +# A table, a run of media with a null between each, and a PID no table lists, repeated. +SOURCE = [] +for n in range(200): + SOURCE.append(packet(0x1000 if n % 50 == 0 else 0x100, n)) + SOURCE.append(NULL) + if n % 7 == 0: + SOURCE.append(packet(0x1ABC, n)) + + +class Place(unittest.TestCase): + def test_a_suffix_is_complete(self): + placement = passthrough.place(SOURCE, SOURCE[100:]) + self.assertEqual((placement.start, placement.gaps, placement.tail), (100, [], 0)) + self.assertTrue(placement.complete) + + def test_a_dropped_run_is_a_gap_at_its_position(self): + capture = SOURCE[10:60] + SOURCE[90:] + placement = passthrough.place(SOURCE, capture) + self.assertEqual(placement.gaps, [(60, 30)]) + self.assertEqual(placement.missing_pids[0x1FFF], SOURCE[60:90].count(NULL)) + + def test_a_missing_tail_is_counted(self): + placement = passthrough.place(SOURCE, SOURCE[:-40]) + self.assertEqual((placement.gaps, placement.tail), ([], 40)) + self.assertFalse(placement.complete) + + def test_a_rewritten_packet_fails(self): + capture = list(SOURCE) + capture[50] = capture[50][:100] + b"\xff" + capture[50][101:] + with self.assertRaises(passthrough.Mismatch): + passthrough.place(SOURCE, capture) + + def test_a_duplicated_run_fails(self): + with self.assertRaises(passthrough.Mismatch): + passthrough.place(SOURCE, SOURCE[:80] + SOURCE[60:80] + SOURCE[80:]) + + def test_a_duplicated_null_does_not_pass_as_a_later_one(self): + # Every other packet is an identical null, so the duplicate matches the source a + # packet on; only the run after it shows it is out of place. + with self.assertRaises(passthrough.Mismatch): + passthrough.place(SOURCE, SOURCE[:41] + [NULL] + SOURCE[41:]) + + def test_reordered_packets_fail(self): + capture = list(SOURCE) + capture[30], capture[32] = capture[32], capture[30] + with self.assertRaises(passthrough.Mismatch): + passthrough.place(SOURCE, capture) + + def test_a_capture_from_elsewhere_fails(self): + with self.assertRaises(passthrough.Mismatch): + passthrough.place(SOURCE, [packet(0x200, n) for n in range(20)]) + + +if __name__ == "__main__": + unittest.main() diff --git a/test/ts/run.sh b/test/ts/run.sh index 6c6298cef69..cd77c8497c0 100755 --- a/test/ts/run.sh +++ b/test/ts/run.sh @@ -26,6 +26,8 @@ # ./run.sh --fragment-pes # split generated clear PES headers across packets # ./run.sh --delay 2s # pass the exporter's --delay # ./run.sh --loss 10 # drop 10% of the relay's datagrams to the subscriber (moq-shaper) +# ./run.sh --passthrough # carry the multiplex whole (`import/export ts --passthrough`) +# ./run.sh --passthrough --mpts # the same with two programs whose recovery points rarely line up # `--live` swaps the analyzer, not the rig. compliance.py grades a captured file # on the stream's own PCR clock, which is the right basis for the IRD model it @@ -81,6 +83,8 @@ LEAK="" # publish video with no HRD at its level's leak, as a full-rate FULL="" # the same with audio, in a multiplex the source fills with no nulls FRAGMENT_PES="" # use following null slots for fragmented PES headers LOSS="" # percent of relay -> subscriber datagrams dropped by moq-shaper +PASSTHROUGH="" # carry the multiplex whole and grade the capture packet by packet against the source +MPTS="" # publish two programs, which only --passthrough carries whole EXPORT=() # extra `export ts` flags (--delay) # How far into the run the second subscriber joins. A late join is the point: two # exporters started together can share a cadence by starting together, which is @@ -173,6 +177,14 @@ while [[ $# -gt 0 ]]; do LOSS="$2" shift 2 ;; + --passthrough) + PASSTHROUGH=1 + shift + ;; + --mpts) + MPTS=1 + shift + ;; *) PASSTHRU+=("$1") shift @@ -255,6 +267,22 @@ if [[ -n "$LOSS" ]]; then fi fi +# The capture is the source's own packets, graded against it by passthrough.py; the arms that +# grade a second capture or the live pipe grade the demultiplexed export's choices. +if [[ -n "$PASSTHROUGH" && -n "$ANALYZE_ONLY$PAIR$LIVE" ]]; then + echo "error: --passthrough cannot be combined with --analyze-only, --pair, or --live" >&2 + exit 1 +fi +if [[ -n "$MPTS" && (-z "$PASSTHROUGH" || -n "$SOURCE$HRD$HEADROOM$LEAK$FULL$OPEN_GOP$FRAGMENT_PES") ]]; then + echo "error: --mpts generates its own clip and needs --passthrough, the mode that carries a multiplex whole" >&2 + exit 1 +fi +IMPORT=(import ts) +if [[ -n "$PASSTHROUGH" ]]; then + IMPORT+=(--passthrough) + EXPORT+=(--passthrough) +fi + URL="" # set once a port is reserved, below have() { command -v "$1" >/dev/null 2>&1; } @@ -370,6 +398,20 @@ elif [[ -n "$HRD$HEADROOM" ]]; then -c:v libx264 -profile:v high -level 4.0 -preset veryfast -pix_fmt yuv420p \ -x264-params "keyint=25:min-keyint=25:scenecut=0:nal-hrd=cbr" -b:v 9M -maxrate 9M -bufsize 9M \ -f mpegts -muxrate "$BITRATE" -pcr_period 20 -pes_payload_size 0 "$SRC_TS" +elif [[ -n "$MPTS" ]]; then + echo "### generating ~${DURATION}s two-program clip with ffmpeg" + # Two services in one multiplex, each with its own PCR PID, their keyframes every 25 and + # 40 frames: they coincide every 8 s, so most of the importer's groups, which open on + # program 1's random access points, open mid-GOP for program 2. + ffmpeg -y -hide_banner -loglevel error \ + -f lavfi -i "testsrc=size=640x360:rate=25" -f lavfi -i "sine=frequency=1000:sample_rate=48000" \ + -f lavfi -i "testsrc2=size=640x360:rate=25" -f lavfi -i "sine=frequency=500:sample_rate=48000" \ + -t "$DURATION" -map 0:v -map 1:a -map 2:v -map 3:a \ + -c:v libx264 -profile:v high -preset veryfast -pix_fmt yuv420p -b:v 2M \ + -x264-params:v:0 "keyint=25:min-keyint=25:scenecut=0" -x264-params:v:1 "keyint=40:min-keyint=40:scenecut=0" \ + -c:a aac -b:a 128k \ + -program program_num=1:st=0:st=1 -program program_num=2:st=2:st=3 \ + -f mpegts -muxrate "$BITRATE" -pcr_period 20 -pes_payload_size 0 "$SRC_TS" elif [[ -n "$LEAK" ]]; then echo "### generating ~${DURATION}s 1080p clip with no HRD at its level's 24 Mb/s leak with ffmpeg" # A full-rate feed's shape: with no HRD, level 4.0's leak from MB into EB (Rbx, 24 Mb/s) @@ -591,8 +633,8 @@ publish() { # shellcheck disable=SC2016 # $1..$5 are the child bash -c positionals, not ours. timeout -k 3 $((DURATION + 20 + 30)) bash -o pipefail -c ' tsp -I file "$1" -P regulate --pcr-synchronous --wait-min 5 | - "$2" --connect "$3" --connect-version "$5" --broadcast "$4" import ts - ' _ "$SRC_TS" "$MOQ" "$URL" "$BROADCAST" "$VERSION" + "$2" --connect "$3" --connect-version "$5" --broadcast "$4" "${@:6}" + ' _ "$SRC_TS" "$MOQ" "$URL" "$BROADCAST" "$VERSION" "${IMPORT[@]}" } harness_spawn pub "$HARNESS_RUN/pub.log" publish PUB_PID="$HARNESS_PID" @@ -629,8 +671,8 @@ stop_shaper() { echo echo "### path (moq-shaper, seed $SEED)" tail -n 1 "$HARNESS_RUN/shaper.log" | sed 's/^shaper: / /' - sed 's/\x1b\[[0-9;]*m//g' "$HARNESS_RUN/sub.log" | grep 'TS export release clock' | tail -n 1 | - grep -o 'dropped=[0-9]* trimmed=[0-9]* gaps=[0-9]*' | sed 's/^/ export: /' || true + sed 's/\x1b\[[0-9;]*m//g' "$HARNESS_RUN/sub.log" | grep -E 'TS (export|passthrough) release clock' | tail -n 1 | + grep -oE 'dropped=[0-9]*( trimmed=[0-9]* gaps=[0-9]*)?' | sed 's/^/ export: /' || true } # ── live: the grader owns the verdict ─────────────────────────────────────── @@ -713,6 +755,30 @@ fi echo "### captured $(wc -c <"$SUB_TS" | tr -d ' ') bytes -> analyzing" +# ── passthrough: the source is the oracle ─────────────────────────────────── +# Every captured packet must be the source's at its exact position from the first one on, and +# compliance.py must grade the capture as it grades that interval of the source, whatever the +# source's own verdict. QUIC retransmits what --loss drops, so a gap fails here as it does under +# holes.py; passthrough.py says whether packets went missing or were rewritten. +if [[ -n "$PASSTHROUGH" ]]; then + echo + if ! python3 "$DIR/passthrough.py" "$SRC_TS" "$SUB_TS" --report-json "$HARNESS_RUN/passthrough.json"; then + echo >&2 + echo "error: the capture is not the source's packets in place; the exporter reported:" >&2 + sed 's/\x1b\[[0-9;]*m//g' "$HARNESS_RUN/sub.log" | + grep -E 'TS passthrough release clock|media skipped upstream|missed its deadline|group evicted' | + tail -n 20 | sed 's/^/ sub: /' >&2 || true + exit 1 + fi + echo + if [[ -z "$SOURCE$OPEN_GOP$HRD$HEADROOM$LEAK$FULL$MPTS" ]]; then + python3 "$DIR/decode.py" "$SRC_TS" "$SUB_TS" --output "$HARNESS_RUN/decode" || exit 1 + else + echo "decoded-content comparison: not covered for this profile" + fi + exit 0 +fi + # The initial decoded-content profile is the generated closed-GOP H.264/AAC # pair. Other arms retain their specific structural/model oracles until their # acquisition and decoder-priming contracts are covered by fixtures.