@rapidmx/meet-plugin 0.5.0 → 0.8.0

package/apps/shared/relay/RelayClient.ts

@@ -0,0 +1,262 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The WebSocket to the server's media relay - the transport under the last-resort tier of a call, used for a pair of
+ * participants whose WebRTC connection could not be made to work at all.
+ *
+ * ## Wire protocol (fixed by the server)
+ *
+ * - The first message is text JSON `{"op":"hello","v":1,"peer":"<peerId>"}`; the server answers `{"op":"ready","v":1}`,
+ * plus `"maxMessageBytes"` - the largest client-to-server message it accepts - on a current server (absent on an
+ * older one, which accepts `MAX_MESSAGE_BYTES`). Nothing else may be sent before `ready`.
+ * - `{"op":"want","peers":[...]}` REPLACES the set of senders this socket receives from (the server accepts at most
+ * `MAX_WANTED_PEERS`). It has to be re-sent after every reconnect, because the server's set dies with the socket.
+ * - A binary message from the client is an opaque payload of at most `maxMessageBytes`. The server forwards it to
+ * every socket that wants this sender as `[1 byte N][N bytes UTF-8 sender peer id][payload]`, stamping the sender
+ * itself so a peer cannot speak as another.
+ * - Binary messages may be dropped under backpressure and the socket may close at any moment, so this client
+ * reconnects with exponential backoff and treats every media send as best effort.
+ *
+ * Authentication is the `jwt` cookie already in place (see `GuestSignalingClient`), so this client sets no cookie.
+ */
+import { DEFAULT_MESSAGE_BYTES } from "./frames.js";
+import type { RelaySocket } from "./relayEnv.js";
+
+/** The largest binary message an older server accepts - it closes the socket on a larger one (uWS's default limit).
+ * Assumed until the server's `ready` announces a different `maxMessageBytes`. */
+export const MAX_MESSAGE_BYTES = DEFAULT_MESSAGE_BYTES;
+/** A `maxMessageBytes` below this is not believed (nothing useful fits), and one above
+ * `MAX_NEGOTIATED_MESSAGE_BYTES` is clamped to it. */
+export const MIN_NEGOTIATED_MESSAGE_BYTES = 1024;
+export const MAX_NEGOTIATED_MESSAGE_BYTES = 1024 * 1024;
+/** The most senders the server lets one socket `want`. */
+export const MAX_WANTED_PEERS = 32;
+/** A media send is dropped, not queued, while more than this many bytes are still waiting to leave - the
+ * connection is slower than the media, and queueing would only add latency to the frames that are still fresh. */
+export const MAX_BUFFERED_BYTES = 256 * 1024;
+/** Reconnect delay: about a second after the first failure, doubling to a ceiling, jittered so a server restart
+ * doesn't bring every client back in the same instant. */
+export const RELAY_BACKOFF_BASE_MS = 1_000;
+export const RELAY_BACKOFF_MAX_MS = 15_000;
+/** How long a socket may take to become `ready` before it is abandoned and retried (a server that accepts the
+ * upgrade but never answers the hello would otherwise hang the tier forever). */
+export const RELAY_HANDSHAKE_TIMEOUT_MS = 10_000;
+
+const SOCKET_OPEN = 1;
+
+export interface RelayClientOptions {
+    url: string;
+    peerId: string;
+    createSocket: (url: string) => RelaySocket;
+    random: () => number;
+    /** Called with the sender's peer id (as stamped by the server) and the original payload. */
+    onMedia: (peerId: string, payload: Uint8Array) => void;
+}
+
+/** Views `data` as bytes when it is binary (an `ArrayBuffer` or a typed array), else `undefined`. Uses
+ * `Object.prototype.toString` rather than `instanceof` so it works for a buffer from another realm too. */
+function toBytes(data: unknown): Uint8Array | undefined {
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    if (Object.prototype.toString.call(data) === "[object ArrayBuffer]") {
+        return new Uint8Array(data as ArrayBuffer);
+    }
+    return undefined;
+}
+
+export class RelayClient {
+    private socket: RelaySocket | undefined;
+    private closed = false;
+    private started = false;
+    private isReady = false;
+    private messageLimit = MAX_MESSAGE_BYTES;
+    private attempt = 0;
+    private wanted: string[] = [];
+    private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+    private handshakeTimer: ReturnType<typeof setTimeout> | undefined;
+    private readonly decoder = new TextDecoder();
+
+    constructor(private readonly options: RelayClientOptions) {}
+
+    /** True once the server has answered the hello on the current socket, i.e. media may be sent. */
+    get ready(): boolean {
+        return this.isReady;
+    }
+
+    /** The largest message `sendMedia()` will send: what the server announced in `ready` (validated and clamped), or
+     * `MAX_MESSAGE_BYTES` before that, without one, and again after every disconnect until the next `ready`. The
+     * frame fragmenter sizes its fragments from this. */
+    get maxMessageBytes(): number {
+        return this.messageLimit;
+    }
+
+    /** Opens the socket (and keeps it open, reconnecting as needed) until `close()`. Idempotent. */
+    start(): void {
+        if (this.started || this.closed) {
+            return;
+        }
+        this.started = true;
+        this.openSocket();
+    }
+
+    /** Replaces the set of senders to receive from. Sent now if the socket is ready, and again after each reconnect. */
+    setWanted(peers: Iterable<string>): void {
+        this.wanted = [...peers].slice(0, MAX_WANTED_PEERS);
+        if (this.isReady) {
+            this.sendText({ op: "want", peers: this.wanted });
+        }
+    }
+
+    /** Sends one media message. Returns whether it was handed to the socket - `false` (dropped) when the socket is
+     * not ready, is backed up, or the message is too large for the server to accept. */
+    sendMedia(bytes: Uint8Array): boolean {
+        const socket = this.socket;
+        if (
+            !socket ||
+            !this.isReady ||
+            socket.readyState !== SOCKET_OPEN ||
+            socket.bufferedAmount > MAX_BUFFERED_BYTES ||
+            bytes.length > this.messageLimit
+        ) {
+            return false;
+        }
+        try {
+            socket.send(bytes);
+            return true;
+        } catch {
+            // The close that follows a dead socket reconnects.
+            return false;
+        }
+    }
+
+    /** Closes the socket and stops reconnecting for good. Idempotent. */
+    close(): void {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.isReady = false;
+        this.messageLimit = MAX_MESSAGE_BYTES;
+        clearTimeout(this.reconnectTimer);
+        clearTimeout(this.handshakeTimer);
+        this.reconnectTimer = this.handshakeTimer = undefined;
+        this.detach();
+    }
+
+    private openSocket(): void {
+        let socket: RelaySocket;
+        try {
+            socket = this.options.createSocket(this.options.url);
+        } catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        socket.binaryType = "arraybuffer";
+        socket.onopen = () => this.sendText({ op: "hello", v: 1, peer: this.options.peerId });
+        socket.onmessage = (event) => this.handleMessage(socket, event.data);
+        socket.onclose = () => this.handleClose(socket);
+        socket.onerror = () => undefined;
+        this.handshakeTimer = setTimeout(() => {
+            this.handshakeTimer = undefined;
+            // Give up on this attempt as if the socket had closed; the close event of a socket we abandon is ignored.
+            this.handleClose(socket);
+        }, RELAY_HANDSHAKE_TIMEOUT_MS);
+    }
+
+    private handleMessage(socket: RelaySocket, data: unknown): void {
+        if (socket !== this.socket) {
+            return;
+        }
+        if (typeof data === "string") {
+            this.handleText(data);
+            return;
+        }
+        const bytes = toBytes(data);
+        if (!bytes || !this.isReady) {
+            return;
+        }
+        const idLength = bytes.length > 0 ? bytes[0] : 0;
+        if (idLength === 0 || bytes.length < 1 + idLength) {
+            return;
+        }
+        // A malformed id decodes to replacement characters, which match no receiver, so it needs no separate check.
+        const peerId = this.decoder.decode(bytes.subarray(1, 1 + idLength));
+        this.options.onMedia(peerId, bytes.subarray(1 + idLength));
+    }
+
+    private handleText(text: string): void {
+        let message: unknown;
+        try {
+            message = JSON.parse(text);
+        } catch {
+            return;
+        }
+        if (!message || typeof message !== "object" || (message as { op?: unknown }).op !== "ready" || this.isReady) {
+            return;
+        }
+        this.isReady = true;
+        this.attempt = 0;
+        const announced = (message as { maxMessageBytes?: unknown }).maxMessageBytes;
+        if (typeof announced === "number" && Number.isInteger(announced) && announced >= MIN_NEGOTIATED_MESSAGE_BYTES) {
+            this.messageLimit = Math.min(announced, MAX_NEGOTIATED_MESSAGE_BYTES);
+        }
+        clearTimeout(this.handshakeTimer);
+        this.handshakeTimer = undefined;
+        // The server's wanted set is per socket, so it starts empty on every (re)connect.
+        this.sendText({ op: "want", peers: this.wanted });
+    }
+
+    private handleClose(socket: RelaySocket): void {
+        if (socket !== this.socket) {
+            return;
+        }
+        this.isReady = false;
+        // The next server might be a different one (a rolling upgrade), so the limit is learned afresh.
+        this.messageLimit = MAX_MESSAGE_BYTES;
+        clearTimeout(this.handshakeTimer);
+        this.handshakeTimer = undefined;
+        this.detach();
+        this.scheduleReconnect();
+    }
+
+    /** Detaches and closes the current socket, if any, so its late events can't reach this client. */
+    private detach(): void {
+        const socket = this.socket;
+        this.socket = undefined;
+        if (!socket) {
+            return;
+        }
+        socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+        try {
+            socket.close(1000, "closing");
+        } catch {
+            // Already gone.
+        }
+    }
+
+    private scheduleReconnect(): void {
+        const ceiling = Math.min(RELAY_BACKOFF_MAX_MS, RELAY_BACKOFF_BASE_MS * 2 ** Math.min(this.attempt, 10));
+        const delay = ceiling / 2 + (this.options.random() * ceiling) / 2;
+        this.attempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            this.openSocket();
+        }, delay);
+    }
+
+    private sendText(message: object): void {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== SOCKET_OPEN) {
+            return;
+        }
+        try {
+            socket.send(JSON.stringify(message));
+        } catch {
+            // The close that follows a dead socket reconnects and re-sends.
+        }
+    }
+}

