From 1c47f5aa30887e23d7e33e00ed01add0dcc4f90b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 16 Oct 2026 16:15:38 -0700 Subject: [PATCH 1/2] quest(m1): plan the audio rename estimate and the update-after-finish race Co-Authored-By: Claude Opus 5.5 --- quest/m1/audio-jitter-target/README.md | 1 + quest/m1/audio-jitter-target/audio-rename.md | 44 +++++++++++++++++++ quest/m1/test-flakes-2/README.md | 1 + quest/m1/test-flakes-2/update-after-finish.md | 39 ++++++++++++++++ 4 files changed, 85 insertions(+) create mode 100644 quest/m1/audio-jitter-target/audio-rename.md create mode 100644 quest/m1/test-flakes-2/update-after-finish.md diff --git a/quest/m1/audio-jitter-target/README.md b/quest/m1/audio-jitter-target/README.md index 08dbf490934..45763853e68 100644 --- a/quest/m1/audio-jitter-target/README.md +++ b/quest/m1/audio-jitter-target/README.md @@ -37,6 +37,7 @@ the native decode path too, asserting the same target series the browser's ## Required - [Opus isolated-ring target](/quest/m1/audio-jitter-target/opus-isolated-target.md) - the isolated ring holds the target at near-zero jitter +- [Audio rename](/quest/m1/audio-jitter-target/audio-rename.md) - a renamed audio track continues the outgoing arrival estimate, so playback neither skips nor stalls - [Watch](/quest/m1/audio-jitter-target/watch.md) - the browser's measured target, proven on Chrome and Safari against the public relay - [AAC bursty budgets](/quest/m1/audio-jitter-target/aac-bursty-budgets.md) - post-fix nightlies confirm AAC no longer re-stalls, and its budgets are tightened from them diff --git a/quest/m1/audio-jitter-target/audio-rename.md b/quest/m1/audio-jitter-target/audio-rename.md new file mode 100644 index 00000000000..0afb702ff2b --- /dev/null +++ b/quest/m1/audio-jitter-target/audio-rename.md @@ -0,0 +1,44 @@ +# [S] An audio rename keeps the arrival estimate + +## Goal + +When `@moq/publish` renames an audio track after a decoder identity change, +`@moq/watch` keeps playing audio without skipping or stalling: the replacement +audio consumer continues the outgoing track's arrival estimate, as video does. +A track read from another broadcast path still starts from the cold-start +prior, as `doc/concept/audio-jitter.md` ("Across renditions") requires. + +## Plan + +Today the audio decoder's `#runLegacyDecoder` and `#runCmafDecoder` clear +`#measured` on teardown, before the replacement subscription opens, and the +new `Container.Consumer` starts from the prior. At a rename, the audio target +drops out of the shared delay, then returns at the cold 100 ms and climbs as +the new track relearns the path. The ring skips on the drop and parks on each +rise, the same failure #5635 fixed for video. + +Decided 2026-10-16 (recommended options; the paper trail is in the plan PR): + +- Hand the outgoing `Container.Consumer` to the replacement through + `ConsumerProps.predecessor`, only when both read the same broadcast path, + mirroring the video decoder. No new API. +- Keep the outgoing estimate in `#measured` until the replacement's consumer + exists. Clear it only when no replacement follows (disabled, muted, or the + rendition removed), so a departed track still stops holding the buffer open. +- Prove it with a unit test in `js/watch/src/audio/decoder.test.ts` on a + mocked clock: warm a bursty audio track, rename it, and assert the ring + neither skips nor goes silent and the delay never drops. A second case moves + the media to another path and asserts it does not inherit. No new + real-browser media case: the unit test reproduces the mechanism + deterministically, and the fixture would need a second audio codec + configuration to rename audio at all. + +Out of scope: `rs/moq-audio` builds a fresh `Target` per decode consumer, so a +native player that follows a rename restarts cold too. That needs its own +quest if native playback follows renames. + +Public API: none. Wire: none. + +## Related + +- [Browser follows a renamed track](/quest/m1/browser-rename-check.md) - the browser check that found the video stall diff --git a/quest/m1/test-flakes-2/README.md b/quest/m1/test-flakes-2/README.md index e2fc6db891d..abb4e871027 100644 --- a/quest/m1/test-flakes-2/README.md +++ b/quest/m1/test-flakes-2/README.md @@ -35,6 +35,7 @@ Public API: none. Wire: none. ## Required +- [Update after finish](/quest/m1/test-flakes-2/update-after-finish.md) - a subscribe update racing a publisher's finish ends the track cleanly in JS and Rust, not with the write's error - [Interop close code](/quest/m1/test-flakes-2/interop-close-code.md) - the browser reliably sees `unauthorized` for a refused session - [Auth refresh mocks time](/quest/m1/test-flakes-2/auth-refresh-mock-time.md) - moq-relay's auth refresh and fixed-lease tests measure a grant's life on one mocked clock - [uring teardown close](/quest/m1/test-flakes-2/uring-teardown-close.md) - moq-uring's published-close teardown test holds under load, fixed at its cause diff --git a/quest/m1/test-flakes-2/update-after-finish.md b/quest/m1/test-flakes-2/update-after-finish.md new file mode 100644 index 00000000000..b8ad07a6b52 --- /dev/null +++ b/quest/m1/test-flakes-2/update-after-finish.md @@ -0,0 +1,39 @@ +# [S] A subscribe update racing a finished track ends it cleanly + +## Goal + +When a publisher finishes a track while the subscriber is writing +SUBSCRIBE_UPDATE on that track's subscribe stream, the subscriber's track ends +cleanly with the publisher's finish, in JS and Rust, instead of failing with the +write's stream error. A real reset of the subscribe stream still fails the +track with the reset's error. + +## Plan + +Seen in the real-browser rename media case on #5635. `@moq/publish` finished +the old `video` track after a rename. The relay closed the subscribe stream +while the player wrote a SUBSCRIBE_UPDATE on it. The write threw "The stream +was aborted by the remote server". In `js/net/src/lite/subscriber.ts`, the +rejected `#runSubscriptionUpdates` won the `terminal` race, so the track closed +with that error. Watch logged a spawn error, and the media check failed on the +console error. It reproduced in one of five local runs on a loaded machine. + +Decided 2026-10-16 (recommended options; the paper trail is in the plan PR): + +- A failed update write defers to the subscribe stream's own outcome. If the + responses end cleanly, the track ends cleanly; if they reject, that error + wins. No retry and no timeout. +- Fix JS and Rust together. `rs/moq-net`'s `lite/subscriber.rs` serve loop + (`ServeMode::Select`) hands the track back with the flush error. Confirm + whether the same race fails a finished track there, and give it the same + rule. +- Regression tests in both languages: a publisher that finishes the track and + stops reading while an update is in flight. The subscriber's track ends + cleanly, and a reset still surfaces its error. Run + `just test interop --all`, since this is session behavior. + +Public API: none. Wire: none. + +## Related + +- [Browser follows a renamed track](/quest/m1/browser-rename-check.md) - the media check this race failed From aa9b3361db9d3a72ce7e2d055297e8ee1e4d6abe Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 16 Oct 2026 16:31:41 -0700 Subject: [PATCH 2/2] quest(m1): the audio rename quest starts once #5635 lands Co-Authored-By: Claude Opus 5.5 --- quest/m1/audio-jitter-target/audio-rename.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/quest/m1/audio-jitter-target/audio-rename.md b/quest/m1/audio-jitter-target/audio-rename.md index 0afb702ff2b..aa6dd0703e9 100644 --- a/quest/m1/audio-jitter-target/audio-rename.md +++ b/quest/m1/audio-jitter-target/audio-rename.md @@ -10,6 +10,10 @@ prior, as `doc/concept/audio-jitter.md` ("Across renditions") requires. ## Plan +Starts once #5635 lands. That PR adds `ConsumerProps.predecessor` to +`@moq/hang` and the video hand-off this quest mirrors; this quest adds no API of +its own. + Today the audio decoder's `#runLegacyDecoder` and `#runCmafDecoder` clear `#measured` on teardown, before the replacement subscription opens, and the new `Container.Consumer` starts from the prior. At a rename, the audio target