diff --git a/quest/m2/README.md b/quest/m2/README.md index a6ec3f47689..ebfc42924ec 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -180,7 +180,7 @@ lite-07; bitrate enforcement is not part of this release. - [Relay io_uring packages](/quest/m2/relay-io-uring-package.md) - Linux relay packages ship io_uring once the ring is on par with tokio - [io_uring thread check](/quest/m2/uring-transport-machines.md) - the relay fanout bench measures `moq_uring::transport::Local`'s per-call thread check after the transport is boxed, removing it only if it shows - [Opus implementation](/quest/m2/audio-opus-backend.md) - compare Opus codec quality, CPU, build cost, and the loss recovery each backend offers -- [Latency ledger](/quest/m2/latency-ledger.md) - a viewer reports its share of playback delay stage by stage: jitter buffer, decode, render, and device +- [Latency ledger](/quest/m2/latency-ledger.md) - a viewer reports its share of playback delay stage by stage: jitter buffer and device - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - Windows decodes HE-AAC, multichannel AAC, and what else the MFTs offer - [Media Foundation encode](/quest/m2/audio-encode-mediafoundation.md) - Windows encodes AAC-LC - [MediaCodec on an emulator](/quest/m2/android-mediacodec-ci.md) - moq-video's MediaCodec tests run nightly on an Android emulator, in a lane the audio MediaCodec quests reuse diff --git a/quest/m2/latency-ledger.md b/quest/m2/latency-ledger.md index 2b776237279..afc6242490e 100644 --- a/quest/m2/latency-ledger.md +++ b/quest/m2/latency-ledger.md @@ -2,12 +2,12 @@ ## Goal -A running viewer can report where its share of the audio delay went (jitter -buffer, decode, render, and output device), stage by stage, through the -public API in both languages. The numbers a user reads when debugging their -own latency are the numbers the harness grades, because they come from the -same place. Publisher and network stages, and an end-to-end total, wait for -a clock that spans the whole path; none exists today. +A running viewer reports where its share of the audio delay went (the jitter +buffer and the output device) through its `.echo` feedback snapshot, in both +languages. The numbers a user reads when debugging their own latency are the +numbers the harness grades, because they come from the same place. Decode and +render stay internal; publisher and network stages, and an end-to-end total, +wait for a clock that spans the whole path, and none exists today. ## Plan @@ -16,23 +16,41 @@ probes, which was the right trade to get it running. This quest promotes them. - Decided 2026-10-08: scope to the viewer's stages. No clock spans publisher to viewer, so the harness reports end-to-end as null. -- Take the viewer stages of the schema the harness already defines - (`jitter_buffer`, `decode`, `render`, `device`) and expose them as fields of - the hang stats and feedback snapshots (`rs/hang/src/stats.rs`, - `rs/hang/src/echo.rs`, and their `@moq/hang` mirrors), rather than a - second readout: an observable value a stats or `.echo` track already - carries, not a callback. Decided so viewers report latency the same way - they report stalls. -- Both languages, matching names, per the repo's cross-language rule. Scrutinise - each exported item: a stage nobody outside can act on stays internal. -- Switch the harness over, deleting the probes it replaces. A ledger with no - consumer is how this drifts from reality. +- Decided 2026-10-30: wait for both feedback reporters (see Required), then + fill the fields from each reporter's tally rather than adding a second + per-player readout the reporters would have to fold in later. +- Decided 2026-10-30: replace the producer-less scalar `latency` on + `hang::echo::Rendition` (`rs/hang/src/echo.rs`), `Echo.RenditionSchema` + (`js/hang/src/echo.ts`), and `ViewerRendition` in + `drafts/draft-lcurley-moq-hang.md` with an object of stages: + `latency: { jitterBuffer?, decode?, render?, device? }`, each integer + milliseconds and absent when unmeasured. The schema is unreleased, so this + breaks no one. +- Decided 2026-10-30: export only `jitterBuffer` and `device`. The decoder + runs inside the jitter-buffer span, so `decode` is zero while the ring holds + anything, and `render` is a fixed ring-to-graph handoff (one 128-frame + quantum in the browser); neither is something a viewer can act on. They stay + unmeasured in the harness schema. +- Decided 2026-10-30: leave the publisher snapshot (`rs/hang/src/stats.rs`) + alone. Every viewer stage belongs in feedback, and publisher stages wait for + a spanning clock. +- Both languages, matching names, per the repo's cross-language rule. +- Switch the harness over, deleting the probes it replaces. Today + `test/audio-quality/clients/js/src/probe.ts` reads `sync.out.delay` and + `AudioContext.outputLatency + baseLatency`, and natively `moq play --metrics` + writes the presentation target. A ledger with no consumer is how this drifts + from reality. - Keep the harness's terms: one duration unit, every timestamp on a named clock, and stages as exclusive spans that cannot both claim the same milliseconds. Inherit those from the schema rather than restating them, so the sum-to-end-to-end identity (with its named `unaccounted` remainder) can be added once a spanning clock exists. +## Required + +- [Browser reporters](/quest/m2/stats/js.md) - `` publishes the feedback snapshot these stages join +- [Rust reporters](/quest/m2/stats/rust.md) - `moq play --echo` publishes the feedback snapshot these stages join + ## Related - [QoS](/quest/m2/qos/README.md) - relay-side health, the same idea from the other end diff --git a/quest/m2/stats/README.md b/quest/m2/stats/README.md index 98046d562b1..c6e5f84b87c 100644 --- a/quest/m2/stats/README.md +++ b/quest/m2/stats/README.md @@ -126,4 +126,4 @@ connection view and the dashboard flow. - [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - a Rust encoder adapts its bitrate to what its viewers report - [Latency ledger](/quest/m2/latency-ledger.md) - adds the viewer's latency - stages to the same stats and feedback snapshots + stages to the same feedback snapshot