Skip to content
Merged
70 changes: 70 additions & 0 deletions js/hang/src/container/consumer.holes.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -238,3 +238,73 @@ test("a hole in a drained backlog is late from the earliest arrival past it, not
installed.close();
}
});

// A pause's timestamp jump is not lateness: the group that resumes it can arrive behind the one after
// it, and is waited for like any hole rather than skipped as too old.
test.each([true, false])("the head after a declared end is waited for (arrives: %p)", async (arrives) => {
const clock = new Manual();
const installed = clock.install();
const track = new Track.Producer("audio");
const consumer = new Consumer(track.subscribe({ delay: { max: Milli(30_000) } }), {
format: new Format("audio"),
delay: { max: Milli(300) },
});
const results: Read[] = [];
const reading = (async () => {
for (;;) {
const read = await consumer.next();
if (!read) return;
results.push(read);
}
})();
const write = (sequence: bigint, ...frames: [number, Uint8Array?][]) => {
const group = track.createGroup(sequence);
for (const [timestamp, payload = new Uint8Array([1])] of frames) {
group.writeFrame({
payload: encodeFrame(payload, Micro(timestamp)),
timestamp: Time.Timestamp.fromMicros(Micro(timestamp)),
});
}
group.finish();
};
const frame = (group: bigint, timestamp: number) => ({
kind: "frame" as const,
group,
frame: expect.objectContaining({ timestamp }),
});
try {
write(0n, [0]);
// The end, then the stopped encoder's final packet, as a native publisher writes them.
write(1n, [60_000, new Uint8Array()], [40_000]);
await flush();
expect(results).toEqual([frame(0n, 0), { kind: "end", group: 1n, end: Micro(60_000) }, frame(1n, 40_000)]);
write(3n, [60_060_000]);
await flush();
await clock.advance(Nano.fromMilli(Milli(299)));
expect(results).toHaveLength(3);
if (arrives) {
write(2n, [60_000_000]);
await flush();
expect(results.slice(3)).toEqual([frame(2n, 60_000_000), frame(3n, 60_060_000)]);
// Resumed, a later hole past the budget is proven again without a wait.
write(5n, [61_000_000]);
await flush();
expect(results.slice(5)).toEqual([
{ kind: "gap", timestamp: Micro(60_060_000), duration: Micro(940_000) },
frame(5n, 61_000_000),
]);
} else {
await clock.advance(Nano.fromMilli(Milli(1)));
expect(results.slice(3)).toEqual([
{ kind: "gap", timestamp: Micro(60_000), duration: Micro(60_000_000) },
frame(3n, 60_060_000),
]);
}
} finally {
consumer.close();
track.finish();
track.close();
await reading;
installed.close();
}
});
10 changes: 9 additions & 1 deletion js/hang/src/container/consumer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,9 @@ export class Consumer {
// Group of the last media frame next() returned, so an endpoint after it reads as that frame's
// duration rather than a declared stop.
#mediaGroup?: bigint;
// The group of the last declared end read, until a frame from a later group resumes the timeline.
// Not at the next frame: the stopped encoder's final packets may follow the end in its group.
#paused?: bigint;
// Media went missing since the last item read, so the next one is preceded by a gap.
#lost = false;
// The furthest presentation point read so far: max(timestamp + duration), endpoints included.
Expand Down Expand Up @@ -826,6 +829,8 @@ export class Consumer {
// is proven: the head already reaches past where presentation left off by more than the
// max delay, so anything still missing in between would arrive too old to play. Proving it
// here matters: #checkMaxDelay would instead drop the head, the very group to play next.
// A declared end proves nothing: the jump past it is the pause, and the media that resumes
// it may still be in flight behind the group after it.
// After track termination no missing group can arrive, so drain across any remaining gap.
// A missing sequence also expires on elapsed monotonic time, so timestamp-free markers
// behind a hole can end a paused track without more arrivals. It is late since a group
Expand All @@ -843,7 +848,8 @@ export class Consumer {
const skipHole =
head.frames.length > 0 &&
(maxDelay === 0 ||
(this.#presentedEnd !== undefined &&
(this.#paused === undefined &&
this.#presentedEnd !== undefined &&
head.latest !== undefined &&
head.latest - this.#presentedEnd > maxDelay));
const elapsed = Instant.durationSince(now(), this.#hole) >= maxDelay * 1000;
Expand Down Expand Up @@ -1076,6 +1082,8 @@ export class Consumer {
const edge = this.#edge;
const lost = this.#lost;
this.#lost = false;
if (read.kind === "end") this.#paused = read.group;
else if (this.#paused !== undefined && read.group > this.#paused) this.#paused = undefined;
Comment thread
kixelated marked this conversation as resolved.
Resolved
this.#advance(read.kind === "frame" ? Micro(resume + (read.frame.duration ?? Micro.zero)) : resume);
if (!lost || edge === undefined) return read;

Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,6 @@ moves what remains of them once their claims merge.
- [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
- [Native WebSocketStream keeps datagrams flowing](/quest/m1/websocket-stream-datagrams.md) - on Chromium's native `WebSocketStream`, QMux over WebSocket sheds a datagram only on a real send backlog, proven in headless Chromium
- [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 loses no speech](/quest/m1/push-to-talk/README.md) - an unmute is heard from its first frame with no catalog round trip: mute moves from holding a disabled rendition to suppressed silence with comfort noise, after a route spike; capture delivers frames on a steady cadence
- [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
- [Socket endpoints split into servers and clients](/quest/m1/socket-roles.md) - servers announce `.server/<id>` and clients `.client/<id>`, so plain grants keep a client from posing as a server or reading another client
- [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide
Expand Down
14 changes: 8 additions & 6 deletions quest/m1/push-to-talk-latency.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,12 @@ ring held when that PCM landed. The run also keeps 60 ms / 128 kbit/s Opus,
the setup the nightly passes on. On the loaded agent host, 2026-11-06 runs at
the fixed 300 ms delay had no underrun or stall but lost heads ("utterance
head was not decoded"): 2 of 22 on the default 20 ms Opus and 1 on 60 ms.
Whether 20 ms frames hit that ordering defect, which
[Push-to-talk](/quest/m1/push-to-talk/README.md) owns, more often is not
settled. What remains is to switch the page to the defaults, measure on `kixtop` again,
and set and enforce the budget.
The group after a head could overtake it, and the read took the mute's
timestamp jump as proof the head was too late to wait for;
[moq-dev/moq#8123](https://github.com/moq-dev/moq/pull/8123) fixed it, and two
20 ms runs after the fix kept all 44 heads. What remains is to switch the
page to the defaults, measure on `kixtop` again, and set and enforce the
budget.

Measured 2026-11-05 on the defaults, before Watch, one run of 22 presses
each, Chromium 156 headless through a local relay. `kixtop` is a MacBook Air
Expand Down Expand Up @@ -81,8 +83,8 @@ Measurement limits: the harness's headless Chromium mutes its output and reads
a fake microphone, so `device` is Chromium's projected output for the default
device and `capture` excludes the microphone's own input latency. Linux's
render callbacks are 43 ms, so its `render` can be negative by up to one
callback. The lost heads are the ordering defect
[Push-to-talk](/quest/m1/push-to-talk/README.md) owns.
callback. The lost heads were the ordering defect
[moq-dev/moq#8123](https://github.com/moq-dev/moq/pull/8123) fixed.

Knobs: the target's frame term (`frameDuration`, 20 ms by default) and its
measured term (`js/watch/src/audio/latency.ts`); device and render follow the
Expand Down
99 changes: 0 additions & 99 deletions quest/m1/push-to-talk/README.md

This file was deleted.

45 changes: 45 additions & 0 deletions rs/moq-mux/src/container/consumer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2717,6 +2717,51 @@ mod tests {
assert_eq!(items(&mut consumer).await, ["0", "end 0", "1000000"]);
}

/// A pause's timestamp jump is not lateness: the group that resumes it can arrive behind the
/// one after it, and is waited for like any hole rather than skipped as too old.
#[tokio::test(start_paused = true)]
async fn the_head_after_a_declared_end_is_waited_for() {
let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.audio));
let mut consumer = Consumer::new(
track.subscribe(
moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_secs(30))),
),
Container::Legacy(crate::container::Kind::Audio),
);
consumer.max_delay = Duration::from_millis(300);
write_group(&mut track, 0, &[ts(0)]);
// The end, then the stopped encoder's final packet, as `moq_audio`'s producer writes them.
let mut group = track.create_group(moq_net::group::Info { sequence: 1 }).unwrap();
let frame = |timestamp, payload| Frame {
timestamp,
payload,
keyframe: true,
duration: None,
};
Container::Legacy(crate::container::Kind::Audio)
.write(
&mut group,
&[
frame(ts(60_000), Bytes::new()),
frame(ts(40_000), Bytes::from_static(b"x")),
],
)
.unwrap();
group.finish().unwrap();
assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0));
assert!(matches!(
consumer.read().await.unwrap(),
Some(Read::End { group: 1, .. })
));
assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(40_000));
write_group(&mut track, 3, &[ts(60_060_000)]);
tokio::time::advance(Duration::from_millis(299)).await;
assert!(consumer.poll_read(&kio::Waiter::noop()).is_pending());
write_group(&mut track, 2, &[ts(60_000_000)]);
track.finish().unwrap();
assert_eq!(items(&mut consumer).await, ["60000000", "60060000"]);
}

#[tokio::test]
async fn a_zero_budget_idle_resume_reports_the_shed_marker_as_a_gap() {
let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.audio));
Expand Down
Loading