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
2 changes: 1 addition & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ moves what remains of them once their claims merge.
- [Group errors are cached by kind](/quest/m1/group-error-cache.md) - permanent group errors bind every reader, retryable ones are kept only for a bounded time, and a live SUBSCRIBE_DROP or FETCH answered `Old` no longer caches it for good
- [The overcommitted receive-window cells run again](/quest/m1/receive-windows-evicted.md) - `benchmark_receive_windows` measures its 256-stream and 4 MiB-frame cells again, reporting delivered frames and evictions instead of stalling
- [Stream credit by priority](/quest/m1/stream-credit/README.md) - every stream opens through one priority entry point, and a higher-priority group takes over or resets a lower one when credit runs out
- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; time-stretched browser playback without steady-state underruns and a native trace replay remain
- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; audio that slows down and catches up around it in every player, graded in that direction, and a native trace replay remain
- [Buffered playback subscribes in ascending order](/quest/m1/buffered-ascending.md) - a buffered `<moq-watch>` asks for the oldest group first, so a voice reply's opening arrives first, and audio's head hold shrinks to the floor
- [Push-to-talk's press-to-audible latency fits a budget on the defaults](/quest/m1/push-to-talk-latency.md) - press to audible on the browser defaults, excluding device output, stays under a kixtop-measured budget that `just test push-to-talk` enforces
- [Lifecycles are explicit state](/quest/m1/explicit-state/README.md) - every lifecycle the 2026-11-07 audit found implicit is one enum or union, fixing the bugs in the 11 lifecycles it redesigns, with review and agent rules against new ones
Expand Down
71 changes: 52 additions & 19 deletions quest/m1/audio-jitter-target/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,19 @@ at once got a target far too shallow to play through the next flush. One
written algorithm, cited by both implementations, produces the same target from
the same arrival trace.

Boundaries: both players converge on the target with NetEq's time stretch:
native playback by playing slightly faster or slower, and the browser only
faster, since its ring starts on the target and slowing down only settles audio
behind the shared clock. Underruns past the target are accepted, not covered
with latency. No packet loss concealment. Video keeps its own target; the
shared clock stays on local time, and the audio ring's stretch converges on it.
Every player follows one rule around that target, with NetEq's time stretch.
In steady state audio plays on the shared clock at the playout delay, which is
the expected resting point for audio and video alike. When the audio received
ahead of the playhead runs low, playback slows down and audio falls behind the
clock; once the buffer refills past the target, playback speeds up until audio
is back on it. Congestion then costs a gap and a catch-up instead of the audio
that arrived late.

Boundaries: zero underruns is not a goal, and neither the target nor a fixed
delay is raised to reach it. No packet loss concealment. Video stays on the
shared clock and shows a late frame when it arrives, so it recovers on its
own. Video measures no network term: the shared delay is the largest
requirement among the subscribed renditions, so video waits for audio's.

## Plan

Expand All @@ -35,14 +42,39 @@ target, in both players from one algorithm and its vectors:
[moq-dev/moq#7856](https://github.com/moq-dev/moq/pull/7856) natively and
[moq-dev/moq#8058](https://github.com/moq-dev/moq/pull/8058) in the browser's ring.

Decided 2026-11-08 (maintainer, on
[moq-dev/moq#8058](https://github.com/moq-dev/moq/pull/8058)): never add
latency to chase zero underruns. Audio and video keep separate clocks, which
align at steady state once the delay is right, so the browser's stretch only
steers audio back onto the clock and never settles it later to absorb jitter.
Some underruns during congestion are expected. The replay rows budget
`av_lag_ms`, how far audio trails the shared clock, exactly as measured, so a
change that buys underruns with latency fails them.
Decided 2026-11-09 (maintainer, /quest-plan): the rule in the Goal. It
replaces the 2026-11-08 decision on
[moq-dev/moq#8058](https://github.com/moq-dev/moq/pull/8058) that the browser
only plays faster and audio never settles later. Video gets the effect for
free, since a late frame shows at once and the picture is live again; audio
cannot, so without a slow-down and a catch-up a stall drops whatever audio
arrives late. What carries over from 2026-11-08: latency is never added to
reach zero underruns, and some underruns during congestion are expected.

- Players: ✅ `moq play`, a live `<moq-watch>`, and a buffered one, on one rule
(rejected: live only, with buffered mode keeping its own).
- Target: ✅ unchanged. The shared delay is
`max over subscribed renditions of (delay + target)`, where audio's target
is `max(measured, jitter) + frame` and video's is its catalog span
(rejected: a network term on every rendition; the plain sum
`delay + jitter + frame + measured`, which buffers a batched publisher's
batch twice; a catalog-only target).
- Video: ✅ on the same clock as audio, and audio alone speeds up and slows
down with the network (rejected: video at its catalog target, with audio
trailing it by the measured lateness).
- Target moves: ✅ the estimator stays as it is, and audio glides to each new
target by stretching (rejected: a slew limit on the measured term, which
the spec already declined as a second knob; deleting the estimator and
letting the lag be the only network term, which underruns a 20 ms Opus
target until the lag builds).
- Bound: ✅ configurable, as
[the `stretch` setting](/quest/m1/audio-jitter-target/stretch-setting.md)
records.
- Tests: no gate may reward moving away from the rule, so
[the grading quest](/quest/m1/audio-jitter-target/grading.md) lands before
[the model](/quest/m1/audio-jitter-target/stretch.md).
- Milestone: ✅ every new child in m1, here (rejected: the model and grading
in m0; the setting in m2).

Decided 2026-11-04 (maintainer), for push-to-talk's silence suppression
([moq-dev/moq#7942](https://github.com/moq-dev/moq/pull/7942)): a silence the publisher declares
Expand All @@ -57,13 +89,14 @@ native playback against its budgets.

## Required

- [Browser ceilings](/quest/m1/audio-jitter-target/browser-ceilings.md) - the chromium rows' ceilings re-measured from seven Nightlies with the browser's time stretch, budgeting `player_skips_per_min`
- [Native stretch](/quest/m1/audio-jitter-target/native-stretch.md) - `moq play` copies NetEq's accelerate and preemptive expand, sharing the browser's seams and vectors, so its native rows play with no audible glitch once the target settles
- [Buffered converge](/quest/m1/audio-jitter-target/buffered-converge.md) - a buffered `<moq-watch>` time-stretches its audio back onto the shared clock after a stall or drift, so lip sync returns and no audio group is dropped
- [Grading](/quest/m1/audio-jitter-target/grading.md) - the audio harness grades steady-state lag, dropped audio, and recovery from a stall, with no gate fixed at zero underruns or zero lag
- [Stretch model](/quest/m1/audio-jitter-target/stretch.md) - every player slows down when its buffer runs low and speeds up once it refills, by one rule and one set of vectors, buffered mode included
- [The `stretch` setting](/quest/m1/audio-jitter-target/stretch-setting.md) - a player sets how far audio may trail before it skips, and zero turns the stretch off
- [Calibrate](/quest/m1/audio-jitter-target/calibrate.md) - every browser and native ceiling re-measured from seven Nightlies with the model
- [Capped budgets](/quest/m1/audio-jitter-target/capped-budgets.md) - the AAC browser budgets are re-measured from nightlies after the TS importer groups each PES
- [Native A/V lag](/quest/m1/audio-jitter-target/native-av-lag.md) - `moq play` reports how far audio trails its presentation clock, and native stops expanding into the gap between arrivals if it settles audio late
- [Native A/V lag](/quest/m1/audio-jitter-target/native-av-lag.md) - `moq play --metrics` reports how far audio trails its presentation clock, so native rows grade `av_lag_ms`
- [Native rendition delay](/quest/m1/audio-jitter-target/native-rendition-delay.md) - `moq play` holds each subscribed rendition's catalog `delay` plus its target, as the browser does
- [Chromium Opus stalled share](/quest/m1/audio-jitter-target/opus-stalled-share.md) - the Chromium Opus browser rows stay under the 0.01 stalled-share budget every night
- [Chromium Opus stalled share](/quest/m1/audio-jitter-target/opus-stalled-share.md) - the Chromium Opus browser rows' stalled-share ceiling is measured with the stretch, and passes

## Closes

Expand Down
56 changes: 0 additions & 56 deletions quest/m1/audio-jitter-target/browser-ceilings.md

This file was deleted.

65 changes: 0 additions & 65 deletions quest/m1/audio-jitter-target/buffered-converge.md

This file was deleted.

59 changes: 59 additions & 0 deletions quest/m1/audio-jitter-target/calibrate.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# [S] Re-measure every audio ceiling after the stretch model lands

## Goal

`test/audio-quality/budgets.json` carries every browser and native row's
ceilings re-measured, by the rule in its note, from seven scheduled Nightly
runs on a `main` that includes
[the stretch model](/quest/m1/audio-jitter-target/stretch.md). The rows budget
steady-state lag, the player's own trims and skips, and underruns as
measured, and the note says the model is in them.

## Plan

Planned 2026-11-09 (maintainer, /quest-plan). This replaces two waits that
were calibrating a player the model changes: the chromium re-measure after
[moq-dev/moq#8058](https://github.com/moq-dev/moq/pull/8058) and the native
one after [moq-dev/moq#8308](https://github.com/moq-dev/moq/pull/8308). Nights
before the model merges do not count.

Carried decisions:

- 2026-11-07 (maintainer, on #8058): ✅ land the player change, then measure
(rejected: hold it until Nightly ceilings are in). The goal is judged by
the rows alone, with no listening run.
- 2026-11-09 (maintainer, on
[moq-dev/moq#8308](https://github.com/moq-dev/moq/pull/8308#issuecomment-6730322286)):
✅ budget `trimmed_ms_per_min` and `player_skips_per_min` (rejected:
budgeting accelerates as discarded audio), and ✅ the nightly runner's
`bench-playback` counts as the quiet-host run (rejected: naming another
host).

The rule: the worst of seven clean nights times 1.25, plus the documented
runner hiccup, rounded to two significant figures. A developer run is not
that calibration. Keep each night's rows in the PR body.

What to report rather than budget: a steady-state `av_lag_ms` p50 more than a
frame above zero on any row but `step`, or a nonzero `player_skips_per_min`
on a row whose stalls fit inside the `stretch` bound. Either means the model
is not doing its job there.

Native rows stay report-only; enforcing them belongs to
[Audio outlives video under bufferbloat](/quest/m4/audio-bufferbloat-av.md).

## Waiting

- moq-dev/moq: seven scheduled Nightly runs on `main` after the stretch model
merges. Find them with `gh run list --workflow nightly.yml --event
schedule` and download each with `gh run download <id> -n
audio-quality-run` as it lands, since artifacts expire after 7 days. Never
dispatch the nightly by hand.

## Required

- [Stretch model](/quest/m1/audio-jitter-target/stretch.md) - the player these ceilings measure

## Related

- [Capped budgets](/quest/m1/audio-jitter-target/capped-budgets.md) - re-measures the AAC browser rows after the TS importer change; if it has not finished when the model lands, these seven nights serve both
- [Chromium Opus stalled share](/quest/m1/audio-jitter-target/opus-stalled-share.md) - the one ceiling failing nightly today
Loading