Skip to content

fix(watch,hang): browser Opus plays through a reader gap with nothing missing - #9191

Merged
kixelated merged 3 commits into
mainfrom
quest/m2/audio-playout/browser-audio-hole-skip
Nov 19, 2026
Merged

kixelated merged 3 commits into
mainfrom
quest/m2/audio-playout/browser-audio-hole-skip

Conversation

@kixelated

@kixelated kixelated commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Grades the Chromium bursty and congestion rows after moq-dev/moq#9068 moved browser audio onto the ordered reader, and fixes the one regression the grade found.

The first scheduled night after #9068 (2026-11-18, 44342367698) put 112 tap underruns a minute on chromium-opus-48000-bursty, where every earlier night had none. These were about one 4 to 6 ms hole a second, with zero player underruns and no media missing from the capture (3127 one-frame groups, contiguous). Two defects combined to cause them:

  • A reader gap where nothing was missing was played as a loss. Opus groups are keyed by their timestamp in microseconds, so 19999 keys between groups are never used. When the ordered reader gave such keys up as a gap and the consumer judged it before the next group's first frame had landed (another group's arrival wakes it), it could not see that the media continued. So it marked a loss, which next() returns as a zero-length gap read. Consumer now records the reader's gap and decides at the next item read: it is a loss only if that item does not continue the timeline (#gapped, resolved in #emit).
  • Every gap cut 6.5 ms of real Opus audio. A gap restarts the codec and re-primes it with the history before the gap. Terminal then trimmed output before the first frame's timestamp, but span maps output a pre-skip earlier, because an Opus packet decodes to the encoder's lookahead before its timestamp. So each restart dropped the first 312 samples of real audio after the gap. The cutoff is now where the frame's output lands (timestamp - delay), so a gap with nothing missing is seamless, and a real gap loses only what was missing.

Also:

  • The routine skipping covered group warning is gone. It fired for most Opus groups in normal playback (197 of every 200 console notes the harness keeps, so it buried the warnings that mattered) for a skip that loses nothing by definition.
  • The replay declares the keys between back-to-back groups skipped, as a timestamp-keyed publisher's appends do on the wire, and leaves keys around missing media owed. Before this, no Nightly capture since the publishers moved to timestamp keys could be replayed: the 11-18 Opus capture starved for its whole minute in replay. A group whose media overlaps the one below also reads as back to back, as the consumer's ptsContiguous does. The committed replay rows use consecutive keys and do not move.
  • The quest is rewritten to what remains: grading the first nights after this lands on the runner.

The starvation (quest item)

The one 7.5 s starvation seen locally during #9068 was not reproduced. The suspected mechanism (an active group that opens but never delivers a frame, which #8799's playhead used to pass) is bounded in ordered mode: the ordered subscription expires such a group one hole wait after its successor lands. A new consumer test pins this (passed at exactly 100 ms for a 100 ms wait), so a trace does not need to record group opens. The runner has never shown it (stalled_share 0 on every Opus bursty night).

Grade, nightly runner

Chromium rows from the audio-quality-run artifacts (per minute unless noted). Before #8799: 11-13 to 11-15. Between: 11-16, 11-17. After #9068: 11-18.

row night tap und. p. skips trimmed ms stalled silence lag p50 lag p95
opus bursty 11-13 / 14 / 15 0 / 0 / 0 0 / 0 / 0 0 / 0 / 0 0 0 18.2 / 17.5 / 5.8 26 / 25.6 / 11.5
opus bursty 11-18 112.4 0 0 0 0.003 3.3 9.7
aac bursty 11-13 / 14 / 15 0 0 0 0 0 37.2 / 14.2 / 3.5 45.4 / 46 / 3.6
aac bursty 11-18 0 0 0 0 0 -1.8 4.6
opus congestion 11-13 / 14 / 15 0 0 / 2.2 / 1.1 0 / 2239.5 / 2626.4 0.045 / 0.036 / 0.045 0.051 / 0.038 / 0.047 52.1 / 20.4 / 6.6 1434.5 / 44.7 / 19.3
opus congestion 11-18 0 15.3 1351.1 0.041 0.038 4.8 16.1
aac congestion 11-13 / 14 / 15 0 0 / 1.1 / 1.1 0 / 2309.5 / 2563.1 0.027 / 0.041 / 0.045 0.031 / 0.039 / 0.044 18.2 / 13 / 3.1 692.5 / 23 / 3.8
aac congestion 11-18 0 6.5 1319.5 0.036 0.04 4.3 4.5

