@rapidmx/meet-plugin 0.6.0 → 0.8.1

package/apps/shared/media/mediaPreferences.ts

@@ -0,0 +1,105 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * What a participant chose last time - which camera and microphone, whether each was on, and their video filters -
+ * kept in this browser's `localStorage` so the next meeting starts the same way.
+ *
+ * It lives on the device rather than on the server on purpose: most participants are guests with no account, and a
+ * camera's id means nothing on another machine anyway. Nothing here is sent anywhere.
+ *
+ * Storage can be missing or refuse to work (private windows, blocked site data, a full quota, server-side rendering),
+ * and none of that is worth failing a call over: every function tolerates it and behaves as if nothing was saved.
+ * Whatever is read back is validated, since it may be from another version of this plugin or edited by hand.
+ *
+ * The custom background picture is stored under its own key: it is by far the largest thing kept, and if it doesn't
+ * fit the rest of the settings should still be saved.
+ */
+import { type VideoFilters, sanitizeFilters } from "./filters/filterTypes.js";
+
+export interface MediaPreferences {
+    /** The camera and microphone the participant picked, by `deviceId`. */
+    cameraId?: string;
+    microphoneId?: string;
+    /** Whether the microphone / camera was on when they left. */
+    micEnabled?: boolean;
+    cameraEnabled?: boolean;
+    filters?: VideoFilters;
+    /** The custom background, as a (downscaled) image data URL. */
+    backgroundImage?: string;
+}
+
+export const PREFERENCES_KEY = "rapidmx.meet.preferences";
+export const BACKGROUND_KEY = "rapidmx.meet.background";
+
+/** The `Storage` to use, or `undefined` where there is none - looked up lazily and guarded, since merely reading
+ * `localStorage` can throw (a browser blocking site data) and it doesn't exist on the server. */
+export function defaultStorage(): Storage | undefined {
+    try {
+        return typeof localStorage === "undefined" ? undefined : localStorage;
+    } catch {
+        return undefined;
+    }
+}
+
+function readJson(storage: Storage, key: string): Record<string, unknown> {
+    try {
+        const parsed: unknown = JSON.parse(storage.getItem(key) ?? "{}");
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {};
+    } catch {
+        return {};
+    }
+}
+
+const text = (value: unknown): string | undefined => (typeof value === "string" && value ? value : undefined);
+const flag = (value: unknown): boolean | undefined => (typeof value === "boolean" ? value : undefined);
+
+export function loadPreferences(storage: Storage | undefined = defaultStorage()): MediaPreferences {
+    if (!storage) {
+        return {};
+    }
+    const raw = readJson(storage, PREFERENCES_KEY);
+    let backgroundImage: string | undefined;
+    try {
+        const stored = storage.getItem(BACKGROUND_KEY);
+        backgroundImage = stored?.startsWith("data:image/") ? stored : undefined;
+    } catch {
+        backgroundImage = undefined;
+    }
+    return {
+        cameraId: text(raw.cameraId),
+        microphoneId: text(raw.microphoneId),
+        micEnabled: flag(raw.micEnabled),
+        cameraEnabled: flag(raw.cameraEnabled),
+        filters: raw.filters === undefined ? undefined : sanitizeFilters(raw.filters),
+        backgroundImage,
+    };
+}
+
+/** Merges `patch` into what is saved. A key set to `undefined` is forgotten; a failure to save is ignored. */
+export function savePreferences(patch: Partial<MediaPreferences>, storage: Storage | undefined = defaultStorage()): void {
+    if (!storage) {
+        return;
+    }
+    const { backgroundImage, ...rest } = patch;
+    if (Object.keys(rest).length > 0) {
+        try {
+            const merged = { ...readJson(storage, PREFERENCES_KEY), ...rest };
+            storage.setItem(PREFERENCES_KEY, JSON.stringify(merged));
+        } catch {
+            // Nowhere to save - the settings just won't carry over.
+        }
+    }
+    if ("backgroundImage" in patch) {
+        try {
+            if (backgroundImage) {
+                storage.setItem(BACKGROUND_KEY, backgroundImage);
+            } else {
+                storage.removeItem(BACKGROUND_KEY);
+            }
+        } catch {
+            // Most likely the image is too big for what is left of the quota.
+        }
+    }
+}

package/apps/shared/media/useLocalMedia.ts

