Skip to content

fix(mux): the export re-acquires an unmarked timeline step - #7165

Merged
kixelated merged 3 commits into
mainfrom
quest/m1/ts-reliability/export-reacquire
Oct 29, 2026
Merged

kixelated merged 3 commits into
mainfrom
quest/m1/ts-reliability/export-reacquire

Conversation

@kixelated

@kixelated kixelated commented Oct 28, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m1/ts-reliability/export-reacquire.md, from moq-dev/moq#7102.

Summary

Before this change, a source whose timestamps stepped with no restart or skip marker kept the export's old clock:

Now jumps() in rs/moq-mux/src/jitter.rs opens a new generation for an unmarked step once the delay can't absorb it, the same way a marked restart does (acquired() resets the steering state, including startup):

  • Forward: the frame is held past bound() (more than a delay past everything queued and its track's lead), and it arrived more than a delay earlier against its decode time than its track's previous frame. A clock within MAX_DRIFT can't move a frame that far between two frames (MAX_DRIFT · elapsed is allowed for). Queueing can't either: frames arrive in send order, so a backlog draining or a sparse track doesn't trigger it.
  • Back: the frame decodes before its track's previous frame and is late. A stall only delays what comes next; it never makes decode go backwards.
  • It applies only to a track on the clock's current generation (a track still on an earlier generation is on that timeline) and only with a nonzero delay (with zero delay nothing is held or late).

Slew check: the frame that straddles the step goes to the new acquisition and never steers the old clock, so the step's span of decode time never reaches MAX_SLEW · elapsed. The test checks that the drift moves by no more than the slew limit allows over the time that actually passed.

Kept from moq-dev/moq#5564: no minimum span or sample count, and the 30 ppm and half-delay lost thresholds are unchanged. The #5564 start-up and drift tests pass unchanged.

doc/bin/cli.md gets one sentence on the behavior. Public API: none. Wire: none.

Tests

  • jitter::tests::an_unmarked_step_reacquires_the_clock: ±16,844.5 s and ±2 s unmarked steps, at 30 s and at 1,200 s (after the rate window fills), with a few ms of arrival jitter. Each opens exactly one new generation, drops nothing, keeps emitting, and the drift stays within the slew limit.
  • ts::export_timing_test::an_unmarked_step_keeps_the_export_rendering: a live H.264 + AAC TS export with a +16,844.5 s and a +2 s mid-group step, for each send lag. Nothing dropped; video keeps rendering.
  • Both new tests fail on main's engine and pass here.
  • just check: passes, 4154 tests.

Choices made without asking

  • Where a step starts. The quest says a step is "a phase change no clock rate within the bound could produce in the elapsed time." Taken literally (30 ppm × 2 s = 60 µs), ordinary arrival jitter and queueing would count as steps. So the line is set where the delay stops absorbing it, about one delay either way. A smaller unmarked step stays a move in latency, as before: if it is over half the delay and persists, it can still fail as drift, which is flaky: just test ts --full exits on the release clock's first rate estimates (~1 in 5 local runs) #5564's existing behavior for latency moves.
  • The leap rule after a skip is unchanged. Without a marker, the forward rule also needs the per-track phase check. bound() alone fires when a track's frames are more than a delay apart and slightly early: packed TS audio broke a_backlog_stays_in_the_source_until_due that way.
  • Two existing tests changed. flv and mkv delay_drops_late_frames_and_drains_the_final_frame wrote their final frame 200 ms ahead of real time with a 100 ms delay. By size that is a forward step, so it now re-acquires. The frame is now sent one delay ahead (decode 300 ms, out at ≥ 400 ms). The tests still check that a late frame is dropped and the final frame drains.
  • The end-to-end export test covers forward steps only. The hang consumer refuses any frame below the previous group's start (moq-dev/moq#4543's rule), so a large step back ends the export with TimestampRewind before the jitter buffer sees it. The step-restart quest handles that on the import side. The backward rule is covered at the jitter level.

