@voltkit-rtc/client 0.2.0

package/src/index.ts

@@ -0,0 +1,945 @@
+/**
+ * Thin client SDK over the orchestrator's signaling protocol.
+ *
+ * The point of shipping this is that consuming projects never touch
+ * mediasoup-client directly -- otherwise every project re-implements transport
+ * setup, consumer resume ordering and reconnection, each slightly wrong.
+ */
+import { Device, type types as ms } from 'mediasoup-client';
+
+// From the package root rather than 'mediasoup-client/types', so the
+// published declarations resolve under every TypeScript module resolution,
+// including the older "node" one that ignores package exports.
+type Consumer = ms.Consumer;
+type Producer = ms.Producer;
+type RtpCapabilities = ms.RtpCapabilities;
+type Transport = ms.Transport;
+type TransportOptions = ms.TransportOptions;
+
+import type { ChatEvents, ChatMessage, ChatState, SendMessageOptions } from './chat.js';
+import { MusicSource, type MusicInput, type MusicOptions, type TrackSource } from './music.js';
+
+export { BroadcastPublisher, WhipError, whipEnd, whipOffer } from './broadcast.js';
+export { AudioMixer, MusicSource } from './music.js';
+export type { MusicInput, MusicOptions, TrackSource } from './music.js';
+export type { BroadcastEvents, BroadcastStartOptions, BroadcastState } from './broadcast.js';
+export { ChatClient, ChatRpcError } from './chat.js';
+export type {
+  ChatClientEvents,
+  ChatEvents,
+  ChatJoinResult,
+  ChatMessage,
+  ChatState,
+  SendMessageOptions,
+} from './chat.js';
+
+export type Role = 'host' | 'cohost' | 'moderator' | 'viewer';
+
+/** Sent when the account behind a session can no longer be used. */
+export interface UsageLimitNotice {
+  reason: 'quota-exhausted' | 'daily-limit-reached' | 'monthly-limit-reached' | 'suspended' | string;
+  graceSeconds: number;
+  /** When the session will be ended, in ms since the epoch. */
+  endsAt: number;
+}
+
+export interface JoinResult {
+  roomId: string;
+  identity: string;
+  role: Role;
+  nodeId: string;
+  isOrigin: boolean;
+  routerRtpCapabilities: RtpCapabilities;
+  participants: ParticipantInfo[];
+  producers: RemoteProducer[];
+  iceServers: RTCIceServer[];
+  /** Room metadata set by your backend or a moderator's setRoomMetadata. */
+  metadata?: unknown;
+  /** Exclusive slots (seats) and who holds them, to seed a seat board. */
+  claims?: SlotClaim[];
+  /** Slots a moderator has locked. */
+  blockedSlots?: string[];
+}
+
+export interface SlotClaim {
+  key: string;
+  identity: string;
+  /** `away`: the holder's connection dropped and the seat is kept for them. */
+  state: 'held' | 'away';
+  /** When an `away` claim expires, in unix milliseconds. */
+  awayUntil?: number;
+}
+
+export interface ParticipantInfo {
+  identity: string;
+  role: Role;
+  handRaised: boolean;
+  muted: boolean;
+  metadata?: unknown;
+}
+
+export interface RemoteProducer {
+  producerId: string;
+  identity: string;
+  kind: 'audio' | 'video';
+  paused: boolean;
+  /** What the track carries. A host playing music publishes two audio tracks: `mic` and `music`. */
+  source?: TrackSource;
+}
+
+const defaultSource = (kind: 'audio' | 'video'): TrackSource => (kind === 'audio' ? 'mic' : 'camera');
+
+export interface ClientEvents extends ChatEvents {
+  connected: () => void;
+  disconnected: (reason: string) => void;
+  joined: (result: JoinResult) => void;
+  track: (info: {
+    identity: string;
+    kind: 'audio' | 'video';
+    track: MediaStreamTrack;
+    producerId: string;
+    /** `music` is a host's in-app music. Play it through its own element to give viewers a music switch. */
+    source: TrackSource;
+  }) => void;
+  trackEnded: (info: { producerId: string; identity: string }) => void;
+  /** Someone paused or resumed one of their tracks: muted their mic, turned their music off. */
+  trackMuted: (info: { identity: string; kind: 'audio' | 'video'; source: TrackSource; producerId: string; paused: boolean }) => void;
+  participantJoined: (p: ParticipantInfo) => void;
+  participantLeft: (p: { identity: string; reason?: string }) => void;
+  roleChanged: (e: { identity: string; role: Role }) => void;
+  handRaised: (e: { identity: string; handRaised: boolean }) => void;
+  /**
+   * A moderator switched your microphone (`audio`), camera (`video`) or both
+   * (no kind) off, or released it (`paused: false`). While paused you cannot
+   * switch it back on.
+   */
+  forceMuted: (e: { by: string; kind?: 'audio' | 'video' | ''; paused: boolean }) => void;
+  mustReconnect: (e: { reason: string; token?: string; retry: boolean }) => void;
+  roomClosed: (e: { reason: string }) => void;
+  kicked: (e: { by: string; reason?: string }) => void;
+  error: (err: Error) => void;
+  localMediaChanged: (state: { micEnabled: boolean; camEnabled: boolean; musicEnabled: boolean }) => void;
+  /** The local stream was replaced, typically after reacquiring devices on a reconnect. */
+  localStreamChanged: (stream: MediaStream | null) => void;
+  /** Media stopped arriving but the connection is intact -- the publisher is reconnecting. */
+  streamInterrupted: (e: { reason: string }) => void;
+  /** The session ended and will not recover. Nothing further will be emitted. */
+  closed: (reason: 'replaced' | 'kicked' | 'room-closed' | 'gave-up' | 'left') => void;
+  /**
+   * The account behind this session ran out of minutes or reached a usage
+   * limit. The session ends at `endsAt` (after `graceSeconds`) unless the
+   * account is topped up first -- tell the user, and stop asking them to wait.
+   */
+  usageLimit: (e: UsageLimitNotice) => void;
+}
+
+type Handler = (...args: never[]) => void;
+
+/** An error returned by the server, carrying its machine-readable code. */
+export class RpcError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'RpcError';
+  }
+}
+
+/**
+ * Failures that reconnecting cannot fix. A room that has ended is not coming
+ * back, and a token that is wrong will be wrong next time too -- retrying
+ * these just floods the log and burns the attempt budget that a genuine
+ * network blip needs.
+ */
+const TERMINAL_JOIN_ERRORS = new Set([
+  'no-room',
+  'room-ended',
+  'wrong-tenant',
+  'bad-token',
+  'no-token',
+  'forbidden',
+  // The account cannot use the service until it is topped up or restored.
+  'quota-exhausted',
+  'daily-limit-reached',
+  'monthly-limit-reached',
+  'tenant-suspended',
+]);
+
+interface Pending {
+  resolve: (v: unknown) => void;
+  reject: (e: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const RPC_TIMEOUT_MS = 15_000;
+const MAX_RECONNECT_ATTEMPTS = 8;
+/** Server close code meaning "another socket took over this identity". */
+const CLOSE_REPLACED = 4001;
+/** The server ended the session on purpose and said why first: do not reconnect. */
+const CLOSE_ENDED = 4003;
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export class StreamClient {
+  private ws: WebSocket | null = null;
+  private device: Device | null = null;
+  private sendTransport: Transport | null = null;
+  private recvTransport: Transport | null = null;
+  // In-flight creations. Two `newProducer` events arriving back to back (a peer
+  // publishing audio and video) both call ensureRecvTransport before either
+  // await resolves, so a plain null check creates two transports -- and the
+  // server only remembers the last one, rejecting consumes on the first.
+  private sendTransportPending: Promise<Transport> | null = null;
+  private recvTransportPending: Promise<Transport> | null = null;
+  private readonly pending = new Map<number, Pending>();
+  private readonly listeners = new Map<string, Set<Handler>>();
+  private readonly consumers = new Map<string, Consumer>();
+  private readonly producers = new Map<string, Producer>();
+  private nextId = 1;
+  private token: string;
+  private joinResult: JoinResult | null = null;
+  private localStream: MediaStream | null = null;
+  // A reconnect tears down every transport and producer. Without remembering
+  // that this client was publishing -- and what it was publishing with -- a
+  // broadcaster that reconnects rejoins silently, which is worse than being
+  // disconnected: the room looks healthy and shows nothing.
+  private wasPublishing = false;
+  private publishConstraints: MediaStreamConstraints | null = null;
+  /** In-app music being published, kept across reconnects so it can be published again. */
+  private music: MusicSource | null = null;
+  private musicProducerId: string | null = null;
+  /** What each remote producer carries, so a pause can say "music" rather than just "audio". */
+  private readonly remoteSources = new Map<string, TrackSource>();
+  private closedByUs = false;
+  private reconnecting = false;
+  private reconnectAttempt = 0;
+
+  constructor(private readonly wsUrl: string, token: string) {
+    this.token = token;
+  }
+
+  on<K extends keyof ClientEvents>(event: K, fn: ClientEvents[K]): () => void {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn as Handler);
+    return () => set!.delete(fn as Handler);
+  }
+
+  private emit<K extends keyof ClientEvents>(event: K, ...args: Parameters<ClientEvents[K]>): void {
+    for (const fn of this.listeners.get(event) ?? []) {
+      try {
+        (fn as (...a: unknown[]) => void)(...args);
+      } catch (err) {
+        console.error(`listener for ${event} threw`, err);
+      }
+    }
+  }
+
+  // ------------------------------------------------------------- connection
+
+  async connect(): Promise<JoinResult> {
+    await this.openSocket();
+    const result = (await this.rpc('join', { token: this.token })) as JoinResult;
+    this.joinResult = result;
+
+    this.device = new Device();
+    await this.device.load({ routerRtpCapabilities: result.routerRtpCapabilities });
+
+    this.emit('joined', result);
+
+    // Subscribe to everything already publishing before we announce readiness.
+    for (const p of result.producers) {
+      await this.consume(p).catch((err) => this.emit('error', err as Error));
+    }
+
+    // Restore our own broadcast. This is what makes an origin failover
+    // survivable for the host: it reconnects onto the new origin and the
+    // stream comes back on its own.
+    if (this.wasPublishing && (result.role === 'host' || result.role === 'cohost')) {
+      await this.republish().catch((err) => this.emit('error', err as Error));
+    }
+    return result;
+  }
+
+  private openSocket(): Promise<void> {
+    // Abandon any previous socket first. Its close handler checks identity
+    // against `this.ws`, so once it is detached it can no longer trigger a
+    // reconnect -- which is what let multiple reconnect chains pile up.
+    this.detachSocket();
+
+    return new Promise((resolve, reject) => {
+      const url = new URL(this.wsUrl);
+      url.searchParams.set('token', this.token);
+      const ws = new WebSocket(url.toString());
+      this.ws = ws;
+
+      const onOpen = () => {
+        this.reconnectAttempt = 0;
+        this.emit('connected');
+        resolve();
+      };
+      const onError = () => reject(new Error('websocket failed to open'));
+
+      ws.addEventListener('open', onOpen, { once: true });
+      ws.addEventListener('error', onError, { once: true });
+      ws.addEventListener('message', (ev) => {
+        if (this.ws === ws) this.onMessage(ev.data as string);
+      });
+      ws.addEventListener('close', (ev) => {
+        ws.removeEventListener('error', onError);
+        // Only the socket we currently consider ours may drive reconnection.
+        if (this.ws !== ws) return;
+        this.ws = null;
+        this.failAllPending(new Error(`socket closed (${ev.code})`));
+        this.emit('disconnected', ev.reason || String(ev.code));
+
+        if (this.closedByUs) return;
+        if (ev.code === CLOSE_REPLACED) {
+          // Another session for this identity is live. Reconnecting would
+          // displace it, and it would displace us right back, forever.
+          this.emit('error', new Error('this identity connected from somewhere else'));
+          this.closedByUs = true;
+          this.emit('closed', 'replaced');
+          return;
+        }
+        if (ev.code === CLOSE_ENDED) {
+          // Normally roomClosed has already ended the session; this covers a
+          // close that arrived without it.
+          this.closedByUs = true;
+          this.emit('closed', 'room-closed');
+          return;
+        }
+        void this.scheduleReconnect();
+      });
+    });
+  }
+
+  private detachSocket(): void {
+    const ws = this.ws;
+    this.ws = null;
+    if (ws && ws.readyState <= WebSocket.OPEN) {
+      try {
+        ws.close(1000, 'superseded');
+      } catch {
+        /* already closing */
+      }
+    }
+  }
+
+  /**
+   * Reconnection is mandatory, not optional: nodes get drained, relays die and
+   * promotions move you to a different node. Always re-ask the orchestrator
+   * where to connect -- never assume the same node.
+   */
+  private async scheduleReconnect(): Promise<void> {
+    // Single-flight. The previous version recursed from its own catch block
+    // while the failed socket's close handler started a second chain, so each
+    // failure doubled the number of chains until the server was being hammered.
+    if (this.reconnecting || this.closedByUs) return;
+    this.reconnecting = true;
+    try {
+      while (!this.closedByUs) {
+        this.reconnectAttempt += 1;
+        if (this.reconnectAttempt > MAX_RECONNECT_ATTEMPTS) {
+          this.emit('error', new Error(`gave up after ${MAX_RECONNECT_ATTEMPTS} reconnect attempts`));
+          this.closedByUs = true;
+          this.emit('closed', 'gave-up');
+          return;
+        }
+        const backoff = Math.min(500 * 2 ** (this.reconnectAttempt - 1), 15_000);
+        await sleep(backoff + Math.random() * 400);
+        if (this.closedByUs) return;
+        try {
+          this.teardownMedia();
+          await this.connect();
+          return; // connect() resets the attempt counter once the socket opens
+        } catch (err) {
+          this.emit('error', err as Error);
+          // Stop on failures a retry cannot resolve. Hammering a room that has
+          // ended produces one error per attempt forever and drowns out
+          // whatever actually went wrong.
+          if (err instanceof RpcError && TERMINAL_JOIN_ERRORS.has(err.code)) {
+            this.closedByUs = true;
+            this.emit('closed', 'gave-up');
+            return;
+          }
+        }
+      }
+    } finally {
+      this.reconnecting = false;
+    }
+  }
+
+  close(): void {
+    // Only an app closing a live session is 'left'; kicked, room-closed and the
+    // others have already reported themselves and set closedByUs.
+    const wasOpen = !this.closedByUs;
+    this.closedByUs = true;
+    this.wasPublishing = false;
+    this.teardownMedia();
+    // Producers no longer stop their tracks, so releasing the camera and
+    // microphone is ours to do -- otherwise the device light stays on.
+    this.localStream?.getTracks().forEach((t) => t.stop());
+    this.localStream = null;
+    const ws = this.ws;
+    this.ws = null;
+    ws?.close(1000, 'client closed');
+    if (wasOpen) this.emit('closed', 'left');
+  }
+
+  private teardownMedia(): void {
+    for (const c of this.consumers.values()) c.close();
+    this.consumers.clear();
+    for (const p of this.producers.values()) p.close();
+    this.producers.clear();
+    this.musicProducerId = null;
+    this.sendTransport?.close();
+    this.recvTransport?.close();
+    this.sendTransport = null;
+    this.recvTransport = null;
+    this.sendTransportPending = null;
+    this.recvTransportPending = null;
+    this.device = null;
+  }
+
+  /** Everything currently known about the room, for rendering. */
+  get info(): JoinResult | null {
+    return this.joinResult;
+  }
+
+  // -------------------------------------------------------------------- rpc
+
+  private rpc(method: string, params: unknown = {}): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      if (this.ws?.readyState !== WebSocket.OPEN) {
+        reject(new Error('socket is not open'));
+        return;
+      }
+      const id = this.nextId++;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} timed out`));
+      }, RPC_TIMEOUT_MS);
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  private failAllPending(err: Error): void {
+    for (const p of this.pending.values()) {
+      clearTimeout(p.timer);
+      p.reject(err);
+    }
+    this.pending.clear();
+  }
+
+  private onMessage(raw: string): void {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+
+    if (typeof msg.id === 'number') {
+      const p = this.pending.get(msg.id);
+      if (!p) return;
+      clearTimeout(p.timer);
+      this.pending.delete(msg.id);
+      if (msg.ok) p.resolve(msg.result);
+      else {
+        const e = msg.error as { code?: string; message?: string } | undefined;
+        p.reject(new RpcError(e?.code ?? 'error', e?.message ?? 'unknown'));
+      }
+      return;
+    }
+
+    if (typeof msg.event === 'string') void this.onEvent(msg.event, msg.data);
+  }
+
+  private async onEvent(event: string, data: unknown): Promise<void> {
+    const d = (data ?? {}) as Record<string, never>;
+    switch (event) {
+      case 'newProducer':
+        await this.consume(data as RemoteProducer).catch((err) => this.emit('error', err as Error));
+        break;
+      case 'producerClosed': {
+        const { producerId, identity } = data as { producerId: string; identity: string };
+        const consumer = this.consumers.get(producerId);
+        if (!consumer) break; // never consumed it, or already cleaned up
+        consumer.close();
+        this.consumers.delete(producerId);
+        this.remoteSources.delete(producerId);
+        this.emit('trackEnded', { producerId, identity });
+        break;
+      }
+      case 'producerPaused': {
+        const p = data as { producerId: string; identity: string; kind: 'audio' | 'video'; paused: boolean };
+        this.emit('trackMuted', {
+          identity: p.identity,
+          kind: p.kind,
+          source: this.remoteSources.get(p.producerId) ?? defaultSource(p.kind),
+          producerId: p.producerId,
+          paused: p.paused,
+        });
+        break;
+      }
+      case 'participantJoined':
+        this.emit('participantJoined', data as ParticipantInfo);
+        break;
+      case 'participantLeft':
+        this.emit('participantLeft', data as { identity: string; reason?: string });
+        break;
+      case 'roleChanged': {
+        const e = data as { identity: string; role: Role };
+        this.emit('roleChanged', e);
+        // Demoted: the server has already closed our producers. Release the
+        // camera and microphone too, instead of capturing for nobody.
+        const canPublish = e.role === 'host' || e.role === 'cohost';
+        if (e.identity === this.joinResult?.identity && !canPublish && this.producers.size > 0) {
+          void this.unpublish().catch(() => undefined);
+        }
+        break;
+      }
+      case 'handRaised':
+      case 'handLowered':
+        this.emit('handRaised', data as { identity: string; handRaised: boolean });
+        break;
+      case 'forceMuted': {
+        // The server has already paused that kind (an audio mute includes
+        // in-app music: it travels as audio). Reflect it locally; a release
+        // changes nothing here -- switching back on is the user's choice.
+        const e = data as { by: string; kind?: 'audio' | 'video' | ''; paused: boolean };
+        if (e.paused) {
+          for (const p of this.producers.values()) {
+            if (!e.kind || p.kind === e.kind) p.pause();
+          }
+          this.emitLocalMedia();
+        }
+        this.emit('forceMuted', e);
+        break;
+      }
+      case 'tokenRefreshed': {
+        // A room outlives its join token many times over. The server hands us a
+        // fresh one periodically so a reconnect at any point still works --
+        // without this, any disconnect after the token's lifetime is terminal.
+        const e = data as { token?: string; role?: Role };
+        if (e.token) this.token = e.token;
+        break;
+      }
+      case 'mustReconnect': {
+        const e = data as { reason: string; token?: string; retry: boolean };
+        // A promotion hands us a fresh token carrying the new role.
+        if (e.token) this.token = e.token;
+        this.emit('mustReconnect', e);
+        if (e.retry) {
+          this.teardownMedia();
+          this.ws?.close(1000, 'reassigned');
+        }
+        break;
+      }
+      case 'streamInterrupted':
+        // Our node survived a failover; the origin did not. Stay connected --
+        // pictures come back when the host republishes and the pipe rebuilds.
+        this.emit('streamInterrupted', d as never);
+        break;
+      case 'usageLimit':
+        this.emit('usageLimit', d as never);
+        break;
+      case 'roomClosed':
+        this.closedByUs = true;
+        this.emit('roomClosed', d as never);
+        this.emit('closed', 'room-closed');
+        this.close();
+        break;
+      case 'kicked':
+        this.closedByUs = true;
+        this.emit('kicked', d as never);
+        this.emit('closed', 'kicked');
+        this.close();
+        break;
+      case 'message':
+        this.emit('message', data as ChatMessage);
+        break;
+      case 'messageDeleted':
+        this.emit('messageDeleted', data as { id: string; by: string });
+        break;
+      case 'chatMuted':
+        this.emit('chatMuted', data as { identity: string; muted: boolean; by: string });
+        break;
+      case 'typing':
+        this.emit('typing', data as { identity: string; typing: boolean });
+        break;
+      default:
+        break;
+    }
+  }
+
+  // ------------------------------------------------------------------ media
+
+  private ensureSendTransport(): Promise<Transport> {
+    if (this.sendTransport) return Promise.resolve(this.sendTransport);
+    if (this.sendTransportPending) return this.sendTransportPending;
+    this.sendTransportPending = this.createSendTransport().finally(() => {
+      this.sendTransportPending = null;
+    });
+    return this.sendTransportPending;
+  }
+
+  private async createSendTransport(): Promise<Transport> {
+    if (!this.device) throw new Error('not connected');
+
+    const params = (await this.rpc('createTransport', { direction: 'send' })) as TransportOptions;
+    const transport = this.device.createSendTransport({
+      ...params,
+      iceServers: this.joinResult?.iceServers,
+    });
+
+    transport.on('connect', ({ dtlsParameters }, ok, fail) => {
+      this.rpc('connectTransport', { transportId: transport.id, dtlsParameters })
+        .then(() => ok())
+        .catch(fail);
+    });
+    transport.on('produce', ({ kind, rtpParameters, appData }, ok, fail) => {
+      this.rpc('produce', { transportId: transport.id, kind, rtpParameters, appData, source: appData.source })
+        .then((res) => ok({ id: (res as { producerId: string }).producerId }))
+        .catch(fail);
+    });
+
+    this.sendTransport = transport;
+    return transport;
+  }
+
+  private ensureRecvTransport(): Promise<Transport> {
+    if (this.recvTransport) return Promise.resolve(this.recvTransport);
+    if (this.recvTransportPending) return this.recvTransportPending;
+    this.recvTransportPending = this.createRecvTransport().finally(() => {
+      this.recvTransportPending = null;
+    });
+    return this.recvTransportPending;
+  }
+
+  private async createRecvTransport(): Promise<Transport> {
+    if (!this.device) throw new Error('not connected');
+
+    const params = (await this.rpc('createTransport', { direction: 'recv' })) as TransportOptions;
+    const transport = this.device.createRecvTransport({
+      ...params,
+      iceServers: this.joinResult?.iceServers,
+    });
+    transport.on('connect', ({ dtlsParameters }, ok, fail) => {
+      this.rpc('connectTransport', { transportId: transport.id, dtlsParameters })
+        .then(() => ok())
+        .catch(fail);
+    });
+
+    this.recvTransport = transport;
+    return transport;
+  }
+
+  /**
+   * Publish local camera + mic. Only host/cohost may; others get a server error.
+   *
+   * Pass the constraints used to obtain the stream and they will be reused to
+   * reacquire the devices if a reconnect finds the tracks have ended.
+   */
+  async publish(stream: MediaStream, constraints?: MediaStreamConstraints): Promise<void> {
+    const transport = await this.ensureSendTransport();
+    this.localStream = stream;
+    this.wasPublishing = true;
+    if (constraints) this.publishConstraints = constraints;
+
+    const audio = stream.getAudioTracks()[0];
+    if (audio) {
+      const producer = await transport.produce({
+        track: audio,
+        // Keep the track alive when the producer closes: a reconnect closes
+        // every producer, and a stopped track cannot be republished.
+        stopTracks: false,
+        codecOptions: { opusStereo: true, opusDtx: true, opusFec: true },
+        appData: { source: 'mic' },
+      });
+      this.producers.set(producer.id, producer);
+    }
+
+    const video = stream.getVideoTracks()[0];
+    if (video) {
+      // Simulcast from day one: retrofitting it later is genuinely annoying,
+      // and it is what lets one node serve far more viewers.
+      const producer = await transport.produce({
+        track: video,
+        stopTracks: false,
+        encodings: [
+          { rid: 'q', scaleResolutionDownBy: 4, maxBitrate: 200_000, scalabilityMode: 'L1T3' },
+          { rid: 'h', scaleResolutionDownBy: 2, maxBitrate: 600_000, scalabilityMode: 'L1T3' },
+          { rid: 'f', scaleResolutionDownBy: 1, maxBitrate: 1_800_000, scalabilityMode: 'L1T3' },
+        ],
+        codecOptions: { videoGoogleStartBitrate: 1000 },
+        appData: { source: 'camera' },
+      });
+      this.producers.set(producer.id, producer);
+    }
+  }
+
+  /**
+   * Re-establish this client's broadcast after a reconnect.
+   *
+   * Reuses the existing tracks when they are still live -- the common case, and
+   * it avoids a second camera permission prompt. Only reacquires the devices
+   * when the tracks have genuinely ended.
+   */
+  private async republish(): Promise<void> {
+    // Music is not a device and cannot be "gone": publish it again whatever
+    // happens to the camera and microphone below.
+    if (this.music) await this.produceMusic(this.music).catch((err) => this.emit('error', err as Error));
+
+    let stream = this.localStream;
+    if (!stream && !this.publishConstraints) return; // music was all that was being published
+    const live = stream?.getTracks().some((t) => t.readyState === 'live') ?? false;
+
+    if (!live) {
+      if (!this.publishConstraints) {
+        this.emit('error', new Error('cannot restore the broadcast: the devices are gone'));
+        return;
+      }
+      stream = await navigator.mediaDevices.getUserMedia(this.publishConstraints);
+      this.localStream = stream;
+      this.emit('localStreamChanged', stream);
+    }
+    if (!stream) return;
+
+    await this.publish(stream);
+  }
+
+  // ------------------------------------------------------------------ music
+
+  /**
+   * Publish music playing inside the page, as its own track.
+   *
+   * The audience gets it clean -- it never passes through the microphone --
+   * and it has its own switch: `setMusicEnabled(false)` silences the music and
+   * leaves the host talking, `setMicEnabled(false)` does the opposite.
+   *
+   * Call it from a click. Browsers will not start audio processing for a page
+   * the user has not interacted with.
+   */
+  async publishMusic(input: MusicInput, options?: MusicOptions): Promise<void> {
+    if (this.music) await this.stopMusic();
+    const music = new MusicSource(input, options);
+    try {
+      await this.produceMusic(music);
+    } catch (err) {
+      music.close();
+      throw err;
+    }
+    this.music = music;
+    this.wasPublishing = true;
+    this.emitLocalMedia();
+  }
+
+  private async produceMusic(music: MusicSource): Promise<void> {
+    const transport = await this.ensureSendTransport();
+    const producer = await transport.produce({
+      track: music.track,
+      stopTracks: false,
+      // Music, not speech. Stereo, no silence suppression (it would chop the
+      // quiet parts of a song), and enough bitrate that it sounds like music.
+      codecOptions: { opusStereo: true, opusDtx: false, opusFec: true, opusMaxAverageBitrate: 128_000 },
+      appData: { source: 'music' },
+    });
+    this.producers.set(producer.id, producer);
+    this.musicProducerId = producer.id;
+  }
+
+  /** True while music is published, whether or not it is switched on. */
+  get musicPublishing(): boolean {
+    return this.music !== null;
+  }
+
+  get musicEnabled(): boolean {
+    const producer = this.musicProducerId ? this.producers.get(this.musicProducerId) : undefined;
+    return producer ? !producer.paused : false;
+  }
+
+  /** 0 to 1, for the audience. The host's own listening level is the element's. */
+  setMusicVolume(volume: number): void {
+    this.music?.setVolume(volume);
+  }
+
+  /** Switch the music off or on for the audience. The microphone is untouched. */
+  async setMusicEnabled(enabled: boolean): Promise<void> {
+    const producer = this.musicProducerId ? this.producers.get(this.musicProducerId) : undefined;
+    if (!producer) return;
+    if (enabled) producer.resume();
+    else producer.pause();
+    await this.rpc('pauseProducer', { producerId: producer.id, paused: !enabled });
+    this.emitLocalMedia();
+  }
+
+  /** Stop publishing music. The element or stream it came from is left as it was. */
+  async stopMusic(): Promise<void> {
+    const id = this.musicProducerId;
+    this.musicProducerId = null;
+    this.music?.close();
+    this.music = null;
+    if (id) {
+      this.producers.get(id)?.close();
+      this.producers.delete(id);
+      await this.rpc('closeProducer', { producerId: id }).catch(() => undefined);
+    }
+    this.emitLocalMedia();
+  }
+
+  private emitLocalMedia(): void {
+    this.emit('localMediaChanged', {
+      micEnabled: this.micEnabled,
+      camEnabled: this.camEnabled,
+      musicEnabled: this.musicEnabled,
+    });
+  }
+
+  private async consume(remote: RemoteProducer): Promise<void> {
+    if (!this.device) throw new Error('not connected');
+    if (this.consumers.has(remote.producerId)) return;
+    // Your own camera is already local; pulling it back off the SFU wastes a
+    // consumer and shows you a delayed copy of yourself.
+    if (remote.identity === this.joinResult?.identity) return;
+
+    const transport = await this.ensureRecvTransport();
+    const params = (await this.rpc('consume', {
+      transportId: transport.id,
+      producerId: remote.producerId,
+      rtpCapabilities: this.device.rtpCapabilities,
+    })) as { id: string; producerId: string; kind: 'audio' | 'video'; rtpParameters: never };
+
+    const consumer = await transport.consume(params);
+    this.consumers.set(remote.producerId, consumer);
+
+    // The server created it paused. Resume only now that our end exists,
+    // otherwise the first frames arrive before there is anything to decode them.
+    await this.rpc('resumeConsumer', { consumerId: consumer.id });
+
+    const kind = consumer.kind as 'audio' | 'video';
+    const source = remote.source ?? defaultSource(kind);
+    this.remoteSources.set(remote.producerId, source);
+    this.emit('track', {
+      identity: remote.identity,
+      kind,
+      track: consumer.track,
+      producerId: remote.producerId,
+      source,
+    });
+  }
+
+  // ------------------------------------------------------------- moderation
+
+  // ------------------------------------------------------------ local media
+
+  /** True once this client has at least one live producer. */
+  get publishing(): boolean {
+    return this.producers.size > 0;
+  }
+
+  get micEnabled(): boolean {
+    return this.trackEnabled('audio');
+  }
+
+  get camEnabled(): boolean {
+    return this.trackEnabled('video');
+  }
+
+  private trackEnabled(kind: 'audio' | 'video'): boolean {
+    for (const p of this.producers.values()) {
+      if (p.kind === kind && p.id !== this.musicProducerId) return !p.paused;
+    }
+    return false;
+  }
+
+  /**
+   * Pausing the producer stops RTP at the source, so it costs nothing on the
+   * SFU and every viewer is told. Muting only the local track would keep
+   * sending silence and leave viewers showing you as unmuted.
+   */
+  async setMicEnabled(enabled: boolean): Promise<void> {
+    await this.setKindEnabled('audio', enabled);
+  }
+
+  async setCamEnabled(enabled: boolean): Promise<void> {
+    await this.setKindEnabled('video', enabled);
+  }
+
+  private async setKindEnabled(kind: 'audio' | 'video', enabled: boolean): Promise<void> {
+    for (const producer of this.producers.values()) {
+      // The music has its own switch. Muting the microphone must not stop the song.
+      if (producer.kind !== kind || producer.id === this.musicProducerId) continue;
+      if (enabled) producer.resume();
+      else producer.pause();
+      await this.rpc('pauseProducer', { producerId: producer.id, paused: !enabled });
+    }
+    this.emitLocalMedia();
+  }
+
+  /** Stop publishing entirely and release the local devices. */
+  async unpublish(): Promise<void> {
+    const ids = [...this.producers.keys()];
+    for (const producer of this.producers.values()) producer.close();
+    this.producers.clear();
+    for (const id of ids) {
+      await this.rpc('closeProducer', { producerId: id }).catch(() => undefined);
+    }
+    this.localStream?.getTracks().forEach((t) => t.stop());
+    this.localStream = null;
+    this.music?.close();
+    this.music = null;
+    this.musicProducerId = null;
+    this.wasPublishing = false;
+    this.emit('localStreamChanged', null);
+    this.emit('localMediaChanged', { micEnabled: false, camEnabled: false, musicEnabled: false });
+  }
+
+  get local(): MediaStream | null {
+    return this.localStream;
+  }
+
+  // ------------------------------------------------------------- moderation
+
+  raiseHand(): Promise<unknown> { return this.rpc('raiseHand'); }
+  lowerHand(): Promise<unknown> { return this.rpc('lowerHand'); }
+  muteParticipant(identity: string): Promise<unknown> { return this.rpc('requestMute', { identity }); }
+  /**
+   * Moderating roles: switch someone's microphone (`audio`), camera (`video`)
+   * or both (no kind) off at the server, where they cannot switch it back on.
+   * `paused: false` releases it; they then turn it on themselves.
+   */
+  forceMute(identity: string, kind?: 'audio' | 'video', paused = true): Promise<unknown> {
+    return this.rpc('forceMute', { identity, kind: kind ?? '', paused });
+  }
+  promote(identity: string, role: Role): Promise<unknown> { return this.rpc('promote', { identity, role }); }
+  kick(identity: string, reason?: string): Promise<unknown> { return this.rpc('kick', { identity, reason }); }
+  endRoom(): Promise<unknown> { return this.rpc('endRoom'); }
+  getRoomState(): Promise<unknown> { return this.rpc('getRoomState'); }
+
+  // ------------------------------------------------------------------- chat
+  //
+  // The room's chat rides this same socket. Someone on a chat-only socket
+  // (ChatClient) for the same channel is in the same conversation.
+
+  sendMessage(text: string, opts: SendMessageOptions = {}): Promise<{ id: string; ts: number }> {
+    return this.rpc('sendMessage', { text, ...opts }) as Promise<{ id: string; ts: number }>;
+  }
+
+  /** Older messages, oldest first. Pass the oldest id you hold as `before`. */
+  async getMessages(opts: { limit?: number; before?: string } = {}): Promise<ChatMessage[]> {
+    const res = (await this.rpc('getMessages', opts)) as { messages: ChatMessage[] };
+    return res.messages;
+  }
+
+  /** Your own message, or anyone's if you are a moderator. */
+  deleteMessage(messageId: string): Promise<unknown> { return this.rpc('deleteMessage', { messageId }); }
+  /** Moderators only. A mute outlasts the muted socket reconnecting. */
+  muteChat(identity: string, muted = true): Promise<unknown> { return this.rpc('muteChat', { identity, muted }); }
+  /** Advisory, and throttled by the server; safe to call on every keystroke. */
+  setTyping(typing: boolean): Promise<unknown> { return this.rpc('setTyping', { typing }); }
+  getChatState(): Promise<ChatState> { return this.rpc('getChatState') as Promise<ChatState>; }
+}