diff --git a/quest/m1/README.md b/quest/m1/README.md index ea0f0389b0a..1d56cea17bc 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -81,6 +81,7 @@ folded into Dropped sources. - [Lazy discovery](/quest/m1/lazy-discovery/README.md) - a `consume` session requests announcements only for prefixes the origin is watching, in JS then Rust; `follow`, `broadcasts`, and the `discovery` option go away - [A spinning loop fails a sim test](/quest/m1/spinning-loops.md) - a sim test names any loop that holds a task poll too long, and each one yields through a budget - [Kotlin wrapper POMs](/quest/m1/kt-ffi-pom.md) - Maven builds of `dev.moq:moq` resolve a published moq-ffi instead of the missing `0.0.0-dev` +- [Plan: redundant TS alignment](/quest/m1/plan-ts-alignment.md) - settle shared source coordinates and distinguish TS identity from coordinated RTP recovery - [Same-epoch importers](/quest/m1/hop-aligned-import.md) - importers sharing one `--epoch` and fed one stream publish identical groups and timestamps, so failover between a redundant pair survives - [moq.sh deploys from CI](/quest/m1/moq-sh-deploy.md) - the first `release` run of the moq.sh workflow deploys with the Workers Editor token - [Plan: untimed verbatim PES](/quest/m1/plan-ts-pes-untimed.md) - decide how a verbatim TS track carries a PES that has no PTS, then write the implementation quest @@ -162,7 +163,8 @@ folded into Dropped sources. - [TTML caption import](/quest/m1/captions-ttml.md) - fMP4 `stpp` tracks within a supported TTML/IMSC profile import as `ttml` renditions on the shared clock instead of being skipped - [fMP4 WebVTT ctim and vtta](/quest/m1/wvtt-ctim-vtta.md) - `wvtt` samples with `ctim` cue times or `vtta` comments import instead of failing - [Encoder colour](/quest/m1/color-model.md) - every moq-video encode path signals the colour its output actually has, or refuses instead of mislabelling -- [T-STD TS export](/quest/m1/tstd/README.md) - `moq export ts` is a proper remux that passes the T-STD buffer model, starting with a fixed `--delay` +- [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide +- [T-STD TS export](/quest/m1/tstd/README.md) - `moq export ts` is a proper remux that passes the supported T-STD buffer models, starting with a fixed `--delay` - [ATSC AC-3](/quest/m1/ts-atsc-ac3.md) - `export ts` carries 48 kHz ATSC AC-3 at every A/52 rate up to 640 kb/s instead of aborting from 384 kb/s up - [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the Rust container consumer reports a frame after a subscribe or discontinuity as non-continuous, like JS, for the tune-in and warmup trims - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - a viewer joining at a recovery point drops the leading pictures it cannot decode; continuous viewers keep them diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index 5bc8469df0f..75c3654ab51 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -12,6 +12,13 @@ failover `export ts` sees a timestamp rewind and exits (#4354). ## Plan +The 2026-10-11 audit adds a planning prerequisite for the shared source +coordinate. The group-number and wall-anchor proposals below are provisional +until it settles how the input supplies a common anchor and wrap era. A +shared epoch or raw PTS/PCR value alone does not supply that mapping. Also +resolve raw passthrough explicitly: today's `--epoch` accepts whole MPTS +there, whereas the semantic importer scope below says one program. + Decided: every publisher of one path and epoch MUST publish the same broadcasts and tracks, since routes with the same epoch resume each other's subscriptions. A redundant pair is keyed by a shared explicit epoch (decided @@ -61,6 +68,10 @@ issues' 1+1 setup (one relay, two `import ts` sharing one `--epoch`, two - [#4352](https://github.com/moq-dev/moq/issues/4352) - close this issue when the quest finishes - [#4354](https://github.com/moq-dev/moq/issues/4354) - close this issue when the quest finishes +## Required + +- [Plan: redundant TS alignment](/quest/m1/plan-ts-alignment.md) - settle the source-to-wall anchor, wrap era and raw group coordinate that a shared epoch alone does not provide + ## Related - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - a redundant pair shares one epoch diff --git a/quest/m1/open-gop-leading-pictures.md b/quest/m1/open-gop-leading-pictures.md index e6fb70d2bee..be7c8d0d01d 100644 --- a/quest/m1/open-gop-leading-pictures.md +++ b/quest/m1/open-gop-leading-pictures.md @@ -1,10 +1,10 @@ -# [M] Open-GOP leading pictures are dropped at tune-in only +# [M] Open-GOP recovery drops orphaned leading pictures after each delivery break ## Goal -A viewer joining an open-GOP broadcast at a recovery point never hands the -decoder a leading picture whose references it does not have, while a viewer -already playing keeps every frame. The rule is the same for H.264 +A viewer joining or resuming an open-GOP broadcast after a non-continuous +transition never hands the decoder a leading picture whose references it +does not have. Continuous groups keep every frame. The rule is the same for H.264 recovery-point keyframes with `recovery_frame_cnt = 0` (the broadcast contribution case, and what the reference capture carries) and H.265 CRA pictures. Gradual recovery (`recovery_frame_cnt > 0`) is out of scope: unsafe pictures @@ -56,13 +56,17 @@ decode, and the JS test should drive the software decoder. export still sends a join's orphaned leading pictures, so 3 of 500 frames on the open-GOP fixture decode after they present (`dts-before-pts`). Trim them at tune-in from the same signal, on the - export's first group only, and make `just test ts --open-gop` pass under + first group after each non-continuous transition, and make + `just test ts --open-gop` pass under `--strict`. Decided in the 2026-10-05 audit: the grader changes with it. `test/ts/open-gop.py`'s decode-order check (a contiguous run of source access units) and leading-pictures check, and the `test/ts/README.md` text that says the round-trip must hand every leading picture on, both expect - every picture today; rewrite them to expect the first group's orphaned - leading pictures trimmed and every later group's kept. Rejected: dropping + every picture today; rewrite them to expect orphaned leading pictures + trimmed after each delivery break and every continuous group's kept. + The 2026-10-11 audit applies the same recovery rule to TS as to the + playback paths: the previous first-group-only wording missed later skips. + Rejected: dropping this bullet and keeping the grader. - Tests: a synthetic group with a keyframe followed by two earlier-stamped deltas is trimmed on the first group and kept on the second; and a viewer diff --git a/quest/m1/plan-ts-alignment.md b/quest/m1/plan-ts-alignment.md new file mode 100644 index 00000000000..7a53c2dbd61 --- /dev/null +++ b/quest/m1/plan-ts-alignment.md @@ -0,0 +1,46 @@ +# [S] Plan: shared coordinates for redundant TS publishers and exporters + +## Goal + +Settle what shared information makes redundant TS publishers and exporters +identify the same content and schedule. Rewrite the implementation quests +around that contract before promising failover or ST 2022-7 compatibility. + +## Plan + +The 2026-10-11 audit found two missing prerequisites: + +- Same epoch identity does not establish a source PCR/PTS-to-wall mapping, + a 33-bit timestamp wrap era, or a common raw-packet position. Importers + starting at different offsets cannot infer these from the UUID alone. + `catalog::Timebase::place` applies a supplied mapping; it does not discover + one. Raw fallback's timeout cuts also depend on acquisition history, even + though the CLI currently accepts a shared `--epoch` there. +- Identical TS packets are insufficient for ST 2022-7, which requires the + matching RTP packets, including headers. Complementary losses on redundant + paths are a reason to merge them; requiring the two legs to drop the same + content defeats that benefit. + +Present the maintainer with the actual shared-coordinate choices: an +explicit common source anchor and era, a common upstream packetizer, or an +honestly narrowed importer contract. Include what each can prove when the +standby starts after a timestamp wrap, a clock break, or a fallback group cut. +Do not derive a media clock from wall arrival and call it deterministic. + +For egress, separate deterministic TS slot/counter identity for common +content from coordinated RTP packetization, sequence/timestamp/SSRC identity +and any receiver merge. Decide the intended scope and API before implementing +`--sync`. NTP-synchronized hosts alone do not supply the missing source map. + +Produce focused implementation quests and explicit refusals for unsupported +shared-epoch modes. Their automated tests start peers at different source +offsets, cross wraps, vary delivery skew, and introduce complementary loss; +compare common content in its shared coordinate rather than whole files +whose delivered content differs. Actual ST 2022-7 claims require RTP-level +tests against the [standard](https://pub.smpte.org/latest/st2022-7/st2022-7-2019.pdf). + +## Related + +- [Same-epoch importers](/quest/m1/hop-aligned-import.md) - currently assumes an input-derived wall anchor is available +- [Deterministic TS legs](/quest/m2/ts-hitless.md) - TS identity and RTP recovery need separate acceptance evidence +- [TS passthrough export](/quest/m1/ts-passthrough-export.md) - unchanged packets do not establish identical groups from independent starts diff --git a/quest/m1/plan-ts-pes-untimed.md b/quest/m1/plan-ts-pes-untimed.md index 70d698f12fb..4f05aec15fd 100644 --- a/quest/m1/plan-ts-pes-untimed.md +++ b/quest/m1/plan-ts-pes-untimed.md @@ -1,11 +1,12 @@ -# [S] Plan: untimed verbatim PES +# [M] Plan: private PES timing and header fidelity ## Goal Decide how a verbatim MPEG-TS track carries a PES that has no PTS without -inventing a time, from import through export. The usual case is asynchronous -private data such as KLV. The output is an implementation quest, or a -recorded reason to keep today's behaviour. +inventing a presentation time, from import through export, and which PES +header semantics it retains. The usual case is asynchronous private data +such as KLV. Produce focused implementation quests with explicit supported +profiles and refusal rules. ## Plan @@ -35,5 +36,26 @@ the decision covers: The maintainer decides the carriage, because it touches the catalog and container contract. -Test plan for the implementation quest: importer to encoded track to -exporter, for a PES without a PTS and for one with a real PTS of 0. +The 2026-10-11 audit expands the decision to avoid settling timestamps in +isolation. A source placement time used for mux scheduling is distinct from +optional PTS and DTS. Today's private-PES track retains payload, `stream_id`, +and present PTS as the frame timestamp, but not the original DTS or other +PES-header fields. The parser skips ESCR, ES rate, trick mode, copy information, CRC and extension +fields; export synthesizes a generic PTS header and cannot reproduce all +special stream-ID header forms. A track called verbatim must say which bytes +or semantics that means. Unknown stream types also need to survive export or +be refused at import, not fail later through an enum conversion. + +Settle per-PES timing presence, scheduling of asynchronous data alongside +advancing media, header preservation versus normalization, and the legacy +container migration together. The exporter currently drops non-video frames +before the initial video time; demonstrate that permitted untimed/private +content is not lost through that rule. Keep the catalog/container decision +separate from raw whole-TS fallback, whose packets already contain the headers. + +Automated CI tests for the implementation quests: importer to encoded track +to exporter for missing PTS versus real PTS 0, distinct PTS/DTS, asynchronous +private data before and between media, optional headers, and special stream +IDs. Fixtures assert either retained semantics or the precise supported-profile +refusal, using TSDuck/FFmpeg where applicable. Update Rust, JS, the MPEG-TS +draft and the guide for any catalog/container wire change. diff --git a/quest/m1/ts-passthrough-export.md b/quest/m1/ts-passthrough-export.md index 098caf4f6cc..a69e43db5fe 100644 --- a/quest/m1/ts-passthrough-export.md +++ b/quest/m1/ts-passthrough-export.md @@ -6,7 +6,9 @@ `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, so it is exactly as T-STD-conformant as the source. +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 @@ -14,6 +16,21 @@ There is no JS player for it. 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, @@ -36,12 +53,23 @@ passthrough quest on #5003, whose import half it completes: a coordinated RTP egress. - Rust only. -Test: an export of a broadcast capture is byte-identical to the input from the -first released group, and the strict T-STD check gives the same verdict on -output and input. Two exporters fed the same objects with different arrival +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 time. Rerun the #4613 netem rig (10% loss, 120 s) against it. +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. @@ -50,5 +78,8 @@ Public API: a new export mode; nothing existing breaks. ## Related -- [TS hitless](/quest/m2/ts-hitless.md) - the demultiplexed lane's 2022-7 legs and the `--sync` anchor +- [Deterministic TS legs](/quest/m2/ts-hitless.md) - common packet identity and the proposed `--sync` anchor - [T-STD TS export](/quest/m1/tstd/README.md) - the jitter buffer and clock recovery this release shares +- [TS validation](/quest/m1/ts-reliability/validation.md) - shared automatic graders and controls +- [Loss and recovery](/quest/m1/ts-reliability/recovery.md) - actual missing content and reacquisition proof +- [Redundant alignment](/quest/m1/plan-ts-alignment.md) - identical common objects do not prove independent importers publish identical groups diff --git a/quest/m1/ts-reliability/README.md b/quest/m1/ts-reliability/README.md new file mode 100644 index 00000000000..ac20be15b2d --- /dev/null +++ b/quest/m1/ts-reliability/README.md @@ -0,0 +1,70 @@ +# TS fidelity and recovery + +## Goal + +The two TS modes have explicit, software-validated contracts under clean +delivery, late join, and lost MoQ content. A dedicated guide explains which +mode to choose, supported profiles, acquisition, loss, and the automated +evidence behind each claim. + +## Plan + +Decided in the 2026-10-11 TS audit: + +- TS to Hang to TS is the semantic mode. Remove packetization and stuffing; + retain the supported source semantics through media tracks and catalog + extensions. Hang's core stays container-neutral. Byte identity is not its + contract. +- TS to MoQ to TS is the packet-preserving fallback. Keep an SPTS or an entire + MPTS unchanged. Per-program tracks mean separately supplied SPTS inputs + in separate raw broadcasts under the existing catalog contract, + not extraction from an MPTS. Reject per-PID splitting and reversible packet + scatter for this lane: both add reconstruction complexity to the fallback. +- Loss in the fallback emits unchanged surviving packets on their source + schedule and reports gaps. Never silently repair continuity counters, + insert tables or stuffing, or compress the missing interval. Exact bytes + do not imply successful decoding or T-STD conformance after loss. +- Start with explicit software-validated profiles and expand with fixtures. + Hardware receivers and commercial qualification are useful additional + evidence, not prerequisites for repeatable CI. Do not claim universal + broadcast compliance from the current subset of the buffer model. +- Every TS validation, including TSDuck and FFmpeg, is an automated test + with assertions and a CI invocation. One-off analysis is diagnostic + evidence, not completion. Long real-time tests may run nightly; short + deterministic checks belong on relevant PRs. + +The existing raw importer admits an aligned 188-byte suffix after acquisition; +it does not currently retain every byte supplied before that point. The guide +must distinguish full-input identity from identity over the admitted interval, +and distinguish a MoQ group boundary from a decoder acquisition point. RAI, +periodic cuts, and an intact object alone do not ensure available PAT/PMT, +codec configuration, clock context, or references for every MPTS program. + +The README owns the guide and the final two-mode integration proof. Reuse the +children's fixtures and CI recipes, including their known-bad controls. Publish +a coverage table linking each supported profile and loss guarantee to its +test; unsupported or unmeasured cells stay explicit. Keep CLI instructions +and the MPEG-TS draft consistent in each feature change. + +The planning children settle catalog and clock contracts before production +changes. Their output adds independently completable implementation quests to +this line; an audit finding is not authorization to guess a public API. +PMT fragmentation (#5220) and initial mux-rate measurement (#5287) have +landed; PSI runs, decoder-time admission, and catalog linger remain with +their current quests. + +## Required + +- [Automated TS validation](/quest/m1/ts-reliability/validation.md) - software decode, structure, timing, and controls run in CI +- [Bounded PES assembly](/quest/m1/ts-reliability/pes.md) - split headers work and damaged input cannot grow staging indefinitely +- [Plan: semantic fidelity](/quest/m1/ts-reliability/fidelity.md) - explicit profiles and PMT lifecycle contracts produce implementation quests +- [Plan: PES timing and headers](/quest/m1/plan-ts-pes-untimed.md) - private PES semantics have a settled carriage and placement contract +- [Loss and recovery tests](/quest/m1/ts-reliability/recovery.md) - actual MoQ omissions exercise reacquisition and unaffected tracks +- [T-STD TS export](/quest/m1/tstd/README.md) - the semantic mux schedules the content it admits within its supported buffer models +- [TS passthrough export](/quest/m1/ts-passthrough-export.md) - unchanged surviving packets keep their original schedule + +## Related + +- [Plan: redundant TS alignment](/quest/m1/plan-ts-alignment.md) - shared identity requires a shared source coordinate, and TS identity alone is not ST 2022-7 +- [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 diff --git a/quest/m1/ts-reliability/fidelity.md b/quest/m1/ts-reliability/fidelity.md new file mode 100644 index 00000000000..edb6f033421 --- /dev/null +++ b/quest/m1/ts-reliability/fidelity.md @@ -0,0 +1,57 @@ +# [M] Plan: explicit semantic TS profiles and live table changes + +## Goal + +Turn the semantic-lane audit into explicit supported profiles and focused +implementation quests. Each accepted mechanism is preserved, intentionally +normalized with a documented meaning, or refused. Nothing advertised as +supported disappears silently. + +## Plan + +Decided 2026-10-11: software-validated profiles first, then incremental +coverage. Broad MPEG-2/ATSC/private-data support is not a prerequisite for +shipping an honest narrower profile. The raw fallback stays an explicit +mode, not an automatic mid-stream switch of the catalog contract. + +Audit findings to reproduce and scope: + +- `Import::handle_pmt` adds streams but does not retire removed PES PIDs; + an existing stream bypasses updated types/descriptors. Several catalog + fields are captured only when a track is created. Export rejects a newly + added ES once tables exist, while removals leave the initial PSI layout. + Settle PMT version transitions, PID reuse, program/PCR changes, and track + identity together. A name must never identify different content after a + restart or PID reuse. +- MPEG-1/2 video is handled as a clock stream and its payload discarded. + Unknown stream-type bytes can import as opaque but fail export's closed + enum conversion. A known stream type is not proof of supported carriage. +- SI ingest recognizes fixed DVB PIDs. ATSC PSIP, CAT/conditional access, + dynamically signalled tables, descriptors and private sections need + explicit profile decisions. Packet passthrough can retain mechanisms the + semantic lane does not understand. +- Section export requires video, leaving audio-only programs with sections + unsupported. Keep opaque SCTE-35 fidelity separate from the later typed + browser cue API; basic carriage should not depend on that API existing. +- Private PES loses optional header semantics today; its timing/header + contract belongs to the existing planning quest linked below. + +The maintainer decides whether a supported profile handles live PMT changes +in place with fresh track identities, replaces the broadcast, or initially +refuses specific transitions. Present the observable tradeoffs and ask before +choosing the public shape. Build a mechanism-to-catalog/track/refusal table +and use it to produce independently completable quests, with Rust/JS/draft +impact recorded for every extension. Keep Hang's core TS-free. + +Every implementation quest includes generated or redistributable fixtures +and an automated round-trip or refusal test in CI. Include PMT add/remove, +version rollover and PID reuse, unknown stream types, audio-only plus +sections, missing timing, and the profile's descriptors. Preserve raw +section/PES bytes only where the settled contract actually promises that. + +## Related + +- [PES timing and headers](/quest/m1/plan-ts-pes-untimed.md) - separate placement, decode and presentation semantics +- [Catalog track identity](/quest/m1/catalog-track-id.md) - names identify the same content throughout their lifetime +- [Automated validation](/quest/m1/ts-reliability/validation.md) - profile declarations link to executable evidence +- [Typed SCTE-35](/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - application cue APIs follow basic opaque carriage diff --git a/quest/m1/ts-reliability/pes.md b/quest/m1/ts-reliability/pes.md new file mode 100644 index 00000000000..66199ca6198 --- /dev/null +++ b/quest/m1/ts-reliability/pes.md @@ -0,0 +1,44 @@ +# [M] TS import assembles PES headers across packets with bounded staging + +## Goal + +Legal clear PES headers can span TS packets, and malformed or incomplete +input cannot grow importer staging indefinitely. Damage cannot concatenate +bytes across a lost packet into a plausible access unit. + +## Plan + +The audit found `Import::handle_pes` parses the first packet's payload as a +complete PES header. `PesStart::parse` needs the complete optional header, +so a legal clear header split across TS packets is discarded. PES payload +continuations and sections waiting for timing also have no explicit byte +bound in their staging paths. Raw passthrough already has explicit bounds; +semantic demux needs equally clear limits appropriate to its own units. + +Reassemble the header before parsing or delivering its payload. Keep the +state machine small and distinguish incomplete input from malformed input. +Honor declared lengths, continuity damage, discontinuity, duplicate packets, +new PUSI, and end of input. Special PES stream IDs have different header +rules and must not be forced through the ordinary optional-header layout. + +Bound retained bytes while waiting for a complete header, an unbounded PES's +next boundary, or missing clock/timestamp information. Derive protocol limits +where they exist, and use the repository's resource-limit conventions for +the rest. Refuse unsupported input explicitly instead of allowing unbounded +growth or silently inventing timing. A public configuration change needs its +own API decision if existing limits cannot express the policy. + +Regression tests fragment legal headers at every packet boundary and prove +payload/timestamps survive. Negative cases cover header length overruns, +truncation, continuity loss, and streams that never supply the awaited +boundary or clock. Assert retained memory is bounded and no damaged unit +escapes. Run these in the Rust CI tests; add a generated fragmented-header +round trip to the automated TSDuck/FFmpeg harness. + +The nonzero PES length underflow is already fixed separately in #5323; +retain its regression rather than duplicating that fix. + +## Related + +- [Automated validation](/quest/m1/ts-reliability/validation.md) - independent parsing and decoding of the reassembled output +- [PES timing and headers](/quest/m1/plan-ts-pes-untimed.md) - defines semantics retained after assembly diff --git a/quest/m1/ts-reliability/recovery.md b/quest/m1/ts-reliability/recovery.md new file mode 100644 index 00000000000..48014c19425 --- /dev/null +++ b/quest/m1/ts-reliability/recovery.md @@ -0,0 +1,62 @@ +# [L] TS recovery is tested against actual missing MoQ content + +## Goal + +Automated tests show how TS output and software decoding recover when MoQ +objects, groups, or tracks are absent or too late, including after playback +has started. Unaffected tracks continue according to the supported profile; +missing dependency chains are not presented as independently decodable. + +## Plan + +Test content loss separately from IP packet loss. QUIC may retransmit IP +loss; a netem percentage does not establish that any MoQ object was omitted. +Keep the real network impairment arm for transport and pacing evidence, and +add deterministic fault schedules at the MoQ content boundary. + +Cover a cold join, a skipped group, a partially delivered group, late objects +that miss release, one stalled/missing track, and resumed delivery. Put loss +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. + +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 +content with FFmpeg, compare recovered frames/samples against a continuous +source decode where applicable, and assert recovery at the profile's valid +acquisition point. No arbitrary recovery timeout becomes a substitute for +the encoded dependency rule. Exercise the graders' failure paths in CI. + +For semantic TS, validate continuity/discontinuity signalling, surviving +access-unit deadlines, decoder buffers and actual decoded output. Recovery +trims apply after a latency skip or discontinuity as well as the first join. +Coordinate the existing open-GOP and gradual-refresh quests: an H.264 +recovery-point SEI does not always promise immediate recovery, and HEVC CRA, +RADL and RASL do not have identical reference rules. Continuous subscribers +must retain valid pictures. + +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. + +Short deterministic arms run on relevant PRs. Long drift and impairment +arms run nightly with failure artifacts. Keep byte-position PCR accuracy +and measured release timing as separate checks. + +## Required + +- [Automated validation](/quest/m1/ts-reliability/validation.md) - shared graders, profiles and known-bad controls +- [TS passthrough export](/quest/m1/ts-passthrough-export.md) - supplies the raw egress exercised by the loss matrix + +## Related + +- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - trims after non-continuous transitions +- [Gradual recovery](/quest/m2/intra-refresh/README.md) - recovery counts and per-group warmup +- [Rust continuity](/quest/m1/rust-continuous.md) - consumers observe delivery breaks diff --git a/quest/m1/ts-reliability/validation.md b/quest/m1/ts-reliability/validation.md new file mode 100644 index 00000000000..df4d35633ce --- /dev/null +++ b/quest/m1/ts-reliability/validation.md @@ -0,0 +1,72 @@ +# [L] TS validators run as automated tests + +## Goal + +TSDuck, FFmpeg, and the repository's TS graders assert the supported output +profiles in repeatable CI tests. A green run means the expected content was +decoded and the named timing and structure checks passed, not merely that a +tool parsed a file or returned zero. + +## Plan + +Required by the maintainer in the 2026-10-11 audit: every TS validation is +automated, including any additional validator introduced later. Use the pinned +Nix tools and share local `just test` recipes with CI. Reuse `test/ts` rather +than introducing a second harness. + +Current gaps: + +- `run.sh` uses FFmpeg to generate sources but never fully decodes the + exported audio/video. `ffprobe_opus_channels` checks metadata only. +- `just test ts --pair` and `table-anchor.py` exist but no workflow invokes + that arm. Add a scheduled gate at minimum. +- `interop.yml` triggers for the harness but not `rs/moq-mux/**`. Relevant + mux, catalog, and TS CLI changes need the short integration gates. +- Plain captured runs do not reject a failed publisher, and the subscriber + is reaped without its status contributing to the verdict. A partial file + can pass analysis after the pipeline has failed. + +Add a reusable full software-decode grader for supported clean profiles, +starting with the existing closed-GOP H.264/AAC generator. FFmpeg must fail +on decode errors, decode every expected stream, and produce nonzero video +frames and audio samples where the source has them. Preserve diagnostics and +per-stream counts. A successful probe or concealment-tolerant decode is not +the assertion. Prove the grader rejects malformed coded payload and a missing +expected stream with automated controls that fail for the intended reason. + +The first declared profile also compares decoded content against the source +over the admitted interval. Match video frames and aligned audio samples rather +than requiring identical demux packet boundaries. Account explicitly for +startup, decoder priming, and end trimming; never loosen an existing duration +check to accommodate missing content. A grader that only checks decode +acceptance and nonzero progress must report that narrower result until the +source comparison passes. Open-GOP acquisition expectations land +with the existing leading-pictures work. + +Keep TSDuck's structural checks and explicit PCR-accuracy threshold, the +byte-schedule grader, and live release timing as distinct assertions. A CBR +byte-position PCR check is not a wall-clock jitter measurement. VBR and MPTS +with independent clocks need their own applicable timing model before they +can be labelled covered. Retain process failures, reports, tool versions, +input fixtures or reproducible generation parameters, and failing output as +CI artifacts. + +The custom T-STD model currently excludes the PSI system buffer, refuses +several layouts/codecs, and borrows AAC's buffer size for Opus. Report these +limits by profile. Coordinate system-buffer controls with `tstd/psi-runs` +and MB/AAC controls with the existing m2 quest; do not duplicate them or call +the current model complete. Correct the blanket claim in the harness docs +that no maintained tool implements T-STD: commercial analyzers advertise +it, while no suitable maintained open-source replacement was established. + +Independent failure reporting landed in #5297; keep its workflow shape, and +ensure an earlier unrelated failure cannot suppress these tests. All new +controls have CI invocations too. + +## Related + +- [TS duration fidelity](/quest/m0/ts-duration-fidelity.md) - fixes the base capture regression without weakening the duration assertion +- [T-STD controls](/quest/m2/tstd-controls.md) - MB and AAC positive/negative coverage +- [PSI system buffer](/quest/m1/tstd/psi-runs.md) - system-buffer proof belongs with the PSI fix +- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - acquisition trims change the decoder oracle +- [Loss and recovery](/quest/m1/ts-reliability/recovery.md) - extends these graders to declared omissions and recovery diff --git a/quest/m1/tstd/README.md b/quest/m1/tstd/README.md index aeeaf2754e3..dbc5cf63012 100644 --- a/quest/m1/tstd/README.md +++ b/quest/m1/tstd/README.md @@ -1,12 +1,13 @@ -# [M] T-STD compliant TS export +# T-STD compliant TS export ## Goal -`moq export ts` output passes a full ISO 13818-1 T-STD buffer-model check -(transport, multiplex, and elementary buffers, with every access unit decoded -at its DTS without overflow or underflow), on a clean path and under -sustained loss. That is the bar for the media-aware lane to carry primary -distribution. Without it, only the passthrough lane can. +`moq export ts` output passes the applicable ISO 13818-1 T-STD buffer-model +checks for explicitly supported profiles, with admitted decodable access +units complete by their decode time and no modelled buffer overflow. Under +loss, validate the surviving content, declared discontinuities and recovery; +missing source units cannot all be decoded. Packet passthrough also needs +timing and recovery evidence before making a distribution-readiness claim. ## Plan @@ -29,9 +30,22 @@ latest. At 500 ms a 540 s run still misses a video deadline about 157 s in, which [send-ahead](/quest/m1/tstd/send-ahead.md)'s 1 s default addresses, and 10 % loss is still to pass. -This README owns the end-to-end proof: the #4613 netem rig (10% loss, a real -~10 Mb/s broadcast TS) passes the strict T-STD check, and the recipe runs -nightly. +This README owns the remaining end-to-end proof: make the #4613 netem rig +(10% loss, a redistributable or reproducible ~10 Mb/s broadcast-style TS) +pass the applicable strict T-STD checks, and run the recipe nightly. This +is a completion requirement, not a result established by the measurements above. + +Audit clarification (2026-10-11): record what actually arrived, was +retransmitted, or missed its deadline. The IP loss percentage alone is not +a MoQ omission test. Keep this network/pacing proof and add deterministic +content-loss coverage through the TS reliability line. Run TSDuck, FFmpeg +software decode, and the custom model as automated assertions with known-bad +controls. A model pass is not independent proof of decoded content. + +The current model does not cover every codec/layout or the PSI system buffer. +Name those exclusions and assumptions in the profile report; the PSI quest +owns its system-buffer proof, and the existing controls quest owns the missing +MB/AAC controls. Do not relabel the current subset a full standards check. ## Required @@ -41,3 +55,5 @@ nightly. ## Related - [TS passthrough export](/quest/m1/ts-passthrough-export.md) - the passthrough lane named in the Goal +- [Automated validation](/quest/m1/ts-reliability/validation.md) - independent decode, profile coverage and CI ownership +- [Loss and recovery](/quest/m1/ts-reliability/recovery.md) - actual object/group omissions and recovery diff --git a/quest/m1/tstd/send-ahead.md b/quest/m1/tstd/send-ahead.md index b398cfc55f7..ddaa61b589e 100644 --- a/quest/m1/tstd/send-ahead.md +++ b/quest/m1/tstd/send-ahead.md @@ -30,4 +30,7 @@ carving alone should cut it by about one delay, not to 0.5 s. it (the existing `a_joiner_runs_at_the_delay_from_its_first_output`, tightened from two delays to one). `hrd9m` passes strict `tstd` at the 1 s default, and a delay below its buffer delay fails loud. -- Ask t0ms to re-grade the CNN capture: latency should drop by about a delay. +- Prove the latency change with generated or redistributable fixtures and + automated assertions in CI. A third-party capture re-grade can supplement + that evidence, but is not a completion dependency or a substitute for the + automated test. diff --git a/quest/m2/README.md b/quest/m2/README.md index 2fd898551ed..e254b301bb9 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -31,7 +31,7 @@ and bench readiness. Refusal reasons folded the same day into - [One port on the io_uring workers](/quest/m2/uring-demux.md) - `moq-uring`'s workers host the UDP demux, so a ring relay keeps WebRTC media and SRT on its QUIC port - [Synced data playback](/quest/m2/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back - [Watch decode gate](/quest/m2/watch-decode-gate.md) - video lookahead stays encoded until it is near presentation, like audio -- [Hitless TS legs](/quest/m2/ts-hitless.md) - two `--sync` export legs emit packet-identical TS for ST 2022-7 +- [Deterministic TS legs](/quest/m2/ts-hitless.md) - two export legs preserve common TS packet identity; coordinated RTP is a separate prerequisite for ST 2022-7 - [DVB E-AC-3](/quest/m2/ts-eac3.md) - E-AC-3 private data is split per access unit (independent frame plus its dependent substreams) and buffer-modelled in TS export - [T-STD controls](/quest/m2/tstd-controls.md) - the harness gains an MB-overflow control and an AAC broadcast reference - [MP4 export](/quest/m2/mp4-export.md) - `moq export mp4 --output` records crash-safe fragments, then finishes a regular MP4 with moov at the end diff --git a/quest/m2/intra-refresh/README.md b/quest/m2/intra-refresh/README.md index 17a54f4ae14..3f41d580f7e 100644 --- a/quest/m2/intra-refresh/README.md +++ b/quest/m2/intra-refresh/README.md @@ -25,6 +25,10 @@ broadcast feeds that only do intra refresh. Decisions the quests share: +The recovery-boundary planning prerequisite checks the duration contract +below before implementation. Its precision and publication ordering must +make these presentation guarantees true even when sweep lengths change. + - One group per refresh cycle. A group starts at the recovery point, the frame that begins a sweep, so a viewer joining at any group boundary is clean after exactly one cycle and relay shedding keeps its meaning. @@ -42,6 +46,7 @@ Decisions the quests share: ## Required +- [Plan: recovery boundaries](/quest/m2/intra-refresh/plan-boundary.md) - settle safe precision and publication ordering before consumers rely on a duration - [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - JS and Rust viewers join `warmup` earlier and withhold display until recovery, except at a true IDR - [H.264 import](/quest/m2/intra-refresh/h264-import.md) - the splitter keeps `recovery_frame_cnt` and import publishes `warmup` from it - [H.265 import](/quest/m2/intra-refresh/h265-import.md) - the splitter reads the recovery-point SEI so an HEVC intra-refresh stream forms groups and publishes `warmup` diff --git a/quest/m2/intra-refresh/consumer-warmup.md b/quest/m2/intra-refresh/consumer-warmup.md index 536638fcad3..b860afe142b 100644 --- a/quest/m2/intra-refresh/consumer-warmup.md +++ b/quest/m2/intra-refresh/consumer-warmup.md @@ -60,6 +60,7 @@ replaces both: the rule is timestamp arithmetic on the group start. ## Required +- [Plan: recovery boundaries](/quest/m2/intra-refresh/plan-boundary.md) - consumers need a safe boundary before presenting the affected pictures - [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the Rust signal this keys on ## Related diff --git a/quest/m2/intra-refresh/h264-import.md b/quest/m2/intra-refresh/h264-import.md index ea803af20d8..7dc8e8eebed 100644 --- a/quest/m2/intra-refresh/h264-import.md +++ b/quest/m2/intra-refresh/h264-import.md @@ -11,6 +11,11 @@ were immediately decodable. ## Plan +The recovery-boundary planning prerequisite must settle the precision and +publication ordering before implementing the duration proposal below. In +particular, rounding down and raising a catalog value after a longer sweep +are not yet proven safe for a viewer that already received those pictures. + - `rs/moq-mux/src/codec/h264/split.rs`: `sei_has_recovery_point` returns the `recovery_frame_cnt` the `h264-parser` crate already exposes on `SeiPayload::RecoveryPoint`, and the split frame carries it. A count of zero @@ -37,3 +42,7 @@ were immediately decodable. length-prefixed path; and a real clip generated with x264 `intra-refresh=1` added as a second round-trip in `test/ts/run.sh` next to the closed-GOP one, asserting the catalog `warmup` and the group count. + +## Required + +- [Plan: recovery boundaries](/quest/m2/intra-refresh/plan-boundary.md) - resolve the rounded and later-mutated warmup contract before implementing it diff --git a/quest/m2/intra-refresh/h265-import.md b/quest/m2/intra-refresh/h265-import.md index 278e0e1d00a..3ab09fd2f03 100644 --- a/quest/m2/intra-refresh/h265-import.md +++ b/quest/m2/intra-refresh/h265-import.md @@ -31,9 +31,11 @@ that machinery in parallel. recovery point's plus the count and measures `warmup` from its timestamp exactly as the H.264 quest does, sharing the measurement and catalog mutation. -- Fixture: synthetic NAL sequences beside the existing suffix-SEI tests, since - x265's intra refresh emits no recovery-point SEI. Verify by hand with an - externally encoded clip (ffmpeg `hevc_nvenc` with intra refresh). +- Fixtures: synthetic NAL sequences beside the existing suffix-SEI tests, + since x265's intra refresh emits no recovery-point SEI, and a + redistributable externally encoded clip when available. An NVENC-generated + fixture may supply that input, but validation must be a repeatable + software-decode test in CI, not a manual check or a hardware-only gate. ## Required diff --git a/quest/m2/intra-refresh/plan-boundary.md b/quest/m2/intra-refresh/plan-boundary.md new file mode 100644 index 00000000000..02dd77acd97 --- /dev/null +++ b/quest/m2/intra-refresh/plan-boundary.md @@ -0,0 +1,38 @@ +# [S] Plan: recovery boundaries remain safe as refresh duration changes + +## Goal + +Settle how consumers know a group's precise recovery boundary before +presenting pictures, including when later refresh sweeps take longer than +earlier ones. Rewrite the import and consumer quests around that contract. + +## Plan + +The 2026-10-11 TS audit found the proposed catalog duration is not yet a +sufficient guarantee. `h264-import` rounds a measured recovery duration down +to milliseconds and raises the global value after observing a longer sweep. +`consumer-warmup` presents any frame at or beyond that duration. A rounded +boundary can precede the recovery picture, and a later catalog update cannot +recall pictures a subscriber has already displayed using the old value. + +Ask the maintainer to choose between an exact per-group boundary and a safe +bound known and published before the affected content, including the latency +and catalog/container consequences. Test timestamp precision, reordered +pictures, frame_num wrap, variable sweep lengths, a missed recovery picture, +and a join/skip before a longer sweep is known. Decode-only pictures still +build reference state; withholding presentation is not dropping their input. + +Review the H.264 recovery-point flags and count semantics and HEVC +CRA/RADL/RASL separately. A timestamp-before-keyframe rule is a conservative +leading-picture policy, not a complete codec dependency model. State which +profiles it supports without changing an existing wire contract by inference. + +Produce implementation and automated software-decode tests in the existing +quests. Use generated fixtures, run short cases in CI, and retain full +reference-decode comparisons for continuous playback and each recovery case. + +## Related + +- [H.264 import](/quest/m2/intra-refresh/h264-import.md) - publishes recovery information +- [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - uses it to withhold presentation +- [TS loss tests](/quest/m1/ts-reliability/recovery.md) - exercise actual group skips and recovered output diff --git a/quest/m2/ts-hitless.md b/quest/m2/ts-hitless.md index 40540918906..dc041cd3d0e 100644 --- a/quest/m2/ts-hitless.md +++ b/quest/m2/ts-hitless.md @@ -1,11 +1,13 @@ -# [L] Two TS export legs emit identical packets for ST 2022-7 +# [L] Redundant TS exports preserve common packet identity ## Goal Two `moq export ts --sync` legs of one broadcast, joined at different moments, emit packet-identical TS from their first common packet, across -skips and source drift, continuity counters included, within one epoch. A ST 2022-7 selector -can then switch between them hitlessly. +skips and source drift, continuity counters included, within one epoch. +This establishes TS identity only. ST 2022-7 also requires matching RTP +headers and payloads; coordinated RTP egress and receiver recovery need +their own scope and tests before claiming selector compatibility. Non-goal: identity across a replaced broadcast. A leg ends on a replacement, or starts a fresh stream with `--stitch`, @@ -28,8 +30,12 @@ requirement, so this waits until the T-STD line settles. there, so it comes from the media and not from what a leg has sent. The PCR moves to its own PID, because a discontinuity flag on the PCR PID would declare a time-base break. Loss is still detected within a group. -- Once anchored identically, both legs must make the same skip decision and - lay out the same slots. t0ms's `two_legs_render_a_skip_the_same_way` +- For content both legs release, the shared schedule must lay out the same + slots. Independent late delivery can leave complementary gaps; forcing both + legs to drop the same content would defeat redundant-path recovery. The + alignment planning prerequisite settles how the TS scheduler and any RTP + egress preserve common coordinates through those gaps. + t0ms's `two_legs_render_a_skip_the_same_way` (`rs/moq-mux/src/container/ts/export_timing_test.rs`) stays ignored until this lands. With the audio late, it also showed a PES header byte that differs at the skip; find and fix that. @@ -41,6 +47,7 @@ requirement, so this waits until the T-STD line settles. ## Required +- [Plan: redundant TS alignment](/quest/m1/plan-ts-alignment.md) - settle shared coordinates and coordinated RTP scope before implementing the public sync contract - [T-STD TS export](/quest/m1/tstd/README.md) - the export, clock recovery, and schedule these legs share ## Related diff --git a/quest/m2/tstd-controls.md b/quest/m2/tstd-controls.md index 5d8d20ffe16..7c7002e9c1f 100644 --- a/quest/m2/tstd-controls.md +++ b/quest/m2/tstd-controls.md @@ -4,8 +4,8 @@ `just test ts-tstd` has a negative control that overflows the video multiplex buffer (MB), and a positive reference that carries AAC the way a broadcast -encoder does. Every buffer and codec the export emits then has a control on -each side. +encoder does. These close the named MB/AAC gaps; they do not establish +coverage of every buffer, codec or layout the exporter can encounter. ## Plan @@ -22,3 +22,8 @@ The only positive reference carries MPEG audio, but the export emits AAC. shared. - Each control fails or passes for the stated reason, and `interop.yml` runs them. + +## Related + +- [TS validation](/quest/m1/ts-reliability/validation.md) - reports supported model coverage and assumptions without claiming full conformance +- [PSI system buffer](/quest/m1/tstd/psi-runs.md) - owns the separate system-buffer assertion and regression diff --git a/quest/m3/msfts-convergence.md b/quest/m3/msfts-convergence.md index 1e9cfdcf394..09031d91ff6 100644 --- a/quest/m3/msfts-convergence.md +++ b/quest/m3/msfts-convergence.md @@ -15,13 +15,24 @@ Decided in the 2026-09-30 audit: moved from m4 and the msfts#33 gate removed. msfts#33 closed on 2026-09-28, answered by msfts#36 (merged 2026-09-24), and egress moved to msfts#37 (closed). Two differences remain: -- **Program tables.** MSFTS carries them in tracks; here they live in the - Hang catalog's `mpegts` section. Decide whether to publish a mapping from - the catalog section to MSFTS's table tracks, or change either side. +- **Program tables.** PAT/PMT information lives in the Hang catalog's + `mpegts` section; supported SI already uses tracks. Map these mechanisms + separately to MSFTS's table tracks instead of saying all tables live in + the catalog. - **ES units.** MSFTS es-units carry the whole PES packet; here they carry the payload plus `stream_id`. Decide whether the PES header fields we drop matter to a subscriber, and converge or document the mapping. +Decided in the 2026-10-11 audit: keep the semantic lane and raw fallback +distinct. Whole SPTS maps to `unmodified-program`, whole MPTS to +`unmodified-multiplex`. MSFTS `per-program` extraction and `es-packets` +(which omit null packets) are not byte-identical whole-input carriage. +The fallback will not split PIDs or add source-position reconstruction +metadata. Use [the current draft](https://datatracker.ietf.org/doc/html/draft-gregoire-moq-msfts) +to document both semantic and scheduling differences; shared terminology +does not establish wire interoperability. Coordinate PES decisions with +[private PES timing and headers](/quest/m1/plan-ts-pes-untimed.md). + Update `drafts/draft-lcurley-moq-mpegts.md` and `doc/concept` with whatever lands. [#4577](https://github.com/moq-dev/moq/pull/4577) (per-ES access units at export) has merged, and [#4579](https://github.com/moq-dev/moq/pull/4579)