Suggested follow-ups

  • A small step back drops the TS export's video. A step back of more than the delay but within one group (for example −560 ms with 600 ms groups and a 500 ms delay) does reach the TS export. Its video decode-time reconstruction clamps DTS to stay non-decreasing, so only the first video frame regresses, and that frame is still in time. The rest arrive late with no regression, and nearly all video is dropped (105 of 120 frames over 8 groups). Main's engine does the same. The fix belongs with the decode-order work on the video path, not the jitter buffer.

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)

kixelated and others added 3 commits October 28, 2026 15:43
A source whose timestamps step with no restart or skip marker, as a
changeover between two encoders whose clocks started hours apart, kept the
old clock: a step forward was held for its whole span and then read as
drift, failing the export ("the source's clock runs +172.5 ppm off ours"),
and a step back went late for good.

The jitter buffer now opens a new generation for such a step, as a marked
restart does, once the delay cannot absorb it. Forward, a frame held past
the bound arrived more than a delay earlier against its decode time than its
track's last; back, a frame decodes before its track's last and is late.
Neither is a phase change a clock within the 13818-1 bound or queueing
makes, so drift, stalls and backlogs keep the clock. The straddling frame is
held for the new generation and never steers the old clock, so the step's
span never feeds the slew limit. The 30 ppm and half-delay thresholds are
unchanged.

Closes quest/m1/ts-reliability/export-reacquire.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title The TS export re-acquires an unmarked timeline step fix(mux): the export re-acquires an unmarked timeline step Oct 28, 2026
@kixelated
kixelated marked this pull request as ready for review October 28, 2026 23:39
@coderabbitai

coderabbitai Bot commented Oct 28, 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 28 minutes.

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: aab33739-86af-40bd-aa8b-d9dc0c647720
Commits

Reviewing files that changed from the base of the PR and between c45748f and dca7eb8.

Files selected for processing: 8
  • doc/bin/cli.md
  • quest/m1/ts-reliability/README.md
  • quest/m1/ts-reliability/export-reacquire.md
  • quest/m1/ts-reliability/step-restart.md
  • rs/moq-mux/src/container/flv/export_test.rs
  • rs/moq-mux/src/container/mkv/export_test.rs
  • rs/moq-mux/src/container/ts/export_timing_test.rs
  • rs/moq-mux/src/jitter.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

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-28T23:41:03.549039Z dca7eb8 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@kixelated kixelated left a comment

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.

Automated review by review (OpenAI)
Reviewed commit: dca7eb8

No actionable bugs found in the changed paths. Reusing generation acquisition for an unmarked step is preferable to relaxing drift limits or adding a second clock-reset mechanism. The forward test combines the existing queue/lead bound with a per-track phase change, and the straddling frame is held before steering, so acquisition resets the measurement window rather than treating the discontinuity as clock rate. The additional per-track state is modest and justified.

The new jitter tests cover both directions before and after the rate window fills; the TS integration test covers forward steps only. This is not a complete backward-step fix for TS: upstream TimestampRewind rejection and the existing decode-time clamping limitation remain outside these changes, as the PR notes.

Static review of the diff and surrounding jitter acquisition, queueing, and steering code only. I did not execute tests or reproduce the reported stream.

@kixelated

Copy link
Copy Markdown
Collaborator Author

Merge summary for head dca7eb824f767ea655c44eff3942f83b7bdb8fda:

  • No changes made during merge. Reviews: Codex (OpenAI) gave a thumbs up on this head (no findings), and the automated OpenAI review found nothing actionable. CodeRabbit was rate-limited, which doesn't count.
  • Required checks pass. quest check --base origin/main passes on this head: the finished quest and its links are deleted.
  • The /quest-merge pick on 2026-10-28 accepted the choices listed in the PR body, including the delay-sized step definition.
  • Follow-up for /quest-plan: a small step back (more than the delay, within one group) still drops most of the TS export's video, through the video DTS clamp. This is pre-existing, as described in the PR body.

Queuing for squash merge.

(Written by Claude Opus 5.5)

@kixelated
kixelated added this pull request to the merge queue Oct 28, 2026
Merged via the queue into main with commit bfae575 Oct 29, 2026
12 checks passed
@kixelated
kixelated deleted the quest/m1/ts-reliability/export-reacquire branch October 29, 2026 01:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant