Skip to content
Closed
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 demo/web/src/viz.ts
Original file line number Diff line number Diff line change
Expand Up @@ -307,7 +307,7 @@ export function bufferBars(parent: Signals.Effect, watch: MoqWatch): HTMLElement
const timestamp = watch.sync.now() as number | undefined;
const stalled = watch.video.out.stalled.peek();
drawRanges(video.canvas, watch.video.out.buffered.peek(), timestamp, stalled);
drawRanges(audio.canvas, watch.audio.out.buffered.peek(), timestamp, false);
drawRanges(audio.canvas, watch.audio.out.buffered.peek(), timestamp, watch.audio.out.stalled.peek());
parent.animate(draw);
};
parent.animate(draw);
Expand Down
4 changes: 2 additions & 2 deletions doc/lib/js/watch.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,10 @@ in sync at the latency you ask for.
| --- | --- |
| `url`, `name` | Relay URL (with `?jwt=` if needed) and broadcast name. |
| `paused`, `muted`, `volume` | The usual player controls, mirrored as reactive properties. |
| `delay` | How far playback trails the live edge: `"auto"` (derived from RTT, the default), a duration like `"300ms"`, or `"instant"` to paint frames as they decode with no pacing at all. |
| `delay` | How far playback trails the live edge: `"auto"` (the default, sized from how late frames actually arrive), a duration like `"300ms"`, or `"instant"` to paint frames as they decode with no pacing at all. |
| `buffer` | Future-dated media held beyond the live edge before playback skips ahead, e.g. `"30s"`. Defaults to none. |
| `captions` | The caption track to show, or absent for off. `el.text.out.available` lists the renditions for a picker. |
| `jitter` | The jitter buffer in ms. |
| `jitter` | The jitter buffer in ms: in `"auto"` this is the measured arrival spread, read-only in practice. |
| `visible` | Only subscribe to video while the element is on screen: a margin (`"20%"` default, `"200px"`), `"always"`, or `"never"`. |
| `reload` | Wait for the broadcast to be announced before subscribing (default on), so a player can be mounted before the stream exists. |
| `catalog-format` | `hang` (default, from the `.hang` suffix), `hangz` (compressed), `msf`, or `manual` to supply the catalog yourself. |
Expand Down
18 changes: 18 additions & 0 deletions js/hang/src/container/consumer.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,24 @@ test("Consumer skips groups via PTS-span when over the max age", async () => {
consumer.close();
});

test("Consumer measures how late frames arrive", async () => {
const track = new Track.Producer("test");
const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), maxAge: 500 as Time.Milli });

// A prompt first group sets the arrival baseline.
writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]);
await settle(150);

// The next group carries 20ms of media but shows up 150ms later, so a player needs the
// difference in its buffer to render it on time. Nothing about the round trip says that.
writeGroupWithLegacyFrames(track, 1, [20_000 as Time.Micro]);
track.close();

await drainFrames(consumer, 300);
expect(consumer.spread.peek()).toBeGreaterThanOrEqual(50 as Time.Milli);
consumer.close();
});

// --- Ordering ---

