From 975ceea5abcdbef2a8efcc5b16d46956596cb908 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 23:14:29 -0700 Subject: [PATCH 01/13] chore(quest): claim quest/m2/stats/js.md Quest-Claim: f50c3ca09491bb8f From 6687905be255475b185233a2bb99fa41615ddc19 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 23:34:34 -0700 Subject: [PATCH 02/13] wip(js): publish stats and viewer feedback from the browser elements --- js/hang/src/index.ts | 2 + js/hang/src/report.ts | 63 ++++++ js/publish/src/audio/capture.test.ts | 1 + js/publish/src/audio/encoder.test.ts | 1 + js/publish/src/audio/encoder.ts | 12 +- js/publish/src/broadcast.test.ts | 104 +++++++++ js/publish/src/broadcast.ts | 97 ++++++++- js/publish/src/element.ts | 58 ++++- js/publish/src/rendition.ts | 23 ++ js/publish/src/ui/components/stats-tab.ts | 7 + js/publish/src/video/capture.test.ts | 4 +- js/publish/src/video/encoder-stall.test.ts | 1 + js/publish/src/video/encoder.test.ts | 10 + js/publish/src/video/encoder.ts | 23 +- js/watch/src/audio/decoder.test.ts | 6 +- js/watch/src/audio/decoder.ts | 109 ++++++++-- js/watch/src/echo.test.ts | 147 +++++++++++++ js/watch/src/echo.ts | 233 +++++++++++++++++++++ js/watch/src/element.ts | 31 +++ js/watch/src/feedback.ts | 106 ++++++++++ js/watch/src/player.ts | 21 +- js/watch/src/video/decoder.test.ts | 10 +- js/watch/src/video/decoder.ts | 109 ++++++++-- 23 files changed, 1130 insertions(+), 48 deletions(-) create mode 100644 js/hang/src/report.ts create mode 100644 js/watch/src/echo.test.ts create mode 100644 js/watch/src/echo.ts create mode 100644 js/watch/src/feedback.ts diff --git a/js/hang/src/index.ts b/js/hang/src/index.ts index e614f079cad..7191432bc63 100644 --- a/js/hang/src/index.ts +++ b/js/hang/src/index.ts @@ -19,5 +19,7 @@ export * as Echo from "./echo"; export * as Health from "./health"; /** A rendition's HLS segment records, each segment's first group and pts. */ export * as Hls from "./hls"; +/** The compressed snapshot track a stats or feedback report is written to. */ +export * as Report from "./report"; /** Publisher media and transport snapshot schemas. */ export * as Stats from "./stats"; diff --git a/js/hang/src/report.ts b/js/hang/src/report.ts new file mode 100644 index 00000000000..7623034c67c --- /dev/null +++ b/js/hang/src/report.ts @@ -0,0 +1,63 @@ +/** + * The track a media report rides on: a publisher's stats or a viewer's feedback. + * @module + */ + +import * as Json from "@moq/json"; +import type * as Moq from "@moq/net"; +import type * as z from "@zod/mini"; + +/** How often a reporter writes, in milliseconds: about once a second, as the hang draft asks. */ +export const INTERVAL = 1000; + +/** The report track's priority: below every media track, so a report never delays the media it describes. */ +export const PRIORITY = -128; + +// Deltas compress against the snapshot in their group, and a joiner asks for a fresh group once +// they outweigh eight snapshots. Matches the Rust CLI's report tracks. +const REFRESH = 8; + +/** + * One compressed snapshot track, written only while someone subscribes, so an unobserved report + * never leaves the process. + */ +export class Writer { + /** The report track. */ + readonly track: Moq.Track.Producer; + + #producer: Json.Snapshot.Producer; + #closed = false; + + /** Create `name` on `broadcast`, validating each report against `schema` before it is written. */ + constructor(broadcast: Moq.Broadcast.Producer, name: string, schema?: z.ZodMiniType) { + this.track = broadcast.createTrack(name, { priority: PRIORITY, compress: true, refresh: REFRESH }); + this.#producer = new Json.Snapshot.Producer({ track: this.track, schema }); + } + + /** Whether anyone subscribes now, which is when {@link update} writes. Observe `track.demand().wanted` to follow it. */ + get wanted(): boolean { + return this.track.demand().wanted.peek() !== undefined; + } + + /** + * Publish `value` when someone subscribes; an unchanged value writes nothing. A track that refuses + * a write would refuse every later one, so it is aborted with the cause, which its subscribers read. + */ + update(value: T): void { + if (this.#closed || !this.wanted) return; + try { + this.#producer.update({ value }); + } catch (err) { + console.warn("a report track failed; closing it", err); + this.#closed = true; + this.track.abort(err instanceof Error ? err : new Error(String(err))); + } + } + + /** End the track cleanly, keeping the last report for a late subscriber. Idempotent. */ + finish(): void { + if (this.#closed) return; + this.#closed = true; + this.#producer.finish(); + } +} diff --git a/js/publish/src/audio/capture.test.ts b/js/publish/src/audio/capture.test.ts index e2fa6760c7c..2486ff5b683 100644 --- a/js/publish/src/audio/capture.test.ts +++ b/js/publish/src/audio/capture.test.ts @@ -559,6 +559,7 @@ test("a failed encoder stays failed until the capture source changes", async () const track = new Moq.Track.Producer("audio").accept({ timescale: Moq.Time.Timescale.MILLI }); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => {}, }; diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index 879d8684679..aa43b64660e 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -282,6 +282,7 @@ async function setup(order = new Order(), codec?: Codec, groupDuration?: Milli) const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); diff --git a/js/publish/src/audio/encoder.ts b/js/publish/src/audio/encoder.ts index 4a10e868fb9..2af1a6c4fb1 100644 --- a/js/publish/src/audio/encoder.ts +++ b/js/publish/src/audio/encoder.ts @@ -14,6 +14,7 @@ import { Signal, } from "@moq/signals"; import type { Broadcast } from "../broadcast"; +import type { RenditionStats } from "../rendition"; import { errors } from "../internal"; import { Estimator, type Order } from "../order"; import type { AudioFrame, Capture, Format } from "./capture"; @@ -82,6 +83,9 @@ export interface Stats { /** Total bytes encoded while serving. Monotonic; diff over an interval for an upload bitrate. */ bytes: number; + + /** The bitrate the encoder targets now, in bits per second, or undefined while none is resolved. */ + bitrate?: number; } /** Signals the encoder reads. */ @@ -127,7 +131,7 @@ export type EncoderOutput = { root: Signal; // True when a subscriber is attached and we're encoding. active: Signal; - // Cumulative output totals (frames, bytes) measured while serving. + // Cumulative output totals (frames, bytes) measured while serving, and the target bitrate. stats: Signal; }; @@ -291,6 +295,10 @@ export class Encoder { this.#signals.run(this.#runSettingsRecovery.bind(this)); this.#signals.run(this.#runCaptureRecovery.bind(this)); this.#signals.run(this.#runRegister.bind(this)); + this.#signals.run((effect) => { + const bitrate = effect.get(this.#config)?.encoder.bitrate; + this.#out.stats.update((stats) => ({ ...stats, bitrate })); + }); } // Pump PCM off the capture into whatever is currently publishing, applying the volume knobs on @@ -387,6 +395,7 @@ export class Encoder { // Publish the resolved config; undefined (no capture) drops it from the catalog. effect.proxy(rendition.config, this.out.catalog); + effect.proxy(rendition.stats, this.out.stats); // The pipeline outlives any one subscription: it is built as soon as capture runs and // #encode reads the live producer per frame rather than subscribing to it. Rebuilding on a @@ -644,6 +653,7 @@ export class Encoder { } this.#out.stats.update((stats) => ({ + ...stats, frames: stats.frames + 1, bytes: stats.bytes + frame.byteLength, })); diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index 82c58d1d0a9..5e96b858dc2 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -1,5 +1,6 @@ import { expect, test } from "bun:test"; import { Manual, Milli, Nano } from "@moq/clock"; +import { Stats } from "@moq/hang"; import * as Catalog from "@moq/hang/catalog"; import * as Json from "@moq/json"; import { Origin, Path, Track } from "@moq/net"; @@ -719,3 +720,106 @@ test("identity changes before the first announce keep the catalog ID as the trac broadcast.close(); }); + +test("stats names a track in the catalog and reports each listed rendition while subscribed", async () => { + const clock = new Manual(); + const installed = clock.install(); + const stats = new Signal(false); + const probe = new Signal({ rtt: Milli(12.7) }); + const broadcast = new Broadcast({ + enabled: true, + origin: new Origin.Producer(), + name: Path.from("test.hang"), + stats, + probe, + }); + try { + const video = broadcast.video("video"); + video.config.set(videoConfig); + video.stats.set({ frames: 3, bytes: 300, keyframes: 1, skipped: 2, bitrate: 1_000_000 }); + // A rendition without a config is not in the catalog, so it is not reported either. + broadcast.audio("audio").stats.set({ frames: 1 }); + await settle(); + expect((await readCatalog(broadcast))?.stats).toBeUndefined(); + + stats.set(true); + await settle(); + expect((await readCatalog(broadcast))?.stats).toEqual({ track: Broadcast.STATS_TRACK }); + + const net = broadcast.net.peek(); + if (!net) throw new Error("expected a network producer once connected"); + const subscriber = net.track(Broadcast.STATS_TRACK).subscribe(); + const consumer = new Json.Snapshot.Consumer({ track: subscriber, schema: Stats.SnapshotSchema }); + await settle(); + await clock.advance(Nano.fromMilli(Milli(1000))); + // Sub-millisecond durations are floored on the wire. + expect((await consumer.latest())?.value).toEqual({ + transport: { rtt: 12 }, + renditions: { video: { frames: 3, bytes: 300, keyframes: 1, skipped: 2, bitrate: 1_000_000 } }, + }); + subscriber.close(); + + stats.set(false); + await settle(); + expect((await readCatalog(broadcast))?.stats).toBeUndefined(); + } finally { + broadcast.close(); + installed.close(); + } +}); + +test("an unsubscribed stats track writes nothing", async () => { + const clock = new Manual(); + const installed = clock.install(); + const broadcast = new Broadcast({ + enabled: true, + origin: new Origin.Producer(), + name: Path.from("test.hang"), + stats: true, + }); + try { + const video = broadcast.video("video"); + video.config.set(videoConfig); + video.stats.set({ frames: 1 }); + await settle(); + await clock.advance(Nano.fromMilli(Milli(3000))); + + const net = broadcast.net.peek(); + if (!net) throw new Error("expected a network producer once connected"); + const subscriber = net.track(Broadcast.STATS_TRACK).subscribe(); + await settle(); + await clock.advance(Nano.fromMilli(Milli(1000))); + // Nothing was written while nobody subscribed, so the first report opens the first group. + expect((await subscriber.recvGroup())?.sequence).toBe(0); + subscriber.close(); + } finally { + broadcast.close(); + installed.close(); + } +}); + +test("echo solicits feedback in the catalog unless it walks above the root", async () => { + const echo = new Signal(Path.normalizeRelative("viewers")); + const name = new Signal(Path.from("room/live.hang")); + const broadcast = new Broadcast({ enabled: true, name, echo }); + try { + await settle(); + expect((await readCatalog(broadcast))?.echo).toEqual({ path: "viewers" }); + + // From `room/live.hang`, `../../viewers` walks above the root, which every viewer refuses. + echo.set(Path.normalizeRelative("../../viewers")); + await settle(); + expect((await readCatalog(broadcast))?.echo).toBeUndefined(); + + // A deeper name brings the same path back within the root. + name.set(Path.from("org/room/live.hang")); + await settle(); + expect((await readCatalog(broadcast))?.echo).toEqual({ path: "../../viewers" }); + + echo.set(undefined); + await settle(); + expect((await readCatalog(broadcast))?.echo).toBeUndefined(); + } finally { + broadcast.close(); + } +}); diff --git a/js/publish/src/broadcast.ts b/js/publish/src/broadcast.ts index 1f835f1d9e9..7166b7ae102 100644 --- a/js/publish/src/broadcast.ts +++ b/js/publish/src/broadcast.ts @@ -1,4 +1,5 @@ -import { Milli } from "@moq/clock"; +import { Milli, Nano } from "@moq/clock"; +import { Report, Stats } from "@moq/hang"; import * as Catalog from "@moq/hang/catalog"; import * as Container from "@moq/hang/container"; import * as Json from "@moq/json"; @@ -8,7 +9,7 @@ import { rotateVideoDimensions } from "@moq/video"; import { CatalogProducer } from "./catalog"; import { errors } from "./internal"; import { Order } from "./order"; -import { type Kind, Rendition } from "./rendition"; +import { type Kind, Rendition, type RenditionStats } from "./rendition"; // The refresh ratio video tracks advertise: a joiner forces a keyframe once a group's deltas // outweigh twice its keyframe. Matches moq-video's capture `REFRESH`; see it for the measurements. @@ -58,6 +59,27 @@ export type BroadcastInput = { * so changing this publishes a new network broadcast. */ maxAge: Getter; + + /** + * Whether to publish a stats track and name it in the catalog's `stats` section. Defaults to + * false. The track reports each rendition's {@link Rendition.stats} under its ID, plus the + * connection's PROBE round-trip time, about once a second while someone subscribes. + */ + stats: Getter; + + /** + * The connection's PROBE estimates, whose round-trip time the stats track reports. Observed only + * while the stats track has a subscriber, since observing it asks the peer for PROBE updates. + */ + probe: Getter; + + /** + * Where viewers may publish feedback, relative to the broadcast as a rendition's `broadcast` + * reference is: from `room/live`, `viewers` is `room/viewers`. Sets the catalog's `echo` section, + * which solicits it; undefined (the default) solicits none. A path that walks above the root from + * the broadcast name is left out of the catalog with a warning, since every viewer would refuse it. + */ + echo: Getter; }; /** @@ -72,6 +94,9 @@ export class Broadcast { /** The catalog track name served to subscribers. */ static readonly CATALOG_TRACK = Catalog.TRACK; + /** The stats track name, named in the catalog's `stats` section while {@link BroadcastInput.stats} is set. */ + static readonly STATS_TRACK = "stats.json"; + /** The wired inputs, read-only. */ readonly in: Readonlys; @@ -139,9 +164,13 @@ export class Broadcast { flip: getter(props?.flip ?? false), rotation: getter(props?.rotation ?? 0), maxAge: getter(props?.maxAge), + stats: getter(props?.stats ?? false), + probe: getter(props?.probe), + echo: getter(props?.echo), }; this.#signals.run(this.#runCatalog.bind(this)); + this.#signals.run(this.#runEcho.bind(this)); this.#signals.run(this.#run.bind(this)); } @@ -291,6 +320,61 @@ export class Broadcast { if (Object.keys(renamed).length > 0) this.#names.update((names) => ({ ...names, ...renamed })); } + // Solicit feedback in the catalog's `echo` section. A path above the root names no broadcast, and a + // viewer refuses the whole catalog for it, so it is left out instead. + #runEcho(effect: Effect) { + const path = effect.get(this.in.echo); + if (path === undefined) return; + const name = effect.get(this.in.name); + if (Moq.Path.tryResolve(name, path) === undefined) { + console.warn(`not soliciting feedback: echo path ${JSON.stringify(path)} walks above the root from ${name}`); + return; + } + this.catalog.mutate((catalog) => { + catalog.echo = { path }; + }); + effect.cleanup(() => + this.catalog.mutate((catalog) => { + delete catalog.echo; + }), + ); + } + + // Name the stats track in the catalog and write a report every interval while someone subscribes. + // The track lives as long as the network broadcast, so disabling stats only stops reporting. + #runStats(effect: Effect, report: () => Report.Writer) { + if (!effect.get(this.in.stats)) return; + const writer = report(); + + this.catalog.mutate((catalog) => { + catalog.stats = { track: Broadcast.STATS_TRACK }; + }); + effect.cleanup(() => + this.catalog.mutate((catalog) => { + delete catalog.stats; + }), + ); + + // Observing the probe asks the peer for PROBE updates, so only do it while someone reads them. + const watched = effect.computed((demand) => demand.get(writer.track.demand().wanted) !== undefined); + effect.run((demand) => { + if (demand.get(watched)) demand.get(this.in.probe); + }); + + effect.interval(() => writer.update(this.#stats() as Stats.Snapshot), Nano.fromMilli(Milli(Report.INTERVAL))); + } + + // What each listed rendition has sent, keyed by its catalog ID, and the connection's round-trip time. + #stats(): { transport?: { rtt: number }; renditions: Record } { + const renditions: Record = {}; + for (const rendition of Object.values(this.#renditions.peek())) { + const stats = rendition.stats.peek(); + if (stats && rendition.config.peek() !== undefined) renditions[rendition.name] = stats; + } + const rtt = this.in.probe.peek()?.rtt; + return rtt === undefined ? { renditions } : { transport: { rtt: Math.floor(rtt) }, renditions }; + } + // The next unused `/` track name in the current network broadcast. This publisher owns the // namespace and reserves `/` for the rendition (see `net`), so skipping every name it has // served, registered, or listed in the catalog (including an application's own sections) is @@ -370,6 +454,15 @@ export class Broadcast { if (this.#kinds === kinds) this.#kinds = new Map(); }); + // Created on first use and kept with the broadcast, like a rendition's track. + let stats: Report.Writer | undefined; + const report = () => { + stats ??= new Report.Writer(broadcast, Broadcast.STATS_TRACK, Stats.SnapshotSchema); + return stats; + }; + effect.cleanup(() => stats?.finish()); + effect.run((inner) => this.#runStats(inner, report)); + let serving = false; effect.run((inner) => { if (!inner.get(this.in.announce)) { diff --git a/js/publish/src/element.ts b/js/publish/src/element.ts index f02e774fcc2..10d6daead9b 100644 --- a/js/publish/src/element.ts +++ b/js/publish/src/element.ts @@ -39,7 +39,19 @@ function parseVersions(value: string | null): string[] | undefined { } /** The attributes the element observes. */ -const OBSERVED = ["url", "versions", "name", "muted", "invisible", "source", "preview", "backend", "announce"] as const; +const OBSERVED = [ + "url", + "versions", + "name", + "muted", + "invisible", + "source", + "preview", + "backend", + "announce", + "stats", + "echo-path", +] as const; /** The built-in capture sources selectable via the `source` attribute. */ export type SourceType = "camera" | "screen" | "file"; @@ -83,6 +95,11 @@ function parsePreview(value: string | null): Preview.Mode { throw invalidAttribute("preview", value, '"encoded", "source", or "none"'); } +// Parse the `echo-path` attribute: a path relative to the broadcast, or undefined when absent. +function parseEchoPath(value: string | null): Moq.Path.Relative | undefined { + return value === null ? undefined : Moq.Path.normalizeRelative(value); +} + function parseBackend(value: string | null): Preview.Backend { if (value === null) return "auto"; const trimmed = value.trim(); @@ -111,6 +128,10 @@ export default class MoqPublish extends HTMLElement { // When to advertise the broadcast: always, or only once a source is live. Undefined while the // `announce` attribute is invalid, which never announces. announce: new Signal("source"), + // Whether to publish a stats track named in the catalog. + stats: new Signal(false), + // Where viewers may publish feedback, relative to the broadcast, or undefined to solicit none. + echoPath: new Signal(undefined), }; /** @@ -223,6 +244,9 @@ export default class MoqPublish extends HTMLElement { display: this.#capture.out.display, flip: this.#flip, rotation: this.#capture.out.rotation, + stats: this.controls.stats, + probe: this.connection.probe, + echo: this.controls.echoPath, }); this.signals.cleanup(() => this.broadcast.close()); @@ -342,6 +366,8 @@ export default class MoqPublish extends HTMLElement { this.signals.run((effect) => this.#reflect(effect, "preview", effect.get(this.controls.preview))); this.signals.run((effect) => this.#reflect(effect, "backend", effect.get(this.controls.backend))); this.signals.run((effect) => this.#reflect(effect, "announce", effect.get(this.controls.announce))); + this.signals.run((effect) => this.#reflect(effect, "stats", effect.get(this.controls.stats) ? "" : undefined)); + this.signals.run((effect) => this.#reflect(effect, "echo-path", effect.get(this.controls.echoPath))); this.signals.run(this.#runSource.bind(this)); } @@ -371,6 +397,8 @@ export default class MoqPublish extends HTMLElement { else if (name === "invisible") this.invisible = parseBoolean(newValue, false); else if (name === "preview") this.preview = parsePreview(newValue); else if (name === "backend") this.backend = parseBackend(newValue); + else if (name === "stats") this.stats = parseBoolean(newValue, false); + else if (name === "echo-path") this.echoPath = parseEchoPath(newValue); else { const exhaustive: never = name; throw new Error(`Invalid attribute: ${exhaustive}`); @@ -588,6 +616,34 @@ export default class MoqPublish extends HTMLElement { this.controls.announce.set(parseAnnounce(value)); this.#accept("announce"); } + + /** + * Whether to publish a stats track, mirrored by the `stats` attribute. The catalog names it in its + * `stats` section, and it reports what each rendition has sent plus the connection's PROBE + * round-trip time, about once a second while someone subscribes. + */ + get stats(): boolean { + return this.controls.stats.peek(); + } + + set stats(value: boolean) { + this.controls.stats.set(value); + this.#accept("stats"); + } + + /** + * Where viewers may publish feedback, relative to the broadcast as a rendition reference is (from + * `room/live`, `viewers` is `room/viewers`), mirrored by the `echo-path` attribute. Sets the + * catalog's `echo` section, so a `` publishes its feedback there. Undefined solicits none. + */ + get echoPath(): Moq.Path.Relative | undefined { + return this.controls.echoPath.peek(); + } + + set echoPath(value: string | undefined) { + this.controls.echoPath.set(parseEchoPath(value ?? null)); + this.#accept("echo-path"); + } } customElements.define("moq-publish", MoqPublish); diff --git a/js/publish/src/rendition.ts b/js/publish/src/rendition.ts index 0fe646a6038..641ef60cf52 100644 --- a/js/publish/src/rendition.ts +++ b/js/publish/src/rendition.ts @@ -4,6 +4,23 @@ import { type Getter, Signal } from "@moq/signals"; /** The media kind of a rendition, selecting its catalog section (`video`, `audio`, or `text`). */ export type Kind = "video" | "audio" | "text"; +/** + * What a rendition's producer has sent, as the broadcast's stats track reports it. Counters are + * cumulative and a missing one means zero; `bitrate` is a gauge, absent when unknown. + */ +export interface RenditionStats { + /** Media frames sent. */ + frames?: number; + /** Media payload bytes sent. */ + bytes?: number; + /** Keyframes sent. */ + keyframes?: number; + /** Frames skipped before sending, such as those an overloaded encoder had no room for. */ + skipped?: number; + /** The latest target encoder bitrate in bits per second. */ + bitrate?: number; +} + /** * A registered rendition track on a {@link Broadcast}: the catalog slot plus the demand-gated track. * @@ -27,6 +44,12 @@ export class Rendition { */ readonly config = new Signal(undefined); + /** + * What the producer has sent under this rendition, written by the producer and reported under + * its ID on the broadcast's stats track. `undefined` leaves the rendition out of the report. + */ + readonly stats = new Signal(undefined); + /** * The live track producer while a subscriber is attached, `undefined` otherwise. * Producers should encode only while this is set (the demand gate), and only media matching diff --git a/js/publish/src/ui/components/stats-tab.ts b/js/publish/src/ui/components/stats-tab.ts index 9076acbf29d..cb24dcebe7f 100644 --- a/js/publish/src/ui/components/stats-tab.ts +++ b/js/publish/src/ui/components/stats-tab.ts @@ -48,6 +48,9 @@ export function statsTab(parent: Effect, publish: MoqPublish): HTMLElement { const videoCard = card("video", "Video", videoIcon); const vRes = line(videoCard.grid, "Resolution"); const vCodec = line(videoCard.grid, "Codec"); + // The same encoder stats the broadcast's stats track reports. + const vTarget = line(videoCard.grid, "Target"); + const vSkipped = line(videoCard.grid, "Skipped"); const vBitrateGraph = graph(parent, "Bitrate", { color: "#a855f7", format: formatBitrate }); const vFpsGraph = graph(parent, "Frame rate", { color: "#facc15", format: formatFps }); videoCard.el.append(vBitrateGraph.el, vFpsGraph.el); @@ -142,6 +145,10 @@ export function statsTab(parent: Effect, publish: MoqPublish): HTMLElement { prevFrames = frames; vFpsGraph.push(elapsed > 0 && frameDelta > 0 ? frameDelta / (elapsed / 1000) : undefined); + const stats = publish.video.out.stats.peek(); + vTarget.textContent = stats.bitrate !== undefined ? formatBitrate(stats.bitrate) : "—"; + vSkipped.textContent = `${stats.skipped}`; + const bytes = encoded(); const byteDelta = bytes - prevBytes; prevBytes = bytes; diff --git a/js/publish/src/video/capture.test.ts b/js/publish/src/video/capture.test.ts index a2dd356f559..83d183a64d3 100644 --- a/js/publish/src/video/capture.test.ts +++ b/js/publish/src/video/capture.test.ts @@ -434,7 +434,7 @@ test("an encoder resuming on a still source encodes a keyframe of the current pi const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI }); // No subscriber yet, so the encoder idles while the source sends its only frame. const live = new Signal(undefined); - const rendition = { config: new Signal(undefined), track: live, close: () => {} }; + const rendition = { config: new Signal(undefined), stats: new Signal(undefined), track: live, close: () => {} }; const encoder = new Encoder("video", { enabled: true, broadcast: { video: () => rendition, order: new Order() } as never, @@ -541,7 +541,7 @@ test("an encoder torn down while a frame is in flight closes that frame", async const capture = new Capture({ source: input.source }); const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI }); const live = new Signal(undefined); - const rendition = { config: new Signal(undefined), track: live, close: () => {} }; + const rendition = { config: new Signal(undefined), stats: new Signal(undefined), track: live, close: () => {} }; const encoder = new Encoder("video", { enabled: true, broadcast: { video: () => rendition, order: new Order() } as never, diff --git a/js/publish/src/video/encoder-stall.test.ts b/js/publish/src/video/encoder-stall.test.ts index 8441cfb25f5..94533e1ff1a 100644 --- a/js/publish/src/video/encoder-stall.test.ts +++ b/js/publish/src/video/encoder-stall.test.ts @@ -111,6 +111,7 @@ test("a slower-than-realtime encoder drops input instead of ratcheting catalog l const audio = new Estimator(); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index cd809ecd4f4..022da4c7322 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -115,6 +115,7 @@ test("encoding tracks encoder config in its child effect", async () => { const track = new Moq.Track.Producer("video/hd").accept({ timescale: Moq.Time.Timescale.MILLI }); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); @@ -156,6 +157,7 @@ test("a demand gap marks a discontinuity and leaves the broadcast-owned track op const live = new Signal(track); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: live, close: () => { track.finish(); @@ -210,6 +212,7 @@ test("a bandwidth estimate updates the bitrate without blanking the config or re const sub = track.subscribe(); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); @@ -295,6 +298,7 @@ test("every published config fits a probe for its own codec", async () => { const sub = track.subscribe(); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); @@ -628,6 +632,7 @@ test("disabling encodes one black keyframe and keeps the rendition with enabled: const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI }); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); @@ -795,6 +800,7 @@ test("the probe encodes with the frame rate and bitrate ceiling", async () => { const sub = track.subscribe(); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); @@ -971,6 +977,7 @@ async function recordKeyframes( const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MICRO, ...info }); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); @@ -1246,6 +1253,7 @@ test("a shrinking capture resizes in band below the advertised ceiling", async ( const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI }); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); @@ -1318,6 +1326,7 @@ test("the catalog bitrate and frame rate only rise", async () => { const sub = track.subscribe(); const rendition = { config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(track), close: () => { track.finish(); @@ -1374,6 +1383,7 @@ test("each broadcast keeps its own ceiling and maxima", async () => { using _videoEncoder = installFakeVideoEncoder(); const rendition = () => ({ config: new Signal(undefined), + stats: new Signal(undefined), track: new Signal(undefined), close: () => {}, }); diff --git a/js/publish/src/video/encoder.ts b/js/publish/src/video/encoder.ts index 22fb12cb899..f6779b47fa8 100644 --- a/js/publish/src/video/encoder.ts +++ b/js/publish/src/video/encoder.ts @@ -14,6 +14,7 @@ import { Signal, } from "@moq/signals"; import type { Broadcast } from "../broadcast"; +import type { RenditionStats } from "../rendition"; import { errors } from "../internal"; import { Estimator, type Order } from "../order"; import { hardwareReliable } from "../support/video"; @@ -30,6 +31,12 @@ export interface Stats { /** Total keyframes encoded while serving. Divide frames by this for the average GOP length. */ keyframes: number; + + /** Total captured frames skipped while serving because the encoder still had a frame queued. */ + skipped: number; + + /** The bitrate the encoder targets now, in bits per second, or undefined while none is resolved. */ + bitrate?: number; } // TODO support signals? @@ -111,7 +118,8 @@ export type EncoderOutput = { resolved: Signal; // True when a subscriber is attached and we're encoding. active: Signal; - // Cumulative output totals (frames, bytes, keyframes) measured while serving. + // Cumulative output totals (frames, bytes, keyframes, skipped) measured while serving, and the + // target bitrate. stats: Signal; }; @@ -151,7 +159,7 @@ export class Encoder { catalog: new Signal(undefined), resolved: new Signal(undefined), active: new Signal(false), - stats: new Signal({ frames: 0, bytes: 0, keyframes: 0 }), + stats: new Signal({ frames: 0, bytes: 0, keyframes: 0, skipped: 0 }), }; /** The derived outputs, read-only. */ readonly out = readonlys(this.#out); @@ -270,6 +278,10 @@ export class Encoder { this.#signals.run(this.#runSettingsRecovery.bind(this)); this.#signals.run(this.#runCaptureRecovery.bind(this)); this.#signals.run(this.#runRegister.bind(this)); + this.#signals.run((effect) => { + const bitrate = effect.get(this.#out.resolved)?.bitrate; + this.#out.stats.update((stats) => ({ ...stats, bitrate })); + }); } // What this rendition advertised on `broadcast`'s track. @@ -337,6 +349,7 @@ export class Encoder { // Publish the resolved catalog config; undefined (until one resolves) leaves it out of the catalog. effect.proxy(rendition.config, this.out.catalog); + effect.proxy(rendition.stats, this.out.stats); // Encode only while enabled and a subscriber is attached (the demand gate). effect.run((effect) => { @@ -414,6 +427,7 @@ export class Encoder { } this.#out.stats.update((stats) => ({ + ...stats, frames: stats.frames + 1, bytes: stats.bytes + frame.byteLength, keyframes: key ? stats.keyframes + 1 : stats.keyframes, @@ -479,7 +493,10 @@ export class Encoder { // A pending input means the codec is saturated. Keep capture live instead of // growing a stale encode queue whose lateness becomes permanent catalog delay. // Drop before answering a keyframe request or advancing the frame-rate cursor. - if (encoder.encodeQueueSize > 0) continue; + if (encoder.encodeQueueSize > 0) { + this.#out.stats.update((stats) => ({ ...stats, skipped: stats.skipped + 1 })); + continue; + } // This doesn't need to be reactive. const config = this.config.peek(); diff --git a/js/watch/src/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index f1450bbd4e3..edad04321ec 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -310,7 +310,7 @@ async function play(initial: Delay, buffered = false, cmaf = false) { // The catalog broadcast's instance, identified by its `closed` handle. const active = new Signal({ closed: {} }); const broadcast = new Signal({ - in: { enabled }, + in: { enabled, name: new Signal(Moq.Path.from("watched")) }, out: { catalog, active }, relativeBroadcast, } as unknown as Broadcast); @@ -976,7 +976,7 @@ async function livePlayback(burst: number) { let producer = new Moq.Broadcast.Producer(); const media = new Signal(producer.consume()); const broadcast = new Signal({ - in: { enabled: new Signal(true) }, + in: { enabled: new Signal(true), name: new Signal(Moq.Path.from("watched")) }, out: { catalog, active: new Signal({ closed: {} }) }, relativeBroadcast: (effect: Effect) => effect.get(media), } as unknown as Broadcast); @@ -1368,7 +1368,7 @@ it("a rejected audio support probe does not leave buffered video waiting on a pe const logged = spyOn(console, "warn").mockImplementation(() => {}); const source = new Source({ broadcast: { - in: { enabled: new Signal(true) }, + in: { enabled: new Signal(true), name: new Signal(Moq.Path.from("watched")) }, out: { catalog: new Signal({ audio: { diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 60c1f4f34ff..e9ffcb27ead 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -1,4 +1,4 @@ -import { Micro, Milli, type Second } from "@moq/clock"; +import { Micro, Milli, type Second, type Wall, wall } from "@moq/clock"; import * as Catalog from "@moq/hang/catalog"; import * as Container from "@moq/hang/container"; import * as Util from "@moq/hang/util"; @@ -16,6 +16,7 @@ import { import { Producer as ArrivalProducer, type Arrivals, gap } from "../arrivals"; import { hostedAssets } from "../assets"; import { base64ToBytes } from "../base64"; +import { type Counter, type Key, type Received, Tally } from "../feedback"; import { type Failure, failureMoved, nextMedia, subscribeMedia } from "../media"; import type { Sync } from "../sync"; import { AudioBuffer } from "./buffer"; @@ -87,8 +88,24 @@ export interface Stats { bytesReceived: number; /** How many times playback ran dry mid-stream; a rising count means the delay is too low. */ underruns: number; + /** Frames that arrived after their playout time. */ + late: number; + /** Renditions that failed to decode. */ + errors: number; + /** Times playback stalled waiting for audio once it had played. */ + stalls: number; + /** Total time spent in finished stalls. */ + stalled: Milli; + /** The newest received media timestamp and the wall time it arrived. */ + arrival?: { timestamp: Milli; wall: Wall }; } +// The running totals before anything is counted. +const EMPTY: Stats = { bytesReceived: 0, underruns: 0, late: 0, errors: 0, stalls: 0, stalled: Milli.zero }; + +// What a decode attempt reads, and where its counts go. +type Attempt = { config: DecoderConfig; failure: Signal; path: Moq.Path.Valid; key: Key }; + /** * Downloads audio from a track and emits it to an AudioContext. * @@ -158,6 +175,13 @@ export class Decoder { #signals = new Effect(); #failed?: Failure; + // What each rendition delivered, for the feedback a viewer reports. + #tally = new Tally(); + // The rendition decoding into the ring, which an underrun or a stall is counted against. + #playing?: Key; + // Whether audio played since the decoder was enabled, so the wait for the first is no stall. + #played = false; + // The catalog fields that require a replacement subscription or decoder. readonly #identity: Computed; @@ -210,6 +234,55 @@ export class Decoder { this.#signals.run(this.#runEnabled.bind(this)); this.#signals.run(this.#runLatency.bind(this)); this.#signals.run(this.#runDecoder.bind(this)); + this.#signals.run(this.#runStalls.bind(this)); + } + + /** + * What this decoder received and played of each rendition in the catalog of the broadcast at + * `path`, keyed by rendition ID, for the feedback a viewer reports. + * @internal + */ + feedback(path: Moq.Path.Valid): Record { + return this.#tally.report(path); + } + + // Count into a rendition's feedback and the decoder's running totals. + #count(key: Key | undefined, counts: Partial>, totals?: (stats: Stats) => Partial) { + if (key) this.#tally.count(key, counts); + if (totals) this.#out.stats.update((current) => ({ ...(current ?? EMPTY), ...totals(current ?? EMPTY) })); + } + + // Count a received frame and whether it arrived too late for playout. + #receive(key: Key, frame: Container.ReceivedFrame, timestamp: Milli, late: boolean): void { + const bytes = frame.payload.byteLength; + this.#tally.arrive(key, timestamp); + this.#count(key, { frames: 1, bytes, late: late ? 1 : 0 }, (stats) => ({ + bytesReceived: stats.bytesReceived + bytes, + late: stats.late + (late ? 1 : 0), + arrival: { timestamp, wall: wall() }, + })); + } + + // Count each stall once audio has played, and how long it lasted. A disabled decoder waits for + // audio again: resuming is a startup, not a stall. + #runStalls(effect: Effect): void { + if (!effect.get(this.in.enabled)) { + this.#played = false; + return; + } + if (!effect.get(this.#out.stalled)) { + this.#played = true; + return; + } + const key = this.#playing; + if (!this.#played || !key) return; + + const end = this.#tally.stall(key); + this.#count(undefined, {}, (stats) => ({ stalls: stats.stalls + 1 })); + effect.cleanup(() => { + const duration = end(); + this.#count(undefined, {}, (stats) => ({ stalled: Milli(stats.stalled + duration) })); + }); } // A group the relay expires is never observed, so a subscription cut to the target would cap the @@ -314,10 +387,7 @@ export class Decoder { const added = underruns - counted; counted = underruns; if (added <= 0) return; - this.#out.stats.update((stats) => ({ - bytesReceived: stats?.bytesReceived ?? 0, - underruns: (stats?.underruns ?? 0) + added, - })); + this.#count(this.#playing, { underruns: added }, (stats) => ({ underruns: stats.underruns + added })); }); effect.set(this.#out.root, worklet); @@ -404,10 +474,13 @@ export class Decoder { } // Closing this effect releases both its container reader and track subscription. const failure = new Signal(undefined); + const rendition: Key = { path: broadcast.in.name.peek(), id: track }; + this.#playing = rendition; let attempt: Effect | undefined; effect.run((inner) => { const error = inner.get(failure); if (!error) return; + this.#count(rendition, { errors: 1 }, (stats) => ({ errors: stats.errors + 1 })); this.#failed = { broadcast: broadcast.out.active.peek()?.closed, media: active.closed, @@ -452,7 +525,7 @@ export class Decoder { // A config the probe accepted can still fail to parse (a malformed init segment or Opus // header). Report it like a decode failure, which also retires the outgoing estimate. - const props = { config, failure, path: active.path }; + const props: Attempt = { config, failure, path: active.path, key: rendition }; spawnFatal(run, failure, async () => { if (config.container.kind === "cmaf") await this.#runCmafDecoder(run, sub, props); else this.#runLegacyDecoder(run, sub, props); @@ -463,7 +536,7 @@ export class Decoder { #runLegacyDecoder( effect: Effect, sub: Moq.Track.Subscriber, - { config, failure, path }: { config: DecoderConfig; failure: Signal; path: Moq.Path.Valid }, + { config, failure, path, key }: Attempt, ): void { const preSkip = config.codec === "opus" && config.description ? Util.Opus.preSkip(Util.Hex.toBytes(config.description)) : 0; @@ -479,7 +552,10 @@ export class Decoder { if (!loaded) return; // cancelled const decoder = new AudioDecoder({ - output: (data) => this.#emit(data), + output: (data) => { + this.#count(key, { decoded: 1 }); + this.#emit(data); + }, error: (error) => failure.set(error), }); effect.cleanup(() => { @@ -530,10 +606,7 @@ export class Decoder { const duration = packetDuration(config.codec, frame); if (duration !== undefined) this.#frame.set(duration); - this.#out.stats.update((stats) => ({ - bytesReceived: (stats?.bytesReceived ?? 0) + frame.payload.byteLength, - underruns: stats?.underruns ?? 0, - })); + this.#receive(key, frame, timestamp, late); if (!(await play(order.push(next)))) return; } @@ -543,7 +616,7 @@ export class Decoder { async #runCmafDecoder( effect: Effect, sub: Moq.Track.Subscriber, - { config, failure, path }: { config: DecoderConfig; failure: Signal; path: Moq.Path.Valid }, + { config, failure, path, key }: Attempt, ): Promise { if (config.container.kind !== "cmaf") return; // just to help typescript @@ -572,7 +645,10 @@ export class Decoder { if (!loaded) return; // cancelled const decoder = new AudioDecoder({ - output: (data) => this.#emit(data), + output: (data) => { + this.#count(key, { decoded: 1 }); + this.#emit(data); + }, error: (error) => failure.set(error), }); effect.cleanup(() => { @@ -616,10 +692,7 @@ export class Decoder { const duration = packetDuration(config.codec, frame); if (duration !== undefined) this.#frame.set(duration); - this.#out.stats.update((stats) => ({ - bytesReceived: (stats?.bytesReceived ?? 0) + frame.payload.byteLength, - underruns: stats?.underruns ?? 0, - })); + this.#receive(key, frame, timestamp, late); if (!(await play(order.push(next)))) return; } diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts new file mode 100644 index 00000000000..f3d86a3573d --- /dev/null +++ b/js/watch/src/echo.test.ts @@ -0,0 +1,147 @@ +import { expect, test } from "bun:test"; +import { Manual, Milli, Nano } from "@moq/clock"; +import { Echo as Schema } from "@moq/hang"; +import type * as Catalog from "@moq/hang/catalog"; +import * as Json from "@moq/json"; +import { Origin, Path } from "@moq/net"; +import { Signal } from "@moq/signals"; +import { Broadcast } from "./broadcast"; +import { checkName, Echo } from "./echo"; +import type { Received } from "./feedback"; + +const flush = async (): Promise => { + for (let i = 0; i < 5; i++) await new Promise((resolve) => setTimeout(resolve, 0)); +}; + +// A watched broadcast whose catalog the test sets directly. +function watched(origin: Origin.Producer, name: string, catalog: Signal): Broadcast { + return new Broadcast({ origin, name: Path.from(name), follow: false, catalogFormat: "manual", catalog }); +} + +// A decoder that reports `received` for the catalog at `path`, and nothing for any other. +function source(path: string, received: Record) { + return { feedback: (base: Path.Valid) => (base === path ? received : {}) }; +} + +// The feedback broadcasts announced on `origin`, by path. +function announced(origin: Origin.Producer): Set { + const paths = new Set(); + const listing = origin.announced(Path.Pattern.subtree(Path.empty())); + void (async () => { + for (;;) { + const entry = await listing.next(); + if (!entry) break; + if (entry.kind === "end") paths.delete(entry.prefix); + else paths.add(entry.prefix); + } + })(); + return paths; +} + +// Read the newest feedback report published at `path`. +async function read(origin: Origin.Producer, path: string, clock: Manual): Promise { + const request = origin.request(Path.from(path)); + await flush(); + const broadcast = request.active.peek(); + if (!broadcast) throw new Error(`no feedback at ${path}`); + const track = broadcast.track(Schema.TRACK).subscribe(); + const consumer = new Json.Snapshot.Consumer({ track, schema: Schema.SnapshotSchema }); + await flush(); + await clock.advance(Nano.fromMilli(Milli(1000))); + const value = (await consumer.latest())?.value; + track.close(); + request.close(); + return value; +} + +test("refuses a name that is not one visible path segment", () => { + for (const name of ["", "a/b", ".", "..", "*", "**", ".hidden"]) expect(() => checkName(name)).toThrow(); + expect(checkName("alice")).toBe("alice"); +}); + +test("publishes feedback where the catalog solicits it and follows the solicitation", async () => { + const clock = new Manual(); + const installed = clock.install(); + const origin = new Origin.Producer(); + const paths = announced(origin); + const catalog = new Signal({}); + const broadcast = watched(origin, "room/live.hang", catalog); + const echo = new Echo({ + broadcast, + origin, + name: "alice", + probe: { rtt: Milli(20) }, + sources: [source("room/live.hang", { video: { frames: 2, bytes: 20 } }), source("room/live.hang", { audio: { underruns: 1 } })], + }); + try { + await flush(); + // Nothing is solicited, so nothing is published. + expect([...paths]).toEqual([]); + + catalog.set({ echo: { path: "viewers" } } as Catalog.Root); + await flush(); + expect([...paths]).toEqual(["room/viewers/alice.echo"]); + expect(await read(origin, "room/viewers/alice.echo", clock)).toEqual({ + transport: { rtt: 20 }, + renditions: { video: { frames: 2, bytes: 20 }, audio: { underruns: 1 } }, + }); + + // A moved path retracts the broadcast it replaces. + catalog.set({ echo: { path: "live/viewers" } } as Catalog.Root); + await flush(); + expect([...paths]).toEqual(["room/live/viewers/alice.echo"]); + + // A removed section retracts it. + catalog.set({}); + await flush(); + expect([...paths]).toEqual([]); + } finally { + echo.close(); + broadcast.close(); + origin.close(); + installed.close(); + } +}); + +test("reporters resolving one feedback path share its broadcast and add their counts", async () => { + const clock = new Manual(); + const installed = clock.install(); + const origin = new Origin.Producer(); + const paths = announced(origin); + const catalog = new Signal({ echo: { path: "viewers" } } as Catalog.Root); + const first = watched(origin, "room/live.hang", catalog); + const second = watched(origin, "room/live.hang", catalog); + const reporters = [first, second].map( + (broadcast, n) => + new Echo({ + broadcast, + origin, + name: "alice", + sources: [source("room/live.hang", { video: { frames: n + 1, arrival: { timestamp: n, wall: 100 + n } } })], + }), + ); + try { + await flush(); + expect([...paths]).toEqual(["room/viewers/alice.echo"]); + expect(await read(origin, "room/viewers/alice.echo", clock)).toEqual({ + renditions: { video: { frames: 3, arrival: { timestamp: 1, wall: 101 } } }, + }); + + // One leaving keeps its counts in the report, which stays cumulative. + reporters[1].close(); + await flush(); + expect([...paths]).toEqual(["room/viewers/alice.echo"]); + expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames).toBe(3); + + // The last one leaving retracts it. + reporters[0].close(); + await flush(); + expect([...paths]).toEqual([]); + } finally { + for (const reporter of reporters) reporter.close(); + first.close(); + second.close(); + origin.close(); + installed.close(); + } +}); diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts new file mode 100644 index 00000000000..17d11ba3566 --- /dev/null +++ b/js/watch/src/echo.ts @@ -0,0 +1,233 @@ +import { Milli, Nano } from "@moq/clock"; +import { Echo as Schema, Report } from "@moq/hang"; +import * as Moq from "@moq/net"; +import { Effect, type Getter, getter, type Inputs, type Readonlys } from "@moq/signals"; +import type { Broadcast } from "./broadcast"; +import type { Received } from "./feedback"; + +/** A viewer report as written: per-rendition counters and the connection's round-trip time. */ +type Snapshot = { transport?: { rtt: number }; renditions: Record }; + +/** Signals the reporter reads. */ +export type EchoInput = { + /** The origin to publish feedback into. */ + origin: Getter; + /** Whether to publish. Defaults to true. */ + enabled: Getter; + /** The viewer's name, one path segment: feedback is published at `/.echo`. Undefined publishes none. */ + name: Getter; + /** The connection's PROBE estimates, whose round-trip time the report carries while someone reads it. */ + probe: Getter; +}; + +/** What a decoder received of each rendition in a catalog, keyed by rendition ID. */ +export interface Feedback { + /** Report what was received of the renditions in the catalog of the broadcast at `path`. */ + feedback(path: Moq.Path.Valid): Record; +} + +/** Constructor properties for {@link Echo}. */ +export type EchoProps = Inputs & { + /** The watched broadcast, whose catalog may solicit feedback. */ + broadcast: Broadcast; + /** The decoders whose counters the report carries. */ + sources: Feedback[]; +}; + +/** + * Refuse an echo name that is not one visible path segment: empty, containing `/`, a dot segment + * or glob, or starting with `.`, which would hide the feedback from discovery. Matches the Rust CLI. + */ +export function checkName(name: string): string { + if (name === "" || name.includes("/") || name === "." || name === ".." || name === "*" || name === "**") { + throw new Error(`echo name ${JSON.stringify(name)} is not a single path segment`); + } + if (name.startsWith(".")) { + throw new Error(`echo name ${JSON.stringify(name)} starts with \`.\`, which hides its feedback from discovery`); + } + return name; +} + +/** + * Publishes a viewer's feedback where a watched catalog solicits it. + * + * Once the catalog carries an `echo` section, this resolves its path against the broadcast, as a + * rendition's `broadcast` reference resolves, and publishes `.echo` there with one + * `feedback.json` snapshot track: what each rendition was received and played, keyed by its ID in + * that catalog, and the connection's PROBE round-trip time. Each catalog update reconciles it: a + * removed section, or a changed path, retracts the broadcast it replaces. + * + * Reporters on one origin that resolve the same feedback path share one broadcast and add their + * counts, since a second broadcast at a path would replace the first. + */ +export class Echo { + /** The wired inputs, read-only. */ + readonly in: Readonlys; + /** The watched broadcast. */ + readonly broadcast: Broadcast; + + readonly #sources: Feedback[]; + #signals = new Effect(); + + constructor(props: EchoProps) { + this.in = { + origin: getter(props.origin), + enabled: getter(props.enabled ?? true), + name: getter(props.name), + probe: getter(props.probe), + }; + this.broadcast = props.broadcast; + this.#sources = props.sources; + + // Derived on its own, so an ordinary catalog update that keeps the echo path keeps the broadcast. + const target = this.#signals.computed((effect) => { + if (!effect.get(this.in.enabled)) return undefined; + const origin = effect.get(this.in.origin); + const name = effect.get(this.in.name); + const echo = effect.get(this.broadcast.out.catalog)?.echo; + if (!origin || name === undefined || !echo) return undefined; + + const base = effect.get(this.broadcast.in.name); + // The catalog consumer already refuses a path above the root; this only narrows the type. + const prefix = Moq.Path.tryResolve(base, echo.path); + if (prefix === undefined) return undefined; + return { origin, base, path: Moq.Path.join(prefix, Moq.Path.from(`${checkName(name)}${Schema.SUFFIX}`)) }; + }); + + this.#signals.run((effect) => { + const current = effect.get(target); + if (!current) return; + + let shared: Shared; + try { + shared = Shared.acquire(current.origin, current.path); + } catch (err) { + console.warn("failed to publish feedback", current.path, err); + return; + } + const leave = shared.join(this, () => this.#report(current.base)); + effect.cleanup(leave); + + // Observing the probe asks the peer for PROBE updates, so only do it while someone reads them. + effect.run((inner) => { + if (inner.get(shared.watched)) inner.get(this.in.probe); + }); + }); + } + + // What the decoders received of the renditions in the catalog of the broadcast at `base`. + #report(base: Moq.Path.Valid): Snapshot { + const renditions: Record = {}; + for (const source of this.#sources) Object.assign(renditions, source.feedback(base)); + const rtt = this.in.probe.peek()?.rtt; + return rtt === undefined ? { renditions } : { transport: { rtt: Math.floor(rtt) }, renditions }; + } + + /** Stop publishing and release everything this holds. */ + close(): void { + this.#signals.close(); + } +} + +// One feedback broadcast per origin and path, shared by every reporter that resolves to it. +const published = new WeakMap>(); + +class Shared { + readonly #origin: Moq.Origin.Table; + readonly #path: Moq.Path.Valid; + readonly #broadcast: Moq.Broadcast.Producer; + readonly #writer: Report.Writer; + // Each reporter's counts, keyed by its owner. + readonly #reporters = new Map Snapshot>(); + // What each owner that left last reported, so the counters stay cumulative without it. Its counts + // are cumulative, so a returning owner reports them again itself. + readonly #retired = new Map(); + #signals = new Effect(); + + /** Whether anyone reads the feedback, which is when it is written. */ + readonly watched: Getter; + + static acquire(origin: Moq.Origin.Table, path: Moq.Path.Valid): Shared { + let paths = published.get(origin); + if (!paths) { + paths = new Map(); + published.set(origin, paths); + } + let shared = paths.get(path); + if (!shared) { + shared = new Shared(origin, path); + paths.set(path, shared); + } + return shared; + } + + private constructor(origin: Moq.Origin.Table, path: Moq.Path.Valid) { + this.#origin = origin; + this.#path = path; + const publication = origin.createBroadcast(path); + this.#broadcast = publication.broadcast; + try { + this.#writer = new Report.Writer(this.#broadcast, Schema.TRACK, Schema.SnapshotSchema); + // A fresh instance, so a reader sees a replaced feedback broadcast as a restart. + publication.announce({ epoch: Moq.Epoch.mint() }); + } catch (err) { + this.#broadcast.close(); + throw err; + } + const demand = this.#writer.track.demand(); + this.watched = this.#signals.computed((effect) => effect.get(demand.wanted) !== undefined); + this.#signals.interval(() => this.#write(), Nano.fromMilli(Milli(Report.INTERVAL))); + } + + /** Add `owner`'s counts to the feedback, returning the function that removes them. */ + join(owner: object, reporter: () => Snapshot): () => void { + this.#retired.delete(owner); + this.#reporters.set(owner, reporter); + return () => { + if (this.#reporters.get(owner) !== reporter) return; + this.#reporters.delete(owner); + this.#retired.set(owner, { renditions: reporter().renditions }); + // Deferred, so a reporter's rerun reuses the broadcast rather than replacing it. + queueMicrotask(() => { + if (this.#reporters.size > 0 || published.get(this.#origin)?.get(this.#path) !== this) return; + published.get(this.#origin)?.delete(this.#path); + this.#close(); + }); + }; + } + + #write(): void { + if (!this.#writer.wanted) return; + let snapshot: Snapshot = { renditions: {} }; + for (const reporter of this.#reporters.values()) snapshot = merge(snapshot, reporter()); + for (const retired of this.#retired.values()) snapshot = merge(snapshot, retired); + this.#writer.update(snapshot as Schema.Snapshot); + } + + // Write the final counts and retract the broadcast. + #close(): void { + this.#write(); + this.#signals.close(); + this.#writer.finish(); + this.#broadcast.close(); + } +} + +// Add two reports' counters per rendition, keeping the newer arrival and the first round-trip time: +// gauges are never summed. +function merge(a: Snapshot, b: Snapshot): Snapshot { + const renditions: Record = { ...a.renditions }; + for (const [id, received] of Object.entries(b.renditions)) { + const sum: Received = { ...renditions[id] }; + for (const [counter, n] of Object.entries(received)) { + if (counter === "arrival") continue; + const key = counter as Exclude; + sum[key] = (sum[key] ?? 0) + (n as number); + } + const arrival = received.arrival; + if (arrival && (sum.arrival === undefined || arrival.wall >= sum.arrival.wall)) sum.arrival = arrival; + renditions[id] = sum; + } + const transport = a.transport ?? b.transport; + return transport ? { transport, renditions } : { renditions }; +} diff --git a/js/watch/src/element.ts b/js/watch/src/element.ts index 4ec31b00af6..0bacd87c731 100644 --- a/js/watch/src/element.ts +++ b/js/watch/src/element.ts @@ -13,6 +13,7 @@ import { Derived, Effect, Signal } from "@moq/signals"; import type * as Audio from "./audio"; import { type Broadcast, CATALOG_FORMATS, type CatalogFormat } from "./broadcast"; import { formatDuration, parseDuration } from "./duration"; +import { checkName } from "./echo"; import { Player } from "./player"; import type { Delay, Sync } from "./sync"; import type * as Text from "./text"; @@ -65,6 +66,7 @@ const OBSERVED = [ "buffer", "catalog-format", "captions", + "echo", ] as const; // Parse visibility, with the default only when the attribute is absent. @@ -103,6 +105,16 @@ function parseBuffer(value: string | null): Milli { throw invalidAttribute("buffer", value, 'a duration like "30s"'); } +// Parse the `echo` attribute: the viewer's feedback name, one visible path segment, or undefined when absent. +function parseEcho(value: string | null): string | undefined { + if (value === null) return undefined; + try { + return checkName(value); + } catch { + throw invalidAttribute("echo", value, "one path segment not starting with `.`"); + } +} + /** Parse the element's catalog-format attribute, refusing unknown formats. */ export function parseCatalogFormat(value: string | null): CatalogFormat | undefined { if (value === null) return undefined; @@ -195,6 +207,7 @@ export default class MoqWatch extends HTMLElement { #follow = new Signal(true); #catalogFormat = new Signal(undefined); #catalog = new Signal(undefined); + #echo = new Signal(undefined); // The canvas element to render into. #canvas = new Signal(undefined); @@ -237,6 +250,7 @@ export default class MoqWatch extends HTMLElement { follow: this.#follow, catalogFormat: this.#catalogFormat, catalog: this.#catalog, + echo: this.#echo, ...this.controls, video: { ...this.controls.video, @@ -311,6 +325,7 @@ export default class MoqWatch extends HTMLElement { this.signals.run((effect) => this.#reflect(effect, "follow", effect.get(this.#follow) ? "" : "false")); this.signals.run((effect) => this.#reflect(effect, "catalog-format", effect.get(this.#catalogFormat))); this.signals.run((effect) => this.#reflect(effect, "captions", effect.get(this.controls.text.target))); + this.signals.run((effect) => this.#reflect(effect, "echo", effect.get(this.#echo))); this.signals.run((effect) => { const delay = effect.get(this.controls.delay); this.#reflect(effect, "delay", typeof delay === "number" ? formatDuration(delay) : delay); @@ -394,6 +409,7 @@ export default class MoqWatch extends HTMLElement { else if (name === "buffer") this.buffer = parseBuffer(newValue); else if (name === "catalog-format") this.catalogFormat = parseCatalogFormat(newValue); else if (name === "captions") this.captions = newValue || undefined; + else if (name === "echo") this.echo = parseEcho(newValue); else { const exhaustive: never = name; throw new Error(`Invalid attribute: ${exhaustive}`); @@ -602,6 +618,21 @@ export default class MoqWatch extends HTMLElement { this.controls.text.target.set(value || undefined); this.#accept("captions"); } + + /** + * The viewer's feedback name, mirrored by the `echo` attribute; undefined (the default) publishes + * no feedback. Once the watched catalog solicits feedback with an `echo` section, the element + * publishes `.echo` under its path, reporting what each rendition received and played. One + * visible path segment: a `/` or a leading `.` is refused. + */ + get echo(): string | undefined { + return this.#echo.peek(); + } + + set echo(value: string | undefined) { + this.#echo.set(parseEcho(value ?? null)); + this.#accept("echo"); + } } customElements.define("moq-watch", MoqWatch); diff --git a/js/watch/src/feedback.ts b/js/watch/src/feedback.ts new file mode 100644 index 00000000000..65414b2ee76 --- /dev/null +++ b/js/watch/src/feedback.ts @@ -0,0 +1,106 @@ +import { Instant, type Milli, Nano, now, wall } from "@moq/clock"; +import * as Catalog from "@moq/hang/catalog"; +import type * as Moq from "@moq/net"; + +/** A cumulative counter a viewer reports for each rendition it read. */ +export type Counter = "frames" | "bytes" | "decoded" | "late" | "errors" | "stalls" | "stalled" | "underruns"; + +/** + * What a viewer received and played of one rendition, in the shape its feedback track reports. + * Counters are cumulative and a missing one means zero; `stalled` is in milliseconds. + */ +export type Received = Partial> & { + /** The newest received media timestamp in milliseconds, and its arrival in milliseconds since the MoQ epoch. */ + arrival?: { timestamp: number; wall: number }; +}; + +/** One rendition a decoder read: its ID in the catalog of the broadcast at `path`. */ +export interface Key { + /** The catalog broadcast, which a feedback report is published for. */ + path: Moq.Path.Valid; + /** The rendition's ID in that catalog, even when its media comes from another broadcast. */ + id: string; +} + +// The most catalog broadcasts a tally keeps counters for. A switch overlaps the outgoing and +// incoming one, so a few cover it without holding every broadcast ever watched. +const MAX_BROADCASTS = 4; + +type Entry = { received: Received; stalling?: Instant }; + +/** + * Cumulative counters per rendition, for each catalog broadcast a decoder read. The decoder counts + * into it as frames arrive and play, and the feedback reporter reads it about once a second. + */ +export class Tally { + #broadcasts = new Map>(); + + #entry(key: Key): Entry { + let renditions = this.#broadcasts.get(key.path); + if (!renditions) { + renditions = new Map(); + this.#broadcasts.set(key.path, renditions); + for (const path of this.#broadcasts.keys()) { + if (this.#broadcasts.size <= MAX_BROADCASTS) break; + this.#broadcasts.delete(path); + } + } + let entry = renditions.get(key.id); + if (!entry) { + entry = { received: {} }; + renditions.set(key.id, entry); + } + return entry; + } + + /** Add `counts` to the rendition's counters. */ + count(key: Key, counts: Partial>): void { + const received = this.#entry(key).received; + for (const [counter, n] of Object.entries(counts) as [Counter, number][]) { + if (n !== 0) received[counter] = (received[counter] ?? 0) + n; + } + } + + /** Record a received frame at media `timestamp`, arriving now. */ + arrive(key: Key, timestamp: Milli): void { + const at = Math.floor(wall() - Catalog.MOQ_EPOCH_UNIX_MILLIS); + // A clock before the MoQ epoch has no wire encoding, so such an arrival is never recorded. + if (at < 0 || timestamp < 0) return; + this.#entry(key).received.arrival = { timestamp: Math.floor(timestamp), wall: at }; + } + + /** + * Count a stall that starts now, returning the function that ends it and reports how long it + * lasted in milliseconds. A report taken meanwhile includes the time stalled so far. + */ + stall(key: Key): () => number { + const entry = this.#entry(key); + const start = now(); + entry.received.stalls = (entry.received.stalls ?? 0) + 1; + entry.stalling = start; + return () => { + const duration = elapsed(start); + if (entry.stalling === start) entry.stalling = undefined; + entry.received.stalled = (entry.received.stalled ?? 0) + duration; + return duration; + }; + } + + /** What was received of each rendition of the broadcast at `path`, keyed by rendition ID. */ + report(path: Moq.Path.Valid): Record { + const report: Record = {}; + for (const [id, entry] of this.#broadcasts.get(path) ?? []) { + const received = { ...entry.received }; + if (entry.stalling !== undefined) received.stalled = (received.stalled ?? 0) + elapsed(entry.stalling); + if (received.stalled !== undefined) received.stalled = Math.floor(received.stalled); + if (received.arrival) received.arrival = { ...received.arrival }; + report[id] = received; + } + return report; + } +} + +// Milliseconds since `start`. +function elapsed(start: Instant): number { + return Nano.toMilli(Instant.durationSince(now(), start)); +} diff --git a/js/watch/src/player.ts b/js/watch/src/player.ts index b31ac65fb28..50d18d4a38c 100644 --- a/js/watch/src/player.ts +++ b/js/watch/src/player.ts @@ -5,6 +5,7 @@ import { Path } from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys, Signal } from "@moq/signals"; import * as Audio from "./audio"; import { Broadcast, type CatalogFormat } from "./broadcast"; +import { Echo } from "./echo"; import { type Delay, Sync } from "./sync"; import * as Text from "./text"; import * as Video from "./video"; @@ -23,8 +24,13 @@ export type PlayerInput = { catalogFormat: Getter; /** Catalog supplied when the format is `manual`. */ catalog: Getter; - /** Connection probe used for rendition selection. */ + /** Connection probe used for rendition selection, and whose round-trip time feedback reports. */ probe: Getter; + /** + * The viewer's name, one path segment, under which to publish feedback once the catalog solicits + * it: `/.echo`. Undefined (the default) publishes none. + */ + echo: Getter; /** Pause media and captions. */ paused: Getter; /** Playback distance from the live edge. */ @@ -90,6 +96,8 @@ export class Player { readonly emitter: Audio.Emitter; /** Caption overlay output. */ readonly textRenderer: Text.Renderer; + /** Feedback published where the catalog solicits it. */ + readonly echo: Echo; #videoEnabled = new Signal(false); #audioEnabled = new Signal(false); @@ -108,6 +116,7 @@ export class Player { catalogFormat: getter(props.catalogFormat), catalog: getter(props.catalog), probe: getter(props.probe), + echo: getter(props.echo), paused: getter(props.paused ?? false), delay: getter(props.delay ?? "auto"), buffer: getter(props.buffer ?? Milli.zero), @@ -185,6 +194,16 @@ export class Player { }); this.#signals.cleanup(() => this.textRenderer.close()); + this.echo = new Echo({ + broadcast: this.broadcast, + origin: this.in.origin, + enabled: this.in.enabled, + name: this.in.echo, + probe: this.in.probe, + sources: [this.video, this.audio], + }); + this.#signals.cleanup(() => this.echo.close()); + this.#signals.run((effect) => { this.#captionsEnabled.set(effect.get(this.in.enabled) && !effect.get(this.in.paused)); }); diff --git a/js/watch/src/video/decoder.test.ts b/js/watch/src/video/decoder.test.ts index a984114ebe6..ee125d8a509 100644 --- a/js/watch/src/video/decoder.test.ts +++ b/js/watch/src/video/decoder.test.ts @@ -36,6 +36,7 @@ let sources = 0; function watchBroadcast(catalog: Signal): Broadcast { const media = closedConsumer(`source-${sources++}`); return { + in: { name: new Signal(Moq.Path.from("watched")) }, out: { catalog, active: new Signal(undefined) }, relativeBroadcast: () => media, } as unknown as Broadcast; @@ -300,6 +301,7 @@ async function guardedPlayback( const media = new Signal(producer.consume()); const catalog = new Signal({ video: { renditions: { video } } }); const broadcast = new Signal({ + in: { name: new Signal(Moq.Path.from("watched")) }, out: { catalog, active }, relativeBroadcast: (effect: Effect) => effect.get(media), } as unknown as Broadcast); @@ -578,7 +580,13 @@ for (const kind of ["legacy", "cmaf"] as const) { try { expect(playback.submitted).toEqual([1000, 1100, 1200]); // Rejected payloads were still received, but never counted as frames. - expect(playback.decoder.out.stats.peek()).toEqual({ frameCount: 3, bytesReceived: 5 }); + expect(playback.decoder.out.stats.peek()).toMatchObject({ frameCount: 3, bytesReceived: 5 }); + // Feedback counts every frame received, under the rendition's ID in the watched catalog. + expect(playback.decoder.feedback(Moq.Path.from("watched")).video).toMatchObject({ + frames: 5, + bytes: 5, + decoded: 3, + }); } finally { playback.close(); } diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 4d0454eea9f..46e550cd45f 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -1,4 +1,4 @@ -import { type Micro, Milli, Nano } from "@moq/clock"; +import { type Micro, Milli, Nano, type Wall, wall } from "@moq/clock"; import * as Catalog from "@moq/hang/catalog"; import * as Container from "@moq/hang/container"; import * as Util from "@moq/hang/util"; @@ -16,6 +16,7 @@ import { } from "@moq/signals"; import { rotateVideoDimensions } from "@moq/video"; import { base64ToBytes } from "../base64"; +import { type Counter, type Key, type Received, Tally } from "../feedback"; import { type Failure, failureMoved, nextMedia, subscribeMedia } from "../media"; import type { Sync } from "../sync"; import { @@ -60,8 +61,26 @@ export interface Stats { /** Number of encoded bytes received. */ bytesReceived: number; + + /** Frames that arrived after their playout time. */ + late: number; + + /** Renditions that failed to decode. */ + errors: number; + + /** Times playback stalled: no new picture for half a second once one had played. */ + stalls: number; + + /** Total time spent in finished stalls. */ + stalled: Milli; + + /** The newest received media timestamp and the wall time it arrived. */ + arrival?: { timestamp: Milli; wall: Wall }; } +// The running totals before anything is counted. +const EMPTY: Stats = { frameCount: 0, bytesReceived: 0, late: 0, errors: 0, stalls: 0, stalled: Milli.zero }; + /** Signals the decoder derives. */ export type DecoderOutput = { /** Fatal decode failure, cleared when another source is selected. */ @@ -128,6 +147,11 @@ export class Decoder { #selected?: DecoderTrack; #failed?: Failure; + // What each rendition delivered, for the feedback a viewer reports. + #tally = new Tally(); + // Whether a picture played since the decoder was enabled, so the wait for the first one is no stall. + #played = false; + #clearCurrentFrame(): void { this.#out.frame.update((prev) => { prev?.close(); @@ -177,6 +201,16 @@ export class Decoder { this.#signals.run(this.#runActive.bind(this)); this.#signals.run(this.#runDisplay.bind(this)); this.#signals.run(this.#runBuffering.bind(this)); + this.#signals.run(this.#runStalls.bind(this)); + } + + /** + * What this decoder received and played of each rendition in the catalog of the broadcast at + * `path`, keyed by rendition ID, for the feedback a viewer reports. + * @internal + */ + feedback(path: Moq.Path.Valid): Record { + return this.#tally.report(path); } // Read from the full catalog entry, which the decoder config omits, so a rising entry resizes Sync. @@ -267,6 +301,8 @@ export class Decoder { config: identity.decoder, identity: key, stats: this.#out.stats, + tally: this.#tally, + key: { path: broadcast.in.name.peek(), id: track }, catalog: broadcast.out.catalog, predecessor, }); @@ -339,6 +375,7 @@ export class Decoder { const frame = inner.get(active.frame); if (!frame) return; // A promoted track holds the previous picture until its first frame. if (active.error.peek()) return; + this.#played = true; if (this.#selected === active) { this.#failed = undefined; this.#out.error.set(undefined); @@ -355,6 +392,7 @@ export class Decoder { } #recordError(track: DecoderTrack, error: Error): void { + track.count({ errors: 1 }, (stats) => ({ errors: stats.errors + 1 })); // An outgoing failure must not replace the selected rendition's failure latch. if (track !== this.#selected && this.#selected?.error.peek()) return; this.#failed = { @@ -402,6 +440,28 @@ export class Decoder { }, Nano.fromMilli(BUFFERING)); } + // Count each stall once a picture has played, and how long it lasted, against the rendition on + // screen. A disabled decoder waits for a new picture again: resuming is a startup, not a stall. + #runStalls(effect: Effect): void { + if (!effect.get(this.in.enabled)) { + this.#played = false; + return; + } + if (!effect.get(this.#out.stalled) || !this.#played) return; + const active = this.#active.peek(); + if (!active) return; + + const end = this.#tally.stall(active.key); + this.#out.stats.update((stats) => ({ ...(stats ?? EMPTY), stalls: (stats?.stalls ?? 0) + 1 })); + effect.cleanup(() => { + const duration = end(); + this.#out.stats.update((stats) => ({ + ...(stats ?? EMPTY), + stalled: Milli((stats?.stalled ?? 0) + duration), + })); + }); + } + /** Stop and release everything this holds. */ close() { this.#clearCurrentFrame(); @@ -427,8 +487,10 @@ interface DecoderTrackProps { // The consumer of the rendition on screen when this one was selected from the same path, whose // arrival estimate it continues. predecessor?: Container.Consumer; - stats: Signal; + // The rendition's feedback counters, under its ID in the catalog it was selected from. + tally: Tally; + key: Key; } class DecoderTrack { @@ -441,6 +503,8 @@ class DecoderTrack { identity: string; catalog: Getter; stats: Signal; + tally: Tally; + key: Key; timestamp = new Signal(undefined); frame = new Signal(undefined); @@ -479,11 +543,35 @@ class DecoderTrack { this.identity = props.identity; this.catalog = props.catalog; this.stats = props.stats; + this.tally = props.tally; + this.key = props.key; this.#predecessor = props.predecessor; this.#signals.run(this.#run.bind(this)); } + // Count into this rendition's feedback and the decoder's running totals. + count(counts: Partial>, totals?: (stats: Stats) => Partial): void { + this.tally.count(this.key, counts); + if (totals) this.stats.update((current) => ({ ...(current ?? EMPTY), ...totals(current ?? EMPTY) })); + } + + // Count a frame read from the track: its bytes even when rejected, and whether an accepted one + // arrived too late for playout. Classifies ingress before decoder backpressure changes the + // delivery clock. + #receive(frame: Container.ReceivedFrame, accepted: boolean): void { + const timestamp = Milli.fromMicro(frame.timestamp as Micro); + const late = accepted && this.sync.received(timestamp, frame.arrival); + const bytes = frame.payload.byteLength; + this.tally.arrive(this.key, timestamp); + this.count({ frames: 1, bytes, late: late ? 1 : 0 }, (stats) => ({ + frameCount: stats.frameCount + (accepted ? 1 : 0), + bytesReceived: stats.bytesReceived + bytes, + late: stats.late + (late ? 1 : 0), + arrival: { timestamp, wall: wall() }, + })); + } + // Reorders groups and frames up to the shared max delay. A rendition switch is not a cold start: // the path's arrivals are what they were, so the estimate continues from whatever read before. #consume(effect: Effect, sub: Moq.Track.Subscriber, format: Container.Format): Container.Consumer { @@ -510,6 +598,7 @@ class DecoderTrack { const decoder = new VideoDecoder({ output: async (frame: VideoFrame) => { try { + this.count({ decoded: 1 }); const timestamp = Milli.fromMicro(frame.timestamp as Micro); if (timestamp < (this.timestamp.peek() ?? 0)) { // Late frame, don't render it. @@ -622,15 +711,9 @@ class DecoderTrack { // resets this guard. Rejected payloads still count as received bytes. const stale = latest !== undefined && next.group < latest; const accepted = !stale && recovery.accept(frame); - this.stats.update((current) => ({ - frameCount: (current?.frameCount ?? 0) + (accepted ? 1 : 0), - bytesReceived: (current?.bytesReceived ?? 0) + frame.payload.byteLength, - })); + this.#receive(frame, accepted); if (!accepted) continue; - // Classify ingress before decoder backpressure changes the delivery clock. - this.sync.received(Milli.fromMicro(frame.timestamp as Micro), frame.arrival); - const chunk = new EncodedVideoChunk({ type: frame.keyframe ? "key" : "delta", data: frame.payload, @@ -708,15 +791,9 @@ class DecoderTrack { // resets this guard. Rejected payloads still count as received bytes. const stale = latest !== undefined && next.group < latest; const accepted = !stale && recovery.accept(frame); - this.stats.update((current) => ({ - frameCount: (current?.frameCount ?? 0) + (accepted ? 1 : 0), - bytesReceived: (current?.bytesReceived ?? 0) + frame.payload.byteLength, - })); + this.#receive(frame, accepted); if (!accepted) continue; - // Classify ingress before decoder backpressure changes the delivery clock. - this.sync.received(Milli.fromMicro(frame.timestamp), frame.arrival); - // Track decode buffer (see #runLegacy: bridge only when no gap or end came between, // never on group adjacency, which proves nothing about the timeline). if (previous !== undefined) { From 2d09aba2f1c135fabf3ff6460771150704c501cc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 23:37:09 -0700 Subject: [PATCH 03/13] wip(js): feedback docs, demo, and tests --- demo/web/src/index.ts | 5 ++++ demo/web/src/publish.html | 4 ++- doc/concept/stats.md | 6 +++- doc/lib/js/publish.md | 19 +++++++++++++ doc/lib/js/watch.md | 15 ++++++++++ js/publish/README.md | 2 ++ js/publish/src/audio/encoder.ts | 2 +- js/publish/src/broadcast.test.ts | 11 ++++--- js/publish/src/broadcast.ts | 4 ++- js/publish/src/video/encoder.ts | 2 +- js/watch/README.md | 3 +- js/watch/src/audio/decoder.ts | 6 +--- js/watch/src/echo.test.ts | 15 ++++++---- js/watch/src/echo.ts | 2 +- js/watch/src/feedback.test.ts | 49 ++++++++++++++++++++++++++++++++ js/watch/src/ui/stats.ts | 7 +++++ 16 files changed, 131 insertions(+), 21 deletions(-) create mode 100644 js/watch/src/feedback.test.ts diff --git a/demo/web/src/index.ts b/demo/web/src/index.ts index 3701505bfae..a312c9f0756 100644 --- a/demo/web/src/index.ts +++ b/demo/web/src/index.ts @@ -79,6 +79,10 @@ const metaSignal = new Signals.Signal(undefined); // tile's follow it reactively. const relayUrl = new Signals.Signal(new URL(RELAY_URL)); +// This page's feedback name: a tile whose catalog solicits feedback publishes `/.echo`, +// which `moq export echo` reads. Tiles of one broadcast share it and add their counts. +const VIEWER = `viewer-${crypto.randomUUID().slice(0, 8)}`; + // Discovery connection (the tiles each open their own connection internally). const connection = new Net.Connection({ url: relayUrl }); @@ -119,6 +123,7 @@ function createTile(name: string): WatchTile { // `broadcast` and decoders, so the shared inspector panel reflects the active tile. const watch = document.createElement("moq-watch") as MoqWatch; watch.name = name; + watch.echo = VIEWER; watch.muted = true; // unmuted only while active (see below) const canvas = document.createElement("canvas"); canvas.style.cssText = "width: 100%; height: auto;"; diff --git a/demo/web/src/publish.html b/demo/web/src/publish.html index 393eb02668b..bc131207374 100644 --- a/demo/web/src/publish.html +++ b/demo/web/src/publish.html @@ -29,7 +29,9 @@