Apart from Opus bursty's tap underruns, which this PR fixes, 11-18 is level with or better than before #8799. Congestion trims about half the audio and takes more, smaller skips, with stalled and silence shares level. Every 11-18 row is within budgets.json. One night is thin, so the quest stays open for the nights after this lands.

Grade, replay on identical arrivals

Every Chromium bursty and congestion capture from 11-16 to 11-18 replayed through the player just before #9068 (527b8937a9~1) and through this PR, both with the replay's skip rule, graded by analyze.ts past the 5 s warmup. The replay models no codec, so it cannot show the restart hole; it compares the hole decisions. (A third tree before #8799 misplays these timestamp-keyed captures, AAC bursty trailing 168 ms where its live nights rested at 3.5 ms, so it is left out.)

capture code p.und/min skips/min trim ms/min stalled silence lag p50 lag p95 target p95
43909101837-aac-44100-bursty before #9068 0 0 0 0 0 0.3 0.3 323.2
43909101837-aac-44100-bursty this PR 0 0 0 0 0 -0.8 -0.8 323.2
43909101837-aac-44100-congestion before #9068 2.2 4.3 1572.2 0.032 0.032 0 3 209.2
43909101837-aac-44100-congestion this PR 2.2 4.3 1572.2 0.032 0.032 0 2.1 209.2
44127032469-aac-44100-bursty before #9068 0 0 0 0 0 0.9 1.4 323.2
44127032469-aac-44100-bursty this PR 0 0 0 0 0 0.9 1.4 323.2
44127032469-aac-44100-congestion before #9068 2.2 3.3 1869.2 0.041 0.04 3.2 8.9 209.2
44127032469-aac-44100-congestion this PR 2.2 1.1 2205.4 0.041 0.04 3.2 8.9 209.2
44342367698-aac-44100-bursty before #9068 0 0 0 0 0 1 1 263.2
44342367698-aac-44100-bursty this PR 0 0 0 0 0 1 1 263.2
44342367698-aac-44100-congestion before #9068 2.2 4.4 2089.4 0.036 0.041 0.3 0.3 209.2
44342367698-aac-44100-congestion this PR 2.2 1.1 2442.5 0.036 0.041 0.3 1.3 209.2
43909101837-opus-48000-bursty before #9068 0 0 0 0 0 -3.1 4.9 120
43909101837-opus-48000-bursty this PR 0 0 0 0 0 -1.3 -1.1 120
43909101837-opus-48000-congestion before #9068 2.2 1.1 1605.7 0.036 0.037 4.2 13 180
43909101837-opus-48000-congestion this PR 2.2 1.1 1779.3 0.041 0.039 -1.9 9.8 180
44127032469-opus-48000-bursty before #9068 0 0 0 0 0 1.2 1.2 140
44127032469-opus-48000-bursty this PR 0 0 0 0 0 -0.2 -0.2 140
44127032469-opus-48000-congestion before #9068 2.2 2.2 1714.6 0.036 0.038 3.9 4.7 140
44127032469-opus-48000-congestion this PR 2.2 5.4 1866.5 0.036 0.038 1.7 2.8 60
44342367698-opus-48000-bursty before #9068 0 0 0 0 0 0.6 6 180
44342367698-opus-48000-bursty this PR 0 0 0 0 0 0.7 2.4 180
44342367698-opus-48000-congestion before #9068 2.2 1.1 1603.8 0.036 0.037 2.7 12.1 180
44342367698-opus-48000-congestion this PR 2.2 4.3 1625.5 0.036 0.036 0.3 11.9 180

Bursty is level or better on every capture. Congestion trims more on five of six (+22 to +353 ms a minute) with stalled and silence shares level: audio the old consumer gave up as missing groups (it logged up to 12 per run against 5 to 6 here) now arrives late and is skipped onto the clock, so the listener hears the same.

Decisions

Taken while the maintainer is away. Each can be undone in review:

  • Fixed the regression in this PR rather than only grading it. Both fixes are small, and without them the quest could not grade "no worse".
  • The Terminal cutoff moves for every gap, not only one with nothing missing. After a real gap, the 6.5 ms of the next packet's lookahead now plays where it was dropped. The alternative was keeping the cut for real gaps, but that audio belongs to the frame after the gap, as the hang draft's presentation time says.
  • The consumer defers only an ordered reader's gap to the next item's continuity. A truncated group or a skipped marker group still marks a loss unconditionally, since a lost end marker can precede a fresh encoder whose codec must restart even when timestamps line up.
  • Removed the skipping covered group warning outright rather than demoting it, since nothing reads it and it fires in normal playback.
  • Rewrote the quest to what remains, sized S, rather than deleting it: its Goal asks for the grade on the nightly runner, which only nights after this lands can give.

