Skip to content
Merged
54 changes: 0 additions & 54 deletions quest/m0/3477-watch-auto-latency.md

This file was deleted.

2 changes: 1 addition & 1 deletion quest/m0/3479-mux-jitter-flush-span.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,5 +61,5 @@ The work:

## Related

- [Auto latency](/quest/m0/3477-watch-auto-latency.md) - reads this field as its codec floor
- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - reads this field as its codec floor
- [#3208](/quest/m1/3208-make-2-5-ms-opus-frame-durations-work-across-bindings.md) - the same ceiling rule for Opus frame durations
2 changes: 1 addition & 1 deletion quest/m0/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ regression test per Root Cause First.

## Quests

- [Auto latency](/quest/m0/3477-watch-auto-latency.md) - js/watch: the measured auto latency (#3517 on dev) is proven clean in a browser and against the public relay
- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured, ported estimate of arrival timing in both languages, not a round-trip guess
- [Jitter estimator](/quest/m0/3479-mux-jitter-flush-span.md) - moq-mux: catalog jitter is the publisher's maximum flush span, never a running minimum
- [WebKit gate](/quest/m0/webkit-webtransport-gate.md) - js/net: every WebKit engine takes the WebSocket path, not just the Safari brand, so iOS Chrome and Firefox stop freezing after two minutes
- [IETF error codes](/quest/m0/ietf-error-codes.md) - every code on a moq-transport wire is a registered value for the negotiated draft, requests and stream resets alike
Expand Down
58 changes: 58 additions & 0 deletions quest/m0/audio-jitter-target/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Audio jitter target

## Goal

The audio playout target is a measured estimate of arrival timing, ported from
a known-good implementation, in the browser and natively alike. The round-trip
formula is gone. `max(20ms, 1.25 x minRtt)` sized the buffer for a single
retransmit, which describes how long the network takes to recover a loss and
not how unevenly a publisher emits frames, so a sender flushing 100 ms of media
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: convergence still uses skip-ahead and silence, so playing slightly
faster or slower to converge stays [Time
stretch](/quest/m2/watch-audio-time-stretch.md). No packet loss concealment.
Video keeps its own target; making the audio playhead the clock is [Plan: A/V
clock](/quest/m1/plan-av-clock.md).

## Plan

Three quests: the survey and the written algorithm first, then one
implementation per language against it. The two implementations are
independent once the spec lands and may run in parallel.
Comment thread
kixelated marked this conversation as resolved.
Resolved

PR #3517 stays open and is fixed in place by the watch quest rather than
restarted. It already deleted the RTT term and plumbed a per-track arrival
`spread` through `Container.Consumer`, measured at container frame arrival and
before the age budget can skip a group, which is the right observation point.
What it got wrong is the estimator on top. A viewer on that branch reads a
14.56 s jitter buffer in auto, and the cause is reproduced in
[Spec](/quest/m0/audio-jitter-target/spec.md): the "plus one frame" term is
learned from the first gap between observed timestamps, so a tune-in across a
stale group sets it to seconds, and nothing clamps the target or bounds how
fast it rises.

Native has no jitter buffer at all. `rs/moq-audio`'s decode `Config` carries
only `latency_max`, an upper bound before skipping a stalled group, and its own
doc comment promises "a companion `latency_min` for jitter-buffer padding will
land in a follow-up". This questline is that follow-up.

## Quests

- [Spec](/quest/m0/audio-jitter-target/spec.md) - survey what already exists, then write the algorithm down once
- [Watch](/quest/m0/audio-jitter-target/watch.md) - js/watch and js/hang implement it, fixing #3517 in place
- [Native](/quest/m0/audio-jitter-target/native.md) - rs/moq-audio grows `latency_min` from the same algorithm

## Closes

- [#3477](https://github.com/moq-dev/moq/issues/3477) - close this issue when the questline finishes
- [#2812](https://github.com/moq-dev/moq/issues/2812) - the iOS stutter report the same estimator fixes

## Related

- [Jitter estimator](/quest/m0/3479-mux-jitter-flush-span.md) - the advertised flush span, whose relationship to the measured target the spec settles
- [Audio quality harness](/quest/m2/audio-quality-harness/README.md) - the automated proof, built on its own schedule
- [Time stretch](/quest/m2/watch-audio-time-stretch.md) - inaudible convergence, on top of this
- [Plan: A/V clock](/quest/m1/plan-av-clock.md) - the clock this target eventually feeds
62 changes: 62 additions & 0 deletions quest/m0/audio-jitter-target/native.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# [M] rs/moq-audio: a measured jitter buffer, not just an upper bound

## Goal

Native playback holds a jitter buffer sized by the algorithm from
[Spec](/quest/m0/audio-jitter-target/spec.md), and passes the same conformance
vector as the browser on the same trace. `moq play` on a path with uneven
arrivals plays through a flush without underrunning, where today it has nothing
to absorb one.

Boundaries: no time-stretching and no loss concealment, matching the browser.
Video keeps its own path.

## Plan

`rs/moq-audio` has no jitter buffer at all. `decode::Config` carries only
`latency_max`, an upper bound before skipping a stalled group, and its doc
comment already promises the companion:

> The `_max` suffix is a reminder that we never *add* latency here: the consumer
> skips only when newer data is already this far ahead. A companion
> `latency_min` for jitter-buffer padding will land in a follow-up.

- Measure arrivals at the same point the browser does, on the container
consumer before the age budget can skip a group, so both languages estimate
from the same observation.
- Add `latency_min` to `decode::Config`, additive on a `#[non_exhaustive]`
struct, so it targets `main`. Its exact contract is a decision this quest
makes and records, not something to leave to the reader, because "floor" and
"fixed target" behave differently under an adaptive estimator:

1. **Floor.** `Some(d)` is a lower bound and the estimator may still raise
the target above it. Recommended: it matches how the browser treats a
rendition's advertised delay, and a viewer asking for more buffer rarely
means "and never more than that".
2. **Exact target.** `Some(d)` pins the target and disables adaptation,
mirroring a fixed browser preset exactly. Choose this if preserving a
fixed-latency preset byte for byte matters more than the parallel above.

Either way, state the precedence against the estimator and against
`latency_max`, and what happens when the requested floor exceeds the
effective `latency_max` that `Consumer` already clamps to publisher
retention. Refusing that combination loudly beats silently clamping it.
- The estimator itself is internal. Only the config field and whatever the
playback path needs to report its current target become public, and each one
is argued for rather than exposed by default.
- `rs/moq-cli` `play` gets the matching knob, and `doc/bin/cli.md` follows. Check
the examples against `--help`.
- The playback sink holds the target the way the browser's rings do: slack above
it, land on it when skipping, re-stall when dry so the next insert refills to
the target rather than playing on an empty cushion.
- Tests: the conformance vector from the spec, plus a decode-path test that
replays the same trimmed arrival trace the browser replays and asserts the
same target series.

`latency_min` is the natural name only because `latency_max` already exists. If
it reads wrong next to a `Duration` that is a floor rather than a budget,
propose alternatives with a recommendation rather than shipping it.

## Required

- [Spec](/quest/m0/audio-jitter-target/spec.md) - the algorithm this implements
Loading
Loading