Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
d751b63
chore(quest): claim quest/m2/audio-playout/browser-audio-hole-skip.md
kixelated Nov 16, 2026
77fb537
fix(watch): audio keeps a hole a late burst fills within the stretch
kixelated Nov 17, 2026
263119c
fix(watch): count the output latency the ring renders ahead by in aud…
kixelated Nov 17, 2026
69a9968
fix(watch): apply the output latency to the signed clock position
kixelated Nov 17, 2026
9a91d6b
chore(quest): claim quest/m2/audio-playout/browser-audio-hole-skip.md
kixelated Nov 18, 2026
41719b7
Merge the claim commit; #8982 already landed this branch's earlier work
kixelated Nov 18, 2026
02eae7d
feat(net)!: an ordered track reports the groups it gives up on, as Ru…
kixelated Nov 18, 2026
3b38c9a
feat(watch,hang): browser audio takes its holes from the ordered reader
kixelated Nov 18, 2026
0f8006d
feat(net): a local track's ordered read reports a fill-owed group it …
kixelated Nov 18, 2026
032efc4
docs(audio-jitter): the browser leaves an audio hole to the ordered r…
kixelated Nov 18, 2026
0858680
test(audio-quality): re-measure the replays reading audio through the…
kixelated Nov 18, 2026
77064db
docs(quest): narrow browser-audio-hole-skip to grading the Chromium rows
kixelated Nov 18, 2026
08e280a
fix(net): an ordered read folds its record, and passes what it reports
kixelated Nov 18, 2026
e2cfd61
fix(net): a resumed reader's copies fold their records, and a gap com…
kixelated Nov 18, 2026
7d9b486
fix(net): an ordered read folds its record at where it is, with no ru…
kixelated Nov 18, 2026
0097b73
fix(net): an ordered read drops the gaps its bounds left out below it
kixelated Nov 18, 2026
f96f161
Merge remote-tracking branch 'origin/main' into quest/m2/audio-playou…
kixelated Nov 18, 2026
1fc4da3
feat(net): an ordered read's nextGroup yields groups, and nextItem it…
kixelated Nov 18, 2026
5cc07b3
docs(quest): ordered-gaps notes js/net already has nextItem
kixelated Nov 18, 2026
6f807af
fix(net,hang,watch): answer the review of the ordered reader
kixelated Nov 18, 2026
a235e50
fix(hang): keep the ordered loss rule, which the timeline check alrea…
kixelated Nov 18, 2026
ccaebbd
perf(net): an ordered read appends a gap past every one waiting
kixelated Nov 18, 2026
6a0531e
fix(net): a key passed under a stale verdict that binds another reade…
kixelated Nov 18, 2026
1cb7b69
fix(net,hang): apply Pullfrog's two suggestions
kixelated Nov 18, 2026
4d6d190
fix(hang): a gap the ordered reader puts on an empty group still mark…
kixelated Nov 18, 2026
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
21 changes: 13 additions & 8 deletions doc/concept/audio-jitter.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,12 +49,18 @@ group is observed when the stall clears. A missing group, one that has delivered
no frame, is waited for only the playout delay, the subscription's `delay.min`,
since past that it would play late: a reordered backlog's holes waited out to the whole budget
would delay the frames behind them, which the estimator would measure as
jitter. The browser player waits less still, only until the group past the hole
trails its clock by the stretch threshold, past which the ring would skip the
hole's audio anyway: a viewer resuming behind a replayed backlog, which arrives
newest first, would otherwise hold the live audio for the backlog's oldest group,
while a late burst that fills a hole a moment after the group past it lands
still plays it. A caller that estimates keeps the budget past the target, which is why
jitter. The browser player leaves the hole to the transport: it reads its audio
through an ordered track reader whose own `delay.max` is what the ring holds of
the delay plus the stretch threshold, past which the ring would skip the hole's
audio anyway, and plays each gap that reader reports as the hole. The reader
gives up on a missing group by the same two clocks as any stale group: once the
newest frame is that far past where the group after it starts, or that group
arrived that long ago. A late burst that fills a hole a moment after the group
past it lands still plays it, and a viewer resuming behind a replayed backlog
does not hold the live audio for the backlog's oldest group. That reader's
budget is its own: a second subscription to the same track, read in arrival
order, observes every frame its own wider budget receives, so the late groups
the reader gives up on are still measured. A caller that estimates keeps the budget past the target, which is why
`moq play` waits on a stalled audio group for the delay plus the estimate's 2 s
ceiling. The observation is also only as honest as
the caller is prompt: `read()` is timed when it resolves, so a player drains it
Expand All @@ -69,8 +75,7 @@ the target: the estimate creeps up one bucket at a time while the frames it
should have measured go unplayed. Both implementations subscribe with the delay
plus the estimate's own 2 s ceiling, whatever the player's `stretch` setting:
`moq play` through its age budget, and the browser through the audio
subscription alone, since its container consumer observes each frame before
applying the local budget. So any lateness the estimator can measure is
subscription it observes arrivals on, beside the narrower ordered one it plays. So any lateness the estimator can measure is
observed at once. A buffered browser player keeps its subscription at least the
delay plus its lookahead.
Browser video keeps the shared budget, because a longer one fetches whole stale
Expand Down
1 change: 1 addition & 0 deletions js/hang/api/container.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ export class Consumer {
export interface ConsumerProps {
delay?: Signals.GetterInit<Net.Track.Delay>;
format: Format;
ordered?: Net.Track.Ordered;
playhead?: Playhead;
predecessor?: Consumer;
warmup?: Net.Clock.Duration;
Expand Down
142 changes: 142 additions & 0 deletions js/hang/src/container/consumer.ordered.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
// A consumer reading an ordered reader: the reader decides every hole, and the arrival subscription
// only feeds the estimate.
import { expect, test } from "bun:test";
import { Duration } from "@moq/clock";
import { Manual } from "@moq/clock/test";
import { Time, Track } from "@moq/net";
import { Consumer, type Read } from "./consumer.ts";
import { encodeFrame, Format } from "./legacy.ts";

const flush = () => new Promise<void>((resolve) => setImmediate(resolve));

// An audio track whose missing groups an unserved fill owes, as a session's feed would, read by a
// consumer whose ordered reader waits `wait` for a hole and whose arrival subscription reaches 2 s.
function setup(wait: number) {
const clock = new Manual();
const installed = clock.install();
const track = new Track.Producer("audio");
const requests = track.requests();
const ordered = track.subscribe({ delay: { min: Duration.ZERO, max: Duration.millis(wait) } }).ordered();
const consumer = new Consumer(track.subscribe({ delay: { max: Duration.secs(2) } }), {
format: new Format("audio"),
delay: { min: Duration.ZERO, max: Duration.secs(2) },
ordered,
});
const reads: Read[] = [];
const reading = (async () => {
for (;;) {
const read = await consumer.next();
if (!read) return;
reads.push(read);
}
})();
// One finished group holding a 20 ms frame at `ms`.
const write = (sequence: bigint, ms: number) => {
const group = track.createGroup(sequence);
group.writeFrame({
payload: encodeFrame(new Uint8Array([1]), Duration.millis(ms)),
timestamp: Time.Timestamp.fromMillis(ms),
});
group.finish();
};
return {
clock,
track,
consumer,
reads,
write,
// What was read, as `frame 20` or `gap 20+20`, in ms.
read: () =>
reads.map((read) =>
read.kind === "gap"
? `gap ${read.timestamp.asMillis()}+${read.duration.asMillis()}`
: read.kind === "frame"
? `frame ${read.frame.timestamp.asMillis()}`
: `end ${read.end.asMillis()}`,
),
async close() {
consumer.close();
requests.close();
track.finish();
track.close();
try {
await reading;
} finally {
installed.close();
}
},
};
}

test("a hole is waited for as long as the ordered reader waits, then read as a gap", async () => {
const t = setup(100);
try {
t.write(0n, 0);
t.write(2n, 40);
await flush();
expect(t.read()).toEqual(["frame 0"]);
// The consumer keeps no wait of its own: the reader's budget alone holds the group past the hole.
await t.clock.advance(Duration.millis(99));
expect(t.read()).toEqual(["frame 0"]);
await t.clock.advance(Duration.millis(1));
await flush();
expect(t.read()).toEqual(["frame 0", "gap 0+40", "frame 40"]);
} finally {
await t.close();
}
});

test("a gap the reader reports before an empty group still reads as a gap before the next frame", async () => {
const t = setup(100);
try {
t.write(0n, 0);
// Group 2 holds nothing. The hole at 1 ages from group 2's arrival, while group 2 ages from
// group 3's later one, so the reader hands out the empty group 2 with the gap on it.
t.track.createGroup(2n).finish();
await t.clock.advance(Duration.millis(90));
t.write(3n, 60);
await t.clock.advance(Duration.millis(10));
await flush();
expect(t.read()).toEqual(["frame 0", "gap 0+60", "frame 60"]);
} finally {
await t.close();
}
});

test("a group that lands within the reader's wait fills its hole", async () => {
const t = setup(100);
try {
t.write(0n, 0);
t.write(2n, 40);
await t.clock.advance(Duration.millis(50));
t.write(1n, 20);
await flush();
expect(t.read()).toEqual(["frame 0", "frame 20", "frame 40"]);
} finally {
await t.close();
}
});

test("the estimate observes late groups the ordered reader gave up on", async () => {
// The spread after 5 s of groups 20 ms apart, every tenth landing `late` ms past its turn.
const spread = async (late: number) => {
const t = setup(50);
try {
const arrivals = Array.from({ length: 250 }, (_, i) => ({ i, at: i * 20 + (i % 10 === 5 ? late : 0) }));
arrivals.sort((a, b) => a.at - b.at);
let at = 0;
for (const arrival of arrivals) {
await t.clock.advance(Duration.millis(arrival.at - at));
at = arrival.at;
t.write(BigInt(arrival.i), arrival.i * 20);
}
await flush();
// The reader passed each late group long before it landed, so it plays as a gap.
if (late > 0) expect(t.read()).not.toContain("frame 100");
return t.consumer.spread.peek();
} finally {
await t.close();
}
};
expect((await spread(300)).gt(await spread(0))).toBe(true);
});
Loading