Skip to content

fix(watch): keep the audio arrival estimate across a rename - #5824

Merged
kixelated merged 5 commits into
mainfrom
quest/m1/audio-jitter-target/audio-rename
Oct 17, 2026
Merged

kixelated merged 5 commits into
mainfrom
quest/m1/audio-jitter-target/audio-rename

Conversation

@kixelated

Copy link
Copy Markdown
Collaborator

Completes quest/m1/audio-jitter-target/audio-rename.md.

Summary

When @moq/publish renames an audio track, @moq/watch used to reset the audio arrival estimate:

  • #runLegacyDecoder / #runCmafDecoder cleared #measured on teardown, so the audio target dropped out of the shared delay.
  • The replacement Container.Consumer then started from the cold 100 ms prior and climbed back up.

The ring skipped on the drop and went silent on each rise. This is the failure #5635 fixed for video.

Changes in js/watch/src/audio/decoder.ts:

  • Predecessor hand-off. A new #consume helper, shared by both container paths, passes the newest consumer as ConsumerProps.predecessor, but only when both read the same broadcast path. This mirrors the video decoder.
  • Hold until replaced. #measured is no longer cleared on teardown. #retire() clears it only when nothing replaces the consumer: disabled, muted, instant, rendition removed, offline, failed, or the subscription closed.
  • Frame term holds too. The rename test also caught a smaller drop. #runDecoder reset #frame to the catalog constant, and that constant is undefined for Opus. So the target lost its 10-20 ms frame term until the replacement's first packet. #frame now changes only when the config states a constant.

doc/concept/audio-jitter.md ("Across renditions") already requires this behavior, so it needs no update.

Tests

js/watch/src/audio/decoder.test.ts, "Decoder across a rename". These read real tracks through real container consumers on a mocked clock:

  • Warm, then rename. A bursty track (runs of 12 frames, about 220 ms late) warms up, then gets renamed. The test asserts the ring neither skips nor goes silent, and the shared delay never drops. On main it fails with skipped: 20160 samples (420 ms) and silent: 4 ticks.
  • Another path. Moving the media to another path does not inherit the estimate.
  • Removed rendition. A removed rendition stops holding the delay. This guards the clear-when-not-replaced path.

just check passes locally.

Public API / wire

None.

Follow-ups

  • rs/moq-audio builds a fresh Target per decode consumer, so a native player that follows a rename still restarts cold. It needs its own quest if native playback follows renames. The quest already marks this out of scope.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

kixelated and others added 2 commits October 16, 2026 19:21
A renamed audio track now continues the outgoing consumer's estimate through
ConsumerProps.predecessor when both read the same path, as video does. The
outgoing estimate stays in the playout target until the replacement's consumer
exists, and is cleared only when nothing replaces it. Opus states no constant
frame duration, so the outgoing one also holds until the replacement's first
packet instead of dropping out of the target.

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

Copy link
Copy Markdown
Collaborator Author

Outcome: the quest is implemented as planned and opened ready for review.

I made one choice beyond the written plan. #frame now holds the outgoing duration when the new config states no constant. Opus never states one, so without this the delay still dropped 10 ms at the rename until the first packet arrived. The other option was to keep resetting #frame and loosen the test so it ignores the frame term. I recommend keeping the fix: the quest's goal is that the delay never drops.

just check passed locally. CI is pending.

(Written by Claude Opus 5.5)

@coderabbitai

coderabbitai Bot commented Oct 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 37 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
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 220d77ec-5e03-474b-ba4a-03ead3e0b614
📥 Commits

Reviewing files that changed from the base of the PR and between e597a1e and 398f7d9.

📒 Files selected for processing: 4
  • js/watch/src/audio/decoder.test.ts
  • js/watch/src/audio/decoder.ts
  • quest/m1/audio-jitter-target/README.md
  • quest/m1/audio-jitter-target/audio-rename.md
  • 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 17, 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-17T04:59:05.482563Z 398f7d9 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: d13a522da1

ℹ️ 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 js/watch/src/audio/decoder.ts Outdated
Comment on lines +354 to +356
// Opus states no constant, so the outgoing duration holds until the replacement's first packet.
const frame = frameDuration(config);
if (frame !== undefined) this.#frame.set(frame);

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 Reset the frame term for unrelated consumers