MoQ Publish

cost of an extra encode + decode. --> - + + diff --git a/doc/concept/stats.md b/doc/concept/stats.md index bd1c35b8373..d7cdf05b5c3 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -36,7 +36,11 @@ measurement stays explicit, so it remains distinct from unavailable. [CLI](/bin/cli#reports-and-feedback), and `moq import --echo-path` solicits feedback. An import counts the frames and payload bytes it writes to each rendition, and video keyframes; an export counts what -it reads and records its newest arrival. See the +it reads and records its newest arrival. In the browser, `` +and `echo-path` do the same for the [publisher](/lib/js/publish#stats-and-feedback), +and `` reports what its [player](/lib/js/watch#feedback) +received, decoded, and played, with only the PROBE round-trip time as its +transport. See the [hang draft](/draft/moq-hang#media-stats) for track framing, field units, and the feedback convention. diff --git a/doc/lib/js/publish.md b/doc/lib/js/publish.md index 051e8b4ab46..3212ed6bfb7 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -35,6 +35,8 @@ WebCodecs, writes the catalog, and publishes a hang broadcast. | `preview` | What the nested element shows: the raw `source` (default), a decoded copy of the `encoded` stream to see what viewers get, or `none`. | | `backend` | How a `` preview is drawn; see [@moq/video](/lib/js/video). `auto` (default), `webgpu`, or `2d`. | | `announce` | When to advertise: once the `source` is live (default), or `always`. Nobody can see or subscribe to the broadcast until it is announced. To keep it out of discovery, use a hidden name with a `.`-prefixed segment; it is still subscribable by name. | +| `stats` | Publish a [stats track](/concept/stats#media-reports) named in the catalog. Off by default. | +| `echo-path` | Solicit viewer feedback under this path, relative to the broadcast as a rendition reference is: from `room/live`, `viewers` is `room/viewers`. Sets the catalog's `echo` section; absent solicits none. | Every attribute is also a reactive property, and property or UI changes reflect back into the attributes. An invalid value is refused rather than defaulted: the @@ -49,6 +51,23 @@ Capture failures, such as `NotAllowedError` when permission is refused, land in `el.sources.audio`, and `` shows them. A refused capture waits for a permission, device, or settings change instead of prompting again. +## Stats and feedback + +With `stats`, the catalog names a `stats.json` track that reports, about once a +second while someone subscribes, what each rendition has sent under its catalog +ID: frames, bytes, keyframes, frames skipped because the encoder was still +busy, and the target bitrate. Its `transport` carries only the PROBE round-trip +time, since browsers report no usable WebTransport statistics. The encoders' +`out.stats` and the stats panel read the same counters, and a custom producer +reports through its rendition's `stats` signal. The `Broadcast` takes the same +options as `stats`, `probe`, and `echo` inputs. + +`echo-path` only asks for feedback: a `` that reads the +catalog publishes `room/viewers/alice.echo`, and `moq export echo` or a dashboard +reads it there. Issue tokens that let viewers publish under that path. A path +that walks above the root from the broadcast name is left out of the catalog +with a warning, since every viewer would refuse it. + ## Encoding The video encoder follows its share of the connection's send-rate estimate, so diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index 248381f2460..645f5cad14a 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -39,6 +39,7 @@ in sync at the latency you ask for. | `backend` | How the canvas is drawn; see [@moq/video](/lib/js/video). `auto` (default), `webgpu`, or `2d`. | | `follow` | Follow the broadcast's announcements (default on): wait for one before subscribing, so a player can mount before the stream exists, and move to each restart. Off requests the name once. | | `catalog-format` | `hang`, `msf`, or `manual`; detected from the name by default. | +| `echo` | The viewer's name for [feedback](/concept/stats#media-reports), one path segment not starting with `.`. Once the catalog solicits feedback, the player publishes `/.echo`. Absent publishes none. | Every attribute is also a reactive property, and property or UI changes reflect back into the attributes. An invalid value is refused rather than defaulted: the @@ -68,6 +69,20 @@ name outside the origin's scope is an `error`. A restarted publisher at the same once, with a fresh catalog, and video, audio, and the clock start over on its timeline instead of waiting for it to catch up to the old one. +## Feedback + +A publisher solicits feedback with the catalog's `echo` section, such as +``. Given `echo="alice"`, the player resolves +that path against the broadcast and publishes `alice.echo` there, with one +`feedback.json` track reporting what each rendition was received and played +under its catalog ID: frames, bytes, decoded, late, decode errors, stalls and +stalled time, audio underruns, and the newest arrival, plus the PROBE +round-trip time. It writes about once a second while someone subscribes, and +follows the catalog: a removed or moved section retracts the broadcast. Players +on one connection watching the same catalog under one name share it and add +their counts. The decoders' `out.stats` and the stats panel read the same +counters. The token must allow publishing under the echo path. + ## Binding from a framework `import "@moq/watch/element"` registers `` when the module diff --git a/js/publish/README.md b/js/publish/README.md index 3462dd54d3a..82b915aacd4 100644 --- a/js/publish/README.md +++ b/js/publish/README.md @@ -72,6 +72,8 @@ The simplest way to publish a stream: | `preview` | string | `"source"` | What the preview renders: `"source"`, `"encoded"`, `"none"` | | `backend` | string | `"auto"` | Graphics API for a `` preview: `"auto"`, `"webgpu"`, `"2d"` | | `announce` | string | `"source"` | When to advertise: `"always"` or `"source"` (once media is captured). A camera source waits for every enabled track, and `"source"` waits until each captured track's config resolves or fails, so the first catalog lists every rendition. After its first announcement, a camera stays announced until deselected or disconnected, including mute, hide, device swaps, and capture retries. The broadcast is created while connected either way. To keep it out of discovery, use a hidden name with a `.`-prefixed segment; it is still subscribable by name. | +| `stats` | boolean | false | Publish a `stats.json` track, named in the catalog, reporting what each rendition sent and the PROBE round-trip time | +| `echo-path` | string | — | Solicit viewer feedback under this path, relative to the broadcast (from `room/live`, `viewers` is `room/viewers`) | Property and built-in UI changes reflect into attributes. Invalid URLs, version lists, and source/preview/backend/announce modes are refused: their property setters throw, and malformed markup diff --git a/js/publish/src/audio/encoder.ts b/js/publish/src/audio/encoder.ts index 2af1a6c4fb1..c167918aed1 100644 --- a/js/publish/src/audio/encoder.ts +++ b/js/publish/src/audio/encoder.ts @@ -14,9 +14,9 @@ import { Signal, } from "@moq/signals"; import type { Broadcast } from "../broadcast"; -import type { RenditionStats } from "../rendition"; import { errors } from "../internal"; import { Estimator, type Order } from "../order"; +import type { RenditionStats } from "../rendition"; import type { AudioFrame, Capture, Format } from "./capture"; import { Gain } from "./gain"; import { Resampler } from "./resampler"; diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index 5e96b858dc2..cc3bb6779d7 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -749,11 +749,14 @@ test("stats names a track in the catalog and reports each listed rendition while const net = broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); const subscriber = net.track(Broadcast.STATS_TRACK).subscribe(); - const consumer = new Json.Snapshot.Consumer({ track: subscriber, schema: Stats.SnapshotSchema }); + const consumer = new Json.Snapshot.Consumer({ + track: subscriber, + schema: Stats.SnapshotSchema, + }); await settle(); await clock.advance(Nano.fromMilli(Milli(1000))); // Sub-millisecond durations are floored on the wire. - expect((await consumer.latest())?.value).toEqual({ + expect((await consumer.latest())?.value as unknown).toEqual({ transport: { rtt: 12 }, renditions: { video: { frames: 3, bytes: 300, keyframes: 1, skipped: 2, bitrate: 1_000_000 } }, }); @@ -804,7 +807,7 @@ test("echo solicits feedback in the catalog unless it walks above the root", asy const broadcast = new Broadcast({ enabled: true, name, echo }); try { await settle(); - expect((await readCatalog(broadcast))?.echo).toEqual({ path: "viewers" }); + expect((await readCatalog(broadcast))?.echo as unknown).toEqual({ path: "viewers" }); // From `room/live.hang`, `../../viewers` walks above the root, which every viewer refuses. echo.set(Path.normalizeRelative("../../viewers")); @@ -814,7 +817,7 @@ test("echo solicits feedback in the catalog unless it walks above the root", asy // A deeper name brings the same path back within the root. name.set(Path.from("org/room/live.hang")); await settle(); - expect((await readCatalog(broadcast))?.echo).toEqual({ path: "../../viewers" }); + expect((await readCatalog(broadcast))?.echo as unknown).toEqual({ path: "../../viewers" }); echo.set(undefined); await settle(); diff --git a/js/publish/src/broadcast.ts b/js/publish/src/broadcast.ts index 7166b7ae102..1e5a94cda1a 100644 --- a/js/publish/src/broadcast.ts +++ b/js/publish/src/broadcast.ts @@ -327,7 +327,9 @@ export class Broadcast { if (path === undefined) return; const name = effect.get(this.in.name); if (Moq.Path.tryResolve(name, path) === undefined) { - console.warn(`not soliciting feedback: echo path ${JSON.stringify(path)} walks above the root from ${name}`); + console.warn( + `not soliciting feedback: echo path ${JSON.stringify(path)} walks above the root from ${name}`, + ); return; } this.catalog.mutate((catalog) => { diff --git a/js/publish/src/video/encoder.ts b/js/publish/src/video/encoder.ts index f6779b47fa8..127e044e879 100644 --- a/js/publish/src/video/encoder.ts +++ b/js/publish/src/video/encoder.ts @@ -14,9 +14,9 @@ import { Signal, } from "@moq/signals"; import type { Broadcast } from "../broadcast"; -import type { RenditionStats } from "../rendition"; import { errors } from "../internal"; import { Estimator, type Order } from "../order"; +import type { RenditionStats } from "../rendition"; import { hardwareReliable } from "../support/video"; import type { Capture } from "./capture"; import { normalizeSource, type Source } from "./types"; diff --git a/js/watch/README.md b/js/watch/README.md index 8a9111f6416..75e6eb483c0 100644 --- a/js/watch/README.md +++ b/js/watch/README.md @@ -76,9 +76,10 @@ The simplest way to watch a stream: | `buffer` | duration | `0ms` | Future-dated media held before playback skips ahead. | | `captions` | string | off | Text rendition to render. | | `catalog-format` | hang, msf, manual | auto-detected | The catalog format; detected from the name suffix unless set. | +| `echo` | path segment | — | The viewer's feedback name: once the catalog solicits feedback, publish `/.echo` reporting what each rendition received and played. | Property and built-in UI changes reflect into attributes. Invalid URLs, numbers, durations, -version lists, and rendering/catalog modes are refused: their property setters throw, and malformed markup +version lists, echo names, and rendering/catalog modes are refused: their property setters throw, and malformed markup reports a browser `error` event and suspends media until corrected or removed. Defaults apply when attributes are absent. diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index e9ffcb27ead..9d0c494de06 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -533,11 +533,7 @@ export class Decoder { }); } - #runLegacyDecoder( - effect: Effect, - sub: Moq.Track.Subscriber, - { config, failure, path, key }: Attempt, - ): void { + #runLegacyDecoder(effect: Effect, sub: Moq.Track.Subscriber, { config, failure, path, key }: Attempt): void { const preSkip = config.codec === "opus" && config.description ? Util.Opus.preSkip(Util.Hex.toBytes(config.description)) : 0; this.#terminal.clear(preSkip, Micro.fromMilli(Milli(config.warmup ?? 0))); diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index f3d86a3573d..ade54575ce9 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -71,7 +71,10 @@ test("publishes feedback where the catalog solicits it and follows the solicitat origin, name: "alice", probe: { rtt: Milli(20) }, - sources: [source("room/live.hang", { video: { frames: 2, bytes: 20 } }), source("room/live.hang", { audio: { underruns: 1 } })], + sources: [ + source("room/live.hang", { video: { frames: 2, bytes: 20 } }), + source("room/live.hang", { audio: { underruns: 1 } }), + ], }); try { await flush(); @@ -81,7 +84,7 @@ test("publishes feedback where the catalog solicits it and follows the solicitat catalog.set({ echo: { path: "viewers" } } as Catalog.Root); await flush(); expect([...paths]).toEqual(["room/viewers/alice.echo"]); - expect(await read(origin, "room/viewers/alice.echo", clock)).toEqual({ + expect((await read(origin, "room/viewers/alice.echo", clock)) as unknown).toEqual({ transport: { rtt: 20 }, renditions: { video: { frames: 2, bytes: 20 }, audio: { underruns: 1 } }, }); @@ -117,13 +120,15 @@ test("reporters resolving one feedback path share its broadcast and add their co broadcast, origin, name: "alice", - sources: [source("room/live.hang", { video: { frames: n + 1, arrival: { timestamp: n, wall: 100 + n } } })], + sources: [ + source("room/live.hang", { video: { frames: n + 1, arrival: { timestamp: n, wall: 100 + n } } }), + ], }), ); try { await flush(); expect([...paths]).toEqual(["room/viewers/alice.echo"]); - expect(await read(origin, "room/viewers/alice.echo", clock)).toEqual({ + expect((await read(origin, "room/viewers/alice.echo", clock)) as unknown).toEqual({ renditions: { video: { frames: 3, arrival: { timestamp: 1, wall: 101 } } }, }); @@ -131,7 +136,7 @@ test("reporters resolving one feedback path share its broadcast and add their co reporters[1].close(); await flush(); expect([...paths]).toEqual(["room/viewers/alice.echo"]); - expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames).toBe(3); + expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(3); // The last one leaving retracts it. reporters[0].close(); diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index 17d11ba3566..4e8ff0fbf34 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -1,5 +1,5 @@ import { Milli, Nano } from "@moq/clock"; -import { Echo as Schema, Report } from "@moq/hang"; +import { Report, Echo as Schema } from "@moq/hang"; import * as Moq from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys } from "@moq/signals"; import type { Broadcast } from "./broadcast"; diff --git a/js/watch/src/feedback.test.ts b/js/watch/src/feedback.test.ts new file mode 100644 index 00000000000..37bacbfd55c --- /dev/null +++ b/js/watch/src/feedback.test.ts @@ -0,0 +1,49 @@ +import { expect, test } from "bun:test"; +import { Manual, Milli, Nano } from "@moq/clock"; +import * as Catalog from "@moq/hang/catalog"; +import { Path } from "@moq/net"; +import { Tally } from "./feedback"; + +const live = { path: Path.from("room/live.hang"), id: "video" }; + +test("counts per rendition of each catalog broadcast, omitting zeros", () => { + const tally = new Tally(); + tally.count(live, { frames: 1, bytes: 10, late: 0 }); + tally.count(live, { frames: 1, bytes: 5 }); + tally.count({ ...live, id: "audio" }, { underruns: 2 }); + tally.count({ path: Path.from("other.hang"), id: "video" }, { frames: 7 }); + expect(tally.report(live.path)).toEqual({ video: { frames: 2, bytes: 15 }, audio: { underruns: 2 } }); + expect(tally.report(Path.from("unknown.hang"))).toEqual({}); +}); + +test("a stall reports its time so far and adds its duration once it ends", async () => { + const clock = new Manual(); + const installed = clock.install(); + try { + const tally = new Tally(); + const end = tally.stall(live); + await clock.advance(Nano.fromMilli(Milli(250.6))); + expect(tally.report(live.path).video).toEqual({ stalls: 1, stalled: 250 }); + await clock.advance(Nano.fromMilli(Milli(100))); + expect(end()).toBeCloseTo(350.6); + await clock.advance(Nano.fromMilli(Milli(1000))); + expect(tally.report(live.path).video).toEqual({ stalls: 1, stalled: 350 }); + } finally { + installed.close(); + } +}); + +test("an arrival pairs the media timestamp with milliseconds since the MoQ epoch", () => { + const tally = new Tally(); + tally.arrive(live, Milli(1234.9)); + const arrival = tally.report(live.path).video.arrival; + expect(arrival?.timestamp).toBe(1234); + expect(arrival?.wall).toBeCloseTo(Date.now() - Catalog.MOQ_EPOCH_UNIX_MILLIS, -3); +}); + +test("keeps the most recent few catalog broadcasts", () => { + const tally = new Tally(); + for (let n = 0; n < 6; n++) tally.count({ path: Path.from(`b${n}.hang`), id: "video" }, { frames: 1 }); + expect(tally.report(Path.from("b0.hang"))).toEqual({}); + expect(tally.report(Path.from("b5.hang"))).toEqual({ video: { frames: 1 } }); +}); diff --git a/js/watch/src/ui/stats.ts b/js/watch/src/ui/stats.ts index 1c2a5dc5551..20e9a320d03 100644 --- a/js/watch/src/ui/stats.ts +++ b/js/watch/src/ui/stats.ts @@ -73,6 +73,9 @@ export function statsTab(parent: Effect, watch: MoqWatch): HTMLElement { const videoCard = card("video", "Video", videoIcon); const vRes = line(videoCard.grid, "Resolution"); const vCodec = line(videoCard.grid, "Codec"); + // The same decoder counters the viewer's feedback reports. + const vLate = line(videoCard.grid, "Late frames"); + const vStalls = line(videoCard.grid, "Stalls"); const vBitrateGraph = graph(parent, "Bitrate", { color: "#a855f7", format: formatBitrate }); const vFpsGraph = graph(parent, "Frame rate", { color: "#facc15", format: formatFps }); videoCard.el.append(vBitrateGraph.el, vFpsGraph.el); @@ -89,6 +92,7 @@ export function statsTab(parent: Effect, watch: MoqWatch): HTMLElement { const aChannels = line(audioCard.grid, "Channels"); const aBitrate = line(audioCard.grid, "Bitrate"); const aUnderruns = line(audioCard.grid, "Underruns"); + const aLate = line(audioCard.grid, "Late frames"); track(parent, audioCard, { catalog: watch.audio.source.out.catalog, flag: watch.controls.audio.muted, @@ -130,6 +134,8 @@ export function statsTab(parent: Effect, watch: MoqWatch): HTMLElement { vBitrateGraph.push(vBitrate); vFpsGraph.push(fps); if (vStats) vPrev = { frames: vStats.frameCount, bytes: vStats.bytesReceived, when: now }; + vLate.textContent = vStats ? `${vStats.late}` : "—"; + vStalls.textContent = vStats ? `${vStats.stalls} (${formatMillis(vStats.stalled)})` : "—"; // Audio. const aConf = watch.audio.source.out.config.peek(); @@ -144,6 +150,7 @@ export function statsTab(parent: Effect, watch: MoqWatch): HTMLElement { // A non-zero count means the target is below what arrivals actually need. const aUnder = aStats?.underruns ?? 0; aUnderruns.textContent = watch.audio.out.stalled.peek() ? `${aUnder} (buffering)` : `${aUnder}`; + aLate.textContent = aStats ? `${aStats.late}` : "—"; // Network. "Estimated max" is the congestion controller / PROBE estimate; // "Actual" is the goodput we measure from the video + audio byte counters. From 4d6d15c07dcc56ad5b3da606a6ac71e57cd8b05c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 23:38:05 -0700 Subject: [PATCH 04/13] quest: finish browser stats and feedback reporters --- quest/m2/stats/README.md | 2 -- quest/m2/stats/health-consumers.md | 9 ++---- quest/m2/stats/js.md | 46 ------------------------------ 3 files changed, 3 insertions(+), 54 deletions(-) delete mode 100644 quest/m2/stats/js.md diff --git a/quest/m2/stats/README.md b/quest/m2/stats/README.md index 98046d562b1..16b57ff8b0d 100644 --- a/quest/m2/stats/README.md +++ b/quest/m2/stats/README.md @@ -113,8 +113,6 @@ connection view and the dashboard flow. - [Rust reporters](/quest/m2/stats/rust.md) - the player, encoders, and gateways publish stats and feedback, as the CLI remuxes do -- [Browser reporters](/quest/m2/stats/js.md) - `` publishes - stats and `` publishes feedback - [Preflight](/quest/m2/stats/preflight.md) - a bounded test run over a broadcast reports which media layer is broken and why - [Client health in use](/quest/m2/stats/health-consumers.md) - a per-connection media counter, consumers of the grade, and re-measured limits diff --git a/quest/m2/stats/health-consumers.md b/quest/m2/stats/health-consumers.md index dc247051e11..7ac2ae86095 100644 --- a/quest/m2/stats/health-consumers.md +++ b/quest/m2/stats/health-consumers.md @@ -15,9 +15,6 @@ grade's limits are re-measured against browser reporters. only for a connection's sole broadcast until then. - Consumers: preflight is planned in [Preflight](/quest/m2/stats/preflight.md); add the demo dashboard and a `moq` CLI sink. -- Re-measure the thresholds in `rs/hang/src/health.rs` once - [Browser reporters](/quest/m2/stats/js.md) publish real numbers. - -## Required - -- [Browser reporters](/quest/m2/stats/js.md) - the browser numbers the limits are measured against +- Re-measure the thresholds in `rs/hang/src/health.rs` against the numbers + the browser reporters publish (`` and + ``). diff --git a/quest/m2/stats/js.md b/quest/m2/stats/js.md deleted file mode 100644 index bea3cad59d3..00000000000 --- a/quest/m2/stats/js.md +++ /dev/null @@ -1,46 +0,0 @@ -# [M] The browser publisher and player report stats and feedback - -## Goal - -`` announces a stats track in its catalog and fills it, and an -attribute solicits feedback by setting the catalog's `echo` section. -``, given an echo name, publishes an `.echo` broadcast under the -echo path of a catalog soliciting feedback. Both use the `@moq/hang` schemas. - -## Plan - -- `js/publish`: - - The encoder `Stats` signals are already per rendition (`frames`, - `bytes`, `keyframes`). Add drops and the target bitrate. - - Fold them into the stats snapshot keyed by rendition ID, and write it - through the `@moq/json` snapshot producer on one track with - `compress: true`, matching the [m1 compression migration](https://github.com/moq-dev/moq/pull/7046). - A `stats` attribute enables it. - - `transport` carries PROBE rtt only, because `WebTransport.getStats()` - returns nothing useful in Chromium or Firefox today. - - An `echo-path` attribute sets the catalog's `echo` section, matching - Rust's `moq import --echo-path` (decided 2026-10-22, maintainer). -- `js/watch`: - - The decoder `Stats` signals grow late frames, stalls and stalled - duration, underruns from the worklet's count, decode errors, and the - newest arrival. - - An `echo` attribute names the viewer, refused unless it is one path - segment, as in Rust. Once a watched catalog carries an - `echo` section, the element resolves the echo path against the broadcast, - appends `.echo`, and publishes there with the fixed feedback track, keyed by rendition ID, the same rule as - Rust, and reconciles it on each catalog update like Rust. - - Watch elements on one connection watching the same catalog under one - name share its producer, because a second `createBroadcast` at a path - closes the first. -- The existing UI stats panels read the same signals. -- The demo sets both attributes, so the media test can read a browser - viewer's feedback through `moq export echo`. -- `doc/lib/js` documents the attributes. -- Decided 2026-10-08: no E2EE refusal here. The elements have no encrypted - broadcast yet, so [Encrypted browser components](/quest/m2/e2ee/browser.md) refuses the - stats track and the `echo` attribute when it adds one: they would publish - rendition IDs and per-track counters in plaintext beside it. - -## Related - -- [Encrypted browser components](/quest/m2/e2ee/browser.md) - refuses stats and feedback on an encrypted broadcast From 5daefb9fe2c305e3659c1d0337c4ae9890960609 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 21:26:49 -0800 Subject: [PATCH 05/13] fix(watch): clock-lint the feedback tests and unblock the latency ledger The feedback tests used the global setTimeout and Date that main's clock lint now denies; they yield and read the wall clock through @moq/clock. The latency ledger quest, added on main, required this quest, which this PR finishes. Co-Authored-By: Claude Opus 5.5 --- js/watch/src/echo.test.ts | 4 ++-- js/watch/src/feedback.test.ts | 4 ++-- quest/m2/latency-ledger.md | 1 - 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index ade54575ce9..ea7d79d7880 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { Manual, Milli, Nano } from "@moq/clock"; +import { Manual, Milli, Nano, yieldNow } from "@moq/clock"; import { Echo as Schema } from "@moq/hang"; import type * as Catalog from "@moq/hang/catalog"; import * as Json from "@moq/json"; @@ -10,7 +10,7 @@ import { checkName, Echo } from "./echo"; import type { Received } from "./feedback"; const flush = async (): Promise => { - for (let i = 0; i < 5; i++) await new Promise((resolve) => setTimeout(resolve, 0)); + for (let i = 0; i < 5; i++) await yieldNow(); }; // A watched broadcast whose catalog the test sets directly. diff --git a/js/watch/src/feedback.test.ts b/js/watch/src/feedback.test.ts index 37bacbfd55c..62a65f5b691 100644 --- a/js/watch/src/feedback.test.ts +++ b/js/watch/src/feedback.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { Manual, Milli, Nano } from "@moq/clock"; +import { Manual, Milli, Nano, wall } from "@moq/clock"; import * as Catalog from "@moq/hang/catalog"; import { Path } from "@moq/net"; import { Tally } from "./feedback"; @@ -38,7 +38,7 @@ test("an arrival pairs the media timestamp with milliseconds since the MoQ epoch tally.arrive(live, Milli(1234.9)); const arrival = tally.report(live.path).video.arrival; expect(arrival?.timestamp).toBe(1234); - expect(arrival?.wall).toBeCloseTo(Date.now() - Catalog.MOQ_EPOCH_UNIX_MILLIS, -3); + expect(arrival?.wall).toBeCloseTo(wall() - Catalog.MOQ_EPOCH_UNIX_MILLIS, -3); }); test("keeps the most recent few catalog broadcasts", () => { diff --git a/quest/m2/latency-ledger.md b/quest/m2/latency-ledger.md index afc6242490e..a9b15b73e79 100644 --- a/quest/m2/latency-ledger.md +++ b/quest/m2/latency-ledger.md @@ -48,7 +48,6 @@ probes, which was the right trade to get it running. This quest promotes them. ## Required -- [Browser reporters](/quest/m2/stats/js.md) - `` publishes the feedback snapshot these stages join - [Rust reporters](/quest/m2/stats/rust.md) - `moq play --echo` publishes the feedback snapshot these stages join ## Related From d7e8dede2cdce309a9a0d60f61c3553575b987e0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 22:02:49 -0800 Subject: [PATCH 06/13] chore(js): refresh the public API reports for stats and feedback Co-Authored-By: Claude Opus 5.5 --- js/hang/api/index.api.md | 13 +++++++++++++ js/publish/api/element.api.md | 10 ++++++++-- js/publish/api/index.api.md | 16 ++++++++++++++++ js/watch/api/element.api.md | 6 ++++-- js/watch/api/index.api.md | 16 ++++++++++++++++ 5 files changed, 57 insertions(+), 4 deletions(-) diff --git a/js/hang/api/index.api.md b/js/hang/api/index.api.md index 4b26a93bb4b..a29e83c26e3 100644 --- a/js/hang/api/index.api.md +++ b/js/hang/api/index.api.md @@ -15,6 +15,7 @@ import { ZodMiniPipe } from "@zod/mini"; import { ZodMiniRecord } from "@zod/mini"; import { ZodMiniString } from "@zod/mini"; import { ZodMiniTransform } from "@zod/mini"; +import { ZodMiniType } from "@zod/mini"; import { infer } from "@zod/mini"; export * as Catalog from "@moq/hang/catalog"; @@ -190,6 +191,18 @@ export namespace Hls { export * as Net from "@moq/net"; +export namespace Report { + export const INTERVAL: 1000; + export const PRIORITY: -128; + export class Writer { + constructor(broadcast: Net.Broadcast.Producer, name: string, schema?: ZodMiniType); + finish(): void; + readonly track: Net.Track.Producer; + update(value: T): void; + get wanted(): boolean; + } +} + export * as Signals from "@moq/signals"; export namespace Stats { diff --git a/js/publish/api/element.api.md b/js/publish/api/element.api.md index 54490b28255..8470d0b8f2b 100644 --- a/js/publish/api/element.api.md +++ b/js/publish/api/element.api.md @@ -17,7 +17,7 @@ export default class extends HTMLElement { constructor(); get announce(): AnnounceMode | undefined; set announce(value: AnnounceMode); - attributeChangedCallback(name: "source" | "url" | "announce" | "name" | "backend" | "versions" | "muted" | "invisible" | "preview", oldValue: string | null, newValue: string | null): void; + attributeChangedCallback(name: "source" | "url" | "stats" | "announce" | "name" | "backend" | "versions" | "muted" | "invisible" | "preview" | "echo-path", oldValue: string | null, newValue: string | null): void; audio: Audio.Encoder; get backend(): Preview.Backend; set backend(value: Preview.Backend); @@ -27,19 +27,23 @@ export default class extends HTMLElement { readonly controls: { announce: Signals.Signal; backend: Signals.Signal; + echoPath: Signals.Signal; invisible: Signals.Signal; muted: Signals.Signal; preview: Signals.Signal; source: Signals.Signal; + stats: Signals.Signal; }; disconnectedCallback(): void; + get echoPath(): Net.Path.Relative | undefined; + set echoPath(value: string | undefined); get invisible(): boolean; set invisible(value: boolean); get muted(): boolean; set muted(value: boolean); get name(): Net.Path.Valid; set name(value: string | Net.Path.Valid); - static observedAttributes: readonly ["url", "versions", "name", "muted", "invisible", "source", "preview", "backend", "announce"]; + static observedAttributes: readonly ["url", "versions", "name", "muted", "invisible", "source", "preview", "backend", "announce", "stats", "echo-path"]; get preview(): Preview.Mode; set preview(value: Preview.Mode); readonly signals: Signals.Effect; @@ -50,6 +54,8 @@ export default class extends HTMLElement { file: Signals.Signal; video: Signals.Signal; }>; + get stats(): boolean; + set stats(value: boolean); get url(): URL | undefined; set url(value: string | URL | undefined); get versions(): readonly string[] | undefined; diff --git a/js/publish/api/index.api.md b/js/publish/api/index.api.md index 7f85518b9c5..8d018ac7cd4 100644 --- a/js/publish/api/index.api.md +++ b/js/publish/api/index.api.md @@ -91,6 +91,7 @@ export namespace Audio { track: Audio.StreamTrack; } export interface Stats { + bitrate?: number; bytes: number; frames: number; } @@ -117,6 +118,7 @@ export namespace Audio { export class Broadcast { constructor(props?: Signals.Inputs); static readonly CATALOG_TRACK: "catalog.json"; + static readonly STATS_TRACK: "stats.json"; audio(name: string): Rendition; readonly catalog: CatalogProducer; close(): void; @@ -132,13 +134,16 @@ export type BroadcastInput = { height: number; width: number; } | undefined>; + echo: Signals.Getter; enabled: Signals.Getter; flip: Signals.Getter; maxAge: Signals.Getter; name: Signals.Getter; onDemand: Signals.Getter; origin: Signals.Getter; + probe: Signals.Getter; rotation: Signals.Getter; + stats: Signals.Getter; }; export class CatalogProducer { @@ -215,9 +220,18 @@ export class Rendition { readonly config: Signals.Signal; readonly kind: Kind; readonly name: string; + readonly stats: Signals.Signal; readonly track: Signals.Getter; } +export interface RenditionStats { + bitrate?: number; + bytes?: number; + frames?: number; + keyframes?: number; + skipped?: number; +} + export * as Signals from "@moq/signals"; export namespace Source { @@ -394,9 +408,11 @@ export namespace Video { track: Video.StreamTrack; } export interface Stats { + bitrate?: number; bytes: number; frames: number; keyframes: number; + skipped: number; } export interface StreamTrack extends MediaStreamTrack { clone(): Video.StreamTrack; diff --git a/js/watch/api/element.api.md b/js/watch/api/element.api.md index 3c3ed50a4ec..e935bd1b270 100644 --- a/js/watch/api/element.api.md +++ b/js/watch/api/element.api.md @@ -16,7 +16,7 @@ import { Video } from "@moq/watch"; export default class extends HTMLElement { constructor(); - attributeChangedCallback(name: "delay" | "buffer" | "follow" | "announced" | "url" | "name" | "volume" | "muted" | "paused" | "visible" | "backend" | "versions" | "catalog-format" | "captions", oldValue: string | null, newValue: string | null): void; + attributeChangedCallback(name: "delay" | "buffer" | "follow" | "announced" | "url" | "echo" | "name" | "volume" | "muted" | "paused" | "visible" | "backend" | "versions" | "catalog-format" | "captions", oldValue: string | null, newValue: string | null): void; readonly audio: Audio.Decoder; get backend(): Video.Backend; set backend(value: Video.Backend); @@ -52,6 +52,8 @@ export default class extends HTMLElement { get delay(): Delay; set delay(value: Delay); disconnectedCallback(): void; + get echo(): string | undefined; + set echo(value: string | undefined); emitter: Audio.Emitter; get follow(): boolean; set follow(value: boolean); @@ -59,7 +61,7 @@ export default class extends HTMLElement { set muted(value: boolean); get name(): Net.Path.Valid; set name(value: string | Net.Path.Valid); - static observedAttributes: readonly ["url", "versions", "name", "paused", "volume", "muted", "visible", "backend", "follow", "announced", "delay", "buffer", "catalog-format", "captions"]; + static observedAttributes: readonly ["url", "versions", "name", "paused", "volume", "muted", "visible", "backend", "follow", "announced", "delay", "buffer", "catalog-format", "captions", "echo"]; get paused(): boolean; set paused(value: boolean); readonly player: Player; diff --git a/js/watch/api/index.api.md b/js/watch/api/index.api.md index 16172b792d3..57850dfcd62 100644 --- a/js/watch/api/index.api.md +++ b/js/watch/api/index.api.md @@ -84,7 +84,15 @@ export namespace Audio { track: Signals.Signal; }; export interface Stats { + arrival?: { + timestamp: Clock.Milli; + wall: Clock.Wall; + }; bytesReceived: number; + errors: number; + late: number; + stalled: Clock.Milli; + stalls: number; underruns: number; } export type Supported = (config: Hang.Catalog.Audio.AudioConfig) => Promise; @@ -310,8 +318,16 @@ export namespace Video { track: Signals.Signal; }; export interface Stats { + arrival?: { + timestamp: Clock.Milli; + wall: Clock.Wall; + }; bytesReceived: number; + errors: number; frameCount: number; + late: number; + stalled: Clock.Milli; + stalls: number; } export type Supported = (config: Hang.Catalog.Video.VideoConfig) => Promise; export type Target = { From 6b5d78e60ba05279a3cee4593f2e9472e97cb3ba Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 22:16:52 -0800 Subject: [PATCH 07/13] fix(watch): feedback belongs to one catalog, without retaining departed reporters A feedback broadcast belongs to one soliciting catalog (hang draft, media-stats), so a reporter for another catalog that resolves a path in use now publishes nothing and warns instead of summing two catalogs' counters, and the demo gives each tile its own name. Departed reporters' final counts fold into one sum, with a weak per-owner share for a returning one, so they are not retained. A tally keeps at most 1024 rendition IDs per catalog broadcast, like Rust's registry. Co-Authored-By: Claude Opus 5.5 --- demo/web/src/index.ts | 8 ++-- doc/lib/js/watch.md | 4 +- js/watch/src/echo.test.ts | 67 ++++++++++++++++++++++++++++++++++ js/watch/src/echo.ts | 69 ++++++++++++++++++++++++++++------- js/watch/src/element.ts | 6 ++- js/watch/src/feedback.test.ts | 9 +++++ js/watch/src/feedback.ts | 9 +++++ 7 files changed, 153 insertions(+), 19 deletions(-) diff --git a/demo/web/src/index.ts b/demo/web/src/index.ts index a312c9f0756..55958c73391 100644 --- a/demo/web/src/index.ts +++ b/demo/web/src/index.ts @@ -79,9 +79,11 @@ const metaSignal = new Signals.Signal(undefined); // tile's follow it reactively. const relayUrl = new Signals.Signal(new URL(RELAY_URL)); -// This page's feedback name: a tile whose catalog solicits feedback publishes `/.echo`, -// which `moq export echo` reads. Tiles of one broadcast share it and add their counts. +// This page's feedback name: a tile whose catalog solicits feedback publishes +// `/-.echo`, which `moq export echo` reads. Each tile takes its own name, +// since a feedback broadcast belongs to one catalog and two broadcasts may solicit the same path. const VIEWER = `viewer-${crypto.randomUUID().slice(0, 8)}`; +let tileCount = 0; // Discovery connection (the tiles each open their own connection internally). const connection = new Net.Connection({ url: relayUrl }); @@ -123,7 +125,7 @@ function createTile(name: string): WatchTile { // `broadcast` and decoders, so the shared inspector panel reflects the active tile. const watch = document.createElement("moq-watch") as MoqWatch; watch.name = name; - watch.echo = VIEWER; + watch.echo = `${VIEWER}-${++tileCount}`; watch.muted = true; // unmuted only while active (see below) const canvas = document.createElement("canvas"); canvas.style.cssText = "width: 100%; height: auto;"; diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index ddb4106aae1..cd0cbaaf22e 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -80,7 +80,9 @@ stalled time, audio underruns, and the newest arrival, plus the PROBE round-trip time. It writes about once a second while someone subscribes, and follows the catalog: a removed or moved section retracts the broadcast. Players on one connection watching the same catalog under one name share it and add -their counts. The decoders' `out.stats` and the stats panel read the same +their counts. A feedback broadcast belongs to one catalog, so a player watching +another catalog that solicits the same path under the same name publishes +nothing and warns; give each catalog's player its own name. The decoders' `out.stats` and the stats panel read the same counters. The token must allow publishing under the echo path. ## Binding from a framework diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index ea7d79d7880..af146e7944c 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -150,3 +150,70 @@ test("reporters resolving one feedback path share its broadcast and add their co installed.close(); } }); + +test("a reporter for another catalog at a path in use publishes nothing", async () => { + const clock = new Manual(); + const installed = clock.install(); + const origin = new Origin.Producer(); + const paths = announced(origin); + const catalog = new Signal({ echo: { path: "viewers" } } as Catalog.Root); + const a = watched(origin, "room/a.hang", catalog); + const b = watched(origin, "room/b.hang", catalog); + const reporters = [ + new Echo({ broadcast: a, origin, name: "alice", sources: [source("room/a.hang", { video: { frames: 2 } })] }), + new Echo({ broadcast: b, origin, name: "alice", sources: [source("room/b.hang", { video: { frames: 100 } })] }), + ]; + try { + await flush(); + expect([...paths]).toEqual(["room/viewers/alice.echo"]); + // Only the first catalog's counts, never a sum across catalogs. + expect((await read(origin, "room/viewers/alice.echo", clock)) as unknown).toEqual({ + renditions: { video: { frames: 2 } }, + }); + } finally { + for (const reporter of reporters) reporter.close(); + a.close(); + b.close(); + origin.close(); + installed.close(); + } +}); + +test("a reporter that leaves and returns is counted once", async () => { + const clock = new Manual(); + const installed = clock.install(); + const origin = new Origin.Producer(); + const catalog = new Signal({ echo: { path: "viewers" } } as Catalog.Root); + const broadcast = watched(origin, "room/live.hang", catalog); + const enabled = new Signal(true); + const staying = new Echo({ + broadcast, + origin, + name: "alice", + sources: [source("room/live.hang", { video: { frames: 1 } })], + }); + const returning = new Echo({ + broadcast, + origin, + enabled, + name: "alice", + sources: [source("room/live.hang", { video: { frames: 10 } })], + }); + try { + await flush(); + enabled.set(false); + await flush(); + // The departed reporter's final counts stay in the report. + expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(11); + + enabled.set(true); + await flush(); + expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(11); + } finally { + staying.close(); + returning.close(); + broadcast.close(); + origin.close(); + installed.close(); + } +}); diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index 4e8ff0fbf34..cdeb53fbbfe 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -57,8 +57,10 @@ export function checkName(name: string): string { * that catalog, and the connection's PROBE round-trip time. Each catalog update reconciles it: a * removed section, or a changed path, retracts the broadcast it replaces. * - * Reporters on one origin that resolve the same feedback path share one broadcast and add their - * counts, since a second broadcast at a path would replace the first. + * Reporters on one origin that resolve the same feedback path for the same catalog share one + * broadcast and add their counts, since a second broadcast at a path would replace the first. A + * feedback broadcast belongs to one soliciting catalog, so a reporter for another catalog that + * resolves a path already in use publishes nothing and warns: give it another name. */ export class Echo { /** The wired inputs, read-only. */ @@ -100,7 +102,7 @@ export class Echo { let shared: Shared; try { - shared = Shared.acquire(current.origin, current.path); + shared = Shared.acquire(current.origin, current.path, current.base); } catch (err) { console.warn("failed to publish feedback", current.path, err); return; @@ -133,37 +135,56 @@ export class Echo { const published = new WeakMap>(); class Shared { + /** The broadcast whose catalog solicited this feedback, which it belongs to. */ + readonly base: Moq.Path.Valid; + readonly #origin: Moq.Origin.Table; readonly #path: Moq.Path.Valid; readonly #broadcast: Moq.Broadcast.Producer; readonly #writer: Report.Writer; // Each reporter's counts, keyed by its owner. readonly #reporters = new Map Snapshot>(); - // What each owner that left last reported, so the counters stay cumulative without it. Its counts - // are cumulative, so a returning owner reports them again itself. - readonly #retired = new Map(); + // The final counts of the owners that left, summed, so the counters stay cumulative without them. + #departed: Snapshot = { renditions: {} }; + // Each departed owner's share of #departed. Its counts are cumulative, so a returning owner takes + // its share back out and reports it again itself. Weak, so a departed owner is not retained. + readonly #shares = new WeakMap(); #signals = new Effect(); /** Whether anyone reads the feedback, which is when it is written. */ readonly watched: Getter; - static acquire(origin: Moq.Origin.Table, path: Moq.Path.Valid): Shared { + /** + * The feedback broadcast at `path` for the catalog of the broadcast at `base`. Throws when it + * already reports for another catalog, since a second broadcast at the path would replace it. + */ + static acquire(origin: Moq.Origin.Table, path: Moq.Path.Valid, base: Moq.Path.Valid): Shared { let paths = published.get(origin); if (!paths) { paths = new Map(); published.set(origin, paths); } let shared = paths.get(path); + if (shared && shared.base !== base) { + if (shared.#reporters.size > 0) { + throw new Error(`${path} already reports feedback for the catalog of ${shared.base}`); + } + // Every reporter for the other catalog left, and its retraction is still pending: retract now. + paths.delete(path); + shared.#close(); + shared = undefined; + } if (!shared) { - shared = new Shared(origin, path); + shared = new Shared(origin, path, base); paths.set(path, shared); } return shared; } - private constructor(origin: Moq.Origin.Table, path: Moq.Path.Valid) { + private constructor(origin: Moq.Origin.Table, path: Moq.Path.Valid, base: Moq.Path.Valid) { this.#origin = origin; this.#path = path; + this.base = base; const publication = origin.createBroadcast(path); this.#broadcast = publication.broadcast; try { @@ -181,12 +202,18 @@ class Shared { /** Add `owner`'s counts to the feedback, returning the function that removes them. */ join(owner: object, reporter: () => Snapshot): () => void { - this.#retired.delete(owner); + const share = this.#shares.get(owner); + if (share) { + this.#shares.delete(owner); + this.#departed = subtract(this.#departed, share); + } this.#reporters.set(owner, reporter); return () => { if (this.#reporters.get(owner) !== reporter) return; this.#reporters.delete(owner); - this.#retired.set(owner, { renditions: reporter().renditions }); + const final: Snapshot = { renditions: reporter().renditions }; + this.#shares.set(owner, final); + this.#departed = merge(this.#departed, final); // Deferred, so a reporter's rerun reuses the broadcast rather than replacing it. queueMicrotask(() => { if (this.#reporters.size > 0 || published.get(this.#origin)?.get(this.#path) !== this) return; @@ -198,9 +225,8 @@ class Shared { #write(): void { if (!this.#writer.wanted) return; - let snapshot: Snapshot = { renditions: {} }; + let snapshot = this.#departed; for (const reporter of this.#reporters.values()) snapshot = merge(snapshot, reporter()); - for (const retired of this.#retired.values()) snapshot = merge(snapshot, retired); this.#writer.update(snapshot as Schema.Snapshot); } @@ -231,3 +257,20 @@ function merge(a: Snapshot, b: Snapshot): Snapshot { const transport = a.transport ?? b.transport; return transport ? { transport, renditions } : { renditions }; } + +// Take a departed reporter's counters back out of `a`. The newest arrival stays, since it is a gauge. +function subtract(a: Snapshot, b: Snapshot): Snapshot { + const renditions: Record = { ...a.renditions }; + for (const [id, received] of Object.entries(b.renditions)) { + const rest: Received = { ...renditions[id] }; + for (const [counter, n] of Object.entries(received)) { + if (counter === "arrival") continue; + const key = counter as Exclude; + const left = (rest[key] ?? 0) - (n as number); + if (left > 0) rest[key] = left; + else delete rest[key]; + } + renditions[id] = rest; + } + return { ...a, renditions }; +} diff --git a/js/watch/src/element.ts b/js/watch/src/element.ts index 03027806141..5e75cd50f2a 100644 --- a/js/watch/src/element.ts +++ b/js/watch/src/element.ts @@ -632,8 +632,10 @@ export default class MoqWatch extends HTMLElement { /** * The viewer's feedback name, mirrored by the `echo` attribute; undefined (the default) publishes * no feedback. Once the watched catalog solicits feedback with an `echo` section, the element - * publishes `.echo` under its path, reporting what each rendition received and played. One - * visible path segment: a `/` or a leading `.` is refused. + * publishes `.echo` under its path, reporting what each rendition received and played. + * Elements on one connection watching the same catalog under one name share it; one watching + * another catalog that solicits the same path needs its own name. One visible path segment: a `/` + * or a leading `.` is refused. */ get echo(): string | undefined { return this.#echo.peek(); diff --git a/js/watch/src/feedback.test.ts b/js/watch/src/feedback.test.ts index 62a65f5b691..c3ce9b9aab8 100644 --- a/js/watch/src/feedback.test.ts +++ b/js/watch/src/feedback.test.ts @@ -47,3 +47,12 @@ test("keeps the most recent few catalog broadcasts", () => { expect(tally.report(Path.from("b0.hang"))).toEqual({}); expect(tally.report(Path.from("b5.hang"))).toEqual({ video: { frames: 1 } }); }); + +test("keeps a bounded number of rendition IDs per catalog broadcast, dropping the oldest", () => { + const tally = new Tally(); + for (let n = 0; n <= 1024; n++) tally.count({ ...live, id: `r${n}` }, { frames: 1 }); + const report = tally.report(live.path); + expect(Object.keys(report)).toHaveLength(1024); + expect(report.r0).toBeUndefined(); + expect(report.r1024).toEqual({ frames: 1 }); +}); diff --git a/js/watch/src/feedback.ts b/js/watch/src/feedback.ts index 65414b2ee76..d3aefea516b 100644 --- a/js/watch/src/feedback.ts +++ b/js/watch/src/feedback.ts @@ -26,6 +26,11 @@ export interface Key { // incoming one, so a few cover it without holding every broadcast ever watched. const MAX_BROADCASTS = 4; +// The most rendition IDs a tally keeps per catalog broadcast, so a catalog that keeps renaming its +// renditions cannot grow it, or each report, without bound. Matches the Rust registry's limit. The +// oldest makes way; one still counting into it starts over, which a reader treats as a reset. +const MAX_RENDITIONS = 1024; + type Entry = { received: Received; stalling?: Instant }; /** @@ -49,6 +54,10 @@ export class Tally { if (!entry) { entry = { received: {} }; renditions.set(key.id, entry); + if (renditions.size > MAX_RENDITIONS) { + const oldest = renditions.keys().next().value; + if (oldest !== undefined) renditions.delete(oldest); + } } return entry; } From 337d9fea486d2d9b88eb36a88615c195b2e2e1a2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 22:36:38 -0800 Subject: [PATCH 08/13] fix(watch): bound departed reporters' rendition IDs like a tally Co-Authored-By: Claude Opus 5.5 --- js/watch/src/echo.test.ts | 31 +++++++++++++++++++++++++++++++ js/watch/src/echo.ts | 6 ++++-- js/watch/src/feedback.ts | 18 ++++++++++++++---- 3 files changed, 49 insertions(+), 6 deletions(-) diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index af146e7944c..96b7509dc5e 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -217,3 +217,34 @@ test("a reporter that leaves and returns is counted once", async () => { installed.close(); } }); + +test("departed reporters' rendition IDs stay bounded", async () => { + const clock = new Manual(); + const installed = clock.install(); + const origin = new Origin.Producer(); + const catalog = new Signal({ echo: { path: "viewers" } } as Catalog.Root); + const broadcast = watched(origin, "room/live.hang", catalog); + const staying = new Echo({ broadcast, origin, name: "alice", sources: [source("room/live.hang", {})] }); + try { + await flush(); + for (let n = 0; n <= 1024; n++) { + const leaving = new Echo({ + broadcast, + origin, + name: "alice", + sources: [source("room/live.hang", { [`r${n}`]: { frames: 1 } })], + }); + await flush(); + leaving.close(); + } + await flush(); + const renditions = (await read(origin, "room/viewers/alice.echo", clock))?.renditions ?? {}; + expect(Object.keys(renditions)).toHaveLength(1024); + expect(renditions.r0).toBeUndefined(); + } finally { + staying.close(); + broadcast.close(); + origin.close(); + installed.close(); + } +}); diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index cdeb53fbbfe..7e54aec18c0 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -3,7 +3,7 @@ import { Report, Echo as Schema } from "@moq/hang"; import * as Moq from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys } from "@moq/signals"; import type { Broadcast } from "./broadcast"; -import type { Received } from "./feedback"; +import { bound, type Received } from "./feedback"; /** A viewer report as written: per-rendition counters and the connection's round-trip time. */ type Snapshot = { transport?: { rtt: number }; renditions: Record }; @@ -213,7 +213,9 @@ class Shared { this.#reporters.delete(owner); const final: Snapshot = { renditions: reporter().renditions }; this.#shares.set(owner, final); - this.#departed = merge(this.#departed, final); + // Bounded like a tally, so departures that each read fresh rendition IDs cannot grow it. + const departed = merge(this.#departed, final); + this.#departed = { renditions: bound(departed.renditions) }; // Deferred, so a reporter's rerun reuses the broadcast rather than replacing it. queueMicrotask(() => { if (this.#reporters.size > 0 || published.get(this.#origin)?.get(this.#path) !== this) return; diff --git a/js/watch/src/feedback.ts b/js/watch/src/feedback.ts index d3aefea516b..cef5e68a0a2 100644 --- a/js/watch/src/feedback.ts +++ b/js/watch/src/feedback.ts @@ -26,10 +26,20 @@ export interface Key { // incoming one, so a few cover it without holding every broadcast ever watched. const MAX_BROADCASTS = 4; -// The most rendition IDs a tally keeps per catalog broadcast, so a catalog that keeps renaming its -// renditions cannot grow it, or each report, without bound. Matches the Rust registry's limit. The -// oldest makes way; one still counting into it starts over, which a reader treats as a reset. -const MAX_RENDITIONS = 1024; +/** + * The most rendition IDs a tally keeps per catalog broadcast, and a feedback report keeps of its + * departed reporters, so a catalog that keeps renaming its renditions cannot grow either, or each + * report, without bound. Matches the Rust registry's limit. The oldest makes way; one still counting + * into it starts over, which a reader treats as a reset. + */ +export const MAX_RENDITIONS = 1024; + +/** Drop the oldest entries of `renditions` beyond {@link MAX_RENDITIONS}, in insertion order. */ +export function bound(renditions: Record): Record { + const ids = Object.keys(renditions); + if (ids.length <= MAX_RENDITIONS) return renditions; + return Object.fromEntries(ids.slice(ids.length - MAX_RENDITIONS).map((id) => [id, renditions[id]])); +} type Entry = { received: Received; stalling?: Instant }; From c0f72601bdc75bc409dfbb75bd584ad4a4c29609 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 22:57:36 -0800 Subject: [PATCH 09/13] refactor(watch): a feedback reporter adds what it counted since joining The departed sum and a per-owner share ledger drifted apart once the sum was bounded: a returning reporter could subtract a share already evicted from the sum. Each reporter now joins with a baseline and reports only what it counts after it, so its earlier counts stay among the departed ones without any per-owner record, and the bounded sum needs nothing kept in step with it. Co-Authored-By: Claude Opus 5.5 --- js/watch/src/echo.test.ts | 15 +++++++++-- js/watch/src/echo.ts | 56 +++++++++++++++++++-------------------- 2 files changed, 40 insertions(+), 31 deletions(-) diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index 96b7509dc5e..5e10311cdea 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -18,9 +18,20 @@ function watched(origin: Origin.Producer, name: string, catalog: Signal) { - return { feedback: (base: Path.Valid) => (base === path ? received : {}) }; + let started = false; + return { + feedback: (base: Path.Valid) => { + if (base !== path) return {}; + if (!started) { + started = true; + return {}; + } + return received; + }, + }; } // The feedback broadcasts announced on `origin`, by path. diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index 7e54aec18c0..ebe8837b87e 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -58,9 +58,9 @@ export function checkName(name: string): string { * removed section, or a changed path, retracts the broadcast it replaces. * * Reporters on one origin that resolve the same feedback path for the same catalog share one - * broadcast and add their counts, since a second broadcast at a path would replace the first. A - * feedback broadcast belongs to one soliciting catalog, so a reporter for another catalog that - * resolves a path already in use publishes nothing and warns: give it another name. + * broadcast, since a second broadcast at a path would replace the first, and add what each counted + * since it joined. A feedback broadcast belongs to one soliciting catalog, so a reporter for another + * catalog that resolves a path already in use publishes nothing and warns: give it another name. */ export class Echo { /** The wired inputs, read-only. */ @@ -142,13 +142,10 @@ class Shared { readonly #path: Moq.Path.Valid; readonly #broadcast: Moq.Broadcast.Producer; readonly #writer: Report.Writer; - // Each reporter's counts, keyed by its owner. + // What each reporter counted since it joined, keyed by its owner. readonly #reporters = new Map Snapshot>(); - // The final counts of the owners that left, summed, so the counters stay cumulative without them. + // What the reporters that left counted, summed, so the counters stay cumulative without them. #departed: Snapshot = { renditions: {} }; - // Each departed owner's share of #departed. Its counts are cumulative, so a returning owner takes - // its share back out and reports it again itself. Weak, so a departed owner is not retained. - readonly #shares = new WeakMap(); #signals = new Effect(); /** Whether anyone reads the feedback, which is when it is written. */ @@ -200,21 +197,20 @@ class Shared { this.#signals.interval(() => this.#write(), Nano.fromMilli(Milli(Report.INTERVAL))); } - /** Add `owner`'s counts to the feedback, returning the function that removes them. */ + /** + * Add what `owner` counts from now on to the feedback, returning the function that removes it. + * Its reporter's counters are cumulative, so only what they add after joining is reported: a + * returning owner's earlier counts are already among the departed ones. + */ join(owner: object, reporter: () => Snapshot): () => void { - const share = this.#shares.get(owner); - if (share) { - this.#shares.delete(owner); - this.#departed = subtract(this.#departed, share); - } - this.#reporters.set(owner, reporter); + const baseline = reporter().renditions; + const counts = () => since(reporter(), baseline); + this.#reporters.set(owner, counts); return () => { - if (this.#reporters.get(owner) !== reporter) return; + if (this.#reporters.get(owner) !== counts) return; this.#reporters.delete(owner); - const final: Snapshot = { renditions: reporter().renditions }; - this.#shares.set(owner, final); // Bounded like a tally, so departures that each read fresh rendition IDs cannot grow it. - const departed = merge(this.#departed, final); + const departed = merge(this.#departed, { renditions: counts().renditions }); this.#departed = { renditions: bound(departed.renditions) }; // Deferred, so a reporter's rerun reuses the broadcast rather than replacing it. queueMicrotask(() => { @@ -260,19 +256,21 @@ function merge(a: Snapshot, b: Snapshot): Snapshot { return transport ? { transport, renditions } : { renditions }; } -// Take a departed reporter's counters back out of `a`. The newest arrival stays, since it is a gauge. -function subtract(a: Snapshot, b: Snapshot): Snapshot { - const renditions: Record = { ...a.renditions }; - for (const [id, received] of Object.entries(b.renditions)) { - const rest: Received = { ...renditions[id] }; +// What `current` counted since `baseline`. A counter below its baseline started over, such as an +// entry the tally dropped, so it counts from zero. The newest arrival and the transport are gauges. +function since(current: Snapshot, baseline: Record): Snapshot { + const renditions: Record = {}; + for (const [id, received] of Object.entries(current.renditions)) { + const added: Received = {}; for (const [counter, n] of Object.entries(received)) { if (counter === "arrival") continue; const key = counter as Exclude; - const left = (rest[key] ?? 0) - (n as number); - if (left > 0) rest[key] = left; - else delete rest[key]; + const base = baseline[id]?.[key] ?? 0; + const delta = (n as number) >= base ? (n as number) - base : (n as number); + if (delta > 0) added[key] = delta; } - renditions[id] = rest; + if (received.arrival) added.arrival = received.arrival; + if (Object.keys(added).length > 0) renditions[id] = added; } - return { ...a, renditions }; + return current.transport ? { transport: current.transport, renditions } : { renditions }; } From 50b4bcf5354980a067dfdec8fbe2c0af79a3e4ca Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 09:37:33 -0800 Subject: [PATCH 10/13] refactor(watch)!: each publishes its own feedback broadcast Drop the sharing of one feedback broadcast between elements on one connection watching the same catalog under one name. Every round of review found another edge case in the bookkeeping it needed: the departed sum, the per-owner ledger, and the join-time baselines. A second element resolving a feedback path already in use now publishes nothing and warns, the same rule as for a different catalog, so each report is just its own element's tally. Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/watch.md | 12 +-- js/watch/src/echo.test.ts | 124 +++++------------------- js/watch/src/echo.ts | 194 ++++++++------------------------------ js/watch/src/element.ts | 6 +- js/watch/src/feedback.ts | 16 +--- 5 files changed, 77 insertions(+), 275 deletions(-) diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index cd0cbaaf22e..05463e9c040 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -78,12 +78,12 @@ that path against the broadcast and publishes `alice.echo` there, with one under its catalog ID: frames, bytes, decoded, late, decode errors, stalls and stalled time, audio underruns, and the newest arrival, plus the PROBE round-trip time. It writes about once a second while someone subscribes, and -follows the catalog: a removed or moved section retracts the broadcast. Players -on one connection watching the same catalog under one name share it and add -their counts. A feedback broadcast belongs to one catalog, so a player watching -another catalog that solicits the same path under the same name publishes -nothing and warns; give each catalog's player its own name. The decoders' `out.stats` and the stats panel read the same -counters. The token must allow publishing under the echo path. +follows the catalog: a removed or moved section retracts the broadcast. Each +player publishes its own broadcast, reporting only what it counted, so a second +player on one connection that resolves the same feedback path, for any catalog, +publishes nothing and warns; give each player its own name. The decoders' +`out.stats` and the stats panel read the same counters. The token must allow +publishing under the echo path. ## Binding from a framework diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index 5e10311cdea..5de3259493b 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -18,20 +18,9 @@ function watched(origin: Origin.Producer, name: string, catalog: Signal) { - let started = false; - return { - feedback: (base: Path.Valid) => { - if (base !== path) return {}; - if (!started) { - started = true; - return {}; - } - return received; - }, - }; + return { feedback: (base: Path.Valid) => (base === path ? received : {}) }; } // The feedback broadcasts announced on `origin`, by path. @@ -117,7 +106,7 @@ test("publishes feedback where the catalog solicits it and follows the solicitat } }); -test("reporters resolving one feedback path share its broadcast and add their counts", async () => { +test("a second reporter at a feedback path in use publishes nothing until it is free", async () => { const clock = new Manual(); const installed = clock.install(); const origin = new Origin.Producer(); @@ -125,34 +114,39 @@ test("reporters resolving one feedback path share its broadcast and add their co const catalog = new Signal({ echo: { path: "viewers" } } as Catalog.Root); const first = watched(origin, "room/live.hang", catalog); const second = watched(origin, "room/live.hang", catalog); - const reporters = [first, second].map( - (broadcast, n) => - new Echo({ - broadcast, - origin, - name: "alice", - sources: [ - source("room/live.hang", { video: { frames: n + 1, arrival: { timestamp: n, wall: 100 + n } } }), - ], - }), - ); + const enabled = new Signal(true); + const reporters = [ + new Echo({ broadcast: first, origin, name: "alice", sources: [source("room/live.hang", { video: { frames: 1 } })] }), + new Echo({ + broadcast: second, + origin, + enabled, + name: "alice", + sources: [source("room/live.hang", { video: { frames: 10 } })], + }), + ]; try { await flush(); expect([...paths]).toEqual(["room/viewers/alice.echo"]); + // Only the first reporter's own counts, never a sum. expect((await read(origin, "room/viewers/alice.echo", clock)) as unknown).toEqual({ - renditions: { video: { frames: 3, arrival: { timestamp: 1, wall: 101 } } }, + renditions: { video: { frames: 1 } }, }); - // One leaving keeps its counts in the report, which stays cumulative. - reporters[1].close(); + // The refused one leaving changes nothing. + enabled.set(false); await flush(); expect([...paths]).toEqual(["room/viewers/alice.echo"]); - expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(3); + expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(1); - // The last one leaving retracts it. + // The holder leaving retracts it and frees the path for a reporter that asks again. reporters[0].close(); await flush(); expect([...paths]).toEqual([]); + enabled.set(true); + await flush(); + expect([...paths]).toEqual(["room/viewers/alice.echo"]); + expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(10); } finally { for (const reporter of reporters) reporter.close(); first.close(); @@ -189,73 +183,3 @@ test("a reporter for another catalog at a path in use publishes nothing", async installed.close(); } }); - -test("a reporter that leaves and returns is counted once", async () => { - const clock = new Manual(); - const installed = clock.install(); - const origin = new Origin.Producer(); - const catalog = new Signal({ echo: { path: "viewers" } } as Catalog.Root); - const broadcast = watched(origin, "room/live.hang", catalog); - const enabled = new Signal(true); - const staying = new Echo({ - broadcast, - origin, - name: "alice", - sources: [source("room/live.hang", { video: { frames: 1 } })], - }); - const returning = new Echo({ - broadcast, - origin, - enabled, - name: "alice", - sources: [source("room/live.hang", { video: { frames: 10 } })], - }); - try { - await flush(); - enabled.set(false); - await flush(); - // The departed reporter's final counts stay in the report. - expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(11); - - enabled.set(true); - await flush(); - expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(11); - } finally { - staying.close(); - returning.close(); - broadcast.close(); - origin.close(); - installed.close(); - } -}); - -test("departed reporters' rendition IDs stay bounded", async () => { - const clock = new Manual(); - const installed = clock.install(); - const origin = new Origin.Producer(); - const catalog = new Signal({ echo: { path: "viewers" } } as Catalog.Root); - const broadcast = watched(origin, "room/live.hang", catalog); - const staying = new Echo({ broadcast, origin, name: "alice", sources: [source("room/live.hang", {})] }); - try { - await flush(); - for (let n = 0; n <= 1024; n++) { - const leaving = new Echo({ - broadcast, - origin, - name: "alice", - sources: [source("room/live.hang", { [`r${n}`]: { frames: 1 } })], - }); - await flush(); - leaving.close(); - } - await flush(); - const renditions = (await read(origin, "room/viewers/alice.echo", clock))?.renditions ?? {}; - expect(Object.keys(renditions)).toHaveLength(1024); - expect(renditions.r0).toBeUndefined(); - } finally { - staying.close(); - broadcast.close(); - origin.close(); - installed.close(); - } -}); diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index ebe8837b87e..c8b9aa498af 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -3,7 +3,7 @@ import { Report, Echo as Schema } from "@moq/hang"; import * as Moq from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys } from "@moq/signals"; import type { Broadcast } from "./broadcast"; -import { bound, type Received } from "./feedback"; +import type { Received } from "./feedback"; /** A viewer report as written: per-rendition counters and the connection's round-trip time. */ type Snapshot = { transport?: { rtt: number }; renditions: Record }; @@ -57,10 +57,10 @@ export function checkName(name: string): string { * that catalog, and the connection's PROBE round-trip time. Each catalog update reconciles it: a * removed section, or a changed path, retracts the broadcast it replaces. * - * Reporters on one origin that resolve the same feedback path for the same catalog share one - * broadcast, since a second broadcast at a path would replace the first, and add what each counted - * since it joined. A feedback broadcast belongs to one soliciting catalog, so a reporter for another - * catalog that resolves a path already in use publishes nothing and warns: give it another name. + * Each reporter publishes its own broadcast, so a report is only ever its own decoders' counts. A + * second broadcast at a path would replace the first, so a reporter that resolves a feedback path + * another reporter on the same origin already publishes publishes nothing and warns: give it + * another name. */ export class Echo { /** The wired inputs, read-only. */ @@ -99,20 +99,47 @@ export class Echo { this.#signals.run((effect) => { const current = effect.get(target); if (!current) return; + const { origin, path, base } = current; - let shared: Shared; + let paths = claimed.get(origin); + if (!paths) { + paths = new Set(); + claimed.set(origin, paths); + } + if (paths.has(path)) { + console.warn("feedback path already in use on this connection; give this player another echo name", path); + return; + } + + let broadcast: Moq.Broadcast.Producer | undefined; + let writer: Report.Writer; try { - shared = Shared.acquire(current.origin, current.path, current.base); + const publication = origin.createBroadcast(path); + broadcast = publication.broadcast; + writer = new Report.Writer(broadcast, Schema.TRACK, Schema.SnapshotSchema); + // A fresh instance, so a reader sees a replaced feedback broadcast as a restart. + publication.announce({ epoch: Moq.Epoch.mint() }); } catch (err) { - console.warn("failed to publish feedback", current.path, err); + broadcast?.close(); + console.warn("failed to publish feedback", path, err); return; } - const leave = shared.join(this, () => this.#report(current.base)); - effect.cleanup(leave); + const published = broadcast; + + const claim = paths; + claim.add(path); + const write = () => writer.update(this.#report(base) as Schema.Snapshot); + // Teardown runs last in, first out: write the final counts, then retract and release the path. + effect.cleanup(() => claim.delete(path)); + effect.cleanup(() => published.close()); + effect.cleanup(() => writer.finish()); + effect.cleanup(write); + effect.interval(write, Nano.fromMilli(Milli(Report.INTERVAL))); // Observing the probe asks the peer for PROBE updates, so only do it while someone reads them. + const demand = writer.track.demand(); effect.run((inner) => { - if (inner.get(shared.watched)) inner.get(this.in.probe); + if (inner.get(demand.wanted) !== undefined) inner.get(this.in.probe); }); }); } @@ -131,146 +158,5 @@ export class Echo { } } -// One feedback broadcast per origin and path, shared by every reporter that resolves to it. -const published = new WeakMap>(); - -class Shared { - /** The broadcast whose catalog solicited this feedback, which it belongs to. */ - readonly base: Moq.Path.Valid; - - readonly #origin: Moq.Origin.Table; - readonly #path: Moq.Path.Valid; - readonly #broadcast: Moq.Broadcast.Producer; - readonly #writer: Report.Writer; - // What each reporter counted since it joined, keyed by its owner. - readonly #reporters = new Map Snapshot>(); - // What the reporters that left counted, summed, so the counters stay cumulative without them. - #departed: Snapshot = { renditions: {} }; - #signals = new Effect(); - - /** Whether anyone reads the feedback, which is when it is written. */ - readonly watched: Getter; - - /** - * The feedback broadcast at `path` for the catalog of the broadcast at `base`. Throws when it - * already reports for another catalog, since a second broadcast at the path would replace it. - */ - static acquire(origin: Moq.Origin.Table, path: Moq.Path.Valid, base: Moq.Path.Valid): Shared { - let paths = published.get(origin); - if (!paths) { - paths = new Map(); - published.set(origin, paths); - } - let shared = paths.get(path); - if (shared && shared.base !== base) { - if (shared.#reporters.size > 0) { - throw new Error(`${path} already reports feedback for the catalog of ${shared.base}`); - } - // Every reporter for the other catalog left, and its retraction is still pending: retract now. - paths.delete(path); - shared.#close(); - shared = undefined; - } - if (!shared) { - shared = new Shared(origin, path, base); - paths.set(path, shared); - } - return shared; - } - - private constructor(origin: Moq.Origin.Table, path: Moq.Path.Valid, base: Moq.Path.Valid) { - this.#origin = origin; - this.#path = path; - this.base = base; - const publication = origin.createBroadcast(path); - this.#broadcast = publication.broadcast; - try { - this.#writer = new Report.Writer(this.#broadcast, Schema.TRACK, Schema.SnapshotSchema); - // A fresh instance, so a reader sees a replaced feedback broadcast as a restart. - publication.announce({ epoch: Moq.Epoch.mint() }); - } catch (err) { - this.#broadcast.close(); - throw err; - } - const demand = this.#writer.track.demand(); - this.watched = this.#signals.computed((effect) => effect.get(demand.wanted) !== undefined); - this.#signals.interval(() => this.#write(), Nano.fromMilli(Milli(Report.INTERVAL))); - } - - /** - * Add what `owner` counts from now on to the feedback, returning the function that removes it. - * Its reporter's counters are cumulative, so only what they add after joining is reported: a - * returning owner's earlier counts are already among the departed ones. - */ - join(owner: object, reporter: () => Snapshot): () => void { - const baseline = reporter().renditions; - const counts = () => since(reporter(), baseline); - this.#reporters.set(owner, counts); - return () => { - if (this.#reporters.get(owner) !== counts) return; - this.#reporters.delete(owner); - // Bounded like a tally, so departures that each read fresh rendition IDs cannot grow it. - const departed = merge(this.#departed, { renditions: counts().renditions }); - this.#departed = { renditions: bound(departed.renditions) }; - // Deferred, so a reporter's rerun reuses the broadcast rather than replacing it. - queueMicrotask(() => { - if (this.#reporters.size > 0 || published.get(this.#origin)?.get(this.#path) !== this) return; - published.get(this.#origin)?.delete(this.#path); - this.#close(); - }); - }; - } - - #write(): void { - if (!this.#writer.wanted) return; - let snapshot = this.#departed; - for (const reporter of this.#reporters.values()) snapshot = merge(snapshot, reporter()); - this.#writer.update(snapshot as Schema.Snapshot); - } - - // Write the final counts and retract the broadcast. - #close(): void { - this.#write(); - this.#signals.close(); - this.#writer.finish(); - this.#broadcast.close(); - } -} - -// Add two reports' counters per rendition, keeping the newer arrival and the first round-trip time: -// gauges are never summed. -function merge(a: Snapshot, b: Snapshot): Snapshot { - const renditions: Record = { ...a.renditions }; - for (const [id, received] of Object.entries(b.renditions)) { - const sum: Received = { ...renditions[id] }; - for (const [counter, n] of Object.entries(received)) { - if (counter === "arrival") continue; - const key = counter as Exclude; - sum[key] = (sum[key] ?? 0) + (n as number); - } - const arrival = received.arrival; - if (arrival && (sum.arrival === undefined || arrival.wall >= sum.arrival.wall)) sum.arrival = arrival; - renditions[id] = sum; - } - const transport = a.transport ?? b.transport; - return transport ? { transport, renditions } : { renditions }; -} - -// What `current` counted since `baseline`. A counter below its baseline started over, such as an -// entry the tally dropped, so it counts from zero. The newest arrival and the transport are gauges. -function since(current: Snapshot, baseline: Record): Snapshot { - const renditions: Record = {}; - for (const [id, received] of Object.entries(current.renditions)) { - const added: Received = {}; - for (const [counter, n] of Object.entries(received)) { - if (counter === "arrival") continue; - const key = counter as Exclude; - const base = baseline[id]?.[key] ?? 0; - const delta = (n as number) >= base ? (n as number) - base : (n as number); - if (delta > 0) added[key] = delta; - } - if (received.arrival) added.arrival = received.arrival; - if (Object.keys(added).length > 0) renditions[id] = added; - } - return current.transport ? { transport: current.transport, renditions } : { renditions }; -} +// The feedback paths published on each origin, so a second reporter never replaces the first's broadcast. +const claimed = new WeakMap>(); diff --git a/js/watch/src/element.ts b/js/watch/src/element.ts index 5e75cd50f2a..623cca8f1b5 100644 --- a/js/watch/src/element.ts +++ b/js/watch/src/element.ts @@ -633,9 +633,9 @@ export default class MoqWatch extends HTMLElement { * The viewer's feedback name, mirrored by the `echo` attribute; undefined (the default) publishes * no feedback. Once the watched catalog solicits feedback with an `echo` section, the element * publishes `.echo` under its path, reporting what each rendition received and played. - * Elements on one connection watching the same catalog under one name share it; one watching - * another catalog that solicits the same path needs its own name. One visible path segment: a `/` - * or a leading `.` is refused. + * Each element publishes its own: a second element on one connection that resolves the same + * feedback path publishes nothing and warns, so give each its own name. One visible path segment: + * a `/` or a leading `.` is refused. */ get echo(): string | undefined { return this.#echo.peek(); diff --git a/js/watch/src/feedback.ts b/js/watch/src/feedback.ts index cef5e68a0a2..defc8911083 100644 --- a/js/watch/src/feedback.ts +++ b/js/watch/src/feedback.ts @@ -27,19 +27,11 @@ export interface Key { const MAX_BROADCASTS = 4; /** - * The most rendition IDs a tally keeps per catalog broadcast, and a feedback report keeps of its - * departed reporters, so a catalog that keeps renaming its renditions cannot grow either, or each - * report, without bound. Matches the Rust registry's limit. The oldest makes way; one still counting - * into it starts over, which a reader treats as a reset. + * The most rendition IDs a tally keeps per catalog broadcast, so a catalog that keeps renaming its + * renditions cannot grow it, or each report, without bound. Matches the Rust registry's limit. The + * oldest makes way; one still counting into it starts over, which a reader treats as a reset. */ -export const MAX_RENDITIONS = 1024; - -/** Drop the oldest entries of `renditions` beyond {@link MAX_RENDITIONS}, in insertion order. */ -export function bound(renditions: Record): Record { - const ids = Object.keys(renditions); - if (ids.length <= MAX_RENDITIONS) return renditions; - return Object.fromEntries(ids.slice(ids.length - MAX_RENDITIONS).map((id) => [id, renditions[id]])); -} +const MAX_RENDITIONS = 1024; type Entry = { received: Received; stalling?: Instant }; From f8ccc91e3acc5fb0e01e09d73613382620f5d394 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 10:01:44 -0800 Subject: [PATCH 11/13] feat(watch): a refused feedback reporter takes over once the holder leaves A second resolving a feedback path already in use on its connection waits and publishes once the first releases it, instead of staying silent until its own target changes. Records the one writer per name decision in the stats epic's Plan. Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/watch.md | 3 ++- js/watch/src/echo.test.ts | 16 ++++++++++------ js/watch/src/echo.ts | 37 +++++++++++++++++++++++-------------- js/watch/src/element.ts | 4 ++-- quest/m2/stats/README.md | 9 +++++++++ 5 files changed, 46 insertions(+), 23 deletions(-) diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index ce91fc9e438..4bfd2702924 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -97,7 +97,8 @@ round-trip time. It writes about once a second while someone subscribes, and follows the catalog: a removed or moved section retracts the broadcast. Each player publishes its own broadcast, reporting only what it counted, so a second player on one connection that resolves the same feedback path, for any catalog, -publishes nothing and warns; give each player its own name. The decoders' +publishes nothing and warns until the first one leaves; give each player its own +name. The decoders' `out.stats` and the stats panel read the same counters. The token must allow publishing under the echo path. diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index 5de3259493b..0a4fb3199cf 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -106,7 +106,7 @@ test("publishes feedback where the catalog solicits it and follows the solicitat } }); -test("a second reporter at a feedback path in use publishes nothing until it is free", async () => { +test("a second reporter at a feedback path in use publishes nothing until the holder leaves", async () => { const clock = new Manual(); const installed = clock.install(); const origin = new Origin.Producer(); @@ -116,7 +116,12 @@ test("a second reporter at a feedback path in use publishes nothing until it is const second = watched(origin, "room/live.hang", catalog); const enabled = new Signal(true); const reporters = [ - new Echo({ broadcast: first, origin, name: "alice", sources: [source("room/live.hang", { video: { frames: 1 } })] }), + new Echo({ + broadcast: first, + origin, + name: "alice", + sources: [source("room/live.hang", { video: { frames: 1 } })], + }), new Echo({ broadcast: second, origin, @@ -139,12 +144,11 @@ test("a second reporter at a feedback path in use publishes nothing until it is expect([...paths]).toEqual(["room/viewers/alice.echo"]); expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(1); - // The holder leaving retracts it and frees the path for a reporter that asks again. - reporters[0].close(); - await flush(); - expect([...paths]).toEqual([]); + // The holder leaving frees the path for a waiting reporter, which takes it over. enabled.set(true); await flush(); + reporters[0].close(); + await flush(); expect([...paths]).toEqual(["room/viewers/alice.echo"]); expect((await read(origin, "room/viewers/alice.echo", clock))?.renditions?.video.frames as unknown).toBe(10); } finally { diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index c8b9aa498af..54a2cb57d71 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -1,7 +1,7 @@ import { Milli, Nano } from "@moq/clock"; import { Report, Echo as Schema } from "@moq/hang"; import * as Moq from "@moq/net"; -import { Effect, type Getter, getter, type Inputs, type Readonlys } from "@moq/signals"; +import { Effect, type Getter, getter, type Inputs, type Readonlys, Signal } from "@moq/signals"; import type { Broadcast } from "./broadcast"; import type { Received } from "./feedback"; @@ -59,8 +59,8 @@ export function checkName(name: string): string { * * Each reporter publishes its own broadcast, so a report is only ever its own decoders' counts. A * second broadcast at a path would replace the first, so a reporter that resolves a feedback path - * another reporter on the same origin already publishes publishes nothing and warns: give it - * another name. + * another reporter on the same origin already publishes publishes nothing and warns until that one + * releases it: give it another name. */ export class Echo { /** The wired inputs, read-only. */ @@ -101,13 +101,18 @@ export class Echo { if (!current) return; const { origin, path, base } = current; - let paths = claimed.get(origin); - if (!paths) { - paths = new Set(); - claimed.set(origin, paths); + let claims = claimed.get(origin); + if (!claims) { + claims = { paths: new Set(), released: new Signal(0) }; + claimed.set(origin, claims); } - if (paths.has(path)) { - console.warn("feedback path already in use on this connection; give this player another echo name", path); + if (claims.paths.has(path)) { + // Try again whenever a reporter on this origin releases its path. + effect.get(claims.released); + console.warn( + "feedback path already in use on this connection; give this player another echo name", + path, + ); return; } @@ -126,11 +131,14 @@ export class Echo { } const published = broadcast; - const claim = paths; - claim.add(path); + const claim = claims; + claim.paths.add(path); const write = () => writer.update(this.#report(base) as Schema.Snapshot); // Teardown runs last in, first out: write the final counts, then retract and release the path. - effect.cleanup(() => claim.delete(path)); + effect.cleanup(() => { + claim.paths.delete(path); + claim.released.update((n) => n + 1); + }); effect.cleanup(() => published.close()); effect.cleanup(() => writer.finish()); effect.cleanup(write); @@ -158,5 +166,6 @@ export class Echo { } } -// The feedback paths published on each origin, so a second reporter never replaces the first's broadcast. -const claimed = new WeakMap>(); +// The feedback paths published on each origin, so a second reporter never replaces the first's +// broadcast, and a count of releases, so a refused reporter tries again once one frees. +const claimed = new WeakMap; released: Signal }>(); diff --git a/js/watch/src/element.ts b/js/watch/src/element.ts index 623cca8f1b5..43cab2f2d0c 100644 --- a/js/watch/src/element.ts +++ b/js/watch/src/element.ts @@ -634,8 +634,8 @@ export default class MoqWatch extends HTMLElement { * no feedback. Once the watched catalog solicits feedback with an `echo` section, the element * publishes `.echo` under its path, reporting what each rendition received and played. * Each element publishes its own: a second element on one connection that resolves the same - * feedback path publishes nothing and warns, so give each its own name. One visible path segment: - * a `/` or a leading `.` is refused. + * feedback path publishes nothing and warns until the first one leaves, so give each its own + * name. One visible path segment: a `/` or a leading `.` is refused. */ get echo(): string | undefined { return this.#echo.peek(); diff --git a/quest/m2/stats/README.md b/quest/m2/stats/README.md index 414e45cdb0b..09b72091133 100644 --- a/quest/m2/stats/README.md +++ b/quest/m2/stats/README.md @@ -68,6 +68,15 @@ kind. before the viewer read the catalog; one broadcast per catalog removes the collisions, the race, and the cap with less code, and needs no JS track request API. +- **One feedback writer per name** (2026-11-02, maintainer). Each player + publishes its own `.echo` broadcast with only its own counts. A second + player on the same connection that resolves the same feedback path, for + the same catalog or another, publishes nothing and warns until the first + one leaves; the application gives each player its own name. Reason: sharing one broadcast between + players needed a departed sum, a per-player ledger, and join-time baselines + to keep the counters cumulative, and four review rounds of + [moq-dev/moq#7222](https://github.com/moq-dev/moq/pull/7222) each found + another edge case in them. - **Trust is the token prefix** (2026-09-29). Whoever the application's tokens let publish under the echo path may report, and no report is authenticated beyond that. From 2e4732188468f04675a350f6bc130722037aea97 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 10:12:56 -0800 Subject: [PATCH 12/13] fix(watch): report arrival at transport ingress and refuse malformed echo names Feedback and decoder stats paired the newest media timestamp with the time the decoder read the frame, so reordering and decoder backpressure inflated the delivery latency a publisher derives from it. Convert the frame's monotonic ingress time to wall time instead. An echo name with a stray backslash passed the name check and only threw inside the reporter's effect once a catalog solicited feedback. Validate the published segment's path spelling in the check, so the setter and the attribute refuse it. Co-Authored-By: Claude Opus 5.5 --- js/watch/src/audio/decoder.ts | 9 +++++---- js/watch/src/echo.test.ts | 5 ++++- js/watch/src/echo.ts | 6 ++++++ js/watch/src/element.ts | 2 +- js/watch/src/feedback.test.ts | 24 ++++++++++++++++++------ js/watch/src/feedback.ts | 16 ++++++++++++---- js/watch/src/video/decoder.ts | 9 +++++---- 7 files changed, 51 insertions(+), 20 deletions(-) diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index f39456624a5..3c918203220 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -1,4 +1,4 @@ -import { Micro, Milli, type Second, type Wall, wall } from "@moq/clock"; +import { Micro, Milli, type Second, type Wall } from "@moq/clock"; import * as Catalog from "@moq/hang/catalog"; import * as Container from "@moq/hang/container"; import * as Util from "@moq/hang/util"; @@ -16,7 +16,7 @@ import { import { Producer as ArrivalProducer, type Arrivals, gap } from "../arrivals"; import { hostedAssets } from "../assets"; import { base64ToBytes } from "../base64"; -import { type Counter, type Key, type Received, Tally } from "../feedback"; +import { arrivedAt, type Counter, type Key, type Received, Tally } from "../feedback"; import { type Failure, failureMoved, nextMedia, subscribeMedia } from "../media"; import type { Sync } from "../sync"; import { AudioBuffer } from "./buffer"; @@ -261,11 +261,12 @@ export class Decoder { // Count a received frame and whether it arrived too late for playout. #receive(key: Key, frame: Container.ReceivedFrame, timestamp: Milli, late: boolean): void { const bytes = frame.payload.byteLength; - this.#tally.arrive(key, timestamp); + const arrived = arrivedAt(frame.arrival); + this.#tally.arrive(key, timestamp, arrived); this.#count(key, { frames: 1, bytes, late: late ? 1 : 0 }, (stats) => ({ bytesReceived: stats.bytesReceived + bytes, late: stats.late + (late ? 1 : 0), - arrival: { timestamp, wall: wall() }, + arrival: { timestamp, wall: arrived }, })); } diff --git a/js/watch/src/echo.test.ts b/js/watch/src/echo.test.ts index 0a4fb3199cf..dfb6af5bdb7 100644 --- a/js/watch/src/echo.test.ts +++ b/js/watch/src/echo.test.ts @@ -55,8 +55,11 @@ async function read(origin: Origin.Producer, path: string, clock: Manual): Promi } test("refuses a name that is not one visible path segment", () => { - for (const name of ["", "a/b", ".", "..", "*", "**", ".hidden"]) expect(() => checkName(name)).toThrow(); + for (const name of ["", "a/b", ".", "..", "*", "**", ".hidden", "a\\b", "alice\\"]) { + expect(() => checkName(name)).toThrow(); + } expect(checkName("alice")).toBe("alice"); + expect(checkName("a\\\\b")).toBe("a\\\\b"); }); test("publishes feedback where the catalog solicits it and follows the solicitation", async () => { diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index 54a2cb57d71..8c827b8ef55 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -37,6 +37,7 @@ export type EchoProps = Inputs & { /** * Refuse an echo name that is not one visible path segment: empty, containing `/`, a dot segment * or glob, or starting with `.`, which would hide the feedback from discovery. Matches the Rust CLI. + * A `\` must escape another `\` in the published name, as in any path. */ export function checkName(name: string): string { if (name === "" || name.includes("/") || name === "." || name === ".." || name === "*" || name === "**") { @@ -45,6 +46,11 @@ export function checkName(name: string): string { if (name.startsWith(".")) { throw new Error(`echo name ${JSON.stringify(name)} starts with \`.\`, which hides its feedback from discovery`); } + try { + Moq.Path.from(`${name}${Schema.SUFFIX}`); + } catch (err) { + throw new Error(`echo name ${JSON.stringify(name)} is not a valid path segment`, { cause: err }); + } return name; } diff --git a/js/watch/src/element.ts b/js/watch/src/element.ts index 43cab2f2d0c..8c52f7d32e3 100644 --- a/js/watch/src/element.ts +++ b/js/watch/src/element.ts @@ -111,7 +111,7 @@ function parseEcho(value: string | null): string | undefined { try { return checkName(value); } catch { - throw invalidAttribute("echo", value, "one path segment not starting with `.`"); + throw invalidAttribute("echo", value, "one path segment not starting with `.`, any `\\` doubled"); } } diff --git a/js/watch/src/feedback.test.ts b/js/watch/src/feedback.test.ts index c3ce9b9aab8..4e484250fd9 100644 --- a/js/watch/src/feedback.test.ts +++ b/js/watch/src/feedback.test.ts @@ -1,8 +1,8 @@ import { expect, test } from "bun:test"; -import { Manual, Milli, Nano, wall } from "@moq/clock"; +import { Manual, Milli, Nano, now, Wall, wall } from "@moq/clock"; import * as Catalog from "@moq/hang/catalog"; import { Path } from "@moq/net"; -import { Tally } from "./feedback"; +import { arrivedAt, Tally } from "./feedback"; const live = { path: Path.from("room/live.hang"), id: "video" }; @@ -35,10 +35,22 @@ test("a stall reports its time so far and adds its duration once it ends", async test("an arrival pairs the media timestamp with milliseconds since the MoQ epoch", () => { const tally = new Tally(); - tally.arrive(live, Milli(1234.9)); - const arrival = tally.report(live.path).video.arrival; - expect(arrival?.timestamp).toBe(1234); - expect(arrival?.wall).toBeCloseTo(wall() - Catalog.MOQ_EPOCH_UNIX_MILLIS, -3); + tally.arrive(live, Milli(1234.9), Wall(Catalog.MOQ_EPOCH_UNIX_MILLIS + 5000.7)); + expect(tally.report(live.path).video.arrival as unknown).toEqual({ timestamp: 1234, wall: 5000 }); +}); + +test("an arrival's wall time is when the frame came off the transport, not when it was read", async () => { + const clock = new Manual(); + const installed = clock.install(); + try { + await clock.advance(Nano.fromMilli(Milli(1000))); + const arrival = Nano.toMilli(Nano(now())); + const before = wall(); + await clock.advance(Nano.fromMilli(Milli(300))); + expect(arrivedAt(arrival)).toBe(before); + } finally { + installed.close(); + } }); test("keeps the most recent few catalog broadcasts", () => { diff --git a/js/watch/src/feedback.ts b/js/watch/src/feedback.ts index defc8911083..2c8916f64b0 100644 --- a/js/watch/src/feedback.ts +++ b/js/watch/src/feedback.ts @@ -1,4 +1,4 @@ -import { Instant, type Milli, Nano, now, wall } from "@moq/clock"; +import { Instant, type Milli, Nano, now, Wall, wall } from "@moq/clock"; import * as Catalog from "@moq/hang/catalog"; import type * as Moq from "@moq/net"; @@ -72,9 +72,9 @@ export class Tally { } } - /** Record a received frame at media `timestamp`, arriving now. */ - arrive(key: Key, timestamp: Milli): void { - const at = Math.floor(wall() - Catalog.MOQ_EPOCH_UNIX_MILLIS); + /** Record a received frame at media `timestamp`, arriving at wall time `arrived`. */ + arrive(key: Key, timestamp: Milli, arrived: Wall): void { + const at = Math.floor(arrived - Catalog.MOQ_EPOCH_UNIX_MILLIS); // A clock before the MoQ epoch has no wire encoding, so such an arrival is never recorded. if (at < 0 || timestamp < 0) return; this.#entry(key).received.arrival = { timestamp: Math.floor(timestamp), wall: at }; @@ -111,6 +111,14 @@ export class Tally { } } +/** + * The wall time of a frame's monotonic ingress time, as a received frame records it before + * reordering or decoder backpressure, so a frame read late still reports when it arrived. + */ +export function arrivedAt(arrival: Milli): Wall { + return Wall(wall() - Math.max(0, Nano.toMilli(Nano(now())) - arrival)); +} + // Milliseconds since `start`. function elapsed(start: Instant): number { return Nano.toMilli(Instant.durationSince(now(), start)); diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 2866bb6b9bb..4b8eab14601 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -1,4 +1,4 @@ -import { type Micro, Milli, Nano, type Wall, wall } from "@moq/clock"; +import { type Micro, Milli, Nano, type Wall } from "@moq/clock"; import * as Catalog from "@moq/hang/catalog"; import * as Container from "@moq/hang/container"; import * as Util from "@moq/hang/util"; @@ -17,7 +17,7 @@ import { } from "@moq/signals"; import { rotateVideoDimensions } from "@moq/video"; import { base64ToBytes } from "../base64"; -import { type Counter, type Key, type Received, Tally } from "../feedback"; +import { arrivedAt, type Counter, type Key, type Received, Tally } from "../feedback"; import { type Failure, failureMoved, nextMedia, subscribeMedia } from "../media"; import { supportCacheKey } from "../support-probe"; import type { Sync } from "../sync"; @@ -601,12 +601,13 @@ class DecoderTrack { const timestamp = Milli.fromMicro(frame.timestamp as Micro); const late = accepted && this.sync.received(timestamp, frame.arrival); const bytes = frame.payload.byteLength; - this.tally?.arrive(this.key, timestamp); + const arrived = arrivedAt(frame.arrival); + this.tally?.arrive(this.key, timestamp, arrived); this.#count({ frames: 1, bytes, late: late ? 1 : 0 }, (stats) => ({ frameCount: stats.frameCount + (accepted ? 1 : 0), bytesReceived: stats.bytesReceived + bytes, late: stats.late + (late ? 1 : 0), - arrival: { timestamp, wall: wall() }, + arrival: { timestamp, wall: arrived }, })); } From d209a9869c421ae8346db685f14a556a588f5292 Mon Sep 17 00:00:00 2001 From: quest fixer Date: Mon, 2 Nov 2026 14:23:46 -0800 Subject: [PATCH 13/13] fix(watch): follow base publication instance API --- js/watch/src/echo.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/js/watch/src/echo.ts b/js/watch/src/echo.ts index 8c827b8ef55..f2d177b2da0 100644 --- a/js/watch/src/echo.ts +++ b/js/watch/src/echo.ts @@ -129,7 +129,7 @@ export class Echo { broadcast = publication.broadcast; writer = new Report.Writer(broadcast, Schema.TRACK, Schema.SnapshotSchema); // A fresh instance, so a reader sees a replaced feedback broadcast as a restart. - publication.announce({ epoch: Moq.Epoch.mint() }); + publication.announce(); } catch (err) { broadcast?.close(); console.warn("failed to publish feedback", path, err);