Skip to content

fix(webrtc): a WHEP pull's stop ends its tracks, and a timeline step is a break - #9032

Merged
kixelated merged 5 commits into
mainfrom
quest/m2/whep-chain-shutdown
Nov 17, 2026
Merged

kixelated merged 5 commits into
mainfrom
quest/m2/whep-chain-shutdown

Conversation

@kixelated

@kixelated kixelated commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Claims quest/m2/whep-chain-shutdown.md, the follow-up of moq-dev/moq#8997.

Summary

Stopping moq import webrtc --connect <whep> -- export rtmp --connect <rtmp> with SIGTERM exits 0, with no track::Producer dropped without finish() or abort() and no clock-drift error.

The drift error was not the stop's. In the loopback chain it fires about 6 s into a run on its own, 3 of 14 runs on main, and a stop merely lands on a process that already died of it. The ingest starts each track's timeline on arrival time, then moves to the sender's RTCP reports once every track has one (about 5 s in). The two tracks' arrival skew was up to 470 ms, so the track placed earlier (audio) stepped forward by that much, with nothing telling a reader. The export's jitter buffer reads an unmarked step under half the delay as a move in latency, and one that is not as the source's clock running 60000 ppm fast. Now:

  • IngestClock::normalize takes the step only on a frame that opens a group (every audio frame, a video keyframe), keeping a video track's timeline through the deltas of its group, and says so.
  • The sink publishes a discontinuity (the track's marker group) before that frame, which every reader already handles as a new clock generation (Bridge::discontinuity, one line per codec).
  • A video step waits for its next keyframe, so the session asks the publisher for one with PLI (once a second, where PLI was negotiated) instead of leaving a sender that keys only on request offset by the arrival skew for the whole session.
  • A step under 20 ms, a sender report's own correction, stays unmarked.

The unfinished tracks had two sources, both a cancelled future that drops what it holds:

  • IngestSink dropped with its bridges and catalog open (Session::run aborts only when its loop returns). It now aborts them with Cancel on drop; finished or aborted sinks have nothing left to abort.
  • The origin's teardown dropped each front's accepted logical track unfinished (track::Producer of the same names, 2 to 4 warnings a stop), though Driver's docs say dropping it aborts active fronts. A dropped FrontServeRun now ends them with Closed.

Validation

  • Real binaries on loopback, three processes as in fix(moq-webrtc): a WHEP pull announces once its catalog exists and survives a mid-group join #8997 (ffmpeg H.264+Opus through import fmp4 -- export webrtc --listen as the WHEP source, the chain, and an import rtmp --listen -- export rtmp --listen sink), the chain stopped with SIGTERM after 5 to 9 s:
    • before: exit 0 each time, drop warnings every run (3 to 6), and the drift error ended the process on its own in 3 of 14 runs (+91814, +252, +286 ppm).
    • after: 30 of 30 exit 0, no drop warning, no drift error. The only warnings are catalog::interval overruns (21 of 30, also on the base) and FLV export only supports one audio track (4 of 30, seen before the marker change; not investigated).
  • To find the cause I recorded each frame the export pushed (decode time, arrival, read) from a failing run and replayed it through the jitter buffer in a test, which failed the same way: the audio's decode - arrival jumped 0.33 s at the sender reports. A second failing run was audio only, which is why a buffer-side loosening (judging drift only after the rate could have cost half the delay) was dropped: it cannot tell one track's 0.3 s step from drift, and a publisher's unmarked step is the publisher's to mark.
  • Unit tests: session::tests::the_sender_reports_step_a_track_where_a_group_opens and video_takes_a_step_at_its_next_keyframe (the exact stepped timestamps, who takes the step and when), ingest::tests::a_step_publishes_a_marker_group (4 groups: two frames, the marker, the next), a_deferred_step_asks_for_a_keyframe (a PLI at once, then at most once a second, none without PLI), a_dropped_sink_aborts_its_tracks (Cancel, not Dropped), and origin::tests::teardown_ends_the_logical_tracks, which warned before the Drop.
  • just check passes (11823 tests). just test interop --all: all checks passed.

Public API and wire impact

None to the public API: MediaSink and Bridge are crate-private, and moq-net gains a Drop only. On the wire an ingest now publishes a discontinuity marker group where a step happens, once per session about 5 s in, which is the existing marker every reader handles.

Decisions

  • ✅ Keep the follow-up quest/m3/flv-export-arrival.md (rejected: drop it). The maintainer's answer, on this PR.
  • ✅ A deferred video step asks for a keyframe with PLI, rate-limited to KEYFRAME_REQUEST_INTERVAL like the first-keyframe request (rejected: let the step land unmarked after a cap, which brings back the unmarked step this PR removes; rejected: wait for the sender's own keyframes, since browser encoders key only on request). Judged on Pullfrog's finding: real, since libwebrtc sends no periodic keyframes.
  • ✅ Without PLI the step waits for the sender's own next keyframe (rejected: an unmarked step after a cap). A sender that cannot be asked is one that keys on its own schedule, and the offset it keeps meanwhile is the arrival skew it had all along.

Caused by

  • No single PR. The abort-only-on-return and the arrival-then-reports timeline are as old as the ingest session driver (moved by moq-dev/moq#8122), and the origin's teardown never ended its logical tracks.

Follow-ups

  • An FLV export judges a frame on when it landed (new, m3, XS): found while tracing the failing run. FlvTrack::empty, not the frame's real arrival, is what Export::fill hands the jitter buffer, so a track whose reads the buffer gates looks sent further ahead each frame. No open decisions. Kept by the maintainer (comment); recorded in its Plan.

Models

Size: S
Implementer: Claude Code, claude-sonnet-5-5, unknown effort (arm B)
Implementer: Claude Code, claude-sonnet-5-5, unknown effort (iterate, S, arm B)

(Written by Claude Sonnet 5.5)

Review

Rewritten by quest review after each round.

  • Head: 0e15f1d

  • Base: origin/main at f88e8f5

  • 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: 01a1eb61-6bf0-7260-8b09-abd0983262bb, round 3

  • Score: 10/10, Source review found no new issues in the incremental change, which requests rate-limited keyframes when a video timeline step is deferred; builds and tests were not run.

  • Rounds: 3; first round 1 (medium 1); findings 1 (medium 1): fixed 1, refuted 0, open 0

  • Findings: none

kixelated and others added 3 commits November 17, 2026 11:43
…is a break

A pull cancelled at shutdown dropped its sink, and the origin's teardown dropped the logical
tracks its fronts served, each unfinished. The sink aborts its tracks and catalog on drop,
and a dropped front ends its logical tracks as closed.

The ingest's timeline steps a track forward once the sender reports replace arrival time.
The export read that unmarked step as the source's clock running past the drift limit, and
failed the chain. A step is now taken where a group opens, and the track publishes a
discontinuity first.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title A WHEP pull chained into an export stops cleanly fix(webrtc): a WHEP pull's stop ends its tracks, and a timeline step is a break Nov 17, 2026
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 17, 2026 21:32
@coderabbitai

coderabbitai Bot commented Nov 17, 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 29 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: 0be58fe6-9928-4dbb-b3c2-e9144697cf83
Commits

Reviewing files that changed from the base of the PR and between 2dcb5f8 and 0e15f1d.

Files selected for processing: 13

  • quest/m2/README.md
  • quest/m2/whep-chain-shutdown.md
  • quest/m3/flv-export-arrival.md
  • rs/moq-net/src/model/origin.rs
  • rs/moq-webrtc/src/codec/av1.rs
  • rs/moq-webrtc/src/codec/h264.rs
  • rs/moq-webrtc/src/codec/h265.rs
  • rs/moq-webrtc/src/codec/mod.rs
  • rs/moq-webrtc/src/codec/opus.rs
  • rs/moq-webrtc/src/codec/vp8.rs
  • rs/moq-webrtc/src/codec/vp9.rs
  • rs/moq-webrtc/src/ingest.rs
  • rs/moq-webrtc/src/session.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.

Important

A video step that lands on a delta frame waits for the next keyframe, and nothing asks for one. A sender that sends keyframes only on request leaves video out of sync with audio for the rest of the session.

Approach: sound. Marking the sender-report step with the existing marker group fixes the cause the PR found (an unmarked step the jitter buffer read as drift) instead of loosening the buffer. The two Drop impls close the cancelled-future paths that left tracks unfinished. The one gap is how long a deferred video step can wait.

Reviewed changes

All 13 files at bfc3770: the ingest clock's step detection, the discontinuity plumbing through the codec bridges, and the two teardown Drops.

  • IngestClock::normalize step detection. A forward jump of more than 20 ms past where the track's timeline would continue counts as a step. Audio frames and keyframes take it and are flagged as stepped. Delta frames stay on the old timeline.
  • Discontinuity plumbing. A new MediaSink::on_discontinuity goes through Bridges, each codec Bridge, and DeferredVideo (a no-op until a frame creates the importer) to the importer's existing marker-group discontinuity().
  • impl Drop for IngestSink. It aborts the bridges and catalog with Cancel. This does nothing after finish: the bridge map is already empty, and catalog::Producer::abort returns early once closed is set.
  • impl Drop for FrontServeRun. It aborts every Logical::Accepted with Closed, including on the orphaned InFlight early-return path. Readers see the same thing as before apart from the error code: abort and an unfinished drop both tear down open groups, and Dropped and Closed are both transient().
  • Quest bookkeeping. The claimed quest file is removed and the new m3 quest flv-export-arrival is added.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread rs/moq-webrtc/src/session.rs Resolved
@kixelated

Copy link
Copy Markdown
Collaborator Author

Maintainer decision (2026-11-17, asked in the /quest-run m0/m1/m2 coordinating session). Pick: /quest-merge.

✅ Keep the follow-up quest/m3/flv-export-arrival.md (rejected: drop it).

(Written by Claude Opus 5.5 with high)

A video track whose timeline should step waits for its next keyframe, which a
sender that keys only on request never sends. Ask with PLI, once an interval,
where it was negotiated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

Recorded the maintainer's decision to keep quest/m3/flv-export-arrival.md in that quest's Plan and the PR body's Decisions, and fixed Pullfrog's finding (0e15f1d, reviewed by Codex round 3, no findings).

(Written by Claude Sonnet 5.5)

@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. The new commit fixes the prior finding about a deferred video step that had no deadline.

Reviewed changes

Changes since bfc3770: the deferred step now asks for a keyframe, and the quest file notes that the maintainer kept it.

  • Mapped::deferred. IngestClock::normalize now reports when it holds a step on a delta frame. The session loop then sends a PLI through the new request_keyframe helper, which Admit::Request now shares.
  • Rate-limited requests. IngestLine::Video now has a request_at field that it takes over from Keyless, so a line can ask at most once per KEYFRAME_REQUEST_INTERVAL (1 s). A line without PLI and an audio line never ask. a_deferred_step_asks_for_a_keyframe tests both cases.
  • Quest note. quest/m3/flv-export-arrival.md now records the maintainer's decision to keep the quest.

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

@kixelated
kixelated added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 29a2029 Nov 17, 2026
6 checks passed
@kixelated
kixelated deleted the quest/m2/whep-chain-shutdown branch November 17, 2026 22:38
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.

1 participant