When playback moves from an AAC/MP3 rendition to an Opus or other variable-duration rendition after an absence or path change, frameDuration(config) returns undefined, so this branch retains the previous stream's frame duration. Once the new consumer publishes its cold estimate, target() therefore adds a frame term belonging to an unrelated codec until the first decodable packet arrives; if the advertised track is paused, this can hold the shared audio/video delay at the wrong value indefinitely. This also conflicts with the current-codec selection order documented in doc/concept/audio-jitter.md lines 235-249. Preserve the old term only for the intended same-path handoff, and otherwise clear #frame when the new config has no constant.

Useful? React with 👍 / 👎.

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.

Agreed. Fixed in 6c3b126. The frame term now moves into #consume. It holds only when the replacement continues the outgoing consumer on the same path with the same codec. An absence clears #consumer, so a return starts from frameDuration(config), and that is undefined for Opus, per the doc's order. A path change or a codec change does the same.

(Written by Claude Opus 5.5)

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

Copy link
Copy Markdown
Collaborator Author

Decision: the maintainer chose to keep the Opus frame-duration fix and merge once CI and reviews pass. After the Codex review it applies only to a same-path, same-codec hand-off.

(Written by Claude Opus 5.5)

@kixelated

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: 6c3b126093

ℹ️ 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 js/watch/src/audio/decoder.ts Outdated
Comment on lines +416 to +419
if (config.container.kind === "cmaf") {
this.#runCmafDecoder(run, sub, { config, failure });
this.#runCmafDecoder(run, sub, props);
} else {
this.#runLegacyDecoder(run, sub, { config, failure });
this.#runLegacyDecoder(run, sub, props);

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 Retire the old estimate when replacement setup throws

When switching from a warmed track to an Opus rendition with a malformed but base64-valid CMAF init segment, or a malformed Opus description, supported() can accept the config and then #runCmafDecoder or #runLegacyDecoder throws before #consume installs the replacement. Since this change removes the teardown cleanup and these calls have no failure path invoking #retire(), the departed consumer's #measured value remains registered indefinitely, holding the shared audio/video delay at a stale value despite there being no audio consumer. Reject these malformed configurations during probing or retire and report the setup failure here.

AGENTS.md reference: AGENTS.md:L17-L17

Useful? React with 👍 / 👎.

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.

Agreed. Fixed in a1a8312. A setup throw inside the subscription effect now goes to the same failure signal a decode error uses. That records #failed, surfaces it on out.error, and calls #retire(). Before this, the throw was only logged as an effect error. The regression test "reports a replacement that fails to set up and stops holding the delay" renames a warm track to an unparseable CMAF init segment. It fails without the catch.

(Written by Claude Opus 5.5)

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

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

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

Reviewed commit: a1a8312844

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

Copy link
Copy Markdown
Collaborator Author

Summary before merge:

  • Rename hand-off. A renamed audio track on the same path continues the outgoing consumer's arrival estimate (ConsumerProps.predecessor). The estimate stays in the playout target until a replacement consumer exists. #retire() clears it when nothing replaces the track.
  • Frame term. This was the maintainer's decision to keep. After the first Codex review it applies only when the same codec continues on the same path. Any other case starts from the codec's own constant, per doc/concept/audio-jitter.md.
  • Setup failure. This came from the second Codex review. A replacement config that throws during setup is now reported through out.error like a decode failure, and its stale estimate is retired.
  • Tests. Four regression tests on a mocked clock cover: rename without skip or silence, another path, setup failure, and removal.
  • Public API / wire. None.

Follow-up: native rs/moq-audio still restarts cold on a rename. It needs its own quest if native playback follows renames.

(Written by Claude Opus 5.5)

@kixelated
kixelated added this pull request to the merge queue Oct 17, 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 17, 2026
…-target/audio-rename

# Conflicts:
#	quest/m1/audio-jitter-target/README.md
@kixelated

Copy link
Copy Markdown
Collaborator Author

The merge queue removed this PR for a merge conflict at 04:49Z. The upstream change reordered the epic's Required list. I resolved it in 398f7d9 by merging main and dropping only the audio-rename line. There are no source changes. CI is green on the new head. Auto-merge is not re-enabled: a new head needs maintainer approval to re-queue.

(Written by Claude Opus 5.5)

@kixelated
kixelated added this pull request to the merge queue Oct 17, 2026
Merged via the queue into main with commit 0198702 Oct 17, 2026
9 checks passed
@kixelated
kixelated deleted the quest/m1/audio-jitter-target/audio-rename branch October 17, 2026 06:23
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