package/apps/shared/relay/RelayReceiver.ts

@@ -0,0 +1,72 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { AudioPlayer } from "./AudioPlayer.js";
+import { decodeFragment, FrameReassembler, KIND_AUDIO } from "./frames.js";
+import type { AudioContextLike, RelayEnv } from "./relayEnv.js";
+import { VideoPlayer } from "./VideoPlayer.js";
+
+/** The canvas is sized to the first decoded picture; until then it is this size. */
+const INITIAL_CANVAS_WIDTH = 320;
+const INITIAL_CANVAS_HEIGHT = 240;
+/** The frame rate `captureStream()` samples the canvas at, matching what the sender produces. */
+const CAPTURE_FPS = 15;
+
+/**
+ * One remote participant as seen through the relay: reassembles their fragments, decodes them, and exposes the result
+ * as an ordinary `MediaStream` (`stream`) so the UI plays a relayed peer exactly like a WebRTC one.
+ *
+ * The stream exists, with both tracks, from construction - silent and blank until media arrives - so the caller can
+ * attach it to an element straight away and never has to swap a stream in later. Audio goes through a
+ * `MediaStreamAudioDestinationNode` on the shared playback context; video is drawn to a canvas and captured.
+ */
+export class RelayReceiver {
+    readonly stream: MediaStream;
+    private readonly audioFrames = new FrameReassembler();
+    private readonly videoFrames = new FrameReassembler();
+    private readonly audio: AudioPlayer;
+    private readonly video: VideoPlayer | undefined;
+
+    constructor(
+        env: RelayEnv,
+        playbackContext: AudioContextLike,
+    ) {
+        const destination = playbackContext.createMediaStreamDestination();
+        this.audio = new AudioPlayer(env, playbackContext, destination);
+
+        const canvas = env.createCanvas();
+        canvas.width = INITIAL_CANVAS_WIDTH;
+        canvas.height = INITIAL_CANVAS_HEIGHT;
+        const context = canvas.getContext("2d");
+        this.video = context ? new VideoPlayer(env, canvas, context) : undefined;
+
+        this.stream = env.createMediaStream([...destination.stream.getAudioTracks(), ...canvas.captureStream(CAPTURE_FPS).getVideoTracks()]);
+    }
+
+    /** Handles one relayed payload from this sender (a media fragment). Anything malformed is ignored. */
+    handleMedia(payload: Uint8Array): void {
+        const fragment = decodeFragment(payload);
+        if (!fragment) {
+            return;
+        }
+        const frame = (fragment.kind === KIND_AUDIO ? this.audioFrames : this.videoFrames).push(fragment);
+        if (!frame) {
+            return;
+        }
+        if (frame.kind === KIND_AUDIO) {
+            this.audio.push(frame);
+        } else {
+            this.video?.push(frame);
+        }
+    }
+
+    /** Releases the decoders and ends the stream's tracks. */
+    close(): void {
+        this.audio.close();
+        this.video?.close();
+        for (const track of this.stream.getTracks()) {
+            track.stop();
+        }
+    }
+}

