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/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
52 changes: 35 additions & 17 deletions quest/m2/latency-ledger.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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) - `<moq-watch>` 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
Expand Down
2 changes: 1 addition & 1 deletion quest/m2/stats/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading