Repository navigation
quest(tstd): plan catalog burst for TS send-ahead #4649
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. | ||
|
|
||
| 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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=100000and 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 leaveburstabsent unless a real bound is available. Add a no-HRD regression with a larger frame after the measuring window.