package/apps/shared/relay/RelaySender.ts

@@ -0,0 +1,74 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { AudioSender } from "./AudioSender.js";
+import { DEFAULT_MESSAGE_BYTES, fragmentFrame, type FrameKind, KIND_AUDIO, KIND_VIDEO } from "./frames.js";
+import type { RelayEnv } from "./relayEnv.js";
+import type { PublishFrame } from "./senderCommon.js";
+import { VideoSender } from "./VideoSender.js";
+
+const SEQ_MODULUS = 0x10000;
+
+/** Numbers and fragments the frames of one sender. The counters belong to the transport rather than to a capture
+ * session, so stopping and restarting sending never resets `seq` - a receiver still holding the old value would
+ * otherwise treat the restarted stream as older than what it has already seen. */
+export class FramePublisher {
+    private readonly seqs: Record<FrameKind, number> = { [KIND_AUDIO]: 0, [KIND_VIDEO]: 0 };
+
+    /** `send` returns whether one message was accepted by the socket. */
+    /** `maxMessageBytes` is the largest message the socket may send right now (it changes when the server's `ready`
+     * announces a limit), so it is read for every frame rather than fixed at construction. */
+    constructor(
+        private readonly send: (message: Uint8Array) => boolean,
+        private readonly maxMessageBytes: () => number = () => DEFAULT_MESSAGE_BYTES,
+    ) {}
+
+    /** Fragments and sends one frame, stopping at the first fragment the socket refuses (the rest could not be
+     * used without it). Returns whether the whole frame went out. */
+    publish: PublishFrame = (kind, keyFrame, data, timestampMs) => {
+        const seq = this.seqs[kind];
+        this.seqs[kind] = (seq + 1) % SEQ_MODULUS;
+        const fragments = fragmentFrame(kind, keyFrame, seq, timestampMs, data, this.maxMessageBytes());
+        if (fragments.length === 0) {
+            return false;
+        }
+        for (const fragment of fragments) {
+            if (!this.send(fragment)) {
+                return false;
+            }
+        }
+        return true;
+    };
+}
+
+export interface RelaySenderOptions {
+    env: RelayEnv;
+    send: (message: Uint8Array) => boolean;
+    canSend: () => boolean;
+    /** The socket's current message limit; defaults to what an older server accepts. */
+    maxMessageBytes?: () => number;
+}
+
+/** The publishing half of the relay: the two capture paths plus the frame numbering they share. */
+export class RelaySender {
+    private readonly audio: AudioSender;
+    private readonly video: VideoSender;
+
+    constructor(options: RelaySenderOptions) {
+        const deps = { env: options.env, publish: new FramePublisher(options.send, options.maxMessageBytes).publish, canSend: options.canSend };
+        this.audio = new AudioSender(deps);
+        this.video = new VideoSender(deps);
+    }
+
+    /** Starts or stops encoding whatever tracks are set. Stopping releases the encoders and audio nodes. */
+    setActive(active: boolean): void {
+        this.audio.setActive(active);
+        this.video.setActive(active);
+    }
+
+    /** `null` sends nothing for that kind. Safe before or after `setActive`. */
+    setTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void {
+        (kind === "audio" ? this.audio : this.video).setTrack(track);
+    }
+}

