@voltkit-rtc/client 0.6.0 → 0.7.0

package/dist/esm/index.js

@@ -7,6 +7,10 @@ import { CameraRecording } from './recording.js';
  * setup, consumer resume ordering and reconnection, each slightly wrong.
  */
 import { Device } from 'mediasoup-client';
+import { isTerminalError, RpcError } from './errors.js';
+import { above60fpsCap, AUDIO_SETTINGS, qualityAt, resolvePermissions, } from './media-permissions.js';
+import { NetworkQualityWatch } from './network.js';
+import { socketUrl, TOKEN_EXPIRING_LEAD_MS, tokenExpiresAt } from './token.js';
 import { chooseCodec, currentEnv, defaultLayerCount, findCodec, h264HardwareEncode, isAppleMobile, isPhoneOrTablet, normalizeCodec, } from './device.js';
 import { MusicSource } from './music.js';
 import { allowedQuality, DEFAULT_VIDEO_POLICY, sameLayout, describeVideoLayers, receiveSpatialLayer, screenEncodings, topLayerSize, videoEncodings, } from './quality.js';
@@ -15,36 +19,29 @@ export { CameraRecording, RecordingUploader, RecordingError } from './recording.
 export { BroadcastPublisher, WhipError, whipEnd, whipOffer } from './broadcast.js';
 export { AudioMixer, MusicSource } from './music.js';
 export { ChatClient, ChatRpcError } from './chat.js';
+export { RpcError, ERROR_CODES, errorInfo, isTerminalError } from './errors.js';
+export { AUDIO_QUALITIES, AUDIO_SETTINGS, DEFAULT_MEDIA_PERMISSIONS, resolvePermissions } from './media-permissions.js';
+export { NETWORK_QUALITY_INTERVAL_MS, NETWORK_QUALITY_LEVELS, networkLevel } from './network.js';
+export { TOKEN_EXPIRING_LEAD_MS, tokenExpiresAt } from './token.js';
 export { allowedQuality, layerBitrate, videoEncodings, VIDEO_QUALITIES } from './quality.js';
