diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 198c6144930..2aee6cccf83 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -106,8 +106,11 @@ Other video waits for its first keyframe. MPEG-TS export pads to the source's constant mux rate when the catalog recorded one, or to `--mux-rate`, on a constant-rate schedule an IRD or groomer can lock to. Each frame goes out as early as the receiver's buffers admit, up -to `--delay` ahead of its decode time on the output's clock, so the output trails the source by twice -the delay; a frame that cannot arrive in time at the rate fails the export. +to `--delay` ahead of its decode time and no further than its decoder buffer +holds. That send-ahead comes out of the delay, so the output trails a TS source +by `--delay`. A frame that cannot arrive in time at the rate fails the export, +as does video whose HRD declares a longer buffer delay than `--delay`; the +error names the `--delay` it needs. ## Play @@ -312,12 +315,15 @@ before *this* consumer skips it. Raising the first never delays playback. At stdin EOF, `import` keeps the finished broadcast up for its max-age, so a subscriber still catching up can drain it; Ctrl-C ends that early. -`export ts` takes `--delay` (default 500 ms) instead, like an SRT receiver's -latency: each frame is muxed that long after its decode time, all tracks in -decode order, so two exporters of one broadcast emit the same order. A frame -arriving after its deadline is dropped, and video resumes at its next -keyframe. The output's PCR follows the source's clock within what ISO/IEC -13818-1 allows. `--delay 0` writes frames in arrival order and drops nothing. +`export ts` takes `--delay` (default 1 s) instead, like an SRT receiver's +latency: the output runs that far behind the source, all tracks in one order, +so two exporters of one broadcast emit the same order. The send-ahead that fills +a receiver's buffers comes out of the same budget; 1 s fits a broadcast-sized +CPB. A source that sends no track ahead of its decode time, as RTMP and browser +publishers do, trails by the video's send-ahead on top. A frame arriving after +its deadline is dropped, and video resumes at its next keyframe. The output's +PCR follows the source's clock within what ISO/IEC 13818-1 allows. +`--delay 0` writes frames in arrival order and drops nothing. A stdout export ends with the broadcast. `export ts --linger 10s` waits that long for the same publisher instance to come back, and carries on with the same diff --git a/doc/bin/srt.md b/doc/bin/srt.md index 3188573aef0..7f7ee1efc6a 100644 --- a/doc/bin/srt.md +++ b/doc/bin/srt.md @@ -44,7 +44,8 @@ moq --connect https://relay.example.com/anon --broadcast event.hang import srt - ``` `--latency` (default 500 ms) sets the SRT receive buffer and doubles as the -export's jitter buffer, like `export ts --delay` in the [CLI](/bin/cli#export): -a frame arriving later than that is dropped. A `--connect` URL needs a +export's delay, like `export ts --delay` in the [CLI](/bin/cli#export), but no +less than that flag's 1 s default: the send-ahead that fills a receiver's +buffers comes out of the delay. A frame arriving later than that is dropped. A `--connect` URL needs a `streamid` query or a path; a listener bridges one `--broadcast` and ignores the stream id it is offered. The library is [`moq-srt`](https://docs.rs/moq-srt). diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index b9163901657..d04d0641472 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -349,6 +349,16 @@ These land with the next breaking release, not the 2026-09-23 train. `next()` and `for await` over a snapshot consumer rather than relying on type errors. On an untimed track nothing marks a group stale, so a `next()` reader that falls behind replays the whole backlog where it used to skip it. +- **`moq export ts --delay` defaults to 1 s and includes the send-ahead.** Each + frame still goes out up to the delay ahead of its decode time, now no further + than its decoder buffer holds, and that comes out of the same budget: the + output trails a TS source by the delay instead of twice it. With a multiplex + rate, video whose HRD declares a longer buffer delay than `--delay` stops the + export with the delay it needs named, so a broadcast feed run at + `--delay 500ms` needs `--delay 1s`. A source that sends every track at its + decode time (RTMP, a browser) trails by the delay plus the video's + send-ahead: 2 s at the new default, where `--delay 500ms` keeps the 1 s it + had. moq-srt egress runs at its SRT latency or 1 s, whichever is longer. ## Wire diff --git a/quest/m1/tstd/README.md b/quest/m1/tstd/README.md index 155cfbd6f8f..96314f6385a 100644 --- a/quest/m1/tstd/README.md +++ b/quest/m1/tstd/README.md @@ -19,7 +19,7 @@ first. 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 +pcrverify at the then-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, @@ -27,8 +27,7 @@ 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. +which the 1 s default `--delay` addresses, and 10 % loss is still to pass. 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) @@ -49,7 +48,6 @@ MB/AAC controls. Do not relabel the current subset a full standards check. ## Required -- [Send-ahead within the delay](/quest/m1/tstd/send-ahead.md) - total lag is `--delay`, send-ahead included, with a 1 s default - [PSI runs](/quest/m1/tstd/psi-runs.md) - the PAT and PMT are deduplicated and paced so the system buffers never overflow - [Video at its full leak](/quest/m1/tstd/video-leak.md) - a leak-bound video PID is admitted at its full Rbx, not about 3 % below it - [Mux overhead](/quest/m1/tstd/mux-overhead.md) - the PCR rides in the video's adaptation field and audio PES carry several frames, so a full CBR source re-muxes at its own rate diff --git a/quest/m1/tstd/send-ahead.md b/quest/m1/tstd/send-ahead.md deleted file mode 100644 index ddaa61b589e..00000000000 --- a/quest/m1/tstd/send-ahead.md +++ /dev/null @@ -1,36 +0,0 @@ -# [M] TS export lag stays within the delay, send-ahead included - -## Goal - -`moq export ts` output trails the source by `--delay`, not twice it. The -send-ahead window that pre-loads the receiver's buffers comes out of the same -budget, capped at what the decoder buffer can hold. The default becomes 1 s, -so broadcast-sized CPBs fit out of the box. - -## Plan - -Decided (2026-10-01). Found in the fixed-delay release -(#4645): frames are held until anchor + DTS + delay, and the schedule then -sends each unit up to another delay ahead of its DTS, so a mid-group joiner -trails the source by two delays. t0ms measured about 1.7 s of delivery at -500 ms: the two delays plus the join and the source's own send-ahead, so -carving alone should cut it by about one delay, not to 0.5 s. - -- One budget. A frame's release deadline is anchor + DTS + delay − its - send-ahead. The send-ahead is at most what the PID's decoder buffer can hold - ahead of its DTS (EB from the SPS HRD or the level, B per 13818-1); sending - further ahead only adds latency (0.93 s of reach on `hrd9m` against a 2 s - delay). -- The default `--delay` rises from 500 ms to 1 s. Broadcast CPBs need - 0.6-1 s of send-ahead (t0ms's CNN capture, `hrd9m`). A source that needs - more than the delay allows fails loud and names the `--delay` it needs. - Update `doc/bin/cli.md`, moq-srt egress (which passes its SRT latency as - the delay), and every example invocation. -- Test: a mid-group joiner's every slot goes out `delay` after the source sent - 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. -- 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/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index 0bcfe61cfa0..075c830eac8 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -1003,7 +1003,7 @@ impl ExportSink { /// A stdout sink's format and the options that apply to it. pub struct Stdout { pub format: SubscribeFormat, - /// The staleness budget, which `ts` also holds every frame for (`--delay`). + /// The staleness budget, which is also how far behind the source `ts` runs (`--delay`). pub max_delay: Duration, pub linger: Duration, /// Follow a replacement as a program switch (`ts` only). @@ -1051,10 +1051,11 @@ impl Container { #[derive(usage::Args, Clone)] #[usage(unknown_flags = "error", args_override_self = false)] pub struct Transport { - /// How long after its decode time each frame is written (e.g. `500ms`), like an SRT - /// receiver's latency. A frame that arrives later than this is dropped, and a stalled - /// group is skipped once it falls half this behind the newest content. - #[usage(long, default = "500ms")] + /// How far behind the source the output runs (e.g. `2s`), like an SRT receiver's latency, + /// including how far ahead of its decode time each frame is sent. A frame that arrives + /// later than this is dropped, and a stalled group is skipped once it falls half this + /// behind the newest content. + #[usage(long, default = "1s")] pub delay: crate::duration::Duration, /// How long to wait for the same publisher instance to come back once it ends (e.g. `10s`), @@ -1086,13 +1087,13 @@ pub struct Transport { impl Transport { fn deprecated(&self) -> moq_tokio::cli::Deprecated { - const HOLDS: &str = "it also holds every frame that long after its decode time"; + const BEHIND: &str = "it also sets how far behind the source the output runs"; let mut found = moq_tokio::cli::Deprecated::default(); if self.max_age.is_some() { - found.changed("--max-age", None, "--delay", HOLDS); + found.changed("--max-age", None, "--delay", BEHIND); } if self.latency_max.is_some() { - found.changed("--latency-max", None, "--delay", HOLDS); + found.changed("--latency-max", None, "--delay", BEHIND); } found } @@ -1173,7 +1174,7 @@ mod tests { }; export.sink.stdout().unwrap().max_delay }; - assert_eq!(stdout(&[]), Duration::from_millis(500)); + assert_eq!(stdout(&[]), Duration::from_secs(1)); assert_eq!(stdout(&["--delay", "2s"]), Duration::from_secs(2)); for old in ["--max-age", "--latency-max"] { let Err(err) = parse(&[old, "1s"]) else { diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index 042d1742b5b..0906f8e4fc9 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -177,8 +177,8 @@ pub struct SubscribeArgs { /// The format to write to stdout. pub format: SubscribeFormat, - /// How far playback may drift from the live edge before skipping groups. TS also - /// holds every frame this long after its decode time (`--delay`). + /// How far playback may drift from the live edge before skipping groups. TS also runs + /// this far behind the source (`--delay`). pub max_delay: Duration, /// How long to wait for the broadcast to come back after it ends (TS only). diff --git a/rs/moq-mux/benches/ts_schedule.rs b/rs/moq-mux/benches/ts_schedule.rs index 10dc7fc4cb5..fb738711df4 100644 --- a/rs/moq-mux/benches/ts_schedule.rs +++ b/rs/moq-mux/benches/ts_schedule.rs @@ -36,6 +36,7 @@ fn admission(c: &mut Criterion) { schedule::Buffer { rate: 2_000_000, size: Some(1_000_000), + reach: Duration::from_secs(1), }, ); } diff --git a/rs/moq-mux/src/codec/h264/mod.rs b/rs/moq-mux/src/codec/h264/mod.rs index 773708a498a..634a2c2c21e 100644 --- a/rs/moq-mux/src/codec/h264/mod.rs +++ b/rs/moq-mux/src/codec/h264/mod.rs @@ -747,6 +747,12 @@ pub(crate) mod fixtures { 0x67, 0xf4, 0x00, 0x15, 0x91, 0x9d, 0x02, 0x82, 0x1f, 0x89, 0xc0, 0x44, 0x00, 0x00, 0x03, 0x00, 0x04, 0x00, 0x00, 0x03, 0x00, 0xca, 0x7c, 0x50, 0xaa, 0x80, ]; + /// `bframes=1:force-cfr=1:nal-hrd=cbr:bitrate=9000:vbv-maxrate=9000:vbv-bufsize=9000`: a + /// contribution encoder's 9 Mbit CBR NAL HRD at 9 Mb/s, one second of buffer delay. + pub(crate) const SPS_HRD: &[u8] = &[ + 0x67, 0x64, 0x00, 0x1e, 0xac, 0xe4, 0x10, 0x9b, 0x01, 0x10, 0x00, 0x00, 0x03, 0x00, 0x10, 0x00, 0x00, 0x03, + 0x03, 0x2e, 0x04, 0x00, 0x00, 0x89, 0x54, 0x40, 0x00, 0x11, 0x2a, 0x8e, 0x4c, 0x30, 0x07, 0x8b, 0x16, 0x89, + ]; pub(crate) const PPS: &[u8] = &[0x68, 0xeb, 0xe3, 0xcb, 0x22, 0xc0]; } @@ -804,6 +810,28 @@ mod tests { assert_eq!(sps_framerate(&[0x67, 0x42, 0xc0, 0x1f, 0xde]), None); } + #[test] + fn sps_hrd_reads_the_nal_hrd() { + use crate::codec::video::{Hrd, Reorder}; + + assert_eq!( + sps_hrd(fixtures::SPS_HRD), + Some(Hrd { + bit_rate: 9_000_000, + cpb_size: 9_000_000 + }) + ); + // The bitstream restriction follows the HRD in the VUI, so it still reads past it. + assert_eq!( + sps_reorder(fixtures::SPS_HRD), + Some(Reorder { + depth: 1, + period: Some((2, 50)) + }) + ); + assert_eq!(sps_hrd(fixtures::SPS_IPB), None); + } + fn annexb_frame(nals: &[&[u8]]) -> Bytes { let mut buf = BytesMut::new(); for nal in nals { diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 2f7ff93cb4b..97c9fc205d6 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -9,9 +9,9 @@ //! position agrees with the values, and a pacing caller releases each slot at //! the instant it asserts. Video is carried as Annex-B, audio as ADTS AAC. //! -//! Every frame is muxed a fixed delay after its decode time ([`Export::with_delay`]), -//! so tracks interleave in `(DTS, PID)` order whatever the arrival skew between them, -//! and the output keeps the source's pace. +//! Every frame is muxed a fixed delay after its release time, its decode time less its +//! send-ahead ([`Export::with_delay`]), so tracks interleave in one order whatever the +//! arrival skew between them, and the output keeps the source's pace. //! //! Video flows through `ExportSource`, which normalizes every H.264/H.265 //! source to length-prefixed NALU plus a resolved avcC/hvcC (parsing in-band @@ -241,6 +241,8 @@ struct Track { buffer: Option, /// The AC-3 sync frame a passed-through PES left unfinished, for the next PES to complete. ac3_carry: Option, + /// The last frame's decode time and its jitter buffer key ([`Self::release_key`]). + released: Option<(Timestamp, Timestamp)>, } impl Track { @@ -260,6 +262,7 @@ impl Track { timing: Timing::default(), buffer: None, ac3_carry: None, + released: None, } } @@ -370,6 +373,39 @@ impl Track { Duration::from_nanos(TsPacket::SIZE as u64 * 8 * 1_000_000_000 / rate.max(1)) } + /// How far ahead of its decode time the track's units may go out under `delay`: as far + /// as [`schedule::ahead`] lets them, and nothing without a delay. + fn ahead(&self, delay: Duration) -> Duration { + if delay.is_zero() { + return Duration::ZERO; + } + let slots = schedule::ahead(self.buffer().as_ref(), schedule::slot(delay.as_nanos())); + PCR_INTERVAL * u32::try_from(slots).unwrap_or(u32::MAX) + } + + /// Where the jitter buffer orders a frame decoding at `decode` under `delay`: at its release + /// time, [`Self::ahead`] before its decode time, so it reaches the schedule as the first slot + /// it may ride is laid, and a slot goes out the delay after the source's clock rather than a + /// delay later still. Keys run a delay past release times, which no send-ahead exceeds, so a + /// frame near the start of the timeline is not cut short of its send-ahead. The clock anchors + /// on the track sent latest against these keys, so every track keeps the whole delay to + /// arrive in. A send-ahead that grew (a new SPS declaring a larger CPB) releases no frame + /// before the one ahead of it. + fn release_key(&mut self, decode: Timestamp, delay: Duration) -> anyhow::Result { + let lead = delay.saturating_sub(self.ahead(delay)); + let key = Duration::from(decode) + .checked_add(lead) + .context("MPEG-TS decode time past the end of the timeline")?; + let mut key = Timestamp::try_from(key)?; + if let Some((last, previous)) = self.released + && decode >= last + { + key = key.max(previous); + } + self.released = Some((decode, key)); + Ok(key) + } + /// Queue every held video frame whose DTS is settled, or all of them when `flush`. /// /// A held frame is ready no earlier than the frame read since the source was last found @@ -410,10 +446,18 @@ impl Track { let decode = dts .and_then(|ticks| Timestamp::from_scale(ticks, 90_000).ok()) .unwrap_or(frame.timestamp); + let key = self.release_key(decode, jitter.delay())?; + // Replaying anchors on the first frame, and the tracks arrive together rather than each + // sent ahead by its send-ahead: judged as arriving that much earlier, as a live source + // sends it, every track's first frames are on the clock whichever anchors it. + let ahead = match jitter.replaying() { + true => (Duration::from(decode) + jitter.delay()).saturating_sub(Duration::from(key)), + false => Duration::ZERO, + }; let arrival = Arrival { - arrived, - read, - decode, + arrived: arrived - ahead, + read: read - ahead, + decode: key, restart, skip, sync: frame.keyframe || !matches!(self.kind, Kind::Video(_)), @@ -469,7 +513,8 @@ impl Timing { /// The receiver's buffers (H.222.0 2.14.3.1, 2.17.2): EB is the HRD's CPB, else the /// level's, and packets go no faster than the slower of the transport buffer's Rx and the - /// leak from MB into EB, so neither MB nor TB fills. + /// leak from MB into EB, so neither MB nor TB fills. EB reaches the HRD's buffer delay + /// ahead, else what the level's CPB holds at its top rate. fn buffer(&self) -> Option { let level = self.level?; let (rate, cpb) = match self.hrd { @@ -479,9 +524,16 @@ impl Timing { Some(Buffer { rate: rate.min(level.leak), size: Some(usize::try_from(cpb / 8).unwrap_or(usize::MAX)), + reach: self.buffer_delay().unwrap_or_else(|| fill(level.cpb, level.leak)), }) } + /// How long the HRD's CPB takes to fill at its rate: how far ahead of its decode time the + /// source may send a picture, so the export has to as well. + fn buffer_delay(&self) -> Option { + self.hrd.map(|hrd| fill(hrd.cpb_size, hrd.bit_rate)) + } + /// The least reorder delay and lookahead the SPS declares, in ticks, so two exporters agree /// on them from their first keyframe whatever reordering each has seen. /// @@ -884,21 +936,31 @@ impl Export { self } - /// Mux each frame this long after its decode time, like an SRT receiver's TSBPD. + /// Mux each frame this long after its release time, like an SRT receiver's TSBPD: its + /// decode time less its send-ahead. + /// + /// The send-ahead comes out of the same budget. A frame may go out up to the delay + /// ahead of its decode time, as far as its PID's decoder buffer holds and as early as the + /// receiver's buffers admit, so a heavy passage rides the slots before it. Its release + /// time is that far before its decode time, so it is muxed just as the first slot it may + /// ride is laid, and each slot goes out the delay after its own time on the source's + /// clock rather than a delay later still. /// /// The clock is acquired before anything goes out: frames are held until a track starts - /// a new group, or for the delay at most, and the freshest of them sets the clock, so a - /// joiner runs at the delay from its first output. The output then keeps the source's - /// pace and muxes every track in `(DTS, PID)` order whatever the arrival skew between - /// them. A frame that arrives after its deadline is dropped, and a video track that - /// dropped one resumes at its next keyframe. A stalled group is skipped once it falls - /// half the delay behind the newest content (see [`Consumer`](crate::container::Consumer)), - /// so the group after it still arrives with the other half to spare. + /// a new group, or for the delay at most, and the freshest of them against its release + /// time sets the clock, so a joiner runs at the delay from its first output and every + /// frame has the whole delay to arrive in. A source that sends its video its send-ahead + /// early, as a TS mux does, is trailed by the delay; one that sends every track at its + /// decode time, by the delay and the video's send-ahead. The output then keeps the + /// source's pace and muxes every track in `(release time, PID)` order whatever the + /// arrival skew between them. A frame that arrives after its deadline is dropped, and a + /// video track that dropped one resumes at its next keyframe. A stalled group is skipped + /// once it falls half the delay behind the newest content (see + /// [`Consumer`](crate::container::Consumer)), so the group after it still arrives with + /// the other half to spare. /// - /// It is also how far ahead of its decode time a frame may go out, as early as the - /// receiver's buffers for its PID admit, so a heavy passage rides the slots before it - /// and the output trails the source by twice the delay. With a multiplex rate, a frame - /// that cannot arrive by its decode time fails the export. Defaults to + /// With a multiplex rate, a frame that cannot arrive by its decode time fails the export, + /// as does video whose HRD declares a buffer delay past the delay. Defaults to /// [`Duration::ZERO`], which holds nothing and sends each frame by its decode time. pub fn with_delay(mut self, delay: Duration) -> Self { self.delay = delay; @@ -1983,6 +2045,19 @@ impl Export { if let Some(buffer) = track.buffer() { self.schedule.set_buffer(pid, buffer); } + // A padded output cannot burst a picture late, so a CPB that the source may fill to + // its declared buffer delay needs that much send-ahead, all of it out of the delay. + if self.mux_rate.is_some() + && let Some(needs) = track.timing.buffer_delay() + { + let slots = schedule::slot(needs.as_nanos()); + anyhow::ensure!( + slots <= schedule::slot(self.delay.as_nanos()), + "MPEG-TS video on PID {pid} declares a {needs:.3?} decoder buffer delay (its HRD's CPB over its bit rate), past what a {:?} delay sends it ahead; raise the delay to {:?}", + self.delay, + PCR_INTERVAL * u32::try_from(slots).unwrap_or(u32::MAX), + ); + } let by = decode.as_nanos().saturating_sub(track.drain().as_nanos()); self.schedule.push( pid, @@ -2004,13 +2079,15 @@ impl Export { /// When the next grid slot is due on the jitter buffer's clock: once every frame that could /// ride it has gone out of the jitter buffer, so its contents depend on the frames alone, /// never on when they arrived, and the output keeps the clock's pace while media is queued - /// or still to decode. `None` without a delay, where frames settle the slots instead. + /// (in the schedule or still in the jitter buffer) or still to decode. `None` without a + /// delay, where frames settle the slots instead. fn slot_due(&self) -> Option<(u128, web_async::time::Instant)> { - if self.delay.is_zero() || self.psi.is_none() || self.schedule.is_empty() { + if self.delay.is_zero() || self.psi.is_none() || (self.schedule.is_empty() && self.jitter.is_empty()) { return None; } let (_, known) = self.schedule.upcoming()?; - let settled = known * PCR_INTERVAL.as_nanos() + self.max_drain().as_nanos(); + // On the jitter buffer's keys, which run a delay past release times ([`Track::release_key`]). + let settled = known * PCR_INTERVAL.as_nanos() + self.max_drain().as_nanos() + self.delay.as_nanos(); let settled = Timestamp::from_micros(u64::try_from(settled / 1_000).ok()?).ok()?; Some((known, self.jitter.at(settled)?)) } @@ -2501,8 +2578,16 @@ fn video_level(config: &VideoConfig, name: &str) -> Level { }) } +/// How long `bits` take to arrive at `rate` bits per second: how far ahead of its decode +/// time a decoder buffer that size, filling at that rate, holds a unit. +fn fill(bits: u64, rate: u64) -> Duration { + let nanos = u128::from(bits) * 1_000_000_000 / u128::from(rate.max(1)); + Duration::from_nanos(u64::try_from(nanos).unwrap_or(u64::MAX)) +} + /// An audio stream's buffers in a receiver (H.222.0 2.4.2.3): by channel count for ADTS -/// AAC (and Opus, which borrows them), 2 Mb/s and the codec's main buffer for the rest. +/// AAC (and Opus, which borrows them), 2 Mb/s and the codec's main buffer for the rest. B +/// reaches as far ahead as it takes to fill at Rx. fn audio_buffer(config: &AudioConfig, kind: &Kind) -> Buffer { let by_channels = || match config.channel_count { 0..=2 => (2_000_000, 3_584), @@ -2518,7 +2603,11 @@ fn audio_buffer(config: &AudioConfig, kind: &Kind) -> Buffer { Kind::Eac3 => (2_000_000, 12_896), _ => (2_000_000, 3_584), }; - Buffer { rate, size: Some(size) } + Buffer { + rate, + size: Some(size), + reach: fill(size as u64 * 8, rate), + } } /// The DVB AC-3 descriptor's tag (ETSI EN 300 468 6.2.1), marking AC-3 as private data. @@ -2543,10 +2632,12 @@ fn verbatim_buffer(kind: &Kind, descriptors: &[catalog::Descriptor]) -> Option Some(Buffer { rate: 2_000_000, size: Some(5_696), + reach: fill(5_696 * 8, 2_000_000), }), TELETEXT_DESCRIPTOR => Some(Buffer { rate: 6_750_000, size: None, + reach: Duration::ZERO, }), _ => None, }) @@ -3113,6 +3204,7 @@ mod tests { Some(Buffer { rate: 6_750_000, size: None, + reach: Duration::ZERO, }) ); assert_eq!(verbatim_buffer(&kind, &[descriptor(0x0a)]), None); diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 214d4b870c1..f3ddef3d75e 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -843,13 +843,15 @@ async fn export_pcr_wraps_below_zero_at_start() { .insert(track.name().to_string(), cfg); } let mut producer = Producer::new(track, HangContainer::Legacy(crate::container::Kind::Data)); + // One group, so the exporter joining at the live edge reads it from the frame decoding in + // slot 0: audio goes out no earlier than its own slot. for i in 0..4u64 { producer .write(Frame { timestamp: Timestamp::from_micros(i * 20_000).unwrap(), duration: None, payload: Bytes::from_static(&[0x01, 0x02, 0x03, 0x04]), - keyframe: true, + keyframe: i == 0, }) .unwrap(); } @@ -5024,8 +5026,9 @@ async fn tune_in_does_not_wait_on_dropped_audio() { rig.video(tick); } out.extend(poll_frames(&mut export)); - // Past the keyframe's deadline, and far enough on that a later frame settles its slot. - tokio::time::advance(delay + Duration::from_micros(4 * VIDEO_US)).await; + // Past the audio's deadline, a delay on from the video's since audio is not sent ahead, + // and far enough on that a later frame settles its slot. + tokio::time::advance(2 * delay + Duration::from_micros(4 * VIDEO_US)).await; out.extend(poll_frames(&mut export)); assert!(!out.is_empty(), "the tune-in waited on audio it had dropped"); } @@ -6044,7 +6047,13 @@ async fn pcr_stays_among_the_bytes_across_reordered_tracks() { .with_delay(RECORDING_MAX_AGE); let frames = drain_frames(&mut exporter).await; let pcrs = media_pcrs(&frames); - assert!(pcrs.len() > 50, "expected the full feed, got {} PCRs", pcrs.len()); + assert_eq!(exporter.dropped(), 0, "expected the full feed"); + // The joiner reads the newest group, 400 ms of video sent at most its 375 ms reach early. + assert!( + pcrs.len() > 15, + "expected a clock across the group, got {} PCRs", + pcrs.len() + ); let gaps: Vec = pcrs.windows(2).map(|w| w[1].0 - w[0].0).collect(); assert_eq!( @@ -6765,6 +6774,53 @@ async fn reordered_video_loses_nothing_on_a_clean_path() { assert_on_time(&out); } +/// Padded video whose HRD declares a longer buffer delay than the export's fails with its +/// first picture, naming the delay it needs, rather than once the source fills its CPB and a +/// picture misses its deadline. At that delay it runs. +#[tokio::test(start_paused = true)] +async fn padded_video_needs_the_delay_its_hrd_declares() { + use crate::codec::h264::fixtures::{PPS, SPS_HRD}; + + let waiter = kio::Waiter::noop(); + for (delay, refused) in [(Duration::from_millis(500), true), (Duration::from_secs(1), false)] { + let mut rig = Reordered::new(SPS_HRD, PPS, &[]).await; + let mut export = rig.export(delay).await.with_mux_rate(2_000_000); + let start = tokio::time::Instant::now(); + let mut out = Vec::new(); + let mut failed = None; + 'run: for tick in 0..TICKS / 2 { + tokio::time::sleep_until(start + Duration::from_micros(tick * VIDEO_US)).await; + rig.video(tick); + while rig.audio_before(tick + 1) {} + while let std::task::Poll::Ready(frame) = export.poll_next(&waiter) { + match frame { + Ok(Some(frame)) => out.push(frame), + Ok(None) => break, + Err(err) => { + failed = Some(err.to_string()); + break 'run; + } + } + } + } + if refused { + let err = failed.expect("a 500 ms delay cannot send a 1 s CPB far enough ahead"); + assert!(err.contains("raise the delay to 1s"), "{err}"); + continue; + } + assert_eq!(failed, None, "a 1 s delay sends a 1 s CPB far enough ahead"); + rig.finish(); + out.extend(drain_frames(&mut export).await); + assert_eq!(export.dropped(), 0, "a clean path drops nothing"); + assert_eq!( + video_timing(&out, ..).len() as u64, + TICKS / 2, + "every video frame went out" + ); + assert_on_time(&out); + } +} + /// Two exporters of a broadcast padded to a multiplex rate, one joining a second late, lay the /// same packets once the joiner's first group is out: how many packets a slot carries, the PCR /// it opens with and which units ride it are functions of the media, not of when either diff --git a/rs/moq-mux/src/container/ts/export_timing_test.rs b/rs/moq-mux/src/container/ts/export_timing_test.rs index 79935811062..e5e33fe8f43 100644 --- a/rs/moq-mux/src/container/ts/export_timing_test.rs +++ b/rs/moq-mux/src/container/ts/export_timing_test.rs @@ -880,12 +880,13 @@ async fn a_joiner_keeps_the_system_clock_in_tolerance() { } /// A receiver that joins mid-group runs at the delay from its first output: every slot goes -/// out a fixed lag after the source sent its media (the delay before release, and the delay -/// the schedule sends ahead of the decode time), rather than that plus how old the group it -/// joined on was. +/// out the delay after a TS source sent it, rather than that plus how old the group it joined +/// on was, or plus the send-ahead again. The source sends its video as far ahead as the +/// export does (the level's CPB reaches past the delay, so the whole delay) and its audio at +/// its decode time, which is the source's clock. #[tokio::test(start_paused = true)] async fn a_joiner_runs_at_the_delay_from_its_first_output() { - let mut live = Live::new(1.0, 0).await; + let mut live = Live::new(1.0, DELAY.as_micros() as i64).await; live.run(JOIN, &mut [], |_| false).await; let mut leg = live.join(Duration::ZERO).await; live.run(JOIN + 10_000_000 / VIDEO_US, &mut [&mut leg], |_| false).await; @@ -894,13 +895,16 @@ async fn a_joiner_runs_at_the_delay_from_its_first_output() { let held: Vec = leg .out .iter() - .map(|(sent, frame)| sent.saturating_duration_since(live.sent(frame.timestamp.as_micros() as u64))) + .map(|(sent, frame)| { + let media = frame.timestamp.as_micros() as u64; + sent.saturating_duration_since(live.send_times(media, media).1) + }) .collect(); assert!(held.len() > 100, "too little output to judge: {}", held.len()); let slot = Duration::from_millis(SLOT_MS as u64); for (i, held) in held.iter().enumerate() { assert!( - *held >= 2 * DELAY && *held <= 2 * DELAY + 2 * slot, + *held >= DELAY && *held <= DELAY + 2 * slot, "slot {i} went out {held:?} after the source sent it, against a {DELAY:?} delay" ); } diff --git a/rs/moq-mux/src/container/ts/schedule.rs b/rs/moq-mux/src/container/ts/schedule.rs index ef3c8dedbd6..d7574a42d4c 100644 --- a/rs/moq-mux/src/container/ts/schedule.rs +++ b/rs/moq-mux/src/container/ts/schedule.rs @@ -37,6 +37,16 @@ pub(super) fn slot(nanos: u128) -> u128 { nanos / PCR_INTERVAL.as_nanos() } +/// How many slots ahead of its due slot a unit on a PID with `buffer` may go out, within a +/// `window` of slots: as far as its decoder buffer reaches, or only the slot before its own +/// where no decoder buffer bounds it. +pub(super) fn ahead(buffer: Option<&Buffer>, window: u128) -> u128 { + match buffer { + Some(buffer) if buffer.size.is_some() => window.min(slot(buffer.reach.as_nanos())), + _ => 1, + } +} + /// One slot in system clock ticks. const SLOT_TICKS: u128 = PCR_INTERVAL.as_nanos() * SYSTEM_CLOCK / 1_000_000_000; @@ -70,6 +80,9 @@ pub(super) struct Buffer { /// first packet until it decodes. `None` bounds nothing, so the PID's units go out only /// in the slot before their own. pub size: Option, + /// How far ahead of its decode time the decoder buffer holds a unit: its size over the + /// rate it fills at. Sending further ahead only adds latency. + pub reach: Duration, } impl Buffer { @@ -77,6 +90,7 @@ impl Buffer { pub const SYSTEM: Self = Self { rate: 1_000_000, size: None, + reach: Duration::ZERO, }; /// The packets one slot may carry on the PID: what its transport buffer passes on within @@ -381,9 +395,11 @@ impl Slot { /// /// Each slot's packets go earliest deadline first across PIDs, each PID in its own order, and /// each unit as soon as its PID's buffers in a receiver admit it. Padded output checks -/// transport occupancy and decoder removal at exact packet positions. A unit may go out up to the `window` before -/// its due slot, which keeps that far ahead of a heavy passage, so the output trails the -/// decode times by the window. +/// transport occupancy and decoder removal at exact packet positions. A unit may go out as far +/// ahead of its due slot as its PID's decoder buffer reaches, within the `window`, which keeps +/// that far ahead of a heavy passage ([`ahead`]). A slot is laid once no unit still to be +/// pushed could go out in it, so a caller that pushes each unit that far ahead of its due slot +/// has the output trail the decode times by no more than the window. /// /// With a multiplex rate each slot carries exactly what the rate allows, padded with null /// packets, and a unit that is not complete by its exact deadline fails the export rather than @@ -395,7 +411,7 @@ impl Slot { pub(super) struct Schedule { /// In push order, which is each PID's decode order. units: VecDeque, - /// Slots before its due slot a unit may go out: the export's delay. + /// Slots before its due slot a unit may go out at most: the export's delay. window: u128, /// The multiplex rate, in bits per second. rate: Option, @@ -539,15 +555,13 @@ impl Schedule { self.ended = false; } - /// The first slot `unit` may go out in: a window ahead of its due slot, or only the slot - /// before it for a PID whose decoder buffer bounds nothing, and never before the slot - /// after the unit pushed ahead of it needs. + /// The first slot `unit` may go out in: [`ahead`] of its due slot, and never before the + /// slot after the unit pushed ahead of it needs. fn release(&self, unit: &Unit) -> u128 { - let ahead = match self.buffers.get(&unit.pid).and_then(|buffer| buffer.size) { - _ if unit.late => return 0, - Some(_) => self.window, - None => 1, - }; + if unit.late { + return 0; + } + let ahead = ahead(self.buffers.get(&unit.pid), self.window); unit.due.saturating_sub(ahead).min(unit.start) } @@ -559,23 +573,23 @@ impl Schedule { (None, Some(first)) => Some(first), // Skip the empty slots of a long gap, keeping the second before what comes next. (Some(next), first) => { - let target = first.or(known.map(|known| known.saturating_sub(self.window))); + let target = first.or(known); Some(next.max(target.map_or(0, |target| target.saturating_sub(BACKFILL)))) } } } - /// The next slot to lay out, and the first slot a unit still to be pushed could be due - /// in once every unit that may ride it is known: the `known` that settles it. + /// The next slot to lay out, and the first slot a unit still to be pushed could go out in + /// once every unit that may ride it is known: the `known` that settles it. pub fn upcoming(&self) -> Option<(u128, u128)> { let index = self.index(None)?; - Some((index, index + self.window + 1)) + Some((index, index + 1)) } /// Lay out the next slot, if it is settled. /// - /// `known` is the first slot a unit still to be pushed could be due in, which settles - /// every slot whose window ends before it; `None` means nothing more is coming, so every + /// `known` is the first slot a unit still to be pushed could go out in ([`Self::release`]), + /// which settles every slot before it; `None` means nothing more is coming, so every /// queued unit goes out and the clock runs on to the last decode time. pub fn next(&mut self, known: Option) -> anyhow::Result> { if known.is_none() && self.is_empty() { @@ -584,7 +598,7 @@ impl Schedule { let Some(index) = self.index(known) else { return Ok(None); }; - if known.is_some_and(|known| index + self.window >= known) { + if known.is_some_and(|known| index >= known) { return Ok(None); } self.next = Some(index + 1); @@ -753,9 +767,7 @@ impl Schedule { continue; } if !self.ended && !unit.late && pid == unit.pid && done > unit.timing.decode as i128 { - anyhow::bail!( - "MPEG-TS output missed a decode deadline on PID {pid} at {rate} b/s; raise the delay or the multiplex rate" - ); + return Err(self.missed(pid, rate)); } self.transport.insert(tb, done); out.positions.as_mut().unwrap().push(position); @@ -804,10 +816,7 @@ impl Schedule { .iter() .find(|unit| !unit.late && unit.timing.by as i128 <= end && unit.remaining() > 0) { - anyhow::bail!( - "MPEG-TS output missed a decode deadline on PID {} at {rate} b/s; raise the delay or the multiplex rate", - unit.pid - ); + return Err(self.missed(unit.pid, rate)); } for unit in self.units.iter().filter(|unit| unit.remaining() == 0 && unit.held > 0) { self.decoding.push_back((unit.pid, unit.timing.decode, unit.held)); @@ -816,6 +825,27 @@ impl Schedule { Ok(out) } + /// The error for a unit on `pid` that misses its decode deadline at `rate`, naming what + /// would carry it: the delay at which it goes as far ahead as its decoder buffer holds, + /// where the window cut it short, else a faster multiplex. + fn missed(&self, pid: u16, rate: u64) -> anyhow::Error { + let reach = self + .buffers + .get(&pid) + .filter(|buffer| buffer.size.is_some()) + .map(|buffer| slot(buffer.reach.as_nanos())) + .filter(|&reach| reach > self.window); + match reach { + Some(reach) => anyhow::anyhow!( + "MPEG-TS output missed a decode deadline on PID {pid} at {rate} b/s; raise the delay to {:?}, which sends it as far ahead as its decoder buffer holds, or the multiplex rate", + PCR_INTERVAL * u32::try_from(reach).unwrap_or(u32::MAX) + ), + None => anyhow::anyhow!( + "MPEG-TS output missed a decode deadline on PID {pid} at {rate} b/s, sent as far ahead as its decoder buffer holds; raise the multiplex rate" + ), + } + } + /// How many of each unit's packets slot `index` carries, at most `budget` in all. /// /// Earliest deadline first across PIDs. A PID whose unit stops short (its buffers full, @@ -919,10 +949,14 @@ mod tests { /// 40 packets per slot, the clock packet included. const RATE: u64 = 40 * PACKET; + /// A decoder buffer's reach past every window here, so the window bounds how far ahead a + /// unit goes. + const REACH: Duration = Duration::from_secs(1); /// A video-like buffer: far more than a slot passes on, and a large decoder buffer. const VIDEO: Buffer = Buffer { rate: 100_000_000, size: Some(1_000_000), + reach: REACH, }; /// Every slot until the schedule is empty: (index, packets per PID, nulls). @@ -1025,6 +1059,27 @@ mod tests { assert_eq!(clock, [36, 37, 38, 39, 40], "the clock runs on to its decode time"); } + /// However long the window, a unit goes out no further ahead of its due slot than its + /// decoder buffer reaches. + #[test] + fn a_unit_goes_out_no_further_ahead_than_its_buffer_reaches() { + let mut schedule = Schedule::new(Duration::from_millis(500)); + schedule.set_rate(Some(RATE)); + schedule.set_buffer( + 1, + Buffer { + reach: Duration::from_millis(100), + ..VIDEO + }, + ); + schedule.push(1, timing(1_000), unit(1, 3), true).unwrap(); + assert_eq!( + drain(&mut schedule)[0].0, + 36, + "the buffer's reach ahead of its due slot" + ); + } + /// A burst bigger than a slot fills the slots from its release on. #[test] fn a_burst_fills_the_slots_from_its_release() { @@ -1039,15 +1094,29 @@ mod tests { assert_eq!(sent, [(36, 39), (37, 39), (38, 22), (39, 0), (40, 0)]); } - /// A burst the window cannot carry by its due slot fails the export. + /// A burst the window cannot carry by its due slot fails the export, naming the delay that + /// sends it as far ahead as its decoder buffer holds. Once the buffer rather than the + /// window stops it, only a faster multiplex helps. #[test] fn a_burst_too_big_for_the_window_fails() { - let mut schedule = Schedule::new(Duration::from_millis(50)); - schedule.set_rate(Some(RATE)); - schedule.set_buffer(1, VIDEO); - schedule.push(1, timing(1_000), unit(1, 200), true).unwrap(); - let err = std::iter::from_fn(|| schedule.next(None).transpose()).find_map(Result::err); - assert!(err.is_some(), "a burst past the window must fail the export"); + for (window, reach, fix) in [ + (50, 1_000, "raise the delay to 1s"), + (1_000, 50, "raise the multiplex rate"), + ] { + let mut schedule = Schedule::new(Duration::from_millis(window)); + schedule.set_rate(Some(RATE)); + schedule.set_buffer( + 1, + Buffer { + reach: Duration::from_millis(reach), + ..VIDEO + }, + ); + schedule.push(1, timing(1_000), unit(1, 200), true).unwrap(); + let err = std::iter::from_fn(|| schedule.next(None).transpose()).find_map(Result::err); + let err = err.expect("a burst past the window must fail the export").to_string(); + assert!(err.contains(fix), "window {window} ms, reach {reach} ms: {err}"); + } } /// Once every source has ended, a unit the window cannot carry by its due slot is the @@ -1076,6 +1145,7 @@ mod tests { let small = Buffer { rate: 100_000_000, size: Some(10 * PAYLOAD), + reach: REACH, }; schedule.set_buffer(1, small); schedule.set_ended(true); @@ -1125,6 +1195,7 @@ mod tests { let audio = Buffer { rate: 2_000_000, size: Some(100_000), + reach: REACH, }; schedule.set_buffer(1, audio); for at in 0..20 { @@ -1143,6 +1214,7 @@ mod tests { let audio = Buffer { rate: 2_000_000, size: Some(100_000), + reach: REACH, }; schedule.set_buffer(1, audio); schedule.set_clock(1); @@ -1162,6 +1234,7 @@ mod tests { let slow = Buffer { rate: 76_800, size: Some(100_000), + reach: REACH, }; schedule.set_buffer(1, slow); schedule.set_clock(1); @@ -1181,6 +1254,7 @@ mod tests { Buffer { rate: 76_800, size: Some(100_000), + reach: REACH, }, ); schedule.push(1, timing(1_000), unit(1, 4), false).unwrap(); @@ -1201,6 +1275,7 @@ mod tests { let small = Buffer { rate: 100_000_000, size: Some(10 * PAYLOAD), + reach: REACH, }; schedule.set_buffer(1, small); schedule.push(1, timing(1_000), unit(1, 8), true).unwrap(); @@ -1240,6 +1315,7 @@ mod tests { Buffer { rate: 2_000_000, size: Some(2_592), + reach: REACH, }, ); let error = schedule @@ -1264,6 +1340,7 @@ mod tests { Buffer { rate: 2_000_000, size: Some(2 * PAYLOAD), + reach: REACH, }, ); schedule @@ -1310,6 +1387,7 @@ mod tests { Buffer { rate: 2_000_000, size: Some(2_592), + reach: REACH, }, ); let bytes = bitrate / 8 * 32 / 1_000; @@ -1417,8 +1495,9 @@ mod tests { schedule.set_buffer(1, VIDEO); schedule.push(1, timing(1_000), unit(1, 8), true).unwrap(); schedule.push(1, timing(1_100), unit(1, 100), false).unwrap(); - // Unpadded, both go out as soon as they are released, a window ahead. - let first: Vec<_> = std::iter::from_fn(|| schedule.next(Some(slot(ms(1_100)))).unwrap()) + // Unpadded, both go out as soon as they are released, a window ahead: the slots before + // the second unit's release are settled. + let first: Vec<_> = std::iter::from_fn(|| schedule.next(Some(slot(ms(1_000)))).unwrap()) .map(|slot| (slot.index, slot.packets.len() / TsPacket::SIZE, slot.nulls)) .collect(); assert_eq!(first, [(36, 8, 0), (37, 0, 0), (38, 0, 0), (39, 0, 0)]); @@ -1442,6 +1521,7 @@ mod tests { Buffer { rate: 2_000_000, size: Some(100_000), + reach: REACH, }, ); schedule.push(1, timing(1_000), unit(1, 50), true).unwrap(); @@ -1570,7 +1650,15 @@ mod tests { packets, keyframe: true, units: vec![video.into()], - caps: HashMap::from([(video.into(), Buffer { rate: RX, size: None }.per_slot())]), + caps: HashMap::from([( + video.into(), + Buffer { + rate: RX, + size: None, + reach: Duration::ZERO, + } + .per_slot(), + )]), positions: None, }; let mut null = unit(0, 1); @@ -1609,10 +1697,12 @@ mod tests { Buffer { rate: 7_833_600, size: None, + reach: Duration::ZERO, }, Buffer { rate: 8_160_000, size: None, + reach: Duration::ZERO, }, ); let slot = Slot { diff --git a/rs/moq-mux/src/jitter.rs b/rs/moq-mux/src/jitter.rs index 5f4fa61a94b..4bfb8e6c9b8 100644 --- a/rs/moq-mux/src/jitter.rs +++ b/rs/moq-mux/src/jitter.rs @@ -282,6 +282,11 @@ impl Buffer { } } + /// How long past its decode time each frame is held. + pub fn delay(&self) -> Duration { + self.delay + } + /// The tracks an acquisition waits to hear from, two delays at most, before it anchors: any /// of them may be the one sent latest against its decode time. pub fn expect(&mut self, keys: impl IntoIterator) { @@ -296,6 +301,11 @@ impl Buffer { self } + /// Whether each clock anchors on its first frame ([`Self::replay`]). + pub fn replaying(&self) -> bool { + self.replay + } + /// Queue a frame, or drop it if it cannot make its deadline. Fails once the source's clock /// runs further off ours than the clock may follow. pub fn push(&mut self, key: K, arrival: Arrival) -> anyhow::Result { diff --git a/rs/moq-srt/src/server.rs b/rs/moq-srt/src/server.rs index 9757e69645c..92e3a81ae58 100644 --- a/rs/moq-srt/src/server.rs +++ b/rs/moq-srt/src/server.rs @@ -184,8 +184,8 @@ pub struct Server { _listener: SrtListener, incoming: SrtIncoming, local_addr: SocketAddr, - /// The negotiated SRT receive latency, reused as the egress skip threshold on - /// each [`Subscribe`] (see [`crate::ts::Subscriber::new`]). + /// The negotiated SRT receive latency, reused as the egress delay (at least a + /// second) on each [`Subscribe`] (see [`crate::ts::Subscriber::new`]). latency: Duration, } @@ -193,8 +193,8 @@ impl Server { /// Bind an SRT listener on `addr` (SRT has no well-known port; 9000 is common). /// /// `latency` is the SRT receive latency, negotiated at handshake time; pass - /// `None` for a sensible default (500ms). It doubles as the egress skip - /// threshold for [`Subscribe`] requests. + /// `None` for a sensible default (500ms). It doubles as the egress delay for + /// [`Subscribe`] requests, but no less than a second. pub async fn bind(addr: SocketAddr, latency: impl Into>) -> Result { let latency = latency.into().unwrap_or(DEFAULT_LATENCY); @@ -276,7 +276,7 @@ struct Pending { /// fields out of it (e.g. a token in `u=` or a custom key). stream_id: Option, peer: SocketAddr, - /// The SRT receive latency, reused as the egress skip threshold on a subscribe. + /// The SRT receive latency, reused as the egress delay (at least a second) on a subscribe. latency: Duration, /// Retention declared on the media tracks an ingest mints, or `None` for hang's own /// default. Override with [`Publish::with_max_age`]. diff --git a/rs/moq-srt/src/ts.rs b/rs/moq-srt/src/ts.rs index 8a2d36cb41e..010d828d5ae 100644 --- a/rs/moq-srt/src/ts.rs +++ b/rs/moq-srt/src/ts.rs @@ -160,10 +160,14 @@ impl Publisher { } } +/// The least delay an egress muxes at, `moq export ts`'s default: the send-ahead that fills a +/// receiver's buffers comes out of the delay, and a broadcast-sized CPB needs a second of it. +const MIN_DELAY: Duration = Duration::from_secs(1); + /// How an egress treats its broadcast ending or being replaced. #[derive(Clone, Copy, Debug, Default)] pub(crate) struct Options { - /// The muxer's jitter-buffer delay ([`Subscriber::new`]). + /// The muxer's delay, at least [`MIN_DELAY`] ([`Subscriber::new`]). pub latency: Duration, /// How long a return or stitched replacement has to supply its first catalog. pub linger: Duration, @@ -188,8 +192,8 @@ pub struct Subscriber { impl Subscriber { /// Resolve the broadcast at `path` in the origin and prepare to mux it to TS. /// - /// `options.latency` is the muxer's jitter-buffer delay: each frame is muxed that long after - /// its decode time, a frame arriving later is dropped, and a stalled group is + /// `options.latency` is the muxer's delay, but no less than [`MIN_DELAY`]: the output runs + /// that far behind the source, a frame arriving later is dropped, and a stalled group is /// skipped after half of it. We reuse the locally configured SRT receive latency for /// it, the same budget an SRT hop gives a packet. It's the configured value, /// not the handshake result (srt-tokio doesn't expose the negotiated latency), @@ -210,7 +214,7 @@ impl Subscriber { let source = moq_mux::Source::new(origin.clone(), broadcast); let export = ts::Export::with_ts(source, moq_mux::catalog::CatalogFormat::Hang) .await? - .with_delay(options.latency); + .with_delay(options.latency.max(MIN_DELAY)); let follower = ts::Follower::new(export)? .with_linger(options.linger) .with_stitch(options.stitch); diff --git a/test/justfile b/test/justfile index fdacef8cd45..24a68e1354e 100644 --- a/test/justfile +++ b/test/justfile @@ -122,7 +122,7 @@ drill-sensitivity *args: # (use a real capture), `--live` (grade PCR release timing and byte position off # the pipe instead, which a capture cannot carry; nightly runs this arm), # `--open-gop` (an open-GOP clip whose leading pictures must survive), `--hrd` -# (1080p video filling a broadcast-sized CPB), `--delay 1s` (the exporter's). See +# (1080p video filling a broadcast-sized CPB), `--delay 2s` (the exporter's). See # ts/README.md. # Check the subscriber's MPEG-TS output for IRD compliance. diff --git a/test/ts/README.md b/test/ts/README.md index 583ac1a7223..92b4ddcecc5 100644 --- a/test/ts/README.md +++ b/test/ts/README.md @@ -35,7 +35,7 @@ just test ts --pair # two exporters of one broadcast, grade table an just test ts --open-gop # open-GOP clip; its leading pictures must survive just test ts --hrd # 1080p video filling a broadcast-sized 9 Mbit CPB just test ts --headroom # the same with four audio PIDs, muxed above the video's Rx -just test ts --delay 1s # pass the exporter's --delay +just test ts --delay 2s # pass the exporter's --delay ``` `--live` swaps the analyzer, not the rig: the same round-trip runs, but the @@ -288,7 +288,7 @@ the total and reports the rate over the tail of the sample beside it. A sender that buffers builds a standing lag once and then runs at the media rate: the lag is a constant offset no receiver can see, and it cannot grow past the latency budget the sender is allowed to hold, so set `--drift-ms` to that budget -(`export ts --delay`, 500 ms by default). A pipe that is not running at the +(`export ts --delay`, 1 s by default). A pipe that is not running at the media rate never stops accumulating and so breaches any fixed bound given a long enough sample. The tail rate is what tells the two apart, and it needs a sample longer than the lag takes to build: measured against the grid-sliced exporter, @@ -364,7 +364,7 @@ outgrow a 6 kB slot, so the exporter has to spread each over the slots before it DTS; CI runs that too (`just test ts --bitrate 2000000`). `--hrd` goes further: a 1080p encode with a 9 Mbit NAL HRD kept near full by noise, the shape of a contribution encoder's output, which sends pictures most of a second ahead of their -decode time and loads the decoder buffer past 60 % at the default delay (the recipe +decode time and fills the decoder buffer to its declared size at the default delay (the recipe moq-dev/moq#4645 graded with; CI runs it too). Every other clip muxes at or below the video's Rx, where its transport buffer cannot fill. `--headroom` puts that video beside three MPEG-1 Layer II PIDs and an AC-3 one in a 12.5 Mb/s multiplex, above diff --git a/test/ts/pcr-timing.py b/test/ts/pcr-timing.py index 6d0491b57d0..69cb6f435cb 100755 --- a/test/ts/pcr-timing.py +++ b/test/ts/pcr-timing.py @@ -670,10 +670,10 @@ def main(): ap.add_argument( "--drift-ms", type=float, - default=500.0, + default=1000.0, help="bound on accumulated release drift, being the standing lag the sender may " "hold; set it to the sender's latency budget (moq export ts --delay, " - "itself 500ms by default)", + "itself 1s by default)", ) ap.add_argument( "--rate-ppm", diff --git a/test/ts/run.sh b/test/ts/run.sh index 5ac319a7c03..541139044c1 100755 --- a/test/ts/run.sh +++ b/test/ts/run.sh @@ -21,7 +21,7 @@ # ./run.sh --open-gop # open-GOP clip; its leading pictures must survive # ./run.sh --hrd # 1080p video filling a broadcast-sized 9 Mbit CPB # ./run.sh --headroom # the same with four audio PIDs, muxed above the video's Rx -# ./run.sh --delay 1s # pass the exporter's --delay +# ./run.sh --delay 2s # pass the exporter's --delay # `--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