@unboundcx/video-sdk-client 2.0.6 → 2.0.8

package/VideoMeetingClient.js

@@ -7,6 +7,11 @@ import { RemoteMediaManager } from "./managers/RemoteMediaManager.js";
 import { QualityMonitor } from "./managers/QualityMonitor.js";
 import { ConnectionHealthMonitor } from "./managers/ConnectionHealthMonitor.js";
 import { StateError, RoomError } from "./utils/errors.js";
+import {
+  getVideoQualityProfile,
+  sendConfigChanged,
+  DEFAULT_VIDEO_QUALITY_LEVEL,
+} from "./videoQualityProfiles.js";
 
 /**
  * Main SDK client for video meeting functionality
@@ -43,6 +48,7 @@ export class VideoMeetingClient extends EventEmitter {
     this.state = "disconnected"; // disconnected, connecting, connected, waiting-room, in-meeting
     this.currentRoomId = null;
     this.joinData = null; // Store video.join() response data
+    this.serverInfo = null; // Handling pod identity (serverId/externalIp/geoLocation)
     this.debug = options.debug;
     this.isGuest = false;
     this.inWaitingRoom = false;
@@ -62,6 +68,11 @@ export class VideoMeetingClient extends EventEmitter {
     this.localMedia = null;
     this.remoteMedia = null;
 
+    // Current video quality level (data-saver). 'auto' by default; the host
+    // app maps its "Data saver" toggle to 'medium'/'auto'. See
+    // videoQualityProfiles.js + setVideoQuality().
+    this._videoQualityLevel = DEFAULT_VIDEO_QUALITY_LEVEL;
+
     // If serverUrl provided, initialize managers now (old behavior)
     if (options.serverUrl) {
       this._initializeManagers(options.serverUrl);
@@ -597,6 +608,13 @@ export class VideoMeetingClient extends EventEmitter {
       // Listen for media.routerCapabilities to know when room is ready
       this.connection.onServerEvent("media.routerCapabilities", (data) => {
         this.logger.info("Room is ready - received media.routerCapabilities");
+        // The handling pod stamps its identity (serverId / externalIp /
+        // geoLocation) onto this message — surface it so the app can show
+        // which server is serving this participant.
+        if (data?.serverInfo) {
+          this.serverInfo = data.serverInfo;
+          this.emit("server:info", data.serverInfo);
+        }
         this.emit("waitingRoom:ready", {
           roomId: videoRoom.id,
           participant,
@@ -757,7 +775,87 @@ export class VideoMeetingClient extends EventEmitter {
    */
   async publishCamera(options = {}) {
     this._ensureInRoom();
-    return await this.localMedia.publishCamera(options);
+    // Honor the active quality level so a camera (re)published after the user
+    // set data-saver — e.g. unmuting mid-call — comes up already capped.
+    const profile = getVideoQualityProfile(this._videoQualityLevel);
+    const merged = {
+      resolution: profile.sendResolution || options.resolution,
+      maxResolution: profile.sendResolution || options.maxResolution,
+      frameRate: profile.sendFrameRate || options.frameRate,
+      ...options,
+    };
+    // options passed by the caller still win for explicit overrides, except
+    // we always apply the quality-level send cap on top.
+    if (profile.sendResolution) {
+      merged.resolution = profile.sendResolution;
+      merged.maxResolution = profile.sendResolution;
+      merged.frameRate = profile.sendFrameRate;
+    }
+    return await this.localMedia.publishCamera(merged);
+  }
+
+  /**
+   * Set the video quality level (data-saver / quality tiers). One call fans
+   * out to both directions:
+   *   - receive: sets a shared layer ceiling on the mediasoup + remote media
+   *     managers so we never pull above the cap from any peer (coordinates
+   *     with QualityMonitor — the lower of {auto-selected, cap} always wins).
+   *   - send: re-caps the live camera's capture resolution/frame-rate +
+   *     simulcast top layer, without a full republish (low flicker). Skipped
+   *     when the send config is unchanged (e.g. auto → high).
+   *
+   * Screen share is intentionally untouched in both directions.
+   *
+   * @param {'auto'|'high'|'medium'|'low'} level
+   * @returns {Promise<void>}
+   */
+  async setVideoQuality(level) {
+    const profile = getVideoQualityProfile(level);
+    const prevLevel = this._videoQualityLevel;
+    this._videoQualityLevel = level;
+    this.logger.info("VideoMeetingClient :: setVideoQuality ::", {
+      level,
+      profile,
+    });
+
+    // ---- receive ceiling (applies immediately to existing consumers) ----
+    if (this.mediasoup) {
+      this.mediasoup.setLayerCeiling(
+        profile.maxSpatialLayer,
+        profile.maxTemporalLayer,
+      );
+    }
+    if (this.remoteMedia) {
+      this.remoteMedia.setLayerCeiling(
+        profile.maxSpatialLayer,
+        profile.maxTemporalLayer,
+      );
+    }
+
+    // ---- send cap (only if the capture config actually changed) ----
+    if (
+      sendConfigChanged(prevLevel, level) &&
+      this.localMedia?.isCameraActive
+    ) {
+      try {
+        await this.localMedia.setSendQuality(profile);
+      } catch (err) {
+        this.logger.error(
+          "VideoMeetingClient :: setVideoQuality :: send cap failed",
+          err,
+        );
+      }
+    }
+
+    this.emit("quality:level", { level });
+  }
+
+  /**
+   * Current video quality level.
+   * @returns {'auto'|'high'|'medium'|'low'}
+   */
+  getVideoQualityLevel() {
+    return this._videoQualityLevel;
   }
 
   /**
@@ -1222,6 +1320,13 @@ export class VideoMeetingClient extends EventEmitter {
     const oldState = this.state;
     this.state = newState;
     this.logger.info(`State changed: ${oldState} -> ${newState}`);
+    // Tell the health monitor whether media should be flowing. Media silence
+    // only signals a problem once we're actually in the meeting; before that
+    // (connecting / waiting-room) there's no media by design, so silence must
+    // not escalate to "Connection lost". Socket/transport failures still do.
+    if (this.connectionHealth?.setMediaExpected) {
+      this.connectionHealth.setMediaExpected(newState === "in-meeting");
+    }
     this.emit("state:changed", { from: oldState, to: newState });
   }
 

package/index.js

@@ -18,6 +18,14 @@
 export { VideoMeetingClient } from './VideoMeetingClient.js';
 export { VideoProcessor } from './VideoProcessor.js';
 
+// Video quality tiers (data-saver / quality level)
+export {
+	VIDEO_QUALITY_LEVELS,
+	VIDEO_QUALITY_PROFILES,
+	DEFAULT_VIDEO_QUALITY_LEVEL,
+	getVideoQualityProfile,
+} from './videoQualityProfiles.js';
+
 // Managers (for advanced usage)
 export { ConnectionManager } from './managers/ConnectionManager.js';
 export { MediasoupManager } from './managers/MediasoupManager.js';

package/managers/ConnectionHealthMonitor.js

@@ -74,6 +74,11 @@ export class ConnectionHealthMonitor {
     this._timer = null;
     this._started = false;
     this._unsubs = [];
+    // Whether media should be flowing. Until we're in the meeting (set by
+    // VideoMeetingClient via setMediaExpected), media silence is expected
+    // and must not escalate the state — the pre-join waiting room is quiet
+    // by design. Socket/transport failures still escalate regardless.
+    this._mediaExpected = false;
 
     // Track transport-level state independently of socket-level state so
     // we can report the right reason in the event payload.
@@ -107,6 +112,13 @@ export class ConnectionHealthMonitor {
   // (any socket message, any stats sample). The wiring below already
   // does this for the common cases — exposed for hosts that want to
   // mark explicit liveness pings.
+  // Public: toggled by VideoMeetingClient when entering/leaving the meeting.
+  // Resets the silence clock on enable so the timer starts fresh at join.
+  setMediaExpected(expected) {
+    this._mediaExpected = !!expected;
+    if (this._mediaExpected) this._lastActivityAt = Date.now();
+  }
+
   markActivity() {
     this._lastActivityAt = Date.now();
     // Hearing from the server is sufficient evidence the connection is
@@ -226,12 +238,19 @@ export class ConnectionHealthMonitor {
     // has run long past Socket.IO's own ping timeout (the engine itself
     // is quiet, which is real evidence). This prevents an idle-but-fine
     // session (e.g. host alone in the room) from cascading to "failed".
+    // Silence only counts as a problem once media should be flowing. Before
+    // that (waiting room / pre-join) it's expected, so don't escalate on it.
+    const silenceCounts = this._mediaExpected;
     const hasCorroboration =
       !this._socketAlive ||
       this._transportFailed() ||
-      silence >= this.opts.silenceReconnectingMs;
+      (silenceCounts && silence >= this.opts.silenceReconnectingMs);
 
-    if (this._state === 'connected' && silence >= this.opts.silenceUnstableMs) {
+    if (
+      this._state === 'connected' &&
+      silenceCounts &&
+      silence >= this.opts.silenceUnstableMs
+    ) {
       this._transition('unstable', `silence:${silence}ms`);
     } else if (this._state === 'unstable' && hasCorroboration) {
       this._transition(

package/managers/LocalMediaManager.js

@@ -75,10 +75,46 @@ export class LocalMediaManager extends EventEmitter {
 	async getDevices() {
 		this.logger.log('Getting available devices');
 
+		// Request permission so enumerateDevices() returns device labels. Ask
+		// for audio and video INDEPENDENTLY — a single denied/missing device
+		// (e.g. camera blocked but microphone allowed) must not throw away the
+		// whole list. These temporary tracks exist only to unlock labels, so we
+		// stop them immediately; the published tracks are separate instances.
+		const stopTracks = (stream) => {
+			try {
+				stream?.getTracks().forEach((t) => t.stop());
+			} catch (e) {
+				/* ignore */
+			}
+		};
 		try {
-			// Request permissions first to get device labels
-			await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
+			stopTracks(
+				await navigator.mediaDevices.getUserMedia({ audio: true, video: true }),
+			);
+		} catch (combinedError) {
+			this.logger.log(
+				'getDevices :: combined permission request failed, trying audio and video separately ::',
+				combinedError?.name,
+			);
+			try {
+				stopTracks(await navigator.mediaDevices.getUserMedia({ audio: true }));
+			} catch (audioError) {
+				this.logger.log(
+					'getDevices :: microphone unavailable ::',
+					audioError?.name,
+				);
+			}
+			try {
+				stopTracks(await navigator.mediaDevices.getUserMedia({ video: true }));
+			} catch (videoError) {
+				this.logger.log(
+					'getDevices :: camera unavailable ::',
+					videoError?.name,
+				);
+			}
+		}
 
