@tribe-nest/media-client 0.1.0

package/build/room/room.d.ts

@@ -0,0 +1,219 @@
+import type { MediaGrants } from "@tribe-nest/media-protocol";
+import { type DisconnectCause, type MediaCoreCredentials, type MediaWebSocketFactory, type ReconnectOptions, type RoomState, type SignalLogLevel } from "../core";
+import type { MediaDeviceFactory, MediaProducerHandle } from "./device";
+/**
+ * The room: a live call, as an application sees it.
+ *
+ * ## The ordering rules, which are the whole content of this file
+ *
+ * Four of them, each with a failure that is invisible until somebody is on a
+ * call:
+ *
+ * 1. **The device loads before anything else.** `consume` on the node needs our
+ *    `rtpCapabilities`, and those do not exist until the device has been loaded
+ *    with the router's. Getting this wrong produces a `consume` that is refused
+ *    for a reason that reads like a codec problem.
+ * 2. **A transport is created lazily and ONCE per direction.** Creating one
+ *    eagerly costs an ICE gather for a participant who may only ever watch.
+ *    Creating two costs a second DTLS handshake and splits the media across
+ *    transports for no reason.
+ * 3. **A consumer is resumed only after its track is attached.** The node
+ *    creates every consumer paused, deliberately: media arriving before there
+ *    is anywhere to put it is dropped, and for video that means waiting for the
+ *    next keyframe to see anything. So the resume belongs after the application
+ *    has the track, not at consume time.
+ * 4. **`autoSubscribe` follows the ACTIVE SET, not the producer list.** The
+ *    node refuses a consume outside it, so a client that subscribed to
+ *    everything would generate a refusal per producer in any room over the
+ *    threshold and show nothing for its trouble.
+ *
+ * ## Coming back is part of the room, not part of the application
+ *
+ * A socket that dies mid-call leaves the room in `reconnecting`, and a state
+ * called "reconnecting" that nothing reconnects is worse than one called
+ * "closed": the screen above it draws a spinner and promises a recovery no code
+ * is performing, so the person waits instead of reloading. So the room itself
+ * drives `core/reconnect.ts`'s policy - fresh credentials through `MEDIA_URL`
+ * every attempt, the node's own drain window honoured, a closed room never
+ * rejoined - and publishes whether an attempt is actually booked
+ * (`isRecovering`) so a UI can tell "wait" from "press something".
+ *
+ * ## What this deliberately does not do
+ *
+ * Decide whether it is allowed to see somebody. `grants` are carried for
+ * RENDERING - so a UI does not offer a control the node is about to refuse -
+ * and the node enforces independently. A client copy of an authorization
+ * decision is a UI hint; treating it as the decision is how a barrier ends up
+ * enforced in the one place an attacker controls.
+ */
+export type MediaRoomCredentials = MediaCoreCredentials;
+export type ConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
+export type MediaTrack = {
+    producerId: string;
+    identity: string;
+    kind: "audio" | "video";
+    track: MediaStreamTrack;
+    /** Paused at the SOURCE, as the publisher left it. */
+    paused: boolean;
+};
+export type LocalPublication = {
+    producerId: string;
+    kind: "audio" | "video";
+    source: string;
+    track: MediaStreamTrack;
+    handle: MediaProducerHandle;
+};
+export type MediaRoomOptions = {
+    /**
+     * Called before EVERY attempt. A join ticket expires in minutes and a call
+     * lasts an hour, so `{ url, token }` passed once is a defect rather than a
+     * naming choice: the first reconnect would present an expired token.
+     */
+    getCredentials: () => Promise<MediaRoomCredentials> | MediaRoomCredentials;
+    /** Follow the node's active set automatically. On by default: a client that
+     * does not follow it shows black tiles in any room over the threshold. */
+    autoSubscribe?: boolean;
+    /**
+     * Required, and supplied by the entry point rather than defaulted here.
+     *
+     * `room.ts` importing the browser device - even lazily - would make this file
+     * un-loadable outside a browser and drag `mediasoup-client` into any bundle
+     * that wanted the room TYPES. The root barrel is the browser entry and is
+     * where `createBrowserDevice` is wired in.
+     */
+    device: MediaDeviceFactory;
+    webSocket?: MediaWebSocketFactory;
+    /**
+     * How hard to try to get back in after a drop. Defaults to
+     * `DEFAULT_RECONNECT_OPTIONS`; `{ maxAttempts: 0 }` turns automatic recovery
+     * off, which leaves `isRecovering` false and is what tells a UI to offer a
+     * control instead of a spinner.
+     */
+    reconnect?: Partial<ReconnectOptions>;
+    onLog?: (level: SignalLogLevel, message: string, detail?: unknown) => void;
+};
+type Listener = () => void;
+export declare class MediaRoom {
+    private readonly options;
+    private readonly signal;
+    private readonly device;
+    private sendTransport;
+    private recvTransport;
+    private iceServers;
+    private grantsValue;
+    private readonly consumers;
+    private readonly tracksByProducer;
+    private readonly publications;
+    private readonly listeners;
+    /** One in-flight subscribe per producer, so a burst of activeSpeakers frames
+     * does not race itself into two consumers for one producer. */
+    private readonly subscribing;
+    private stateValue;
+    private connection;
+    private lastError;
+    /** Consecutive failed attempts since the last successful join. */
+    private reconnectAttempt;
+    private reconnectTimer;
+    private recovering;
+    /** `close()` has been called. Nothing may open a socket after that. */
+    private disposed;
+    constructor(options: MediaRoomOptions);
+    get state(): RoomState;
+    get connectionState(): ConnectionState;
+    get error(): DisconnectCause | undefined;
+    /**
+     * Is another attempt booked?
+     *
+     * The difference between "wait" and "press something", and the room is the
+     * only side that knows: `connectionState` is `reconnecting` both while a
+     * retry is in flight and after the policy has given up, and a screen that
+     * cannot tell them apart spins forever over a call that is over.
+     */
+    get isRecovering(): boolean;
+    /** What the NODE says this token may do. For rendering only. */
+    get grants(): MediaGrants | undefined;
+    /**
+     * Snapshots, rebuilt only when something changed.
+     *
+     * These are read by `useSyncExternalStore`, which compares with `Object.is`.
+     * A getter that spread the map on every call would hand it a NEW array every
+     * check, so React would see a change every time and re-render for ever -
+     * "The result of getSnapshot should be cached to avoid an infinite loop".
+     *
+     * The reducer in `core/state.ts` returns the same object when nothing changed
+     * for exactly this reason; these getters have to hold the same property.
+     */
+    private trackSnapshot;
+    private publicationSnapshot;
+    get tracks(): MediaTrack[];
+    get localPublications(): LocalPublication[];
+    /** Subscribe to changes. Returns an unsubscribe. */
+    onChange(listener: Listener): () => void;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Decide whether to come back, and book the attempt. Returns whether one was.
+     *
+     * The policy is `core/reconnect.ts`'s rather than a second copy of it here:
+     * "a drained node is left alone for the window it named", "a closed room is
+     * never rejoined", "a terminal refusal is not retried" and "jitter or the
+     * whole fleet lands on one replacement node together" each have an outage
+     * behind them, and a restatement is a restatement that drifts.
+     *
+     * The attempt goes through `connect()`, which fetches CREDENTIALS afresh: a
+     * join ticket lives minutes, so the one that opened this call is already
+     * stale, and the node placement has to be resolved again anyway because the
+     * node we just lost is the one node that cannot serve us.
+     */
+    private scheduleReconnect;
+    private cancelReconnect;
+    /**
+     * Publish a track.
+     *
+     * `source` travels in `appData` and is what the node checks against
+     * `publishKinds`: a token granting audio only must not be able to publish a
+     * screen share by relabelling it, and the node is where that is decided.
+     */
+    publish(track: MediaStreamTrack, source: "camera" | "microphone" | "screen"): Promise<LocalPublication>;
+    unpublish(producerId: string): Promise<void>;
+    setPaused(producerId: string, paused: boolean): Promise<void>;
+    /**
+     * Bring subscriptions in line with what the node says we should be receiving.
+     *
+     * RULE 4. The target is the ACTIVE SET, not the producer list: the node
+     * refuses anything outside it, so subscribing to every producer in a large
+     * room produces one refusal per producer and nothing to show.
+     *
+     * Below the threshold the node reports every producer as active, so the two
+     * are the same thing and this needs no special case.
+     */
+    syncSubscriptions(): Promise<void>;
+    subscribe(producerId: string): Promise<void>;
+    private doSubscribe;
+    /** RULE 2: lazily, and once. */
+    private ensureSendTransport;
+    private ensureRecvTransport;
+    private onFrame;
+    /**
+     * Everything the connection was carrying, released.
+     *
+     * The local CAPTURES go with it, and that is the part worth stating. A
+     * publication whose transport has closed sends nothing, but the
+     * `getUserMedia` track behind it is still capturing: the recording indicator
+     * stays lit on the machine and the controls above still read "Mute", claiming
+     * a microphone is publishing into a room that has ended. Leaving them running
+     * is retained personal capture after the session it was consented to was
+     * terminated by the other party, so the room stops them wherever the
+     * connection goes - a leave, a drop, a drain, or the host closing the room -
+     * rather than only on the one path a person happens to take deliberately.
+     *
+     * The node is not told: this runs when the socket is already gone, and the
+     * node tears the session down on close anyway. Ending one publication on a
+     * LIVE connection is `unpublish`, which does tell it.
+     */
+    private teardownMedia;
+    private emit;
+}
+export declare function connectToRoom(options: MediaRoomOptions): Promise<MediaRoom>;
+export {};
+//# sourceMappingURL=room.d.ts.map

