diff --git a/js/watch/api/index.api.md b/js/watch/api/index.api.md index 4e444f96155..7e3076ddbb4 100644 --- a/js/watch/api/index.api.md +++ b/js/watch/api/index.api.md @@ -80,6 +80,7 @@ export namespace Audio { available: Signals.Signal>; catalog: Signals.Signal; config: Signals.Signal; + error: Signals.Signal; jitter: Signals.Signal; track: Signals.Signal; }; diff --git a/js/watch/src/audio/source.test.ts b/js/watch/src/audio/source.test.ts index 8237f14b156..2a3dfc28ddf 100644 --- a/js/watch/src/audio/source.test.ts +++ b/js/watch/src/audio/source.test.ts @@ -20,10 +20,15 @@ function broadcast(renditions: Record) { return { catalog, broadcast: { out: { catalog } } as unknown as Broadcast }; } -// Wait on the probe's causal boundary, rather than a timer or a guessed number of ticks. +// Wait out the probe, then a tick for the effects its result wakes. A probe served wholly from +// the cache sets and clears `pending` in one run, which notifies nothing, so start with a tick +// that lets the rerun happen rather than waiting on a change that may never come. async function settled(source: Source): Promise { - if (!source.pending.peek()) await source.pending.changed(); - while (source.pending.peek()) await source.pending.changed(); + await yieldNow(); + while (source.pending.peek()) { + await source.pending.changed(); + await yieldNow(); + } } test("a rejected rendition probe preserves its supported siblings", async () => { @@ -195,3 +200,113 @@ test("holds on a broadcast whose renditions match the previous one", async () => source.close(); } }); + +async function quietly(fn: () => Promise): Promise { + const warn = console.warn; + console.warn = () => {}; + try { + await fn(); + } finally { + console.warn = warn; + } +} + +test("reports NotSupportedError when no rendition is supported", () => + quietly(async () => { + const state = broadcast({ mic: config("opus") }); + const source = new Source({ broadcast: state.broadcast, supported: async () => false }); + try { + await settled(source); + expect(source.out.error.peek()?.name).toBe("NotSupportedError"); + expect(source.out.available.peek()).toEqual({}); + + state.catalog.set({ audio: { renditions: {} } }); + await settled(source); + expect(source.out.error.peek()).toBeUndefined(); + } finally { + source.close(); + } + })); + +test("a rejecting probe alone is unsupported", () => + quietly(async () => { + const source = new Source({ + broadcast: broadcast({ mic: config("opus") }).broadcast, + supported: async () => { + throw new TypeError("probe failed"); + }, + }); + try { + await settled(source); + expect(source.out.error.peek()?.name).toBe("NotSupportedError"); + expect(source.out.track.peek()).toBeUndefined(); + } finally { + source.close(); + } + })); + +test("does not wedge the effect when a support probe never settles", async () => { + const supported = new Signal<(config: Catalog.AudioConfig) => Promise>(() => new Promise(() => {})); + const source = new Source({ broadcast: broadcast({ mic: config("opus") }).broadcast, supported }); + try { + if (!source.pending.peek()) await source.pending.changed(); + expect(source.out.available.peek()).toEqual({}); + expect(source.out.error.peek()).toBeUndefined(); + + // Swapping the probe reruns the effect, which has to tear the parked one down first. + supported.set(async () => true); + await settled(source); + expect(source.out.track.peek()).toBe("mic"); + } finally { + source.close(); + } +}); + +test("a catalog replaced while its probe is pending publishes only the replacement", async () => { + const probes = new Map void>(); + const state = broadcast({ old: config("opus") }); + const source = new Source({ + broadcast: state.broadcast, + supported: (c) => new Promise((resolve) => probes.set(c.codec, resolve)), + }); + try { + if (!source.pending.peek()) await source.pending.changed(); + const old = probes.get("opus"); + expect(old).toBeDefined(); + + state.catalog.set({ audio: { renditions: { next: config("mp4a.40.2") } } }); + while (!probes.has("mp4a.40.2")) await yieldNow(); + + // The torn-down probe settles late; its result must not land. + old?.(true); + probes.get("mp4a.40.2")?.(true); + await settled(source); + expect(Object.keys(source.out.available.peek())).toEqual(["next"]); + expect(source.out.track.peek()).toBe("next"); + } finally { + source.close(); + } +}); + +test("serves unchanged configs from the cache when the catalog changes", async () => { + const state = broadcast({ mic: config("opus") }); + const probed: string[] = []; + const source = new Source({ + broadcast: state.broadcast, + supported: async (c) => { + probed.push(c.codec); + return true; + }, + }); + try { + await settled(source); + expect(probed).toEqual(["opus"]); + + state.catalog.set({ audio: { renditions: { mic: config("opus"), backup: config("mp4a.40.2") } } }); + await settled(source); + expect(probed).toEqual(["opus", "mp4a.40.2"]); + expect(Object.keys(source.out.available.peek())).toEqual(["mic", "backup"]); + } finally { + source.close(); + } +}); diff --git a/js/watch/src/audio/source.ts b/js/watch/src/audio/source.ts index 901476fedd0..0641d075d45 100644 --- a/js/watch/src/audio/source.ts +++ b/js/watch/src/audio/source.ts @@ -2,6 +2,7 @@ import { Milli } from "@moq/clock"; import type * as Catalog from "@moq/hang/catalog"; import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; import type { Broadcast } from "../broadcast"; +import { SupportProbe } from "../support-probe"; /** What the viewer wants from the audio rendition. */ export type Target = { @@ -32,6 +33,11 @@ export type SourceInput = { export type SourceOutput = { catalog: Signal; available: Signal>; + + // Why no rendition can be chosen, or undefined while healthy or still probing. A + // `NotSupportedError` means the browser can decode none of the catalog's renditions. + error: Signal; + track: Signal; config: Signal; @@ -47,18 +53,20 @@ export class Source { /** The wired inputs, read-only. */ readonly in: Readonlys; + #probe = new SupportProbe("audio"); + readonly #out: SourceOutput = { catalog: new Signal(undefined), available: new Signal>({}), + error: this.#probe.error, track: new Signal(undefined), config: new Signal(undefined), jitter: new Signal(undefined), }; /** The derived outputs, read-only. */ readonly out = readonlys(this.#out); - #pending = new Signal(false); /** Whether rendition support is still being resolved. @internal */ - readonly pending: Getter = this.#pending; + readonly pending: Getter = this.#probe.pending; // The last selection, which a disable holds while no enabled rendition remains. #held?: { broadcast: Broadcast; track: string }; @@ -92,46 +100,13 @@ export class Source { } #runSupported(effect: Effect): void { + const supported = effect.get(this.in.supported); // Read the catalog from the broadcast itself, so the probe result is tagged with the right one. const broadcast = effect.get(this.in.broadcast); const renditions = (broadcast && effect.get(broadcast.out.catalog)?.audio?.renditions) ?? {}; - const supported = effect.get(this.in.supported); - if (!supported) return; - - effect.set(this.#pending, true, false); - effect.spawn(async () => { - try { - const available: Record = {}; - - for (const [name, config] of Object.entries(renditions)) { - // `supported` comes from the consumer, so we cannot assume it ever settles. A rerun - // waits for the tasks it spawned, so an unraced probe would hold the next run shut. - let isSupported = false; - try { - isSupported = !!(await effect.race(supported(config))); - } catch (err) { - if (effect.abort.aborted) return; - console.warn( - `[Source] audio rendition ${name} (${config.codec}) support probe failed; treating as unsupported`, - err, - ); - } - - // Torn down: stop probing and publish nothing, since the rerun redoes this. - if (effect.abort.aborted) return; - - if (isSupported) available[name] = config; - } - - if (Object.keys(available).length === 0 && Object.keys(renditions).length > 0) { - console.warn("no supported audio renditions found:", renditions); - } - - this.#probed.set(broadcast); - this.#out.available.set(available); - } finally { - this.#pending.set(false); - } + this.#probe.run(effect, supported, renditions, (available) => { + this.#probed.set(broadcast); + this.#out.available.set(available); }); } diff --git a/js/watch/src/support-probe.ts b/js/watch/src/support-probe.ts new file mode 100644 index 00000000000..0af9ffe5b6d --- /dev/null +++ b/js/watch/src/support-probe.ts @@ -0,0 +1,100 @@ +import { type Effect, type Getter, Signal } from "@moq/signals"; + +/** Internal key used to describe which fields can change a support probe's result. */ +export const supportCacheKey = Symbol("supportCacheKey"); + +/** A function that checks if a rendition configuration can be played. */ +type Supported = ((config: Config) => Promise) & { + [supportCacheKey]?: (config: Config) => string; +}; + +/** + * Probes which renditions a `supported` function accepts, shared by the audio and video sources. + * + * A result is cached per rendition until the rendition's config changes, keyed by the probe's + * `supportCacheKey` or else the whole config. + */ +export class SupportProbe { + readonly #kind: string; + + readonly #pending = new Signal(false); + /** Whether rendition support is still being resolved. */ + readonly pending: Getter = this.#pending; + + /** A `NotSupportedError` once no rendition of a non-empty catalog is supported. */ + readonly error = new Signal(undefined); + + #cache = new WeakMap, Map>(); + + constructor(kind: "audio" | "video") { + this.#kind = kind; + } + + /** + * Probe `renditions` within `effect`, then `publish` the supported ones. + * Nothing is published when the effect is torn down first, since its rerun redoes this. + */ + run( + effect: Effect, + supported: Supported | undefined, + renditions: Record, + publish: (available: Record) => void, + ): void { + this.error.set(undefined); + if (!supported) return; + + let cache = this.#cache.get(supported); + if (!cache) { + cache = new Map(); + this.#cache.set(supported, cache); + } + const names = new Set(Object.keys(renditions)); + for (const name of cache.keys()) { + if (!names.has(name)) cache.delete(name); + } + + const cacheKey = supported[supportCacheKey] ?? ((config: Config) => JSON.stringify(config)); + + effect.set(this.#pending, true, false); + effect.spawn(async () => { + const available: Record = {}; + + for (const [name, config] of Object.entries(renditions)) { + const key = cacheKey(config); + const cached = cache.get(name); + let isSupported = cached?.key === key ? cached.supported : undefined; + if (isSupported === undefined) { + try { + // `supported` comes from the consumer, so we cannot assume it ever settles. A + // rerun waits for the tasks it spawned, so an unraced probe would hold it shut. + const result = await effect.race(supported(config)); + // Undefined when torn down; the abort check below handles it. + if (result !== undefined) { + isSupported = !!result; + // Recompute the key: a probe may rewrite the config it accepted. + cache.set(name, { key: cacheKey(config), supported: isSupported }); + } + } catch (err) { + if (effect.abort.aborted) return; + console.warn( + `[Source] ${this.#kind} rendition ${name} (${config.codec}) support probe failed; treating as unsupported`, + err, + ); + } + } + + // Torn down: stop probing and publish nothing, since the rerun redoes this. + if (effect.abort.aborted) return; + + if (isSupported) available[name] = config; + } + + if (Object.keys(available).length === 0 && Object.keys(renditions).length > 0) { + console.warn(`[Source] no supported ${this.#kind} renditions found:`, renditions); + this.error.set(new DOMException(`no supported ${this.#kind} renditions`, "NotSupportedError")); + } + publish(available); + this.#pending.set(false); + }); + } +} diff --git a/js/watch/src/ui/components/unsupported-indicator.test.ts b/js/watch/src/ui/components/unsupported-indicator.test.ts new file mode 100644 index 00000000000..997c544c7a8 --- /dev/null +++ b/js/watch/src/ui/components/unsupported-indicator.test.ts @@ -0,0 +1,63 @@ +import { expect, test } from "bun:test"; +import { yieldNow } from "@moq/clock"; +import { Effect, Signal } from "@moq/signals"; +import type MoqWatch from "../../element"; +import { unsupportedIndicator } from "./unsupported-indicator"; + +const unsupported = () => new DOMException("no supported renditions", "NotSupportedError"); + +test("reports unsupported audio only when the broadcast has no video", async () => { + // The only DOM the component touches: a container holding a text span. + const container = { style: { display: "" }, setAttribute: () => {}, appendChild: () => {} }; + const text = { textContent: "" }; + const original = globalThis.document; + let created = 0; + globalThis.document = { + createElement: () => (created++ === 0 ? container : text), + } as unknown as Document; + + const video = { + catalog: new Signal<{ renditions: Record } | undefined>(undefined), + error: new Signal(undefined), + }; + const audio = { + catalog: new Signal({ renditions: { mic: { codec: "opus" } } }), + error: new Signal(undefined), + }; + const watch = { + broadcast: { out: { status: new Signal("live") } }, + video: { source: { out: video } }, + audio: { source: { out: audio } }, + } as unknown as MoqWatch; + + const effect = new Effect(); + try { + unsupportedIndicator(effect, watch); + await yieldNow(); + expect(container.style.display).toBe("none"); + + audio.error.set(unsupported()); + await yieldNow(); + expect(container.style.display).toBe(""); + expect(text.textContent).toBe("This audio codec is not supported by your browser: opus"); + + // A video section the reachability filter emptied is no video, so audio still reports. + video.catalog.set({ renditions: {} }); + await yieldNow(); + expect(container.style.display).toBe(""); + expect(text.textContent).toBe("This audio codec is not supported by your browser: opus"); + + // Playable video carries the broadcast, so unsupported audio alone is not reported. + video.catalog.set({ renditions: { hd: { codec: "avc1.640028" } } }); + await yieldNow(); + expect(container.style.display).toBe("none"); + + video.error.set(unsupported()); + await yieldNow(); + expect(container.style.display).toBe(""); + expect(text.textContent).toBe("This video codec is not supported by your browser: avc1.640028"); + } finally { + effect.close(); + globalThis.document = original; + } +}); diff --git a/js/watch/src/ui/components/unsupported-indicator.ts b/js/watch/src/ui/components/unsupported-indicator.ts index db02f72bc63..81e7a190ea9 100644 --- a/js/watch/src/ui/components/unsupported-indicator.ts +++ b/js/watch/src/ui/components/unsupported-indicator.ts @@ -1,7 +1,7 @@ import type { Effect } from "@moq/signals"; import type MoqWatch from "../../element"; -/** Shows when the player needs an update or cannot decode any video rendition. */ +/** Shows when the player needs an update, or cannot decode the video or, lacking video, the audio. */ export function unsupportedIndicator(parent: Effect, watch: MoqWatch): HTMLElement { const container = document.createElement("div"); container.className = "watch-ui__notice watch-ui__unsupported-indicator"; @@ -20,16 +20,22 @@ export function unsupportedIndicator(parent: Effect, watch: MoqWatch): HTMLEleme return; } - const unsupported = effect.get(watch.video.source.out.error)?.name === "NotSupportedError"; + // Audio speaks for the broadcast only when there is no video to report on. The reachability + // filter can leave a video section with no renditions, which counts as no video. + const video = effect.get(watch.video.source.out.catalog); + const hasVideo = Object.keys(video?.renditions ?? {}).length > 0; + const kind = hasVideo ? "video" : "audio"; + const source = hasVideo ? watch.video.source : watch.audio.source; + const unsupported = effect.get(source.out.error)?.name === "NotSupportedError"; const show = unsupported && (status === "loading" || status === "live"); container.style.display = show ? "" : "none"; if (!show) return; - const renditions = effect.get(watch.video.source.out.catalog)?.renditions ?? {}; + const renditions = (hasVideo ? video : effect.get(watch.audio.source.out.catalog))?.renditions ?? {}; const codecs = [...new Set(Object.values(renditions).map((rendition) => rendition.codec))].join(", "); text.textContent = codecs - ? `This video codec is not supported by your browser: ${codecs}` - : "This video codec is not supported by your browser"; + ? `This ${kind} codec is not supported by your browser: ${codecs}` + : `This ${kind} codec is not supported by your browser`; }); return container; diff --git a/js/watch/src/video/config.ts b/js/watch/src/video/config.ts index 0c284366e48..79d20ce83f0 100644 --- a/js/watch/src/video/config.ts +++ b/js/watch/src/video/config.ts @@ -1,8 +1,5 @@ import type * as Catalog from "@moq/hang/catalog"; -/** Internal key used to describe which fields can change a support probe's result. */ -export const supportCacheKey = Symbol("supportCacheKey"); - /** The catalog fields that determine the demuxer and WebCodecs decoder instance. */ export type DecoderConfig = Pick< Catalog.VideoConfig, diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 0ca3ddda970..8a97fd516c4 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -18,14 +18,9 @@ import { import { rotateVideoDimensions } from "@moq/video"; import { base64ToBytes } from "../base64"; import { type Failure, failureMoved, nextMedia, subscribeMedia } from "../media"; +import { supportCacheKey } from "../support-probe"; import type { Sync } from "../sync"; -import { - type DecoderConfig, - decoderConfigKey, - type PlaybackIdentity, - playbackIdentity, - supportCacheKey, -} from "./config"; +import { type DecoderConfig, decoderConfigKey, type PlaybackIdentity, playbackIdentity } from "./config"; import { caughtUp, renditionJitter, switchJitter } from "./playhead"; import { Recovery } from "./recovery"; import type { Source } from "./source"; diff --git a/js/watch/src/video/source.test.ts b/js/watch/src/video/source.test.ts index d6e33de2955..c40569d1465 100644 --- a/js/watch/src/video/source.test.ts +++ b/js/watch/src/video/source.test.ts @@ -4,7 +4,8 @@ import * as Catalog from "@moq/hang/catalog"; import { Path } from "@moq/net"; import { Signal } from "@moq/signals"; import { Broadcast } from "../broadcast"; -import { decoderConfigKey, supportCacheKey } from "./config"; +import { supportCacheKey } from "../support-probe"; +import { decoderConfigKey } from "./config"; import { Source } from "./source"; const flush = () => yieldNow(); diff --git a/js/watch/src/video/source.ts b/js/watch/src/video/source.ts index 6ddbf1922c3..31162082e73 100644 --- a/js/watch/src/video/source.ts +++ b/js/watch/src/video/source.ts @@ -2,7 +2,7 @@ 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 { supportCacheKey } from "./config"; +import { SupportProbe } from "../support-probe"; /** * A function that checks if a video configuration can be played. @@ -11,10 +11,6 @@ import { supportCacheKey } from "./config"; */ export type Supported = (config: Catalog.VideoConfig) => Promise; -type CacheableSupported = Supported & { - [supportCacheKey]?: (config: Catalog.VideoConfig) => string; -}; - /** What the viewer wants from the video rendition; the source picks the best one within it. */ export type Target = { // Optional manual override for the selected rendition name. @@ -207,18 +203,19 @@ export class Source { /** The wired inputs, read-only. */ readonly in: Readonlys; + #probe = new SupportProbe("video"); + readonly #out: SourceOutput = { catalog: new Signal(undefined), available: new Signal>({}), - error: new Signal(undefined), + error: this.#probe.error, track: new Signal(undefined), config: new Signal(undefined), }; /** The derived outputs, read-only. */ readonly out = readonlys(this.#out); - #pending = new Signal(false); /** Whether rendition support is still being resolved. @internal */ - readonly pending: Getter = this.#pending; + readonly pending: Getter = this.#probe.pending; // The last selection, which a disable holds while no enabled rendition remains. #held?: { broadcast: Broadcast; track: string }; @@ -228,7 +225,6 @@ export class Source { #probed = new Signal(undefined); #signals = new Effect(); - #supportCache = new WeakMap>(); constructor(props?: Inputs) { this.in = { @@ -255,72 +251,12 @@ export class Source { #runSupported(effect: Effect): void { const supported = effect.get(this.in.supported); - if (!supported) { - this.#out.error.set(undefined); - return; - } - // Read the catalog from the broadcast itself, so the probe result is tagged with the right one. const broadcast = effect.get(this.in.broadcast); const renditions = (broadcast && effect.get(broadcast.out.catalog)?.video?.renditions) ?? {}; - this.#out.error.set(undefined); - let cache = this.#supportCache.get(supported); - if (!cache) { - cache = new Map(); - this.#supportCache.set(supported, cache); - } - const names = new Set(Object.keys(renditions)); - for (const name of cache.keys()) { - if (!names.has(name)) cache.delete(name); - } - - effect.set(this.#pending, true, false); - effect.spawn(async () => { - const available: Record = {}; - - for (const [name, config] of Object.entries(renditions)) { - const cacheKey = (supported as CacheableSupported)[supportCacheKey]; - const key = cacheKey ? cacheKey(config) : JSON.stringify(config); - const cached = cache.get(name); - let isSupported: boolean | undefined = false; - if (cached?.key === key) { - isSupported = cached.supported; - } else { - let failed = false; - try { - // `supported` comes from the consumer, so we cannot assume it ever settles. A - // rerun waits for the tasks it spawned, so an unraced probe would hold it shut. - isSupported = await effect.race(supported(config)); - } catch (err) { - failed = true; - console.warn( - `[Source] video rendition ${name} (${config.codec}) support probe failed; treating as unsupported`, - err, - ); - } - if (!failed && isSupported !== undefined) { - cache.set(name, { - key: cacheKey ? cacheKey(config) : JSON.stringify(config), - supported: isSupported, - }); - } - } - - // Torn down: stop probing and publish nothing, since the rerun redoes this. - if (effect.abort.aborted) return; - - if (isSupported) available[name] = config; - } - - if (Object.keys(available).length === 0 && Object.keys(renditions).length > 0) { - console.warn("[Source] No supported video renditions found:", renditions); - this.#out.error.set(new DOMException("no supported video renditions", "NotSupportedError")); - } else { - this.#out.error.set(undefined); - } + this.#probe.run(effect, supported, renditions, (available) => { this.#probed.set(broadcast); this.#out.available.set(available); - this.#pending.set(false); }); } diff --git a/quest/m2/README.md b/quest/m2/README.md index aae6ce7d51b..e3454ee9330 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -124,7 +124,6 @@ lite-07; bitrate enforcement is not part of this release. - [One port on the io_uring workers](/quest/m2/uring-demux.md) - `moq-uring`'s workers host the UDP demux, so a ring relay keeps WebRTC media and SRT on its QUIC port - [Synced data playback](/quest/m2/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back - [Watch decode gate](/quest/m2/watch-decode-gate.md) - video lookahead stays encoded until it is near presentation, like audio -- [One support probe for watch audio and video](/quest/m2/watch-support-probe.md) - one probe helper with video's cache, and audio reports unsupported renditions - [moqsrc A/V sync](/quest/m2/moqsrc-av-sync.md) - a nightly test measures A/V skew from `moqsrc` through clock-synced sinks - [fMP4 ambisonic layout](/quest/m2/mux-vr-ambisonic-fmp4.md) - fMP4 Opus import fills `ambisonic` from the `dOps` mapping table - [Linux decoded frames](/quest/m2/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback diff --git a/quest/m2/watch-support-probe.md b/quest/m2/watch-support-probe.md deleted file mode 100644 index d41718ea7b5..00000000000 --- a/quest/m2/watch-support-probe.md +++ /dev/null @@ -1,26 +0,0 @@ -# [S] One support probe for watch audio and video - -## Goal - -The watch audio and video `Source`s probe rendition support through one -private helper that owns the race against an unsettled probe, the config-keyed -cache, `pending`, and abort. Audio gains video's cache and an `out.error` that -is `NotSupportedError` when no audio rendition is supported, and the bundled -UI's unsupported indicator reports an audio-only broadcast it cannot play. -Rendition selection stays separate per kind. Additive `@moq/watch` API; no -wire impact. - -## Plan - -Decided 2026-10-27 (maintainer interview, from the 2026-10-27 refactor audit): - -- Audio exposes `out.error` like video, and the unsupported indicator is its - consumer: it fires when video is unsupported, or when the catalog has no - video and audio is unsupported. -- Video's `#runSupported` (`js/watch/src/video/source.ts`) caches per - rendition by `supportCacheKey` or the JSON config and sets the error; audio's - (`js/watch/src/audio/source.ts`) re-probes every run and only logs. The - helper takes video's behavior for both. -- Test a catalog replaced while a probe is pending, a probe that never - settles, a rejecting probe, and a catalog change that leaves configs - unchanged (served from cache).