feat(moq-mux)!: fixed-delay jitter buffer and per-PID T-STD admission for TS export

.github/workflows/interop.yml

@@ -128,6 +128,24 @@ jobs:
         env:
           MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs
 
+      # 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.
+      - name: TS keyframe bursts
+        run: nix develop --command just test ts --bitrate 2000000
+        shell: bash -leo pipefail {0}
+        env:
+          MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs
+
+      # 1080p video filling a broadcast-sized 9 Mbit CPB, at the default delay: the
+      # source sends pictures most of a second ahead of their decode time, and the
+      # export has to as well without overflowing the receiver's buffers.
+      - name: TS broadcast-sized CPB
+        run: nix develop --command just test ts --hrd
+        shell: bash -leo pipefail {0}
+        env:
+          MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs
+
       # The same round-trip over an open-GOP clip: every leading picture after a
       # recovery point must come back, in decode order.
       - name: TS open GOP

doc/bin/cli.md

@@ -130,10 +130,13 @@ SI matches the selection by DVB `service_id`, which is assumed to equal the PAT
 moq --connect https://relay.example.com/anon --broadcast event.hang import ts --program all < mux.ts
 ```
 
-MPEG-TS export restarts its clock and table cadence after a declared marker,
-discarding the old mux buffer. The first new clock packet signals the break and
-stdout pacing re-anchors. Every rendition joins the new program generation;
-no track is fenced across the marker.
+MPEG-TS export starts a new clock after a declared marker, and the first new
+clock packet signals the break. Each track goes out on the old clock until it
+reaches the marker, then joins the new one, unless an old-clock frame would go
+out after the new clock's first, which is dropped. Once the export has measured
+each track's lead over the others (two seconds of media), the new clock keeps
+it, so a track the source sends later than the rest crosses without losing
+frames. No track is fenced across the marker.
 
 MPEG-TS export frames AAC as ADTS, which labels only the AAC Main, LC, SSR,
 and LTP profiles. HE-AAC and HE-AACv2 go out as their AAC-LC core, and decoders
@@ -152,11 +155,20 @@ the program without that AAC track, and adds the track if an element arrives.
 
 A constant-rate MPEG-TS source records its multiplex rate in the catalog
 (`mpegts.muxRate`, measured off the PCR clock, null stuffing included), and
-`export ts` pads its output with null packets back to that rate so an IRD or
-groomer receives a constant-rate stream. `--mux-rate 5000000` pads to an explicit
-rate instead, including for a broadcast that recorded none. Media is never delayed
-or dropped to fit: a source that sustains more than the rate overruns it, and a
-VBR source records nothing, so export without either stays unpadded.
+`export ts` pads its output with null packets back to that rate on a constant-rate
+schedule, so an IRD or groomer recovering its clock from packet arrival can lock:
+every PCR is the time of its own byte position at the rate. `--mux-rate 5000000`
+pads to an explicit rate instead, including for a broadcast that recorded none.
+
+Each frame goes out as early as a receiver's buffers for its PID admit (the
+ISO 13818-1 T-STD: no more of a PID's packets per interval than its transport
+buffer passes on, and no more bytes than its decoder buffer holds, sized from the
+SPS's HRD or level for video and per codec for audio), up to `--delay` ahead of its
+decode time on the output's PCR clock, earliest decode time first. So a heavy passage rides the intervals
+before it, and the output trails the source by twice the delay. A frame that cannot
+arrive by its decode time at the rate fails the export with an error naming both
+knobs; a broadcast-sized decoder buffer (a CPB of a second or more) needs a delay to
+match. A VBR source records no rate, so export without one stays unpadded.
 
 The `fmp4`, `mkv`, `flv`, `h264`, and `h265` exports select renditions with
 flags before the sink: `--video-name` and `--audio-name` pick a rendition,
@@ -502,13 +514,32 @@ See [Authentication](/bin/relay/auth).
 `import --max-age` (default 30 s) tells relays how long to keep old
 groups fetchable, which the [HLS gateway](/bin/hls) depends on. `export --max-delay` (default 500 ms) is how far a stalled group may fall
 behind the live edge before *this* consumer skips it. Raising the first never delays playback.
-`export ts` still spells its budget `--max-age`.
 
-For `export ts`, `--max-age` also bounds how long the muxer holds a leading
-track for a lagging one. Frames go out in media-time order across all tracks,
-not arrival order, so two exporters of one broadcast emit them in one order. A
-track quiet for longer is muxed around until it catches up; a sparse track
-(SCTE-35) costs that wait once per cue. `--max-age 0` keeps arrival order.
+`export ts` takes `--delay` (default 500 ms) instead, and works like an SRT
+receiver's latency. Every frame is released to the multiplexer that long after
+its decode time, on a clock that keeps the source's pace and muxes all tracks in decode order
+whatever their arrival skew: two exporters of one broadcast emit them in one
+order. The export joins at the newest group and holds its output until it
+has heard from every audio, video, DVB AC-3 and teletext track (two delays at most) and a
+track starts its next group, or one of the frames it holds falls due. It then
+starts the clock on the track the source sends latest against its decode time,
+from that track's freshest frame: a broadcast TS sends video most of a second
+ahead and audio just in time, and the audio must keep the delay too. What of
+the joined group is older than the delay is dropped, so a joiner runs at the
+delay from its first output. A frame that arrives later than its deadline is
+dropped, and video then resumes at its next keyframe. The clock follows the
+source's, measured from the frames that arrive least delayed on the track sent
+latest, so a source whose clock runs a
+little fast or slow neither goes late nor piles up over a long run, and a
+spell of network queueing does not move it. The output's PCR is that clock,
+so it keeps to what ISO/IEC 13818-1 allows a system clock: within 30 ppm of
+the exporter's, its rate changing by at most 0.075 Hz/s. Catching up with a
+source near that limit takes hours; one further off is counted in the
+export's stats, and fails the export once it has used half the delay. Each
+25 ms slice of the output is written when the clock reaches it. A stalled group
+is skipped once it falls half the delay behind, leaving the group after it the
+other half. `--delay 0` holds nothing and drops
+nothing, writing frames in arrival order as they come.
 
 A stdout export ends with the broadcast. `export ts --linger 10s` waits that
 long for the broadcast to come back instead: a publisher that restarts within

doc/bin/srt.md

@@ -44,8 +44,9 @@ publishes each program as its own broadcast (`event.hang` becomes
 moq --connect https://relay.example.com/anon --broadcast event.hang import srt --listen '[::]:9000' --program all
 ```
 
