Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 56 additions & 30 deletions quest/m2/audio-playout/browser-audio-hole-skip.md
Original file line number Diff line number Diff line change
@@ -1,40 +1,66 @@
# [M] Browser audio keeps a hole a late burst still fills
# [L] Browser audio takes its holes from the ordered reader

## Goal

`@moq/watch`'s audio no longer skips a missing group that lands a moment
after the group past it: the Chromium `bursty` and `congestion` rows of
`just test audio-quality` grade no worse than before
[moq-dev/moq#8799](https://github.com/moq-dev/moq/pull/8799) gave the audio
consumer the player's clock, while the Firefox `after resume` window that PR
fixed stays audible.
`@moq/watch`'s audio reads its track through `@moq/net`'s ordered reader with
a reader budget equal to what the ring holds, and plays each `Gap` the reader
reports as the hole: the audio container consumer keeps no hole wait of its
own and no longer passes `playhead`. Video keeps the playhead. The Chromium
`bursty` and `congestion` rows of `just test audio-quality` grade no worse
than before [moq-dev/moq#8799](https://github.com/moq-dev/moq/pull/8799)
gave the audio consumer the player's clock, and the Firefox `after resume`
window that PR fixed stays audible.

## Plan

Native evidence, from the PR that gave the Rust consumer the same clock
Decided 2026-11-16 (maintainer, /quest-run): ✅ the transport decides an
audio hole, through an ordered reader whose budget is the ring's size
(rejected: first measure the playhead rule against a hand-written wait in
the container consumer, as this quest planned before; keep the playhead rule
and the separate wait).

Why the playhead rule goes: natively, ending an audio hole once the clock
reaches the group past it took `bursty` from 3 to 155 underruns a minute
(`just test audio-quality --runtimes native --codecs opus --duration 40
--seed 7`): ending an audio hole once the clock reaches the group past it
took `bursty` from 3 to 155 underruns a minute. A burst's groups land late
together, so the group past a hole is already due when the missing one lands
a moment later in the same burst. Ending it at the clock plus the 200 ms
stretch held `bursty` level but left `congestion` worse than the native
estimate wait (A/V lag p95 808 to 946 ms against 288 to 631 ms over three
runs each). `moq play` gives the clock to video only for that reason.

`js/watch/src/audio/decoder.ts` passes `playhead: this.sync` with a
`wait` of `sync.out.maxDelay`, so the browser has the rule that measured
worst natively. First measure: the Chromium `bursty` and `congestion` rows
with and without that `playhead`, a few runs each, since `congestion` is
noisy.

If the browser regressed, recommended: audio waits a hole out for its
playout estimate from the arrival of the group past it, as native audio does
(`rs/moq-audio/src/decode/consumer.rs`, `set_wait(self.delay())`), instead of
the playhead. That still ends the resume hole within one playout delay.
Confirm with #8799's repro, `taskset -c 4-5 nix develop --command just test
media --media-engines firefox --media-cases rename,pause`. Video keeps the
playhead.
--seed 7`). A burst's groups land late together, so the group past a hole is
already due when the missing one lands a moment later in the same burst.
Native audio instead waits a hole out for its playout estimate from the
arrival of the group past it (`rs/moq-audio/src/decode/consumer.rs`), and
[moq-dev/moq#8984](https://github.com/moq-dev/moq/pull/8984) makes that wait
the subscription's `Delay::min`. Rust `track::Ordered`
([moq-dev/moq#8910](https://github.com/moq-dev/moq/pull/8910)) gives up on a
missing group by the same two clocks: the live edge's timestamp a budget past
it, or its successor's arrival a budget ago. So the rule lives once, in the
transport.

Work:

- Mirror `track::Ordered`'s `Item::{Group, Gap { range, error }}` in
`@moq/net`, whose `Ordered` handle (`js/net/src/track.ts`) skips a stale or
dropped group silently today, with the reader's own budget as in Rust.
This is #8910's follow-up "mirror `Item` in `@moq/net` once a consumer
needs it"; the bindings follow when a binding consumer needs it.
- The budget is what the ring holds (`ring.held(delay)` in
`js/watch/src/audio/decoder.ts`), and follows it as the delay estimate,
stretch, and output latency move. It is the reader's, not the
subscription's: the subscription keeps reaching the estimator's 2 s
ceiling past the delay, since a group the relay expires is never observed
and the estimate could not rise after underruns.
- The audio container consumer (`js/hang/src/container/consumer.ts`, used
from `js/watch/src/audio/decoder.ts` and `replay.ts`) reads ordered for
audio, turns each `Gap` into its hole, and drops its own hole wait and the
`playhead` it is passed.
- Measure the Chromium `bursty` and `congestion` rows before and after, a few
runs each, since `congestion` is noisy. Confirm the resume hole with
#8799's repro, `taskset -c 4-5 nix develop --command just test media
--media-engines firefox --media-cases rename,pause`.

## Waiting

- moq-dev/moq: [#8910](https://github.com/moq-dev/moq/pull/8910) merges,
which defines `Item` and `Gap` for the JS mirror to follow.

## Related

- [A hole is waited for by the subscription's delay](/quest/m2/delay-hole-wait.md) - removes the separate wait this would keep for browser audio, so the two settle the same rule
- [A hole is waited for by the subscription's delay](/quest/m2/delay-hole-wait.md) - settles the wait rule this moves into the transport
- [moq-net publishes no item without a caller](/quest/m2/unused-api/net.md) - the Rust container reader moving onto `Gap`, this quest's native counterpart
2 changes: 1 addition & 1 deletion quest/m2/delay-hole-wait.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,4 +79,4 @@ loses `ConsumerProps.wait`. Wire: none.
## Related

- [Native audio playout is a library](/quest/m3/audio-playout-library.md) - moves the placement this wait feeds into moq-audio
- [Browser audio keeps a hole a late burst still fills](/quest/m2/audio-playout/browser-audio-hole-skip.md) - measures whether the browser's audio playhead over-skips, which decides the rule this quest applies to both languages
- [Browser audio takes its holes from the ordered reader](/quest/m2/audio-playout/browser-audio-hole-skip.md) - moves the browser audio hole rule this settles into `@moq/net`'s ordered reader