@voltkit-rtc/client 0.7.2 → 0.8.0

package/dist/esm/index.js

@@ -9,7 +9,15 @@ import { CameraRecording } from './recording.js';
 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 { NetworkQualityWatch, networkQualityOf, readTransportStats } from './network.js';
+import { MediaPathWatch, SocketLiveness } from './link.js';
+import { AdaptiveVideos, pageIsVisible } from './adaptive.js';
+import { AudioProtection, PROTECT_SAMPLE_MS, readInboundAudio, readOutboundAudio } from './fallback.js';
+import { ActiveSpeakers, AUDIO_LEVEL_INTERVAL_MS, SPEAKING_LEVEL } from './speakers.js';
+import { connectionPath, runPreflight, syntheticMedia } from './preflight.js';
+import { DiagnosticsLog, SDK_VERSION } from './diagnostics.js';
+import { HEALTH_SAMPLE_MS, HealthDecisions, INTERRUPTED_AFTER_MS, readMediaSource } from './health.js';
+import { constraintsFor, deviceIdOf, diffDevices, enumerate } from './devices.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';
@@ -24,19 +32,41 @@ export { AUDIO_QUALITIES, AUDIO_SETTINGS, DEFAULT_MEDIA_PERMISSIONS, resolvePerm
 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';
+export { SPEAKING_LEVEL } from './speakers.js';
+export { SDK_VERSION } from './diagnostics.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');
+/** A receiver's most recent audio level (0..1), from its synchronization sources: cheap, made for this. */
+function receiverLevel(receiver) {
+    const sources = receiver?.getSynchronizationSources?.() ?? [];
+    let level = 0;
+    for (const s of sources)
+        if (typeof s.audioLevel === 'number')
+            level = Math.max(level, s.audioLevel);
+    return level;
+}
+/** A microphone producer's level now (0..1), from its media-source statistics. */
+async function senderLevel(producer) {
+    const stats = await producer.getStats();
+    for (const s of stats.values()) {
+        if (s.type === 'media-source' && typeof s.audioLevel === 'number')
+            return s.audioLevel;
+    }
+    return 0;
+}
 // 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 = {
+    mediaReconnecting: 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,
+    usageLimit: true, walletLow: true, tokenExpiring: true, networkQuality: true, videoLimited: true, cpuConstrained: true,
+    streamFallback: true, publishFallback: true, devicesChanged: true, localTrackEnded: true, audioLevels: true, activeSpeakers: true, mediaWarning: true, autoplayFailed: true,
     screenShareStarted: true, screenShareEnded: true, error: true, localMediaChanged: true, localStreamChanged: true,
     message: true, messageDeleted: true, chatMuted: true, typing: true,
 };
@@ -48,7 +78,6 @@ const MAX_RECONNECT_ATTEMPTS = 8;
 const CLOSE_REPLACED = 4001;
 /** The server ended the session on purpose and said why first: do not reconnect. */
 const CLOSE_ENDED = 4003;
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const isLayer = (value) => Number.isInteger(value) && value >= 0;
 /**
  * Where a new camera stream's bandwidth estimate starts, in kbps. Chrome
@@ -58,6 +87,16 @@ const VIDEO_START_BITRATE_KBPS = 2000;
 /** Why a connect() gave up: close() ran while it was under way, and close wins. */
 const closedWhileConnecting = () => new RpcError('not-connected', 'the session was closed while connecting');
 /** Why a publish gave up: unpublish() ran while it was under way, and unpublish wins. */
+/**
+ * The constraints that capture again what two publishes captured: each kind
+ * as the later publish asked for it, or as the earlier one did if the later
+ * one did not ask for it.
+ */
+function mergeConstraints(earlier, later) {
+    if (!earlier)
+        return later;
+    return { ...earlier, ...later, audio: later.audio || earlier.audio, video: later.video || earlier.video };
+}
 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
@@ -81,6 +120,78 @@ function declareAudioQuality(rtpParameters, appData) {
 export class StreamClient {
     wsUrl;
     options;
+    backoffWake = null;
+    onlineTarget = null;
+    online = () => {
+        if (this.closedByUs)
+            return;
+        this.backoffWake?.();
+        this.socketLiveness.checkNow();
+    };
+    socketLiveness = new SocketLiveness({
+        active: () => !this.closedByUs && this.state === 'connected',
+        ping: () => { void this.rpc('ping').catch(() => undefined); },
+        dead: () => this.recoverConnection('socket-timeout'),
+    });
+    mediaPaths = new MediaPathWatch({
+        active: () => !this.closedByUs && this.state === 'connected',
+        restartIce: id => this.restartMediaIce(id),
+        reconnect: reason => this.recoverConnection(reason),
+        onPathChange: (transportId, reconnecting) => {
+            if (!this.closedByUs)
+                this.emit('mediaReconnecting', { transportId, reconnecting });
+        },
+    });
+    recoverConnection(reason) {
+        if (this.closedByUs || !this.joinedOnce || this.state !== 'connected')
+            return;
+        this.setState('reconnecting');
+        if (this.closedByUs)
+            return; // a state listener may close synchronously
+        this.mediaPaths.reset();
+        if (this.closedByUs)
+            return;
+        this.detachSocket(reason);
+        this.networkWatch.set(false);
+        this.emit('disconnected', reason);
+        void this.scheduleReconnect();
+    }
+    async restartMediaIce(id) {
+        const transport = [this.sendTransport, this.recvTransport].find(t => t?.id === id);
+        const socket = this.ws;
+        if (!transport || transport.closed || this.closedByUs || this.state !== 'connected')
+            return 'skipped';
+        const { iceParameters } = await this.rpc('restartIce', { transportId: id });
+        if (this.ws !== socket || transport.closed || this.closedByUs ||
+            (transport !== this.sendTransport && transport !== this.recvTransport))
+            return 'skipped';
+        await transport.restartIce({ iceParameters });
+        if (this.ws === socket && !this.closedByUs && !transport.closed && transport.connectionState === 'connected') {
+            this.mediaPaths.update(id, 'connected');
+        }
+        return 'restarted';
+    }
+    watchTransport(transport) {
+        transport.on('connectionstatechange', state => {
+            if (transport !== this.sendTransport && transport !== this.recvTransport)
+                return;
+            if (!this.closedByUs && this.state === 'connected')
+                this.mediaPaths.update(transport.id, state);
+        });
+        transport.observer?.on('close', () => this.mediaPaths.forget(transport.id));
+    }
+    waitBackoff(ms) {
+        return new Promise(resolve => {
+            const finish = () => {
+                clearTimeout(timer);
+                if (this.backoffWake === finish)
+                    this.backoffWake = null;
+                resolve();
+            };
+            const timer = setTimeout(finish, ms);
+            this.backoffWake = finish;
+        });
+    }
     ws = null;
     device = null;
     sendTransport = null;
@@ -105,6 +216,15 @@ export class StreamClient {
     // broadcaster that reconnects rejoins silently, which is worse than being
     // disconnected: the room looks healthy and shows nothing.
     wasPublishing = false;
+    /** The deadline of the socket being opened (openSocket). */
+    openDeadline;
+    /**
+     * This client's own moderation per kind: whether a moderator holds it off,
+     * and a revision every decision bumps. A switch-on that was waiting for the
+     * server when a decision arrived does not act on its reply (V072-06).
+     */
+    forcedOff = { audio: false, video: false };
+    moderationRevision = { audio: 0, video: 0 };
     publishConstraints = null;
     publishOptions = {};
     /** In-app music being published, kept across reconnects so it can be published again. */
@@ -144,6 +264,67 @@ export class StreamClient {
      * the full picture.
      */
     preferredLayers = new Map();
+    /**
+     * Adaptive stream (attachVideo): each attached remote video at the size it is
+     * shown, and paused at the server while no attached element is visible.
+     */
+    adaptive = new AdaptiveVideos({
+        layers: (id) => this.remoteVideoLayers.get(id) ?? [],
+        apply: (id, want) => { void this.applyAdaptive(id, this.withFallback(id, want)); },
+        pixelRatio: () => (typeof window !== 'undefined' ? window.devicePixelRatio : 1),
+        pageVisible: pageIsVisible,
+    });
+    /** Audio-only fallback: whether it may happen, its decisions, and the sampling that feeds them. */
+    audioOnlyEnabled = true;
+    protection = new AudioProtection((active) => this.onAudioProtection(active));
+    protectionTimer = null;
+    protectionSampling = false;
+    /** Publisher-side fallback: off unless asked for; its decisions, timer, and whether it holds the camera now. */
+    publishFallbackEnabled = false;
+    publishProtection = new AudioProtection((active) => { void this.onPublishProtection(active); });
+    publishProtectionTimer = null;
+    publishProtectionSampling = false;
+    cameraHeldByFallback = false;
+    /** Remote videos the media server reports it cut for this viewer's bandwidth. */
+    bandwidthCut = new Set();
+    /** Remote cameras the audio-only fallback holds back now (reported with fallback: true). */
+    protectionHeld = new Set();
+    /** audioLevels / activeSpeakers: read only while someone listens. */
+    levelTimer = null;
+    levelSampling = false;
+    speakers = new ActiveSpeakers();
+    /** mediaWarning: decisions, the sampling timer, and the system interruptions being timed. */
+    health = new HealthDecisions((warning) => this.emit('mediaWarning', warning));
+    healthTimer = null;
+    healthSampling = false;
+    interruptions = new Map();
+    /** getDiagnostics(): the SDK's recent events, for a support ticket. */
+    diagnosticsLog = new DiagnosticsLog();
+    /** play(): elements the browser refused to play until the viewer interacts, retried on the next gesture. */
+    autoplayBlocked = new Set();
+    gestureWatchOn = false;
+    onGesture = () => { void this.retryAutoplay(); };
+    /** setPlayoutDelay: the receive buffer asked for every remote track, in ms (null: the browser's own). */
+    playoutDelayMs = null;
+    /** devicesChanged: the device list last seen, kept while someone listens. */
+    knownDevices = [];
+    deviceWatchOn = false;
+    onDeviceChange = () => { void this.refreshDevices(); };
+    /** Videos adaptive stream has paused at the server, by producer id. */
+    adaptivePaused = new Set();
+    /** The server has no pauseConsumer (an older controller): a hidden video drops to its smallest layer instead. */
+    pauseUnsupported = false;
+    /** The last cpuConstrained said. */
+    cpuConstrainedNow = false;
+    /** prioritizePerformance(): the camera's largest simulcast layer is not encoded while true. */
+    performanceFirst = false;
+    /**
+     * Dynacast (the server's `producerLayers`): the highest layer any viewer needs, by producer id (-1 = nobody
+     * watches, the smallest layer stays on). No entry: every layer, as before the server said anything.
+     */
+    layersNeeded = new Map();
+    /** The highest camera layer this client set active, and on which producer. */
+    cameraMaxLayer = null;
     /** endRoom() calls waiting for their reply; a roomClosed that arrives first answers them. */
     endRoomWaiters = new Set();
     closedByUs = false;
@@ -170,7 +351,14 @@ export class StreamClient {
     codecFallbackLogged = false;
     sendStatsBaseline = new Map();
     recvStatsBaseline = new Map();
-    limitWatch = new VideoLimitWatch((baseline, isCurrent) => this.sampleCamera(baseline, isCurrent), (event) => this.emit('videoLimited', event), undefined, () => { this.frameRateLowSamples = 0; this.frameRateWarmupSamples = 2; });
+    limitWatch = new VideoLimitWatch((baseline, isCurrent) => this.sampleCamera(baseline, isCurrent), (event) => {
+        this.emit('videoLimited', event);
+        const constrained = event.reason === 'cpu';
+        if (constrained !== this.cpuConstrainedNow) {
+            this.cpuConstrainedNow = constrained;
+            this.emit('cpuConstrained', { constrained });
+        }
+    }, 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. */
@@ -201,11 +389,55 @@ export class StreamClient {
     audioCapReported = false;
     sizeCapReported = false;
     networkWatch = new NetworkQualityWatch(() => this.transportStats(), () => this.producers.size > 0, (quality) => this.emit('networkQuality', quality));
+    /**
+     * A pre-call check (Twilio's runPreflight, LiveKit's ConnectionCheck, Agora's last-mile probe): joins the room the
+     * token names, publishes `options.media` (cloned, your tracks keep running) or a tone and a moving picture it makes,
+     * measures for `durationMs` (5 s) and leaves. Mint a host token for a test room nobody else is in: the session is
+     * real, and billed like any other for its few seconds. Resolves with each step, how media travelled (UDP is best;
+     * TCP or a relay means a firewall in the way), the round trip, loss and upload, and any camera or microphone warning
+     * seen. Never rejects: a failure is a step with `ok: false` and its error.
+     */
+    static async preflight(wsUrl, token, options = {}) {
+        const client = new StreamClient(wsUrl, token, { audioOnlyFallback: false });
+        const synthetic = options.media ? null : syntheticMedia();
+        const stream = options.media ? new MediaStream(options.media.getTracks().map((t) => t.clone())) : synthetic.stream;
+        try {
+            return await runPreflight({
+                connect: () => client.connect(),
+                publish: (media) => client.publish(media),
+                sendState: () => client.sendTransport?.connectionState ?? null,
+                sendStats: async () => (client.sendTransport ? (await client.sendTransport.getStats()).values() : null),
+                onWarning: (listener) => client.on('mediaWarning', (w) => listener(w.code, w.active)),
+                close: () => client.close(),
+            }, stream, options);
+        }
+        finally {
+            synthetic?.stop();
+        }
+    }
+    /**
+     * Warm the connection before `connect()` (LiveKit's prepareConnection): a HEAD request to the server, so the
+     * name lookup and the TLS handshake are done by the time the socket opens. Call it as the user heads for the
+     * room (opening the room screen, say). Never rejects; it only saves time.
+     */
+    static async prepareConnection(wsUrl) {
+        try {
+            const url = new URL(wsUrl);
+            url.protocol = url.protocol === 'ws:' ? 'http:' : 'https:';
+            url.pathname = '/';
+            url.search = '';
+            await fetch(url.toString(), { method: 'HEAD', mode: 'no-cors', cache: 'no-store' });
+        }
+        catch {
+            // Only a warm-up: connect() does the real work either way.
+        }
+    }
     constructor(wsUrl, token, options = {}) {
         this.wsUrl = wsUrl;
         this.options = options;
         this.token = token;
         this.tokenExpiry = tokenExpiresAt(token);
+        this.audioOnlyEnabled = options.audioOnlyFallback !== false;
     }
     on(event, fn) {
         let set = this.listeners.get(event);
@@ -216,16 +448,28 @@ export class StreamClient {
         set.add(fn);
         // videoLimited and networkQuality cost a getStats every few seconds, so
         // they run only while heard.
-        if (event === 'videoLimited')
+        if (event === 'videoLimited' || event === 'cpuConstrained')
             this.syncLimitWatch();
         if (event === 'networkQuality')
             this.syncNetworkWatch();
+        if (event === 'devicesChanged')
+            this.syncDeviceWatch();
+        if (event === 'audioLevels' || event === 'activeSpeakers')
+            this.syncLevelWatch();
+        if (event === 'mediaWarning')
+            this.syncHealthWatch();
         return () => {
             set.delete(fn);
-            if (event === 'videoLimited')
+            if (event === 'videoLimited' || event === 'cpuConstrained')
                 this.syncLimitWatch();
             if (event === 'networkQuality')
                 this.syncNetworkWatch();
+            if (event === 'devicesChanged')
+                this.syncDeviceWatch();
+            if (event === 'audioLevels' || event === 'activeSpeakers')
+                this.syncLevelWatch();
+            if (event === 'mediaWarning')
+                this.syncHealthWatch();
         };
     }
     /** Where the session stands: idle, connecting, connected, reconnecting or closed. */
@@ -239,6 +483,10 @@ export class StreamClient {
         this.state = next;
         if (next === 'closed')
             this.stopTimers();
+        else {
+            this.syncLevelWatch();
+            this.syncHealthWatch();
+        }
         this.emit('connectionStateChanged', { state: next, previous });
     }
     /** Over for good: the state, then the event that says why. */
@@ -260,6 +508,20 @@ export class StreamClient {
         this.close();
     }
     stopTimers() {
+        if (this.publishProtectionTimer)
+            clearInterval(this.publishProtectionTimer);
+        this.publishProtectionTimer = null;
+        this.autoplayBlocked.clear();
+        this.watchGesture(false);
+        this.stopProtection();
+        this.stopLevelWatch();
+        this.stopHealthWatch(false);
+        this.stopDeviceWatch();
+        this.socketLiveness.stop();
+        this.mediaPaths.reset();
+        this.backoffWake?.();
+        this.onlineTarget?.removeEventListener('online', this.online);
+        this.onlineTarget = null;
         if (this.tokenTimer)
             clearTimeout(this.tokenTimer);
         this.tokenTimer = null;
@@ -269,6 +531,7 @@ export class StreamClient {
         return this.listeners.get(event)?.size ?? 0;
     }
     emit(event, ...args) {
+        this.diagnosticsLog.record(event, args);
         for (const fn of this.listeners.get(event) ?? []) {
             try {
                 fn(...args);
@@ -306,7 +569,10 @@ export class StreamClient {
             // the socket would be closed by the server's join deadline instead, and
             // that close would start reconnecting a session that never began.
             const superseded = this.ws !== null && this.ws !== socket;
-            if (!this.joinedOnce && !superseded) {
+            // A reconnect attempt that failed (its join timed out, say) lets its
+            // socket go now too, so nothing it says later reaches the session while
+            // the next attempt waits its backoff (V072-05).
+            if ((!this.joinedOnce || this.reconnecting) && !superseded) {
                 this.detachSocket();
                 if (this.state === 'connecting')
                     this.setState('idle');
@@ -321,6 +587,11 @@ export class StreamClient {
         this.joinedOnce = true;
         this.skippedVideos.clear();
         this.setState('connected');
+        this.socketLiveness.start();
+        if (!this.onlineTarget && typeof window !== 'undefined' && window.addEventListener) {
+            this.onlineTarget = window;
+            window.addEventListener('online', this.online);
+        }
         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.
@@ -330,6 +601,8 @@ export class StreamClient {
                 throw closedWhileConnecting();
         }
         const own = result.participants.find((p) => p.identity === result.identity);
+        this.moderate('audio', Boolean(own?.muted), true);
+        this.moderate('video', Boolean(own?.videoBlocked), true);
         if (own?.muted)
             this.applyLocalModeration('audio');
         if (own?.videoBlocked)
@@ -350,12 +623,13 @@ export class StreamClient {
                 this.remoteVideoLayers.delete(producerId);
         // Subscribe to everything already publishing before we announce readiness.
         // A close() part-way stops it: what is left would only fail, after closed.
-        for (const p of result.producers) {
-            if (closed())
-                throw closedWhileConnecting();
-            await this.consume(p).catch((err) => { if (!closed())
-                this.emit('error', err); });
-        }
+        // All at once, as newProducer events already are (and the Flutter SDK does): each subscription reserves its slot
+        // before its first await, in this order, and the receive transport is made once. A room with six publishers
+        // starts six videos together instead of one after another, two round trips each.
+        if (closed())
+            throw closedWhileConnecting();
+        await Promise.all(result.producers.map((p) => this.consume(p).catch((err) => { if (!closed())
+            this.emit('error', err); })));
         // Restore our own broadcast. This is what makes an origin failover
         // survivable for the host: it reconnects onto the new origin and the
         // stream comes back on its own.
@@ -366,6 +640,9 @@ export class StreamClient {
         if (closed())
             throw closedWhileConnecting();
         this.syncNetworkWatch();
+        this.syncProtection();
+        this.syncLevelWatch();
+        this.syncPublishProtection();
         return result;
     }
     /**
@@ -385,22 +662,38 @@ export class StreamClient {
         return new Promise((resolve, reject) => {
             const ws = new WebSocket(socketUrl(this.wsUrl, this.token));
             this.ws = ws;
+            // Bounded like every request (V072-05): a socket that does not open in
+            // time fails the attempt with `timeout` and is closed, instead of
+            // holding connect() -- or a reconnect attempt -- indefinitely.
+            this.openDeadline = setTimeout(() => {
+                reject(new RpcError('timeout', `the connection did not open in ${RPC_TIMEOUT_MS / 1000} s`));
+                if (this.ws === ws)
+                    this.detachSocket('open timed out', 'the connection did not open in time');
+            }, RPC_TIMEOUT_MS);
             const onOpen = () => {
+                clearTimeout(this.openDeadline);
                 this.emit('connected');
                 resolve();
             };
-            const onError = () => reject(new RpcError('connect-failed', 'websocket failed to open'));
+            const onError = () => {
+                clearTimeout(this.openDeadline);
+                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) => {
-                if (this.ws === ws)
+                if (this.ws === ws) {
+                    this.socketLiveness.received();
                     this.onMessage(ev.data);
+                }
             });
             ws.addEventListener('close', (ev) => {
                 ws.removeEventListener('error', onError);
                 // Only the socket we currently consider ours may drive reconnection.
                 if (this.ws !== ws)
                     return;
+                this.socketLiveness.stop();
+                this.mediaPaths.reset();
                 this.ws = null;
                 this.failAllPending(new RpcError('not-connected', `socket closed (${ev.code})`));
                 this.emit('disconnected', ev.reason || String(ev.code));
@@ -433,6 +726,8 @@ export class StreamClient {
         });
     }
     detachSocket(reason = 'superseded', why = 'the connection was replaced') {
+        this.socketLiveness.stop();
+        clearTimeout(this.openDeadline);
         const ws = this.ws;
         this.ws = null;
         if (!ws)
@@ -482,7 +777,7 @@ export class StreamClient {
                     return;
                 }
                 const backoff = Math.min(500 * 2 ** (this.reconnectAttempt - 1), 15_000);
-                await sleep(backoff + Math.random() * 400);
+                await this.waitBackoff(backoff + Math.random() * 400);
                 if (this.closedByUs)
                     return;
                 try {
@@ -518,6 +813,9 @@ export class StreamClient {
     }
     close() {
         void this.stopRecording().catch(() => undefined);
+        // Adaptive stream stops watching elements: nothing is received any more.
+        this.adaptive.dispose();
+        this.adaptivePaused.clear();
         // Only an app closing a live session is 'left'; kicked, room-closed and the
         // others have already reported themselves and set closedByUs.
         const wasOpen = !this.closedByUs;
@@ -551,7 +849,15 @@ export class StreamClient {
             this.emit('closed', 'left');
     }
     teardownMedia() {
+        this.mediaPaths.reset();
+        // The videos go with their consumers; a reconnect decides afresh. What was reported held back is withdrawn, so an
+        // app's "poor connection" overlay does not outlive it.
+        this.clearFallbacks();
         this.subscriptions.clear();
+        // Producers made after this are new: the server says again what their viewers need.
+        this.layersNeeded.clear();
+        // New consumers start paused at the server; adaptive stream decides again for each.
+        this.adaptivePaused.clear();
         for (const c of this.consumers.values())
             c.close();
         this.consumers.clear();
@@ -771,6 +1077,35 @@ export class StreamClient {
             case 'newProducer':
                 await this.consume(data).catch((err) => this.emit('error', err));
                 break;
+            case 'streamFallback': {
+                // The media server cut (or resumed) one of this viewer's videos for its bandwidth.
+                const e = data;
+                if (typeof e.producerId !== 'string' || !this.consumers.has(e.producerId))
+                    break;
+                const cut = e.fallback === true;
+                if (cut === this.bandwidthCut.has(e.producerId))
+                    break;
+                if (cut)
+                    this.bandwidthCut.add(e.producerId);
+                else
+                    this.bandwidthCut.delete(e.producerId);
+                this.emitFallback(e.producerId, cut, 'bandwidth');
+                break;
+            }
+            case 'producerLayers': {
+                // Dynacast: what this client's viewers need from one of its producers. Layers nobody receives are not
+                // encoded (the smallest always is, so a new viewer starts at once); null means every layer.
+                const e = data;
+                if (typeof e.producerId !== 'string')
+                    break;
+                if (typeof e.spatialLayer === 'number' && Number.isInteger(e.spatialLayer))
+                    this.layersNeeded.set(e.producerId, e.spatialLayer);
+                else
+                    this.layersNeeded.delete(e.producerId);
+                if (this.cameraProducer()?.id === e.producerId)
+                    void this.cameraTask(() => this.syncCameraLayers());
+                break;
+            }
             case 'producerClosed': {
                 const { producerId, identity } = data;
                 this.subscriptions.delete(producerId);
@@ -778,6 +1113,9 @@ export class StreamClient {
                 this.receiveQualities.delete(producerId);
                 this.remoteVideoLayers.delete(producerId);
                 this.skippedVideos.delete(producerId);
+                this.adaptivePaused.delete(producerId);
+                this.bandwidthCut.delete(producerId);
+                this.protectionHeld.delete(producerId);
                 const consumer = this.consumers.get(producerId);
                 consumer?.close();
                 this.consumers.delete(producerId);
@@ -814,6 +1152,8 @@ export class StreamClient {
             case 'participantMuted': {
                 const wire = data;
                 const e = { identity: wire.identity, kind: wire.kind, paused: wire.paused ?? wire.muted ?? false };
+                if (e.identity && e.identity === this.joinResult?.identity)
+                    this.moderate(e.kind, e.paused, true);
                 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 } : {}),
@@ -831,6 +1171,9 @@ export class StreamClient {
                 const e = data;
                 this.updateRoster((list) => list.filter((p) => p.identity !== e.identity));
                 this.emit('participantLeft', e);
+                const speakers = this.speakers.remove(e.identity);
+                if (speakers)
+                    this.emit('activeSpeakers', { speakers });
                 break;
             }
             case 'roleChanged': {
@@ -860,6 +1203,7 @@ export class StreamClient {
                 // in-app music: it travels as audio). Reflect it locally; a release
                 // changes nothing here -- switching back on is the user's choice.
                 const e = data;
+                this.moderate(e.kind, Boolean(e.paused));
                 if (e.paused) {
                     this.applyLocalModeration(e.kind);
                     this.emitLocalMedia();
@@ -977,16 +1321,21 @@ export class StreamClient {
             return Promise.resolve(this.sendTransport);
         if (this.sendTransportPending)
             return this.sendTransportPending;
-        this.sendTransportPending = this.createSendTransport().finally(() => {
-            this.sendTransportPending = null;
+        const pending = this.createSendTransport().finally(() => {
+            if (this.sendTransportPending === pending)
+                this.sendTransportPending = null;
         });
-        return this.sendTransportPending;
+        return this.sendTransportPending = pending;
     }
     async createSendTransport() {
         if (!this.device)
             throw new RpcError('not-connected', 'not connected');
+        const device = this.device;
+        const socket = this.ws;
         const params = (await this.rpc('createTransport', { direction: 'send' }));
-        const transport = this.device.createSendTransport({
+        if (this.closedByUs || device !== this.device || socket !== this.ws)
+            throw closedWhileConnecting();
+        const transport = device.createSendTransport({
             ...params,
             iceServers: this.joinResult?.iceServers,
         });
@@ -1004,6 +1353,7 @@ export class StreamClient {
                 .catch(fail);
         });
         this.sendTransport = transport;
+        this.watchTransport(transport);
         return transport;
     }
     ensureRecvTransport() {
@@ -1011,16 +1361,21 @@ export class StreamClient {
             return Promise.resolve(this.recvTransport);
         if (this.recvTransportPending)
             return this.recvTransportPending;
-        this.recvTransportPending = this.createRecvTransport().finally(() => {
-            this.recvTransportPending = null;
+        const pending = this.createRecvTransport().finally(() => {
+            if (this.recvTransportPending === pending)
+                this.recvTransportPending = null;
         });
-        return this.recvTransportPending;
+        return this.recvTransportPending = pending;
     }
     async createRecvTransport() {
         if (!this.device)
             throw new RpcError('not-connected', 'not connected');
+        const device = this.device;
+        const socket = this.ws;
         const params = (await this.rpc('createTransport', { direction: 'recv' }));
-        const transport = this.device.createRecvTransport({
+        if (this.closedByUs || device !== this.device || socket !== this.ws)
+            throw closedWhileConnecting();
+        const transport = device.createRecvTransport({
             ...params,
             iceServers: this.joinResult?.iceServers,
         });
@@ -1030,6 +1385,7 @@ export class StreamClient {
                 .catch(fail);
         });
         this.recvTransport = transport;
+        this.watchTransport(transport);
         return transport;
     }
     /**
@@ -1063,10 +1419,28 @@ export class StreamClient {
         // leave nothing behind that a reconnect would publish again.
         if (generation !== this.publishGeneration)
             throw unpublishedWhile('stream');
-        this.localStream = stream;
+        // A second publish adds to the first (the microphone, then the camera):
+        // one local stream carries every live track, so unpublish() and close()
+        // stop them all and a reconnect publishes each again. Replacing it
+        // orphaned the first stream's tracks, still capturing (V072-01).
+        const previous = this.localStream;
+        const merged = previous !== null && previous !== stream && previous.getTracks().some((t) => t.readyState === 'live');
+        if (merged) {
+            const ids = new Set(stream.getTracks().map((t) => t.id));
+            // The new stream's tracks first: of one kind, the newer track is the one
+            // published (as before), and the older one is still stopped with it.
+            this.localStream = new MediaStream([
+                ...stream.getTracks(),
+                ...previous.getTracks().filter((t) => t.readyState === 'live' && !ids.has(t.id)),
+            ]);
+            this.emit('localStreamChanged', this.localStream);
+        }
+        else {
+            this.localStream = stream;
+        }
         this.wasPublishing = true;
         if (constraints)
-            this.publishConstraints = constraints;
+            this.publishConstraints = merged ? mergeConstraints(this.publishConstraints, constraints) : constraints;
         if (options) {
             this.publishOptions = { ...options };
             this.frameRateFallback = false;
@@ -1177,6 +1551,7 @@ export class StreamClient {
             appData: { source: 'mic', audioQuality: quality },
         });
         await this.keepProducer(producer, generation, 'microphone');
+        this.watchTrackEnded(producer);
         this.micQuality = quality;
         // A microphone handed over switched off, or muted before a reconnect.
         await this.pauseOnServer(producer);
@@ -1323,6 +1698,7 @@ export class StreamClient {
                 if (this.cameraEncodings && sameLayout(this.cameraEncodings, next) &&
                     previousSize?.width === width && previousSize?.height === height) {
                     await current.replaceTrack({ track });
+                    this.watchTrackEnded(current);
                     await this.applyLayerBitrates(current, next);
                     return;
                 }
@@ -1426,7 +1802,9 @@ export class StreamClient {
         this.receiveQualities.delete(producerId);
         // Kept first: a reconnect that interrupts the request still applies it.
         this.preferredLayers.set(producerId, layers);
-        await this.rpc('setPreferredLayers', { consumerId: consumer.id, ...layers });
+        // Shown through attachVideo: the lower of this and the size it is shown at.
+        const adaptive = this.adaptive.current(producerId);
+        await this.rpc('setPreferredLayers', { consumerId: consumer.id, ...(adaptive ? this.effectiveLayers(producerId, adaptive) : layers) });
     }
     async collectVideoStats(baseline) {
         const producer = this.cameraProducer();
@@ -1465,7 +1843,8 @@ export class StreamClient {
         }
         this.receiveQualities.set(producerId, quality);
         this.preferredLayers.set(producerId, layers);
-        await this.rpc('setPreferredLayers', { consumerId: consumer.id, ...layers });
+        const adaptive = this.adaptive.current(producerId);
+        await this.rpc('setPreferredLayers', { consumerId: consumer.id, ...(adaptive ? this.effectiveLayers(producerId, adaptive) : layers) });
     }
     cameraProducer() {
         for (const p of this.producers.values()) {
@@ -1557,14 +1936,65 @@ export class StreamClient {
         // unpublish() may have run while this was being made (a publish, a
         // quality change or a track swap under way).
         await this.keepProducer(producer, generation, 'camera');
+        this.watchTrackEnded(producer);
+        this.syncPublishProtection();
         this.cameraEncodings = encodings;
         this.frameRateLowSamples = 0;
         this.frameRateWarmupSamples = 2;
         await this.pauseOnServer(producer);
         await this.applyDegradationPreference(producer);
         this.syncLimitWatch();
+        // A new camera producer starts with every layer: put the performance and viewer limits back on it.
+        await this.syncCameraLayers();
         return producer;
     }
+    /**
+     * Lighten this device's work while it is overloaded (LiveKit's
+     * `prioritizePerformance`): the camera's largest simulcast layer stops being
+     * encoded -- the most expensive part of publishing -- and viewers get the
+     * next one. `false` brings it back. Call it on `cpuConstrained`, together
+     * with your app's own savings (effects off, smaller remote videos). Kept for
+     * later publishes and reconnects until changed. A camera sent as one layer
+     * is left as it is.
+     */
+    async prioritizePerformance(on = true) {
+        this.performanceFirst = on;
+        await this.cameraTask(() => this.syncCameraLayers());
+    }
+    /** Whether `prioritizePerformance()` is in force. */
+    get performancePrioritized() {
+        return this.performanceFirst;
+    }
+    /**
+     * The camera's active simulcast layers: every layer, except the top one while
+     * performance comes first, and none above the highest any viewer needs
+     * (dynacast; the smallest always stays on, so a new viewer starts at once).
+     */
+    async syncCameraLayers() {
+        const producer = this.cameraProducer();
+        const count = this.cameraEncodings?.length ?? 0;
+        if (!producer || producer.closed || count < 2)
+            return;
+        const top = count - 1;
+        let max = top;
+        if (this.performanceFirst)
+            max = Math.min(max, top - 1);
+        const needed = this.layersNeeded.get(producer.id);
+        if (needed !== undefined)
+            max = Math.min(max, Math.max(0, needed));
+        // A producer just made sends every layer: nothing to ask of it until a limit applies.
+        const applied = this.cameraMaxLayer?.producerId === producer.id ? this.cameraMaxLayer.layer : top;
+        if (applied === max)
+            return;
+        try {
+            await producer.setMaxSpatialLayer(max);
+            this.cameraMaxLayer = { producerId: producer.id, layer: max };
+        }
+        catch (err) {
+            if (!producer.closed)
+                this.emit('error', err);
+        }
+    }
     /**
      * Keep a producer just made -- unless unpublish() ran while it was being
      * made. Kept, it would publish again what was just unpublished, so it is
@@ -1639,7 +2069,7 @@ export class StreamClient {
     }
     /** videoLimited sampling runs while a camera is published and someone listens. */
     syncLimitWatch() {
-        this.limitWatch.set(!this.closedByUs && this.cameraProducer() !== undefined && (this.listenerCount('videoLimited') > 0 || this.cameraFrameRate === 60));
+        this.limitWatch.set(!this.closedByUs && this.cameraProducer() !== undefined && (this.listenerCount('videoLimited') > 0 || this.listenerCount('cpuConstrained') > 0 || this.cameraFrameRate === 60));
     }
     /**
      * Re-establish this client's broadcast after a reconnect.
@@ -2099,6 +2529,8 @@ export class StreamClient {
         const consumer = await transport.consume(params);
         current(consumer);
         this.consumers.set(remote.producerId, consumer);
+        if (this.playoutDelayMs !== null)
+            this.applyPlayoutDelay(consumer.rtpReceiver);
         this.remoteVideoLayers.set(remote.producerId, remote.videoLayers ?? remote.appData?.videoLayers ?? params.videoLayers ?? []);
         // Layers asked for before a reconnect: the new consumer gets them before
         // its first frame instead of starting at the full picture. Not getting
@@ -2114,13 +2546,27 @@ export class StreamClient {
                 this.emit('error', new RpcError('quality-unavailable', 'this publisher no longer describes its video layers; using Auto'));
             }
         }
+        // Adaptive stream: a video the app shows through attachVideo starts at the
+        // size it is shown, and one nobody can see stays paused.
+        const adaptive = consumer.kind === 'video' ? this.adaptive.current(remote.producerId) : null;
+        if (adaptive)
+            layers = this.effectiveLayers(remote.producerId, adaptive);
+        // A camera arriving while the audio-only fallback holds cameras back starts held back too.
+        const held = consumer.kind === 'video' && this.protection.active && (remote.source ?? 'camera') === 'camera';
         if (layers) {
             await this.rpc('setPreferredLayers', { consumerId: consumer.id, ...layers }).catch((err) => this.emit('error', err));
         }
         current(consumer);
         // The server created it paused. Resume only now that our end exists,
         // otherwise the first frames arrive before there is anything to decode them.
-        await this.rpc('resumeConsumer', { consumerId: consumer.id });
+        this.adaptivePaused.delete(remote.producerId);
+        if ((adaptive && !adaptive.visible) || (held && !this.pauseUnsupported))
+            this.adaptivePaused.add(remote.producerId);
+        else
+            await this.rpc('resumeConsumer', { consumerId: consumer.id });
+        if (held && this.pauseUnsupported) {
+            await this.rpc('setPreferredLayers', { consumerId: consumer.id, spatialLayer: 0, temporalLayer: 0 }).catch(() => undefined);
+        }
         current(consumer);
         const kind = consumer.kind;
         const source = remote.source ?? defaultSource(kind);
@@ -2133,6 +2579,681 @@ export class StreamClient {
             producerId: remote.producerId,
             source,
         });
+        if (kind === 'video')
+            this.adaptive.consumed(remote.producerId);
+        if (held) {
+            this.protectionHeld.add(remote.producerId);
+            this.emitFallback(remote.producerId, true, 'audio-protection');
+        }
+        this.syncProtection();
+    }
+    /**
+     * Adaptive stream (like LiveKit's adaptiveStream and Tencent TRTC's small
+     * stream with receiveWhenViewVisible): tell the SDK which element shows a
+     * remote video. It then receives the smallest layer that fills that element
+     * sharply (its size on screen × devicePixelRatio, at most 2) and pauses the
+     * video at the server while the element is not visible (scrolled away,
+     * `display: none`, or the tab in the background), so a grid of small tiles
+     * stops decoding full-size video. Attach the same video to several elements
+     * and the largest visible one decides. Returns the function that detaches
+     * it; detach when the element goes away. A ceiling set with
+     * `setReceiveQuality` or `setPreferredLayers` still applies. Works with any
+     * server; one without `pauseConsumer` gets the smallest layer instead of a
+     * pause.
+     */
+    attachVideo(producerId, element) {
+        return this.adaptive.attach(producerId, element);
+    }
+    /** The layers to ask for: the app's ceiling (setReceiveQuality / setPreferredLayers) and adaptive stream's, the lower. */
+    effectiveLayers(producerId, want) {
+        let manual = this.preferredLayers.get(producerId);
+        const quality = this.receiveQualities.get(producerId);
+        if (quality && quality !== 'auto') {
+            try {
+                manual = { spatialLayer: receiveSpatialLayer(this.remoteVideoLayers.get(producerId) ?? [], quality) };
+            }
+            catch {
+                manual = undefined;
+            }
+        }
+        const adaptive = want?.visible ? want.spatialLayer : null;
+        if (adaptive === null || adaptive === undefined)
+            return manual ?? { spatialLayer: -1, temporalLayer: -1 };
+        if (!manual || manual.spatialLayer < 0)
+            return { spatialLayer: adaptive };
+        return { ...manual, spatialLayer: Math.min(manual.spatialLayer, adaptive) };
+    }
+    // ------------------------------------------------------- diagnostics
+    /**
+     * A snapshot for a support ticket (what Agora's log upload and Twilio's Insights are used for): the SDK version and
+     * browser, the session (room, identity, role, state), how each media transport is connected (UDP, TCP or relayed),
+     * the round trip and upload now, what is published and received, and the last 200 notable events (state changes,
+     * errors, recoveries, fallbacks, warnings) with their times. Plain JSON: `JSON.stringify` it and attach it. Holds
+     * no tokens and no media.
+     */
+    async getDiagnostics() {
+        const transport = async (t) => {
+            if (!t || t.closed)
+                return null;
+            let path = null;
+            try {
+                path = connectionPath((await t.getStats()).values());
+            }
+            catch {
+                // Best effort.
+            }
+            return { state: t.connectionState, path };
+        };
+        let network = null;
+        try {
+            const reports = await this.transportStats();
+            const current = new Map([...reports].map(([key, report]) => [key, readTransportStats(report)]));
+            if (current.size > 0) {
+                const q = networkQualityOf(current, new Map(), this.producers.size > 0);
+                network = { rttMs: q.rttMs, availableKbps: q.availableKbps };
+            }
+        }
+        catch {
+            // Best effort.
+        }
+        const join = this.joinResult;
+        return {
+            sdk: SDK_VERSION,
+            at: Date.now(),
+            userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+            connectionState: this.state,
+            room: join?.roomId ?? null,
+            identity: join?.identity ?? null,
+            role: join?.role ?? null,
+            transports: { send: await transport(this.sendTransport), recv: await transport(this.recvTransport) },
+            network,
+            published: [...this.producers.values()].filter((p) => !p.closed)
+                .map((p) => ({ source: String(p.appData.source ?? p.kind), kind: p.kind, paused: p.paused })),
+            received: [...this.consumers.entries()].filter(([, c]) => !c.closed).map(([producerId, c]) => ({
+                identity: this.remoteInfo.get(producerId)?.identity ?? '',
+                source: this.remoteSources.get(producerId) ?? (c.kind === 'audio' ? 'mic' : 'camera'),
+                kind: c.kind,
+                paused: c.paused || this.adaptivePaused.has(producerId),
+            })),
+            log: this.diagnosticsLog.list(),
+        };
+    }
+    // ------------------------------------------------------- autoplay
+    /**
+     * Play a `<video>` or `<audio>` showing a remote track, the way autoplay rules allow (Agora's and Tencent TRTC's
+     * autoplay handling). Resolves true when it plays. When the browser refuses until the viewer interacts with the
+     * page, resolves false, emits `autoplayFailed` with a `resume()` for a "Tap to unmute" button, and plays it -- with
+     * every other refused element -- on the next tap, click or key press by itself.
+     */
+    async play(element) {
+        try {
+            await element.play();
+            this.autoplayBlocked.delete(element);
+            return true;
+        }
+        catch (err) {
+            if (err?.name !== 'NotAllowedError')
+                throw err;
+            this.autoplayBlocked.add(element);
+            this.watchGesture(true);
+            this.emit('autoplayFailed', { element, resume: async () => { await this.play(element); } });
+            return false;
+        }
+    }
+    watchGesture(on) {
+        if (typeof document === 'undefined' || on === this.gestureWatchOn)
+            return;
+        this.gestureWatchOn = on;
+        for (const type of ['pointerdown', 'keydown', 'touchend']) {
+            if (on)
+                document.addEventListener(type, this.onGesture, { capture: true });
+            else
+                document.removeEventListener(type, this.onGesture, { capture: true });
+        }
+    }
+    async retryAutoplay() {
+        for (const element of [...this.autoplayBlocked]) {
+            try {
+                await element.play();
+                this.autoplayBlocked.delete(element);
+            }
+            catch {
+                // Still refused (or the element went away); the next gesture tries again.
+                if (!element.isConnected)
+                    this.autoplayBlocked.delete(element);
+            }
+        }
+        if (this.autoplayBlocked.size === 0)
+            this.watchGesture(false);
+    }
+    // ------------------------------------------------------- playout delay
+    /**
+     * Trade a little delay for smoother playback (Tencent TRTC's playoutDelay): every remote track is buffered about
+     * `ms` before it plays, which rides out the jitter of a mobile network without freezes. For an audience watching a
+     * stream, 300-500 ms is a good value; people talking with each other want `null` (the browser's own, as small as
+     * it can keep). Applies to what is received now and later. Browsers without the setting (before Chrome 114) keep
+     * their own; 0-4000 ms.
+     */
+    setPlayoutDelay(ms) {
+        this.playoutDelayMs = ms === null ? null : Math.min(4000, Math.max(0, Math.round(ms)));
+        for (const consumer of this.consumers.values())
+            this.applyPlayoutDelay(consumer.rtpReceiver);
+    }
+    applyPlayoutDelay(receiver) {
+        if (!receiver || !('jitterBufferTarget' in receiver))
+            return;
+        try {
+            receiver.jitterBufferTarget = this.playoutDelayMs;
+        }
+        catch {
+            // Out of the browser's range: it keeps its own.
+        }
+    }
+    // ------------------------------------------------------- audio levels
+    /** Levels are read only while someone listens and the session is connected. */
+    syncLevelWatch() {
+        const wanted = !this.closedByUs && this.state === 'connected' &&
+            (this.listenerCount('audioLevels') > 0 || this.listenerCount('activeSpeakers') > 0);
+        if (wanted && !this.levelTimer) {
+            this.levelTimer = setInterval(() => void this.sampleAudioLevels(), AUDIO_LEVEL_INTERVAL_MS);
+            this.levelTimer.unref?.();
+        }
+        else if (!wanted) {
+            this.stopLevelWatch();
+        }
+    }
+    stopLevelWatch() {
+        if (this.levelTimer)
+            clearInterval(this.levelTimer);
+        this.levelTimer = null;
+        this.speakers.reset();
+    }
+    /**
+     * One reading: each remote audio from its receiver's synchronization sources (the most recent packet's level, no
+     * statistics report needed), the own microphone from its sender's media-source statistics.
+     */
+    async sampleAudioLevels() {
+        if (this.levelSampling)
+            return;
+        this.levelSampling = true;
+        try {
+            const levels = [];
+            for (const [producerId, consumer] of this.consumers) {
+                if (consumer.kind !== 'audio' || consumer.closed)
+                    continue;
+                const info = this.remoteInfo.get(producerId);
+                if (!info)
+                    continue;
+                const level = info.paused ? 0 : receiverLevel(consumer.rtpReceiver);
+                levels.push({ identity: info.identity, producerId, source: this.remoteSources.get(producerId) ?? 'mic', level, speaking: level > SPEAKING_LEVEL, local: false });
+            }
+            const mic = this.micProducer();
+            const self = this.joinResult?.identity;
+            if (mic && !mic.paused && self) {
+                const level = await senderLevel(mic);
+                levels.push({ identity: self, producerId: mic.id, source: 'mic', level, speaking: level > SPEAKING_LEVEL, local: true });
+            }
+            if (!this.levelTimer)
+                return;
+            if (this.listenerCount('audioLevels') > 0)
+                this.emit('audioLevels', levels);
+            const loudest = new Map();
+            for (const l of levels)
+                if (l.source === 'mic')
+                    loudest.set(l.identity, Math.max(loudest.get(l.identity) ?? 0, l.level));
+            const speakers = this.speakers.update(loudest);
+            if (speakers)
+                this.emit('activeSpeakers', { speakers });
+        }
+        catch {
+            // Best effort; the next reading tries again.
+        }
+        finally {
+            this.levelSampling = false;
+        }
+    }
+    // ------------------------------------------------------- media health
+    /** The published devices are sampled only while someone listens and the session is connected. */
+    syncHealthWatch() {
+        const wanted = !this.closedByUs && this.state === 'connected' && this.listenerCount('mediaWarning') > 0;
+        if (wanted && !this.healthTimer) {
+            this.healthTimer = setInterval(() => void this.sampleHealth(), HEALTH_SAMPLE_MS);
+            this.healthTimer.unref?.();
+        }
+        else if (!wanted) {
+            this.stopHealthWatch(this.listenerCount('mediaWarning') > 0 && !this.closedByUs);
+        }
+    }
+    /** Stop sampling; `report` says each active warning cleared (nothing is said after close). */
+    stopHealthWatch(report) {
+        if (this.healthTimer)
+            clearInterval(this.healthTimer);
+        this.healthTimer = null;
+        for (const timer of this.interruptions.values())
+            clearTimeout(timer);
+        this.interruptions.clear();
+        if (report)
+            this.health.clearAll();
+    }
+    async sampleHealth() {
+        if (this.healthSampling)
+            return;
+        this.healthSampling = true;
+        try {
+            const mic = this.micProducer();
+            const camera = this.cameraProducer();
+            const micLevel = mic && !mic.paused ? readMediaSource((await mic.getStats()).values()).level : null;
+            const cameraFps = camera && !camera.paused ? readMediaSource((await camera.getStats()).values()).fps : null;
+            if (!this.healthTimer)
+                return;
+            this.health.feed({ micLevel, cameraFps, askedFps: this.videoFrameRate });
+            // An interrupted device that is no longer published never says it came back: that is over too.
+            if (!mic)
+                this.health.interrupted('mic-interrupted', false);
+            if (!camera)
+                this.health.interrupted('camera-interrupted', false);
+        }
+        catch {
+            // Best effort; the next sample tries again.
+        }
+        finally {
+            this.healthSampling = false;
+        }
+    }
+    // ---------------------------------------------------------------- devices
+    /**
+     * The cameras, microphones and speakers the browser offers, optionally of one kind. Labels are empty until the
+     * page has been granted camera or microphone access.
+     */
+    listDevices(kind) {
+        return enumerate(kind);
+    }
+    /**
+     * Publish from another camera or microphone (LiveKit's switchActiveDevice, Agora's setDevice). The device is
+     * captured with the constraints publish was given (size, frame rate, echo cancellation) and its track replaces the
+     * published one: a camera of the same size swaps with no pause for viewers, a microphone always does. The track it
+     * replaces is stopped, releasing that device; the client's own stream follows (`localStreamChanged`), and a
+     * reconnect captures the chosen device again. A camera or microphone that is switched off stays off.
+     *
+     * For a camera published as a canvas or another processed track, capture the new camera yourself and pass your
+     * processed track to `replaceVideoTrack`; this rejects rather than replace your picture with the raw camera.
+     * Rejects when that kind is not being published.
+     */
+    async switchDevice(kind, deviceId) {
+        const md = typeof navigator !== 'undefined' ? navigator.mediaDevices : undefined;
+        if (!md?.getUserMedia)
+            throw new Error('switchDevice: this browser cannot capture media');
+        if (kind === 'videoinput') {
+            const current = this.cameraProducer()?.track ?? this.localStream?.getVideoTracks()[0] ?? null;
+            if (!current)
+                throw new Error('switchDevice: no camera is being published');
+            if (!deviceIdOf(current)) {
+                throw new Error('switchDevice: the published video is not a camera capture (a canvas or processed track); capture the camera yourself and call replaceVideoTrack');
+            }
+            const video = constraintsFor(this.publishConstraints?.video, deviceId);
+            const track = (await md.getUserMedia({ video })).getVideoTracks()[0];
+            if (!track)
+                throw new Error('switchDevice: the camera gave no video');
+            try {
+                await this.replaceVideoTrack(track);
+            }
+            catch (err) {
+                track.stop();
+                throw err;
+            }
+            if (current !== track)
+                current.stop();
+            this.publishConstraints = { ...(this.publishConstraints ?? {}), video };
+            return;
+        }
+        await this.micTask(async () => {
+            const producer = this.micProducer();
+            if (!producer)
+                throw new Error('switchDevice: no microphone is being published');
+            const audio = constraintsFor(this.publishConstraints?.audio, deviceId);
+            const track = (await md.getUserMedia({ audio })).getAudioTracks()[0];
+            if (!track)
+                throw new Error('switchDevice: the microphone gave no audio');
+            if (producer.closed || this.micProducer() !== producer) {
+                track.stop();
+                throw new Error('switchDevice: the microphone was unpublished meanwhile');
+            }
+            await this.adoptAudioTrack(producer, track);
+            this.publishConstraints = { ...(this.publishConstraints ?? {}), audio };
+        });
+    }
+    /** Put `track` on the microphone producer and in the client's own stream; the replaced track is stopped. */
+    async adoptAudioTrack(producer, track) {
+        const previous = producer.track;
+        await producer.replaceTrack({ track });
+        const video = this.localStream ? this.localStream.getTracks().filter((t) => t.kind !== 'audio') : [];
+        this.localStream = new MediaStream([track, ...video]);
+        this.emit('localStreamChanged', this.localStream);
+        if (previous && previous !== track)
+            previous.stop();
+        this.watchTrackEnded(producer);
+    }
+    /** Notice when the producer's present track stops from outside (unplugged, permission revoked). */
+    watchTrackEnded(producer) {
+        const track = producer.track;
+        if (!track || typeof track.addEventListener !== 'function')
+            return;
+        track.addEventListener('ended', () => { void this.onTrackEnded(producer, track); }, { once: true });
+        // The system taking the device (a call, another app) mutes the track; held a moment, it is reported.
+        const which = producer.appData.source === 'mic' ? 'mic' : producer.appData.source === 'camera' ? 'camera' : null;
+        if (!which)
+            return;
+        const code = which === 'mic' ? 'mic-interrupted' : 'camera-interrupted';
+        const current = () => !this.closedByUs && !producer.closed && producer.track === track;
+        track.addEventListener('mute', () => {
+            if (!current() || this.interruptions.has(which))
+                return;
+            this.interruptions.set(which, setTimeout(() => {
+                this.interruptions.delete(which);
+                if (current() && track.muted)
+                    this.health.interrupted(code, true);
+            }, INTERRUPTED_AFTER_MS));
+        });
+        track.addEventListener('unmute', () => {
+            const timer = this.interruptions.get(which);
+            if (timer)
+                clearTimeout(timer);
+            this.interruptions.delete(which);
+            if (current())
+                this.health.interrupted(code, false);
+        });
+    }
+    /**
+     * A published camera or microphone stopped from outside. The microphone comes back from the system default (Chime
+     * keeps audio flowing, LiveKit moves to the first available device); a camera is switched off and reported, never
+     * swapped for another camera on its own (Chime stops it the same way).
+     */
+    async onTrackEnded(producer, track) {
+        const live = () => !this.closedByUs && !producer.closed && producer.track === track && this.producers.get(producer.id) === producer;
+        if (!live())
+            return;
+        const deviceId = deviceIdOf(track);
+        if (producer.appData.source === 'mic') {
+            await this.micTask(async () => {
+                if (!live())
+                    return;
+                try {
+                    const md = navigator.mediaDevices;
+                    const audio = constraintsFor(this.publishConstraints?.audio, null);
+                    const next = (await md.getUserMedia({ audio })).getAudioTracks()[0];
+                    if (!next)
+                        throw new Error('no microphone');
+                    if (!live()) {
+                        next.stop();
+                        return;
+                    }
+                    await this.adoptAudioTrack(producer, next);
+                    this.publishConstraints = { ...(this.publishConstraints ?? {}), audio };
+                    this.emit('localTrackEnded', { kind: 'audio', deviceId, recovered: true });
+                }
+                catch {
+                    if (!live())
+                        return;
+                    await this.setMicEnabled(false).catch(() => undefined);
+                    this.emit('localTrackEnded', { kind: 'audio', deviceId, recovered: false });
+                }
+            });
+            return;
+        }
+        if (producer.appData.source === 'camera') {
+            await this.setCamEnabled(false).catch(() => undefined);
+            if (!this.closedByUs)
+                this.emit('localTrackEnded', { kind: 'video', deviceId, recovered: false });
+        }
+    }
+    /** devicesChanged is watched only while someone listens. */
+    syncDeviceWatch() {
+        const md = typeof navigator !== 'undefined' ? navigator.mediaDevices : undefined;
+        const wanted = !this.closedByUs && this.listenerCount('devicesChanged') > 0 && typeof md?.addEventListener === 'function';
+        if (wanted && !this.deviceWatchOn) {
+            this.deviceWatchOn = true;
+            md.addEventListener('devicechange', this.onDeviceChange);
+            void enumerate().then((list) => { if (this.deviceWatchOn)
+                this.knownDevices = list; }).catch(() => undefined);
+        }
+        else if (!wanted) {
+            this.stopDeviceWatch();
+        }
+    }
+    stopDeviceWatch() {
+        if (!this.deviceWatchOn)
+            return;
+        this.deviceWatchOn = false;
+        navigator.mediaDevices?.removeEventListener?.('devicechange', this.onDeviceChange);
+    }
+    async refreshDevices() {
+        let now;
+        try {
+            now = await enumerate();
+        }
+        catch {
+            return;
+        }
+        if (!this.deviceWatchOn)
+            return;
+        const { added, removed } = diffDevices(this.knownDevices, now);
+        this.knownDevices = now;
+        if (added.length > 0 || removed.length > 0)
+            this.emit('devicesChanged', { devices: now, added, removed });
+    }
+    /** Adaptive stream's decision for a video, with the audio-only fallback holding remote cameras back. */
+    withFallback(producerId, want) {
+        if (this.protection.active && this.remoteSources.get(producerId) === 'camera')
+            return { visible: false, spatialLayer: null };
+        return want;
+    }
+    /**
+     * Audio-only fallback (like Agora's AUDIO_ONLY stream fallback): on unless `audioOnlyFallback: false` was given.
+     * While this viewer's received sound breaks up badly -- a quarter of it lost over about 15 s -- remote camera
+     * videos are paused at the server (screen shares stay) so what bandwidth there is goes to the audio; they come
+     * back once it has recovered for a while, holding longer if it falls back again soon. Each held video is reported
+     * by `streamFallback`. `false` brings any held video back now and stops watching.
+     */
+    setAudioOnlyFallback(enabled) {
+        this.audioOnlyEnabled = enabled;
+        if (!enabled)
+            this.protection.release();
+        this.syncProtection();
+    }
+    /**
+     * The publisher side of the audio-only fallback (Agora's setLocalPublishFallbackOption(AUDIO_ONLY)), off by default:
+     * while this client's own sound breaks up on the way to the server -- a quarter of it lost over about 15 s -- its
+     * camera is paused (viewers see it paused) so the upload carries the voice, and resumed once it recovers, holding
+     * longer after a relapse. Reported by `publishFallback`. A camera you or a moderator switch off meanwhile stays off.
+     * `false` brings a held camera back now.
+     */
+    setPublishFallback(enabled) {
+        this.publishFallbackEnabled = enabled;
+        if (!enabled)
+            this.publishProtection.release();
+        this.syncPublishProtection();
+    }
+    syncPublishProtection() {
+        const wanted = this.publishFallbackEnabled && !this.closedByUs && this.state === 'connected' &&
+            this.micProducer() !== undefined && (this.cameraProducer() !== undefined || this.publishProtection.active);
+        if (wanted && !this.publishProtectionTimer) {
+            this.publishProtectionTimer = setInterval(() => void this.samplePublishProtection(), PROTECT_SAMPLE_MS);
+            this.publishProtectionTimer.unref?.();
+        }
+        else if (!wanted && this.publishProtectionTimer) {
+            clearInterval(this.publishProtectionTimer);
+            this.publishProtectionTimer = null;
+        }
+    }
+    async samplePublishProtection() {
+        const transport = this.sendTransport;
+        if (this.publishProtectionSampling || !transport || transport.closed)
+            return;
+        this.publishProtectionSampling = true;
+        try {
+            const report = await transport.getStats();
+            if (transport !== this.sendTransport || !this.publishProtectionTimer)
+                return;
+            this.publishProtection.feed(readOutboundAudio(report.values()));
+        }
+        catch {
+            // Best effort.
+        }
+        finally {
+            this.publishProtectionSampling = false;
+        }
+    }
+    /** The publisher-side fallback decided: hold the camera, or bring it back if it is still ours to bring back. */
+    async onPublishProtection(active) {
+        const camera = this.cameraProducer();
+        if (active) {
+            if (!camera || camera.paused) {
+                this.syncPublishProtection();
+                return;
+            }
+            this.cameraHeldByFallback = true;
+            camera.pause();
+            this.emit('publishFallback', { fallback: true });
+            await this.rpc('pauseProducer', { producerId: camera.id, paused: true }).catch(() => undefined);
+            this.emitLocalMedia();
+        }
+        else if (this.cameraHeldByFallback) {
+            this.cameraHeldByFallback = false;
+            if (camera && camera.paused && !this.forcedOff.video) {
+                camera.resume();
+                await this.rpc('pauseProducer', { producerId: camera.id, paused: false }).catch(() => undefined);
+                this.emitLocalMedia();
+            }
+            this.emit('publishFallback', { fallback: false });
+        }
+        this.syncPublishProtection();
+    }
+    /** Whether the audio-only fallback is holding remote cameras back now. */
+    get audioOnlyFallbackActive() {
+        return this.protection.active;
+    }
+    /** The audio-only fallback decided: hold remote cameras back, or let them come back. */
+    onAudioProtection(active) {
+        for (const [producerId, consumer] of this.consumers) {
+            if (consumer.kind !== 'video' || this.remoteSources.get(producerId) !== 'camera')
+                continue;
+            const want = this.withFallback(producerId, this.adaptive.current(producerId) ?? { visible: true, spatialLayer: null });
+            void this.applyAdaptive(producerId, want);
+            if (active && !this.protectionHeld.has(producerId)) {
+                this.protectionHeld.add(producerId);
+                this.emitFallback(producerId, true, 'audio-protection');
+            }
+            else if (!active && this.protectionHeld.delete(producerId)) {
+                this.emitFallback(producerId, false, 'audio-protection');
+            }
+        }
+        this.syncProtection();
+    }
+    emitFallback(producerId, fallback, reason) {
+        const info = this.remoteInfo.get(producerId);
+        this.emit('streamFallback', {
+            producerId,
+            identity: info?.identity ?? '',
+            source: this.remoteSources.get(producerId) ?? 'camera',
+            fallback,
+            reason,
+        });
+    }
+    /** Withdraw every held-back report (teardown; nothing is said after close) and forget the decisions. */
+    clearFallbacks() {
+        if (!this.closedByUs) {
+            for (const producerId of this.bandwidthCut)
+                this.emitFallback(producerId, false, 'bandwidth');
+            for (const producerId of this.protectionHeld)
+                this.emitFallback(producerId, false, 'audio-protection');
+        }
+        this.bandwidthCut.clear();
+        this.protectionHeld.clear();
+        this.protection.reset();
+        this.stopProtection();
+    }
+    /**
+     * The received audio is sampled only while the fallback could matter: enabled, connected, with remote audio to
+     * judge by and a remote camera to hold back (or one held back already).
+     */
+    syncProtection() {
+        let audio = false;
+        let camera = false;
+        for (const [producerId, consumer] of this.consumers) {
+            if (consumer.closed)
+                continue;
+            if (consumer.kind === 'audio')
+                audio = true;
+            else if (this.remoteSources.get(producerId) === 'camera')
+                camera = true;
+        }
+        const wanted = this.audioOnlyEnabled && !this.closedByUs && this.state === 'connected' && audio && (camera || this.protection.active);
+        if (wanted && !this.protectionTimer) {
+            this.protectionTimer = setInterval(() => void this.sampleProtection(), PROTECT_SAMPLE_MS);
+            // Background sampling never keeps a server-side or test process alive (Node); browsers have no unref.
+            this.protectionTimer.unref?.();
+        }
+        else if (!wanted) {
+            this.stopProtection();
+        }
+    }
+    stopProtection() {
+        if (this.protectionTimer)
+            clearInterval(this.protectionTimer);
+        this.protectionTimer = null;
+    }
+    async sampleProtection() {
+        const transport = this.recvTransport;
+        if (this.protectionSampling || !transport || transport.closed)
+            return;
+        this.protectionSampling = true;
+        try {
+            const report = await transport.getStats();
+            if (transport !== this.recvTransport || !this.protectionTimer)
+                return;
+            this.protection.feed(readInboundAudio(report.values()));
+        }
+        catch {
+            // Statistics are best effort; the next sample tries again.
+        }
+        finally {
+            this.protectionSampling = false;
+        }
+    }
+    /** Apply adaptive stream's decision for one video: pause it, or resume it at its layer. */
+    async applyAdaptive(producerId, want) {
+        const consumer = this.consumers.get(producerId);
+        // Not received (yet): a consumer made later starts from the decision in force.
+        if (!consumer || consumer.kind !== 'video' || consumer.closed || this.closedByUs)
+            return;
+        try {
+            if (!want.visible) {
+                if (this.pauseUnsupported) {
+                    await this.rpc('setPreferredLayers', { consumerId: consumer.id, spatialLayer: 0, temporalLayer: 0 });
+                    return;
+                }
+                if (this.adaptivePaused.has(producerId))
+                    return;
+                this.adaptivePaused.add(producerId);
+                await this.rpc('pauseConsumer', { consumerId: consumer.id });
+                return;
+            }
+            if (this.adaptivePaused.delete(producerId))
+                await this.rpc('resumeConsumer', { consumerId: consumer.id });
+            await this.rpc('setPreferredLayers', { consumerId: consumer.id, ...this.effectiveLayers(producerId, want) });
+        }
+        catch (err) {
+            if (this.consumers.get(producerId) !== consumer || consumer.closed || this.closedByUs)
+                return;
+            if (!want.visible && err instanceof RpcError && err.code === 'unknown-method') {
+                // An older server: drop to the smallest layer instead of pausing.
+                this.adaptivePaused.delete(producerId);
+                this.pauseUnsupported = true;
+                await this.applyAdaptive(producerId, want);
+                return;
+            }
+            this.emit('error', err);
+        }
     }
     // ------------------------------------------------------------- moderation
     // ------------------------------------------------------------ local media
@@ -2180,21 +3301,63 @@ export class StreamClient {
             this.music?.setEnabled(false);
     }
     async setKindEnabled(kind, enabled) {
-        for (const producer of this.producers.values()) {
-            // The music has its own switch. Muting the microphone must not stop the song.
-            if (producer.kind !== kind || producer.appData.source !== defaultSource(kind))
+        // Your own choice about the camera ends the publisher-side fallback's hold on it: it never undoes your choice.
+        if (kind === 'video' && this.cameraHeldByFallback) {
+            this.cameraHeldByFallback = false;
+            this.publishProtection.reset();
+            this.emit('publishFallback', { fallback: false });
+        }
+        const generation = this.publishGeneration;
+        // Unpublished or closed while waiting: nothing is left to switch, and the
+        // call resolves, as it does with nothing published (V072-03).
+        const ended = () => generation !== this.publishGeneration || this.closedByUs;
+        // The music has its own switch. Muting the microphone must not stop the song.
+        const targets = [...this.producers.values()].filter((p) => p.kind === kind && p.appData.source === defaultSource(kind));
+        for (const producer of targets) {
+            if (ended())
+                return;
+            if (this.producers.get(producer.id) !== producer || producer.closed)
                 continue;
+            const revision = this.moderationRevision[kind];
             if (!enabled)
                 producer.pause();
-            await this.rpc('pauseProducer', { producerId: producer.id, paused: !enabled });
-            if (enabled)
-                producer.resume();
+            try {
+                await this.rpc('pauseProducer', { producerId: producer.id, paused: !enabled });
+            }
+            catch (err) {
+                if (ended())
+                    return;
+                throw err;
+            }
+            if (ended())
+                return;
+            if (!enabled || this.producers.get(producer.id) !== producer || producer.closed)
+                continue;
+            if (revision !== this.moderationRevision[kind] || this.forcedOff[kind]) {
+                // A moderator decided while this waited: the older request does not
+                // undo it. It stays off here, and the server is told so too, since
+                // which of the two it applied last cannot be known from here.
+                void this.rpc('pauseProducer', { producerId: producer.id, paused: true }).catch(() => undefined);
+                this.emitLocalMedia();
+                throw new RpcError('force-muted', `a moderator changed your ${kind} while this request waited; it stays off`);
+            }
+            producer.resume();
         }
         this.emitLocalMedia();
     }
+    /** Record a moderation decision ('' = both kinds). A roster snapshot counts only where it changes what is known. */
+    moderate(kind, paused, snapshot = false) {
+        for (const k of kind ? [kind] : ['audio', 'video']) {
+            if (snapshot && this.forcedOff[k] === paused)
+                continue;
+            this.forcedOff[k] = paused;
+            this.moderationRevision[k] += 1;
+        }
+    }
     /** Stop publishing entirely and release the local devices. */
     async unpublish() {
         void this.stopRecording().catch(error => this.emit('error', error));
+        this.layersNeeded.clear();
         // All of it takes effect now; only telling the server is waited for. So
         // publish() and unpublish() act in the order they are called: a publish
         // called while this still waits is not undone by it, and one already