diff --git a/demo/web/src/index.ts b/demo/web/src/index.ts index be940e31546..a4b045b1c3d 100644 --- a/demo/web/src/index.ts +++ b/demo/web/src/index.ts @@ -119,9 +119,9 @@ function createTile(name: string): WatchTile { const watch = document.createElement("moq-watch") as MoqWatch; watch.name = name; watch.muted = true; // unmuted only while active (see below) - // Default to a fixed 100ms jitter buffer (instead of adaptive "real-time") so - // the latency visualization has something to show. Drag it in the panel. - watch.setAttribute("latency", "100"); + // Default to a fixed 100ms jitter buffer (instead of adaptive "auto") so + // the delay visualization has something to show. Drag it in the panel. + watch.setAttribute("delay", "100ms"); const canvas = document.createElement("canvas"); canvas.style.cssText = "width: 100%; height: auto;"; watch.appendChild(canvas); diff --git a/demo/web/src/viz.ts b/demo/web/src/viz.ts index f181cd7d8c0..abe1a5a4969 100644 --- a/demo/web/src/viz.ts +++ b/demo/web/src/viz.ts @@ -6,7 +6,7 @@ * * - `graph()` is a rolling sparkline (used for bitrate / frame rate). * - `bufferBars()` is an editable view of the video/audio jitter buffer; drag it - * to change the latency target. + * to change the delay. */ import type { BufferedRanges, Signals } from "@moq/watch"; @@ -198,11 +198,11 @@ function drawRanges( } } -const STEP = 10; // latency drag/keyboard granularity, in milliseconds +const STEP = 10; // delay drag/keyboard granularity, in milliseconds /** - * Editable latency visualization: video + audio jitter buffers drawn as bars - * from the playhead (left edge) out to ~4s, with the current latency target + * Editable delay visualization: video + audio jitter buffers drawn as bars + * from the playhead (left edge) out to ~4s, with the current delay * marked. Drag (or focus + arrow keys) to set the buffer, like ``. * Each call binds to one `watch`; close the parent effect to stop it. */ @@ -213,7 +213,7 @@ export function bufferBars(parent: Signals.Effect, watch: MoqWatch): HTMLElement viz.style.cssText = "position: relative; cursor: ew-resize;"; viz.tabIndex = 0; viz.setAttribute("role", "slider"); - viz.setAttribute("aria-label", "Latency target"); + viz.setAttribute("aria-label", "Playback delay"); viz.setAttribute("aria-valuemin", "0"); viz.setAttribute("aria-valuemax", String(BUFFER_MAX)); @@ -252,14 +252,14 @@ export function bufferBars(parent: Signals.Effect, watch: MoqWatch): HTMLElement const legend = document.createElement("div"); legend.className = "mt-2 text-[10px] text-neutral-500"; - legend.textContent = "buffered ahead of the playhead; drag to change the latency target"; + legend.textContent = "buffered ahead of the playhead; drag to change the delay"; root.append(viz, legend); - // Set the latency floor, leaving the ceiling. Cast bypasses the branded ms type. - const setLatency = (ms: number) => { + // Set the playback delay. Cast bypasses the branded ms type. + const setDelay = (ms: number) => { const clamped = Math.max(0, Math.min(BUFFER_MAX, ms)); - watch.latencyMin = clamped as unknown as typeof watch.latencyMin; + watch.delay = clamped as unknown as typeof watch.delay; }; const setFromX = (clientX: number) => { @@ -267,7 +267,7 @@ export function bufferBars(parent: Signals.Effect, watch: MoqWatch): HTMLElement if (rect.width <= 0) return; const x = Math.max(0, Math.min(clientX - rect.left, rect.width)); const ms = (x / rect.width) * BUFFER_MAX; - setLatency(Math.round(ms / STEP) * STEP); + setDelay(Math.round(ms / STEP) * STEP); }; let dragging = false; @@ -290,7 +290,7 @@ export function bufferBars(parent: Signals.Effect, watch: MoqWatch): HTMLElement : 0; if (delta === 0) return; e.preventDefault(); - setLatency((watch.sync.out.jitter.peek() as unknown as number) + delta); + setDelay((watch.sync.out.jitter.peek() as unknown as number) + delta); }); // Position the target line from the live jitter (actual measured buffer in ms). diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 4f76e89ccb6..40876154ac0 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -215,12 +215,14 @@ it reads without being able to publish it, since that is what an RTMP or SRT ingest produces. A rendition whose config declares HE-AAC fails when it opens, either spelling of it; one that carries SBR without declaring it plays as its AAC-LC core. -`--latency-max` controls how far a stalled media group may lag before it is -skipped and defaults to `500ms`. These flags all follow the `play` verb: +`--max-age` controls how stale a media group may get before it is skipped and +defaults to `500ms`. It is a staleness budget, not a playout delay: raising it +never holds the picture back, it only waits longer on a late group before giving +up. These flags all follow the `play` verb: ```bash moq --connect https://relay.example.com/anon --broadcast conference.hang \ - play --video-name hd --audio-name en --latency-max 250ms + play --video-name hd --audio-name en --max-age 250ms ``` Video decoding prefers the platform hardware backend and falls back to the @@ -618,7 +620,7 @@ Import formats: - `flv` - FLV / RTMP (H.264 video, AAC audio) - `capture` - capture local devices directly (camera H.264 + microphone Opus; requires the `capture` build feature; does not read stdin) -`import --latency-max ` (default `30s`) declares how long relays keep a +`import --max-age ` (default `30s`) declares how long relays keep a non-latest group of the published media tracks fetchable. It is a retention budget, so raising it never makes a subscriber play further behind live: it caps how far back a fetch can still reach. The default is sized for a segmented @@ -626,7 +628,7 @@ egress (HLS/DASH), which may only advertise segments that are still fetchable; lower it when nothing reads history and the memory matters: ```bash -moq --connect https://relay.example.com --broadcast my-stream.hang import --latency-max 5s ts +moq --connect https://relay.example.com --broadcast my-stream.hang import --max-age 5s ts ``` It sits on `import` itself rather than the endpoint, so it applies to every @@ -672,13 +674,13 @@ for raw elementary streams instead of combining those sinks with a contradictory Every export sink caps how long a stalled group is waited on before the muxer skips to a newer one. Each owns the knob so its default fits the transport: the -stdout containers and `rtmp` take `--latency-max` (default `500ms`), and `srt` +stdout containers and `rtmp` take `--max-age` (default `500ms`), and `srt` reuses its `--latency` (the receive buffer doubles as the skip threshold). WebRTC (`rtc`) is real-time and doesn't buffer, so it has no such knob. HLS export doesn't subscribe to media at all (segments are fetched on demand), so it has no latency knob either. This is the subscriber half of the pair the protocol names: the export knob is how long *this* consumer waits, while -[`import --latency-max`](#container-formats) is how long the publisher keeps a +[`import --max-age`](#container-formats) is how long the publisher keeps a group around for anyone to fetch. ### MPEG-TS @@ -695,7 +697,7 @@ moq --connect https://relay.example.com --broadcast my-stream.hang export ts | f ``` TS export is paced: bytes leave stdout at the instant the stream's clock (PCR) -asserts, smoothed within the `--latency-max` budget, so the pipe carries a +asserts, smoothed within the `--max-age` budget, so the pipe carries a real-time transport stream rather than draining as fast as frames arrive. TS export carries H.264 / H.265 as Annex-B and AAC as ADTS. Both in-band diff --git a/doc/lib/js/@moq/watch.md b/doc/lib/js/@moq/watch.md index 22f258fa2fb..0e1542de7a0 100644 --- a/doc/lib/js/@moq/watch.md +++ b/doc/lib/js/@moq/watch.md @@ -71,11 +71,14 @@ a real bundler (the examples below). - `muted`: Mute audio (boolean) - `volume`: Audio volume (0 to 1, default: 1) - `reload`: Wait for (re)announcement before subscribing (default: true). Ignored when the relay does not support broadcast discovery, which subscribes immediately instead of waiting forever. -- `latency`: Latency target. `"real-time"` (default) derives it from RTT, or a number sets a fixed jitter buffer in ms. Collapses `latency-min` and `latency-max` to one value (minimize latency). `"instant"` stops pacing off the clock, see [instant playback](#instant-playback). -- `latency-min`: Latency floor (the jitter/startup buffer). Same units as `latency`; leaves the ceiling untouched. -- `latency-max`: Latency ceiling. `"real-time"` (default) minimizes latency; a number caps at that many ms. A ceiling above the floor enables [buffered playback](#buffered-playback): build up a buffer from future-dated frames instead of skipping ahead. +- `delay`: How far playback trails the live edge, the jitter/startup buffer. `"auto"` (default) sizes it from the connection RTT, or a duration like `"100ms"` fixes it. `"instant"` stops pacing off the clock, see [instant playback](#instant-playback). +- `buffer`: Future-dated media held beyond the live edge before playback skips ahead, e.g. `"30s"`. Defaults to none, which minimizes latency. Anything above zero enables [buffered playback](#buffered-playback): build up a buffer from future-dated frames instead of skipping ahead. - `catalog-format`: Catalog format. One of `"hang"`, `"hangz"` (the [DEFLATE-compressed](/concept/layer/hang#compression) `catalog.json.z` track), `"msf"` (see [MSF](/concept/standard/msf)), or `"manual"` (supply the catalog yourself). When omitted, the format is auto-detected from the broadcast `name` extension (`.hang` or `.msf`), falling back to `"hang"`. `"hangz"` is opt-in only and never auto-detected (it shares the `.hang` suffix). +Durations (`delay`, `buffer`) carry a unit, either `ms` or `s`. A bare number is +rejected rather than guessed at, since most players measure these in seconds while +the matching DOM properties are in milliseconds; only `"0"` is accepted unitless. + ## Catalog Formats `@moq/watch` can consume either the default [hang](/concept/layer/hang) catalog @@ -148,55 +151,47 @@ el.catalog = myCatalog; ## Buffered playback -Latency is a **range**, `[latency-min, latency-max]`. By default the range is -collapsed (`latency` sets both to one value) and `@moq/watch` minimizes latency: -it anchors playback to the earliest frame seen relative to its timestamp and skips -ahead whenever the buffer grows past the target. That is right for live -conferencing, but wrong for content written *faster than real-time* with -timestamps in the future, such as a text-to-speech response streamed all at once. +`delay` and `buffer` sit on opposite sides of the live edge. `delay` is how far the +playhead trails it, absorbing jitter. `buffer` is how much future-dated media is +held beyond it before playback skips forward. + +By default `buffer` is zero and `@moq/watch` minimizes latency: it anchors playback +to the earliest frame seen relative to its timestamp and skips ahead whenever the +buffer grows past the target. That is right for live conferencing, but wrong for +content written *faster than real-time* with timestamps in the future, such as a +text-to-speech response streamed all at once. -Open the range, by setting a `latency-max` above the floor, to anchor playback to -the first frame received and play through at the encoded pace. The buffer is -allowed to float anywhere between the floor and the ceiling without skipping: +Set a `buffer` to anchor playback to the first frame received and play through at +the encoded pace. Media is then allowed to float anywhere up to `delay + buffer` +ahead of the playhead without skipping: ```html + delay="100ms" buffer="30s"> ``` -In JavaScript, `latency` takes either a scalar (collapsed, minimize) or a range -object. The `latencyMin` / `latencyMax` properties are read-modify-write sugar -over the same `latency` value: +In JavaScript the two are independent properties, both in milliseconds: ```typescript const el = document.querySelector("moq-watch")!; -el.latency = { min: 100, max: 30_000 }; // floor 100ms, ceiling 30s -// equivalently, set the bounds independently: -el.latencyMin = 100; // floor: start after 100ms buffered -el.latencyMax = 30_000; // ceiling: never skip until 30s buffered +el.delay = 100; // trail the live edge by 100ms +el.buffer = 30_000; // hold up to 30s of future-dated media ``` -`latency-min` is the jitter/startup buffer (it can also be `"real-time"` for an -adaptive floor). `latency-max` is the ceiling, and it has two forms: - -- a **number** (ms): buffer freely up to the cap, then skip ahead, so latency - stays at most that far behind the newest frame. -- **`"real-time"`** (the default) or any value `<= latency-min`: collapsed, i.e. - today's minimize-latency behavior. +`delay` also takes `"auto"` for a jitter buffer that tracks the connection RTT, which +is the default. -The ceiling is always finite: the buffer is bounded by `latency-max` rather than -growing without limit. The mechanism is the same in every case: the playhead is -anchored on the first frame and only re-anchored (skipped forward) when keeping it -would push latency past `latency-max`. Minimize is just the degenerate case where -the ceiling equals the floor. +The buffer is always finite, so it can't grow without limit. The mechanism is the +same in every case: the playhead is anchored on the first frame and only re-anchored +(skipped forward) when keeping it would leave a frame more than `delay + buffer` +ahead. Minimize is just the degenerate case where `buffer` is zero. -The buffered lookahead is held cheaply. The decoded audio ring only holds the -**floor** (`latency-min`) worth of PCM; everything above it stays upstream as -encoded frames, and the decoder applies backpressure (stops decoding ahead) until -the playhead nears each frame. So a large `latency-max` costs encoded bytes, not -seconds of decoded PCM. +The buffered lookahead is held cheaply. The decoded audio ring only holds `delay` +worth of PCM; everything above it stays upstream as encoded frames, and the decoder +applies backpressure (stops decoding ahead) until the playhead nears each frame. So +a large `buffer` costs encoded bytes, not seconds of decoded PCM. At each new utterance, call `reset()` to flush the audio buffer and re-anchor playback to the next frame. The producer can interrupt by writing a new utterance @@ -248,42 +243,41 @@ The component exposes everything via its `broadcast` property ## Instant playback -`latency-min="0"` still de-jitters: playback is anchored to the first frame, so a +`delay="0"` still de-jitters: playback is anchored to the first frame, so a frame that arrives early waits until its timestamp comes up. That's what keeps motion smooth, and it costs at least a frame interval. -`latency="instant"` empties the buffer and stops pacing off the clock, rather than +`delay="instant"` empties the buffer and stops pacing off the clock, rather than just shrinking the buffer. Frames paint the moment they decode, so latency drops to whatever the display costs (about half a refresh interval on average) and the canvas shows the newest frame at every repaint: ```html - + ``` -It is a value of `latency`, not a bound, so `latency-min="instant"` is rejected: -there is no range to sit inside. Assigning `latency-min` or `latency-max` writes a -range and therefore leaves the mode. +It is a value of `delay`, and it overrides `buffer`: holding a lookahead would +contradict holding nothing. Assigning a duration to `delay` leaves the mode. The tradeoff is motion: frames are presented at network cadence rather than at their timestamps, so delivery jitter shows up as judder. Reach for it when a fresh picture matters more than a smooth one, such as remote control or a camera -viewfinder, and prefer `latency` otherwise. +viewfinder, and prefer a paced `delay` otherwise. This disables audio. The audio ring needs a target depth to avoid underrunning, and unsynced video has nothing pulling it back toward the audio clock, so the two would drift apart. -Note that `latency-min="0"` is not the same thing, and neither half of this is +Note that `delay="0"` is not the same thing, and neither half of this is redundant. A zero floor still holds the selected rendition's own delay, a frame interval at 60fps, and it still sleeps, because the wait comes from the playback anchor rather than the buffer. `"instant"` drops both. The clock itself keeps running: video still reports every frame it receives and still resets it on a rewind. That keeps anything else reading the clock working, and -it means switching back to a paced latency resumes from a current reference instead +it means switching back to a paced delay resumes from a current reference instead of a stale one. Captions are one such reader, so they keep working. With nothing buffered they track diff --git a/js/hang/src/container/consumer.nonsequential.test.ts b/js/hang/src/container/consumer.nonsequential.test.ts index 37f396e4545..27511644474 100644 --- a/js/hang/src/container/consumer.nonsequential.test.ts +++ b/js/hang/src/container/consumer.nonsequential.test.ts @@ -18,7 +18,7 @@ test("Consumer waits on a non-sequential hang group because it has no per-frame // presentation end is unknown until the next group arrives. With non-sequential group ids we // therefore cannot prove the timeline is unbroken across a jump: a large id gap is // indistinguishable from a real missing segment that may still be in transit. So the consumer - // waits (and lets #checkLatency / #tryDurationSkip decide once the latency budget or duration + // waits (and lets #checkMaxAge / #tryDurationSkip decide once the max age budget or duration // coverage proves the gap too old) rather than eagerly skipping ahead, which would drop an // in-transit group and wreck audio. // @@ -26,7 +26,7 @@ test("Consumer waits on a non-sequential hang group because it has no per-frame // as a trailing frame carrying the group's end timestamp. Until the container carries that, expect // the wait. The CMAF path (per-sample duration in the moof) is covered in consumer.test.ts. const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 5000 as Time.Milli }); + const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), maxAge: 5000 as Time.Milli }); // Group A at a large sequence, completed so the cursor advances past it. const a = new Group.Producer(1_000_000); @@ -55,7 +55,7 @@ test("Consumer waits on a non-sequential hang group because it has no per-frame timestamp: Time.Timestamp.now(), }); - // Within the latency budget (5s), the parked next() stays parked: no duration means no proof of + // Within the max age budget (5s), the parked next() stays parked: no duration means no proof of // contiguity, so the consumer waits instead of eagerly delivering across the gap. const result = await Promise.race([ pending, diff --git a/js/hang/src/container/consumer.outoforder.test.ts b/js/hang/src/container/consumer.outoforder.test.ts index 03b5b869270..a26e868a7be 100644 --- a/js/hang/src/container/consumer.outoforder.test.ts +++ b/js/hang/src/container/consumer.outoforder.test.ts @@ -50,7 +50,7 @@ test("out-of-order groups are delivered rather than dropped", async () => { const track = new Track.Producer("test").accept({ maxAge: 30_000 }); const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), { format: new LegacyFormat(), - latency: 5000 as Time.Milli, + maxAge: 5000 as Time.Milli, }); // The live edge lands first, and delivery starts there rather than waiting. @@ -80,7 +80,7 @@ test("a below-cursor group still downloading is not truncated", async () => { const track = new Track.Producer("test").accept({ maxAge: 30_000 }); const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), { format: new LegacyFormat(), - latency: 5000 as Time.Milli, + maxAge: 5000 as Time.Milli, }); // The live edge group arrives first and starts delivery (still open). diff --git a/js/hang/src/container/consumer.test.ts b/js/hang/src/container/consumer.test.ts index 64889cd51a7..2da4b48da6c 100644 --- a/js/hang/src/container/consumer.test.ts +++ b/js/hang/src/container/consumer.test.ts @@ -36,7 +36,7 @@ function settle(ms = 20): Promise { } // Keep transport drift filtering out of container-consumer tests. These cases -// exercise the consumer's own latency policy against a complete retained track. +// exercise the consumer's own max age policy against a complete retained track. // These tests write every group up front and only then read, so they ask for history // rather than the live edge. function replay(track: Track.Producer): Track.Subscriber { @@ -191,7 +191,7 @@ async function drainFrames( test("Consumer delivers frames from a single group", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); track.close(); @@ -205,7 +205,7 @@ test("Consumer delivers frames from a single group", async () => { test("Consumer forces keyframe true at index 0", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); track.close(); @@ -229,7 +229,7 @@ test("Consumer index spans MoQ frames for keyframe detection", async () => { }; const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: multiFormat, latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: multiFormat, maxAge: 500 as Time.Milli }); const group = new Group.Producer(0); group.writeFrame({ payload: new Uint8Array([0x01]), timestamp: Time.Timestamp.now() }); // first MoQ frame → 3 samples @@ -257,7 +257,7 @@ test("Consumer keeps frames decoded before an error (truncated GoP)", async () = }; const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: truncatingFormat, latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: truncatingFormat, maxAge: 500 as Time.Milli }); // Group.Producer 0: 2 valid frames then a tail-truncating error. const g0 = new Group.Producer(0); @@ -284,7 +284,7 @@ test("Consumer keeps frames decoded before an error (truncated GoP)", async () = test("Consumer close returns undefined from next()", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); const promise = consumer.next(); consumer.close(); @@ -295,7 +295,7 @@ test("Consumer close returns undefined from next()", async () => { test("Consumer throws on concurrent next() calls", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); // First call blocks waiting for data void consumer.next(); @@ -305,19 +305,19 @@ test("Consumer throws on concurrent next() calls", async () => { consumer.close(); }); -test("Consumer skips groups via PTS-span when over latency", async () => { +test("Consumer skips groups via PTS-span when over the max age", async () => { const track = new Track.Producer("test"); - // Zero latency = skip everything that's not the latest - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 0 as Time.Milli }); + // Zero max age = skip everything that's not the latest + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 0 as Time.Milli }); - // Write groups with increasing timestamps. With 0 latency, any PTS span > 0 triggers skip. + // Write groups with increasing timestamps. With a 0 max age, any PTS span > 0 triggers skip. writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]); writeGroupWithLegacyFrames(track, 1, [100_000 as Time.Micro]); writeGroupWithLegacyFrames(track, 2, [200_000 as Time.Micro]); track.close(); const frames = await drainFrames(consumer, 300); - // With zero latency, the consumer should skip to the latest group + // With a zero max age, the consumer should skip to the latest group const groups = [...new Set(frames.map((f) => f.group))]; expect(groups.at(-1)).toBe(2); consumer.close(); @@ -327,7 +327,7 @@ test("Consumer skips groups via PTS-span when over latency", async () => { test("Consumer delivers groups in sequence order regardless of arrival order", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 2, [60_000 as Time.Micro]); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]); @@ -346,7 +346,7 @@ test("Consumer delivers groups in sequence order regardless of arrival order", a test("Consumer delivers a group that arrives below the cursor", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); // Group.Producer 5 arrives first (sets active = 5) writeGroupWithLegacyFrames(track, 5, [0 as Time.Micro]); @@ -371,7 +371,7 @@ test("Consumer delivers a group that arrives below the cursor", async () => { test("Consumer next() returns group-done signals", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); writeGroupWithLegacyFrames(track, 1, [66_000 as Time.Micro]); @@ -400,7 +400,7 @@ test("Consumer next() returns group-done signals", async () => { test("Consumer returns legacy endpoint markers as ordered metadata", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); const group = new Group.Producer(0); group.writeFrame({ @@ -428,7 +428,7 @@ test("Consumer returns legacy endpoint markers as ordered metadata", async () => test("Consumer delivers a rewound endpoint before its terminal packet", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); const previous = new Group.Producer(0); previous.writeFrame({ @@ -475,7 +475,7 @@ test("Consumer delivers a rewound endpoint before its terminal packet", async () test("Consumer buffered signal updates as frames arrive", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 500 as Time.Milli }); expect(consumer.buffered.peek()).toEqual([]); @@ -497,7 +497,7 @@ test("Consumer buffered signal updates as frames arrive", async () => { test("Consumer recovers from gap in group sequence numbers", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 100 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 100 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 20_000 as Time.Micro]); writeGroupWithLegacyFrames(track, 1, [40_000 as Time.Micro, 60_000 as Time.Micro]); @@ -527,7 +527,7 @@ test("Consumer handles empty decode result without deadlock", async () => { }; const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: emptyThenValid, latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: emptyThenValid, maxAge: 500 as Time.Milli }); const group = new Group.Producer(0); group.writeFrame({ payload: new Uint8Array([0x01]), timestamp: Time.Timestamp.now() }); // empty decode @@ -553,7 +553,7 @@ test("Consumer preserves empty media from formats without endpoint markers", asy }, }; const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format, latency: 500 as Time.Milli }); + const consumer = new Consumer(track.subscribe(), { format, maxAge: 500 as Time.Milli }); const group = new Group.Producer(0); group.writeFrame({ payload: new Uint8Array([1]), timestamp: Time.Timestamp.now() }); group.close(); @@ -572,7 +572,7 @@ test("Consumer with CmafFormat delivers correct timestamps", async () => { const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), - latency: 500 as Time.Milli, + maxAge: 500 as Time.Milli, }); const group = new Group.Producer(0); @@ -643,7 +643,7 @@ const durationFormat: ContainerFormat = { test("Consumer duration-skips a stalled group once it is covered", async () => { const track = new Track.Producer("test"); // Latency dwarfs the gap, so only duration coverage can trigger the skip. - const consumer = new Consumer(replay(track), { format: durationFormat, latency: 10_000 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: durationFormat, maxAge: 10_000 as Time.Milli }); // Group.Producer 0: one frame at ts=0 lasting 33ms, never closed (stalled). const g0 = new Group.Producer(0); @@ -680,7 +680,7 @@ test("Consumer does not duration-skip when the gap is not covered", async () => }; const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: shortFormat, latency: 10_000 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: shortFormat, maxAge: 10_000 as Time.Milli }); // Group.Producer 0 stays open and later receives a second frame; nothing covers the gap, // so that late frame must survive rather than being skipped. @@ -715,7 +715,7 @@ test("Consumer delivers a PTS-contiguous next group whose sequence jumped (CMAF) const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), - latency: 500 as Time.Milli, + maxAge: 500 as Time.Milli, }); // Group A (seq 1_000_000): one 3000-tick sample, so its content ends at 33_333µs (3000/90000 * 1e6). @@ -771,10 +771,10 @@ test("Consumer delivers a PTS-contiguous next group whose sequence jumped (CMAF) // Delivery resumes only once the missing, timeline-continuous group arrives. test("Consumer waits on a PTS gap instead of skipping to a later buffered group (CMAF)", async () => { const track = new Track.Producer("test"); - // Large latency so the gap can't be latency-skipped during the test window. + // Large max age so the gap can't be age-skipped during the test window. const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), - latency: 10_000 as Time.Milli, + maxAge: 10_000 as Time.Milli, }); // Group A (seq 1_000_000): content ends at 33_333µs. @@ -848,7 +848,7 @@ test("Consumer delivers a contiguous group after one that completed out of order const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), - latency: 10_000 as Time.Milli, + maxAge: 10_000 as Time.Milli, }); // A (seq 1_000_000) stays open so it remains the active group. @@ -890,13 +890,13 @@ test("Consumer delivers a contiguous group after one that completed out of order }); // While the cursor sits below every buffered group (a real PTS gap it is waiting out), the delivery -// head still has to run the latency check on each frame. If only the head is receiving frames, +// head still has to run the max age check on each frame. If only the head is receiving frames, // that check is the only thing left that can break the stall. -test("Consumer latency-skips a waited-out gap when only the head receives frames (CMAF)", async () => { +test("Consumer age-skips a waited-out gap when only the head receives frames (CMAF)", async () => { const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), - latency: 100 as Time.Milli, + maxAge: 100 as Time.Milli, }); // A (seq 1000): one frame, ends at 3000 ticks (33_333µs). @@ -915,7 +915,7 @@ test("Consumer latency-skips a waited-out gap when only the head receives frames await settle(); // C (seq 3000) lands just behind B, inside the 100ms budget, then goes silent for the rest of - // the test. So C's frames can't be what re-runs the latency check. + // the test. So C's frames can't be what re-runs the max age check. const c = new Group.Producer(3000); track.writeGroup(c); c.writeFrame({ payload: encodeCmafFrame(0x03, 93_000, 2), timestamp: Time.Timestamp.now() }); @@ -929,7 +929,7 @@ test("Consumer latency-skips a waited-out gap when only the head receives frames await settle(10); } - // The latency check drops B as the oldest and delivery resumes at C. + // The max age check drops B as the oldest and delivery resumes at C. const result = await Promise.race([pending, settle(300).then(() => "timeout" as const)]); expect(result).not.toBe("timeout"); const delivered = result as { frame?: Frame; continuous?: boolean } | undefined; @@ -944,10 +944,10 @@ test("Consumer latency-skips a waited-out gap when only the head receives frames // `continuous` is what downstream buffer accounting keys on, so it must be false exactly when the // consumer dropped something. Group numbers can't answer that: they aren't required to be -// sequential, and adjacency doesn't rule out a group the latency check dropped on the way past. +// sequential, and adjacency doesn't rule out a group the max age check dropped on the way past. test("Consumer reports continuity while nothing is dropped", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 100 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 100 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); await settle(); @@ -965,7 +965,7 @@ test("Consumer reports continuity while nothing is dropped", async () => { test("Consumer reports an empty group as a codec discontinuity", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 2_000 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 2_000 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]); const marker = new Group.Producer(1); @@ -987,7 +987,7 @@ test("Consumer reports an empty group as a codec discontinuity", async () => { test("Consumer advances a completed empty group across a sequence gap", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 0 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 0 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]); await settle(); @@ -1012,9 +1012,9 @@ test("Consumer advances a completed empty group across a sequence gap", async () consumer.close(); }); -test("Consumer waits for an empty-group FIN before latency-skipping it", async () => { +test("Consumer waits for an empty-group FIN before age-skipping it", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 0 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), maxAge: 0 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]); await settle(); @@ -1049,7 +1049,7 @@ test("Consumer reports continuity across a PTS-contiguous group id jump (CMAF)", const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), - latency: 10_000 as Time.Milli, + maxAge: 10_000 as Time.Milli, }); const a = new Group.Producer(1_000_000); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index d60d6a98929..26b3bae2cae 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -9,9 +9,15 @@ import type { BufferedRanges, Frame } from "./types"; export interface ConsumerProps { /** The container format used to decode each MoQ frame. */ format: Format; - /** Target latency in milliseconds, controlling how aggressively slow groups are skipped (default: 0). */ + /** + * How stale a group may get before it is skipped, in milliseconds (default: 0). + * + * Measured as the span from the oldest buffered frame to the newest, so it bounds how long a + * late or missing group is waited for. The local half of the subscription's + * `maxAge`; both measure the same budget, one on the wire and one as frames are read. + */ // Read-only: a Getter (e.g. another component's output) is accepted directly. - latency?: GetterInit; + maxAge?: GetterInit; } interface Group { @@ -108,11 +114,11 @@ function continues(prev: Group, next: Group | undefined): next is Group { ); } -/** Reads frames from a MoQ track in order, buffering groups and skipping slow ones to meet the latency target. */ +/** Reads frames from a MoQ track in order, buffering groups and skipping ones that age past `maxAge`. */ export class Consumer { #track: Moq.Track.Subscriber; #format: Format; - #latency: Getter; + #maxAge: Getter; #groups: Group[] = []; #active?: number; // the active group sequence number // Presentation end (max PTS + duration) of the group we most recently advanced past, so next()'s @@ -122,8 +128,8 @@ export class Consumer { // Group of the last frame next() returned, so it can report whether the following result // continues that frame's timeline. Undefined until the first delivery and after a rewind. #deliveredGroup?: number; - // Set whenever the consumer throws content away: a slow group skipped to meet the latency - // target, a group truncated by a decode error, a reneged straggler, a rewind. Reported (and + // Set whenever the consumer throws content away: a group that aged past `maxAge`, + // a group truncated by a decode error, a reneged straggler, a rewind. Reported (and // cleared) on the first frame delivered from the next group, which is where the missing span // sits. Only the consumer can know this, which is why next() reports it instead of leaving // callers to guess from group numbers. @@ -143,7 +149,7 @@ export class Consumer { constructor(track: Moq.Track.Subscriber, props: ConsumerProps) { this.#track = track; this.#format = props.format; - this.#latency = getter(props.latency ?? Moq.Time.Milli.zero); + this.#maxAge = getter(props.maxAge ?? Moq.Time.Milli.zero); this.#signals.spawn(this.#run.bind(this)); this.#signals.cleanup(() => { @@ -244,13 +250,13 @@ export class Consumer { let skipped = false; if (group.consumer.sequence !== this.#active) { // A non-active group: resolve it against an active reset (dropping a - // reneged straggler), else detect a new rewind, then check latency. This + // reneged straggler), else detect a new rewind, then check the age. This // runs even when the group is the delivery head, because that is exactly // the stalled case (#active sits below every buffered group) where the - // latency budget is what eventually breaks the stall. + // max age budget is what eventually breaks the stall. if (this.#classifyStale(group)) return; this.#checkReset(group); - this.#checkLatency(); + this.#checkMaxAge(); // A newer group reaching back to where the stalled active group has // already presented means we can advance now instead of waiting. @@ -286,11 +292,11 @@ export class Consumer { // Advance to the next buffered group's actual sequence, but ONLY if it continues this // group's timeline. Some encoders number groups non-sequentially with large gaps (not // +1), so a bare `+= 1` would point #active at a nonexistent sequence and stall next() - // until #checkLatency skipped it -- every group through the skip path, i.e. constant + // until #checkMaxAge skipped it -- every group through the skip path, i.e. constant // stutter. A real PTS gap is different: an intermediate group may still be in transit, // so fall back to +1 there (next()'s promotion guard fixes it up once a continuous - // group arrives) and let #checkLatency / #tryDurationSkip skip the gap only once - // latency or duration coverage proves it too old. + // group arrives) and let #checkMaxAge / #tryDurationSkip skip the gap only once + // age or duration coverage proves it too old. const next = this.#groups[this.#groups.indexOf(group) + 1]; this.#active = continues(group, next) ? next.consumer.sequence : group.consumer.sequence + 1; } @@ -322,22 +328,22 @@ export class Consumer { // Frames within a group are consecutive by protocol, so only a group boundary can break it, and // there it comes down to whether anything was dropped in between. Deliberately not derived from // group numbers: they need not be sequential, so adjacency neither proves continuity nor catches - // a group the latency check truncated on the way past. + // a group the max age check truncated on the way past. #continuesDelivery(sequence: number): boolean { if (this.#deliveredGroup === undefined) return false; return sequence === this.#deliveredGroup || !this.#gap; } - #checkLatency() { + #checkMaxAge() { if (this.#active === undefined) return; let skipped = false; - // Keep skipping the oldest group while the buffered span exceeds the latency target. + // Keep skipping the oldest group while the buffered span exceeds the max age. // This also handles gaps in group sequence numbers: if #active points to a missing - // group, the latency span proves the missing content is too old to wait for. + // group, the span proves the missing content is too old to wait for. while (this.#groups.length >= 2) { - const threshold = Moq.Time.Micro.fromMilli(this.#latency.peek()); + const threshold = Moq.Time.Micro.fromMilli(this.#maxAge.peek()); const first = this.#groups[0]; if (first.empty && !first.consumer.done) break; @@ -355,8 +361,8 @@ export class Consumer { if (min === undefined || max === undefined) break; - const latency = max - min; - if (latency <= threshold) break; + const age = max - min; + if (age <= threshold) break; this.#groups.shift(); this.#active = this.#groups[0]?.consumer.sequence; @@ -510,7 +516,7 @@ export class Consumer { * `continuous` is true when this result picks up exactly where the previous frame left off, so * the span between them can be treated as delivered. It is false on the first frame, after a * rewind, and whenever the consumer threw content away to keep up: a slow group skipped for the - * latency target, a group truncated by a decode error, a reneged straggler. Use it rather than + * max age, a group truncated by a decode error, a reneged straggler. Use it rather than * comparing group numbers, which are not required to be sequential: adjacency neither proves * the timeline is unbroken nor catches a group dropped on the way past. * @@ -540,7 +546,7 @@ export class Consumer { // Promote #active to the first buffered group when it continues the timeline we left off at, // or when a completed empty group declares a boundary that makes the earlier gap irrelevant. // Otherwise a real gap sits before it and an in-transit group may still arrive, so wait. - // #checkLatency skips the gap once the buffered span exceeds the latency budget, and + // #checkMaxAge skips the gap once the buffered span exceeds the budget, and // #tryDurationSkip once the duration covers it. if (this.#active !== undefined && this.#groups.length > 0) { const head = this.#groups[0]; @@ -591,7 +597,7 @@ export class Consumer { // a below-#active group (a backlog group admitted behind the live edge) may // still be downloading when its buffer momentarily drains, and removing it // then silently truncates its tail. #runGroup notifies whenever the head - // group gains a frame, so waiting here is woken, and #checkLatency bounds + // group gains a frame, so waiting here is woken, and #checkMaxAge bounds // how long a stalled head can hold delivery up. if (this.#groups[0].done) { if (this.#groups[0].consumer.sequence === this.#active) { diff --git a/js/hang/src/container/types.ts b/js/hang/src/container/types.ts index 5f4d53a9177..15e79fe0dd8 100644 --- a/js/hang/src/container/types.ts +++ b/js/hang/src/container/types.ts @@ -13,7 +13,7 @@ export interface Frame { // per-sample duration; containers that don't (Legacy) leave it undefined, // which the consumer treats as zero. The consumer adds it to `timestamp` to // learn how far a group has presented, so it can advance to a newer group as - // soon as the gap is covered instead of waiting out the latency budget. + // soon as the gap is covered instead of waiting out the max age budget. duration?: Time.Micro; } diff --git a/js/moq-boy/src/game.ts b/js/moq-boy/src/game.ts index 054411aa303..9c881808c2b 100644 --- a/js/moq-boy/src/game.ts +++ b/js/moq-boy/src/game.ts @@ -74,7 +74,7 @@ export class Game { // Reactive state exposed to UI. readonly hovered = new Moq.Signals.Signal(false); readonly active = new Moq.Signals.Signal(false); - readonly latency = new Moq.Signals.Signal("real-time"); + readonly delay = new Moq.Signals.Signal("auto"); readonly userMuted = new Moq.Signals.Signal(false); readonly volume = new Moq.Signals.Signal(0.25); readonly status = new Moq.Signals.Signal(undefined); @@ -140,7 +140,7 @@ export class Game { // local signal so Sync can be constructed first. const videoJitter = new Moq.Signals.Signal(undefined); this.sync = new Watch.Sync({ - latency: this.latency, + delay: this.delay, probe: connection.probe, video: videoJitter, audio: this.audioSource.out.jitter, diff --git a/js/moq-boy/src/ui/components/StatsPanel.tsx b/js/moq-boy/src/ui/components/StatsPanel.tsx index 0436a7388e1..6b86b2a2c94 100644 --- a/js/moq-boy/src/ui/components/StatsPanel.tsx +++ b/js/moq-boy/src/ui/components/StatsPanel.tsx @@ -11,7 +11,7 @@ export default function StatsPanel() { const onJitterInput = (e: Event) => { const el = e.currentTarget as HTMLInputElement; - game.latency.set(Number.parseInt(el.value, 10) as import("@moq/net").Time.Milli); + game.delay.set(Number.parseInt(el.value, 10) as import("@moq/net").Time.Milli); }; const location = () => ctx.status()?.location; diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index f418bc0299e..91a93de9fd6 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -164,9 +164,9 @@ export class Decoder { }); effect.cleanup(() => worklet.disconnect()); - // Initial target latency in samples. - const latency = this.sync.out.buffer.peek(); - const latencySamples = ringSamples(sampleRate, latency); + // Initial ring depth in samples. + const delay = this.sync.out.delay.peek(); + const latencySamples = ringSamples(sampleRate, delay); const buffered = this.sync.out.buffered.peek(); // Let the factory pick the best transport (SharedArrayBuffer or postMessage). @@ -213,11 +213,11 @@ export class Decoder { const ring = this.#ring; if (!ring) return; - const latency = effect.get(this.sync.out.buffer); - ring.setLatency(ringSamples(ring.rate, latency)); + const delay = effect.get(this.sync.out.delay); + ring.setLatency(ringSamples(ring.rate, delay)); } - // Re-anchor when the latency floor *increases*. A larger floor needs a deeper cushion: video + // Re-anchor when the delay floor *increases*. A larger floor needs a deeper cushion: video // rebuilds it implicitly (its per-frame sync.wait() reads the live buffer, so it just holds // longer), but the audio ring keeps draining at its old depth -- resize() (via setLatency) only // re-stalls an *empty* ring, so a mid-playback ring never refills to the new floor and audio runs @@ -227,7 +227,7 @@ export class Decoder { // natural catch-up. #runLatencyReanchor(effect: Effect): void { const floor = reanchorFloor({ - latency: effect.get(this.sync.in.latency), + delay: effect.get(this.sync.in.delay), audio: effect.get(this.sync.in.audio), video: effect.get(this.sync.in.video), }); @@ -274,7 +274,7 @@ export class Decoder { broadcast: active, track, priority: Catalog.PRIORITY.audio, - latency: this.sync.out.maxBuffer, + maxAge: this.sync.out.maxAge, }); if (config.container.kind === "cmaf") { @@ -293,7 +293,7 @@ export class Decoder { // TODO include JITTER_UNDERHEAD const consumer = new Container.Consumer(sub, { format, - latency: this.sync.out.maxBuffer, + maxAge: this.sync.out.maxAge, }); effect.cleanup(() => consumer.close()); @@ -398,7 +398,7 @@ export class Decoder { const consumer = new Container.Consumer(sub, { format: new Container.Cmaf.Format(init), - latency: this.sync.out.maxBuffer, + maxAge: this.sync.out.maxAge, }); effect.cleanup(() => consumer.close()); diff --git a/js/watch/src/audio/latency.test.ts b/js/watch/src/audio/latency.test.ts index 3f5ed43c39a..39cade4ba05 100644 --- a/js/watch/src/audio/latency.test.ts +++ b/js/watch/src/audio/latency.test.ts @@ -5,29 +5,29 @@ import { reanchorFloor, ringSamples } from "./latency"; const ms = (value: number) => value as Time.Milli; describe("reanchorFloor", () => { - it("includes fixed latency and the largest media delay", () => { - expect(reanchorFloor({ latency: ms(100), audio: ms(20), video: ms(80) })).toBe(ms(180)); + it("includes the fixed delay and the largest media delay", () => { + expect(reanchorFloor({ delay: ms(100), audio: ms(20), video: ms(80) })).toBe(ms(180)); }); it("tracks rendition delay without adaptive RTT jitter", () => { - expect(reanchorFloor({ latency: "real-time", audio: ms(20), video: ms(80) })).toBe(ms(80)); - expect(reanchorFloor({ latency: "real-time", audio: ms(20), video: ms(200) })).toBe(ms(200)); + expect(reanchorFloor({ delay: "auto", audio: ms(20), video: ms(80) })).toBe(ms(80)); + expect(reanchorFloor({ delay: "auto", audio: ms(20), video: ms(200) })).toBe(ms(200)); }); }); describe("ringSamples", () => { - // `latency="instant"` reports a zero buffer. Passed through, the ring rejects it and the + // `delay="instant"` reports a zero buffer. Passed through, the ring rejects it and the // worklet is left with no backend that any later resize can revive. - it("floors a zero latency at one render quantum", () => { + it("floors a zero delay at one render quantum", () => { expect(ringSamples(48_000, ms(0))).toBe(128); }); - it("floors a latency too short to fill a quantum", () => { + it("floors a delay too short to fill a quantum", () => { // 1ms at 48kHz is 48 samples. expect(ringSamples(48_000, ms(1))).toBe(128); }); - it("leaves a latency above the floor alone", () => { + it("leaves a delay above the floor alone", () => { expect(ringSamples(48_000, ms(100))).toBe(4_800); }); }); diff --git a/js/watch/src/audio/latency.ts b/js/watch/src/audio/latency.ts index 33a4d0b797d..e45485bdc8d 100644 --- a/js/watch/src/audio/latency.ts +++ b/js/watch/src/audio/latency.ts @@ -1,10 +1,10 @@ import { Time } from "@moq/net"; -import { type Latency, latencyBounds } from "../sync"; +import type { Delay } from "../sync"; /** The inputs that determine whether audio needs a deeper playback cushion. */ export interface ReanchorFloor { - /** The configured latency target. */ - latency: Latency; + /** How far playback trails the live edge. */ + delay: Delay; /** Additional delay required by the selected audio rendition. */ audio?: Time.Milli; @@ -13,10 +13,11 @@ export interface ReanchorFloor { video?: Time.Milli; } -/** The stable latency floor whose increase requires the audio ring to refill. */ +/** The stable delay floor whose increase requires the audio ring to refill. */ export function reanchorFloor(props: ReanchorFloor): Time.Milli { - const { min } = latencyBounds(props.latency); - const target = min === "real-time" ? Time.Milli.zero : min; + // "auto" and "instant" contribute nothing: the adaptive RTT component is deliberately excluded + // so an RTT wiggle doesn't re-anchor, and "instant" holds nothing at all. + const target = typeof props.delay === "number" ? props.delay : Time.Milli.zero; const media = Time.Milli.max(props.audio ?? Time.Milli.zero, props.video ?? Time.Milli.zero); return Time.Milli.add(target, media); } @@ -26,13 +27,13 @@ export function reanchorFloor(props: ReanchorFloor): Time.Milli { const RENDER_QUANTUM = 128; /** - * The ring depth for a target latency, floored at one AudioWorklet render quantum. + * The ring depth for a target delay, floored at one AudioWorklet render quantum. * - * `latency="instant"` reports a zero buffer, which the ring rejects outright: construction throws, + * `delay="instant"` reports a zero buffer, which the ring rejects outright: construction throws, * the worklet is left with no backend, and every later resize is gated on that backend existing, so * audio never recovers. Audio keeps its own floor rather than deriving its depth verbatim from a * buffer whose meaning is "video holds nothing". */ -export function ringSamples(rate: number, latency: Time.Milli): number { - return Math.max(RENDER_QUANTUM, Math.ceil(rate * Time.Second.fromMilli(latency))); +export function ringSamples(rate: number, delay: Time.Milli): number { + return Math.max(RENDER_QUANTUM, Math.ceil(rate * Time.Second.fromMilli(delay))); } diff --git a/js/watch/src/duration.test.ts b/js/watch/src/duration.test.ts new file mode 100644 index 00000000000..fc60ea50eee --- /dev/null +++ b/js/watch/src/duration.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, it } from "bun:test"; +import type { Time } from "@moq/net"; +import { formatDuration, parseDuration } from "./duration"; + +const ms = (value: number) => value as Time.Milli; + +describe("parseDuration", () => { + it("parses milliseconds", () => { + expect(parseDuration("300ms")).toBe(ms(300)); + expect(parseDuration("0ms")).toBe(ms(0)); + expect(parseDuration("1.5ms")).toBe(ms(1.5)); + }); + + it("parses seconds", () => { + expect(parseDuration("30s")).toBe(ms(30_000)); + expect(parseDuration("0.25s")).toBe(ms(250)); + }); + + it("rejects a bare number, which would otherwise be a 1000x error", () => { + expect(parseDuration("30")).toBeUndefined(); + expect(parseDuration("100")).toBeUndefined(); + }); + + it("accepts a bare zero, where the unit can't matter", () => { + expect(parseDuration("0")).toBe(ms(0)); + }); + + it("rejects anything else", () => { + expect(parseDuration("")).toBeUndefined(); + expect(parseDuration("-5ms")).toBeUndefined(); + expect(parseDuration("auto")).toBeUndefined(); + expect(parseDuration("1e3ms")).toBeUndefined(); + expect(parseDuration("30 s")).toBeUndefined(); + expect(parseDuration("30sec")).toBeUndefined(); + expect(parseDuration("30m")).toBeUndefined(); + }); + + it("tolerates surrounding whitespace", () => { + expect(parseDuration(" 30s ")).toBe(ms(30_000)); + }); +}); + +describe("formatDuration", () => { + it("round-trips through parseDuration, which is what keeps attribute reflection settled", () => { + expect(parseDuration(formatDuration(ms(300)))).toBe(ms(300)); + expect(parseDuration(formatDuration(ms(30_000)))).toBe(ms(30_000)); + expect(parseDuration(formatDuration(ms(0)))).toBe(ms(0)); + }); + + it("round-trips a fraction, since the reflected value is parsed straight back", () => { + // Rounding here would rewrite the caller's value: 1.5 becoming 2, and 0.4 becoming 0, + // which also switches buffered playback off. + expect(parseDuration(formatDuration(ms(1.5)))).toBe(ms(1.5)); + expect(parseDuration(formatDuration(ms(0.4)))).toBe(ms(0.4)); + }); +}); diff --git a/js/watch/src/duration.ts b/js/watch/src/duration.ts new file mode 100644 index 00000000000..d912fbebebf --- /dev/null +++ b/js/watch/src/duration.ts @@ -0,0 +1,36 @@ +import { Time } from "@moq/net"; + +/** + * Parse a duration attribute: `"300ms"`, `"30s"`, or a bare `"0"`. + * + * A bare number other than zero is rejected rather than guessed at. Most players measure these in + * seconds while we store milliseconds, so assuming a unit would turn a value copied from another + * player into a 1000x error. Zero is exempt because `0ms` and `0s` are the same value. + * + * Returns undefined when the value doesn't parse, leaving the fallback to the caller. + * + * @internal + */ +export function parseDuration(value: string): Time.Milli | undefined { + const match = /^(\d+(?:\.\d+)?)(ms|s)?$/.exec(value.trim()); + if (!match) return undefined; + + const amount = Number.parseFloat(match[1]); + if (!Number.isFinite(amount)) return undefined; + if (match[2] === undefined) return amount === 0 ? Time.Milli.zero : undefined; + + return Time.Milli(match[2] === "s" ? amount * 1000 : amount); +} + +/** + * Render a duration back out as an attribute value, in the canonical unit. + * + * Not rounded: the reflected attribute is parsed straight back into the signal, so rounding here + * would rewrite the value behind the caller (`1.5ms` becoming `2ms`, and `0.4ms` becoming zero, + * which also switches buffered playback off). + * + * @internal + */ +export function formatDuration(value: Time.Milli): string { + return `${value}ms`; +} diff --git a/js/watch/src/element.ts b/js/watch/src/element.ts index af82054139e..e5e01f413a8 100644 --- a/js/watch/src/element.ts +++ b/js/watch/src/element.ts @@ -11,7 +11,8 @@ import * as Moq from "@moq/net"; import { Effect, Signal } from "@moq/signals"; import * as Audio from "./audio"; import { Broadcast, type CatalogFormat, parseCatalogFormat } from "./broadcast"; -import { type Bound, type Latency, latencyBounds, latencyFromBounds, Sync } from "./sync"; +import { formatDuration, parseDuration } from "./duration"; +import { type Delay, Sync } from "./sync"; import * as Text from "./text"; import * as Video from "./video"; @@ -23,9 +24,13 @@ const OBSERVED = [ "muted", "visible", "reload", + "delay", + "buffer", + // Released spellings, kept parsing but off the documented surface. `latency-max` is absent + // deliberately: its old ceiling included the floor, so translating it faithfully would mean + // tracking the resolved delay reactively, which is the coupling `buffer` exists to remove. "latency", "latency-min", - "latency-max", "jitter", "catalog-format", "captions", @@ -45,6 +50,49 @@ function parseVisible(value: string | null): Video.Visible { return "20%"; } +// Parse the `delay` attribute: "auto" (adaptive), "instant" (no buffer, no pacing), or a duration. +function parseDelay(value: string | null): Delay { + const trimmed = value?.trim(); + if (!trimmed || trimmed === "auto") return "auto"; + if (trimmed === "instant") return "instant"; + const parsed = parseDuration(trimmed); + if (parsed !== undefined) return parsed; + console.warn(`moq-watch: invalid delay="${value}", expected "auto", "instant", or a duration like "300ms"`); + return "auto"; +} + +// Parse the `buffer` attribute: a duration, or none when absent. +function parseBuffer(value: string | null): Time.Milli { + const trimmed = value?.trim(); + if (!trimmed) return Moq.Time.Milli.zero; + const parsed = parseDuration(trimmed); + if (parsed !== undefined) return parsed; + console.warn(`moq-watch: invalid buffer="${value}", expected a duration like "30s"`); + return Moq.Time.Milli.zero; +} + +// The released `latency` / `latencyMin` property spellings, translated onto `delay`. The range +// object is refused rather than half-applied: its ceiling included the floor, so it has no faithful +// `buffer` without tracking the resolved delay, which is the coupling `buffer` exists to remove. +function coerceLegacyDelay(value: unknown): Delay { + if (value === "instant") return "instant"; + if (value === undefined || value === "auto" || value === "real-time") return "auto"; + if (typeof value === "number" && Number.isFinite(value)) return Moq.Time.Milli(value); + throw new Error( + "moq-watch: the latency range is gone. Set `delay` (how far playback trails the live edge) and `buffer` (media held beyond it).", + ); +} + +// The released spellings of `delay`, in bare milliseconds. Kept unitless so pages still on them +// behave exactly as they did; `delay` is the current surface and does require a unit. +function parseLegacyDelay(value: string | null): Delay { + const trimmed = value?.trim(); + if (!trimmed || trimmed === "real-time") return "auto"; + if (trimmed === "instant") return "instant"; + const parsed = Number.parseFloat(trimmed); + return Moq.Time.Milli(Number.isFinite(parsed) ? parsed : 100); +} + /** * Parse a boolean attribute: absent uses `defaultValue`, bare presence is true, and an explicit * `"false"`/`"0"` is false. Presence alone can't express false, and attributes that default to @@ -93,7 +141,7 @@ export default class MoqWatch extends HTMLElement { /** Renders caption cues into an overlay above the canvas. */ captionsRenderer: Text.Renderer; - /** Keeps audio and video playing at the target latency. */ + /** Keeps audio and video playing at the configured delay. */ sync: Sync; // The mutable user controls. As the top of the tree, this element owns the @@ -105,7 +153,10 @@ export default class MoqWatch extends HTMLElement { muted: new Signal(false), // When video is downloaded relative to the canvas position. See {@link Video.Visible}. visible: new Signal("20%"), - latency: new Signal("real-time"), + // How far playback trails the live edge. + delay: new Signal("auto"), + // Future-dated media held beyond the live edge before playback skips ahead. + buffer: new Signal(Moq.Time.Milli.zero), // The desired video rendition (resolution/bitrate cap). target: new Signal(undefined), // The selected caption track name, or undefined for off (the default; captions are opt-in). @@ -131,11 +182,6 @@ export default class MoqWatch extends HTMLElement { #videoEnabled = new Signal(false); #audioEnabled = new Signal(false); - // Set while this element writes the `latency` attribute itself, so attributeChangedCallback - // ignores the echo. Dropping a stale value would otherwise parse back as "real-time" and - // clobber the range that replaced it. - #reflectingLatency = false; - // Set when the element is connected to the DOM. #enabled = new Signal(false); @@ -197,7 +243,8 @@ export default class MoqWatch extends HTMLElement { const videoJitter = new Signal(undefined); this.sync = new Sync({ - latency: this.controls.latency, + delay: this.controls.delay, + buffer: this.controls.buffer, probe: this.connection.probe, video: videoJitter, audio: audioSource.out.jitter, @@ -239,18 +286,18 @@ export default class MoqWatch extends HTMLElement { }); // Audio download follows the emitter's enable policy (paused/muted), except an instant - // latency turns it off outright: the ring needs a target depth to avoid underrunning, and + // delay turns it off outright: the ring needs a target depth to avoid underrunning, and // unpaced video has nothing pulling it back toward the audio clock. this.signals.run((effect) => { const enabled = effect.get(this.emitter.out.enabled); - this.#audioEnabled.set(enabled && effect.get(this.controls.latency) !== "instant"); + this.#audioEnabled.set(enabled && effect.get(this.controls.delay) !== "instant"); }); // Stopping the download leaves the ring holding a floor's worth of PCM, and the emitter // stays connected to drain it. Flush on the way in so audio stops now instead of playing // against video that just jumped to the live edge. this.signals.run((effect) => { - if (effect.get(this.controls.latency) !== "instant") return; + if (effect.get(this.controls.delay) !== "instant") return; this.audio.reset(); }); @@ -349,29 +396,15 @@ export default class MoqWatch extends HTMLElement { this.setAttribute("visible", visible); }); + // Each knob is 1:1 with its attribute, so the echo back through attributeChangedCallback + // parses to the value already held and the effect settles. this.signals.run((effect) => { - const latency = effect.get(this.controls.latency); - if (latency === "instant") { - this.#reflectLatency("instant"); - return; - } + const delay = effect.get(this.controls.delay); + this.setAttribute("delay", typeof delay === "number" ? formatDuration(delay) : delay); + }); - const { min, max } = latencyBounds(latency); - // Only reflect the collapsed `latency` sugar attribute when the range is actually - // collapsed. An open range is expressed via latency-min/latency-max, and writing - // `latency` here would round-trip back through attributeChangedCallback and collapse it. - if (min !== max) { - // Still drop a stale "instant": leaving it would advertise a mode the element is no - // longer in, and a clone would come back up in it. - if (this.getAttribute("latency") === "instant") this.#reflectLatency(undefined); - return; - } - if (min === "real-time") { - this.#reflectLatency("real-time"); - } else { - const jitter = Math.floor(effect.get(this.sync.out.jitter)); - this.#reflectLatency(jitter.toString()); - } + this.signals.run((effect) => { + this.setAttribute("buffer", formatDuration(effect.get(this.controls.buffer))); }); // Track the element's rendered size and feed it into the rendition picker, @@ -426,35 +459,6 @@ export default class MoqWatch extends HTMLElement { this.#enabled.set(false); } - // Parse a single latency bound: absent or "real-time" is adaptive, otherwise a fixed ms value. - #parseBound(value: string | null): Bound { - if (!value || value === "real-time") return "real-time"; - if (value === "instant") { - console.warn('moq-watch: "instant" is not a bound, use latency="instant"'); - return "real-time"; - } - const parsed = Number.parseFloat(value); - return Moq.Time.Milli(Number.isFinite(parsed) ? parsed : 100); - } - - // Write the `latency` attribute (undefined removes it) without the echo coming back through - // attributeChangedCallback. Custom element reactions run before setAttribute/removeAttribute - // returns, so the flag still covers the callback. - #reflectLatency(value: string | undefined): void { - this.#reflectingLatency = true; - try { - if (value === undefined) this.removeAttribute("latency"); - else this.setAttribute("latency", value); - } finally { - this.#reflectingLatency = false; - } - } - - // Parse the `latency` attribute, which also accepts the range-replacing "instant". - #parseLatency(value: string | null): Latency { - return value?.trim() === "instant" ? "instant" : this.#parseBound(value); - } - attributeChangedCallback(name: Observed, oldValue: string | null, newValue: string | null) { if (oldValue === newValue) { return; @@ -475,16 +479,12 @@ export default class MoqWatch extends HTMLElement { this.controls.visible.set(parseVisible(newValue)); } else if (name === "reload") { this.#reload.set(parseBoolean(newValue, true)); - } else if (name === "latency") { - // Sugar: collapse the floor and ceiling to a single value. - if (!this.#reflectingLatency) this.latency = this.#parseLatency(newValue); - } else if (name === "latency-min") { - this.latencyMin = this.#parseBound(newValue); - } else if (name === "latency-max") { - this.latencyMax = this.#parseBound(newValue); - } else if (name === "jitter") { - // Deprecated: use latency="" instead. - this.latency = this.#parseBound(newValue); + } else if (name === "delay") { + this.controls.delay.set(parseDelay(newValue)); + } else if (name === "buffer") { + this.controls.buffer.set(parseBuffer(newValue)); + } else if (name === "latency" || name === "latency-min" || name === "jitter") { + this.controls.delay.set(parseLegacyDelay(newValue)); } else if (name === "catalog-format") { this.#catalogFormat.set(parseCatalogFormat(newValue)); } else if (name === "captions") { @@ -553,43 +553,58 @@ export default class MoqWatch extends HTMLElement { } /** - * The latency target. Assign a scalar (or `"real-time"`) to minimize latency, or an object - * `{ min, max }` to open a range and buffer future-dated frames. See {@link Latency}. + * How far playback trails the live edge, in milliseconds. See {@link Delay}. + * + * `"auto"` (the default) sizes the jitter buffer from the connection RTT. `"instant"` drops the + * clock instead: video paints the moment it decodes and audio is disabled. + */ + get delay(): Delay { + return this.controls.delay.peek(); + } + + set delay(value: Delay) { + this.controls.delay.set(value); + } + + /** + * Future-dated media held beyond the live edge before playback skips ahead, in milliseconds. * - * `"instant"` drops the clock instead: video paints the moment it decodes and audio is - * disabled. Assigning `latencyMin` or `latencyMax` leaves that mode, since both write a range. + * Zero (the default) minimizes latency. A larger value enables buffered playback: build up a + * buffer from future-dated frames (e.g. TTS written faster than real-time) and only skip ahead + * once they would sit further than `delay + buffer` past the playhead. Call `reset()` at each + * utterance boundary. */ - get latency(): Latency { - return this.controls.latency.peek(); + get buffer(): Time.Milli { + return this.controls.buffer.peek(); } - set latency(value: Latency) { - this.controls.latency.set(value); + set buffer(value: Time.Milli) { + this.controls.buffer.set(value); } - /** The latency floor (jitter/startup buffer). Read-modify-writes `latency`, leaving the ceiling. */ - get latencyMin(): Bound { - return latencyBounds(this.controls.latency.peek()).min; + /** @internal */ + get latency(): Delay { + return this.controls.delay.peek(); } - set latencyMin(value: Bound) { - const { max } = latencyBounds(this.controls.latency.peek()); - this.controls.latency.set(latencyFromBounds(value, max)); + set latency(value: unknown) { + this.controls.delay.set(coerceLegacyDelay(value)); } - /** - * The latency ceiling: `"real-time"` (default) minimizes, a number caps at that many ms. A - * ceiling above the floor enables buffered playback: build up a buffer from future-dated frames - * (e.g. TTS written faster than real-time) and only skip ahead past the cap. Call `reset()` at - * each utterance boundary. Read-modify-writes `latency`, leaving the floor untouched. - */ - get latencyMax(): Bound { - return latencyBounds(this.controls.latency.peek()).max; + /** @internal */ + get latencyMin(): Delay { + return this.controls.delay.peek(); + } + + set latencyMin(value: unknown) { + this.controls.delay.set(coerceLegacyDelay(value)); } - set latencyMax(value: Bound) { - const { min } = latencyBounds(this.controls.latency.peek()); - this.controls.latency.set(latencyFromBounds(min, value)); + /** @internal */ + set latencyMax(_value: unknown) { + throw new Error( + "moq-watch: `latencyMax` is gone. Use `buffer`, the media held beyond the live edge; the old ceiling included the floor, so it is `latencyMax - delay`.", + ); } /** The jitter buffer in milliseconds. */ diff --git a/js/watch/src/media.test.ts b/js/watch/src/media.test.ts index 96fec974498..383a5b1b4bb 100644 --- a/js/watch/src/media.test.ts +++ b/js/watch/src/media.test.ts @@ -6,7 +6,7 @@ import { subscribeMedia } from "./media"; const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); -test("media latency is present on the initial subscription and later updates", async () => { +test("media max age is present on the initial subscription and later updates", async () => { let initial: Moq.Track.Subscription | undefined; const updates: Moq.Track.Subscription[] = []; const subscriber = { @@ -21,18 +21,18 @@ test("media latency is present on the initial subscription and later updates", a }, }), } as unknown as Moq.Broadcast.Consumer; - const latency = new Signal(Time.Milli(250)); + const maxAge = new Signal(Time.Milli(250)); const effect = new Effect(); subscribeMedia(effect, { broadcast, track: "media", priority: 7, - latency, + maxAge, }); expect(initial).toEqual({ priority: 7, maxAge: 250 }); - latency.set(Time.Milli(500)); + maxAge.set(Time.Milli(500)); await flush(); expect(updates.at(-1)).toEqual({ priority: 7, maxAge: 500 }); diff --git a/js/watch/src/media.ts b/js/watch/src/media.ts index f600b1962eb..6f557c376b7 100644 --- a/js/watch/src/media.ts +++ b/js/watch/src/media.ts @@ -3,7 +3,7 @@ import type { Time } from "@moq/net"; import type { Effect, Getter } from "@moq/signals"; /** - * Open a media subscription with its latency ceiling on the initial request and every update. + * Open a media subscription with its max age on the initial request and every update. * * @internal */ @@ -13,15 +13,15 @@ export function subscribeMedia( broadcast: Moq.Broadcast.Consumer; track: string; priority: number; - latency: Getter; + maxAge: Getter; }, ): Moq.Track.Subscriber { - const subscription = () => ({ priority: props.priority, maxAge: props.latency.peek() }); + const subscription = () => ({ priority: props.priority, maxAge: props.maxAge.peek() }); const subscriber = props.broadcast.track(props.track).subscribe(subscription()); effect.cleanup(() => subscriber.close()); effect.run((inner) => { - subscriber.update({ priority: props.priority, maxAge: inner.get(props.latency) }); + subscriber.update({ priority: props.priority, maxAge: inner.get(props.maxAge) }); }); return subscriber; diff --git a/js/watch/src/sync.test.ts b/js/watch/src/sync.test.ts index d2a18044741..ca8c8209b1f 100644 --- a/js/watch/src/sync.test.ts +++ b/js/watch/src/sync.test.ts @@ -1,59 +1,65 @@ import { describe, expect, it } from "bun:test"; import type { Time } from "@moq/net"; import { Signal } from "@moq/signals"; -import { type Latency, Sync } from "./sync"; +import { Sync } from "./sync"; // Effects in @moq/signals flush on a microtask, so let pending updates drain before asserting. const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); -describe("latency range", () => { - it("is collapsed by default", async () => { +describe("delay and buffer", () => { + it("holds no lookahead by default", async () => { const sync = new Sync(); await flush(); expect(sync.out.buffered.peek()).toBe(false); sync.close(); }); - it("stays collapsed for a scalar latency", async () => { - const sync = new Sync({ latency: 100 as Time.Milli }); + it("caps maxAge at the delay when no buffer is configured", async () => { + const sync = new Sync({ delay: 100 as Time.Milli }); await flush(); expect(sync.out.buffered.peek()).toBe(false); - expect(sync.out.maxBuffer.peek()).toBe(100 as Time.Milli); + expect(sync.out.delay.peek()).toBe(100 as Time.Milli); + expect(sync.out.maxAge.peek()).toBe(100 as Time.Milli); sync.close(); }); - it("enters buffered mode when the ceiling is above the floor", async () => { - const sync = new Sync({ latency: { max: 30_000 as Time.Milli } }); + it("adds the buffer on top of the delay", async () => { + // The buffer is measured from the live edge, so it does not swallow the delay: a frame may + // sit `delay + buffer` ahead of the playhead before playback skips forward. + const sync = new Sync({ delay: 100 as Time.Milli, buffer: 30_000 as Time.Milli }); await flush(); expect(sync.out.buffered.peek()).toBe(true); - expect(sync.out.maxBuffer.peek()).toBe(30_000 as Time.Milli); + expect(sync.out.maxAge.peek()).toBe(30_100 as Time.Milli); sync.close(); }); - it("stays collapsed when the ceiling is at or below the floor", async () => { - // Fixed 200ms floor sits above the 100ms ceiling, so there's no room to buffer. - const sync = new Sync({ latency: { min: 200 as Time.Milli, max: 100 as Time.Milli } }); + it("stays unbuffered for a zero buffer", async () => { + const sync = new Sync({ delay: 200 as Time.Milli, buffer: 0 as Time.Milli }); await flush(); expect(sync.out.buffered.peek()).toBe(false); + expect(sync.out.maxAge.peek()).toBe(200 as Time.Milli); sync.close(); }); - it("reacts to a ceiling set after construction", async () => { - const latency = new Signal("real-time"); - const sync = new Sync({ latency }); + it("reacts to a buffer set after construction", async () => { + const buffer = new Signal(0 as Time.Milli); + const sync = new Sync({ delay: 100 as Time.Milli, buffer }); await flush(); expect(sync.out.buffered.peek()).toBe(false); - latency.set({ max: 30_000 as Time.Milli }); + buffer.set(30_000 as Time.Milli); await flush(); expect(sync.out.buffered.peek()).toBe(true); + expect(sync.out.maxAge.peek()).toBe(30_100 as Time.Milli); sync.close(); }); - it("stays collapsed for an explicit real-time ceiling", async () => { - const sync = new Sync({ latency: { max: "real-time" } }); + it("holds nothing when instant, whatever the buffer says", async () => { + const sync = new Sync({ delay: "instant", buffer: 30_000 as Time.Milli }); await flush(); expect(sync.out.buffered.peek()).toBe(false); + expect(sync.out.delay.peek()).toBe(0 as Time.Milli); + expect(sync.out.maxAge.peek()).toBe(0 as Time.Milli); sync.close(); }); }); diff --git a/js/watch/src/sync.ts b/js/watch/src/sync.ts index 2b68f971718..3f0c2a82fcb 100644 --- a/js/watch/src/sync.ts +++ b/js/watch/src/sync.ts @@ -2,54 +2,38 @@ import type * as Moq from "@moq/net"; import { Time } from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; -/** A single latency bound: `"real-time"` adapts to the RTT; a `Time.Milli` fixes the jitter buffer. */ -export type Bound = "real-time" | Time.Milli; - /** - * Latency target. A scalar (or `"real-time"`) collapses the range and minimizes latency, the live - * default. An object opens a range `[min, max]`: playback buffers freely between the floor and the - * ceiling and only skips ahead once latency would exceed the ceiling, so faster-than-real-time - * frames (e.g. a TTS response with future timestamps) build up instead of being skipped. Both - * bounds default to `"real-time"` when omitted. The ceiling is always finite (no uncapped buffering), - * so worst case the audio ring drops its oldest samples rather than exhausting memory. + * How far playback trails the live edge. + * + * `"auto"` (the default) sizes the jitter buffer from the connection RTT; a `Time.Milli` fixes it. * * `"instant"` drops the buffer and the pacing together: nothing is held, and {@link Sync.wait} - * returns without sleeping, so a frame presents as soon as it exists. It replaces the range rather - * than sitting inside it, so it is not a {@link Bound} and can't be used as a floor or ceiling. - * Audio is the owner's business: a ring with no depth underruns, so whoever wants this mode is - * expected to turn audio off. - */ -export type Latency = "instant" | Bound | { min?: Bound; max?: Bound }; - -/** - * Resolve a {@link Latency} into explicit floor/ceiling bounds (a scalar collapses to `min == max`). - * `"instant"` holds nothing, so both bounds are zero. + * returns without sleeping, so a frame presents as soon as it exists. It also overrides + * {@link SyncInput.buffer}, since holding a lookahead would contradict holding nothing. Audio is + * the owner's business: a ring with no depth underruns, so whoever wants this mode is expected to + * turn audio off. */ -export function latencyBounds(latency: Latency): { min: Bound; max: Bound } { - if (latency === "instant") return { min: Time.Milli.zero, max: Time.Milli.zero }; - if (latency === "real-time" || typeof latency === "number") { - return { min: latency, max: latency }; - } - return { min: latency.min ?? "real-time", max: latency.max ?? "real-time" }; -} - -/** Build a {@link Latency} from explicit bounds, collapsing to a scalar when they're equal. */ -export function latencyFromBounds(min: Bound, max: Bound): Latency { - return min === max ? min : { min, max }; -} +export type Delay = "instant" | "auto" | Time.Milli; const MIN_JITTER = Time.Milli(20); const FALLBACK_JITTER = Time.Milli(100); export type SyncInput = { + /** How far playback trails the live edge. See {@link Delay}. */ + delay: Getter; + /** - * Latency target: a scalar minimizes (collapsed range), an object opens a range, and - * `"instant"` holds nothing and never sleeps. See {@link Latency}. + * Future-dated media held beyond the live edge before playback skips ahead (default: zero). + * + * Zero minimizes latency, the live default: playback re-anchors as soon as anything arrives + * early. A larger value lets faster-than-real-time frames (a TTS response with future + * timestamps) build up instead of being skipped. Always finite, so worst case the audio ring + * drops its oldest samples rather than exhausting memory. */ - latency: Getter; + buffer: Getter; /** - * The connection's PROBE estimates, whose RTT drives "real-time" jitter. Usually wired + * The connection's PROBE estimates, whose RTT drives "auto" jitter. Usually wired * from a `Connection.Shared`'s or `Reload`'s `probe`. */ probe: Getter; @@ -66,24 +50,25 @@ type SyncOutput = { // This will keep being updated as we catch up to the live playhead then will be relatively static. reference: Signal; - // The total buffer required: jitter + max(audio, video). - buffer: Signal; + // The resolved delay from the live edge to the playhead: jitter + max(audio, video). + delay: Signal; - // The jitter buffer in milliseconds (always numeric). - // In "real-time" mode this is updated automatically from RTT. - // When the floor is a number, jitter equals that number. + // The jitter component of `delay` (always numeric). + // In "auto" mode this is updated automatically from RTT. + // When the delay is a number, jitter equals that number. jitter: Signal; // The media timestamp of the most recently received frame. timestamp: Signal; - // Derived: true when the ceiling sits above the floor. Buffered playback lets the reference - // stay anchored so future-dated frames build up a buffer, re-anchoring (skipping ahead) only - // when latency would exceed the ceiling. See `reset()`. + // Derived: true when a lookahead is configured. Buffered playback lets the reference stay + // anchored so future-dated frames build up, re-anchoring (skipping ahead) only once they + // would sit further than `maxAge` ahead of the playhead. See `reset()`. buffered: Signal; - // Derived cap on buffered audio (ms), consumed by the audio ring to size itself. Always finite. - maxBuffer: Signal; + // Derived: `delay + buffer`, the furthest a held frame may sit ahead of the playhead. Feeds the + // transport subscription and the container consumer, which bound the same span. Always finite. + maxAge: Signal; }; export class Sync { @@ -91,11 +76,11 @@ export class Sync { readonly #out: SyncOutput = { reference: new Signal(undefined), - buffer: new Signal(Time.Milli.zero), + delay: new Signal(Time.Milli.zero), jitter: new Signal(FALLBACK_JITTER), timestamp: new Signal(undefined), buffered: new Signal(false), - maxBuffer: new Signal(Time.Milli.zero), + maxAge: new Signal(Time.Milli.zero), }; readonly out = readonlys(this.#out); @@ -114,7 +99,8 @@ export class Sync { constructor(props?: Inputs) { this.in = { - latency: getter(props?.latency ?? ("real-time" as Latency)), + delay: getter(props?.delay ?? ("auto" as Delay)), + buffer: getter(props?.buffer ?? Time.Milli.zero), probe: getter(props?.probe), audio: getter(props?.audio), video: getter(props?.video), @@ -123,46 +109,38 @@ export class Sync { this.#update = Promise.withResolvers(); this.#signals.run(this.#runJitter.bind(this)); - this.#signals.run(this.#runBuffer.bind(this)); - this.#signals.run(this.#runRange.bind(this)); + this.#signals.run(this.#runDelay.bind(this)); + this.#signals.run(this.#runMaxAge.bind(this)); } - // Derive `buffered` / `maxBuffer` from the floor (`buffer`) and the ceiling (the `max` bound). - #runRange(effect: Effect): void { - const { max } = latencyBounds(effect.get(this.in.latency)); - const floor = effect.get(this.#out.buffer); - - if (max === "real-time") { - // Ceiling tracks the floor: minimize latency, the live default. - this.#out.buffered.set(false); - this.#out.maxBuffer.set(floor); - } else { - // Buffered only when the ceiling is above the floor; otherwise it collapses to minimize. - this.#out.buffered.set(max > floor); - this.#out.maxBuffer.set(Time.Milli.max(max, floor)); - } - } + // Derive `buffered` / `maxAge` from the resolved delay and the configured lookahead. + #runMaxAge(effect: Effect): void { + const delay = effect.get(this.#out.delay); + // "instant" holds nothing, so a configured lookahead doesn't apply. + const buffer = effect.get(this.in.delay) === "instant" ? Time.Milli.zero : effect.get(this.in.buffer); - // The maximum total latency (lookahead + floor) we tolerate before re-anchoring, in ms. - // Used by `received()` to decide when to skip ahead. - #latencyCap(): Time.Milli { - const { max } = latencyBounds(this.in.latency.peek()); - const floor = this.#out.buffer.peek(); - if (max === "real-time") return floor; - return Time.Milli.max(max, floor); + this.#out.buffered.set(buffer > 0); + this.#out.maxAge.set(Time.Milli.add(delay, buffer)); } #runJitter(effect: Effect): void { - const { min } = latencyBounds(effect.get(this.in.latency)); + const delay = effect.get(this.in.delay); + + if (delay === "instant") { + // Holds nothing at all. + this.#minRtt = undefined; + this.#out.jitter.set(Time.Milli.zero); + return; + } - if (typeof min === "number") { - // Fixed mode: the floor value is the jitter. + if (typeof delay === "number") { + // Fixed mode: the configured delay is the jitter. this.#minRtt = undefined; - this.#out.jitter.set(min); + this.#out.jitter.set(delay); return; } - // "real-time" mode: compute jitter from the connection's RTT estimate. + // "auto" mode: compute jitter from the connection's RTT estimate. const rtt = effect.get(this.in.probe)?.rtt; if (rtt !== undefined) { // Track minimum RTT as baseline, ignoring bufferbloat. @@ -179,23 +157,23 @@ export class Sync { this.#out.jitter.set(FALLBACK_JITTER); } - #runBuffer(effect: Effect): void { + #runDelay(effect: Effect): void { const jitter = effect.get(this.#out.jitter); const video = effect.get(this.in.video) ?? Time.Milli.zero; const audio = effect.get(this.in.audio) ?? Time.Milli.zero; - // A zero floor still holds the rendition's own delay, which is a frame interval at 60fps. + // A zero delay still holds the rendition's own delay, which is a frame interval at 60fps. // "instant" holds nothing at all. - const instant = effect.get(this.in.latency) === "instant"; - const buffer = instant ? Time.Milli.zero : Time.Milli.add(Time.Milli.max(video, audio), jitter); - this.#out.buffer.set(buffer); + const instant = effect.get(this.in.delay) === "instant"; + const delay = instant ? Time.Milli.zero : Time.Milli.add(Time.Milli.max(video, audio), jitter); + this.#out.delay.set(delay); this.#update.resolve(); this.#update = Promise.withResolvers(); } // Fold a newly received frame into the reference. The reference anchors playback to the - // wall clock; we lower it (skip ahead) only when keeping it would push latency past the cap. + // wall clock; we lower it (skip ahead) only when keeping it would push the lookahead past `maxAge`. received(timestamp: Time.Milli, label = ""): void { this.#out.timestamp.update((current) => (current === undefined || timestamp > current ? timestamp : current)); const now = Time.Milli.now(); @@ -211,8 +189,8 @@ export class Sync { // Check if `wait()` would not sleep at all. // NOTE: We check here instead of in `wait()` so we can identify when frames are received late. // Otherwise, chained `wait()` calls would cause a false-positive during CPU starvation. - const floor = this.#out.buffer.peek(); - const sleep = Time.Milli.add(Time.Milli.sub(currentRef, ref), floor); + const delay = this.#out.delay.peek(); + const sleep = Time.Milli.add(Time.Milli.sub(currentRef, ref), delay); if (sleep < 0) { const entry = this.#late.get(label); if (entry) { @@ -231,15 +209,16 @@ export class Sync { } } - // Frame isn't earlier than the anchor: it can't lower latency, so keep the reference. + // Frame isn't earlier than the anchor: it can't add lookahead, so keep the reference. if (ref >= currentRef) return; - // Frame is earlier (more lookahead). `sleep` is the latency keeping the anchor would impose. - const cap = this.#latencyCap(); + // Frame is earlier (more lookahead). `sleep` is how far ahead of the playhead keeping the + // anchor would put it. + const cap = this.#out.maxAge.peek(); if (sleep <= cap) return; // within budget: let the buffer grow instead of skipping ahead - // Over the cap: re-anchor down so the resulting latency is exactly the cap. - this.#setReference(Time.Milli.add(ref, Time.Milli.sub(cap, floor))); + // Over the cap: re-anchor down so the resulting lookahead is exactly the cap. + this.#setReference(Time.Milli.add(ref, Time.Milli.sub(cap, delay))); } #setReference(ref: Time.Milli): void { @@ -263,14 +242,14 @@ export class Sync { now(): Time.Milli | undefined { const reference = this.#out.reference.peek(); if (reference === undefined) return undefined; - return Time.Milli.sub(Time.Milli.sub(Time.Milli.now(), reference), this.#out.buffer.peek()); + return Time.Milli.sub(Time.Milli.sub(Time.Milli.now(), reference), this.#out.delay.peek()); } // Sleep until it's time to render this frame. async wait(timestamp: Time.Milli): Promise { - // A zero buffer still sleeps: the sleep comes from the reference, which holds an early frame + // A zero delay still sleeps: the sleep comes from the reference, which holds an early frame // until its timestamp comes up. "instant" is the only thing that skips the wait itself. - if (this.in.latency.peek() === "instant") return; + if (this.in.delay.peek() === "instant") return; const reference = this.#out.reference.peek(); if (reference === undefined) { @@ -279,7 +258,7 @@ export class Sync { for (;;) { // Switching to "instant" resolves `#update`, so frames parked here wake and leave. - if (this.in.latency.peek() === "instant") return; + if (this.in.delay.peek() === "instant") return; // Sleep until it's time to decode the next frame. // NOTE: This function runs in parallel for each frame. @@ -289,7 +268,7 @@ export class Sync { const currentRef = this.#out.reference.peek(); if (currentRef === undefined) return; - const sleep = Time.Milli.add(Time.Milli.sub(currentRef, ref), this.#out.buffer.peek()); + const sleep = Time.Milli.add(Time.Milli.sub(currentRef, ref), this.#out.delay.peek()); if (sleep <= 0) return; // Skip setTimeout for small sleeps; the timer resolution (~4ms) would overshoot. diff --git a/js/watch/src/text/renderer.ts b/js/watch/src/text/renderer.ts index 02e71bbedb7..de39991d537 100644 --- a/js/watch/src/text/renderer.ts +++ b/js/watch/src/text/renderer.ts @@ -250,7 +250,7 @@ export class Renderer { broadcast: active, track, priority: Catalog.PRIORITY.text, - latency: this.sync.out.maxBuffer, + maxAge: this.sync.out.maxAge, }); const store: CueStore = { cues: [], regions: new Map(), clears: [] }; const commit = () => renderer.changeTrack({ cues: [...store.cues], regions: [...store.regions.values()] }); diff --git a/js/watch/src/ui/components/buffer-control.ts b/js/watch/src/ui/components/buffer-control.ts index cd082c6aed4..21c79d9cf7e 100644 --- a/js/watch/src/ui/components/buffer-control.ts +++ b/js/watch/src/ui/components/buffer-control.ts @@ -141,7 +141,7 @@ export function bufferControl(parent: Effect, watch: MoqWatch, max: Moq.Time.Mil const ms = (x / trackWidth) * max; const snapped = Moq.Time.Milli(Math.round(ms / RANGE_STEP) * RANGE_STEP); const clamped = Moq.Time.Milli(Math.max(MIN_RANGE, Math.min(max, snapped))); - watch.latencyMin = clamped; + watch.delay = clamped; }; const interact = () => { @@ -181,7 +181,7 @@ export function bufferControl(parent: Effect, watch: MoqWatch, max: Moq.Time.Mil interact(); const current = watch.sync.out.jitter.peek(); const value = Moq.Time.Milli(Math.max(MIN_RANGE, Math.min(max, current + delta))); - watch.latencyMin = value; + watch.delay = value; }); const draw = () => { diff --git a/js/watch/src/ui/components/latency.ts b/js/watch/src/ui/components/latency.ts index 81b1359422a..57428989c6d 100644 --- a/js/watch/src/ui/components/latency.ts +++ b/js/watch/src/ui/components/latency.ts @@ -2,14 +2,13 @@ import * as Moq from "@moq/net"; import type { Effect } from "@moq/signals"; import * as DOM from "@moq/signals/dom"; import type MoqWatch from "../../element"; -import { latencyBounds } from "../../sync"; import { formatMillis } from "../format"; import { bufferControl } from "./buffer-control"; -type Preset = { label: string; value: "real-time" | number }; +type Preset = { label: string; value: "auto" | number }; const PRESETS: Preset[] = [ - { label: "Real-time", value: "real-time" }, + { label: "Auto", value: "auto" }, { label: "100ms", value: 100 }, { label: "250ms", value: 250 }, { label: "500ms", value: 500 }, @@ -17,7 +16,7 @@ const PRESETS: Preset[] = [ { label: "2s", value: 2000 }, ]; -/** The Latency tab: choose a buffer target and watch the live buffer timeline. */ +/** The Latency tab: choose a playback delay and watch the live buffer timeline. */ export function latencyTab(parent: Effect, watch: MoqWatch): HTMLElement { const container = DOM.create("div", { className: "tab-body latency" }); @@ -26,16 +25,16 @@ export function latencyTab(parent: Effect, watch: MoqWatch): HTMLElement { const buttons = PRESETS.map((preset) => { const chip = DOM.create("button", { className: "chip", type: "button" }, preset.label); parent.event(chip, "click", () => { - watch.latencyMin = preset.value === "real-time" ? "real-time" : Moq.Time.Milli(preset.value); + watch.delay = preset.value === "auto" ? "auto" : Moq.Time.Milli(preset.value); }); chips.appendChild(chip); return { preset, chip }; }); parent.run((effect) => { - const mode = latencyBounds(effect.get(watch.controls.latency)).min; + const mode = effect.get(watch.controls.delay); for (const { preset, chip } of buttons) { - const active = preset.value === "real-time" ? mode === "real-time" : mode === preset.value; + const active = preset.value === "auto" ? mode === "auto" : mode === preset.value; chip.classList.toggle("chip--active", active); } }); @@ -54,17 +53,17 @@ export function latencyTab(parent: Effect, watch: MoqWatch): HTMLElement { readout.append(jitterStat, bufferStat); parent.run((effect) => { - const mode = latencyBounds(effect.get(watch.controls.latency)).min; + const mode = effect.get(watch.controls.delay); const jitter = effect.get(watch.sync.out.jitter); - const total = effect.get(watch.sync.out.buffer); - jitterVal.textContent = `${formatMillis(jitter)}${mode === "real-time" ? " (auto)" : ""}`; + const total = effect.get(watch.sync.out.delay); + jitterVal.textContent = `${formatMillis(jitter)}${mode === "auto" ? " (auto)" : ""}`; bufferVal.textContent = formatMillis(total); }); const hint = DOM.create( "div", { className: "tab-hint" }, - "A larger buffer smooths over network jitter at the cost of latency. Real-time tracks the connection RTT automatically. Drag the timeline to fine-tune.", + "A larger delay smooths over network jitter at the cost of latency. Auto tracks the connection RTT. Drag the timeline to fine-tune.", ); container.append(chips, timeline, readout, hint); diff --git a/js/watch/src/ui/components/live-badge.ts b/js/watch/src/ui/components/live-badge.ts index 77b2014ce3a..55fc59ab3fd 100644 --- a/js/watch/src/ui/components/live-badge.ts +++ b/js/watch/src/ui/components/live-badge.ts @@ -54,7 +54,7 @@ export function liveBadge(parent: Effect, watch: MoqWatch, state: UiState): HTML parent.run((effect) => { // Show the total added latency (jitter buffer + codec frame overhead), // which is what the viewer actually experiences. - const total = effect.get(watch.sync.out.buffer); + const total = effect.get(watch.sync.out.delay); latency.textContent = `+${formatMillis(total)} latency`; }); diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 01a7d503ded..684ae821b24 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -301,7 +301,7 @@ class DecoderTrack { broadcast: this.broadcast, track: this.track, priority: Catalog.PRIORITY.video, - latency: this.sync.out.maxBuffer, + maxAge: this.sync.out.maxAge, }); const decoder = new VideoDecoder({ @@ -377,7 +377,7 @@ class DecoderTrack { // Create consumer that reorders groups/frames up to the provided latency. const consumer = new Container.Consumer(sub, { format, - latency: this.sync.out.maxBuffer, + maxAge: this.sync.out.maxAge, }); effect.cleanup(() => consumer.close()); @@ -453,7 +453,7 @@ class DecoderTrack { const consumer = new Container.Consumer(sub, { format: new Container.Cmaf.Format(init), - latency: this.sync.out.maxBuffer, + maxAge: this.sync.out.maxAge, }); effect.cleanup(() => consumer.close()); diff --git a/quest/m2/2829-moq-export-ts-the-audio-video-interleave-is-decided-by.md b/quest/m2/2829-moq-export-ts-the-audio-video-interleave-is-decided-by.md index bceabfde65c..d0548f84cba 100644 --- a/quest/m2/2829-moq-export-ts-the-audio-video-interleave-is-decided-by.md +++ b/quest/m2/2829-moq-export-ts-the-audio-video-interleave-is-decided-by.md @@ -95,7 +95,7 @@ track cannot hold the output: after a small window, emit what is in hand, as tod That makes the ordering a function of the media wherever the window is not exceeded, which is the condition under which two legs can be a redundant pair. It would fit naturally alongside the existing -`--latency-max`. +`--max-age`. I am happy to put this behind a flag if a deterministic-rendering mode is preferable to changing the default. diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index ec0a9252425..efa5f56e32c 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -633,7 +633,11 @@ pub struct Import { /// advertise segments that are still fetchable; lower it when nothing reads history and the /// memory matters. Media tracks only -- the catalog and timeline are read at the live edge, /// which is retained unconditionally. - #[usage(long = "latency-max")] + // `--latency-max` was the released spelling and keeps parsing. A field-level `alias` is + // already hidden (`visible_alias` is the advertised form), so the dead name stays out of + // `--help`. An implementation comment rather than a doc one for the same reason: `///` + // here *is* the help text. + #[usage(long, alias = "latency-max")] pub max_age: Option, /// The single source feeding the Origin. @@ -773,8 +777,8 @@ impl ExportSink { #[derive(usage::Args, Clone)] #[usage(unknown_flags = "error", args_override_self = false)] pub struct Container { - /// Maximum latency before skipping a stalled group (e.g. `500ms`, `1s`). - #[usage(long = "latency-max", default = "500ms")] + /// How stale a group may get before it is skipped (e.g. `500ms`, `1s`). + #[usage(long, alias = "latency-max", default = "500ms")] pub max_age: moq_tokio::Duration, } @@ -1249,28 +1253,39 @@ mod tests { assert_eq!(import.max_age, None); // It sits on the parent `import`, so it parses ahead of any source, gateway or not. - let cli = Invocation::try_parse_from(["moq", "import", "--latency-max", "5s", "ts"]).unwrap(); + let cli = Invocation::try_parse_from(["moq", "import", "--max-age", "5s", "ts"]).unwrap(); let Command::Import(import) = &cli.stages[0] else { panic!("expected import") }; assert_eq!(import.max_age, Some(Duration::from_secs(5).into())); - let cli = Invocation::try_parse_from([ - "moq", - "import", - "--latency-max", - "5s", - "rtmp", - "--listen", - "127.0.0.1:1935", - ]) - .unwrap(); + let cli = + Invocation::try_parse_from(["moq", "import", "--max-age", "5s", "rtmp", "--listen", "127.0.0.1:1935"]) + .unwrap(); let Command::Import(import) = &cli.stages[0] else { panic!("expected import") }; assert_eq!(import.max_age, Some(Duration::from_secs(5).into())); } + /// The released spelling keeps parsing, so a script written against it still runs. + #[test] + fn latency_max_still_parses_as_max_age() { + let cli = Invocation::try_parse_from(["moq", "import", "--latency-max", "5s", "ts"]).unwrap(); + let Command::Import(import) = &cli.stages[0] else { + panic!("expected import") + }; + assert_eq!(import.max_age, Some(Duration::from_secs(5).into())); + + let cli = + Invocation::try_parse_from(["moq", "export", "--broadcast", "b", "ts", "--latency-max", "1s"]).unwrap(); + let Command::Export(export) = &cli.stages[0] else { + panic!("expected export") + }; + let (_, max_age, _) = export.sink.stdout().expect("ts writes to stdout"); + assert_eq!(max_age, Duration::from_secs(1)); + } + #[test] fn token_verb() { let cli = Invocation::try_parse_from(["moq", "token", "generate", "--algorithm", "ES256"]).unwrap(); diff --git a/rs/moq-cli/src/moq.rs b/rs/moq-cli/src/moq.rs index ca6dad06110..60df96247d4 100644 --- a/rs/moq-cli/src/moq.rs +++ b/rs/moq-cli/src/moq.rs @@ -20,7 +20,7 @@ pub struct ImportTarget { pub name: String, /// How long relays keep a non-latest group of the published media tracks fetchable - /// (`--latency-max`), or `None` for the publisher's own default. + /// (`--max-age`), or `None` for the publisher's own default. pub max_age: Option, } diff --git a/rs/moq-cli/src/play.rs b/rs/moq-cli/src/play.rs index 00bc32e3768..dff92ef1e76 100644 --- a/rs/moq-cli/src/play.rs +++ b/rs/moq-cli/src/play.rs @@ -51,8 +51,11 @@ pub struct Args { #[usage(long, value_enum)] pub catalog_format: Option, - /// Maximum media buffering before skipping a stalled group. - #[usage(long = "latency-max", default = "500ms")] + /// How stale a media group may get before it is skipped. + /// + /// A staleness budget, not a playout delay: it never holds the picture back, it caps how + /// long a late group is waited for. The presentation clock anchors to the speaker. + #[usage(long, alias = "latency-max", default = "500ms")] pub max_age: moq_tokio::Duration, /// Rendition selection by track name or codec. diff --git a/rs/moq-cli/src/rtmp.rs b/rs/moq-cli/src/rtmp.rs index b2ec96c58d5..04a31b71e37 100644 --- a/rs/moq-cli/src/rtmp.rs +++ b/rs/moq-cli/src/rtmp.rs @@ -37,9 +37,9 @@ pub struct ExportArgs { #[usage(flatten)] pub endpoint: Args, - /// Maximum age before skipping a stalled group. RTMP is unpaced, so this + /// How stale a group may get before it is skipped. RTMP is unpaced, so this /// bounds buffering, not the wire rate. - #[usage(long = "latency-max", default = "500ms")] + #[usage(long, alias = "latency-max", default = "500ms")] pub max_age: moq_tokio::Duration, } diff --git a/rs/moq-mux/src/pace.rs b/rs/moq-mux/src/pace.rs index 777a903a6bc..e01c613dccb 100644 --- a/rs/moq-mux/src/pace.rs +++ b/rs/moq-mux/src/pace.rs @@ -169,7 +169,7 @@ mod tests { } /// Regression: the lead comparison must not construct `now + lead`, which - /// panics on a large but valid `Duration` (`--latency-max` is unbounded). + /// panics on a large but valid `Duration` (`--max-age` is unbounded). #[test] fn huge_lead_does_not_overflow() { let start = Instant::now(); diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index 2739877c213..0b344f2f973 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -63,7 +63,7 @@ pub struct Frame { /// /// A fill stamps the group's cache access once for the whole batch, which bounds /// frames rather than elapsed time. A reader that may take longer than the track's -/// `latency_max` to work through one batch calls +/// `max_age` to work through one batch calls /// [`group::Consumer::keep_alive`] between frames, or the rest of the group is /// expired out from under it. #[derive(Debug, Default)] diff --git a/skills/moq/SKILL.md b/skills/moq/SKILL.md index 0c83fbe5065..fd52b76a1fe 100644 --- a/skills/moq/SKILL.md +++ b/skills/moq/SKILL.md @@ -28,7 +28,7 @@ Everything below builds on these layers. **Conferencing (Zoom-style)**. Browser capture and playback with `@moq/publish` + `@moq/watch`; each participant is a broadcast, discovered via announcements. Bridge existing WebRTC clients with the WHIP/WHEP gateway (`rs/moq-rtc`). Why MoQ over WebRTC: https://doc.moq.dev/concept/use-case/conferencing -**Voice/video AI agents**. Server-side media without a browser, straight from Rust: `moq-mux` publishes and decodes media containers (fMP4/CMAF, MPEG-TS, FLV), while `rs/moq-video` and `rs/moq-audio` capture/encode and decode/render with hardware codecs (VideoToolbox, D3D11, NVENC, VAAPI). Python bindings fit ML stacks, and the Pipecat voice-agent framework ships MoQ transport support (https://github.com/pipecat-ai/pipecat). TTS output written faster than real-time plays smoothly via `@moq/watch` buffered playback (`latency-max`). Background: https://moq.dev/blog/webrtc-is-the-problem and https://doc.moq.dev/concept/use-case/ai +**Voice/video AI agents**. Server-side media without a browser, straight from Rust: `moq-mux` publishes and decodes media containers (fMP4/CMAF, MPEG-TS, FLV), while `rs/moq-video` and `rs/moq-audio` capture/encode and decode/render with hardware codecs (VideoToolbox, D3D11, NVENC, VAAPI). Python bindings fit ML stacks, and the Pipecat voice-agent framework ships MoQ transport support (https://github.com/pipecat-ai/pipecat). TTS output written faster than real-time plays smoothly via `@moq/watch` buffered playback (`buffer`). Background: https://moq.dev/blog/webrtc-is-the-problem and https://doc.moq.dev/concept/use-case/ai **Real-time data, no media at all**. Chat, multiplayer game state, telemetry, collaborative apps: publish raw tracks with `@moq/net` or `moq-net`. Helpers: `moq-json` / `@moq/json` (JSON snapshots, merge-patch deltas, append logs) and `moq-flate` / `@moq/flate` (compression). A synchronized-clock example lives in `js/clock`. Same relays, same auth as media. Rule of thumb: anything that can be delta encoded or dropped when stale is a good fit for MoQ.