Skip to content

fix(mux): a TS export states its whole delay to the relay - #9067

Merged
kixelated merged 5 commits into
mainfrom
quest/m1/export-delay-wire
Nov 18, 2026
Merged

kixelated merged 5 commits into
mainfrom
quest/m1/export-delay-wire

Conversation

@kixelated

@kixelated kixelated commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

A fixed-delay TS export (moq export ts --delay D, the --passthrough release, and the SRT egress built on it) told the relay half its delay. The relay then reset a group with Old once it was D/2 old. Every TS track subscription now states Delay { min: D, max: D }, so the relay holds a group for the export's whole delay. The export's own stalled-group skip moves from D/2 to D too, so a stall shorter than D loses nothing.

Closes #9018

Changes

  • ts::Export (new tracks, resubscribe, rebind) and ts::Release subscribe with export::subscribed(D), which is {min: D, max: D}. Before, it was {min: None, max: D/2}.
  • The local skip is export::skipping(D), {min: None, max: D}: a stalled group is skipped once the group after it runs D past it, and a missing group is waited for D. It is set apart from the subscription through ExportSource::skipping_at and Consumer::skipping_at (both pub(crate)), because a consumer given the wire's min: D would reach back D at a live start. Consumer::set_delay now shares the clamp with them.
  • budget() (D/2) now bounds only a packed PES's span and how far a padded output may fall behind before it sheds.
  • Tests:
    • feat(moq-mux)!: fixed-delay jitter buffer and per-PID T-STD admission for TS export #4645's guards a_skip_at_the_join_keeps_one_clock and a_skip_while_running_keeps_one_clock now assert the new bound: a group whose tail never arrives holds the next group for the whole delay, that group's first frames are then due and go late, and the video resumes at the keyframe after it. So at most one group (15 frames) goes, and the video keeps one clock with the audio. Before, they asserted no drops.
    • New a_path_stall_within_the_delay_loses_nothing: a whole-path stall of 300, 400, or 475 ms (D = 500 ms) across a group boundary, drained newest group first with the export reading the newer group before the older tail lands, drops nothing and skips no video. At D/2, 3 of its 6 cases skip the older group's tail. The timing harness gained Live::stall_path for it.
    • fixed_delay_keeps_buffered_pes_ahead_of_the_clock: a replay join now keeps the whole delay of backlog, 151 PES instead of 76.
    • a_skipped_group_flags_the_clock: with a delay, a 6 s hole may now be skipped and flagged instead of backfilled (details under Decisions). The test still checks that only skipped slots flag the PCR, each right before the audio resuming its hole.
  • Audited moq-cli and moq-mux for other fixed-delay subscribers. flv/mkv exports, moq play video and audio, and the TS SI tracks already state the whole delay. fmp4/mp4/h264/h265 play nothing out, so they keep max only by design.
  • Docs: moq export ts --delay's help and moq-srt's Subscriber doc say a stalled group is skipped once it falls the delay behind, not half.
  • moq-srt's a_publisher_marker_keeps_an_srt_receiver_playing writes its post-marker burst as 0.5 s instead of 3 s at once. Details under Decisions.
  • export-order: the D/2 drain-order case this PR had added to its Plan is gone, since a skip at D no longer loses that tail.

Decisions

  • Local skip at D ✅ D (rejected: D/2). The maintainer's call in this comment: a stall shorter than D loses nothing, and the relay already holds groups for D. The cost, accepted: a group whose tail never arrives holds the next one for D, so that next group goes late (one GOP in the feat(moq-mux)!: fixed-delay jitter buffer and per-PID T-STD admission for TS export #4645 guards, where D/2 lost nothing).
  • The skip keeps its own min: None. Feeding the consumer the subscription's {D, D} directly would also make a live start reach back D, adding D of startup latency on top of the export's own delay. So the separate skip stays, now differing from the subscription only in min.
  • A hole after a long outage may now flag the PCR. With a delay, the export waits D for a missing group, so the group after it is read right at its deadline. Whether the scheduler then backfills the empty slots of a hole longer than its 1 s backfill window or skips them and flags the first PCR now depends on that timing: in a_skipped_group_flags_the_clock, the first 6 s hole is backfilled and the second flagged. Both are valid TS; nothing is dropped.
  • The SRT marker test changed its burst length. Its 3 s burst made the publisher shed the marker's group as stale before the egress read it. On main the break was flagged only because the D/2 budget also shed two media groups: the 2.08 s gap read as an unmarked step past the 1 s delay. With D on the wire, only a 1.08 s gap is left, which the delay absorbs, so no flag. A 0.5 s burst keeps the marker deliverable, so the test exercises the declared marker it is named for.
  • Join backlog: the export's default Range::oldest now reaches back D on the relay (it was D/2). A live export still starts at the newest group and discards the rest, so the relay may send up to D of backlog that a joining export drops. min changes no join, because Range::oldest ignores it.