+/** 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']);
 const defaultSource = (kind) => (kind === 'audio' ? 'mic' : 'camera');
-/** An error returned by the server, carrying its machine-readable code. */
-export class RpcError extends Error {
-    code;
-    constructor(code, message) {
-        super(`${code}: ${message}`);
-        this.code = code;
-        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 = {
+    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));
 const RPC_TIMEOUT_MS = 15_000;
 const MAX_RECONNECT_ATTEMPTS = 8;
 /** Server close code meaning "another socket took over this identity". */
@@ -59,9 +56,29 @@ const isLayer = (value) => Number.isInteger(value) && value >= 0;
  */
 const VIDEO_START_BITRATE_KBPS = 2000;
 /** Why a publish gave up: unpublish() ran while it was under way, and unpublish wins. */
-const unpublishedWhile = (what) => `the ${what} was unpublished while it was being published`;
+const unpublishedWhile = (what) => 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, appData) {
+    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 {
     wsUrl;
+    options;
     ws = null;
     device = null;
     sendTransport = null;
@@ -131,10 +148,31 @@ export class StreamClient {
     codecFallbackLogged = false;
     sendStatsBaseline = new Map();
     recvStatsBaseline = new Map();
-    limitWatch = new VideoLimitWatch((baseline) => this.sampleCamera(baseline), (event) => this.emit('videoLimited', event));
-    constructor(wsUrl, token) {
+    limitWatch = new VideoLimitWatch((baseline, isCurrent) => this.sampleCamera(baseline, isCurrent), (event) => this.emit('videoLimited', event), undefined, () => { this.frameRateLowSamples = 0; this.frameRateWarmupSamples = 2; });
+    /** Where the session stands; see connectionStateChanged. */
+    state = 'idle';
+    /** When the token held for reconnects expires (unix ms), and the timer that warns before it does. */
+    tokenExpiry;
+    tokenTimer = null;
+    /** Whose each received track is and whether it is switched off, by producerId. */
+    remoteInfo = new Map();
+    /** Videos left unconsumed at the fan-out limit, oldest first; consumed as others end. */
+    skippedVideos = new Map();
+    /** Producers whose video this client receives, or is about to: the fan-out count. */
+    videoSlots = new Set();
+    /** The quality the microphone producer was made with. */
+    micQuality = 'std';
+    // Changes to the microphone producer run one at a time, as the camera's do.
+    micQueue = Promise.resolve();
+    // A request the project does not allow is reported once, until it is made again.
+    audioCapReported = false;
+    sizeCapReported = false;
+    networkWatch = new NetworkQualityWatch(() => this.transportStats(), () => this.producers.size > 0, (quality) => this.emit('networkQuality', quality));
+    constructor(wsUrl, token, options = {}) {
         this.wsUrl = wsUrl;
+        this.options = options;
         this.token = token;
+        this.tokenExpiry = tokenExpiresAt(token);
     }
     on(event, fn) {
         let set = this.listeners.get(event);
@@ -143,15 +181,45 @@ export class StreamClient {
             this.listeners.set(event, set);
         }
         set.add(fn);
-        // 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);
             if (event === 'videoLimited')
                 this.syncLimitWatch();
+            if (event === 'networkQuality')
+                this.syncNetworkWatch();
         };
     }
+    /** Where the session stands: idle, connecting, connected, reconnecting or closed. */
+    get connectionState() {
+        return this.state;
+    }
+    setState(next) {
+        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. */
+    finish(reason) {
+        this.closedByUs = true;
+        this.setState('closed');
+        this.emit('closed', reason);
+    }
+    stopTimers() {
+        if (this.tokenTimer)
+            clearTimeout(this.tokenTimer);
+        this.tokenTimer = null;
+        this.networkWatch.set(false);
+    }
     listenerCount(event) {
         return this.listeners.get(event)?.size ?? 0;
     }
@@ -168,6 +236,8 @@ export class StreamClient {
     // ------------------------------------------------------------- connection
     async connect() {
         let result;
+        if (this.state === 'idle' || this.state === 'closed')
+            this.setState('connecting');
         try {
             await this.openSocket();
             result = (await this.rpc('join', { token: this.token }));
@@ -179,8 +249,11 @@ 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)
+            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.
@@ -189,6 +262,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.
         if (result.role !== 'host' && result.role !== 'cohost' && (this.wasPublishing || this.screenPending)) {
@@ -223,11 +299,17 @@ export class StreamClient {
         if (this.wasPublishing && (result.role === 'host' || result.role === 'cohost')) {
             await this.republish().catch((err) => this.emit('error', err));
         }
+        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.
+     */
     createDevice() {
-        return new Device();
+        const { handlerName } = this.options;
+        return handlerName ? new Device({ handlerName }) : new Device();
     }
     openSocket() {
         // Abandon any previous socket first. Its close handler checks identity
@@ -235,15 +317,13 @@ export class StreamClient {
         // 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());
+            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 });
             ws.addEventListener('message', (ev) => {
@@ -256,33 +336,33 @@ export class StreamClient {
                 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();
             });
         });
@@ -315,9 +395,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);
@@ -336,12 +415,11 @@ export class StreamClient {
                 }
                 catch (err) {
                     this.emit('error', err);
-                    // 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;
                     }
                 }
@@ -368,6 +446,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());
@@ -375,6 +454,7 @@ export class StreamClient {
         const ws = this.ws;
         this.ws = null;
         ws?.close(1000, 'client closed');
+        this.setState('closed');
         if (wasOpen)
             this.emit('closed', 'left');
     }
@@ -382,6 +462,9 @@ export class StreamClient {
         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();
@@ -398,22 +481,137 @@ 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() {
         return this.joinResult;
     }
+    /** Who is in the room now, this client included; kept current from the roster events. */
+    get participants() {
+        return [...(this.joinResult?.participants ?? [])];
+    }
+    /** Every track this client is receiving now. */
+    get remoteTracks() {
+        const out = [];
+        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() {
+        return resolvePermissions(this.joinResult);
+    }
+    /** How this session is billed: `legacy` (minutes) or `wallet`; null before a join or on older servers. */
+    get billingMode() {
+        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) {
+        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 }));
+                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). */
+    setToken(token, expiresAt) {
+        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.
+     */
+    scheduleTokenExpiring() {
+        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. */
+    syncNetworkWatch() {
+        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. */
+    async transportStats() {
+        const out = new Map();
+        for (const transport of [this.sendTransport, this.recvTransport]) {
+            if (!transport || transport.closed)
+                continue;
+            const report = await transport.getStats();
+            out.set(transport.id, report.values());
+        }
+        return out;
+    }
     // -------------------------------------------------------------------- rpc
     rpc(method, params = {}) {
         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 }));
@@ -444,7 +642,7 @@ export class StreamClient {
                 p.resolve(msg.result);
             else {
                 const e = msg.error;
-                p.reject(new RpcError(e?.code ?? 'error', e?.message ?? 'unknown'));
+                p.reject(new RpcError(e?.code ?? 'error', e?.message ?? 'unknown', e?.data));
             }
             return;
         }
@@ -462,17 +660,27 @@ 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));
                 break;
             }
             case 'producerPaused': {
                 const p = data;
+                const info = this.remoteInfo.get(p.producerId);
+                if (info)
+                    info.paused = Boolean(p.paused);
                 this.emit('trackMuted', {
                     identity: p.identity,
                     kind: p.kind,
@@ -482,27 +690,40 @@ export class StreamClient {
                 });
                 break;
             }
-            case 'participantJoined':
-                this.emit('participantJoined', data);
+            case 'participantJoined': {
+                const p = data;
+                // 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;
                 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) => p.identity !== e.identity ? p : { ...p,
-                        ...(!e.kind || e.kind === 'audio' ? { muted: e.paused } : {}),
-                        ...(!e.kind || e.kind === 'video' ? { videoBlocked: e.paused } : {}),
-                    });
+                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);
+            case 'participantUpdated': {
+                const e = data;
+                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;
+                this.updateRoster((list) => list.filter((p) => p.identity !== e.identity));
+                this.emit('participantLeft', e);
                 break;
+            }
             case 'roleChanged': {
                 const e = data;
                 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.
@@ -513,9 +734,13 @@ export class StreamClient {
                 break;
             }
             case 'handRaised':
-            case 'handLowered':
+            case 'handLowered': {
+                const e = data;
+                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);
                 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
@@ -528,20 +753,33 @@ export class StreamClient {
                 this.emit('forceMuted', e);
                 break;
             }
+            case 'claimChanged': {
+                const e = data;
+                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;
+                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;
                 if (e.token)
-                    this.token = e.token;
+                    this.setToken(e.token, typeof e.expiresAt === 'number' && e.expiresAt > 0 ? e.expiresAt * 1000 : null);
                 break;
             }
             case 'mustReconnect': {
                 const e = data;
                 // A promotion hands us a fresh token carrying the new role.
                 if (e.token)
-                    this.token = e.token;
+                    this.setToken(e.token, null);
                 this.emit('mustReconnect', e);
                 if (e.retry) {
                     this.teardownMedia();
@@ -557,16 +795,22 @@ export class StreamClient {
             case 'usageLimit':
                 this.emit('usageLimit', d);
                 break;
+            case 'walletLow': {
+                const e = data;
+                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);
-                this.emit('closed', 'room-closed');
+                this.finish('room-closed');
                 this.close();
                 break;
             case 'kicked':
                 this.closedByUs = true;
                 this.emit('kicked', d);
-                this.emit('closed', 'kicked');
+                this.finish('kicked');
                 this.close();
                 break;
             case 'message':
@@ -585,6 +829,25 @@ export class StreamClient {
                 break;
         }
     }
+    /** Change the roster the join result holds; a new array each time, so a renderer sees the change. */
+    updateRoster(change) {
+        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. */
+    applyClaim(e) {
+        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
     ensureSendTransport() {
         if (this.sendTransport)
@@ -598,7 +861,7 @@ export class StreamClient {
     }
     async createSendTransport() {
         if (!this.device)
-            throw new Error('not connected');
+            throw new RpcError('not-connected', 'not connected');
         const params = (await this.rpc('createTransport', { direction: 'send' }));
         const transport = this.device.createSendTransport({
             ...params,
@@ -610,7 +873,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.producerId }))
                 .catch(fail);
         });
@@ -629,7 +895,7 @@ export class StreamClient {
     }
     async createRecvTransport() {
         if (!this.device)
-            throw new Error('not connected');
+            throw new RpcError('not-connected', 'not connected');
         const params = (await this.rpc('createTransport', { direction: 'recv' }));
         const transport = this.device.createRecvTransport({
             ...params,
@@ -656,12 +922,24 @@ export class StreamClient {
      * kept for a reconnect's republish.
      */
     async publish(stream, constraints, options) {
+        // 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);
+    }
+    async publishStream(stream, constraints, options) {
         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'));
+            throw unpublishedWhile('stream');
         this.localStream = stream;
         this.wasPublishing = true;
         if (constraints)
@@ -670,35 +948,140 @@ 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() {
+        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) {
+        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;
+    }
+    micProducer() {
+        for (const p of this.producers.values()) {
+            if (p.kind === 'audio' && p.appData.source === 'mic')
+                return p;
+        }
+        return undefined;
+    }
+    micTask(task) {
+        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. */
+    audioQualityFor() {
+        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.
+     */
+    async produceMic(transport, track, generation) {
+        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. */
+    async reproduceMic(current, track) {
+        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() {
         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() {
-        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() {
+        return this.cameraProducer() ? this.cameraFrameRate : 30;
     }
     /**
      * Change the video quality while publishing. The camera's producer is
@@ -708,6 +1091,7 @@ export class StreamClient {
      */
     async setVideoQuality(quality) {
         this.publishOptions = { ...this.publishOptions, quality };
+        this.sizeCapReported = false;
         await this.cameraTask(async () => {
             const current = this.cameraProducer();
             const track = current?.track;
@@ -717,25 +1101,54 @@ 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) {
         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;
             if (!current || !track || track.readyState !== 'live')
                 return;
             try {
-                await track.applyConstraints?.({ frameRate: { ideal: frameRate, max: frameRate } });
+                await track.applyConstraints?.({ ...track.getConstraints?.(), frameRate: { ideal: frameRate, max: frameRate } });
             }
             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. */
+    allows60() {
+        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.
+     */
+    cameraQuality(frameRate) {
+        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);
     }
     /**
      * Send a different video track from now on: a canvas with effects drawn on
@@ -781,7 +1194,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) {
@@ -974,7 +1388,7 @@ export class StreamClient {
      */
     async produceCamera(transport, track, generation, paused = !track.enabled) {
         if (generation !== this.publishGeneration)
-            throw new Error(unpublishedWhile('camera'));
+            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
@@ -985,8 +1399,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;
         try {
@@ -1036,7 +1451,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);
     }
@@ -1075,7 +1490,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. */
     reportCodecFallback(message) {
         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;
@@ -1133,7 +1548,7 @@ export class StreamClient {
         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'));
+                this.emit('error', new RpcError('devices-gone', 'cannot restore the broadcast: the devices are gone'));
                 return;
             }
             const ended = stream;
@@ -1155,13 +1570,15 @@ export class StreamClient {
         }
         if (!stream)
             return;
-        await this.publish(stream);
+        await this.publishStream(stream);
     }
     // ------------------------------------------------------------- screen sharing
     /** Publish a screen beside the camera. Call from a click so capture permission can open. */
     async publishScreen(options = {}) {
         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')
@@ -1182,7 +1599,7 @@ export class StreamClient {
             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'));
+                throw unpublishedWhile('screen');
             this.screenStream = stream;
             this.screenMode = mode;
             this.screenAudioEnabled = options.audio !== false;
@@ -1192,7 +1609,7 @@ export class StreamClient {
             video.addEventListener('ended', onEnded, { once: true });
             await this.restoreScreen();
             if (generation !== this.screenGeneration || video.readyState !== 'live')
-                throw new Error(unpublishedWhile('screen'));
+                throw unpublishedWhile('screen');
             this.screenStarted = true;
             this.wasPublishing = true;
             this.emit('screenShareStarted', { stream, mode });
@@ -1256,7 +1673,7 @@ 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; });
@@ -1264,7 +1681,7 @@ export class StreamClient {
             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);
@@ -1275,7 +1692,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,
@@ -1283,19 +1705,34 @@ export class StreamClient {
                 appData: { source: 'screen-audio' },
             }));
     }
+    /**
+     * 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.
+     */
     frameRateFor(track) {
         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;
     }
-    async sampleCamera(baseline) {
+    async sampleCamera(baseline, isCurrent) {
+        const sampledProducer = this.cameraProducer();
         const stats = await this.collectVideoStats(baseline);
+        if (!isCurrent() || sampledProducer !== this.cameraProducer())
+            return null;
         if (this.cameraFrameRate !== 60 || this.frameRateFallback || !stats)
             return stats;
         if (this.cameraProducer()?.paused)
@@ -1309,12 +1746,12 @@ export class StreamClient {
         const limited = stats.layers.some((layer) => layer.active && (layer.qualityLimitation === 'cpu' || layer.qualityLimitation === 'bandwidth'));
         this.frameRateLowSamples = limited && stats.fps > 0 && stats.fps < 50 ? this.frameRateLowSamples + 1 : 0;
         if (this.frameRateLowSamples >= 3) {
-            this.frameRateFallback = true;
             void this.cameraTask(async () => {
                 const producer = this.cameraProducer();
-                if (!producer?.track || producer.closed)
+                if (!isCurrent() || producer !== sampledProducer || this.frameRateFallback || !producer?.track || producer.closed)
                     return;
-                await producer.track.applyConstraints?.({ frameRate: { ideal: 30, max: 30 } }).catch(() => undefined);
+                this.frameRateFallback = true;
+                await producer.track.applyConstraints?.({ ...producer.track.getConstraints?.(), frameRate: { ideal: 30, max: 30 } }).catch(() => undefined);
                 await this.reproduceCamera(producer, producer.track);
                 this.emit('error', new RpcError('frame-rate-fallback', 'this device or upload cannot sustain 60 fps; publishing at 30 fps'));
             }).catch((error) => this.emit('error', error));
@@ -1333,6 +1770,8 @@ export class StreamClient {
      * the user has not interacted with.
      */
     async publishMusic(input, options) {
+        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();
@@ -1343,7 +1782,7 @@ export class StreamClient {
             // 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'));
+                throw unpublishedWhile('music');
         }
         catch (err) {
             music.close();
@@ -1356,7 +1795,7 @@ export class StreamClient {
     async produceMusic(music, generation) {
         const transport = await this.ensureSendTransport();
         if (generation !== this.publishGeneration)
-            throw new Error(unpublishedWhile('music'));
+            throw unpublishedWhile('music');
         const producer = await transport.produce({
             track: music.track,
             stopTracks: false,
@@ -1416,13 +1855,49 @@ export class StreamClient {
     }
     async consume(remote) {
         if (!this.device)
-            throw new Error('not connected');
+            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. */
+    async consumeSkipped() {
+        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);
+        }
+    }
+    async consumeNow(remote) {
+        if (!this.device)
+            throw new RpcError('not-connected', 'not connected');
         const transport = await this.ensureRecvTransport();
         const params = (await this.rpc('consume', {
             transportId: transport.id,
@@ -1455,6 +1930,7 @@ export class StreamClient {
         const kind = consumer.kind;
         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,
@@ -1599,6 +2075,57 @@ export class StreamClient {
     kick(identity, reason) { return this.rpc('kick', { identity, reason }); }
     endRoom() { return this.rpc('endRoom'); }
     getRoomState() { 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, identity) {
+        await this.rpc('claim', identity ? { key, identity } : { key });
+    }
+    /** Give up a slot. Moderators may release anyone's. */
+    async release(key) {
+        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) {
+        await this.rpc('blockSlot', { key });
+    }
+    /** Unlock a slot. Moderators only. */
+    async unblockSlot(key) {
+        await this.rpc('unblockSlot', { key });
+    }
+    /** Replace your own display metadata; the room hears it as participantUpdated. */
+    async setMetadata(metadata) {
+        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, options = {}) {
+        const res = (await this.rpc('setRoomMetadata', {
+            metadata,
+            ...(options.replace ? { replace: true } : {}),
+            ...(options.requireFree ? { requireFree: options.requireFree } : {}),
+        }));
+        return res?.metadata ?? null;
+    }
     // ------------------------------------------------------------------- chat
     //
     // The room's chat rides this same socket. Someone on a chat-only socket