diff --git a/quest/m1/tstd/README.md b/quest/m1/tstd/README.md index f681316236a..d47867d71a5 100644 --- a/quest/m1/tstd/README.md +++ b/quest/m1/tstd/README.md @@ -30,3 +30,4 @@ nightly. - [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 +- [Burst](/quest/m1/tstd/burst.md) - catalog `burst` sizes the send-ahead window, so `--delay` is only network margin diff --git a/quest/m1/tstd/burst.md b/quest/m1/tstd/burst.md new file mode 100644 index 00000000000..943974a15eb --- /dev/null +++ b/quest/m1/tstd/burst.md @@ -0,0 +1,73 @@ +# [L] TS export sizes its send-ahead from each rendition's burst + +## Goal + +A TS→MoQ→TS remux reproduces the source's buffer timing with no tuning. +Each hang catalog rendition can declare `burst`: its largest frame in bytes, +normally the I-frame. `moq export ts` sizes its send-ahead window from it and +fixes it at start, so `--delay` only adds network margin on top. + +## Plan + +Decided (2026-09-30): + +- Why: the export's minimum latency (no network delay or loss, mux rate still + achievable) is a property of the media, so the catalog carries it. `--delay` + is the receiver's margin for its own network and nothing else. Today + [fixed-delay release](/quest/m1/tstd/delay.md) uses one `--delay` for both. +- `burst` is the largest frame in bytes. It is not the HRD leaky-bucket + backlog: the largest frame is simpler for a publisher to declare and for an + importer to measure. A run of several large frames isn't covered, so + `jitter` and `--delay` absorb it. +- Send-ahead window: the largest `burst ÷ bitrate` over all renditions, which + is the time to send each rendition's largest frame at its own rate. + - When `burst` or `bitrate` is missing, video defaults to 1 s (the common + VBV default) and audio to one frame duration (true CBR). + - Hold: catalog `jitter` (plus `delay`) + the window + `--delay`. +- The export fixes the window and hold at start and never grows them. A frame + larger than its rendition's `burst` fails loud, as does a burst that doesn't + fit the window at the mux rate. Late frames stay a strict drop. +- Keep `mpegts.muxRate`; don't replace it for now. Deriving the rate from + rendition `bitrate`s was considered, but it needs every carried track to + declare one: text and future SCTE-35/ID3 sections have no `bitrate`, and + the export would have to add its own PSI/SI/PCR overhead. The mux rate stays + `--mux-rate` or `mpegts.muxRate`. Without either, the output is unpadded as + today, and `burst` only sizes the hold. +- `jitter` keeps its meaning, which is reordering and flush spread. The + importer doesn't fold buffer delay into it, and TS/FLV export keep sizing + their DTS reserve from it. +- The field stays named `burst` and in bytes, so it doesn't depend on the mux + rate. +- `ts import`: + - Takes `burst` from the source's declared HRD (the largest access unit, + bounded by `cpb_size`). + - Without a declared HRD, it measures the largest access unit. It holds + those renditions out of the catalog until its existing 2 s measuring + window closes (the one that already gates `mpegts.muxRate`), so an export + never starts on a guess. + +Catalog: `burst` is an additive field. It lands with +[fixed-delay release](/quest/m1/tstd/delay.md), which is breaking and on +`dev`. Wire: the hang catalog gains one optional field. + +Update in the same PR: + +- `rs/hang`, `js/hang`, and `drafts/draft-lcurley-moq-hang.md`: the field + definition, its unit, and that a publisher declaring it MUST NOT emit a + larger frame. +- `doc/concept`, plus `doc/bin/cli.md` for `--delay`. + +Test: + +- A TS→MoQ→TS remux of the Kyrion capture (declared HRD) and of an x264 clip + (no HRD) passes strict `tstd`, with `--delay 0` on a clean path. +- A frame over its declared `burst` fails loud. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - the hold and send-ahead machinery this sizes from the catalog + +## Related + +- [Encoders declare burst](/quest/m2/burst-encoders.md) - non-TS sources stop relying on the default +- [Catalog estimate rate limit](/quest/m1/catalog-estimate-rate.md) - the other catalog estimates and how often they republish diff --git a/quest/m2/README.md b/quest/m2/README.md index 4de4234a256..2647211509a 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -22,6 +22,7 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [Stream sessions](/quest/m2/uring-tcp/README.md) - serve WebSocket and HTTP from the io_uring workers, where io_uring pays off most - [fMP4 emsg](/quest/m2/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them - [ID3 catalog section](/quest/m2/id3.md) - timed ID3 as a first-class container-neutral catalog section +- [Encoders declare burst](/quest/m2/burst-encoders.md) - Rust encoders advertise their VBV bound as the catalog `burst` - [FLV script tags](/quest/m2/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import - [#2279](/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition - [CEA-608/708](/quest/m2/captions-cea.md) - captions carried inside video SEI become a real text rendition at import diff --git a/quest/m2/burst-encoders.md b/quest/m2/burst-encoders.md new file mode 100644 index 00000000000..01a1fb2a815 --- /dev/null +++ b/quest/m2/burst-encoders.md @@ -0,0 +1,25 @@ +# [M] Rust encoders declare their burst + +## Goal + +The `moq-video` encoders run a VBV buffer and advertise its bound as the +catalog `burst`, so a TS export of a natively encoded broadcast sizes its +send-ahead from the encoder's real limit instead of the 1 s video default. + +## Plan + +Decided (2026-09-30): + +- Rust encoders set a VBV buffer (x264/ffmpeg `vbv-bufsize`, or each hardware + backend's equivalent). They declare its size as the largest frame they can + emit, and `bitrate` as the VBV max rate. +- A backend that can't bound frame size omits `burst`, and the export's + default applies. +- `js/publish` omits `burst`: WebCodecs exposes no VBV bound. Revisit if it + ever does. +- Test: a TS export of a `moq-video` broadcast passes strict `tstd`, sized + from the declared `burst`. + +## Required + +- [Burst field](/quest/m1/tstd/burst.md) - defines `burst` and the export that reads it