Skip to content

fix(moq-mux): exporters follow a rendition moved to a new track - #6276

Merged
kixelated merged 11 commits into
mainfrom
quest/m1/export-rendition-rebind
Oct 23, 2026
Merged

kixelated merged 11 commits into
mainfrom
quest/m1/export-rendition-rebind

Conversation

@kixelated

@kixelated kixelated commented Oct 22, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

When a catalog update keeps a rendition's ID but changes its resolved track or broadcast, the fMP4, TS, MKV and FLV exporters kept muxing the old track (or stopped when it ended), because each resolved the track once when it built the rendition's ExportSource and keyed it by ID afterwards. Closes the quest quest/m1/export-rendition-rebind.md (deleted here).

Approach

  • ExportSource keeps its resolved target (broadcast path, epoch, track name) and answers reads(source, name, config) on every catalog update. A mismatch is a move.
  • Before the header/init/PMT, a moved rendition starts over as a newly added one.
  • After it, ExportSource::continuing(previous) builds the new source under the same output track: it reads the new track from its live edge, carries the skip/marker/cut counters on (the move counts as one skip), and drops frames until a sync frame past the latest one the old track delivered. On a shared clock the first group may overlap; a later group that is still behind fails with Error::RenditionRewound.
  • The fMP4 leave/return path now uses the same machinery (Resume/resuming): a return to the same track resumes after the last group, a return to a different track splices like a move.
  • Per muxer, output state carries on and declarations are rechecked:
    • fMP4: same track id, fragment sequence and written frontier; the old track's buffered run goes out as its own fragment; a changed sample entry fails with TrackChanged.
    • TS: same PID and continuity counters, frames held for DTS go out first, decode clock resets; a move to a track of another kind fails, since the PMT, lane and receiver buffer stay as announced and each frame is framed under the track's kind as it goes out (an AAC track keeps its configuration). Video parameter sets ride with each frame, so a new SPS is fine. Under --sync (moq-dev/moq#5949) the rebind forgets the old track's lane group (group sequences are per track) and keeps the lane's end, so the new track's units take their lane positions from its own groups and legs moved at different points of the old track agree from the new track's first common slot. Like a resubscription, the rebound source restamps subscribed, the floor moq-dev/moq#6249's arrival-stamp lateness puts under cached frames (MKV does the same).
    • MKV: same track number; the new track's TrackEntry is checked against the header before any of its frames go out (mkv::Error::TrackChanged).
    • FLV: same codec required; a new sequence-header tag goes out ahead of the first frame read under a different config record.
  • Tests per exporter (move within the broadcast and to a sibling broadcast, plus changed init data), a unit test for the splice and its rewind failure, and a TS --sync test that two legs moved after different old groups (one of them sharing the new track's first sequence) render the new track identically.

Impact

  • Public API: new variant moq_mux::Error::RenditionRewound { rendition, start, read } (enum is #[non_exhaustive]).
  • Public API: new variant moq_mux::container::mkv::Error::TrackChanged(String) (enum is #[non_exhaustive]).
  • Behavior: FLV now emits a new sequence-header tag whenever a track's config record changes, including an in-band SPS change on an unmoved Annex-B track (it used to keep the stale header).
  • Behavior: MKV keeps finished tracks after the header instead of dropping them, so a later catalog update still listing (or moving) a finished rendition no longer fails with HeaderAddedTrack.
  • Behavior: a TS move to a track of another kind (such as an AAC configuration change) fails as a layout change.
  • Behavior: MKV checks the container of every rendition each catalog lists, so a rendition moved to a CMAF track fails with UnsupportedCmafTrack.
  • Wire: none.

Decisions

Decided by the maintainer's recommended-course instruction, 2026-10-22.

  1. Overlap and rewind policy.
    • ✅ Skip ahead to the first sync frame past the old track's last delivered frame; overlap allowed only in the first group; a later group still behind fails with RenditionRewound.
    • Fail on any overlap (most same-clock moves would fail, since the live group usually overlaps).
    • For TS, treat the move as a timeline restart with a PCR discontinuity instead of failing on rewind.
  2. Discontinuity signal on a forward move.
    • ✅ None on a forward move onto the same clock (TS flags nothing, fMP4 has a tfdt gap); going back fails loudly.
    • Always flag a format discontinuity on a move (wrong on a continuous time base).
  3. Error naming.
    • ✅ Error::RenditionRewound.
    • Reuse TimestampRewind (its message says "previous group's start", which misleads here).
    • Another name such as MovedBack.
  4. FLV and MKV behavior changes.
    • ✅ Keep them in this PR, since the rebind needs them.
    • Split them into their own PR.

Alternatives

  • Rebuilding the whole export (new header) on a move: rejected, it resets output state mid-stream.
  • Tracking the target inside each muxer: rejected for one Target in ExportSource, so all four share the identity check and the splice.

Follow-ups

  • Audit other catalog readers that resolve a rendition's track once, such as the moq-rtc egress (subscribe_track per rendition), for the same move gap.
  • Merged main (2026-10-22); just check passed locally on the merge. Nightly feature matrix, macOS, and Windows not run.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

A catalog update that keeps a rendition's ID but changes its resolved
`track` or `broadcast` now rebuilds that rendition's source in the fMP4,
TS, MKV and FLV exporters. Before the header, the rendition starts over as
if newly added. After it, a new source continues the old one under the
declared output track: it reads the new track from its live edge and skips
to the first sync frame past what the old track delivered, failing with
`Error::RenditionRewound` if a later group still goes back in time.

Output state carries on: fMP4 keeps its track id, fragment sequence and
written frontier, and checks the new sample entry against the moov; TS
keeps its PID and continuity counters and refuses a move the PMT cannot
announce; MKV checks the new TrackEntry against the header before writing
any of the new track; FLV emits a new sequence-header tag when the codec
config record changes.

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

Copy link
Copy Markdown
Collaborator Author

Quest outcome: implemented for all four exporters with per-exporter tests (move within the broadcast, move to a sibling broadcast, changed init data) and a splice unit test. just ci passed locally; nightly feature matrix, macOS and Windows not run. Left as a draft for the four open decisions in the description (splice/rewind policy, no discontinuity on a forward move, error naming, the FLV/MKV behavior changes).

(written by Claude Opus 5.5)

@kixelated
kixelated marked this pull request as ready for review October 22, 2026 06:41
@coderabbitai

coderabbitai Bot commented Oct 22, 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 41 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: 1cbf5fa6-2d25-43d2-b9b7-0e0ed1234a0e
📥 Commits

Reviewing files that changed from the base of the PR and between 2a0da45 and 0f8be37.

📒 Files selected for processing: 18
  • quest/m1/README.md
  • quest/m1/annexb-export.md
  • quest/m1/export-rendition-rebind.md
  • rs/moq-mux/src/container/flv/export.rs
  • rs/moq-mux/src/container/flv/export_test.rs
  • rs/moq-mux/src/container/fmp4/export.rs
  • rs/moq-mux/src/container/fmp4/export_test.rs
  • rs/moq-mux/src/container/mkv/export.rs
  • rs/moq-mux/src/container/mkv/export_test.rs
  • rs/moq-mux/src/container/mkv/mod.rs
  • rs/moq-mux/src/container/mod.rs
  • rs/moq-mux/src/container/source.rs
  • rs/moq-mux/src/container/test_util.rs
  • rs/moq-mux/src/container/ts/export.rs
  • rs/moq-mux/src/container/ts/export_test.rs
  • rs/moq-mux/src/container/ts/lane.rs
  • rs/moq-mux/src/error.rs
  • rs/moq-mux/src/source.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 22, 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-23T14:23:44.723500Z 0f8be37 New commits
ℹ️ 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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 171ad21e54

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-mux/src/container/source.rs Resolved
kixelated and others added 2 commits October 22, 2026 14:54
Resolve against #5949 (TS `--sync` lanes) and #6249 (arrival-stamp
lateness): a rebound source restamps `subscribed` instead of the removed
`empty`, frames carry their arrival through the splice, and the TS lanes
keep reading the source's group sequence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two `--sync` legs the catalog moves after reading different amounts of
the old track render the new track's slots identically. The move test
shares its setup with it through `moved_export`.

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

Copy link
Copy Markdown
Collaborator Author

@codex review

(Written by Claude Opus 5.5)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 98641e6d8b

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-mux/src/container/ts/export.rs Resolved
Group sequences belong to one track, so a `--sync` lane that kept the
old track's group would continue it with the new track's group of the
same sequence: its positions and continuity counters then depend on
which group each leg last read. A rebind now forgets the group, keeping
the lane's end so the new group still lays after what went out.

The sync move test covers it: one leg last read the old track's group 1,
the sequence of the first new-track group it reads.

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

Copy link
Copy Markdown
Collaborator Author

@codex review

(Written by Claude Opus 5.5)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9a7af53919

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-mux/src/container/source.rs Resolved
…ssor

A source resuming its track subscribed from `group + 1`, which overflows
when the last group delivered was `u64::MAX`. Subscribe to the groups
after it with an exclusive bound instead, which moq-net already reads as
an empty range at the end of the sequence space.

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

Copy link
Copy Markdown
Collaborator Author

@codex review

(Written by Claude Opus 5.5)

1 similar comment
@kixelated

Copy link
Copy Markdown
Collaborator Author

@codex review

(Written by Claude Opus 5.5)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1ba4295a0b

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-mux/src/container/mkv/export.rs Resolved
The MKV export checked a rendition's container only when it added the
track, so a move after the header to a CMAF track skipped the typed
`UnsupportedCmafTrack` refusal. Check every rendition each catalog lists.

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

Copy link
Copy Markdown
Collaborator Author

@codex review

(Written by Claude Opus 5.5)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 37db970bee

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-mux/src/container/ts/export.rs Resolved
The muxer frames each frame under the track's kind as it leaves the
jitter buffer, so swapping in the new track's kind on a move framed the
old track's queued AAC frames with the new configuration, and the
`--sync` lanes stay sized from the announced one. A move now requires the
same kind (an AAC track keeps its configuration) and keeps it, along
with the receiver buffer derived from it.

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

Copy link
Copy Markdown
Collaborator Author

@codex review

(Written by Claude Opus 5.5)

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: ac3ebe4b5b

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@kixelated
kixelated added this pull request to the merge queue Oct 22, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Oct 23, 2026
@kixelated
kixelated added this pull request to the merge queue Oct 23, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9ebaa75b47

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +2106 to +2109
let same = match (&kind, &track.kind) {
(Kind::Aac { config, .. }, Kind::Aac { config: old, .. }) => config == old,
(kind, old) => kind == old,
};

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Compare PMT descriptors before rebinding

When a move is accompanied by changed mpegts.tracks[name].descriptors, such as registration or extension descriptors that identify a private stream, this check accepts the replacement based only on Kind. The track and already-emitted PMT retain the old descriptors while replacement payload starts flowing on that PID, so downstream demuxers can interpret it using stale signaling; reject the move unless its effective descriptors also match the announced ones.

AGENTS.md reference: rs/moq-mux/AGENTS.md:L10-L10

Useful? React with 👍 / 👎.

@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Oct 23, 2026
Keep main's sibling-instance end (SourceState::Ended, the instance field)
alongside the rendition rebind: the Ended check moves into poll_track, and
request_path keeps main's announcement-waiting body while staying pub(crate)
for Target::request. reference-announcements.md stays deleted as on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated enabled auto-merge October 23, 2026 07:10
@kixelated
kixelated added this pull request to the merge queue Oct 23, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Oct 23, 2026
@kixelated
kixelated added this pull request to the merge queue Oct 23, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 37d2bb1fdd

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

if track.flavor.has_composition_time() {
track.last_dts = Some(timestamp);
}
let record = track.config_record()?;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Keep the pending frame's original FLV config

When the header is returned with a pre-header frame still in track.pending, a catalog move can rebind track.source before the next poll. This lookup then captures the replacement source's codec record for the old pending frame, so, for example, an old H.264 or AAC payload can be emitted immediately after a sequence header describing the new track. Store the record when the pending frame is originally read, or drain that frame before rebinding.

Useful? React with 👍 / 👎.

@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Oct 23, 2026
Resolve the TS export against PMT revisions (#6289): rebind runs after
the stale resubscribe and moves only listed tracks, keeping their PID,
kind and descriptors; a track the PMT does not list yet starts over on
the moved track through the joining path. The SI collision check is
main's unified one over taken and draining PIDs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated added this pull request to the merge queue Oct 23, 2026
Merged via the queue into main with commit 397e251 Oct 23, 2026
10 checks passed
@kixelated
kixelated deleted the quest/m1/export-rendition-rebind branch October 23, 2026 16:08
kixelated added a commit that referenced this pull request Oct 23, 2026
Drops the sync hunks #6276 added to lane.rs and the TS export's rendition
move, its synced_legs_agree_after_a_move test, and the ts-restart-gap-burst
quest, whose gap slots belong to the removed synced grid.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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