@voltkit-rtc/client 0.6.1 → 0.7.0

package/src/index.ts

@@ -19,6 +19,19 @@ type Transport = ms.Transport;
 type TransportOptions = ms.TransportOptions;
 
 import type { ChatEvents, ChatMessage, ChatState, SendMessageOptions } from './chat.js';
+import { isTerminalError, RpcError } from './errors.js';
+import {
+  above60fpsCap,
+  AUDIO_SETTINGS,
+  qualityAt,
+  resolvePermissions,
+  type AudioQuality,
+  type JoinBilling,
+  type JoinMedia,
+  type MediaPermissions,
+} from './media-permissions.js';
+import { NetworkQualityWatch, type NetworkQuality } from './network.js';
+import { socketUrl, TOKEN_EXPIRING_LEAD_MS, tokenExpiresAt } from './token.js';
 import {
   chooseCodec,
   currentEnv,
@@ -66,6 +79,13 @@ 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 { RpcError, ERROR_CODES, errorInfo, isTerminalError } from './errors.js';
+export type { ErrorCode, ErrorInfo, ErrorOrigin } from './errors.js';
+export { AUDIO_QUALITIES, AUDIO_SETTINGS, DEFAULT_MEDIA_PERMISSIONS, resolvePermissions } from './media-permissions.js';
+export type { AudioQuality, BillingMode, JoinBilling, JoinMedia, MediaPermissions, MediaProfile } from './media-permissions.js';
+export { NETWORK_QUALITY_INTERVAL_MS, NETWORK_QUALITY_LEVELS, networkLevel } from './network.js';
+export type { NetworkQuality, NetworkQualityLevel } from './network.js';
+export { TOKEN_EXPIRING_LEAD_MS, tokenExpiresAt } from './token.js';
 export { allowedQuality, layerBitrate, videoEncodings, VIDEO_QUALITIES } from './quality.js';
 export type { LayerCount, VideoEncoding, VideoPolicy, VideoQuality, VideoLayer, ReceiveQuality, ScreenMode } from './quality.js';
 export type { CodecPreference } from './device.js';
@@ -89,6 +109,59 @@ export interface UsageLimitNotice {
   endsAt: number;
 }
 
+/**
+ * Wallet billing: what the project may still spend covers less than the
+ * grace period at the current burn, or (`cleared: true`) a recharge or a
+ * lower burn lifted it back above it.
+ */
+export interface WalletLowNotice {
+  /** Seconds the funds cover at the current burn; -1 on a cleared notice when nothing limits them. */
+  remainingSeconds: number;
+  /** True once the warning is over: hide the banner, and the `usageLimit` countdown sent beside it is cancelled. */
+  cleared?: boolean;
+}
+
+/** The token this client would reconnect with lapses soon, and nobody has refreshed it. */
+export interface TokenExpiringNotice {
+  /** When it expires, in ms since the epoch. */
+  expiresAt: number;
+  secondsLeft: number;
+}
+
+/** Where a session stands, in the order a session goes through them. `closed` is final; the `closed` event says why. */
+export const CONNECTION_STATES = Object.freeze(['idle', 'connecting', 'connected', 'reconnecting', 'closed'] as const);
+export type ConnectionState = (typeof CONNECTION_STATES)[number];
+
+export type ClosedReason = 'replaced' | 'kicked' | 'room-closed' | 'gave-up' | 'left';
+
+/** A slot changed hands, went away, came back, was locked or was freed. */
+export interface ClaimChange {
+  key: string;
+  /** Null when the slot is now free or blocked. */
+  identity: string | null;
+  state: 'held' | 'away' | 'free' | 'blocked';
+  /** `claimed`, `moved`, `released`, `disconnected`, `reconnected`, `expired`, `blocked` or `unblocked`. */
+  reason: string;
+}
+
+/** A track this client is receiving. */
+export interface RemoteTrack {
+  producerId: string;
+  identity: string;
+  kind: 'audio' | 'video';
+  source: TrackSource;
+  track: MediaStreamTrack;
+  /** Its publisher has it switched off (or a moderator does). */
+  paused: boolean;
+}
+
+/** What this client publishes, as `localMediaChanged` reports it. */
+export interface LocalMediaState {
+  micEnabled: boolean;
+  camEnabled: boolean;
+  musicEnabled: boolean;
+}
+
 export interface JoinResult {
   roomId: string;
   identity: string;
@@ -110,9 +183,24 @@ export interface JoinResult {
    * on a publisher's incoming bitrate. Absent from older servers: 1080p.
    */
   video?: VideoPolicy;
+  /**
+   * The project's media settings, the modes they allow and the fan-out
+   * limits. Absent from older servers; `mediaPermissions` resolves either.
+   */
+  media?: JoinMedia;
+  /** How this session is billed. Absent from older servers. */
+  billing?: JoinBilling;
 }
 
 export interface PublishOptions {
+  /**
+   * The microphone: `'std'` (the default) is mono Opus up to 64 kbps, billed
+   * as standard audio; `'hd'` is stereo Opus up to 128 kbps, billed as HD
+   * audio. HD in a project limited to standard audio sends standard and warns
+   * on `error` with `audio-quality-not-allowed`. Change it live with
+   * `setAudioQuality`. Music (`publishMusic`) is not affected.
+   */
+  audioQuality?: AudioQuality;
   /** 30 by default. Only the top layer uses 60; capture at 60 too. */
   frameRate?: 30 | 60;
   /**
@@ -158,6 +246,23 @@ export interface ScreenPublishOptions {
   stream?: MediaStream;
 }
 
+/**
+ * The handlers mediasoup-client can make its Device with. `ReactNative106` is
+ * reserved for future native hosts (react-native-webrtc); nothing published
+ * uses it yet.
+ */
+export type DeviceHandlerName = 'Chrome111' | 'Chrome74' | 'Firefox120' | 'Safari12' | 'ReactNative106';
+
+/** `new StreamClient(wsUrl, token, options)`. Everything here is optional; a browser needs none of it. */
+export interface ClientOptions {
+  /**
+   * The mediasoup-client handler to make the Device with, instead of detecting
+   * the browser from its user agent. Leave it unset in browsers; it is
+   * reserved for future native hosts, which have no user agent to detect.
+   */
+  handlerName?: DeviceHandlerName;
+}
+
 export interface SlotClaim {
   key: string;
   identity: string;
@@ -193,6 +298,8 @@ const defaultSource = (kind: 'audio' | 'video'): TrackSource => (kind === 'audio
 export interface ClientEvents extends ChatEvents {
   connected: () => void;
   disconnected: (reason: string) => void;
+  /** idle → connecting → connected ⇄ reconnecting → closed. Read it any time as `connectionState`. */
+  connectionStateChanged: (e: { state: ConnectionState; previous: ConnectionState }) => void;
   joined: (result: JoinResult) => void;
   track: (info: {
     identity: string;
@@ -208,6 +315,8 @@ export interface ClientEvents extends ChatEvents {
   participantJoined: (p: ParticipantInfo) => void;
   participantLeft: (p: { identity: string; reason?: string }) => void;
   participantMuted: (e: { identity: string; kind?: 'audio' | 'video' | ''; paused: boolean }) => void;
+  /** Someone's display metadata changed (their own `setMetadata`). */
+  participantUpdated: (e: { identity: string; metadata: unknown }) => void;
   roleChanged: (e: { identity: string; role: Role }) => void;
   handRaised: (e: { identity: string; handRaised: boolean; metadata?: Record<string, unknown>; reason?: string }) => void;
   /**
@@ -216,25 +325,58 @@ export interface ClientEvents extends ChatEvents {
    * switch it back on.
    */
   forceMuted: (e: { by: string; kind?: 'audio' | 'video' | ''; paused: boolean }) => void;
+  /**
+   * A slot changed. **Draw `away` as taken (greyed), never as free**: the
+   * holder's connection dropped and the slot is kept for them. `info.claims`
+   * and `info.blockedSlots` are kept current from these.
+   */
+  claimChanged: (e: ClaimChange) => void;
+  /** Room metadata changed (a moderator's `setRoomMetadata`); persisted, so `info.metadata` is kept current too. */
+  roomMetadataChanged: (e: { metadata: unknown; by?: string }) => void;
   mustReconnect: (e: { reason: string; token?: string; retry: boolean }) => void;
   roomClosed: (e: { reason: string }) => void;
   kicked: (e: { by: string; reason?: string }) => void;
   screenShareStarted: (e: { stream: MediaStream; mode: ScreenMode }) => void;
   screenShareEnded: (e: { reason: 'stopped' | 'track-ended' }) => void;
+  /**
+   * A failure, or a warning that changes nothing else: an `RpcError` whose
+   * `code` is in `ERROR_CODES` (`frame-rate-fallback`,
+   * `audio-quality-not-allowed`, ...). Switch on the code.
+   */
   error: (err: Error) => void;
-  localMediaChanged: (state: { micEnabled: boolean; camEnabled: boolean; musicEnabled: boolean }) => void;
+  localMediaChanged: (state: LocalMediaState) => 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;
+  closed: (reason: ClosedReason) => 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;
+  /**
+   * Wallet billing: the funds this project may spend cover less than the
+   * grace period at the current burn, repeated while it lasts; the room closes
+   * when they reach zero unless the wallet is recharged. A notice with
+   * `cleared: true` ends the warning (and the `usageLimit` countdown beside it).
+   */
+  walletLow: (e: WalletLowNotice) => void;
+  /**
+   * The token this client would reconnect with expires in about a minute and
+   * the server has not refreshed it (it stops when the account may no longer
+   * be used, or the socket is down). Mint a new one on your backend and hand it
+   * over with `updateToken`.
+   */
+  tokenExpiring: (e: TokenExpiringNotice) => void;
+  /**
+   * Round trip, packet loss and available bandwidth to the media server, about
+   * every 3 s while listened to and media is flowing, with a level for the UI
+   * (thresholds in the README). Sampled only while someone listens.
+   */
+  networkQuality: (e: NetworkQuality) => void;
   /**
    * Your camera video is being held back by this device (`cpu`: too busy to
    * encode it), by the upload (`bandwidth`), or by something else (`other`);
@@ -248,33 +390,22 @@ export interface ClientEvents extends ChatEvents {
 
 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',
-]);
+// Every event a StreamClient emits. Typed against ClientEvents, so adding an
+// event without listing it here (or listing one that does not exist) fails to
+// compile; the contract check compares this list with docs/sdk-contract.json.
+const EVENT_NAMES: { readonly [K in keyof ClientEvents]-?: true } = {
+  connected: true, disconnected: true, connectionStateChanged: true, joined: true,
+  track: true, trackEnded: true, trackMuted: true,
+  participantJoined: true, participantLeft: true, participantMuted: true, participantUpdated: true,
+  roleChanged: true, handRaised: true, forceMuted: true, claimChanged: true, roomMetadataChanged: true,
+  mustReconnect: true, roomClosed: true, kicked: true, streamInterrupted: true, closed: true,
+  usageLimit: true, walletLow: true, tokenExpiring: true, networkQuality: true, videoLimited: true,
+  screenShareStarted: true, screenShareEnded: true, error: true, localMediaChanged: true, localStreamChanged: true,
+  message: true, messageDeleted: true, chatMuted: true, typing: true,
+};
+
+/** The names of every event `StreamClient.on` accepts. */
+export const CLIENT_EVENTS = Object.freeze(Object.keys(EVENT_NAMES) as (keyof ClientEvents)[]);
 
 interface Pending {
   resolve: (v: unknown) => void;
@@ -306,7 +437,26 @@ const isLayer = (value: unknown): value is number => Number.isInteger(value) &&
 const VIDEO_START_BITRATE_KBPS = 2000;
 
 /** Why a publish gave up: unpublish() ran while it was under way, and unpublish wins. */
-const unpublishedWhile = (what: string) => `the ${what} was unpublished while it was being published`;
+const unpublishedWhile = (what: string) => new RpcError('unpublished', `the ${what} was unpublished while it was being published`);
+
+/**
+ * mediasoup-client puts the microphone's Opus maxaveragebitrate in the answer
+ * SDP only, so the server would never see it. Declare it in the producer's
+ * parameters too: the media node bills HD on a declared value above 64,000
+ * (spec §4) and refuses one in a project limited to standard audio, so a
+ * standard microphone declares 64,000 and an HD one 128,000. Music and screen
+ * audio go out as they always did.
+ */
+function declareAudioQuality(rtpParameters: ms.RtpParameters, appData: Record<string, unknown>): ms.RtpParameters {
+  const quality = appData.audioQuality;
+  if (appData.source !== 'mic' || (quality !== 'std' && quality !== 'hd')) return rtpParameters;
+  const maxaveragebitrate = AUDIO_SETTINGS[quality].maxBitrate;
+  return {
+    ...rtpParameters,
+    codecs: rtpParameters.codecs.map((codec) => (codec.mimeType.toLowerCase() === 'audio/opus'
+      ? { ...codec, parameters: { ...codec.parameters, maxaveragebitrate } } : codec)),
+  };
+}
 
 export class StreamClient {
   private ws: WebSocket | null = null;
@@ -384,9 +534,33 @@ export class StreamClient {
     undefined,
     () => { this.frameRateLowSamples = 0; this.frameRateWarmupSamples = 2; },
   );
+  /** Where the session stands; see connectionStateChanged. */
+  private state: ConnectionState = 'idle';
+  /** When the token held for reconnects expires (unix ms), and the timer that warns before it does. */
+  private tokenExpiry: number | null;
+  private tokenTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Whose each received track is and whether it is switched off, by producerId. */
+  private readonly remoteInfo = new Map<string, { identity: string; kind: 'audio' | 'video'; paused: boolean }>();
+  /** Videos left unconsumed at the fan-out limit, oldest first; consumed as others end. */
+  private readonly skippedVideos = new Map<string, RemoteProducer>();
+  /** Producers whose video this client receives, or is about to: the fan-out count. */
+  private readonly videoSlots = new Set<string>();
+  /** The quality the microphone producer was made with. */
+  private micQuality: AudioQuality = 'std';
+  // Changes to the microphone producer run one at a time, as the camera's do.
+  private micQueue: Promise<unknown> = Promise.resolve();
+  // A request the project does not allow is reported once, until it is made again.
+  private audioCapReported = false;
+  private sizeCapReported = false;
+  private readonly networkWatch = new NetworkQualityWatch(
+    () => this.transportStats(),
+    () => this.producers.size > 0,
+    (quality) => this.emit('networkQuality', quality),
+  );
 
-  constructor(private readonly wsUrl: string, token: string) {
+  constructor(private readonly wsUrl: string, token: string, private readonly options: ClientOptions = {}) {
     this.token = token;
+    this.tokenExpiry = tokenExpiresAt(token);
   }
 
   on<K extends keyof ClientEvents>(event: K, fn: ClientEvents[K]): () => void {
@@ -396,14 +570,43 @@ export class StreamClient {
       this.listeners.set(event, set);
     }
     set.add(fn as Handler);
-    // videoLimited costs a getStats every 2 s, so it runs only while heard.
+    // videoLimited and networkQuality cost a getStats every few seconds, so
+    // they run only while heard.
     if (event === 'videoLimited') this.syncLimitWatch();
+    if (event === 'networkQuality') this.syncNetworkWatch();
     return () => {
       set!.delete(fn as Handler);
       if (event === 'videoLimited') this.syncLimitWatch();
+      if (event === 'networkQuality') this.syncNetworkWatch();
     };
   }
 
+  /** Where the session stands: idle, connecting, connected, reconnecting or closed. */
+  get connectionState(): ConnectionState {
+    return this.state;
+  }
+
+  private setState(next: ConnectionState): void {
+    if (next === this.state) return;
+    const previous = this.state;
+    this.state = next;
+    if (next === 'closed') this.stopTimers();
+    this.emit('connectionStateChanged', { state: next, previous });
+  }
+
+  /** Over for good: the state, then the event that says why. */
+  private finish(reason: ClosedReason): void {
+    this.closedByUs = true;
+    this.setState('closed');
+    this.emit('closed', reason);
+  }
+
+  private stopTimers(): void {
+    if (this.tokenTimer) clearTimeout(this.tokenTimer);
+    this.tokenTimer = null;
+    this.networkWatch.set(false);
+  }
+
   private listenerCount(event: keyof ClientEvents): number {
     return this.listeners.get(event)?.size ?? 0;
   }
@@ -422,6 +625,7 @@ export class StreamClient {
 
   async connect(): Promise<JoinResult> {
     let result: JoinResult;
+    if (this.state === 'idle' || this.state === 'closed') this.setState('connecting');
     try {
       await this.openSocket();
       result = (await this.rpc('join', { token: this.token })) as JoinResult;
@@ -433,7 +637,10 @@ export class StreamClient {
       // A session that never got going: the app has the error. Left open,
       // the socket would be closed by the server's join deadline instead, and
       // that close would start reconnecting a session that never began.
-      if (!this.joinedOnce) this.detachSocket();
+      if (!this.joinedOnce) {
+        this.detachSocket();
+        if (this.state === 'connecting') this.setState('idle');
+      }
       throw err;
     }
     // Joined and set up: the next drop gets every reconnect attempt again.
@@ -442,6 +649,9 @@ export class StreamClient {
     // retried about twice a second, forever.
     this.reconnectAttempt = 0;
     this.joinedOnce = true;
+    this.skippedVideos.clear();
+    this.setState('connected');
+    this.scheduleTokenExpiring();
 
     // A role or mute can change while the socket is away. The fresh roster
     // decides what may return; reconnecting never turns a blocked device on.
@@ -477,12 +687,18 @@ export class StreamClient {
     if (this.wasPublishing && (result.role === 'host' || result.role === 'cohost')) {
       await this.republish().catch((err) => this.emit('error', err as Error));
     }
+    this.syncNetworkWatch();
     return result;
   }
 
-  /** A new mediasoup Device for each join. Its own method so tests, which have no WebRTC, can stand one in. */
+  /**
+   * A new mediasoup Device for each join: the handler named in the options, or
+   * the one detected from the browser. Its own method so tests, which have no
+   * WebRTC, can stand one in.
+   */
   private createDevice(): Device {
-    return new Device();
+    const { handlerName } = this.options;
+    return handlerName ? new Device({ handlerName }) : new Device();
   }
 
   private openSocket(): Promise<void> {
@@ -492,16 +708,14 @@ export class StreamClient {
     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());
+      const ws = new WebSocket(socketUrl(this.wsUrl, this.token));
       this.ws = ws;
 
       const onOpen = () => {
         this.emit('connected');
         resolve();
       };
-      const onError = () => reject(new Error('websocket failed to open'));
+      const onError = () => reject(new RpcError('connect-failed', 'websocket failed to open'));
 
       ws.addEventListener('open', onOpen, { once: true });
       ws.addEventListener('error', onError, { once: true });
@@ -513,32 +727,32 @@ export class StreamClient {
         // 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.failAllPending(new RpcError('not-connected', `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('error', new RpcError('replaced', 'this identity connected from somewhere else'));
           // The producers outlive this close until the app calls close(); the
           // videoLimited sampling must not, or it reports after `closed`.
           this.limitWatch.reset();
-          this.emit('closed', 'replaced');
+          this.finish('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.limitWatch.reset();
-          this.emit('closed', 'room-closed');
+          this.finish('room-closed');
           return;
         }
         // Before a first successful join the app is still waiting on
         // connect(), which reports the failure; there is nothing to restore.
         if (!this.joinedOnce) return;
+        this.setState('reconnecting');
+        this.networkWatch.set(false);
         void this.scheduleReconnect();
       });
     });
@@ -571,9 +785,8 @@ export class StreamClient {
       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');
+          this.emit('error', new RpcError('reconnect-gave-up', `gave up after ${MAX_RECONNECT_ATTEMPTS} reconnect attempts`));
+          this.finish('gave-up');
           return;
         }
         const backoff = Math.min(500 * 2 ** (this.reconnectAttempt - 1), 15_000);
@@ -589,12 +802,11 @@ export class StreamClient {
           if (this.ws) return;
         } 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');
+          // Stop on failures a retry cannot resolve (the registry's terminal
+          // codes). Hammering a room that has ended produces one error per
+          // attempt forever and drowns out whatever actually went wrong.
+          if (err instanceof RpcError && isTerminalError(err.code)) {
+            this.finish('gave-up');
             return;
           }
         }
@@ -621,6 +833,7 @@ export class StreamClient {
     this.music = null;
     // Nothing is emitted after closing, so not even a clearing videoLimited.
     this.limitWatch.reset();
+    this.skippedVideos.clear();
     // 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());
@@ -628,12 +841,16 @@ export class StreamClient {
     const ws = this.ws;
     this.ws = null;
     ws?.close(1000, 'client closed');
+    this.setState('closed');
     if (wasOpen) this.emit('closed', 'left');
   }
 
   private teardownMedia(): void {
     for (const c of this.consumers.values()) c.close();
     this.consumers.clear();
+    this.remoteInfo.clear();
+    this.skippedVideos.clear();
+    this.videoSlots.clear();
     for (const p of this.producers.values()) p.close();
     this.producers.clear();
     this.musicProducerId = null;
@@ -649,25 +866,142 @@ export class StreamClient {
     this.sendTransportPending = null;
     this.recvTransportPending = null;
     this.device = null;
+    this.syncNetworkWatch();
   }
 
-  /** Everything currently known about the room, for rendering. */
+  /**
+   * Everything currently known about the room, for rendering: the join
+   * result, kept current -- participants, roles, hands, mutes, display
+   * metadata, slots and room metadata follow the events.
+   */
   get info(): JoinResult | null {
     return this.joinResult;
   }
 
+  /** Who is in the room now, this client included; kept current from the roster events. */
+  get participants(): ParticipantInfo[] {
+    return [...(this.joinResult?.participants ?? [])];
+  }
+
+  /** Every track this client is receiving now. */
+  get remoteTracks(): RemoteTrack[] {
+    const out: RemoteTrack[] = [];
+    for (const [producerId, consumer] of this.consumers) {
+      const info = this.remoteInfo.get(producerId);
+      if (!info || consumer.closed) continue;
+      out.push({
+        producerId, identity: info.identity, kind: info.kind, track: consumer.track,
+        source: this.remoteSources.get(producerId) ?? defaultSource(info.kind), paused: info.paused,
+      });
+    }
+    return out;
+  }
+
+  /**
+   * What this project lets this client publish: from the join result's
+   * `media` (servers with wallet billing), else its `video` policy, else
+   * everything before a join. Offer only these in your UI; the SDK refuses
+   * or caps anything else with the server's own codes.
+   */
+  get mediaPermissions(): MediaPermissions {
+    return resolvePermissions(this.joinResult);
+  }
+
+  /** How this session is billed: `legacy` (minutes) or `wallet`; null before a join or on older servers. */
+  get billingMode(): 'legacy' | 'wallet' | null {
+    return this.joinResult?.billing?.mode ?? null;
+  }
+
+  // ------------------------------------------------------------ token refresh
+
+  /**
+   * Hand the session a newer room token, minted by your backend for the same
+   * room and identity (`POST /v1/rooms/{roomId}/tokens`), typically on
+   * `tokenExpiring`. On a live connection the server checks it like a join
+   * token (`bad-token`, or `token-mismatch` for another room or identity; the
+   * session then keeps its token); otherwise it is kept for the next join,
+   * which checks it there. Resolves to when it expires (unix ms), when known.
+   */
+  async updateToken(token: string): Promise<{ expiresAt: number | null }> {
+    if (typeof token !== 'string' || token.trim() === '') throw new TypeError('updateToken needs a token');
+    if (this.state === 'closed') throw new RpcError('not-connected', 'this session is closed; create a new client');
+    if (this.state === 'connected' && this.ws?.readyState === WebSocket.OPEN) {
+      try {
+        const res = (await this.rpc('refreshToken', { token })) as { expiresAt?: unknown } | undefined;
+        const at = typeof res?.expiresAt === 'number' && res.expiresAt > 0 ? res.expiresAt * 1000 : null;
+        this.setToken(token, at);
+        return { expiresAt: this.tokenExpiry };
+      } catch (err) {
+        // An older server has no refreshToken, and a socket that dropped
+        // during the call is reconnecting: either way keep the token for the
+        // next join, which checks it.
+        if (!(err instanceof RpcError) || (err.code !== 'unknown-method' && err.code !== 'not-connected')) throw err;
+      }
+    }
+    this.setToken(token, null);
+    return { expiresAt: this.tokenExpiry };
+  }
+
+  /** The token reconnects use from now on, with its expiry (read from the token when not given). */
+  private setToken(token: string, expiresAt: number | null): void {
+    this.token = token;
+    this.tokenExpiry = expiresAt ?? tokenExpiresAt(token);
+    this.scheduleTokenExpiring();
+  }
+
+  /**
+   * Warn TOKEN_EXPIRING_LEAD_MS before the token held for reconnects
+   * expires. Every new token -- the server's refresh, a promotion's, the
+   * app's -- reschedules it, so it fires only when nobody refreshed it.
+   */
+  private scheduleTokenExpiring(): void {
+    if (this.tokenTimer) clearTimeout(this.tokenTimer);
+    this.tokenTimer = null;
+    const expiresAt = this.tokenExpiry;
+    if (expiresAt === null || this.state === 'idle' || this.state === 'closed') return;
+    // setTimeout cannot wait longer than about 24.8 days.
+    const delay = Math.min(Math.max(0, expiresAt - TOKEN_EXPIRING_LEAD_MS - Date.now()), 2_147_000_000);
+    this.tokenTimer = setTimeout(() => {
+      this.tokenTimer = null;
+      if (this.state === 'closed' || this.tokenExpiry !== expiresAt) return;
+      if (expiresAt - TOKEN_EXPIRING_LEAD_MS > Date.now()) {
+        this.scheduleTokenExpiring(); // woke early from a clamped wait
+        return;
+      }
+      this.emit('tokenExpiring', { expiresAt, secondsLeft: Math.max(0, Math.round((expiresAt - Date.now()) / 1000)) });
+    }, delay);
+  }
+
+  // ------------------------------------------------------------ network quality
+
+  /** networkQuality sampling runs while someone listens and the session is connected. */
+  private syncNetworkWatch(): void {
+    this.networkWatch.set(!this.closedByUs && this.state === 'connected' && this.listenerCount('networkQuality') > 0);
+  }
+
+  /** Each live media transport's statistics, keyed by transport so a new one starts fresh. */
+  private async transportStats(): Promise<Map<string, Iterable<Record<string, unknown>>>> {
+    const out = new Map<string, Iterable<Record<string, unknown>>>();
+    for (const transport of [this.sendTransport, this.recvTransport]) {
+      if (!transport || transport.closed) continue;
+      const report = await transport.getStats();
+      out.set(transport.id, report.values() as Iterable<Record<string, unknown>>);
+    }
+    return out;
+  }
+
   // -------------------------------------------------------------------- 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'));
+        reject(new RpcError('not-connected', 'socket is not open'));
         return;
       }
       const id = this.nextId++;
       const timer = setTimeout(() => {
         this.pending.delete(id);
-        reject(new Error(`${method} timed out`));
+        reject(new RpcError('timeout', `${method} timed out`));
       }, RPC_TIMEOUT_MS);
       this.pending.set(id, { resolve, reject, timer });
       this.ws.send(JSON.stringify({ id, method, params }));
@@ -697,8 +1031,8 @@ export class StreamClient {
       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'));
+        const e = msg.error as { code?: string; message?: string; data?: unknown } | undefined;
+        p.reject(new RpcError(e?.code ?? 'error', e?.message ?? 'unknown', e?.data));
       }
       return;
     }
@@ -717,16 +1051,24 @@ export class StreamClient {
         this.preferredLayers.delete(producerId);
         this.receiveQualities.delete(producerId);
         this.remoteVideoLayers.delete(producerId);
+        this.skippedVideos.delete(producerId);
         const consumer = this.consumers.get(producerId);
         if (!consumer) break; // never consumed it, or already cleaned up
+        this.videoSlots.delete(producerId);
         consumer.close();
         this.consumers.delete(producerId);
         this.remoteSources.delete(producerId);
+        this.remoteInfo.delete(producerId);
         this.emit('trackEnded', { producerId, identity });
+        // A video slot opened under the fan-out limit: the oldest video left
+        // waiting takes it.
+        if (consumer.kind === 'video') void this.consumeSkipped().catch((err) => this.emit('error', err as Error));
         break;
       }
       case 'producerPaused': {
         const p = data as { producerId: string; identity: string; kind: 'audio' | 'video'; paused: boolean };
+        const info = this.remoteInfo.get(p.producerId);
+        if (info) info.paused = Boolean(p.paused);
         this.emit('trackMuted', {
           identity: p.identity,
           kind: p.kind,
@@ -736,26 +1078,40 @@ export class StreamClient {
         });
         break;
       }
-      case 'participantJoined':
-        this.emit('participantJoined', data as ParticipantInfo);
+      case 'participantJoined': {
+        const p = data as ParticipantInfo;
+        // A reconnecting participant joins again: replace, never duplicate.
+        this.updateRoster((list) => [...list.filter((q) => q.identity !== p.identity), p]);
+        this.emit('participantJoined', p);
         break;
+      }
       case 'participantMuted': {
         const wire = data as { identity: string; kind?: 'audio' | 'video' | ''; muted?: boolean; paused?: boolean };
         const e = { identity: wire.identity, kind: wire.kind, paused: wire.paused ?? wire.muted ?? false };
-        if (this.joinResult) this.joinResult.participants = this.joinResult.participants.map((p) =>
+        this.updateRoster((list) => list.map((p) =>
           p.identity !== e.identity ? p : { ...p,
             ...(!e.kind || e.kind === 'audio' ? { muted: e.paused } : {}),
             ...(!e.kind || e.kind === 'video' ? { videoBlocked: e.paused } : {}),
-          });
+          }));
         this.emit('participantMuted', e);
         break;
       }
-      case 'participantLeft':
-        this.emit('participantLeft', data as { identity: string; reason?: string });
+      case 'participantUpdated': {
+        const e = data as { identity: string; metadata?: unknown };
+        this.updateRoster((list) => list.map((p) => (p.identity !== e.identity ? p : { ...p, metadata: e.metadata })));
+        this.emit('participantUpdated', { identity: e.identity, metadata: e.metadata ?? null });
+        break;
+      }
+      case 'participantLeft': {
+        const e = data as { identity: string; reason?: string };
+        this.updateRoster((list) => list.filter((p) => p.identity !== e.identity));
+        this.emit('participantLeft', e);
         break;
+      }
       case 'roleChanged': {
         const e = data as { identity: string; role: Role };
         if (e.identity === this.joinResult?.identity) this.joinResult.role = e.role;
+        this.updateRoster((list) => list.map((p) => (p.identity !== e.identity ? p : { ...p, role: e.role })));
         this.emit('roleChanged', e);
         // Demoted: the server has already closed our producers. Release the
         // camera and microphone too, instead of capturing for nobody.
@@ -766,9 +1122,13 @@ export class StreamClient {
         break;
       }
       case 'handRaised':
-      case 'handLowered':
+      case 'handLowered': {
+        const e = data as { identity: string; handRaised: boolean; metadata?: Record<string, unknown> };
+        this.updateRoster((list) => list.map((p) => (p.identity !== e.identity ? p
+          : { ...p, handRaised: Boolean(e.handRaised), ...(e.handRaised ? { handMetadata: e.metadata } : { handMetadata: undefined }) })));
         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
@@ -781,18 +1141,30 @@ export class StreamClient {
         this.emit('forceMuted', e);
         break;
       }
+      case 'claimChanged': {
+        const e = data as { key: string; identity?: string | null; state: ClaimChange['state']; reason?: string };
+        this.applyClaim(e);
+        this.emit('claimChanged', { key: e.key, identity: e.identity || null, state: e.state, reason: e.reason ?? '' });
+        break;
+      }
+      case 'roomMetadataChanged': {
+        const e = data as { metadata?: unknown; by?: string };
+        if (this.joinResult) this.joinResult.metadata = e.metadata;
+        this.emit('roomMetadataChanged', { metadata: e.metadata ?? null, ...(e.by ? { by: e.by } : {}) });
+        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;
+        const e = data as { token?: string; role?: Role; expiresAt?: number };
+        if (e.token) this.setToken(e.token, typeof e.expiresAt === 'number' && e.expiresAt > 0 ? e.expiresAt * 1000 : null);
         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;
+        if (e.token) this.setToken(e.token, null);
         this.emit('mustReconnect', e);
         if (e.retry) {
           this.teardownMedia();
@@ -808,16 +1180,22 @@ export class StreamClient {
       case 'usageLimit':
         this.emit('usageLimit', d as never);
         break;
+      case 'walletLow': {
+        const e = data as { remainingSeconds?: unknown; cleared?: unknown };
+        const remainingSeconds = typeof e?.remainingSeconds === 'number' && Number.isFinite(e.remainingSeconds) ? e.remainingSeconds : 0;
+        this.emit('walletLow', e?.cleared === true ? { remainingSeconds, cleared: true } : { remainingSeconds });
+        break;
+      }
       case 'roomClosed':
         this.closedByUs = true;
         this.emit('roomClosed', d as never);
-        this.emit('closed', 'room-closed');
+        this.finish('room-closed');
         this.close();
         break;
       case 'kicked':
         this.closedByUs = true;
         this.emit('kicked', d as never);
-        this.emit('closed', 'kicked');
+        this.finish('kicked');
         this.close();
         break;
       case 'message':
@@ -837,6 +1215,23 @@ export class StreamClient {
     }
   }
 
+  /** Change the roster the join result holds; a new array each time, so a renderer sees the change. */
+  private updateRoster(change: (list: ParticipantInfo[]) => ParticipantInfo[]): void {
+    if (this.joinResult) this.joinResult.participants = change(this.joinResult.participants ?? []);
+  }
+
+  /** Keep the join result's slots current: claims held or away, and the moderator's locks. */
+  private applyClaim(e: { key: string; identity?: string | null; state: string }): void {
+    const join = this.joinResult;
+    if (!join) return;
+    const claims = (join.claims ?? []).filter((c) => c.key !== e.key);
+    let blocked = (join.blockedSlots ?? []).filter((key) => key !== e.key);
+    if ((e.state === 'held' || e.state === 'away') && e.identity) claims.push({ key: e.key, identity: e.identity, state: e.state });
+    if (e.state === 'blocked') blocked = [...blocked, e.key];
+    join.claims = claims;
+    join.blockedSlots = blocked;
+  }
+
   // ------------------------------------------------------------------ media
 
   private ensureSendTransport(): Promise<Transport> {
@@ -849,7 +1244,7 @@ export class StreamClient {
   }
 
   private async createSendTransport(): Promise<Transport> {
-    if (!this.device) throw new Error('not connected');
+    if (!this.device) throw new RpcError('not-connected', 'not connected');
 
     const params = (await this.rpc('createTransport', { direction: 'send' })) as TransportOptions;
     const transport = this.device.createSendTransport({
@@ -863,7 +1258,10 @@ export class StreamClient {
         .catch(fail);
     });
     transport.on('produce', ({ kind, rtpParameters, appData }, ok, fail) => {
-      this.rpc('produce', { transportId: transport.id, kind, rtpParameters, appData, source: appData.source, videoLayers: appData.videoLayers })
+      this.rpc('produce', {
+        transportId: transport.id, kind, rtpParameters: declareAudioQuality(rtpParameters, appData),
+        appData, source: appData.source, videoLayers: appData.videoLayers,
+      })
         .then((res) => ok({ id: (res as { producerId: string }).producerId }))
         .catch(fail);
     });
@@ -882,7 +1280,7 @@ export class StreamClient {
   }
 
   private async createRecvTransport(): Promise<Transport> {
-    if (!this.device) throw new Error('not connected');
+    if (!this.device) throw new RpcError('not-connected', 'not connected');
 
     const params = (await this.rpc('createTransport', { direction: 'recv' })) as TransportOptions;
     const transport = this.device.createRecvTransport({
@@ -912,11 +1310,24 @@ export class StreamClient {
    * kept for a reconnect's republish.
    */
   async publish(stream: MediaStream, constraints?: MediaStreamConstraints, options?: PublishOptions): Promise<void> {
+    // A kind the project switched off is refused here, before anything is
+    // produced, with the code the controller would answer with.
+    const permissions = this.mediaPermissions;
+    if (!permissions.audio && stream.getAudioTracks().length > 0) {
+      throw new RpcError('media-disabled', 'audio is switched off for this project');
+    }
+    if (!permissions.video && stream.getVideoTracks().length > 0) {
+      throw new RpcError('media-disabled', 'video is switched off for this project');
+    }
+    await this.publishStream(stream, constraints, options);
+  }
+
+  private async publishStream(stream: MediaStream, constraints?: MediaStreamConstraints, options?: PublishOptions): Promise<void> {
     const generation = this.publishGeneration;
     const transport = await this.ensureSendTransport();
     // unpublish() ran first: this publish is over before it began, and must
     // leave nothing behind that a reconnect would publish again.
-    if (generation !== this.publishGeneration) throw new Error(unpublishedWhile('stream'));
+    if (generation !== this.publishGeneration) throw unpublishedWhile('stream');
     this.localStream = stream;
     this.wasPublishing = true;
     if (constraints) this.publishConstraints = constraints;
@@ -924,39 +1335,144 @@ export class StreamClient {
       this.publishOptions = { ...options };
       this.frameRateFallback = false;
       this.frameRateLowSamples = 0;
+      this.audioCapReported = false;
+      this.sizeCapReported = false;
     }
+    // Only a reconnect's republish gets here with a kind switched off since:
+    // what is still allowed goes out, and the rest is reported.
+    const permissions = this.mediaPermissions;
 
     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' },
-      });
-      await this.keepProducer(producer, generation, 'microphone');
-      // A microphone handed over switched off, or muted before a reconnect.
-      await this.pauseOnServer(producer);
+    if (audio && !permissions.audio) {
+      this.emit('error', new RpcError('media-disabled', 'audio is switched off for this project; the microphone is not published'));
+    } else if (audio) {
+      await this.micTask(() => this.produceMic(transport, this.localStream?.getAudioTracks()[0] ?? audio, generation));
     }
 
     const video = stream.getVideoTracks()[0];
-    if (video) {
+    if (video && !permissions.video) {
+      this.emit('error', new RpcError('media-disabled', 'video is switched off for this project; the camera is not published'));
+    } else if (video) {
       // The track is read when the camera's turn comes: one handed to
       // replaceVideoTrack while this publish was under way is the one to send.
       await this.cameraTask(() => this.produceCamera(transport, this.localStream?.getVideoTracks()[0] ?? video, generation));
     }
   }
 
+  // ------------------------------------------------------------ audio quality
+
+  /**
+   * The microphone's audio quality: what it is being sent at while
+   * published, else what the next publish will use, after the project's limit.
+   */
+  get audioQuality(): AudioQuality {
+    if (this.micProducer()) return this.micQuality;
+    return this.publishOptions.audioQuality === 'hd' && this.mediaPermissions.audioQualityMax === 'hd' ? 'hd' : 'std';
+  }
+
+  /**
+   * Switch the microphone between standard (mono, up to 64 kbps) and HD
+   * (stereo, up to 128 kbps) while live. The codec settings are fixed per
+   * producer, so the microphone's producer is replaced: listeners hear a gap
+   * of a fraction of a second, and a microphone that is off stays off. Rejects
+   * with `audio-quality-not-allowed` when the project allows standard audio
+   * only. Resolves to the quality in use.
+   */
+  async setAudioQuality(quality: AudioQuality): Promise<AudioQuality> {
+    if (quality !== 'std' && quality !== 'hd') throw new RangeError("setAudioQuality: expected 'std' or 'hd'");
+    if (quality === 'hd' && this.mediaPermissions.audioQualityMax !== 'hd') {
+      throw new RpcError('audio-quality-not-allowed', 'HD audio is not enabled for this project');
+    }
+    this.publishOptions = { ...this.publishOptions, audioQuality: quality };
+    this.audioCapReported = false;
+    await this.micTask(async () => {
+      const current = this.micProducer();
+      const track = current?.track;
+      if (!current || !track || track.readyState !== 'live' || this.micQuality === quality) return;
+      await this.reproduceMic(current, track);
+    });
+    return this.audioQuality;
+  }
+
+  private micProducer(): Producer | undefined {
+    for (const p of this.producers.values()) {
+      if (p.kind === 'audio' && (p.appData as { source?: string }).source === 'mic') return p;
+    }
+    return undefined;
+  }
+
+  private micTask<T>(task: () => Promise<T>): Promise<T> {
+    const run = this.micQueue.then(task, task);
+    this.micQueue = run.catch(() => undefined);
+    return run;
+  }
+
+  /** The audio quality to send: the request, capped to the project's, with the cap reported once. */
+  private audioQualityFor(): AudioQuality {
+    if (this.publishOptions.audioQuality !== 'hd') return 'std';
+    if (this.mediaPermissions.audioQualityMax === 'hd') return 'hd';
+    if (!this.audioCapReported) {
+      this.audioCapReported = true;
+      this.emit('error', new RpcError('audio-quality-not-allowed', 'HD audio is not enabled for this project; publishing standard audio'));
+    }
+    return 'std';
+  }
+
+  /**
+   * Produce the microphone at the audio quality in force. A track handed over
+   * switched off (or paused before a reconnect or a quality change) starts
+   * paused, on both ends.
+   */
+  private async produceMic(transport: Transport, track: MediaStreamTrack, generation: number): Promise<Producer> {
+    if (generation !== this.publishGeneration) throw unpublishedWhile('microphone');
+    const quality = this.audioQualityFor();
+    const settings = AUDIO_SETTINGS[quality];
+    const producer = await transport.produce({
+      track,
+      // Keep the track alive when the producer closes: a reconnect closes
+      // every producer, and a stopped track cannot be republished.
+      stopTracks: false,
+      // The answer's maxaveragebitrate sets the encoder's rate and the
+      // sender's maxBitrate holds it there: standard must stay at or under
+      // 64 kbps, which is what the server measures to bill it, so its sender
+      // is held a little under the declared rate (Opus VBR overshoots).
+      encodings: [{ maxBitrate: settings.senderMaxBitrate }],
+      codecOptions: { opusStereo: settings.stereo, opusDtx: true, opusFec: true, opusMaxAverageBitrate: settings.maxBitrate },
+      appData: { source: 'mic', audioQuality: quality },
+    });
+    await this.keepProducer(producer, generation, 'microphone');
+    this.micQuality = quality;
+    // A microphone handed over switched off, or muted before a reconnect.
+    await this.pauseOnServer(producer);
+    return producer;
+  }
+
+  /** Close the microphone producer and produce its track again at the quality now in force. */
+  private async reproduceMic(current: Producer, track: MediaStreamTrack): Promise<Producer> {
+    const generation = this.publishGeneration;
+    current.close();
+    this.producers.delete(current.id);
+    // The server allows one producer per source: the old one goes first.
+    await this.rpc('closeProducer', { producerId: current.id }).catch(() => undefined);
+    return this.produceMic(await this.ensureSendTransport(), track, generation);
+  }
+
   /** What this project may publish. Known once joined; 1080p before that. */
   get videoPolicy(): VideoPolicy {
     return this.joinResult?.video ?? DEFAULT_VIDEO_POLICY;
   }
 
-  /** The quality video is being sent at, after the project's limit. */
+  /**
+   * The quality video is being sent at, after the project's limit: at 60 fps
+   * the largest size the project allows at 60, otherwise its 30 fps maximum.
+   */
   get videoQuality(): VideoQuality {
-    return allowedQuality(this.publishOptions.quality, this.videoPolicy);
+    return qualityAt(this.publishOptions.quality, this.videoFrameRate, this.mediaPermissions);
+  }
+
+  /** The camera's frame rate: what it is being sent at while published, else 30 until a publish decides. */
+  get videoFrameRate(): 30 | 60 {
+    return this.cameraProducer() ? this.cameraFrameRate : 30;
   }
 
   /**
@@ -967,6 +1483,7 @@ export class StreamClient {
    */
   async setVideoQuality(quality: VideoQuality): Promise<VideoQuality> {
     this.publishOptions = { ...this.publishOptions, quality };
+    this.sizeCapReported = false;
     await this.cameraTask(async () => {
       const current = this.cameraProducer();
       const track = current?.track;
@@ -976,12 +1493,24 @@ export class StreamClient {
     return this.videoQuality;
   }
 
-  /** Change the camera frame rate without stopping screen, microphone or music. */
+  /**
+   * Change the camera frame rate without stopping screen, microphone or music.
+   * 60 where the project allows none stays at 30 and warns on `error` with
+   * `frame-rate-not-allowed`, without touching the camera; a camera or device
+   * that cannot keep 60 up falls back with `frame-rate-fallback`. Resolves to
+   * the frame rate used.
+   */
   async setVideoFrameRate(frameRate: 30 | 60): Promise<30 | 60> {
     if (frameRate !== 30 && frameRate !== 60) throw new RangeError('setVideoFrameRate: expected 30 or 60');
     this.publishOptions = { ...this.publishOptions, frameRate };
     this.frameRateFallback = false;
     this.frameRateLowSamples = 0;
+    this.sizeCapReported = false;
+    if (frameRate === 60 && !this.allows60()) {
+      this.frameRateFallback = true;
+      this.emit('error', new RpcError('frame-rate-not-allowed', '60 fps is not enabled for this project; publishing at 30 fps'));
+      return this.videoFrameRate;
+    }
     await this.cameraTask(async () => {
       const current = this.cameraProducer();
       const track = current?.track;
@@ -990,7 +1519,27 @@ export class StreamClient {
       catch { /* Existing capture settings decide whether 60 fps is possible. */ }
       await this.reproduceCamera(current, track);
     });
-    return this.cameraProducer() ? this.cameraFrameRate : this.videoPolicy.maxFrameRate === 30 ? 30 : frameRate;
+    return this.cameraProducer() ? this.cameraFrameRate : this.allows60() ? frameRate : 30;
+  }
+
+  /** Whether this project allows any 60 fps mode. */
+  private allows60(): boolean {
+    const permissions = this.mediaPermissions;
+    return permissions.maxFrameRate === 60 && permissions.maxVideoQuality60 !== null;
+  }
+
+  /**
+   * The quality to send at a frame rate. A request above what 60 fps allows
+   * is sent at the largest size it does allow, and said so once.
+   */
+  private cameraQuality(frameRate: 30 | 60): VideoQuality {
+    const permissions = this.mediaPermissions;
+    if (frameRate === 60 && !this.sizeCapReported && above60fpsCap(this.publishOptions.quality, permissions)) {
+      this.sizeCapReported = true;
+      this.emit('error', new RpcError('video-quality-not-allowed',
+        `${this.publishOptions.quality} at 60 fps is not enabled for this project; publishing ${permissions.maxVideoQuality60} at 60 fps`));
+    }
+    return qualityAt(this.publishOptions.quality, frameRate, permissions);
   }
 
   /**
@@ -1033,7 +1582,8 @@ export class StreamClient {
       const paused = current.paused;
       try {
         const { width = 0, height = 0 } = track.getSettings();
-        const next = videoEncodings(width, height, this.videoQuality, this.layerCount(), this.frameRateFor(track));
+        const frameRate = this.frameRateFor(track);
+        const next = videoEncodings(width, height, this.cameraQuality(frameRate), this.layerCount(), frameRate);
         const previousSize = current.track?.getSettings();
         if (this.cameraEncodings && sameLayout(this.cameraEncodings, next) &&
             previousSize?.width === width && previousSize?.height === height) {
@@ -1222,7 +1772,7 @@ export class StreamClient {
     generation: number,
     paused = !track.enabled,
   ): Promise<Producer> {
-    if (generation !== this.publishGeneration) throw new Error(unpublishedWhile('camera'));
+    if (generation !== this.publishGeneration) throw unpublishedWhile('camera');
     // mediasoup-client starts a producer paused exactly when its track is
     // off. Setting the track to the camera's state first makes the producer
     // start in it, and a camera that is off never sends a frame of the new
@@ -1233,8 +1783,9 @@ export class StreamClient {
     // the device, so the browser sends every layer asked for (see
     // videoEncodings).
     const { width = 0, height = 0 } = track.getSettings();
-    const quality = this.videoQuality;
+    // The frame rate first: the size the project allows depends on it.
     this.cameraFrameRate = this.frameRateFor(track);
+    const quality = this.cameraQuality(this.cameraFrameRate);
     const encodings = videoEncodings(width, height, quality, this.layerCount(), this.cameraFrameRate);
     let codecs: RtpCodecCapability[] | undefined;
     try {
@@ -1283,7 +1834,7 @@ export class StreamClient {
     if (generation !== this.publishGeneration) {
       producer.close();
       await this.rpc('closeProducer', { producerId: producer.id }).catch(() => undefined);
-      throw new Error(unpublishedWhile(what));
+      throw unpublishedWhile(what);
     }
     this.producers.set(producer.id, producer);
   }
@@ -1327,7 +1878,7 @@ export class StreamClient {
   /** A forced H.264 that could not be used is the app's to hear about; 'auto' just notes it, once. */
   private reportCodecFallback(message: string): void {
     if (normalizeCodec(this.publishOptions.codec) === 'h264') {
-      this.emit('error', new Error(message));
+      this.emit('error', new RpcError('codec-fallback', message));
     } else if (!this.codecFallbackLogged) {
       this.codecFallbackLogged = true;
       console.warn(`[voltkit-rtc] ${message}`);
@@ -1381,7 +1932,7 @@ export class StreamClient {
 
     if (!live) {
       if (!this.publishConstraints) {
-        this.emit('error', new Error('cannot restore the broadcast: the devices are gone'));
+        this.emit('error', new RpcError('devices-gone', 'cannot restore the broadcast: the devices are gone'));
         return;
       }
       const ended = stream;
@@ -1401,7 +1952,7 @@ export class StreamClient {
     }
     if (!stream) return;
 
-    await this.publish(stream);
+    await this.publishStream(stream);
   }
 
   // ------------------------------------------------------------- screen sharing
@@ -1409,6 +1960,7 @@ export class StreamClient {
   /** Publish a screen beside the camera. Call from a click so capture permission can open. */
   async publishScreen(options: ScreenPublishOptions = {}): Promise<MediaStream> {
     if (this.joinResult?.role !== 'host' && this.joinResult?.role !== 'cohost') throw new RpcError('forbidden', 'only hosts and cohosts can share a screen');
+    if (!this.mediaPermissions.video) throw new RpcError('media-disabled', 'video is switched off for this project');
     if (this.screenStream || this.screenPending) throw new RpcError('screen-share-active', 'a screen share is already active');
     if (options.mode !== undefined && options.mode !== 'detail' && options.mode !== 'motion') throw new TypeError('publishScreen: mode must be detail or motion');
     const mode = options.mode ?? 'detail';
@@ -1425,7 +1977,7 @@ export class StreamClient {
       });
       const video = stream.getVideoTracks()[0];
       if (!video || video.readyState !== 'live') throw new RpcError('screen-share-no-video', 'screen capture did not provide a live video track');
-      if (generation !== this.screenGeneration || this.closedByUs) throw new Error(unpublishedWhile('screen'));
+      if (generation !== this.screenGeneration || this.closedByUs) throw unpublishedWhile('screen');
       this.screenStream = stream;
       this.screenMode = mode;
       this.screenAudioEnabled = options.audio !== false;
@@ -1434,7 +1986,7 @@ export class StreamClient {
       this.screenEndedListener = onEnded;
       video.addEventListener('ended', onEnded, { once: true });
       await this.restoreScreen();
-      if (generation !== this.screenGeneration || video.readyState !== 'live') throw new Error(unpublishedWhile('screen'));
+      if (generation !== this.screenGeneration || video.readyState !== 'live') throw unpublishedWhile('screen');
       this.screenStarted = true;
       this.wasPublishing = true;
       this.emit('screenShareStarted', { stream, mode });
@@ -1487,14 +2039,14 @@ export class StreamClient {
     const { width = 0, height = 0 } = video.getSettings();
     const encodings = screenEncodings(width, height, this.screenMode);
     // A project's explicit safety restriction also applies to screen video.
-    const cap = topLayerSize(width, height, this.videoPolicy.maxQuality);
+    const cap = topLayerSize(width, height, this.mediaPermissions.maxVideoQuality);
     const screenScale = encodings.at(-1)!.scaleResolutionDownBy;
     if (cap.scale > screenScale) encodings.forEach((e) => { e.scaleResolutionDownBy *= cap.scale / screenScale; });
     const keep = async (producer: Producer) => {
       if (generation !== this.screenGeneration || publishing !== this.publishGeneration || video.readyState !== 'live') {
         producer.close();
         await this.rpc('closeProducer', { producerId: producer.id }).catch(() => undefined);
-        throw new Error(unpublishedWhile('screen'));
+        throw unpublishedWhile('screen');
       }
       this.producers.set(producer.id, producer);
       this.screenProducerIds.add(producer.id);
@@ -1505,7 +2057,12 @@ export class StreamClient {
       codecOptions: { videoGoogleStartBitrate: VIDEO_START_BITRATE_KBPS },
       appData: { source: 'screen', videoLayers: describeVideoLayers(width, height, encodings) },
     }));
-    const audio = stream.getAudioTracks().find((track) => track.readyState === 'live');
+    let audio = stream.getAudioTracks().find((track) => track.readyState === 'live');
+    if (audio && this.screenAudioEnabled && !this.mediaPermissions.audio) {
+      // The screen goes out; its sound cannot in a project without audio.
+      this.emit('error', new RpcError('media-disabled', 'audio is switched off for this project; the screen is shared without its sound'));
+      audio = undefined;
+    }
     if (audio && this.screenAudioEnabled && generation === this.screenGeneration) await keep(await transport.produce({
       track: audio, stopTracks: false,
       codecOptions: { opusStereo: true, opusDtx: false, opusFec: true, opusMaxAverageBitrate: 128000 },
@@ -1513,12 +2070,24 @@ export class StreamClient {
     }));
   }
 
+  /**
+   * 60 only when asked for, allowed by the project, captured at 50 or more and
+   * not fallen back from. The project's refusal and the camera's are reported
+   * apart, each once: `frame-rate-not-allowed` is the server's own code for a
+   * 60 fps producer the project does not allow, `frame-rate-fallback` means
+   * the camera or device cannot provide it.
+   */
   private frameRateFor(track: MediaStreamTrack): 30 | 60 {
     if (this.publishOptions.frameRate !== 60 || this.frameRateFallback) return 30;
+    if (!this.allows60()) {
+      this.frameRateFallback = true;
+      this.emit('error', new RpcError('frame-rate-not-allowed', '60 fps is not enabled for this project; publishing at 30 fps'));
+      return 30;
+    }
     const captured = track.getSettings().frameRate;
-    if (this.videoPolicy.maxFrameRate === 30 || (typeof captured === 'number' && captured < 50)) {
+    if (typeof captured === 'number' && captured < 50) {
       this.frameRateFallback = true;
-      this.emit('error', new RpcError('frame-rate-fallback', '60 fps is unavailable from this camera or project; publishing at 30 fps'));
+      this.emit('error', new RpcError('frame-rate-fallback', '60 fps is unavailable from this camera; publishing at 30 fps'));
       return 30;
     }
     return 60;
@@ -1563,6 +2132,7 @@ export class StreamClient {
    * the user has not interacted with.
    */
   async publishMusic(input: MusicInput, options?: MusicOptions): Promise<void> {
+    if (!this.mediaPermissions.audio) throw new RpcError('media-disabled', 'audio is switched off for this project');
     const generation = this.publishGeneration;
     if (this.music) await this.stopMusic();
     const music = new MusicSource(input, options);
@@ -1571,7 +2141,7 @@ export class StreamClient {
       // Checked again here: an unpublish() after the producer was kept has
       // already closed it, and the music must not be remembered for a
       // reconnect to publish again.
-      if (generation !== this.publishGeneration) throw new Error(unpublishedWhile('music'));
+      if (generation !== this.publishGeneration) throw unpublishedWhile('music');
     } catch (err) {
       music.close();
       throw err;
@@ -1583,7 +2153,7 @@ export class StreamClient {
 
   private async produceMusic(music: MusicSource, generation: number): Promise<void> {
     const transport = await this.ensureSendTransport();
-    if (generation !== this.publishGeneration) throw new Error(unpublishedWhile('music'));
+    if (generation !== this.publishGeneration) throw unpublishedWhile('music');
     const producer = await transport.produce({
       track: music.track,
       stopTracks: false,
@@ -1646,12 +2216,46 @@ export class StreamClient {
   }
 
   private async consume(remote: RemoteProducer): Promise<void> {
-    if (!this.device) throw new Error('not connected');
+    if (!this.device) throw new RpcError('not-connected', '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;
+    // A wallet session receives at most media.fanout.maxVideoSubscriptions
+    // videos; the media node refuses the next. Wait for a slot instead of
+    // asking for a refusal, and say so once per video.
+    if (remote.kind === 'video' && !this.videoSlots.has(remote.producerId)) {
+      const limit = this.mediaPermissions.maxVideoSubscriptions;
+      if (limit !== null && this.videoSlots.size >= limit) {
+        if (!this.skippedVideos.has(remote.producerId)) {
+          this.skippedVideos.set(remote.producerId, remote);
+          this.emit('error', new RpcError('video-subscription-limit',
+            `already receiving ${limit} videos, the most this project allows; ${remote.identity}'s video waits for one to end`));
+        }
+        return;
+      }
+      this.videoSlots.add(remote.producerId);
+    }
+    try {
+      await this.consumeNow(remote);
+    } catch (err) {
+      if (!this.consumers.has(remote.producerId)) this.videoSlots.delete(remote.producerId);
+      throw err;
+    }
+  }
 
+  /** The oldest videos left waiting at the fan-out limit take the slots that opened. */
+  private async consumeSkipped(): Promise<void> {
+    for (const [producerId, remote] of this.skippedVideos) {
+      const limit = this.mediaPermissions.maxVideoSubscriptions;
+      if (limit !== null && this.videoSlots.size >= limit) return;
+      this.skippedVideos.delete(producerId);
+      await this.consume(remote);
+    }
+  }
+
+  private async consumeNow(remote: RemoteProducer): Promise<void> {
+    if (!this.device) throw new RpcError('not-connected', 'not connected');
     const transport = await this.ensureRecvTransport();
     const params = (await this.rpc('consume', {
       transportId: transport.id,
@@ -1683,6 +2287,7 @@ export class StreamClient {
     const kind = consumer.kind as 'audio' | 'video';
     const source = remote.source ?? defaultSource(kind);
     this.remoteSources.set(remote.producerId, source);
+    this.remoteInfo.set(remote.producerId, { identity: remote.identity, kind, paused: Boolean(remote.paused) });
     this.emit('track', {
       identity: remote.identity,
       kind,
@@ -1822,6 +2427,67 @@ export class StreamClient {
   endRoom(): Promise<unknown> { return this.rpc('endRoom'); }
   getRoomState(): Promise<unknown> { return this.rpc('getRoomState'); }
 
+  // ------------------------------------------------------- slots and metadata
+  //
+  // A slot is a named thing in the room that at most one participant holds at
+  // a time: a seat on a board, a guest spot. Keys are yours; the server never
+  // learns that `seat-13` is a seat. `info.claims` and `info.blockedSlots`
+  // seed a board on join and follow claimChanged.
+
+  /**
+   * Take a slot, or (moderators) grant one by naming `identity`. One claim
+   * per identity: a second moves you. Refused with `slot-taken` when someone
+   * holds it (away included) and `slot-blocked` when a moderator locked it.
+   * Claim first, then promote: if the slot has gone, nothing has happened yet.
+   */
+  async claim(key: string, identity?: string): Promise<void> {
+    await this.rpc('claim', identity ? { key, identity } : { key });
+  }
+
+  /** Give up a slot. Moderators may release anyone's. */
+  async release(key: string): Promise<void> {
+    await this.rpc('release', { key });
+  }
+
+  /**
+   * Lock a slot so nobody may claim it. Moderators only. Refused with
+   * `slot-occupied` while someone holds it: taking a seat from a person using
+   * it is two deliberate acts, not a side effect of one tap.
+   */
+  async blockSlot(key: string): Promise<void> {
+    await this.rpc('blockSlot', { key });
+  }
+
+  /** Unlock a slot. Moderators only. */
+  async unblockSlot(key: string): Promise<void> {
+    await this.rpc('unblockSlot', { key });
+  }
+
+  /** Replace your own display metadata; the room hears it as participantUpdated. */
+  async setMetadata(metadata: Record<string, unknown>): Promise<void> {
+    await this.rpc('setMetadata', { metadata });
+  }
+
+  /**
+   * Change room-scoped metadata. Moderators only, and persisted, so a client
+   * joining later reads it from `info.metadata`. Merges one key deep by
+   * default (a null value deletes its key); `replace` swaps the whole object.
+   * `requireFree` names slots that must be unheld for the change to apply,
+   * checked and applied together: the refusal (`slot-occupied`) names the
+   * offending keys in `RpcError.data.slots`. Resolves to the metadata now.
+   */
+  async setRoomMetadata(
+    metadata: Record<string, unknown>,
+    options: { replace?: boolean; requireFree?: string[] } = {},
+  ): Promise<unknown> {
+    const res = (await this.rpc('setRoomMetadata', {
+      metadata,
+      ...(options.replace ? { replace: true } : {}),
+      ...(options.requireFree ? { requireFree: options.requireFree } : {}),
+    })) as { metadata?: unknown } | undefined;
+    return res?.metadata ?? null;
+  }
+
   // ------------------------------------------------------------------- chat
   //
   // The room's chat rides this same socket. Someone on a chat-only socket