test("Consumer delivers groups in sequence order regardless of arrival order", async () => {
Expand Down
25 changes: 25 additions & 0 deletions js/hang/src/container/consumer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import * as Moq from "@moq/net";
import { Effect, type Getter, type GetterInit, getter, Signal } from "@moq/signals";

import type { Format } from "./format";
import { Jitter } from "./jitter";
import type { BufferedRanges, Frame } from "./types";

/** Options for constructing a {@link Consumer}. */
Expand Down Expand Up @@ -143,6 +144,18 @@ export class Consumer {
/** The time ranges currently buffered and ready to play. */
readonly buffered: Getter<BufferedRanges> = this.#buffered;

// Measured at arrival, before any group is skipped: a target derived from what survives the
// age budget would only ever confirm the budget it was cut to.
#spread = new Jitter();

/**
* How late frames arrive relative to the earliest one, measured as they land.
*
* Size the playback buffer with this rather than with the round trip, which says nothing about
* how evenly a publisher emits frames.
*/
readonly spread: Getter<Time.Milli> = this.#spread.value;

#signals = new Effect();

/** Start consuming the given track, decoding frames with `props.format`. */
Expand Down Expand Up @@ -256,11 +269,21 @@ export class Consumer {
// max age budget is what eventually breaks the stall.
if (this.#classifyStale(group)) return;
this.#checkReset(group);

// Measured once the timeline is settled and before the age budget can skip
// the group: a reneged straggler is already gone, a rewinding group is read
// against the baseline `#checkReset` just re-anchored rather than against
// the epoch it replaced, and a target derived from what survives the budget
// would only ever confirm the budget it was cut to.
if (!marker) this.#spread.observe(frame.timestamp, Moq.Time.Milli.now());
this.#checkMaxAge();

// A newer group reaching back to where the stalled active group has
// already presented means we can advance now instead of waiting.
skipped = this.#tryDurationSkip();
} else if (!marker) {
// The active group needs no classification, so its arrival counts as is.
this.#spread.observe(frame.timestamp, Moq.Time.Milli.now());
}

// Wake next() for the current delivery head so its frames surface as they
Expand Down Expand Up @@ -438,6 +461,7 @@ export class Consumer {
this.#rewind.boundary = reset;
this.#rewind.discontinuity++;
this.#gap = true;
this.#spread.reanchor();

// Drop buffered groups the boundary can already prove stale; keep ambiguous ones.
this.#groups = this.#groups.filter((g) => {
Expand Down Expand Up @@ -661,6 +685,7 @@ export class Consumer {
this.#presentedEnd = undefined;
this.#deliveredGroup = undefined;
this.#gap = true;
this.#spread.reanchor();
}

#updateBuffered(): void {
Expand Down
125 changes: 125 additions & 0 deletions js/hang/src/container/jitter.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
import { describe, expect, it } from "bun:test";
import { Time } from "@moq/net";
import { Jitter } from "./jitter";

const CHUNK_MS = 20;

/** Feed one arrival, in milliseconds on both axes. */
function observe(jitter: Jitter, media: number, arrival: number): void {
jitter.observe(Time.Micro.fromMilli(media as Time.Milli), arrival as Time.Milli);
}

/**
* A sender emitting one chunk every `CHUNK_MS`, holding `burst - 1` of them back and flushing the
* whole run at once. `burst` of 1 is an evenly paced sender.
*/
function flush(jitter: Jitter, chunks: number, burst: number, base = 50): void {
let held: number[] = [];
for (let i = 0; i < chunks; i++) {
const media = i * CHUNK_MS;
held.push(media);
if (held.length < burst) continue;
const arrival = media + base;
for (const m of held) observe(jitter, m, arrival);
held = [];
}
}

describe("arrival jitter", () => {
it("is one frame for an evenly paced sender", () => {
// Nothing arrives late, so all the buffer needs to hold is the frame being played.
const jitter = new Jitter();
flush(jitter, 500, 1);
expect(jitter.value.peek()).toBe(CHUNK_MS as Time.Milli);
});

it("does not follow the absolute delay", () => {
// A sender on the other side of the planet is not a jittery sender: only the spread of
// arrivals matters, which is what makes the round trip the wrong term to size a buffer from.
const near = new Jitter();
flush(near, 500, 1, 10);
const far = new Jitter();
flush(far, 500, 1, 2000);
expect(far.value.peek()).toBe(near.value.peek());
});

it("converges on the flush span of a bursty sender", () => {
// Three chunks land at once, so the oldest is two chunk durations late.
const jitter = new Jitter();
flush(jitter, 600, 3);
expect(jitter.value.peek()).toBeGreaterThanOrEqual(3 * CHUNK_MS);
expect(jitter.value.peek()).toBeLessThanOrEqual(4 * CHUNK_MS);
});

it("rises as soon as one arrival proves the buffer is too shallow", () => {
const jitter = new Jitter();
flush(jitter, 100, 1);
expect(jitter.value.peek()).toBe(CHUNK_MS as Time.Milli);

// A single 250ms straggler is only 1% of the samples, so the percentile ignores it. It costs
// one bucket of histogram resolution, not a quarter second of buffer.
observe(jitter, 100 * CHUNK_MS, 100 * CHUNK_MS + 250);
expect(jitter.value.peek()).toBeLessThan(2 * CHUNK_MS);

// A run of them is the network, not an outlier, and the estimate follows within a second.
for (let i = 0; i < 20; i++) {
observe(jitter, (101 + i) * CHUNK_MS, (101 + i) * CHUNK_MS + 250);
}
expect(jitter.value.peek()).toBeGreaterThan(150 as Time.Milli);
});

it("lowers by at most one chunk per interval", () => {
const jitter = new Jitter();
flush(jitter, 600, 3);
const peak = jitter.value.peek();
expect(peak).toBeGreaterThan(0 as Time.Milli);

// Arrivals settle. Sample the estimate every second of the recovery: a step larger than one
// chunk would drop a viewer's playhead onto a cushion that isn't there yet.
let previous = peak;
let last = 0;
const base = 600 * CHUNK_MS;
for (let i = 0; i < 6000; i++) {
const media = base + i * CHUNK_MS;
observe(jitter, media, media + 50);
const now = media + 50;
if (now - last < 1000) continue;
last = now;
const current = jitter.value.peek();
expect(previous - current).toBeLessThanOrEqual(CHUNK_MS);
previous = current;
}

// And it does come back down to a frame plus the histogram's resolution once arrivals have
// been even for a while.
expect(jitter.value.peek()).toBeLessThan(2 * CHUNK_MS);
});

it("expires the baseline after a long gap", () => {
const jitter = new Jitter();
flush(jitter, 200, 1);

// Nothing arrives for over a minute, and the path delay is higher when the stream resumes.
// Frames still land evenly, so they are punctual, not late: a minimum from before the gap
// would read the whole difference as jitter.
const base = 200 * CHUNK_MS + 90_000;
for (let i = 0; i < 200; i++) {
observe(jitter, base + i * CHUNK_MS, base + i * CHUNK_MS + 400);
}
expect(jitter.value.peek()).toBe(CHUNK_MS as Time.Milli);
});

it("forgets the baseline across a discontinuity", () => {
const jitter = new Jitter();
flush(jitter, 200, 1);

// The publisher restarts its timeline an hour in the past. Without a re-anchor every arrival
// after it reads as an hour late and the estimate saturates.
jitter.reanchor();
const base = 3_600_000;
for (let i = 0; i < 200; i++) {
observe(jitter, base + i * CHUNK_MS, i * CHUNK_MS + 50);
}
expect(jitter.value.peek()).toBe(CHUNK_MS as Time.Milli);
});
});
Loading