package/build/room/room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../../src/room/room.ts"],"names":[],"mappings":"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"}

package/build/room/room.js

@@ -0,0 +1,438 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaRoom = void 0;
+exports.connectToRoom = connectToRoom;
+const core_1 = require("../core");
+class MediaRoom {
+    options;
+    signal;
+    device;
+    sendTransport;
+    recvTransport;
+    iceServers = [];
+    grantsValue;
+    consumers = new Map();
+    tracksByProducer = new Map();
+    publications = new Map();
+    listeners = new Set();
+    /** One in-flight subscribe per producer, so a burst of activeSpeakers frames
+     * does not race itself into two consumers for one producer. */
+    subscribing = new Map();
+    stateValue = core_1.initialRoomState;
+    connection = "idle";
+    lastError;
+    /** Consecutive failed attempts since the last successful join. */
+    reconnectAttempt = 0;
+    reconnectTimer;
+    recovering = false;
+    /** `close()` has been called. Nothing may open a socket after that. */
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+        this.device = options.device();
+        this.signal = new core_1.MediaSignal({
+            getCredentials: options.getCredentials,
+            ...(options.webSocket ? { webSocket: options.webSocket } : {}),
+            ...(options.onLog ? { onLog: options.onLog } : {}),
+        });
+        this.signal.onAny((frame) => this.onFrame(frame));
+        this.signal.onClose((cause) => {
+            this.lastError = cause;
+            // Before the decision, and unconditionally. The transports are dead
+            // whatever happens next, and so is every capture that was feeding them.
+            this.teardownMedia();
+            if (cause.type === "closed_by_client") {
+                this.connection = "closed";
+                this.recovering = false;
+                this.emit();
+                return;
+            }
+            this.connection = "reconnecting";
+            this.recovering = this.scheduleReconnect(cause);
+            this.emit();
+        });
+    }
+    get state() {
+        return this.stateValue;
+    }
+    get connectionState() {
+        return this.connection;
+    }
+    get error() {
+        return this.lastError;
+    }
+    /**
+     * Is another attempt booked?
+     *
+     * The difference between "wait" and "press something", and the room is the
+     * only side that knows: `connectionState` is `reconnecting` both while a
+     * retry is in flight and after the policy has given up, and a screen that
+     * cannot tell them apart spins forever over a call that is over.
+     */
+    get isRecovering() {
+        return this.recovering;
+    }
+    /** What the NODE says this token may do. For rendering only. */
+    get grants() {
+        return this.grantsValue;
+    }
+    /**
+     * Snapshots, rebuilt only when something changed.
+     *
+     * These are read by `useSyncExternalStore`, which compares with `Object.is`.
+     * A getter that spread the map on every call would hand it a NEW array every
+     * check, so React would see a change every time and re-render for ever -
+     * "The result of getSnapshot should be cached to avoid an infinite loop".
+     *
+     * The reducer in `core/state.ts` returns the same object when nothing changed
+     * for exactly this reason; these getters have to hold the same property.
+     */
+    trackSnapshot = [];
+    publicationSnapshot = [];
+    get tracks() {
+        return this.trackSnapshot;
+    }
+    get localPublications() {
+        return this.publicationSnapshot;
+    }
+    /** Subscribe to changes. Returns an unsubscribe. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async connect() {
+        this.cancelReconnect();
+        // A retry is not a first connection, and saying "Connecting to the call"
+        // over a call somebody is already in reads as though they had been thrown
+        // out of it.
+        this.connection = this.reconnectAttempt > 0 ? "reconnecting" : "connecting";
+        this.emit();
+        const joined = await this.signal.connect();
+        // RULE 1: the device loads first. Everything below needs its capabilities.
+        if (!this.device.loaded) {
+            await this.device.load(joined.routerRtpCapabilities);
+        }
+        this.iceServers = (joined.iceServers ?? []);
+        this.grantsValue = joined.grants;
+        this.stateValue = (0, core_1.reduceRoomState)(this.stateValue, joined);
+        this.connection = "connected";
+        this.lastError = undefined;
+        // A successful join resets the ladder: an hour-long call that drops once
+        // should not start at a 30-second delay because of a blip at minute two.
+        this.reconnectAttempt = 0;
+        this.recovering = false;
+        this.emit();
+        if (this.options.autoSubscribe !== false)
+            await this.syncSubscriptions();
+    }
+    async close() {
+        this.disposed = true;
+        this.cancelReconnect();
+        this.recovering = false;
+        this.connection = "closed";
+        await this.signal.leave().catch(() => undefined);
+        this.teardownMedia();
+        this.emit();
+    }
+    // -------------------------------------------------------------------------
+    // getting back in
+    // -------------------------------------------------------------------------
+    /**
+     * Decide whether to come back, and book the attempt. Returns whether one was.
+     *
+     * The policy is `core/reconnect.ts`'s rather than a second copy of it here:
+     * "a drained node is left alone for the window it named", "a closed room is
+     * never rejoined", "a terminal refusal is not retried" and "jitter or the
+     * whole fleet lands on one replacement node together" each have an outage
+     * behind them, and a restatement is a restatement that drifts.
+     *
+     * The attempt goes through `connect()`, which fetches CREDENTIALS afresh: a
+     * join ticket lives minutes, so the one that opened this call is already
+     * stale, and the node placement has to be resolved again anyway because the
+     * node we just lost is the one node that cannot serve us.
+     */
+    scheduleReconnect(cause) {
+        if (this.disposed)
+            return false;
+        const decision = (0, core_1.decideReconnect)({
+            cause,
+            attempt: this.reconnectAttempt,
+            ...(this.options.reconnect ? { options: this.options.reconnect } : {}),
+        });
+        if (decision.action === "stop") {
+            this.options.onLog?.("warn", `not reconnecting: ${decision.reason}`, cause);
+            return false;
+        }
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (this.disposed)
+                return;
+            this.reconnectAttempt += 1;
+            // A failed attempt comes back through `signal.onClose`, which is the only
+            // place that decides. Swallowed here so a retry does not surface as an
+            // unhandled rejection in the host application's console.
+            void this.connect().catch(() => undefined);
+        }, decision.delayMs);
+        return true;
+    }
+    cancelReconnect() {
+        if (this.reconnectTimer === undefined)
+            return;
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+    }
+    // -------------------------------------------------------------------------
+    // publishing
+    // -------------------------------------------------------------------------
+    /**
+     * Publish a track.
+     *
+     * `source` travels in `appData` and is what the node checks against
+     * `publishKinds`: a token granting audio only must not be able to publish a
+     * screen share by relabelling it, and the node is where that is decided.
+     */
+    async publish(track, source) {
+        const kind = track.kind === "audio" ? "audio" : "video";
+        if (!this.device.canProduce(kind)) {
+            throw new Error(`this browser cannot produce ${kind}`);
+        }
+        const transport = await this.ensureSendTransport();
+        const handle = await transport.produce({ track, appData: { source } });
+        const publication = {
+            producerId: handle.id,
+            kind,
+            source,
+            track,
+            handle,
+        };
+        this.publications.set(handle.id, publication);
+        this.emit();
+        return publication;
+    }
+    async unpublish(producerId) {
+        const publication = this.publications.get(producerId);
+        if (!publication)
+            return;
+        publication.handle.close();
+        publication.track.stop();
+        this.publications.delete(producerId);
+        // Told to the node, because closing a local handle stops OUR sending and
+        // leaves the node holding a producer nobody is feeding.
+        await this.signal.request({ method: "closeProducer", producerId }).catch(() => undefined);
+        this.emit();
+    }
+    async setPaused(producerId, paused) {
+        const publication = this.publications.get(producerId);
+        if (!publication)
+            return;
+        if (paused)
+            publication.handle.pause();
+        else
+            publication.handle.resume();
+        await this.signal
+            .request({ method: paused ? "pauseProducer" : "resumeProducer", producerId })
+            .catch(() => undefined);
+        this.emit();
+    }
+    // -------------------------------------------------------------------------
+    // subscribing
+    // -------------------------------------------------------------------------
+    /**
+     * Bring subscriptions in line with what the node says we should be receiving.
+     *
+     * RULE 4. The target is the ACTIVE SET, not the producer list: the node
+     * refuses anything outside it, so subscribing to every producer in a large
+     * room produces one refusal per producer and nothing to show.
+     *
+     * Below the threshold the node reports every producer as active, so the two
+     * are the same thing and this needs no special case.
+     */
+    async syncSubscriptions() {
+        const wanted = new Set(this.stateValue.activeSpeakers);
+        for (const [producerId, consumer] of this.consumers) {
+            if (wanted.has(producerId))
+                continue;
+            // Dropped rather than paused. A consumer the node has moved out of the
+            // active set is one it may refuse to keep feeding, and holding it costs
+            // the node a consumer object for a tile nobody is looking at.
+            consumer.close();
+            this.consumers.delete(producerId);
+            this.tracksByProducer.delete(producerId);
+            await this.signal.request({ method: "closeConsumer", consumerId: consumer.id }).catch(() => undefined);
+        }
+        await Promise.all([...wanted].map((producerId) => this.subscribe(producerId)));
+        this.emit();
+    }
+    async subscribe(producerId) {
+        if (this.consumers.has(producerId))
+            return;
+        const inFlight = this.subscribing.get(producerId);
+        // Two `activeSpeakers` frames in the same tick would otherwise both pass the
+        // check above and build two consumers for one producer.
+        if (inFlight)
+            return inFlight;
+        const work = this.doSubscribe(producerId).finally(() => this.subscribing.delete(producerId));
+        this.subscribing.set(producerId, work);
+        return work;
+    }
+    async doSubscribe(producerId) {
+        const entry = this.stateValue.producers.find((p) => p.producerId === producerId);
+        if (!entry)
+            return;
+        const transport = await this.ensureRecvTransport();
+        const response = (await this.signal.request({
+            method: "consume",
+            transportId: transport.id,
+            producerId,
+            rtpCapabilities: this.device.rtpCapabilities,
+        }));
+        const consumer = await transport.consume({
+            id: response.consumerId,
+            producerId: response.producerId,
+            kind: response.kind,
+            rtpParameters: response.rtpParameters,
+        });
+        this.consumers.set(producerId, consumer);
+        this.tracksByProducer.set(producerId, {
+            producerId,
+            identity: entry.identity,
+            kind: response.kind,
+            track: consumer.track,
+            paused: entry.paused,
+        });
+        // RULE 3: resume LAST. The node creates every consumer paused, so media
+        // arriving before the application has the track is dropped - and for video
+        // that means a black tile until the next keyframe.
+        await this.signal.request({ method: "resumeConsumer", consumerId: consumer.id });
+        consumer.resume();
+        this.emit();
+    }
+    // -------------------------------------------------------------------------
+    // transports
+    // -------------------------------------------------------------------------
+    /** RULE 2: lazily, and once. */
+    async ensureSendTransport() {
+        if (this.sendTransport)
+            return this.sendTransport;
+        const description = (await this.signal.request({
+            method: "createTransport",
+            direction: "send",
+        }));
+        this.sendTransport = this.device.createSendTransport({
+            description,
+            iceServers: this.iceServers,
+            handlers: {
+                onConnect: async (dtlsParameters) => {
+                    await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
+                },
+                onProduce: async ({ kind, rtpParameters, appData }) => {
+                    const produced = (await this.signal.request({
+                        method: "produce",
+                        transportId: description.transportId,
+                        kind,
+                        rtpParameters,
+                        ...(appData ? { appData } : {}),
+                    }));
+                    return produced.producerId;
+                },
+            },
+        });
+        return this.sendTransport;
+    }
+    async ensureRecvTransport() {
+        if (this.recvTransport)
+            return this.recvTransport;
+        const description = (await this.signal.request({
+            method: "createTransport",
+            direction: "recv",
+        }));
+        this.recvTransport = this.device.createRecvTransport({
+            description,
+            iceServers: this.iceServers,
+            handlers: {
+                onConnect: async (dtlsParameters) => {
+                    await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
+                },
+            },
+        });
+        return this.recvTransport;
+    }
+    // -------------------------------------------------------------------------
+    // events
+    // -------------------------------------------------------------------------
+    onFrame(frame) {
+        const next = (0, core_1.reduceRoomState)(this.stateValue, frame);
+        const changed = next !== this.stateValue;
+        this.stateValue = next;
+        if (frame.event === "joined")
+            this.grantsValue = frame.grants ?? this.grantsValue;
+        if (frame.event === "producerClosed") {
+            const consumer = this.consumers.get(frame.producerId);
+            consumer?.close();
+            this.consumers.delete(frame.producerId);
+            this.tracksByProducer.delete(frame.producerId);
+        }
+        // The node has changed what we should be receiving. Following it is the
+        // client's whole job in a large room.
+        const followsSet = frame.event === "activeSpeakers" || frame.event === "producerAppeared";
+        if (followsSet && this.options.autoSubscribe !== false && this.connection === "connected") {
+            void this.syncSubscriptions().catch((err) => this.options.onLog?.("warn", "subscription sync failed", err));
+        }
+        if (changed)
+            this.emit();
+    }
+    /**
+     * Everything the connection was carrying, released.
+     *
+     * The local CAPTURES go with it, and that is the part worth stating. A
+     * publication whose transport has closed sends nothing, but the
+     * `getUserMedia` track behind it is still capturing: the recording indicator
+     * stays lit on the machine and the controls above still read "Mute", claiming
+     * a microphone is publishing into a room that has ended. Leaving them running
+     * is retained personal capture after the session it was consented to was
+     * terminated by the other party, so the room stops them wherever the
+     * connection goes - a leave, a drop, a drain, or the host closing the room -
+     * rather than only on the one path a person happens to take deliberately.
+     *
+     * The node is not told: this runs when the socket is already gone, and the
+     * node tears the session down on close anyway. Ending one publication on a
+     * LIVE connection is `unpublish`, which does tell it.
+     */
+    teardownMedia() {
+        for (const consumer of this.consumers.values())
+            consumer.close();
+        this.consumers.clear();
+        this.tracksByProducer.clear();
+        for (const publication of this.publications.values()) {
+            publication.handle.close();
+            publication.track.stop();
+        }
+        this.publications.clear();
+        this.sendTransport?.close();
+        this.recvTransport?.close();
+        this.sendTransport = undefined;
+        this.recvTransport = undefined;
+    }
+    emit() {
+        // Rebuilt HERE, once per change, rather than per read. Every mutation
+        // already funnels through this, so nothing can change without the snapshot
+        // following it.
+        this.trackSnapshot = [...this.tracksByProducer.values()];
+        this.publicationSnapshot = [...this.publications.values()];
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch {
+                // One subscriber throwing must not stop the others from being told.
+            }
+        }
+    }
+}
+exports.MediaRoom = MediaRoom;
+async function connectToRoom(options) {
+    const room = new MediaRoom(options);
+    await room.connect();
+    return room;
+}
+//# sourceMappingURL=room.js.map