Validation

  • Downloaded six nights' audio-quality-run artifacts (11-13 to 11-18) and tabulated the four rows (above). In the 11-18 Opus bursty capture, the 52 tap gaps came with zero player underruns, and the arrivals show no missing media. The page log shows skipping missing groups: 374660001 -> 374680000, a range strictly between two adjacent 20 ms groups.
  • Live, on this host (load around 18), just test audio-quality --runtimes chromium --codecs opus --profiles bursty --duration 60 --capture:
    • this PR: 0 tap underruns, 0 short quanta, 0 gap ms a minute, A/V lag p50 0.6 ms;
    • this PR with the Terminal and consumer changes reverted: 136.8 underruns, 62.4 short quanta, 306.2 gap ms a minute, the runner's 11-18 signature (112.4, 54.6, 252.9). Its console logged 12 skipping missing groups in its 200-note window, against 2 here.
  • Replayed all 12 captures on both sides of Browser audio takes its holes from the ordered reader #9068 (table above), and just test audio-quality --replays --enforce: every committed replay row is unchanged and within budget.
  • New tests, each failing on the old code: a gap with nothing missing leaves no hole in Opus output (terminal.test.ts) and a gap over keys that held no media is no loss (consumer.ordered.test.ts, old code reads gap 20+0). Also a gap over keys that held media is still a loss and an open group that never delivers a frame is passed once the reader's wait ages it. The existing test that asserted the 312-sample cut now asserts the frame plays whole.
  • waits out only the keys around missing media when groups are keyed by timestamp (replay.test.ts): with the old Math.abs rule, groups overlapping by 2 ms starve the replay (0 ms heard, against 9944 ms back to back); with the one-sided rule both play 9944 ms, and a missing group still underruns.
  • bun test in js/hang (786 pass) and js/watch (644 pass), just check passed.

Public API

None. Behavior: browser Opus after a gap plays the frame's whole output, 6.5 ms more than before, and a reader gap over keys with no media no longer restarts the codec. @moq/hang's Consumer no longer logs skipping covered group. Wire: none.

Caused by

  • moq-dev/moq#8980 - re-primed the codec after a gap but trimmed output before the frame's timestamp rather than where its output lands, dropping a pre-skip of real Opus audio at every gap (found by check, the Nightly audio-quality tap underruns)
  • moq-dev/moq#9068 - marked an ordered reader's gap a loss when the consumer judged it before the next group's first frame landed, so gaps over never-used timestamp keys restarted the codec (found by check, the same row)

Follow-ups

None new. The quest keeps grading the nights after this lands.

Models

Size: M
Implementer: Claude Code, claude-opus-5-5, high effort
Implementer: Claude Code, claude-opus-5-5, medium effort (iterate, XS, arm B)

(Written by Claude Opus 5.5 with high, iterated by Claude Opus 5.5 with medium)

Review

Rewritten by quest review after each round.

  • Head: f30fb10

  • Base: origin/main at 075130c

  • Risk: medium, The changes could disrupt audio continuity or gap handling for browser playback consumers, but preserve public APIs and wire formats, and a revert fully undoes them.

  • Classified: medium by Codex, gpt-6.1-sol, low effort, session 01a1f59e-d7a3-7af2-a9fa-64e63296342f

  • Reviewer: Codex, gpt-6.1-sol, high effort

  • Session: 01a1f59e-ed1c-7742-9ea6-5be1e4a5aa23, round 1

  • Score: 8/10, No actionable defects were found after tracing ordering, codec restart, and replay behavior, but builds and tests were prohibited.

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

  • Findings: none

kixelated and others added 2 commits November 19, 2026 07:56
… missing

A reader gap over keys a timestamp-keyed publisher never used was marked a
loss when the consumer judged it before the group's first frame landed, and
every gap restarted the Opus codec with a cut at the frame's timestamp, which
dropped the pre-skip of real audio. Together they put about one 4 to 6 ms hole
a second into browser Opus playback on the bursty Nightly row.

- Terminal cuts restarted output where the frame's output lands, a pre-skip
  before its timestamp.
- An ordered reader's gap is a loss only if the next item does not continue
  the timeline.
