Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions quest/m1/tstd/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
73 changes: 73 additions & 0 deletions quest/m1/tstd/burst.md
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +44 to +47

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Do not turn a two-second sample into a lifetime frame-size bound

For a live source without HRD, the largest AU observed in two seconds says nothing about later scene cuts. If startup's maximum is 100 kB and a later valid keyframe is 150 kB, this plan advertises burst=100000 and then terminates export under lines 27-29, even though the source never promised that bound. Holding publication for two seconds does not make this safe. Keep an observed estimate distinct from an enforced declaration, or leave burst absent unless a real bound is available. Add a no-HRD regression with a larger frame after the measuring window.


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
1 change: 1 addition & 0 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 25 additions & 0 deletions quest/m2/burst-encoders.md
Original file line number Diff line number Diff line change
@@ -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
Loading