Validation

  • cargo test -p moq-mux --lib: 2,100 passed. cargo test -p moq-srt -p moq-cli: all passed. just check passed.
  • The new stall test discriminates: with the skip temporarily back at D/2, 3 of its 6 cases skipped the older group's tail; at D all 6 lose nothing.
  • Traced the feat(moq-mux)!: fixed-delay jitter buffer and per-PID T-STD admission for TS export #4645 guards at D before changing them: in each, the 15 drops are exactly the group after the stalled one (video resumes at the next keyframe, ticks 75 and 120), for both audio lags.
  • Still to see in the field: moq-relay resets a subscriber's groups as Old after a stall of about a quarter of its max_delay #9018's reporter can re-run the blackout sweep on this branch, where resets should start near a D stall instead of about D/4.
  • Real surface (previous round, unchanged by this one): ran a local moq-relay at trace level, a real-time ffmpeg -re -stream_loop -1 … bbb.ts | moq import ts, and moq export ts --delay 2s. The relay decoded max_delay: Some(2s) on the 0.avc3 and 1.aac SUBSCRIBEs (main sends 1 s). The output probes as h264 and aac.

Impact

Public API: none (pub(crate) only). Wire: none; existing fields carry different values. Behavior: a TS export's subscription asks a relay to keep groups for its whole delay, and the export itself waits the whole delay for a stalled or missing group before skipping it.

Caused by

Follow-ups

None.

Models

Size: S
Implementer: Claude Code, claude-opus-5-5, unknown effort (arm A)
Implementer: Claude Code, claude-opus-5-5, high effort (iterate, S, arm A)

🤖 Generated with Claude Code

(Written by Claude Opus 5.5 with high)

Review

Rewritten by quest review after each round.

  • Head: ec902bf

  • Base: origin/main at d9ccbad

  • Risk: medium, the base has no RISK.md to name what is always high or customer-facing, so every change is medium

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, medium effort

  • Session: 01a1ed7d-04b7-71f0-9be2-7a4a0bb33bfe, round 1

  • Score: 8/10, No actionable defects were identified; the subscription and local skip changes appear consistent and have mocked-time regression coverage, though builds and tests were not run as instructed.

  • Rounds: 1; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

kixelated and others added 4 commits November 17, 2026 19:55
The TS export and passthrough subscribed with half their delay as the max,
the export's local skip budget, so a relay reset a group with Old once it
was D/2 old. They now state the whole delay as both bounds, and keep
skipping a stalled group at half the delay locally.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e to export-order

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title A fixed-delay export states its whole delay to the relay fix(mux): a TS export states its whole delay to the relay Nov 18, 2026
@kixelated

Copy link
Copy Markdown
Collaborator Author

Decision from the maintainer:

(Written by Claude Opus 5.5 with high)

The maintainer moved the export's local skip from D/2 to D, so a stall
shorter than the delay loses nothing. #4645's guards now bound the loss to
the one group a never-finished group holds, and a new timing test shows a
whole-path stall between D/2 and D across a group boundary loses nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 18, 2026 07:10
@coderabbitai

coderabbitai Bot commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 50 seconds.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 3f7a6577-f310-472b-a4c5-a156b34f9571
Commits

Reviewing files that changed from the base of the PR and between bf55130 and ec902bf.

Files selected for processing: 10

  • quest/m1/export-delay-wire.md
  • rs/moq-cli/src/args.rs
  • rs/moq-mux/src/container/consumer.rs
  • rs/moq-mux/src/container/source.rs
  • rs/moq-mux/src/container/ts/export.rs
  • rs/moq-mux/src/container/ts/export_test.rs
  • rs/moq-mux/src/container/ts/export_timing_test.rs
  • rs/moq-mux/src/container/ts/release.rs
  • rs/moq-srt/src/server.rs
  • rs/moq-srt/src/ts.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

✅ No new issues found.

Approach: Sound. It fixes the cause: the wire delay now carries the whole delay, {D, D}. The export's own skip stays a separate {None, D}, so a live start doesn't reach back D. Keeping that split is right, because reach_start and start_skip both read min_delay.

Reviewed changes

I reviewed all 10 files across the 5 commits. I traced how the subscription delay and the local skip delay flow from ts::Export/ts::Release through ExportSource into Consumer.

  • Wire delay: every TS track subscription (new, resubscribe, rebind, and Release's passthrough) now uses export::subscribed(D). No budget()-based subscription is left in ts/.
  • Local skip: ExportSource::skipping_at is applied in poll_track after Consumer::new(...).continuing(..) and before .live(). So the consumer's min_delay is None by the time startup runs, and max_delay stays D, clamped to max_age as before.
  • Consumer::set_delay refactor: the shared set_skip uses the same Reading | Failed guard, so an ended reader still keeps its old values.
  • budget(): it now bounds only PES packing span and padded-output shedding, and those call sites are unchanged.
  • Tests: the #4645 guards now allow at most one GOP lost. The new a_path_stall_within_the_delay_loses_nothing drains the newest group first and covers stalls between D/2 and D. The replay-join backlog count and the SRT marker burst length were updated to match the new D horizon.
  • Docs: the --delay CLI help, Export docs, and moq-srt Subscriber docs now say the skip is at D, not D/2.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit 16880c8 Nov 18, 2026
10 checks passed
@kixelated
kixelated deleted the quest/m1/export-delay-wire branch November 18, 2026 07:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

moq-relay resets a subscriber's groups as Old after a stall of about a quarter of its max_delay

1 participant