- The routine covered-group skip no longer warns.
- The replay declares the keys between back-to-back timestamp-keyed groups
  skipped, so Nightly captures replay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Browser audio's ordered reader grades no worse than before #8799 fix(watch,hang): browser Opus plays through a reader gap with nothing missing Nov 19, 2026
@kixelated
kixelated marked this pull request as ready for review November 19, 2026 16:27
@coderabbitai

coderabbitai Bot commented Nov 19, 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 48 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: 0d79238f-bfef-41ab-a7fc-4258e3b2332c
Commits

Reviewing files that changed from the base of the PR and between a4fa80a and f30fb10.

Files selected for processing: 8

  • js/hang/src/container/consumer.ordered.test.ts
  • js/hang/src/container/consumer.ts
  • js/watch/src/audio/replay.test.ts
  • js/watch/src/audio/replay.ts
  • js/watch/src/audio/terminal.test.ts
  • js/watch/src/audio/terminal.ts
  • quest/m2/audio-playout/browser-audio-hole-skip.md
  • test/audio-quality/README.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

@kixelated

Copy link
Copy Markdown
Collaborator Author

Merge pick (maintainer away, granted the coordinator merges it confidently recommends): ✅ /quest-merge, accepting the decisions listed in the PR body (the pre-skip cutoff applies to every gap, the loss check covers only transport gaps, the quest rewritten to wait for nightly grades).

(Written by Claude Opus 5.5 with high)

@kixelated
kixelated enabled auto-merge November 19, 2026 16:29

@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 critical issues — one small mismatch in the replay's skip rule, noted inline.

Approach: sound. The PR moves the ordered-gap loss decision from group promotion, where the head's first frame may not have landed yet, to #emit, where the next item's timestamp is known. It also puts Terminal's cutoff on the same timeline span maps output onto. Each fix addresses the root cause of one half of the tap-underrun signature.

Reviewed changes

I reviewed the full diff at 21286cd: the consumer, terminal and replay changes, their tests, the quest rewrite and the README note.

  • Deferred ordered-gap loss: #gapped records the keys the ordered reader gave up on, and #emit marks a loss only when the next item does not continue #edge. The non-ordered path, truncation and the skip paths still set #lost unconditionally.
  • Terminal cutoff: #before is now timestamp - delay + max(0, warmup - primed), so restarting the codec after a gap keeps the frame's whole output and no longer cuts 312 samples.
  • Replay skip declaration: when the next group lands, the replay declares the keys between two back-to-back groups skipped and leaves the keys around missing media owed.
  • Warning cleanup: the routine skipping covered group warning is removed.
  • Tests: new consumer tests cover a gap over unused keys, a gap over real media and an open group that never delivers a frame. A new terminal test checks that output is seamless across a restart.

Note: 1 inline comment(s) dropped because they did not anchor to lines inside the PR diff:

  • js/watch/src/audio/replay.ts:237 (RIGHT) — line 237 (RIGHT) is not inside a diff hunk

Pullfrog  | Fix it ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

… the consumer does

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated disabled auto-merge November 19, 2026 21:06
@kixelated

Copy link
Copy Markdown
Collaborator Author

Answering the inline note from Pullfrog's review, which was dropped for anchoring outside the diff (replay.ts:232: Math.abs rejects a group overlapping the one below, where the consumer's ptsContiguous accepts it).

Fixed in f30fb10 as suggested: the replay's skip rule now checks only one side. It mattered more than a nit. In a new test, groups overlapping by 2 ms starved the whole replay under the old rule (0 ms heard, against 9944 ms back to back), since every key between them stayed owed.

(Written by Claude Opus 5.5 with medium)

@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.

Reviewed changes

Reviewed the one new commit since the prior pullfrog review (21286cd → f30fb10).

  • One-sided replay contiguity: the replay now treats a group as back to back when it starts at or before the end of the group below plus 1 ms, matching the consumer's ptsContiguous. This resolves the Math.abs mismatch noted in the prior review.
  • Replay test: waits out only the keys around missing media when groups are keyed by timestamp covers exact and overlapping groups, which play the same audio, and a missing group, which still underruns.

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

@kixelated
kixelated added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit f1b2a08 Nov 19, 2026
7 checks passed
@kixelated
kixelated deleted the quest/m2/audio-playout/browser-audio-hole-skip branch November 19, 2026 21:33
kixelated added a commit that referenced this pull request Nov 20, 2026
Resolves hang's consumer against #9191: a gap the ordered read reports defers its loss
verdict to the next item's timeline continuity, and a data marker's untimed end counts
as a loss behind a gap, since it cannot show the timeline continues.

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