@@ -20,10 +20,18 @@
  * - **Devices**: `selectDevice()` swaps in another camera or microphone; `devicechange` refreshes the lists.
  * - **Level**: `audioLevel` (0-5) follows the microphone while it is unmuted, for the "your audio is being sent"
  * indicator.
+ * - **Filters**: while any video filter is on (`setFilters()`), `videoTrack`/`videoStream` are the *filtered*
+ * picture (`filters/VideoFilterProcessor.ts`) rather than the camera's own track - so everything downstream, the
+ * lobby preview and every path the call sends over, gets it without knowing. The camera's track stays owned here; the
+ * processor only reads it. If the filtered picture can't be made there is no video at all rather than an unfiltered
+ * one, since the filter may be hiding the participant's room.
+ * - **Remembered settings**: the devices picked, whether the microphone and camera were on, and the filters are
+ * saved on this device (`mediaPreferences.ts`) and applied the next time - a saved device is asked for as a
+ * preference (`ideal`), so one that has since been unplugged falls back to the default instead of failing.
  *
  * Nothing here runs during SSR: browser APIs are only touched from effects and event handlers.
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import {
     type DeviceLists,
     type MediaAccessError,
@@ -33,6 +41,10 @@ import {
     requestUserMedia,
 } from "./deviceMedia.js";
 import { startLevelMeter } from "./levelMeter.js";
+import { loadPicture, prepareBackgroundImage } from "./filters/backgroundImage.js";
+import { NO_FILTERS, type VideoFilters, filtersActive } from "./filters/filterTypes.js";
+import { type BackgroundPicture, type FilterStatus, VideoFilterProcessor } from "./filters/VideoFilterProcessor.js";
+import { type MediaPreferences, loadPreferences, savePreferences } from "./mediaPreferences.js";
 
 export type MediaKind = "audio" | "video";
 
@@ -47,6 +59,9 @@ const VIDEO_CONSTRAINTS: MediaTrackConstraints = { facingMode: "user", width: {
 /** The mean deviation (the level meter's 0-100 scale) that fills the whole indicator - ordinary speech sits well
  * below full scale. */
 const LEVEL_FULL_SCALE = 20;
+const FILTERS_UNSUPPORTED =
+    "Video effects aren't supported in this browser, so your camera is off. Turn the effects off to show your camera.";
+
 export const AUDIO_LEVEL_STEPS = 5;
 
 export interface LocalMedia {
@@ -70,6 +85,16 @@ export interface LocalMedia {
     selectedDeviceIds: Partial<Record<MediaKind, string>>;
     /** 0-`AUDIO_LEVEL_STEPS`: how loud the microphone is right now - always 0 while muted. */
     audioLevel: number;
+    /** The video filters in effect - `NO_FILTERS` when the camera is sent as it is. */
+    filters: VideoFilters;
+    /** Whether the filters' models are still loading, and why a filter isn't fully working. */
+    filterStatus: FilterStatus;
+    /** Whether a custom background image has been chosen (and so "custom image" can be switched to at once). */
+    hasBackgroundImage: boolean;
+    /** Changes some of the filters, keeping the rest. */
+    setFilters(patch: Partial<VideoFilters>): void;
+    /** Uses `file` as the custom background and switches to it. Resolves to why the file can't be used, or `null`. */
+    chooseBackgroundImage(file: File): Promise<string | null>;
     /** Asks for the camera and microphone (or just `kind`), see this module's doc comment. */
     requestAccess(kind?: MediaKind): Promise<void>;
     toggleMic(): Promise<void>;
@@ -90,7 +115,17 @@ function statusFor(error: MediaAccessError): TrackStatus {
     }
 }
 
-export function useLocalMedia(): LocalMedia {
+export interface LocalMediaOptions {
+    /** Where the filters' models are hosted, when not on the default CDN - see `filters/mlModels.ts`. */
+    effectsAssetsUrl?: string;
+}
+
+/** `base`, asking for `preferredId` (the device used last time) when there is one - as a preference, not a demand. */
+function preferring(base: MediaTrackConstraints, preferredId?: string): MediaTrackConstraints {
+    return preferredId ? { ...base, deviceId: { ideal: preferredId } } : base;
+}
+
+export function useLocalMedia({ effectsAssetsUrl }: LocalMediaOptions = {}): LocalMedia {
     const [supported, setSupported] = useState(true);
     const [requesting, setRequesting] = useState(false);
     const [error, setError] = useState<MediaAccessError | null>(null);
@@ -99,10 +134,66 @@ export function useLocalMedia(): LocalMedia {
     const [micEnabled, setMicEnabled] = useState(true);
     const [devices, setDevices] = useState<DeviceLists>({ cameras: [], microphones: [] });
     const [audioLevel, setAudioLevel] = useState(0);
+    const [filters, setFiltersState] = useState<VideoFilters>(NO_FILTERS);
+    const [background, setBackground] = useState<BackgroundPicture | null>(null);
+    const [filterStatus, setFilterStatus] = useState<FilterStatus>({ loading: false, error: null });
+    const [processed, setProcessed] = useState<MediaStreamTrack | null>(null);
 
     const tracksRef = useRef<Record<MediaKind, MediaStreamTrack | null>>({ audio: null, video: null });
     const micEnabledRef = useRef(true);
     const mountedRef = useRef(true);
+    const prefsRef = useRef<MediaPreferences | null>(null);
+    const filtersRef = useRef<VideoFilters>(NO_FILTERS);
+    const backgroundRef = useRef<BackgroundPicture | null>(null);
+    const processorRef = useRef<VideoFilterProcessor | null>(null);
+
+    const applyFilters = useCallback((next: VideoFilters) => {
+        filtersRef.current = next;
+        setFiltersState(next);
+    }, []);
+
+    const applyBackground = useCallback((picture: BackgroundPicture) => {
+        backgroundRef.current = picture;
+        setBackground(picture);
+    }, []);
+
+    /** What was remembered from last time - read once, the first time anything needs it, and applied to the state it
+     * covers. Never during render: storage doesn't exist on the server, and reading it would make the first client
+     * render differ from the server's. */
+    const ensurePrefs = useCallback((): MediaPreferences => {
+        if (prefsRef.current) {
+            return prefsRef.current;
+        }
+        const prefs = loadPreferences();
+        prefsRef.current = prefs;
+        if (prefs.micEnabled === false) {
+            micEnabledRef.current = false;
+            setMicEnabled(false);
+        }
+        if (prefs.filters) {
+            applyFilters(prefs.filters);
+        }
+        if (prefs.backgroundImage) {
+            loadPicture(prefs.backgroundImage).then(
+                (picture) => {
+                    if (mountedRef.current) {
+                        applyBackground(picture);
+                    }
+                },
+                () => undefined,
+            );
+        }
+        return prefs;
+    }, [applyBackground, applyFilters]);
+
+    /** Saves a change to the remembered settings. */
+    const remember = useCallback(
+        (patch: Partial<MediaPreferences>) => {
+            prefsRef.current = { ...ensurePrefs(), ...patch };
+            savePreferences(patch);
+        },
+        [ensurePrefs],
+    );
 
     const refreshDevices = useCallback(async () => {
         const list = await listDevices();
@@ -138,7 +229,10 @@ export function useLocalMedia(): LocalMedia {
         tracksRef.current = { ...tracksRef.current, [kind]: track };
         setTracks(tracksRef.current);
         setStatus((prev) => ({ ...prev, [kind]: "live" }));
-    }, []);
+        if (kind === "video") {
+            remember({ cameraEnabled: true });
+        }
+    }, [remember]);
 
     const adoptStream = useCallback(
         (stream: MediaStream) => {
@@ -149,11 +243,14 @@ export function useLocalMedia(): LocalMedia {
         [adoptTrack],
     );
 
-    /** Asks for one kind on its own - a specific device when `deviceId` is given. */
+    /** Asks for one kind on its own - a specific device when `deviceId` is given, else the one used last time. */
     const acquire = useCallback(
         async (kind: MediaKind, deviceId?: string): Promise<boolean> => {
             const base = kind === "audio" ? AUDIO_CONSTRAINTS : VIDEO_CONSTRAINTS;
-            const constraint: MediaTrackConstraints = deviceId ? { ...base, deviceId: { exact: deviceId } } : base;
+            const prefs = ensurePrefs();
+            const constraint: MediaTrackConstraints = deviceId
+                ? { ...base, deviceId: { exact: deviceId } }
+                : preferring(base, kind === "audio" ? prefs.microphoneId : prefs.cameraId);
             const result = await requestUserMedia({ [kind]: constraint });
             if (!result.ok) {
                 if (mountedRef.current) {
@@ -168,12 +265,24 @@ export function useLocalMedia(): LocalMedia {
             }
             return true;
         },
-        [adoptStream],
+        [adoptStream, ensurePrefs],
     );
 
     /** Asks for the camera and the microphone in a single prompt. */
     const acquireBoth = useCallback(async () => {
-        const both = await requestUserMedia({ audio: AUDIO_CONSTRAINTS, video: VIDEO_CONSTRAINTS });
+        const prefs = ensurePrefs();
+        if (prefs.cameraEnabled === false) {
+            // The camera was off when the participant last left: join with it off, without switching it on first.
+            if (mountedRef.current) {
+                setStatus((prev) => ({ ...prev, video: "off" }));
+            }
+            await acquire("audio");
+            return;
+        }
+        const both = await requestUserMedia({
+            audio: preferring(AUDIO_CONSTRAINTS, prefs.microphoneId),
+            video: preferring(VIDEO_CONSTRAINTS, prefs.cameraId),
+        });
         if (both.ok) {
             adoptStream(both.value);
         } else if (both.error.kind === "permission-denied") {
@@ -187,7 +296,7 @@ export function useLocalMedia(): LocalMedia {
             await acquire("audio");
             await acquire("video");
         }
-    }, [acquire, adoptStream]);
+    }, [acquire, adoptStream, ensurePrefs]);
 
     const requestAccess = useCallback(
         async (kind?: MediaKind) => {
@@ -211,6 +320,7 @@ export function useLocalMedia(): LocalMedia {
         if (!track) {
             micEnabledRef.current = true;
             setMicEnabled(true);
+            remember({ micEnabled: true });
             await acquire("audio");
             await refreshDevices();
             return;
@@ -219,7 +329,8 @@ export function useLocalMedia(): LocalMedia {
         micEnabledRef.current = next;
         track.enabled = next;
         setMicEnabled(next);
-    }, [acquire, refreshDevices]);
+        remember({ micEnabled: next });
+    }, [acquire, refreshDevices, remember]);
 
     const toggleCamera = useCallback(async () => {
         const track = tracksRef.current.video;
@@ -233,7 +344,8 @@ export function useLocalMedia(): LocalMedia {
         tracksRef.current = { ...tracksRef.current, video: null };
         setTracks(tracksRef.current);
         setStatus((prev) => ({ ...prev, video: "off" }));
-    }, [acquire, refreshDevices]);
+        remember({ cameraEnabled: false });
+    }, [acquire, refreshDevices, remember]);
 
     const selectDevice = useCallback(
         async (kind: MediaKind, deviceId: string) => {
@@ -247,10 +359,37 @@ export function useLocalMedia(): LocalMedia {
                     setTracks(tracksRef.current);
                 }
             }
-            await acquire(kind, deviceId);
+            if (await acquire(kind, deviceId)) {
+                remember(kind === "audio" ? { microphoneId: deviceId } : { cameraId: deviceId });
+            }
             await refreshDevices();
         },
-        [acquire, refreshDevices],
+        [acquire, refreshDevices, remember],
+    );
+
+    const setFilters = useCallback(
+        (patch: Partial<VideoFilters>) => {
+            const next = { ...filtersRef.current, ...patch };
+            applyFilters(next);
+            remember({ filters: next });
+        },
+        [applyFilters, remember],
+    );
+
+    const chooseBackgroundImage = useCallback(
+        async (file: File): Promise<string | null> => {
+            const prepared = await prepareBackgroundImage(file);
+            if (!prepared.ok) {
+                return prepared.message;
+            }
+            if (mountedRef.current) {
+                applyBackground(prepared.picture);
+                remember({ backgroundImage: prepared.dataUrl });
+                setFilters({ background: "image" });
+            }
+            return null;
+        },
+        [applyBackground, remember, setFilters],
     );
 
     const release = useCallback(() => {
@@ -304,7 +443,47 @@ export function useLocalMedia(): LocalMedia {
         };
     }, [tracks.audio, micEnabled]);
 
-    const videoStream = useMemo(() => (tracks.video ? new MediaStream([tracks.video]) : null), [tracks.video]);
+    // Puts the camera through the filters for as long as any is on - see this module's doc comment. A layout effect,
+    // so the filtered track is in place before the first frame is painted rather than after an unfiltered one.
+    const filtersOn = filtersActive(filters);
+    const source = tracks.video;
+    useLayoutEffect(() => {
+        if (!source || !filtersOn) {
+            return;
+        }
+        let processor: VideoFilterProcessor;
+        try {
+            processor = new VideoFilterProcessor({
+                source,
+                filters: filtersRef.current,
+                backgroundImage: backgroundRef.current,
+                assetsUrl: effectsAssetsUrl,
+                onStatus: setFilterStatus,
+            });
+        } catch {
+            setFilterStatus({ loading: false, error: FILTERS_UNSUPPORTED });
+            // Turning the filters off (or the camera) clears the message again.
+            return () => setFilterStatus({ loading: false, error: null });
+        }
+        processorRef.current = processor;
+        setProcessed(processor.track);
+        return () => {
+            processor.stop();
+            processorRef.current = null;
+            setProcessed(null);
+            setFilterStatus({ loading: false, error: null });
+        };
+    }, [source, filtersOn, effectsAssetsUrl]);
+
+    // Passes a change of filters (or of the background picture) on to the running processor.
+    useEffect(() => {
+        processorRef.current?.update(filters, background);
+    }, [filters, background]);
+
+    // While filters are on, the camera's own track is never what's sent: the filtered one is, or nothing.
+    const videoTrack = filtersOn ? (source ? processed : null) : source;
+
+    const videoStream = useMemo(() => (videoTrack ? new MediaStream([videoTrack]) : null), [videoTrack]);
 
     const selectedDeviceIds = useMemo(
         () => ({
@@ -319,7 +498,7 @@ export function useLocalMedia(): LocalMedia {
         requesting,
         error,
         audioTrack: tracks.audio,
-        videoTrack: tracks.video,
+        videoTrack,
         videoStream,
         micEnabled,
         micOn: !!tracks.audio && micEnabled,
@@ -328,6 +507,11 @@ export function useLocalMedia(): LocalMedia {
         devices,
         selectedDeviceIds,
         audioLevel,
+        filters,
+        filterStatus,
+        hasBackgroundImage: !!background,
+        setFilters,
+        chooseBackgroundImage,
         requestAccess,
         toggleMic,
         toggleCamera,

package/apps/shared/push/GuestSignalingClient.ts

@@ -4,7 +4,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 /**
  * A standalone `SignalingChannel` (`../webrtc/types.js`) over `@rapidrest/service-core`'s `/push` WebSocket -
- * built from scratch rather than reusing `@rapidmx/react-shared`'s `PushClient`/`getPushClient()`.
+ * built from scratch rather than reusing `@rapidmx/web-client`'s `PushClient`/`getPushClient()` (`lib/mail/pushClient.js`).
  *
  * ## Why not `PushClient`
  *
@@ -63,8 +63,8 @@
  * absent, as described above - the browser's real cookie was always going to win that write anyway, so the
  * correct behavior is to not fight it and let it authenticate normally instead.
  */
-import { apiOrigin } from "@rapidmx/react-shared/util/api.js";
-import { pushUrl } from "@rapidmx/react-shared/mail/pushClient.js";
+import { apiOrigin } from "@rapidmx/web-client/lib/util/api.js";
+import { pushUrl } from "@rapidmx/web-client/lib/mail/pushClient.js";
 import type { SignalMessage, SignalingChannel } from "../webrtc/types.js";
 
 /** The subset of the browser's `WebSocket` this client uses - matches `PushClient`'s own identical seam, so a
@@ -99,7 +99,7 @@ export interface GuestSignalingClientOptions {
      * `Authorization` header at all, relying entirely on the browser's own already-existing `jwt` session cookie
      * for both the WebSocket upgrade and each `POST /push/:id` publish - see this module's doc comment. */
     token?: string;
-    /** Defaults to `@rapidmx/react-shared`'s `pushUrl()` - the exact URL `PushClient` itself connects to. */
+    /** Defaults to `@rapidmx/web-client`'s `pushUrl()` (`lib/mail/pushClient.js`) - the exact URL `PushClient` itself connects to. */
     url?: () => string | undefined;
     createSocket?: PushSocketFactory;
     fetchImpl?: typeof fetch;

package/apps/shared/relay/AudioPlayer.ts

@@ -0,0 +1,111 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { TimestampUnwrapper, type Frame } from "./frames.js";
+import type { AudioContextLike, AudioDataLike, DecoderLike, RelayEnv } from "./relayEnv.js";
+import { safeClose } from "./senderCommon.js";
+
+export const PLAYBACK_SAMPLE_RATE = 48_000;
+/** How far ahead of the clock the first packet after a start or an underrun is scheduled. It is the jitter buffer:
+ * packets arriving up to this late (relative to their neighbours) still play in order without a gap. */
+export const JITTER_BUFFER_SECONDS = 0.08;
+/** If scheduled audio already runs this far past the clock the receiver has fallen behind (a burst, or the sender's
+ * clock running fast), so further packets are dropped until playback catches up - better a brief skip than latency
+ * that keeps growing. */
+export const MAX_AHEAD_SECONDS = 0.4;
+/** Skip a packet instead of queueing it when the decoder is this far behind. */
+export const AUDIO_MAX_DECODE_QUEUE = 16;
+
+/**
+ * Decodes one sender's Opus packets and schedules them for playback into a `MediaStreamAudioDestinationNode`.
+ *
+ * Each decoded block is copied into an `AudioBuffer` and started on its own `AudioBufferSourceNode` at
+ * `max(currentTime + jitter, nextTime)`, where `nextTime` is when the previous block ends - so consecutive blocks
+ * join seamlessly, and after a gap in the stream playback restarts with the jitter buffer's worth of headroom.
+ * Opus packets are independently decodable, so a lost packet costs only its own 20 ms and needs no recovery step;
+ * the decoder is created lazily and discarded on any error, and replaced by the next packet.
+ */
+export class AudioPlayer {
+    private decoder: DecoderLike | undefined;
+    private nextTime = 0;
+    private readonly timestamps = new TimestampUnwrapper();
+
+    /** `destination` is the node whose stream the peer's `MediaStream` carries. */
+    constructor(
+        private readonly env: RelayEnv,
+        private readonly ctx: AudioContextLike,
+        private readonly destination: unknown,
+    ) {}
+
+    /** Feeds one reassembled audio frame (one Opus packet). */
+    push(frame: Frame): void {
+        const decoder = this.decoder ?? this.createDecoder();
+        if (!decoder || decoder.decodeQueueSize > AUDIO_MAX_DECODE_QUEUE) {
+            return;
+        }
+        try {
+            decoder.decode(
+                this.env.createEncodedAudioChunk({ type: "key", timestamp: this.timestamps.next(frame.timestampMs) * 1000, data: frame.data }),
+            );
+        } catch {
+            this.discardDecoder();
+        }
+    }
+
+    close(): void {
+        this.discardDecoder();
+    }
+
+    private discardDecoder(): void {
+        const decoder = this.decoder;
+        this.decoder = undefined;
+        safeClose(decoder);
+    }
+
+    private createDecoder(): DecoderLike | undefined {
+        let decoder: DecoderLike | undefined;
+        try {
+            decoder = this.env.createAudioDecoder({
+                output: (data) => this.play(data),
+                error: () => {
+                    // Only the current decoder's failure matters; a stale one was already replaced.
+                    if (this.decoder === decoder) {
+                        this.discardDecoder();
+                    }
+                },
+            });
+            decoder.configure({ codec: "opus", sampleRate: PLAYBACK_SAMPLE_RATE, numberOfChannels: 1 });
+        } catch {
+            safeClose(decoder);
+            return undefined;
+        }
+        this.decoder = decoder;
+        return decoder;
+    }
+
+    /** Schedules one decoded block. Always closes `data`. */
+    private play(data: AudioDataLike): void {
+        try {
+            const now = this.ctx.currentTime;
+            if (this.nextTime - now > MAX_AHEAD_SECONDS) {
+                return;
+            }
+            const buffer = this.ctx.createBuffer(1, data.numberOfFrames, data.sampleRate);
+            const pcm = new Float32Array(data.numberOfFrames);
+            data.copyTo(pcm, { planeIndex: 0, format: "f32-planar" });
+            buffer.copyToChannel(pcm, 0);
+            const source = this.ctx.createBufferSource();
+            source.buffer = buffer;
+            source.connect(this.destination);
+            source.onended = () => source.disconnect();
+            const start = Math.max(now + JITTER_BUFFER_SECONDS, this.nextTime);
+            source.start(start);
+            this.nextTime = start + buffer.duration;
+        } catch {
+            // A block the browser will not take (an odd sample rate, a closed context) is dropped like a lost packet.
+        } finally {
+            data.close();
+        }
+    }
+}