+		try {
 			const devices = await navigator.mediaDevices.enumerateDevices();
 
 			const result = {
@@ -95,7 +131,7 @@ export class LocalMediaManager extends EventEmitter {
 
 			return result;
 		} catch (error) {
-			this.logger.error('Failed to get devices:', error);
+			this.logger.error('Failed to enumerate devices:', error);
 			throw wrapError(error, 'getDevices');
 		}
 	}
@@ -824,6 +860,162 @@ export class LocalMediaManager extends EventEmitter {
 		}
 	}
 
+	/**
+	 * Apply a send-side quality cap (data-saver / quality level) to the live
+	 * camera WITHOUT a full republish/renegotiation. Two coordinated moves:
+	 *
+	 *   1. Re-acquire the camera at the capped capture resolution + frame
+	 *      rate and replaceTrack() it into the existing producer. Lowering
+	 *      actual capture is what saves CPU, battery and capture-side
+	 *      bandwidth — disabling a simulcast layer alone keeps encoding the
+	 *      full-res frame.
+	 *   2. Cap the simulcast top layer via setParameters (deactivate
+	 *      encodings whose source res now exceeds the cap), so we don't pay
+	 *      1080p-tier bits to ship a 540p picture.
+	 *
+	 * Same device, same background, no transport renegotiation → far less
+	 * visible than tearing the producer down and re-publishing. No-op if the
+	 * camera isn't currently active.
+	 *
+	 * @param {Object} profile - from videoQualityProfiles.js
+	 * @param {string|null} profile.sendResolution - '360p'|'540p'|'720p'|'1080p'|null
+	 * @param {number} profile.sendFrameRate
+	 * @returns {Promise<void>}
+	 */
+	async setSendQuality(profile = {}) {
+		if (!this.producers.video || !this.streams.camera) {
+			this.logger.info(
+				'LocalMediaManager :: setSendQuality :: no active camera, skipping'
+			);
+			return;
+		}
+
+		const oldProcessedStream = this.streams.camera;
+		const oldRawStream = this.rawCameraStream;
+
+		try {
+			// Re-acquire at the capped capture constraints, reusing the current
+			// device/facingMode (cameraSource) so we don't switch cameras.
+			const reacquireOptions = {
+				...(this.cameraSource || {}),
+				resolution: profile.sendResolution || undefined,
+				frameRate: profile.sendFrameRate || undefined,
+			};
+			const constraints = this._getVideoConstraints(reacquireOptions);
+			this.logger.info(
+				'LocalMediaManager :: setSendQuality :: re-acquiring camera',
+				{ sendResolution: profile.sendResolution, frameRate: profile.sendFrameRate }
+			);
+
+			const rawStream = await navigator.mediaDevices.getUserMedia({
+				video: constraints,
+			});
+
+			let stream = rawStream;
+			if (this.currentBackgroundOptions) {
+				try {
+					await this.videoProcessor.cleanup();
+				} catch (cleanupErr) {
+					this.logger.warn(
+						'LocalMediaManager :: setSendQuality :: processor cleanup failed',
+						cleanupErr
+					);
+				}
+				stream = await this.videoProcessor.applyBackground(
+					rawStream,
+					this.currentBackgroundOptions
+				);
+			}
+
+			const newTrack = stream.getVideoTracks()[0];
+			await this.producers.video.replaceTrack({ track: newTrack });
+			this._watchCameraTrack(newTrack);
+
+			// Stop the old streams now that the new track is live.
+			if (oldRawStream && oldRawStream !== rawStream) {
+				oldRawStream.getTracks().forEach((t) => t.stop());
+			}
+			if (
+				oldProcessedStream &&
+				oldProcessedStream !== oldRawStream &&
+				oldProcessedStream !== stream
+			) {
+				oldProcessedStream.getTracks().forEach((t) => t.stop());
+			}
+
+			this.streams.camera = stream;
+			this.rawCameraStream = rawStream;
+
+			// Cap the simulcast top layer to match the new capture resolution.
+			this._capSendSimulcastToResolution(profile.sendResolution);
+
+			this.logger.info('LocalMediaManager :: setSendQuality :: applied', {
+				resolution: `${newTrack.getSettings().width}x${newTrack.getSettings().height}`,
+				frameRate: newTrack.getSettings().frameRate,
+			});
+
+			this.emit('stream:added', {
+				type: 'camera',
+				stream,
+				producer: this.producers.video,
+			});
+		} catch (error) {
+			this.logger.error(
+				'LocalMediaManager :: setSendQuality :: failed',
+				error
+			);
+			throw wrapError(error, 'setSendQuality');
+		}
+	}
+
+	/**
+	 * Deactivate simulcast encodings whose source resolution exceeds the cap,
+	 * via RTCRtpSender.setParameters (no renegotiation). null/'1080p' = no cap
+	 * (reactivate everything). Mirrors QualityMonitor's outbound capping but
+	 * keyed off a user-chosen resolution rather than a 'mid'|'low' target.
+	 * @private
+	 * @param {string|null} sendResolution
+	 */
+	_capSendSimulcastToResolution(sendResolution) {
+		const sender = this.producers.video?.rtpSender;
+		if (!sender || typeof sender.getParameters !== 'function') return;
+
+		// rid → approx source width at 1080p capture (l=1/4, m=1/2, h=full).
+		// Keep a layer active only if its width is within the cap.
+		const capWidth =
+			{ '360p': 640, '540p': 960, '720p': 1280 }[sendResolution] || Infinity;
+
+		try {
+			const params = sender.getParameters();
+			if (!params.encodings || params.encodings.length < 2) return;
+			let changed = false;
+			for (const enc of params.encodings) {
+				// scaleResolutionDownBy tells us this layer's output width
+				// relative to the captured frame; below the cap stays active.
+				const settings = this.streams.camera?.getVideoTracks()[0]?.getSettings();
+				const captureWidth = settings?.width || 1920;
+				const layerWidth = captureWidth / (enc.scaleResolutionDownBy || 1);
+				const wantActive = layerWidth <= capWidth + 1; // +1 for rounding
+				if (enc.active !== wantActive) {
+					enc.active = wantActive;
+					changed = true;
+				}
+			}
+			if (changed) {
+				sender.setParameters(params);
+				this.logger.info(
+					'LocalMediaManager :: _capSendSimulcastToResolution ::',
+					{ sendResolution, capWidth }
+				);
+			}
+		} catch (err) {
+			this.logger.warn(
+				'LocalMediaManager :: _capSendSimulcastToResolution failed',
+				err
+			);
+		}
+	}
+
 	/**
 	 * Update background effect on active camera
 	 * @param {Object} options - Background options
@@ -1090,7 +1282,9 @@ export class LocalMediaManager extends EventEmitter {
 	 */
 	_getVideoConstraints(options = {}) {
 		const resolutions = {
+			'360p': { width: 640, height: 360 },
 			'480p': { width: 640, height: 480 },
+			'540p': { width: 960, height: 540 },
 			'720p': { width: 1280, height: 720 },
 			'1080p': { width: 1920, height: 1080 },
 		};

package/managers/MediasoupManager.js

@@ -33,6 +33,11 @@ export class MediasoupManager extends EventEmitter {
     this.producers = new Map(); // Map<type, Producer>
     this.consumers = new Map(); // Map<consumerId, Consumer>
 
+    // Receive-side quality ceiling (data-saver / quality level). Enforced in
+    // setPeerPreferredLayer so every inbound-layer request is bounded. null =
+    // no cap. See videoQualityProfiles.js + RemoteMediaManager.setLayerCeiling.
+    this.layerCeiling = { maxSpatialLayer: null, maxTemporalLayer: null };
+
     // Initialize stats collector
     this.statsCollector = new StatsCollector(this.logger);
     this.virtualBackgroundStore = null; // Will be set externally
@@ -580,19 +585,32 @@ export class MediasoupManager extends EventEmitter {
           // No `return` — we still want to call transport.produce().
         } else {
 
-        // Check if user has set a max resolution preference
+        // Check if user has set a max resolution preference (data-saver /
+        // quality level). The top simulcast layer is capped to this; lower
+        // layers scale from it. Bitrate budget tracks the cap so we don't
+        // pay 1080p bits to send a 540p top layer.
         const maxResolution = options.maxResolution || "1080p"; // Default to 1080p
 
+        // Resolution caps → { width, bitrate } for the top (h) layer. Only
+        // applied when the captured track is actually larger than the cap.
+        const RES_CAPS = {
+          "360p": { width: 640, bitrate: 400000 },
+          "540p": { width: 960, bitrate: 1000000 },
+          "720p": { width: 1280, bitrate: 2000000 },
+          "1080p": { width: 1920, bitrate: 3500000 },
+        };
+
         // Calculate target resolution based on user preference
         let targetWidth = baseWidth;
         let targetHeight = baseHeight;
         let targetBitrate = 3500000;
 
-        if (maxResolution === "720p" && baseWidth > 1280) {
-          // User prefers 720p max - scale down from 1080p
-          targetWidth = 1280;
-          targetHeight = 720;
-          targetBitrate = 2000000;
+        const cap = RES_CAPS[maxResolution];
+        if (cap && baseWidth > cap.width) {
+          // Scale the top layer down to the cap, preserving aspect ratio.
+          targetHeight = Math.round((baseHeight * cap.width) / baseWidth);
+          targetWidth = cap.width;
+          targetBitrate = cap.bitrate;
         }
 
         // Adaptive simulcast configuration based on target resolution
@@ -855,8 +873,13 @@ export class MediasoupManager extends EventEmitter {
       producer.close();
       this.producers.delete(type);
 
-      // Notify server with correct event name and format
-      await this.connection.request("media.produce.close", {
+      // Notify server. Event name is `media.produceClose` (camelCase
+       // suffix) — must match the handler registration in app1-socket's
+       // /video routes and app1-video-server's NATS handler map. A dotted
+       // variant ("media.produce.close") gets silently dropped server-side
+       // and the SDK then times out after 5s with the producer still
+       // active on the SFU — remote consumers see a frozen frame.
+      await this.connection.request("media.produceClose", {
         producer: {
           id: producer.id,
           producerType: type,
@@ -1055,6 +1078,20 @@ export class MediasoupManager extends EventEmitter {
    */
   setPeerPreferredLayer(peerParticipantId, spatialLayer) {
     if (!this.connection?.socket) return false;
+    // Apply the user's quality ceiling (data-saver). This is the single
+    // chokepoint every layer request flows through — the resize
+    // auto-selector AND QualityMonitor's inbound uncap (which asks for
+    // spatialLayer 2) both land here — so clamping once keeps every caller
+    // bounded. The lower of {requested, ceiling} always wins.
+    const spatial =
+      this.layerCeiling.maxSpatialLayer == null
+        ? spatialLayer
+        : Math.min(spatialLayer, this.layerCeiling.maxSpatialLayer);
+    const temporal =
+      this.layerCeiling.maxTemporalLayer == null
+        ? 2
+        : Math.min(2, this.layerCeiling.maxTemporalLayer);
+
     // Find every consumer whose producer belongs to this peer. We may
     // have a video + a screenshare consumer for the same peer; we cap
     // only kind='video' to avoid clobbering screen share quality.
@@ -1064,13 +1101,23 @@ export class MediasoupManager extends EventEmitter {
       if (consumer.appData?.participantId !== peerParticipantId) continue;
       this.connection.socket.emit("media.consumer.setPreferredLayers", {
         consumer: { id: consumer.id },
-        preferredLayers: { spatialLayer, temporalLayer: 2 },
+        preferredLayers: { spatialLayer: spatial, temporalLayer: temporal },
       });
       sent = true;
     }
     return sent;
   }
 
+  /**
+   * Set the receive-side quality ceiling enforced in setPeerPreferredLayer.
+   * null for either value lifts that ceiling. Data-saver / quality level.
+   * @param {number|null} maxSpatialLayer
+   * @param {number|null} maxTemporalLayer
+   */
+  setLayerCeiling(maxSpatialLayer, maxTemporalLayer) {
+    this.layerCeiling = { maxSpatialLayer, maxTemporalLayer };
+  }
+
   /**
    * Pause/resume the local consumer AND ask the SFU to stop/start
    * forwarding bytes for this peer's video. Local pause alone would

package/managers/QualityMonitor.js

@@ -30,11 +30,15 @@
 // quality-monitor-thresholds.test.js for the user-visible reaction
 // times these collectively produce.
 const DEFAULTS = {
-  // SignalState gates — outer gate per level transition. Tuned to be
-  // patient: a blip that clears within ~20s isn't worth telling the
-  // user about; below that we let the SDK adapt invisibly.
-  warnSustainedMs: 20000,
-  critSustainedMs: 35000,
+  // SignalState gates — outer gate per level transition. Kept in line with
+  // the inner encoder gates (encoderConstrainedMs / encoderSevereConstrainedMs)
+  // and the user-visible reaction times asserted in
+  // quality-monitor-thresholds.test.js: a silent cap / warning within ~10s of
+  // sustained badness, critical within ~25s. Short enough to feel Meet/Zoom-
+  // fast, long enough that momentary BWE blips don't toast — the recovery hold
+  // + per-level toast cooldown below absorb flapping.
+  warnSustainedMs: 8000,
+  critSustainedMs: 20000,
   // network thresholds (round trip)
   rttWarnMs: 300,
   rttCritMs: 500,
@@ -412,10 +416,18 @@ export class QualityMonitor {
             maxLoss >= this.thresholds.lossWarnRatio
           ? 1
           : 0;
+    // Bandwidth-pressure signals (the available-outgoing-bitrate floor and
+    // the encoder bandwidth-limited ratio) are only meaningful when we're
+    // actually sending video. With the camera off/denied, Chrome's BWE has
+    // nothing to probe and availableOutgoingBitrate reads artificially low —
+    // counting that as a bad network wrongly marks audio-only participants
+    // "poor" and triggers a disable-camera suggestion for a camera that's
+    // already off. RTT + loss remain valid either way.
     // Only count availMbps once we've seen a real reading (>0); some
     // browsers report 0 transiently at session start.
-    const bandwidthSeverity =
-      availMbps > 0 && availMbps <= this.thresholds.availMbpsCrit
+    const bandwidthSeverity = !this._isSendingVideo()
+      ? 0
+      : availMbps > 0 && availMbps <= this.thresholds.availMbpsCrit
         ? 2
         : bwLimitedRatio >= this.thresholds.encoderBwLimitedCritRatio
           ? 2
@@ -585,6 +597,7 @@ export class QualityMonitor {
     // pressure (availMbps + encoder-bw-limited ratio), so throttled
     // uplinks correctly drive network → critical alongside outbound.
     const triggerCritical =
+      this._isSendingVideo() &&
       this.outbound.level === "critical" &&
       this.network.level === "critical";
     const t = now();
@@ -763,6 +776,17 @@ export class QualityMonitor {
     return null;
   }
 
+  // Are we actively sending video right now (producer exists and isn't
+  // paused/closed)? Used to suppress encoder/bandwidth-pressure signals and
+  // the disable-camera suggestion when the camera is off or denied — Chrome's
+  // available-outgoing-bitrate reads artificially low with nothing to send,
+  // which would otherwise flag an audio-only participant's network as "poor"
+  // and even suggest disabling a camera that's already off.
+  _isSendingVideo() {
+    const p = this._findVideoProducer();
+    return !!(p && !p.closed && !p.paused);
+  }
+
   _emit(evt) {
     // Always log into the debug ring, even if onQualityEvent throws.
     try {

package/managers/RemoteMediaManager.js

@@ -39,12 +39,28 @@ export class RemoteMediaManager extends EventEmitter {
 		// Queue for producers that arrived before transports were ready
 		this.pendingProducers = [];
 
+		// Producer ids currently being consumed (in-flight). A producer can be
+		// announced via both the pending queue and a re-sent media.producer.created
+		// after room.join; consuming it twice yields two consumers with the same
+		// msid, which makes setRemoteDescription fail ("Duplicate a=msid lines").
+		this.consumingProducers = new Set();
+
 		// Server event listeners will be set up after socket connects
 		this.listenersSetup = false;
 
 		// Map of video element observers: participantId -> { element, observer, lastWidth, lastHeight }
 		this.videoElementTracking = new Map();
 
+		// User-chosen quality ceiling (data-saver / quality level). These cap
+		// what we'll accept from EVERY remote peer, on top of the size-based
+		// auto-selection and QualityMonitor's bad-network capping. null = no
+		// ceiling (default). Whoever wants the LOWER layer wins, so a ceiling
+		// here can never raise quality — it only ever lowers it. Set via
+		// setLayerCeiling(); both the resize auto-selector and QualityMonitor
+		// clamp through clampSpatialLayer()/clampTemporalLayer().
+		this.maxSpatialLayer = null;
+		this.maxTemporalLayer = null;
+
 		// Map of local mute states for remote streams: `${participantId}:${type}` -> boolean
 		this.localMuteStates = new Map();
 
@@ -237,10 +253,25 @@ export class RemoteMediaManager extends EventEmitter {
 			// Wait for device and transports to be ready before consuming
 			// Transports are created when media.transports event arrives from server
 			if (!this.mediasoup.device.loaded || !this.mediasoup.recvTransport) {
-				this.logger.warn('Device or transport not ready yet, queuing producer:', producer.id);
-				this.pendingProducers.push({ producer, participant });
+				if (!this.pendingProducers.some((p) => p.producer.id === producer.id)) {
+					this.logger.warn('Device or transport not ready yet, queuing producer:', producer.id);
+					this.pendingProducers.push({ producer, participant });
+				}
+				return;
+			}
+
+			// Skip if we're already consuming this producer or already have a
+			// consumer for it. Without this, a producer announced via both the
+			// pending queue and a re-sent media.producer.created gets consumed
+			// twice → duplicate msid → setRemoteDescription parse failure.
+			if (
+				this.consumingProducers.has(producer.id) ||
+				this._isProducerConsumed(producer.id)
+			) {
+				this.logger.info('Skipping duplicate consume for producer:', producer.id);
 				return;
 			}
+			this.consumingProducers.add(producer.id);
 
 			// Emit event to let UI know we're attempting to consume a stream
 			const streamType = producer.producerType || producer.type || 'unknown';
@@ -324,7 +355,22 @@ export class RemoteMediaManager extends EventEmitter {
 				error: error.message,
 				canRetryManually: true
 			});
+		} finally {
+			// Clear the in-flight marker. On success the consumers map now tracks
+			// it (see _isProducerConsumed); on failure it's free to retry.
+			this.consumingProducers.delete(producer.id);
+		}
+	}
+
+	/**
+	 * Whether we already hold a consumer for this producer id.
+	 * @private
+	 */
+	_isProducerConsumed(producerId) {
+		for (const data of this.consumers.values()) {
+			if (data.producerId === producerId) return true;
 		}
+		return false;
 	}
 
 	/**
@@ -488,9 +534,66 @@ export class RemoteMediaManager extends EventEmitter {
 			(typeof window !== 'undefined' && window.devicePixelRatio) || 1;
 		const maxPx = Math.max(width || 0, height || 0) * dpr;
 
-		if (maxPx <= 480) return 0; // ≤480 px → 270p source suffices
-		if (maxPx <= 960) return 1; // ≤960 px → 540p source suffices
-		return 2; // larger → need 1080p source
+		let layer;
+		if (maxPx <= 480) layer = 0; // ≤480 px → 270p source suffices
+		else if (maxPx <= 960) layer = 1; // ≤960 px → 540p source suffices
+		else layer = 2; // larger → need 1080p source
+
+		// Apply the user's quality ceiling (data-saver). A large tile on a
+		// metered connection should still be served the capped layer.
+		return this.clampSpatialLayer(layer);
+	}
+
+	/**
+	 * Clamp a desired spatial layer to the user's ceiling. The lower of the
+	 * two always wins, so callers (resize auto-selector, QualityMonitor) can
+	 * request whatever they think is optimal and never exceed the cap.
+	 * @param {number} layer - Desired spatial layer (0-2)
+	 * @returns {number}
+	 */
+	clampSpatialLayer(layer) {
+		if (this.maxSpatialLayer == null) return layer;
+		return Math.min(layer, this.maxSpatialLayer);
+	}
+
+	/**
+	 * Clamp a desired temporal layer to the user's ceiling. See clampSpatialLayer.
+	 * @param {number} layer - Desired temporal layer (0-2)
+	 * @returns {number}
+	 */
+	clampTemporalLayer(layer) {
+		if (this.maxTemporalLayer == null) return layer;
+		return Math.min(layer, this.maxTemporalLayer);
+	}
+
+	/**
+	 * Set the user-chosen quality ceiling (data-saver / quality level) and
+	 * immediately re-apply it to every consumer we're currently tracking, so
+	 * a mid-call toggle takes effect right away. Pass null for either value to
+	 * lift that ceiling.
+	 * @param {number|null} maxSpatialLayer - 0-2 or null for no cap
+	 * @param {number|null} maxTemporalLayer - 0-2 or null for no cap
+	 */
+	setLayerCeiling(maxSpatialLayer, maxTemporalLayer) {
+		this.maxSpatialLayer = maxSpatialLayer;
+		this.maxTemporalLayer = maxTemporalLayer;
+		this.logger.info('RemoteMediaManager :: Set Layer Ceiling ::', {
+			maxSpatialLayer,
+			maxTemporalLayer,
+		});
+
+		// Re-evaluate every tracked element against the new ceiling. We
+		// recompute from the element's current size so lifting the cap also
+		// restores the size-appropriate layer, not just lowers it.
+		for (const [participantId, tracking] of this.videoElementTracking) {
+			const consumer = this._getVideoConsumerForParticipant(participantId);
+			if (!consumer) continue;
+			const optimalLayer = this._calculateOptimalSpatialLayer(
+				tracking.element.clientWidth,
+				tracking.element.clientHeight
+			);
+			this._updateConsumerLayers(consumer, optimalLayer);
+		}
 	}
 
 	/**
@@ -624,17 +727,21 @@ export class RemoteMediaManager extends EventEmitter {
 		}
 
 		try {
-			// Set preferred layers: spatialLayer and temporalLayer
-			// temporalLayer 2 = highest frame rate for the spatial layer
+			// spatialLayer is already clamped by callers via
+			// _calculateOptimalSpatialLayer/clampSpatialLayer. temporalLayer 2
+			// is the highest frame rate for the spatial layer; clamp it to the
+			// user's ceiling (data-saver low → ≈half frame rate).
+			const spatial = this.clampSpatialLayer(spatialLayer);
+			const temporal = this.clampTemporalLayer(2);
 			await consumer.setPreferredLayers({
-				spatialLayer: spatialLayer,
-				temporalLayer: 2,
+				spatialLayer: spatial,
+				temporalLayer: temporal,
 			});
 
 			this.logger.log('RemoteMediaManager :: Updated Consumer Layers ::', {
 				consumerId: consumer.id,
-				spatialLayer,
-				temporalLayer: 2,
+				spatialLayer: spatial,
+				temporalLayer: temporal,
 			});
 		} catch (error) {
 			this.logger.error('RemoteMediaManager :: Failed to Update Consumer Layers ::', error);

package/managers/StatsCollector.js

@@ -355,6 +355,10 @@ export class StatsCollector {
           network.local.type = localCandidate.networkType;
           network.local.port = localCandidate.port;
           network.local.protocol = localCandidate.protocol;
+          // host | srflx | prflx | relay — 'relay' means traffic is going
+          // through a TURN server, a strong "why is it slow" signal.
+          network.local.candidateType = localCandidate.candidateType;
+          network.local.relayProtocol = localCandidate.relayProtocol;
         }
 
         const remoteCandidate = stats.get(candidate.remoteCandidateId);
@@ -362,7 +366,13 @@ export class StatsCollector {
           network.remote.wanIp = remoteCandidate.ip;
           network.remote.port = remoteCandidate.port;
           network.remote.protocol = remoteCandidate.protocol;
+          network.remote.candidateType = remoteCandidate.candidateType;
         }
+
+        // Relay in use if either end of the nominated pair is a TURN relay.
+        network.relay =
+          localCandidate?.candidateType === 'relay' ||
+          remoteCandidate?.candidateType === 'relay';
       }
     }
 
@@ -395,6 +405,7 @@ export class StatsCollector {
             audioStats.totalPacketSendDelay = this.validateNumber(
               report.totalPacketSendDelay,
             );
+            audioStats.nackCount = this.validateNumber(report.nackCount);
           } else if (
             report.type === 'remote-inbound-rtp' ||
             report.type === 'inbound-rtp'
@@ -432,6 +443,12 @@ export class StatsCollector {
             videoStats.qLdOther = report?.qualityLimitationDurations?.other;
             videoStats.qlResolutionChanges =
               report?.qualityLimitationResolutionChanges;
+            videoStats.qualityLimitationReason =
+              report?.qualityLimitationReason;
+            // Retransmits / keyframe requests — congestion + loss indicators.
+            videoStats.nackCount = this.validateNumber(report.nackCount);
+            videoStats.pliCount = this.validateNumber(report.pliCount);
+            videoStats.firCount = this.validateNumber(report.firCount);
           } else if (report.type === 'remote-inbound-rtp') {
             videoStats.jitter = this.validateNumber(report.jitter);
             videoStats.roundTripTime = this.validateNumber(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unboundcx/video-sdk-client",
-	"version": "2.0.6",
+	"version": "2.0.8",
 	"description": "Framework-agnostic WebRTC video meeting SDK powered by mediasoup",
 	"type": "module",
 	"main": "index.js",
@@ -43,6 +43,7 @@
 	"files": [
 		"index.js",
 		"VideoMeetingClient.js",
+		"videoQualityProfiles.js",
 		"VideoProcessor.js",
 		"AudioMixer.js",
 		"managers/",

package/videoQualityProfiles.js

@@ -0,0 +1,100 @@
+// Video quality tiers — single source of truth for the data-saver / quality
+// selection feature. The UI surfaces a simple "Data saver" toggle, but the SDK
+// is built around a richer set of named levels so we can expose finer control
+// (an Auto/Low/Medium/High dropdown) later without touching the managers.
+//
+// A profile describes BOTH directions:
+//
+//   send  — how we publish our own camera:
+//             sendResolution  capture/encode resolution cap (getUserMedia +
+//                             simulcast top layer). null = no cap (use device
+//                             default / 1080p).
+//             sendFrameRate   capture frame-rate cap.
+//
+//   receive — the ceiling on what we pull from every remote peer:
+//             maxSpatialLayer   highest simulcast spatial layer we'll accept
+//                               (0=≈270p, 1=≈540p, 2=≈1080p). null = no ceiling
+//                               (size-based auto-selection, today's behavior).
+//             maxTemporalLayer  highest temporal (frame-rate) layer we'll
+//                               accept (2=full, 1=≈half, 0=≈quarter). null =
+//                               no ceiling.
+//
+// Screen share is intentionally NOT governed by these profiles — shared text
+// must stay legible, so the screen-share producer/consumers always run at their
+// own high-quality single-layer profile regardless of the selected level.
+
+/** @typedef {'auto'|'high'|'medium'|'low'} VideoQualityLevel */
+
+export const VIDEO_QUALITY_LEVELS = ['auto', 'high', 'medium', 'low'];
+
+export const DEFAULT_VIDEO_QUALITY_LEVEL = 'auto';
+
+// resolution presets reference the same keys LocalMediaManager._getVideoConstraints
+// understands ('360p' | '540p' | '720p' | '1080p').
+export const VIDEO_QUALITY_PROFILES = Object.freeze({
+  // Size-based auto-selection on receive; full quality on send. This is the
+  // historical default behaviour — no ceilings imposed.
+  auto: {
+    label: 'Auto',
+    sendResolution: null, // device default (≈1080p)
+    sendFrameRate: 30,
+    maxSpatialLayer: null, // no ceiling — tile-size auto-selection wins
+    maxTemporalLayer: null,
+  },
+  // Explicit "best" — same caps as auto but pins send to 1080p rather than
+  // whatever the device defaults to. Useful as the OFF target if we ever want
+  // to force-max instead of auto.
+  high: {
+    label: 'High',
+    sendResolution: '1080p',
+    sendFrameRate: 30,
+    maxSpatialLayer: 2,
+    maxTemporalLayer: 2,
+  },
+  // The "Data saver" target. Meaningful savings, still very usable face video.
+  medium: {
+    label: 'Medium',
+    sendResolution: '540p',
+    sendFrameRate: 30,
+    maxSpatialLayer: 1, // never accept the 1080p layer from anyone
+    maxTemporalLayer: 2,
+  },
+  // Aggressive savings for genuinely tight / CPU-constrained connections.
+  low: {
+    label: 'Low',
+    sendResolution: '360p',
+    sendFrameRate: 15,
+    maxSpatialLayer: 0, // lowest layer only
+    maxTemporalLayer: 1, // ≈half frame-rate on receive
+  },
+});
+
+/**
+ * Resolve a level name to its profile, falling back to the default for unknown
+ * input so callers never have to null-check.
+ * @param {VideoQualityLevel} level
+ * @returns {typeof VIDEO_QUALITY_PROFILES.auto}
+ */
+export function getVideoQualityProfile(level) {
+  return (
+    VIDEO_QUALITY_PROFILES[level] ||
+    VIDEO_QUALITY_PROFILES[DEFAULT_VIDEO_QUALITY_LEVEL]
+  );
+}
+
+/**
+ * True when the two levels would produce a different *send* configuration
+ * (capture resolution or frame-rate). Used to skip a needless camera republish
+ * when only the receive ceiling changed (e.g. auto → high).
+ * @param {VideoQualityLevel} a
+ * @param {VideoQualityLevel} b
+ * @returns {boolean}
+ */
+export function sendConfigChanged(a, b) {
+  const pa = getVideoQualityProfile(a);
+  const pb = getVideoQualityProfile(b);
+  return (
+    pa.sendResolution !== pb.sendResolution ||
+    pa.sendFrameRate !== pb.sendFrameRate
+  );
+}