@unboundcx/video-sdk-client 2.0.3 → 2.0.5

package/VideoMeetingClient.js

@@ -206,6 +206,14 @@ export class VideoMeetingClient extends EventEmitter {
       this.emit("device:changed", data);
     });
 
+    this.localMedia.on("camera:degraded", (data) => {
+      this.emit("camera:degraded", data);
+    });
+
+    this.localMedia.on("camera:restarted", (data) => {
+      this.emit("camera:restarted", data);
+    });
+
     // Remote media events
     this.remoteMedia.on("participant:added", (data) => {
       this.emit("participant:joined", data);
@@ -882,6 +890,21 @@ export class VideoMeetingClient extends EventEmitter {
     return await this.localMedia.updateCameraBackground(options);
   }
 
+  /**
+   * Restart the local camera in place. Use after a 'camera:degraded'
+   * event, or as a user-triggered recovery from a frozen video state.
+   * Re-acquires the camera, reapplies any active background, and
+   * replaces the track on the existing producer (no renegotiation).
+   *
+   * @param {Object} [options] - Optional deviceId/facingMode override.
+   *                             If omitted, reuses the last-known camera source.
+   * @returns {Promise<MediaStream>}
+   */
+  async restartCamera(options) {
+    this._ensureInRoom();
+    return await this.localMedia.restartCamera(options);
+  }
+
   /**
    * Mute camera
    * @returns {Promise<void>}

package/managers/LocalMediaManager.js

@@ -229,12 +229,11 @@ export class LocalMediaManager extends EventEmitter {
 			// Store stream
 			this.streams.camera = stream;
 
-			// Setup track ended handler
-			track.addEventListener('ended', () => {
-				this.logger.warn('Camera track ended');
-				this.emit('track:ended', { type: 'camera' });
-				this.streams.camera = null;
-			});
+			// Attach health watchers (ended / muted) on the producer's
+			// current track. _watchCameraTrack handles both ended and
+			// browser-side mute (which is distinct from user mute and
+			// indicates the OS took the camera, USB unplug, etc.).
+			this._watchCameraTrack(track);
 
 			// Publish to mediasoup
 			const producer = await this.mediasoup.produce(track, {
@@ -367,9 +366,19 @@ export class LocalMediaManager extends EventEmitter {
 			// Get display media
 			// Note: Audio is only available when sharing a Chrome Tab or Window (not Screen)
 			// Chrome will show an audio checkbox for Tab and Window sharing if audio is requested
+			//
+			// Video constraints: cap at 1920×1080 / 15fps so a huge external
+			// monitor or 4K display doesn't push absurd amounts of bandwidth
+			// or compute. 15fps is plenty for screen content (text + UI
+			// changes infrequently); the encoder profile in MediasoupManager
+			// uses degradationPreference="maintain-resolution" so the
+			// browser keeps the pixels sharp and drops frames if it has to.
 			const constraints = {
 				video: {
 					cursor: 'always',
+					width: { max: 1920 },
+					height: { max: 1080 },
+					frameRate: { ideal: 15, max: 30 },
 				},
 				// Request audio with processing disabled for system audio
 				// System audio should not have echo cancellation, noise suppression, or auto gain control
@@ -757,6 +766,7 @@ export class LocalMediaManager extends EventEmitter {
 
 			// Replace track in producer
 			await this.producers.video.replaceTrack({ track: newTrack });
+			this._watchCameraTrack(newTrack);
 
 			// If producer was paused (camera muted), resume it
 			// When user manually changes camera, they likely want to use it
@@ -867,6 +877,7 @@ export class LocalMediaManager extends EventEmitter {
 
 				const newTrack = newStream.getVideoTracks()[0];
 				await this.producers.video.replaceTrack({ track: newTrack });
+				this._watchCameraTrack(newTrack);
 
 				// Commit new state, then tear down old.
 				this.streams.camera = newStream;
@@ -929,6 +940,7 @@ export class LocalMediaManager extends EventEmitter {
 			const newTrack = processedStream.getVideoTracks()[0];
 
 			await this.producers.video.replaceTrack({ track: newTrack });
+			this._watchCameraTrack(newTrack);
 
 			// Commit new state.
 			this.currentBackgroundOptions = options;
@@ -1166,6 +1178,165 @@ export class LocalMediaManager extends EventEmitter {
 		return this.muteState.microphone;
 	}
 
+	/**
+	 * Attach health watchers to the producer's current video track.
+	 *
+	 * Emits:
+	 *   - 'track:ended' { type: 'camera' }   — kept for back-compat
+	 *   - 'camera:degraded' { reason, track } — track is no longer
+	 *       delivering frames (ended, OS-level muted, etc.). Remotes
+	 *       will see a frozen frame until the producer is paused or the
+	 *       track is replaced via restartCamera().
+	 *
+	 * The 'mute' event here is the browser's own muting (camera taken
+	 * over by another app, USB unplug, OS privacy switch) — distinct
+	 * from the user pressing our mute button.
+	 */
+	_watchCameraTrack(track) {
+		if (!track) return;
+		// Stash so subsequent watchers can replace listeners cleanly.
+		if (this._watchedCameraTrack === track) return;
+		this._watchedCameraTrack = track;
+
+		const onEnded = () => {
+			this.logger.warn('Camera track ended');
+			this.emit('track:ended', { type: 'camera' });
+			if (this.streams.camera) this.streams.camera = null;
+			this.emit('camera:degraded', { reason: 'ended', track });
+		};
+		const onMute = () => {
+			this.logger.warn('Camera track muted (browser-side)');
+			this.emit('camera:degraded', { reason: 'muted', track });
+		};
+
+		track.addEventListener('ended', onEnded);
+		track.addEventListener('mute', onMute);
+	}
+
+	/**
+	 * Restart the local camera in place.
+	 *
+	 * Re-acquires the camera via `cameraSource` (or any caller-supplied
+	 * deviceId/facingMode), reapplies the current background if one was
+	 * active, and `replaceTrack`s the live producer. Use this when
+	 * 'camera:degraded' has fired or the user manually clicks "Restart
+	 * camera" after a freeze.
+	 *
+	 * Does NOT change isCameraMuted. If the producer was paused on
+	 * degradation, the caller is responsible for resuming it once the
+	 * new track is in place (we resume here automatically for ergonomics).
+	 *
+	 * @param {Object} [options] - Optional deviceId/facingMode override.
+	 * @returns {Promise<MediaStream>} New camera stream.
+	 */
+	async restartCamera(options = {}) {
+		this.logger.info('Restarting camera', options);
+
+		if (!this.producers.video) {
+			throw new Error('No active camera producer to restart');
+		}
+
+		const source =
+			Object.keys(options).length > 0 ? options : this.cameraSource || {};
+
+		const oldProcessedStream = this.streams.camera;
+		const oldRawStream = this.rawCameraStream;
+
+		try {
+			const constraints = this._getVideoConstraints(source);
+			let rawStream;
+			try {
+				rawStream = await navigator.mediaDevices.getUserMedia({
+					video: constraints,
+				});
+			} catch (err) {
+				if (
+					err.name === 'OverconstrainedError' ||
+					err.name === 'ConstraintNotSatisfiedError'
+				) {
+					this.logger.warn(
+						'Restart hit constraints, retrying with ideal-only:',
+						err.constraint,
+					);
+					const fallback = {
+						...(source.deviceId ? { deviceId: { exact: source.deviceId } } : {}),
+						...(source.facingMode
+							? { facingMode: { exact: source.facingMode } }
+							: {}),
+						width: { ideal: constraints.width?.ideal },
+						height: { ideal: constraints.height?.ideal },
+						frameRate: constraints.frameRate,
+					};
+					rawStream = await navigator.mediaDevices.getUserMedia({
+						video: fallback,
+					});
+				} else {
+					throw err;
+				}
+			}
+
+			let stream = rawStream;
+			if (this.currentBackgroundOptions) {
+				try {
+					await this.videoProcessor.cleanup();
+				} catch (cleanupErr) {
+					this.logger.warn('Processor cleanup during restart failed:', cleanupErr);
+				}
+				stream = await this.videoProcessor.applyBackground(
+					rawStream,
+					this.currentBackgroundOptions,
+				);
+			}
+
+			const newTrack = stream.getVideoTracks()[0];
+			await this.producers.video.replaceTrack({ track: newTrack });
+
+			// If we paused the producer when degradation was detected,
+			// resume now that a healthy track is attached. Don't touch
+			// the user's mute state.
+			if (this.producers.video.paused && !this.muteState.camera) {
+				try {
+					this.producers.video.resume();
+				} catch (resumeErr) {
+					this.logger.warn('Producer resume after restart failed:', resumeErr);
+				}
+			}
+
+			// Commit + stop old streams.
+			this.streams.camera = stream;
+			this.rawCameraStream = rawStream;
+			if (source.facingMode) {
+				this.cameraSource = { facingMode: source.facingMode };
+			} else {
+				const trackDeviceId =
+					rawStream.getVideoTracks()[0]?.getSettings().deviceId ||
+					source.deviceId ||
+					null;
+				this.cameraSource = trackDeviceId ? { deviceId: trackDeviceId } : null;
+			}
+
+			if (oldRawStream && oldRawStream !== rawStream) {
+				oldRawStream.getTracks().forEach((t) => t.stop());
+			}
+			if (
+				oldProcessedStream &&
+				oldProcessedStream !== oldRawStream &&
+				oldProcessedStream !== stream
+			) {
+				oldProcessedStream.getTracks().forEach((t) => t.stop());
+			}
+
+			this._watchCameraTrack(newTrack);
+			this.emit('camera:restarted', { stream });
+			this.logger.info('Camera restarted successfully');
+
+			return stream;
+		} catch (error) {
+			this.logger.error('Failed to restart camera:', error);
+			throw wrapError(error, 'restartCamera');
+		}
+	}
+
 	/**
 	 * Clean up all local streams
 	 */

package/managers/MediasoupManager.js

@@ -509,6 +509,60 @@ export class MediasoupManager extends EventEmitter {
         const baseWidth = settings.width || 1920;
         const baseHeight = settings.height || 1080;
 
+        const isScreenShare = options.appData?.type === "screenShare";
+
+        // ───────────────────────────────────────────────────────────
+        // Screen-share encoder profile
+        //
+        // Screen content is fundamentally different from camera:
+        //   - Mostly static (text, UI, diagrams) with occasional motion
+        //   - Text legibility is binary — readable or not, no in-between
+        //   - Receivers either need to read it or they're zoomed out
+        //
+        // So: single high-quality layer (not 3-tier simulcast), much
+        // higher max bitrate per pixel, lower framerate target (the
+        // encoder handles this via degradationPreference + the actual
+        // capture frame rate, which Chrome lowers automatically for
+        // static content). Also set contentHint='detail' on the
+        // track itself so the encoder favours sharpness over motion.
+        // ───────────────────────────────────────────────────────────
+        if (isScreenShare) {
+          try {
+            track.contentHint = "detail";
+          } catch (err) {
+            this.logger.warn("Could not set contentHint on screenshare track:", err);
+          }
+          // Bitrate budget tuned for text crispness: ~5 Mbps at 1080p,
+          // ~3 Mbps at 720p, scaled linearly for unusual sizes. Cap
+          // upper at 8 Mbps so a huge external monitor doesn't blow
+          // through user bandwidth.
+          const pixels = baseWidth * baseHeight;
+          const bitrate = Math.min(
+            8_000_000,
+            Math.max(2_000_000, Math.round(pixels * 2.5)),
+          );
+          produceOptions.encodings = [
+            {
+              rid: "h",
+              maxBitrate: bitrate,
+              scaleResolutionDownBy: 1.0,
+            },
+          ];
+          // degradationPreference="maintain-resolution" tells WebRTC
+          // to drop framerate before resolution if bandwidth tightens
+          // — exactly what we want for text.
+          produceOptions.degradationPreference = "maintain-resolution";
+          this.logger.info("VIDEO_QUALITY :: screen-share encoder profile", {
+            resolution: `${baseWidth}×${baseHeight}`,
+            bitrate: `${(bitrate / 1_000_000).toFixed(1)}Mbps`,
+            contentHint: track.contentHint,
+            degradationPreference: "maintain-resolution",
+          });
+          // Skip the camera simulcast branches below.
+          // (Falls through to the produceOptions logging.)
+          // No `return` — we still want to call transport.produce().
+        } else {
+
         // Check if user has set a max resolution preference
         const maxResolution = options.maxResolution || "1080p"; // Default to 1080p
 
@@ -584,6 +638,7 @@ export class MediasoupManager extends EventEmitter {
             bitrate: "800kbps",
           });
         }
+        } // end camera-profile else (matches `if (isScreenShare)`)
       }
 
       this.logger.info("Calling transport.produce with options:", {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unboundcx/video-sdk-client",
-	"version": "2.0.3",
+	"version": "2.0.5",
 	"description": "Framework-agnostic WebRTC video meeting SDK powered by mediasoup",
 	"type": "module",
 	"main": "index.js",