-`--latency` sets the SRT receive buffer and doubles as the skip threshold on
-export. Export paces each SRT payload on the media clock, and re-anchors that
+`--latency` sets the SRT receive buffer and doubles as the export's jitter
+buffer delay, as `export ts --delay` in the [CLI](/bin/cli): each frame is muxed that
+long after its decode time, and one arriving later is dropped. Export paces each SRT payload on the media clock, and re-anchors that
 pacing on a declared marker, so a restarted timeline plays out from the
 live edge instead of stalling until it catches up. A `--connect` URL needs a `streamid` query or a path; a listener
 bridges one `--broadcast` and ignores the stream id it is offered. The

doc/setup/upgrade.md

@@ -71,6 +71,13 @@ These land with the next breaking release, not the 2026-09-23 train.
   the rendition's own delay added on top. `Sync.out.jitter` now always
   equals `Sync.out.delay`, and `"auto"` with no decoder registered resolves to
   0 rather than 100 ms.
+- **`moq export ts --delay` replaces `--max-age`** (#4645). Each frame is
+  written that long after its decode time, on a clock that follows the
+  source's; `--max-age` and `--latency-max` are refused with the new flag
+  named. In Rust, moq-mux's `ts::Export::with_max_age` is `with_delay`, and
+  `ts::stats::Export` gains the dropped-frame count (late frames, and the
+  video frames then dropped waiting for a keyframe), measured drift and
+  out-of-tolerance count beside its `streams` rows. It is no longer `Eq`.
 - **moq-mux has no clock translators.** `clock::Anchor`, `clock::Lane`, and
   `SourceMap` (#4667) are gone, along with the importers' `live()`. Publish the
   source's own timestamps and let the catalog clock map them to wall time;
@@ -141,7 +148,7 @@ These land with the next breaking release, not the 2026-09-23 train.
   `moq_video_decoder_output`, `moq_consume_video`, and `moq_consume_audio`.
   `moq export fmp4`, `mkv`, `flv`, `h264`, `h265`, and `rtmp` take
   `--max-delay`, and refuse `--max-age`. `track::Info::max_age`,
-  `MoqTrackInfo.max_age_us`, `moq import --max-age`, and `moq export ts --max-age` are unchanged, as is the wire.
+  `MoqTrackInfo.max_age_us`, and `moq import --max-age` are unchanged, as is the wire.
 - **moq-relay auth takes the client-CA answer.** `auth::Config::validate` and
   `init` take `client_ca: bool`, whether any listener verifies client
   certificates, and `validate_client_ca` is gone. `moq --listen` with an
@@ -168,8 +175,7 @@ These land with the next breaking release, not the 2026-09-23 train.
 - **moq-mux TS stats live in `ts::stats`.** `ts::Stats` is
   `ts::stats::Snapshot` and `ts::StreamStats` is `ts::stats::Stream`, whose
   `track` is an owned `String`. `ts::Export::stats` returns
-  `ts::stats::Export`, which carries only `streams`; feed it to
-  `stats::Log` with `.into()`. `ts::MultipleProgramsError` is
+  `ts::stats::Export`; feed it to `stats::Log` with `.into()`. `ts::MultipleProgramsError` is
   `#[non_exhaustive]`: recover it by downcast and read `programs`.
 - **@moq/publish drops `OpusConfig.usedtx`.** Chromium's DTX output shifts the
   audio timeline, so Opus DTX is always off (the WebCodecs default). Remove the

quest/m1/README.md

@@ -166,8 +166,8 @@ blocks. The quests that gated m0 lines moved under them.
 - [Audio warmup](/quest/m1/audio-warmup.md) - a viewer joining an Opus rendition mid-stream never hears the unconverged first 80 ms
 - [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - moq-gst picks the broadcast wall epoch; a restarted source is a new epoch, not a forward re-anchor
 - [TS passthrough](/quest/m1/ts-passthrough.md) - `--passthrough` carries the multiplex as whole packets, listed in an `m2ts` catalog section, and writes it back byte-identical (less late drops) on a fixed delay
-- [FLV export delay](/quest/m1/flv-export-delay.md) - FLV interleaves through the shared fixed-delay release stage
-- [MKV export delay](/quest/m1/mkv-export-delay.md) - MKV interleaves through the shared fixed-delay release stage
+- [FLV export delay](/quest/m1/flv-export-delay.md) - FLV interleaves through the shared jitter buffer
+- [MKV export delay](/quest/m1/mkv-export-delay.md) - MKV interleaves through the shared jitter buffer
 - [MKV lacing](/quest/m1/mkv-lacing.md) - laced MKV blocks import as one timed frame each, refused without DefaultDuration
 - [Release profile](/quest/m1/release-profile.md) - every release build gets fat LTO, one codegen unit, and stripping from the workspace profile instead of three script exports
 - [Size report](/quest/m1/size-report.md) - a nightly job reports every shipped artifact's size, native and JS, and alerts when one grows

quest/m1/flv-export-delay.md

@@ -3,16 +3,16 @@
 ## Goal
 
 `moq export flv --delay <dur>` interleaves tracks through the shared
-fixed-delay release stage, so its tag order is a function of the media, not
+jitter buffer, so its tag order is a function of the media, not
 of arrival, as the TS export's is.
 
 ## Plan
 
 Today `pick_next_track` (`rs/moq-mux/src/container/flv/export.rs`) takes the
 smallest *pending* timestamp, so which track goes first depends on which frame
-has arrived. Replace it with the release stage from
-[fixed-delay release](/quest/m1/tstd/delay.md), with the same `--delay` flag
-and the same late-frame drop. Update `doc/bin/cli.md`.
+has arrived. Replace it with the jitter buffer the TS export uses
+(`rs/moq-mux/src/jitter.rs`), with the same `--delay` flag and the same
+late-frame drop. Update `doc/bin/cli.md`.
 
 Decided in the 2026-10-06 audit: `--delay` replaces the staleness flag, as it
 replaced `--max-age` on TS, so one knob sets both the release delay and the
@@ -22,7 +22,3 @@ renames that flag to `--max-delay` first; this quest then replaces
 
 Public API: breaking, the exporter's staleness setting becomes the delay
 setting. Wire: none.
-
-## Required
-
-- [Fixed-delay release](/quest/m1/tstd/delay.md) - builds the shared release stage

quest/m1/mkv-export-delay.md

@@ -3,16 +3,16 @@
 ## Goal
 
 `moq export mkv --delay <dur>` interleaves tracks through the shared
-fixed-delay release stage, so its tag order is a function of the media, not
+jitter buffer, so its tag order is a function of the media, not
 of arrival, as the TS export's is.
 
 ## Plan
 
 Today `pick_next_track` (`rs/moq-mux/src/container/mkv/export.rs`) takes the
 smallest *pending* timestamp, so which track goes first depends on which frame
-has arrived. Replace it with the release stage from
-[fixed-delay release](/quest/m1/tstd/delay.md), with the same `--delay` flag
-and the same late-frame drop. Update `doc/bin/cli.md`.
+has arrived. Replace it with the jitter buffer the TS export uses
+(`rs/moq-mux/src/jitter.rs`), with the same `--delay` flag and the same
+late-frame drop. Update `doc/bin/cli.md`.
 
 Decided in the 2026-10-06 audit: `--delay` replaces the staleness flag, as it
 replaced `--max-age` on TS, so one knob sets both the release delay and the
@@ -22,7 +22,3 @@ renames that flag to `--max-delay` first; this quest then replaces
 
 Public API: breaking, the exporter's staleness setting becomes the delay
 setting. Wire: none.
-
-## Required
-
-- [Fixed-delay release](/quest/m1/tstd/delay.md) - builds the shared release stage

quest/m1/open-gop-leading-pictures.md

@@ -76,10 +76,6 @@ decode, and the JS test should drive the software decoder.
   group's leading pictures trimmed too, so an implementation that only trims
   the initial group fails. Both cases in both languages.
 
-## Required
-
-- [Fixed-delay release](/quest/m1/tstd/delay.md) - the TS export this trims lands with #4645
-
 ## Related
 
 - [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - the `recovery_frame_cnt > 0` case this rule does not cover

quest/m1/ts-passthrough.md

@@ -70,8 +70,8 @@ Decided (2026-10-01), from a discussion with t0ms:
 - A multiplex is paced on one PCR PID: the `PCR_PID` in the PMT of the PAT's
   first program, or `--pcr-pid`. Every byte stays in order behind it. Programs
   on independent clocks are out of scope.
-- The export reuses the [fixed-delay release](/quest/m1/tstd/delay.md)
-  stage, keyed on each object's PCR time instead of a DTS, which also
+- The export reuses the TS export's jitter buffer (`rs/moq-mux/src/jitter.rs`,
+  #4645), 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
@@ -119,10 +119,8 @@ hang catalog gains an `m2ts` root section; additive.
 ## Required
 
 - [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - the restart-under-a-new-epoch path a backward PCR discontinuity reuses
-- [Fixed-delay release](/quest/m1/tstd/delay.md) - the release stage this reuses, with its clock recovery (#4645)
 
 ## Related
 
 - [TS hitless](/quest/m2/ts-hitless.md) - the demultiplexed lane's 2022-7 legs and the `--sync` anchor
 - [MSFTS convergence](/quest/m2/msfts-convergence.md) - the ES-level side of the same mapping
-- [TS byte schedule](/quest/m1/tstd/byte-schedule.md) - the remux's equivalent of pacing on the source PCR

quest/m1/tstd/README.md

@@ -1,4 +1,4 @@
-# T-STD compliant TS export
+# [M] T-STD compliant TS export
 
 ## Goal
 
@@ -16,20 +16,26 @@ Padding, pacing, and muxing all assume a fixed delay, so the export gets one
 first. t0ms is testing whether T-STD compliance is feasible at all; record
 the result here. If it isn't, re-plan this line.
 
-The full-model check (`tstd` in `test/ts/compliance.py`) fails today's export
-for two reasons, both delivery timing: 7-10 % of video access units finish
-arriving after their DTS, and audio runs ~230 ms ahead in bursts that overflow
-its TB and B. The media itself fits its buffers, so nothing yet says the bar
-is out of reach.
+Measured (2026-10-01, #4645): with the fixed-delay jitter buffer, per-PID
+admission against each PID's T-STD buffers, and PCRs at their byte position, a
+clean-path round trip passes the strict T-STD check and TSDuck's ±500 ns
+pcrverify at the default 500 ms delay, for the generated clip at 10 Mb/s and
+2 Mb/s and for a 1080p encode filling a 9 Mbit CPB (`just test ts --hrd`, after
+t0ms's recipe). A unit that cannot arrive by its DTS fails the export rather
+than arrive late. t0ms graded it on a CNN broadcast capture (PAFF H.264, MP2,
+DVB AC-3, teletext, SCTE-35; 2026-10-02): at 1 s on loopback, across hosts and
+under the #4613 rig at 0 % and 1 % loss, every track passed T-STD and
+`compliance.py` with no late drops, once the clock anchored on the track sent
+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.
 
 ## Required
 
-- [Fixed-delay release](/quest/m1/tstd/delay.md) - frames go out at media time plus a fixed `--delay`, in one order under loss
-- [TS byte schedule](/quest/m1/tstd/byte-schedule.md) - PCRs sit on the byte grid the mux rate implies, paced against the fixed delay
 - [Send-ahead within the delay](/quest/m1/tstd/send-ahead.md) - total lag is `--delay`, send-ahead included, with a 1 s default
 - [Mux-rate hold](/quest/m1/tstd/mux-rate-hold.md) - import publishes its catalog once the mux rate is measured, so export is constant-rate from the start