package/apps/shared/relay/RelayTransport.ts

@@ -0,0 +1,188 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The last-resort media tier of a call: when two participants' WebRTC connection cannot be made at all (typically a
+ * network that blocks UDP and TURN alike), their audio and video travel over a WebSocket to the server, which fans
+ * each participant's frames out to whoever asked for them. This module is the facade the mesh manager talks to; the
+ * pieces behind it are:
+ *
+ * - `RelayClient` - the socket: hello/ready/want, reconnection, dropping media it cannot send promptly.
+ * - `frames` - the fragment format inside each WebSocket message and the reassembly of it.
+ * - `RelaySender` (`AudioSender`, `VideoSender`) - capture and encode the local tracks (Opus and VP8 via WebCodecs).
+ * - `RelayReceiver` (`AudioPlayer`, `VideoPlayer`) - decode a remote participant back into a `MediaStream`.
+ *
+ * There is one transport (one socket) per meeting, however many peers use it, and the codecs are fixed - there is no
+ * negotiation, because both ends are this same code.
+ */
+import { apiOrigin } from "@rapidmx/react-shared/util/api.js";
+import { PLAYBACK_SAMPLE_RATE } from "./AudioPlayer.js";
+import { resumeAudioContext } from "./audioResume.js";
+import { RelayClient } from "./RelayClient.js";
+import { detectRelayEnv, type AudioContextLike, type RelayEnv } from "./relayEnv.js";
+import { RelayReceiver } from "./RelayReceiver.js";
+import { RelaySender } from "./RelaySender.js";
+
+export interface RelayTransport {
+    /** false when this browser lacks WebSocket, AudioEncoder/AudioDecoder/VideoEncoder/VideoDecoder, VideoFrame,
+     * AudioContext or canvas.captureStream - the mesh then never falls back to the relay. */
+    readonly supported: boolean;
+    /** Start receiving `peerId`'s media (opens/keeps the socket, adds to `want`). `onStream` gets a MediaStream that
+     * plays that peer (one audio + one video track). Called at most once per stream creation; calling receiveFrom
+     * again for the same peer is a no-op. */
+    receiveFrom(peerId: string, onStream: (stream: MediaStream) => void): void;
+    stopReceivingFrom(peerId: string): void;
+    /** Start/stop publishing the local tracks (encode + send). Only encodes while active; stopping releases the
+     * encoders and audio nodes. */
+    setSending(active: boolean): void;
+    /** Same semantics as `MeshConnectionManager.setLocalTrack`: null = send nothing for that kind. Safe to call
+     * before or after `setSending`. */
+    setLocalTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void;
+    /** Closes the socket, all coders, streams and timers. Idempotent. */
+    close(): void;
+}
+
+export interface RelayTransportOptions {
+    meetingUid: string;
+    /** This participant's peer id on the meeting's signaling channel - the id the server stamps on what it sends. */
+    peerId: string;
+    /** Overrides the socket URL (default: `relayUrl(meetingUid)`). */
+    url?: string;
+    /** Overrides every browser API the relay uses (default: `detectRelayEnv()`), so a test can drive it with fakes. */
+    env?: RelayEnv;
+}
+
+/** The relay WebSocket's URL for a meeting: this deployment's origin (the API origin when the UI is served from a
+ * different one, else the page's own), `http` becoming `ws` - the same derivation `pushUrl()` uses for `/push`.
+ * `undefined` when there is no origin at all (not running in a browser). */
+export function relayUrl(meetingUid: string): string | undefined {
+    const origin = apiOrigin() || (typeof window !== "undefined" ? window.location.origin : "");
+    return origin ? `${origin.replace(/^http/i, "ws")}/api/mail/video-meetings/relay/${encodeURIComponent(meetingUid)}` : undefined;
+}
+
+/** What `createRelayTransport()` returns on a browser that cannot run the relay: every call is a no-op. */
+const UNSUPPORTED_TRANSPORT: RelayTransport = {
+    supported: false,
+    receiveFrom: () => undefined,
+    stopReceivingFrom: () => undefined,
+    setSending: () => undefined,
+    setLocalTrack: () => undefined,
+    close: () => undefined,
+};
+
+class WebSocketRelayTransport implements RelayTransport {
+    readonly supported = true;
+    private readonly client: RelayClient;
+    private readonly sender: RelaySender;
+    private readonly receivers = new Map<string, RelayReceiver>();
+    private playback: AudioContextLike | undefined;
+    private stopResume: (() => void) | undefined;
+    private closed = false;
+
+    constructor(
+        private readonly env: RelayEnv,
+        url: string,
+        peerId: string,
+    ) {
+        this.client = new RelayClient({
+            url,
+            peerId,
+            createSocket: (target) => env.createSocket(target),
+            random: () => env.random(),
+            onMedia: (sender, payload) => this.receivers.get(sender)?.handleMedia(payload),
+        });
+        this.sender = new RelaySender({
+            env,
+            send: (message) => this.client.sendMedia(message),
+            canSend: () => this.client.ready,
+            maxMessageBytes: () => this.client.maxMessageBytes,
+        });
+    }
+
+    receiveFrom(peerId: string, onStream: (stream: MediaStream) => void): void {
+        if (this.closed || this.receivers.has(peerId)) {
+            return;
+        }
+        const receiver = this.createReceiver();
+        if (!receiver) {
+            return;
+        }
+        this.receivers.set(peerId, receiver);
+        this.client.start();
+        this.client.setWanted(this.receivers.keys());
+        onStream(receiver.stream);
+    }
+
+    stopReceivingFrom(peerId: string): void {
+        const receiver = this.receivers.get(peerId);
+        if (!receiver) {
+            return;
+        }
+        this.receivers.delete(peerId);
+        receiver.close();
+        this.client.setWanted(this.receivers.keys());
+    }
+
+    setSending(active: boolean): void {
+        if (this.closed) {
+            return;
+        }
+        if (active) {
+            this.client.start();
+        }
+        this.sender.setActive(active);
+    }
+
+    setLocalTrack(kind: "audio" | "video", track: MediaStreamTrack | null): void {
+        if (!this.closed) {
+            this.sender.setTrack(kind, track);
+        }
+    }
+
+    close(): void {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.sender.setActive(false);
+        for (const receiver of this.receivers.values()) {
+            receiver.close();
+        }
+        this.receivers.clear();
+        this.client.close();
+        this.stopResume?.();
+        // `close()` rejects for a context that is already closed; nothing to do about it.
+        this.playback?.close().catch(() => undefined);
+        this.playback = undefined;
+    }
+
+    /** A receiver on the shared playback context, or `undefined` if this browser will not build one (the peer then
+     * simply has no relayed media). */
+    private createReceiver(): RelayReceiver | undefined {
+        try {
+            if (!this.playback) {
+                this.playback = this.env.createAudioContext(PLAYBACK_SAMPLE_RATE);
+                // Nothing the user just did created this context, so it may start suspended - see `resumeAudioContext`.
+                this.stopResume = resumeAudioContext(this.playback, this.env.document);
+            }
+            return new RelayReceiver(this.env, this.playback);
+        } catch {
+            return undefined;
+        }
+    }
+}
+
+/**
+ * Creates the relay transport for one meeting. Returns an inert transport (`supported: false`) when the browser lacks
+ * something the relay needs, so the caller can simply check `supported` once and never fall back to it.
+ * No socket is opened until the first `receiveFrom()` or `setSending(true)`.
+ */
+export function createRelayTransport(options: RelayTransportOptions): RelayTransport {
+    const env = options.env ?? detectRelayEnv();
+    const url = options.url ?? relayUrl(options.meetingUid);
+    if (!env || !url) {
+        return UNSUPPORTED_TRANSPORT;
+    }
+    return new WebSocketRelayTransport(env, url, options.peerId);
+}