From b728a69781adb1720fa7df9043c81613d5dbc80c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 11:50:54 -0800 Subject: [PATCH 1/5] chore(quest): claim quest/m2/probe/viewer-upswitch.md Quest-Claim: 35e812f1dc86a690 From 9273ecc8abc106cd066bdb01d6db3b9b0ac76201 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:14:07 -0800 Subject: [PATCH 2/5] feat(watch)!: video selects from the viewer grant, so a small rendition moves up A player's video now selects from its viewer's grant less the audio the claim covers, instead of the connection's whole PROBE estimate. The grant is capped at the ceiling the player claims, so a relay probing up to that target makes the best rendition selectable, and players sharing a connection split it. Player drops `probe`; Video.Source takes `rate` in its place and holds the last rate while it is unknown. Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/watch.md | 10 ++-- js/moq-boy/src/game.ts | 2 +- js/room/src/remote.ts | 1 - js/watch/MIGRATE.md | 8 +++ js/watch/api/index.api.md | 3 +- js/watch/src/element.ts | 1 - js/watch/src/player.test.ts | 90 +++++++++++++++++++++++++++++++ js/watch/src/player.ts | 35 +++++++----- js/watch/src/video/source.test.ts | 69 ++++++++++-------------- js/watch/src/video/source.ts | 40 +++++++------- js/watch/src/viewer.ts | 19 +++++-- quest/m2/probe/README.md | 1 - quest/m2/probe/viewer-upswitch.md | 42 --------------- 13 files changed, 192 insertions(+), 129 deletions(-) delete mode 100644 quest/m2/probe/viewer-upswitch.md diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index e06dec0c09d..f8ba12d911f 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -186,7 +186,6 @@ import * as Watch from "@moq/watch"; const connection = new Moq.Connection({ url: new URL("https://relay.example.com/anon") }); const player = new Watch.Player({ origin: connection.origin, - probe: connection.probe, name: Moq.Path.from("alice.hang"), video: { canvas }, viewer: { viewers: connection.viewers }, @@ -205,10 +204,13 @@ estimate (see [`connection.viewers`](/lib/js/net)). Its ceiling follows the catalog: the rate at which selection would pick the best enabled video rendition the `video.target` allows, plus the selected audio rendition's bitrate, counting only media being downloaded. A relay that probes raises the -estimate toward it, so a larger rendition can become affordable. Set +estimate toward it, and video selects from the claim's grant less that audio, so a viewer on a small +rendition moves up once the grant reaches the ceiling. Players sharing a connection split its estimate +instead of each selecting against all of it. Set `viewer.max` (`controls.viewer.max` on ``) to claim a fixed ceiling -in bits per second instead while media downloads, or `0` to claim nothing; omit `viewer.viewers` to -leave the connection's estimate unclaimed. +in bits per second instead while media downloads, which also caps what video selects, or `0` to claim nothing; omit `viewer.viewers` to +leave the connection's estimate unclaimed. Without a claim, video selects the best rendition its +`video.target` allows. To chart when each audio frame arrived against when it plays, open an `arrivals()` handle on the audio decoder. It yields every frame received while it is open, stamped diff --git a/js/moq-boy/src/game.ts b/js/moq-boy/src/game.ts index 9ef27185543..a8e6b2ca8b8 100644 --- a/js/moq-boy/src/game.ts +++ b/js/moq-boy/src/game.ts @@ -140,7 +140,7 @@ export class Game { broadcast: this.broadcast, target: this.#target, supported: Watch.Video.Decoder.supported, - probe: connection.probe, + rate: new Moq.Signals.Derived([connection.probe], (probe) => probe?.estimatedRecvRate), }); this.#signals.cleanup(() => this.videoSource.close()); diff --git a/js/room/src/remote.ts b/js/room/src/remote.ts index e16c12f8598..00b28e059ae 100644 --- a/js/room/src/remote.ts +++ b/js/room/src/remote.ts @@ -51,7 +51,6 @@ export class Member { this.player = new Watch.Player({ origin: connection.origin, - probe: connection.probe, name: path, video: { canvas: this.canvas }, audio: { muted: this.muted, volume: this.volume }, diff --git a/js/watch/MIGRATE.md b/js/watch/MIGRATE.md index d6a80096983..6767184a1e8 100644 --- a/js/watch/MIGRATE.md +++ b/js/watch/MIGRATE.md @@ -4,6 +4,14 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Video selects from the viewer grant + +`Player` no longer takes `probe`: video selects from its viewer's grant (`viewer.viewers`), less the audio the claim covers, instead of the connection's whole `estimatedRecvRate`. +Remove `probe` and pass `viewer: { viewers: connection.viewers }`; without a claim, video selects the best rendition its target allows. +`Video.Source` takes `rate`, the receive rate in bits per second video may spend, in place of `probe`. +To keep selecting from the whole connection estimate, pass `rate: new Signals.Derived([connection.probe], (probe) => probe?.estimatedRecvRate)`. +An unknown rate now holds the last one instead of selecting the best rendition, so a reconnect no longer jumps to the top of the ladder. + ### Players claim a viewer target from the catalog `` and `@moq/room` now hold a viewer on their connection's `viewers` for as long as they download, with a ceiling taken from the catalog, so a relay that probes raises the receive estimate toward the best enabled rendition. diff --git a/js/watch/api/index.api.md b/js/watch/api/index.api.md index 1eea1a447ea..c5779f3883e 100644 --- a/js/watch/api/index.api.md +++ b/js/watch/api/index.api.md @@ -172,7 +172,6 @@ export type PlayerInput = { name: Signals.Getter; origin: Signals.Getter; paused: Signals.Getter; - probe: Signals.Getter; text: { container: Signals.Getter; target: Signals.Getter; @@ -311,7 +310,7 @@ export namespace Video { } export type SourceInput = { broadcast: Signals.Getter; - probe: Signals.Getter; + rate: Signals.Getter; supported: Signals.Getter; target: Signals.Getter; }; diff --git a/js/watch/src/element.ts b/js/watch/src/element.ts index ef5cb78cb2a..1a627201fb5 100644 --- a/js/watch/src/element.ts +++ b/js/watch/src/element.ts @@ -248,7 +248,6 @@ export default class MoqWatch extends HTMLElement { this.player = new Player({ origin: this.connection.origin, - probe: this.connection.probe, enabled: this.#enabled, name: this.#name, follow: this.#follow, diff --git a/js/watch/src/player.test.ts b/js/watch/src/player.test.ts index b0baf5492df..73f60aa7872 100644 --- a/js/watch/src/player.test.ts +++ b/js/watch/src/player.test.ts @@ -1,4 +1,5 @@ import { expect, mock, test } from "bun:test"; +import * as Catalog from "@moq/hang/catalog"; import { Bandwidth, Origin, Path } from "@moq/net"; import { Signal } from "@moq/signals"; @@ -6,6 +7,8 @@ import { Signal } from "@moq/signals"; mock.module("./audio/render-worklet.ts?worklet", () => ({ default: async () => "blob:fake-render" })); const { Player } = await import("./player"); +const Audio = await import("./audio"); +const Video = await import("./video"); async function flush() { for (let i = 0; i < 10; i++) await Promise.resolve(); @@ -132,3 +135,90 @@ test("Player claims its viewer only while it downloads, and an override replaces expect(viewers.target.peek()).toBe(0); viewers.close(); }); + +test("Player selects video from its viewer grant less audio, moving up as the grant rises", async () => { + // Bun has no WebCodecs or Web Audio: accept every rendition so selection runs, and park the + // audio graph, which builds for any selected rendition, before it needs a worklet. + const supported = { video: Video.Decoder.supported, audio: Audio.Decoder.supported }; + Video.Decoder.supported = async () => true; + Audio.Decoder.supported = async () => true; + const context = Object.getOwnPropertyDescriptor(globalThis, "AudioContext"); + globalThis.AudioContext = class extends EventTarget { + state = "running"; + audioWorklet = { addModule: () => new Promise(() => {}) }; + suspend = async () => {}; + resume = async () => {}; + close = async () => {}; + } as unknown as typeof AudioContext; + + const estimate = new Signal(undefined); + const viewers = new Bandwidth.Viewers(estimate); + const visible = new Signal<"always" | "never">("always"); + const video = (width: number, height: number, bitrate: number) => + Catalog.VideoConfigSchema.parse({ + codec: "avc1.640028", + container: { kind: "legacy" }, + codedWidth: width, + codedHeight: height, + bitrate, + }); + const catalog = { + video: { + renditions: { + "360p": video(640, 360, 800_000), + "1080p": video(1920, 1080, 4_000_000), + }, + }, + audio: { + renditions: { + audio: Catalog.AudioConfigSchema.parse({ + codec: "opus", + sampleRate: 48000, + numberOfChannels: 2, + container: { kind: "legacy" }, + bitrate: 100_000, + }), + }, + }, + }; + const player = new Player({ + name: Path.from("live"), + catalogFormat: "manual", + catalog, + video: { visible }, + viewer: { viewers }, + }); + try { + await flush(); + // The 1080p rendition over the selection margin, plus audio. + expect(viewers.target.peek()).toBe(5_100_000); + + // An app-limited estimate funds only the small rendition. + estimate.set(1_200_000); + await flush(); + expect(player.video.source.out.track.peek()).toBe("360p"); + + // Short of the target by one bit, the audio's share leaves too little for 1080p. + estimate.set(5_099_999); + await flush(); + expect(player.video.source.out.track.peek()).toBe("360p"); + + // A probe that reaches the target moves the viewer up. + estimate.set(5_100_000); + await flush(); + expect(player.video.source.out.track.peek()).toBe("1080p"); + + // Hidden video claims only audio, which says nothing about video: the selection holds. + visible.set("never"); + await flush(); + expect(viewers.target.peek()).toBe(100_000); + expect(player.video.source.out.track.peek()).toBe("1080p"); + } finally { + player.close(); + viewers.close(); + Video.Decoder.supported = supported.video; + Audio.Decoder.supported = supported.audio; + if (context) Object.defineProperty(globalThis, "AudioContext", context); + else delete (globalThis as { AudioContext?: unknown }).AudioContext; + } +}); diff --git a/js/watch/src/player.ts b/js/watch/src/player.ts index 2cdb66a3745..9aa69884bba 100644 --- a/js/watch/src/player.ts +++ b/js/watch/src/player.ts @@ -24,8 +24,6 @@ export type PlayerInput = { catalogFormat: Getter; /** Catalog supplied when the format is `manual`. */ catalog: Getter; - /** Connection probe used for rendition selection. */ - probe: Getter; /** Pause media and captions. */ paused: Getter; /** Playback distance from the live edge. */ @@ -52,7 +50,10 @@ export type PlayerInput = { /** Silence audio and stop its download. */ muted: Getter; }; - /** The claim this player holds on its connection's receive estimate while it downloads. */ + /** + * The claim this player holds on its connection's receive estimate while it downloads. Video + * selects from the claim's grant less the audio it covers, so without a claim it ranks alone. + */ viewer: { /** Where to claim, normally the connection's `viewers`; absent claims nothing. */ viewers: Getter | undefined>; @@ -104,6 +105,7 @@ export class Player { readonly textRenderer: Text.Renderer; #videoEnabled = new Signal(false); + #videoRate = new Signal(undefined); #audioEnabled = new Signal(false); #captionsEnabled = new Signal(false); #signals = new Effect(); @@ -119,7 +121,6 @@ export class Player { follow: getter(props.follow ?? true), catalogFormat: getter(props.catalogFormat), catalog: getter(props.catalog), - probe: getter(props.probe), paused: getter(props.paused ?? false), delay: getter(props.delay ?? "auto"), buffer: getter(props.buffer ?? Milli.zero), @@ -151,7 +152,7 @@ export class Player { broadcast: this.broadcast, target: this.in.video.target, supported: Video.Decoder.supported, - probe: this.in.probe, + rate: this.#videoRate, }); const audioSource = new Audio.Source({ broadcast: this.broadcast, @@ -202,18 +203,28 @@ export class Player { this.#signals.cleanup(() => this.textRenderer.close()); // Claim only for the media being downloaded, so a hidden or muted player asks for less. + const audioBitrate = this.#signals.computed((effect) => + effect.get(this.#audioEnabled) ? (effect.get(audioSource.out.config)?.bitrate ?? 0) : 0, + ); const max = this.#signals.computed((effect) => { const video = effect.get(this.#videoEnabled); - const audio = effect.get(this.#audioEnabled); - if (!video && !audio) return 0; + if (!video && !effect.get(this.#audioEnabled)) return 0; const override = effect.get(this.in.viewer.max); if (override !== undefined) return override; - let max = 0; - if (video) max += effect.get(videoSource.out.ceiling) ?? 0; - if (audio) max += effect.get(audioSource.out.config)?.bitrate ?? 0; - return max; + const audio = effect.get(audioBitrate) ?? 0; + return video ? (effect.get(videoSource.out.ceiling) ?? 0) + audio : audio; + }); + const grant = holdViewer(this.#signals, this.in.viewer.viewers, max); + + // Video spends what the grant leaves after the audio it covers. A grant that excludes video, + // while video isn't downloading, says nothing about it, so selection holds its last rate. + this.#signals.run((effect) => { + const rate = effect.get(this.#videoEnabled) ? effect.get(grant) : undefined; + effect.set( + this.#videoRate, + rate === undefined ? undefined : Math.max(0, rate - (effect.get(audioBitrate) ?? 0)), + ); }); - holdViewer(this.#signals, this.in.viewer.viewers, max); this.#signals.run((effect) => { this.#captionsEnabled.set(effect.get(this.in.enabled) && !effect.get(this.in.paused)); diff --git a/js/watch/src/video/source.test.ts b/js/watch/src/video/source.test.ts index 5b09e305c19..9bc1ad2d09c 100644 --- a/js/watch/src/video/source.test.ts +++ b/js/watch/src/video/source.test.ts @@ -506,7 +506,7 @@ describe("Source viewer ceiling", () => { const source = new Source({ broadcast, supported: async () => true }); try { await settle(); - // Over the selection margin, so an estimate that reaches it selects 1080p. + // Over the selection margin, so a rate that reaches it selects 1080p. expect(source.out.ceiling.peek()).toBe(5_000_000); catalog.set({ @@ -523,20 +523,16 @@ describe("Source viewer ceiling", () => { } }); - it("is an estimate that selects that rendition", async () => { - const probe = new Signal<{ estimatedRecvRate: number } | undefined>(undefined); - const source = new Source({ - broadcast: mockBroadcast(ladder()), - supported: async () => true, - probe: probe as never, - }); + it("is a rate that selects that rendition", async () => { + const rate = new Signal(undefined); + const source = new Source({ broadcast: mockBroadcast(ladder()), supported: async () => true, rate }); try { await settle(); const ceiling = source.out.ceiling.peek() ?? 0; - probe.set({ estimatedRecvRate: ceiling }); + rate.set(ceiling); await settle(); expect(source.out.track.peek()).toBe("1080p"); - probe.set({ estimatedRecvRate: ceiling - 1 }); + rate.set(ceiling - 1); await settle(); expect(source.out.track.peek()).toBe("720p"); } finally { @@ -544,6 +540,25 @@ describe("Source viewer ceiling", () => { } }); + it("holds the last rate while it is unknown, and ranks alone before the first", async () => { + const rate = new Signal(undefined); + const source = new Source({ broadcast: mockBroadcast(ladder()), supported: async () => true, rate }); + try { + await settle(); + expect(source.out.track.peek()).toBe("1080p"); + + rate.set(1_000_000); + await settle(); + expect(source.out.track.peek()).toBe("360p"); + + rate.set(undefined); + await settle(); + expect(source.out.track.peek()).toBe("360p"); + } finally { + source.close(); + } + }); + it("skips renditions without a catalog bitrate, and is unset when none has one", async () => { const { broadcast, catalog } = mutableBroadcast({ "360p": config("avc1.640028", { codedWidth: 640, codedHeight: 360, bitrate: 800_000 }), @@ -564,7 +579,7 @@ describe("Source viewer ceiling", () => { } }); - it("stays within the target's caps, without margin when the estimate cannot steer", async () => { + it("stays within the target's caps, without margin when the rate cannot steer", async () => { const target = new Signal({ height: 720 }); const source = new Source({ broadcast: mockBroadcast(ladder()), target, supported: async () => true }); try { @@ -579,7 +594,7 @@ describe("Source viewer ceiling", () => { await settle(); expect(source.out.ceiling.peek()).toBe(2_400_000); - // A zero bitrate is explicit too: the lowest rendition, not the estimate's pick. + // A zero bitrate is explicit too: the lowest rendition, not the rate's pick. target.set({ bitrate: 0 }); await settle(); expect(source.out.ceiling.peek()).toBe(800_000); @@ -588,33 +603,3 @@ describe("Source viewer ceiling", () => { } }); }); - -describe("Source probe observation", () => { - it("does not observe the probe without a selectable rendition", async () => { - let reads = 0; - const probe = new Signal(undefined); - const counted = { - peek: () => { - reads++; - return probe.peek(); - }, - subscribe: (fn: () => void) => { - reads++; - return probe.subscribe(fn); - }, - changed: () => probe.changed(), - }; - const source = new Source({ - broadcast: mockBroadcast({ hd: config("avc1.640028", { bitrate: 1_000_000, enabled: false }) }), - supported: async () => true, - probe: counted as never, - }); - try { - await settle(); - expect(source.out.track.peek()).toBeUndefined(); - expect(reads).toBe(0); - } finally { - source.close(); - } - }); -}); diff --git a/js/watch/src/video/source.ts b/js/watch/src/video/source.ts index 02e05fd2410..6382418c257 100644 --- a/js/watch/src/video/source.ts +++ b/js/watch/src/video/source.ts @@ -1,5 +1,4 @@ import * as Catalog from "@moq/hang/catalog"; -import type * as Moq from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; import type { Broadcast } from "../broadcast"; import { SupportProbe } from "../support-probe"; @@ -27,7 +26,7 @@ export type Target = { // Maximum desired bitrate in bits per second, a cap rather than a hint: selection picks the // best rendition within it, and `0` picks the lowest rendition with a known bitrate. - // Omit it to select from the connection's PROBE estimate instead. + // Omit it to select from the `rate` input instead. bitrate?: number; }; @@ -40,10 +39,10 @@ export type SourceInput = { // probe are filtered out. Nothing is selected until one is provided. supported: Getter; - // The connection's PROBE estimates, used to auto-select a rendition when the target has no - // explicit bitrate. Usually wired from a `Connection`'s `probe`. - // Optional: without it auto-selection falls back to the rank order alone. - probe: Getter; + // The receive rate in bits per second this video may spend, used to auto-select a rendition + // when the target has no explicit bitrate. A `Player` wires its viewer grant less its audio. + // While `undefined`, selection keeps the last rate it had, or ranks alone without one. + rate: Getter; }; /** Signals the source derives. */ @@ -61,11 +60,11 @@ export type SourceOutput = { // The receive rate, in bits per second, at which selection settles on the best rendition // the target allows, or undefined when no candidate has a catalog bitrate. A player claims it - // as its viewer ceiling, so a probe that reaches it makes that rendition selectable. + // as its viewer ceiling, so a grant that reaches it makes that rendition selectable. ceiling: Signal; }; -// Automatic selection spends at most this share of the receive estimate, to avoid oscillation. +// Automatic selection spends at most this share of the receive rate, to avoid oscillation. const MARGIN = 0.8; /** @@ -205,7 +204,7 @@ function preferredRenditions(renditions: Record): R return Object.fromEntries(entries.filter(([, config]) => (config.preference ?? 0) === top)); } -/** Whether the receive estimate steers selection: not with nothing to select, or a pinned rendition or bitrate. */ +/** Whether the receive rate steers selection: not with nothing to select, or a pinned rendition or bitrate. */ function steers(available: Record, target: Target | undefined): boolean { if (Object.keys(available).length === 0) return false; return !(target?.name && target.name in available) && target?.bitrate === undefined; @@ -234,6 +233,9 @@ export class Source { /** Whether rendition support is still being resolved. @internal */ readonly pending: Getter = this.#probe.pending; + // The last defined `rate`, held while it is unknown, such as across a reconnect. + #rate: number | undefined; + #signals = new Effect(); constructor(props?: Inputs) { @@ -241,7 +243,7 @@ export class Source { broadcast: getter(props?.broadcast), target: getter(props?.target), supported: getter(props?.supported), - probe: getter(props?.probe), + rate: getter(props?.rate), }; this.#signals.run(this.#runCatalog.bind(this)); @@ -271,9 +273,9 @@ export class Source { #runSelected(effect: Effect): void { const available = enabledRenditions(effect.get(this.#out.available)); const target = effect.get(this.in.target); - // Read the estimate only when it steers selection: observing it requests PROBE. - const estimate = steers(available, target) ? effect.get(this.in.probe)?.estimatedRecvRate : undefined; - const selected = this.#choose(available, target, estimate); + // Read the rate only when it steers selection, so a pinned choice doesn't rerun with it. + if (steers(available, target)) this.#rate = effect.get(this.in.rate) ?? this.#rate; + const selected = this.#choose(available, target, this.#rate); if (!selected) return; effect.set(this.#out.track, selected); @@ -283,26 +285,26 @@ export class Source { #runCeiling(effect: Effect): void { const available = enabledRenditions(effect.get(this.#out.available)); const target = effect.get(this.in.target); - // An unlimited estimate picks the best rendition bandwidth could ever buy. + // An unlimited rate picks the best rendition bandwidth could ever buy. const best = this.#choose(available, target, Number.POSITIVE_INFINITY); const bitrate = best === undefined ? undefined : available[best].bitrate; if (bitrate === undefined) return; - // Only the estimate's discounted share counts, so it must reach the bitrate over the margin. + // Only the rate's discounted share counts, so it must reach the bitrate over the margin. const ceiling = steers(available, target) ? Math.ceil(bitrate / MARGIN) : bitrate; effect.set(this.#out.ceiling, ceiling, undefined); } - // Pick among the enabled renditions, given the receive estimate if known. + // Pick among the enabled renditions, given the receive rate if known. #choose( available: Record, target: Target | undefined, - estimate: number | undefined, + rate: number | undefined, ): string | undefined { if (target?.name && target.name in available) return target.name; if (Object.keys(available).length === 0) return undefined; - if (estimate != null && steers(available, target)) { - target = { ...target, bitrate: Math.round(estimate * MARGIN) }; + if (rate != null && steers(available, target)) { + target = { ...target, bitrate: Math.round(rate * MARGIN) }; } return this.#select(preferredRenditions(available), target); diff --git a/js/watch/src/viewer.ts b/js/watch/src/viewer.ts index 8ba5de0c653..28697b4e2cf 100644 --- a/js/watch/src/viewer.ts +++ b/js/watch/src/viewer.ts @@ -1,8 +1,9 @@ import type { Bandwidth } from "@moq/net"; -import type { Effect, Getter } from "@moq/signals"; +import { type Effect, type Getter, Signal } from "@moq/signals"; /** - * Hold one viewer on `viewers` while `max` is nonzero, keeping its ceiling at `max`. + * Hold one viewer on `viewers` while `max` is nonzero, keeping its ceiling at `max`, and return its + * grant: the viewer's slice of the receive estimate, or `undefined` without a claim or an estimate. * * The claim is released when `max` drops to zero or `undefined`, `viewers` changes or goes away, or * `effect` closes. A ceiling the registry refuses, such as a negative one or one from a catalog @@ -15,13 +16,18 @@ export function holdViewer( effect: Effect, viewers: Getter | undefined>, max: Getter, -): void { +): Getter { + const grant = new Signal(undefined); + effect.run((outer) => { const registry = outer.get(viewers); if (!registry) return; let viewer: Bandwidth.Viewer | undefined; - outer.cleanup(() => viewer?.close()); + outer.cleanup(() => { + viewer?.close(); + grant.set(undefined); + }); outer.run((inner) => { const ceiling = inner.get(max) ?? 0; @@ -29,6 +35,8 @@ export function holdViewer( try { if (viewer) viewer.update(ceiling); else viewer = registry.watch(ceiling); + const held = viewer; + inner.run((nested) => grant.set(nested.get(held.rate))); return; } catch (err) { console.warn("[Player] viewer ceiling refused; releasing the claim until it changes", err); @@ -36,6 +44,9 @@ export function holdViewer( } viewer?.close(); viewer = undefined; + grant.set(undefined); }); }); + + return grant; } diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 68894f03235..341e1082a43 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -100,7 +100,6 @@ This README's own work, once the children land: - [One page-wide getStats sampling ticker](/quest/m2/probe/stats-ticker.md) - a page's connections share one sampling ticker - [Padding probes](/quest/m2/probe/padding.md) - a browser probes with a lowest-priority padding stream on an ALR schedule - [JS rung disable](/quest/m2/probe/rung-disable-js.md) - `@moq/publish` applies the native rung rule, recovering through padding -- [Viewer up-switch](/quest/m2/probe/viewer-upswitch.md) - a viewer capped by its small rendition finds headroom through PROBE and moves up ## Related diff --git a/quest/m2/probe/viewer-upswitch.md b/quest/m2/probe/viewer-upswitch.md deleted file mode 100644 index a19124f91a8..00000000000 --- a/quest/m2/probe/viewer-upswitch.md +++ /dev/null @@ -1,42 +0,0 @@ -# [M] A viewer on a small rendition can find headroom and move up - -## Goal - -A `@moq/watch` viewer with no `target.bitrate`, whose receive estimate is -capped by the small rendition it plays, can confirm spare capacity and select -a larger rendition, without pinning by name. - -## Plan - -`js/watch/src/video/source.ts` caps automatic selection at 0.8 times -`estimatedRecvRate`. The estimate only follows what is being sent, so it stays -app-limited, and `js/net` never sends a PROBE target to request headroom above -it. - -Decided (2026-10-04): its own quest, after the transport can validate -headroom. The viewer sends a PROBE target and selection uses the validated -estimate. - -Decided with the maintainer on 2026-10-17: this joined the -[probe epic](/quest/m2/probe/README.md). Players -set the viewer target (`viewer` on `Watch.Player`), the session sends it as its PROBE target -([moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)), and the relay's sender probes the downlink up to it; this -quest makes selection act on the estimate that rises. The relay runs -moq-quic, whose native probing ([moq-dev/moq#6635](https://github.com/moq-dev/moq/pull/6635)) is that -sender. - -Selection reads its broadcast's viewer grant (`Bandwidth.Viewer.rate`), not -the connection's whole -`estimatedRecvRate`, so several watchers on one pooled connection don't each -select against the full downlink (decided with the maintainer on 2026-10-19). - -The player's viewer ceiling already covers the selection margin and audio: -it is the best enabled video rendition's bitrate over 0.8 (the rate at which -`Video.Source` selects it, its `out.ceiling`) plus the selected audio -rendition's bitrate. A grant is capped at the ceiling, so selection keeps its -0.8x discount but subtracts the audio bitrate from the grant first; a full -grant then selects the best rendition. - -## Closes - -- [#4773](https://github.com/moq-dev/moq/issues/4773) - close this issue when the quest finishes From 9f1e931348daf140352a89cffdd1d299f7fc3fa2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:28:11 -0800 Subject: [PATCH 3/5] fix: callers read the connection's probe instead of the player's Co-Authored-By: Claude Opus 5.5 --- bench/browser/page/media.ts | 2 +- test/audio-quality/clients/js/src/probe.test.ts | 2 +- test/audio-quality/clients/js/src/probe.ts | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/bench/browser/page/media.ts b/bench/browser/page/media.ts index 3b884fdfd05..73bc1081820 100644 --- a/bench/browser/page/media.ts +++ b/bench/browser/page/media.ts @@ -182,10 +182,10 @@ async function watch(config: Media): Promise<{ first_frame_ms: number }> { const connection = new Moq.Connection({ url: new URL(config.url), websocket: { enabled: false } }); player = new Watch.Player({ origin: connection.origin, - probe: connection.probe, name: Moq.Path.from(config.path), video: { canvas, visible: "always", backend: "2d" }, audio: { muted: true }, + viewer: { viewers: connection.viewers }, }); const sampler = setInterval(() => { const memory = (performance as Performance & { memory?: { usedJSHeapSize: number } }).memory; diff --git a/test/audio-quality/clients/js/src/probe.test.ts b/test/audio-quality/clients/js/src/probe.test.ts index 8433d4efc69..0cac89a67ef 100644 --- a/test/audio-quality/clients/js/src/probe.test.ts +++ b/test/audio-quality/clients/js/src/probe.test.ts @@ -17,8 +17,8 @@ test("audio-only sampling holds probe demand until its final RTT sample", async }); const empty = new Signal(undefined); const watch = { + connection: { probe: network }, player: { - in: { probe: network }, audio: { out: { stalled: new Signal(false), context: empty, root: empty, timestamp: empty, stats: empty }, source: { out: { config: empty } }, diff --git a/test/audio-quality/clients/js/src/probe.ts b/test/audio-quality/clients/js/src/probe.ts index 16758a653d0..c8ae79c7e24 100644 --- a/test/audio-quality/clients/js/src/probe.ts +++ b/test/audio-quality/clients/js/src/probe.ts @@ -63,7 +63,7 @@ export function probe(watch: MoqWatch, capture = false): Probe { const signals = new Effect(); // Peeking does not request PROBE reports on an audio-only page. - signals.subscribe(watch.player.in.probe, () => {}); + signals.subscribe(watch.connection.probe, () => {}); // Stall changes are taken as they happen: a re-stall shorter than the sample grid is exactly the // one a 250 ms read would miss, and it is what tells a stall from an underrun. @@ -128,7 +128,7 @@ export function probe(watch: MoqWatch, capture = false): Probe { stalled: audio.out.stalled.peek(), delay: sync.out.delay.peek(), playerUnderruns: audio.out.stats.peek()?.underruns, - rtt: watch.player.in.probe.peek()?.rtt, + rtt: watch.connection.probe.peek()?.rtt, jitter: audio.source.out.config.peek()?.jitter, renditionDelay: audio.source.out.config.peek()?.delay, outputLatency: context ? context.outputLatency * 1000 : undefined, From 477b0a6f257bfd54b56f33cd4fba7b1a3fa668cd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:33:45 -0800 Subject: [PATCH 4/5] docs(watch): stop probing but keep adapting with setTarget(0) Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/watch.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index f8ba12d911f..1117275bb90 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -210,7 +210,8 @@ instead of each selecting against all of it. Set `viewer.max` (`controls.viewer.max` on ``) to claim a fixed ceiling in bits per second instead while media downloads, which also caps what video selects, or `0` to claim nothing; omit `viewer.viewers` to leave the connection's estimate unclaimed. Without a claim, video selects the best rendition its -`video.target` allows. +`video.target` allows. To stop the relay probing while still adapting, keep the claim and call +`connection.viewers.setTarget(0)`. To chart when each audio frame arrived against when it plays, open an `arrivals()` handle on the audio decoder. It yields every frame received while it is open, stamped From ae304170036bf8bbc14a10c2259f49bcf948a5a5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:36:39 -0800 Subject: [PATCH 5/5] docs(watch): leave MIGRATE.md to the release cut The migration note stays in the PR's Impact section, per the rule that only the release cut edits MIGRATE.md. Co-Authored-By: Claude Opus 5.5 --- js/watch/MIGRATE.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/js/watch/MIGRATE.md b/js/watch/MIGRATE.md index 6767184a1e8..d6a80096983 100644 --- a/js/watch/MIGRATE.md +++ b/js/watch/MIGRATE.md @@ -4,14 +4,6 @@ How to update your code for each breaking change, newest first. ## Unreleased -### Video selects from the viewer grant - -`Player` no longer takes `probe`: video selects from its viewer's grant (`viewer.viewers`), less the audio the claim covers, instead of the connection's whole `estimatedRecvRate`. -Remove `probe` and pass `viewer: { viewers: connection.viewers }`; without a claim, video selects the best rendition its target allows. -`Video.Source` takes `rate`, the receive rate in bits per second video may spend, in place of `probe`. -To keep selecting from the whole connection estimate, pass `rate: new Signals.Derived([connection.probe], (probe) => probe?.estimatedRecvRate)`. -An unknown rate now holds the last one instead of selecting the best rendition, so a reconnect no longer jumps to the top of the ladder. - ### Players claim a viewer target from the catalog `` and `@moq/room` now hold a viewer on their connection's `viewers` for as long as they download, with a ceiling taken from the catalog, so a relay that probes raises the receive estimate toward the best enabled rendition.