@unboundcx/video-sdk-client 1.1.0

package/managers/LocalMediaManager.js

@@ -0,0 +1,1051 @@
+import { EventEmitter } from '../utils/EventEmitter.js';
+import { Logger } from '../utils/Logger.js';
+import {
+	PermissionDeniedError,
+	DeviceNotFoundError,
+	wrapError,
+} from '../utils/errors.js';
+import { VideoProcessor } from '../VideoProcessor.js';
+
+/**
+ * Manages local media streams (camera, microphone, screen share)
+ *
+ * Events:
+ * - 'stream:added' - New local stream added
+ * - 'stream:removed' - Local stream removed
+ * - 'device:changed' - Device changed
+ * - 'track:ended' - Track ended unexpectedly
+ */
+export class LocalMediaManager extends EventEmitter {
+	/**
+	 * @param {Object} options
+	 * @param {MediasoupManager} options.mediasoup - Mediasoup manager instance
+	 * @param {boolean} options.debug - Enable debug logging
+	 */
+	constructor(options) {
+		super();
+
+		this.mediasoup = options.mediasoup;
+		this.logger = new Logger('SDK:LocalMediaManager', options.debug);
+
+		// Store active streams
+		this.streams = {
+			camera: null,
+			microphone: null,
+			screenShare: null,
+		};
+
+		// Store a separate unmuted microphone stream for muted-speaking detection
+		// This stream is never paused/disabled so we can always detect audio levels
+		this.rawMicrophoneStream = null;
+
+		// Store producers
+		this.producers = {
+			video: null,
+			audio: null,
+			screenShare: null,
+			screenShareAudio: null,
+		};
+
+		// Mute state
+		this.muteState = {
+			camera: false,
+			screenShareAudio: false,
+			microphone: false,
+		};
+
+		// Video processor for virtual backgrounds
+		this.videoProcessor = new VideoProcessor({ debug: options.debug });
+		this.currentBackgroundOptions = null;
+	}
+
+	/**
+	 * Get available media devices
+	 * @returns {Promise<Object>} Object with cameras, microphones, speakers arrays
+	 */
+	async getDevices() {
+		this.logger.log('Getting available devices');
+
+		try {
+			// Request permissions first to get device labels
+			await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
+
+			const devices = await navigator.mediaDevices.enumerateDevices();
+
+			const result = {
+				cameras: devices.filter((d) => d.kind === 'videoinput'),
+				microphones: devices.filter((d) => d.kind === 'audioinput'),
+				speakers: devices.filter((d) => d.kind === 'audiooutput'),
+			};
+
+			this.logger.info('Available devices:', {
+				cameras: result.cameras.length,
+				microphones: result.microphones.length,
+				speakers: result.speakers.length,
+			});
+
+			return result;
+		} catch (error) {
+			this.logger.error('Failed to get devices:', error);
+			throw wrapError(error, 'getDevices');
+		}
+	}
+
+	/**
+	 * Start camera and publish to server
+	 * @param {Object} options
+	 * @param {string} options.deviceId - Camera device ID
+	 * @param {string} options.resolution - Resolution preset (480p, 720p, 1080p)
+	 * @param {string} options.maxResolution - Max resolution for simulcast (720p, 1080p)
+	 * @param {number} options.frameRate - Frame rate (default: 24)
+	 * @param {Object} options.background - Background effect options
+	 * @param {string} options.background.type - 'none' | 'blur' | 'image'
+	 * @param {number} options.background.blurLevel - Blur level in pixels (default: 8)
+	 * @param {string} options.background.imageUrl - Background image URL
+	 * @returns {Promise<MediaStream>}
+	 */
+	async publishCamera(options = {}) {
+		this.logger.info('Publishing camera', options);
+
+		try {
+			let stream;
+			let originalTrack;
+
+			// Check if we're reusing an existing track from WaitingRoom
+			if (options.existingTrack) {
+				this.logger.info('VIDEO_QUALITY :: Using existing track from WaitingRoom', {
+					trackKind: options.existingTrack.kind,
+					trackId: options.existingTrack.id,
+					trackReadyState: options.existingTrack.readyState
+				});
+				originalTrack = options.existingTrack;
+				stream = new MediaStream([originalTrack]);
+
+				const settings = originalTrack.getSettings();
+				this.logger.info('VIDEO_QUALITY :: Existing track settings:', {
+					width: settings.width,
+					height: settings.height,
+					frameRate: settings.frameRate,
+					deviceId: settings.deviceId,
+					allSettings: settings
+				});
+			} else {
+				// Request new stream (old behavior)
+				const constraints = this._getVideoConstraints(options);
+				this.logger.info('VIDEO_QUALITY :: Requesting camera with constraints:', constraints);
+
+				try {
+					stream = await navigator.mediaDevices.getUserMedia({
+						video: constraints,
+					});
+				} catch (err) {
+					if (err.name === 'OverconstrainedError' || err.name === 'ConstraintNotSatisfiedError') {
+						this.logger.warn('VIDEO_QUALITY :: Camera constraints too strict, retrying without min constraints:', err.constraint);
+
+						const fallbackConstraints = {
+							deviceId: constraints.deviceId,
+							width: { ideal: constraints.width.ideal },
+							height: { ideal: constraints.height.ideal },
+							frameRate: constraints.frameRate
+						};
+
+						this.logger.info('Retrying with fallback constraints:', fallbackConstraints);
+						stream = await navigator.mediaDevices.getUserMedia({
+							video: fallbackConstraints,
+						});
+					} else {
+						throw err;
+					}
+				}
+
+				originalTrack = stream.getVideoTracks()[0];
+				const originalSettings = originalTrack.getSettings();
+				this.logger.info('VIDEO_QUALITY :: Original camera stream obtained:', {
+					width: originalSettings.width,
+					height: originalSettings.height,
+					frameRate: originalSettings.frameRate,
+					deviceId: originalSettings.deviceId
+				});
+
+				// Log camera capabilities
+				try {
+					const capabilities = originalTrack.getCapabilities();
+					this.logger.info('VIDEO_QUALITY :: Camera capabilities:', {
+						width: capabilities.width,
+						height: capabilities.height,
+						frameRate: capabilities.frameRate,
+						aspectRatio: capabilities.aspectRatio
+					});
+
+					if (capabilities.width && capabilities.width.max > originalSettings.width) {
+						this.logger.warn(`VIDEO_QUALITY :: ⚠️ Camera supports up to ${capabilities.width.max}×${capabilities.height.max} but only got ${originalSettings.width}×${originalSettings.height}!`);
+						this.logger.warn('Possible causes: Browser settings, camera firmware, system camera settings, or bandwidth limits');
+					}
+				} catch (err) {
+					this.logger.warn('Could not get camera capabilities:', err);
+				}
+			}
+
+			// Apply background effect if specified
+			if (options.background && options.background.type !== 'none') {
+				this.logger.info('Applying background effect:', options.background);
+				this.currentBackgroundOptions = options.background;
+				stream = await this.videoProcessor.applyBackground(stream, options.background);
+
+				// Log processed stream dimensions
+				const processedTrack = stream.getVideoTracks()[0];
+				const processedSettings = processedTrack.getSettings();
+				this.logger.info('Background applied, processed stream:', {
+					width: processedSettings.width,
+					height: processedSettings.height,
+					frameRate: processedSettings.frameRate
+				});
+			}
+
+			const track = stream.getVideoTracks()[0];
+
+			// 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;
+			});
+
+			// Publish to mediasoup
+			const producer = await this.mediasoup.produce(track, {
+				appData: { type: 'video' },
+				simulcast: options.simulcast, // Pass through simulcast option
+				maxResolution: options.maxResolution, // Pass through max resolution preference
+			});
+
+			this.producers.video = producer;
+
+			this.logger.info('Camera published', {
+				deviceId: track.getSettings().deviceId,
+				resolution: `${track.getSettings().width}x${track.getSettings().height}`,
+				backgroundEffect: options.background?.type || 'none',
+			});
+
+			this.emit('stream:added', { type: 'camera', stream, producer });
+
+			return stream;
+		} catch (error) {
+			this.logger.error('Failed to publish camera:', error);
+
+			if (error.name === 'NotAllowedError') {
+				throw new PermissionDeniedError('camera', error);
+			}
+
+			if (error.name === 'NotFoundError') {
+				throw new DeviceNotFoundError('camera', options.deviceId);
+			}
+
+			throw wrapError(error, 'publishCamera');
+		}
+	}
+
+	/**
+	 * Start microphone and publish to server
+	 * @param {Object} options
+	 * @param {string} options.deviceId - Microphone device ID
+	 * @param {boolean} options.echoCancellation - Enable echo cancellation
+	 * @param {boolean} options.noiseSuppression - Enable noise suppression
+	 * @returns {Promise<MediaStream>}
+	 */
+	async publishMicrophone(options = {}) {
+		this.logger.info('Publishing microphone', options);
+
+		try {
+			let stream;
+			let track;
+
+			// Check if we're reusing an existing track from WaitingRoom
+			if (options.existingTrack) {
+				this.logger.info('Using existing audio track from WaitingRoom');
+				track = options.existingTrack;
+				stream = new MediaStream([track]);
+			} else {
+				// Request new stream (old behavior)
+				const constraints = {
+					deviceId: options.deviceId ? { exact: options.deviceId } : undefined,
+					echoCancellation: options.echoCancellation !== false,
+					noiseSuppression: options.noiseSuppression !== false,
+					autoGainControl: false, // Disabled - amplifies background noise
+				};
+
+				stream = await navigator.mediaDevices.getUserMedia({
+					audio: constraints,
+				});
+
+				track = stream.getAudioTracks()[0];
+			}
+
+			// Store stream
+			this.streams.microphone = stream;
+
+			// Also store a clone for muted-speaking detection (never disabled)
+			const clonedTrack = track.clone();
+			this.rawMicrophoneStream = new MediaStream([clonedTrack]);
+			this.logger.info('Created raw microphone stream clone for muted-speaking detection');
+
+			// Setup track ended handler
+			track.addEventListener('ended', () => {
+				this.logger.warn('Microphone track ended');
+				this.emit('track:ended', { type: 'microphone' });
+				this.streams.microphone = null;
+				// Also clean up raw stream
+				if (this.rawMicrophoneStream) {
+					this.rawMicrophoneStream.getTracks().forEach(t => t.stop());
+					this.rawMicrophoneStream = null;
+				}
+			});
+
+			// Publish to mediasoup
+			const producer = await this.mediasoup.produce(track, {
+				appData: { type: 'audio' },
+			});
+
+			this.producers.audio = producer;
+
+			this.logger.info('Microphone published', {
+				deviceId: track.getSettings().deviceId,
+			});
+
+			this.emit('stream:added', { type: 'microphone', stream, producer });
+
+			return stream;
+		} catch (error) {
+			this.logger.error('Failed to publish microphone:', error);
+
+			if (error.name === 'NotAllowedError') {
+				throw new PermissionDeniedError('microphone', error);
+			}
+
+			if (error.name === 'NotFoundError') {
+				throw new DeviceNotFoundError('microphone', options.deviceId);
+			}
+
+			throw wrapError(error, 'publishMicrophone');
+		}
+	}
+
+	/**
+	 * Start screen sharing and publish to server
+	 * @param {Object} options
+	 * @param {boolean} options.audio - Include system audio
+	 * @returns {Promise<MediaStream>}
+	 */
+	async publishScreenShare(options = {}) {
+		this.logger.info('LocalMediaManager :: publishScreenShare called with options:', JSON.stringify(options));
+
+		try {
+			// 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
+			const constraints = {
+				video: {
+					cursor: 'always',
+				},
+				// Request audio with processing disabled for system audio
+				// System audio should not have echo cancellation, noise suppression, or auto gain control
+				audio: {
+					echoCancellation: false,
+					noiseSuppression: false,
+					autoGainControl: false,
+					sampleRate: 48000,
+					sampleSize: 16,
+					channelCount: 2
+				}
+			};
+
+			this.logger.info('LocalMediaManager :: Requesting display media with constraints:', JSON.stringify(constraints));
+			const stream = await navigator.mediaDevices.getDisplayMedia(constraints);
+			this.logger.info('LocalMediaManager :: Display media obtained - video tracks:', stream.getVideoTracks().length, 'audio tracks:', stream.getAudioTracks().length);
+
+			// Log audio track details if present
+			const audioTracks = stream.getAudioTracks();
+			if (audioTracks.length > 0) {
+				this.logger.info('LocalMediaManager :: Audio track found:', audioTracks[0].label, 'enabled:', audioTracks[0].enabled);
+			} else {
+				this.logger.warn('LocalMediaManager :: No audio track in stream. User may not have checked "Share audio" checkbox or shared Screen instead of Tab/Window.');
+			}
+
+			const videoTrack = stream.getVideoTracks()[0];
+
+			// Store stream
+			this.streams.screenShare = stream;
+
+			// Setup track ended handler (user stopped sharing)
+			videoTrack.addEventListener('ended', () => {
+				this.logger.info('Screen share track ended (user stopped sharing)');
+				this.stopScreenShare();
+			});
+
+			// Publish video track to mediasoup
+			const producer = await this.mediasoup.produce(videoTrack, {
+				appData: { type: 'screenShare' },
+			});
+
+			this.producers.screenShare = producer;
+
+			this.logger.info('Screen share published');
+
+			this.emit('stream:added', { type: 'screenShare', stream, producer });
+
+			// If audio track exists, publish it separately
+			if (audioTracks.length > 0) {
+				const audioTrack = audioTracks[0];
+				const audioProducer = await this.mediasoup.produce(audioTrack, {
+					appData: { type: 'screenShareAudio' },
+				});
+				this.producers.screenShareAudio = audioProducer;
+				this.logger.info('Screen share audio published');
+
+				// Setup track ended handler for audio
+				audioTrack.addEventListener('ended', () => {
+					this.logger.info('Screen share audio track ended');
+					if (this.producers.screenShareAudio) {
+						this.mediasoup.closeProducer('screenShareAudio');
+						this.producers.screenShareAudio = null;
+					}
+				});
+			} else {
+				this.logger.warn('LocalMediaManager :: No audio track available. Note: In Chrome, check the "Share audio" checkbox when sharing a Tab or Window. Screen sharing does not support audio.');
+			}
+
+			return stream;
+		} catch (error) {
+			this.logger.error('Failed to publish screen share:', error);
+
+			if (error.name === 'NotAllowedError') {
+				throw new PermissionDeniedError('screen', error);
+			}
+
+			throw wrapError(error, 'publishScreenShare');
+		}
+	}
+
+	/**
+	 * Stop camera
+	 */
+	async stopCamera() {
+		this.logger.info('Stopping camera');
+
+		if (!this.streams.camera) {
+			this.logger.warn('No camera stream to stop');
+			return;
+		}
+
+		// Stop all tracks
+		this.streams.camera.getTracks().forEach((track) => track.stop());
+
+		// Close producer
+		if (this.producers.video) {
+			await this.mediasoup.closeProducer('video');
+			this.producers.video = null;
+		}
+
+		this.streams.camera = null;
+
+		this.emit('stream:removed', { type: 'camera' });
+	}
+
+	/**
+	 * Stop microphone
+	 */
+	async stopMicrophone() {
+		this.logger.info('Stopping microphone');
+
+		if (!this.streams.microphone) {
+			this.logger.warn('No microphone stream to stop');
+			return;
+		}
+
+		// Stop all tracks
+		this.streams.microphone.getTracks().forEach((track) => track.stop());
+
+		// Close producer
+		if (this.producers.audio) {
+			await this.mediasoup.closeProducer('audio');
+			this.producers.audio = null;
+		}
+
+		this.streams.microphone = null;
+
+		this.emit('stream:removed', { type: 'microphone' });
+	}
+
+	/**
+	 * Stop screen sharing
+	 */
+	async stopScreenShare() {
+		this.logger.info('Stopping screen share');
+
+		if (!this.streams.screenShare) {
+			this.logger.warn('No screen share stream to stop');
+			return;
+		}
+
+		// Stop all tracks
+		this.streams.screenShare.getTracks().forEach((track) => track.stop());
+
+		// Close producers
+		if (this.producers.screenShare) {
+			await this.mediasoup.closeProducer('screenShare');
+			this.producers.screenShare = null;
+		}
+
+		if (this.producers.screenShareAudio) {
+			await this.mediasoup.closeProducer('screenShareAudio');
+			this.producers.screenShareAudio = null;
+		}
+
+		this.streams.screenShare = null;
+
+		this.emit('stream:removed', { type: 'screenShare' });
+	}
+
+	/**
+	 * Enable screenshare audio (add audio to existing screenshare)
+	 * @returns {Promise<void>}
+	 */
+	async enableScreenShareAudio() {
+		this.logger.info('Enabling screen share audio');
+
+		if (!this.streams.screenShare) {
+			throw new Error('No active screen share to add audio to');
+		}
+
+		if (this.producers.screenShareAudio) {
+			this.logger.warn('Screen share audio already enabled');
+			return;
+		}
+
+		try {
+			// Request a new screenshare with audio
+			const stream = await navigator.mediaDevices.getDisplayMedia({
+				video: true,
+				audio: {
+					echoCancellation: false,
+					noiseSuppression: false,
+					autoGainControl: false,
+					sampleRate: 48000,
+					sampleSize: 16,
+					channelCount: 2
+				}
+			});
+
+			// Check if audio track was granted
+			const audioTrack = stream.getAudioTracks()[0];
+			if (!audioTrack) {
+				this.logger.warn('No audio track available from display media');
+				// Stop the new stream since we only wanted audio
+				stream.getTracks().forEach((track) => track.stop());
+				return;
+			}
+
+			// Replace video track in existing stream (user might have selected different window)
+			const oldVideoTrack = this.streams.screenShare.getVideoTracks()[0];
+			const newVideoTrack = stream.getVideoTracks()[0];
+
+			// Update the video track in the stream
+			this.streams.screenShare.removeTrack(oldVideoTrack);
+			this.streams.screenShare.addTrack(newVideoTrack);
+			oldVideoTrack.stop();
+
+			// Replace the video producer
+			await this.mediasoup.replaceTrack('screenShare', newVideoTrack);
+
+			// Add audio track to stream
+			this.streams.screenShare.addTrack(audioTrack);
+
+			// Publish audio track
+			const audioProducer = await this.mediasoup.produce(audioTrack, {
+				appData: { type: 'screenShareAudio' },
+			});
+			this.producers.screenShareAudio = audioProducer;
+			this.muteState.screenShareAudio = false;
+
+			// Setup track ended handler
+			newVideoTrack.addEventListener('ended', () => {
+				this.logger.info('Screen share track ended (user stopped sharing)');
+				this.stopScreenShare();
+			});
+
+			this.logger.info('Screen share audio enabled');
+			this.emit('stream:updated', { type: 'screenShare', stream: this.streams.screenShare });
+
+		} catch (error) {
+			this.logger.error('Failed to enable screen share audio:', error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Disable screenshare audio (remove audio from existing screenshare)
+	 * @returns {Promise<void>}
+	 */
+	async disableScreenShareAudio() {
+		this.logger.info('Disabling screen share audio');
+
+		if (!this.producers.screenShareAudio) {
+			this.logger.warn('No screen share audio to disable');
+			return;
+		}
+
+		// Close the audio producer
+		await this.mediasoup.closeProducer('screenShareAudio');
+		this.producers.screenShareAudio = null;
+
+		// Remove and stop audio track from stream
+		const audioTrack = this.streams.screenShare.getAudioTracks()[0];
+		if (audioTrack) {
+			this.streams.screenShare.removeTrack(audioTrack);
+			audioTrack.stop();
+		}
+
+		this.muteState.screenShareAudio = false;
+
+		this.logger.info('Screen share audio disabled');
+		this.emit('stream:updated', { type: 'screenShare', stream: this.streams.screenShare });
+	}
+
+	/**
+	 * Mute screenshare audio
+	 * @returns {Promise<void>}
+	 */
+	async muteScreenShareAudio() {
+		if (!this.producers.screenShareAudio) {
+			this.logger.warn('No screen share audio to mute');
+			return;
+		}
+
+		try {
+			await this.mediasoup.pauseProducer('screenShareAudio');
+			this.muteState.screenShareAudio = true;
+			this.logger.info('Screen share audio muted');
+			this.emit('mute-state-changed', { type: 'screenShareAudio', muted: true });
+		} catch (error) {
+			this.logger.error('Failed to mute screen share audio:', error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Unmute screenshare audio
+	 * @returns {Promise<void>}
+	 */
+	async unmuteScreenShareAudio() {
+		if (!this.producers.screenShareAudio) {
+			this.logger.warn('No screen share audio to unmute');
+			return;
+		}
+
+		try {
+			await this.mediasoup.resumeProducer('screenShareAudio');
+			this.muteState.screenShareAudio = false;
+			this.logger.info('Screen share audio unmuted');
+			this.emit('mute-state-changed', { type: 'screenShareAudio', muted: false });
+		} catch (error) {
+			this.logger.error('Failed to unmute screen share audio:', error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Toggle screenshare audio mute state
+	 * @returns {Promise<boolean>} New mute state
+	 */
+	async toggleScreenShareAudioMute() {
+		if (this.muteState.screenShareAudio) {
+			await this.unmuteScreenShareAudio();
+		} else {
+			await this.muteScreenShareAudio();
+		}
+		return this.muteState.screenShareAudio;
+	}
+
+	/**
+	 * Change camera device
+	 * @param {Object|string} options - Camera options or deviceId string for backward compatibility
+	 * @param {string} options.deviceId - Camera device ID (desktop)
+	 * @param {string} options.facingMode - Camera facing mode: 'user' or 'environment' (mobile)
+	 * @returns {Promise<MediaStream>}
+	 */
+	async changeCamera(options) {
+		// Support backward compatibility: if options is a string, treat it as deviceId
+		if (typeof options === 'string') {
+			options = { deviceId: options };
+		}
+
+		this.logger.info('Changing camera:', options);
+
+		if (!this.producers.video) {
+			throw new Error('No active camera to change');
+		}
+
+		try {
+			// Get new stream
+			const constraints = this._getVideoConstraints(options);
+			let stream = await navigator.mediaDevices.getUserMedia({
+				video: constraints,
+			});
+
+			// Reapply background effect if it was active
+			if (this.currentBackgroundOptions) {
+				this.logger.info('Reapplying background effect after camera change');
+				stream = await this.videoProcessor.applyBackground(
+					stream,
+					this.currentBackgroundOptions,
+				);
+			}
+
+			const newTrack = stream.getVideoTracks()[0];
+
+			// Replace track in producer
+			await this.producers.video.replaceTrack({ track: newTrack });
+
+			// If producer was paused (camera muted), resume it
+			// When user manually changes camera, they likely want to use it
+			if (this.producers.video.paused) {
+				this.logger.info('Producer was paused, resuming to send new camera track');
+				this.producers.video.resume();
+				this.muteState.camera = false;
+			}
+
+			// Stop old stream
+			if (this.streams.camera) {
+				this.streams.camera.getTracks().forEach((track) => track.stop());
+			}
+
+			// Store new stream
+			this.streams.camera = stream;
+
+			this.logger.info('Camera changed successfully');
+
+			// Determine the deviceId to emit
+			// For mobile using facingMode, map to 'user' or 'environment'
+			// For desktop, use the actual deviceId
+			let emitDeviceId;
+			if (options.facingMode) {
+				// Mobile: use facingMode as the identifier
+				emitDeviceId = options.facingMode;
+			} else {
+				// Desktop: use deviceId from options or extract from track
+				emitDeviceId = options.deviceId || newTrack.getSettings().deviceId;
+			}
+
+			this.emit('device:changed', { type: 'camera', deviceId: emitDeviceId, stream });
+
+			return stream;
+		} catch (error) {
+			this.logger.error('Failed to change camera:', error);
+			throw wrapError(error, 'changeCamera');
+		}
+	}
+
+	/**
+	 * Update background effect on active camera
+	 * @param {Object} options - Background options
+	 * @param {string} options.type - 'none' | 'blur' | 'image'
+	 * @param {number} options.blurLevel - Blur level in pixels (default: 8)
+	 * @param {string} options.imageUrl - Background image URL
+	 * @returns {Promise<MediaStream>}
+	 */
+	async updateCameraBackground(options) {
+		this.logger.info('Updating camera background:', options);
+
+		if (!this.streams.camera) {
+			throw new Error('No active camera stream');
+		}
+
+		if (!this.producers.video) {
+			throw new Error('No active video producer');
+		}
+
+		try {
+			// Clean up old processor if exists
+			if (this.currentBackgroundOptions) {
+				await this.videoProcessor.cleanup();
+			}
+
+			// Get current device ID
+			const currentTrack = this.streams.camera.getVideoTracks()[0];
+			const deviceId = currentTrack.getSettings().deviceId;
+
+			// If removing background, restart with original stream
+			if (options.type === 'none') {
+				this.logger.info('Removing background effect');
+				this.currentBackgroundOptions = null;
+
+				const constraints = this._getVideoConstraints({ deviceId });
+				const newStream = await navigator.mediaDevices.getUserMedia({
+					video: constraints,
+				});
+
+				const newTrack = newStream.getVideoTracks()[0];
+
+				await this.producers.video.replaceTrack({ track: newTrack });
+
+				this.streams.camera.getTracks().forEach((t) => t.stop());
+				this.streams.camera = newStream;
+
+				this.logger.info('Background effect removed');
+				this.emit('background:changed', { type: 'none' });
+
+				return newStream;
+			}
+
+			// Apply new background effect
+			this.currentBackgroundOptions = options;
+
+			// Get fresh stream
+			const constraints = this._getVideoConstraints({ deviceId });
+			let stream = await navigator.mediaDevices.getUserMedia({
+				video: constraints,
+			});
+
+			// Apply background
+			stream = await this.videoProcessor.applyBackground(stream, options);
+
+			const newTrack = stream.getVideoTracks()[0];
+
+			// Replace track in producer
+			await this.producers.video.replaceTrack({ track: newTrack });
+
+			// Stop old stream
+			this.streams.camera.getTracks().forEach((t) => t.stop());
+			this.streams.camera = stream;
+
+			this.logger.info('Background effect updated successfully');
+			this.emit('background:changed', options);
+
+			return stream;
+		} catch (error) {
+			this.logger.error('Failed to update camera background:', error);
+			throw wrapError(error, 'updateCameraBackground');
+		}
+	}
+
+	/**
+	 * Change microphone device
+	 * @param {string} deviceId - New microphone device ID
+	 * @returns {Promise<MediaStream>}
+	 */
+	async changeMicrophone(deviceId) {
+		this.logger.info('Changing microphone to:', deviceId);
+
+		if (!this.producers.audio) {
+			throw new Error('No active microphone to change');
+		}
+
+		try {
+			// Get new stream
+			const stream = await navigator.mediaDevices.getUserMedia({
+				audio: {
+					deviceId: { exact: deviceId },
+					echoCancellation: true,
+					noiseSuppression: true,
+				},
+			});
+
+			const newTrack = stream.getAudioTracks()[0];
+
+			// Replace track in producer
+			await this.producers.audio.replaceTrack({ track: newTrack });
+
+			// If producer was paused (microphone muted), resume it
+			// When user manually changes microphone, they likely want to use it
+			if (this.producers.audio.paused) {
+				this.logger.info('Producer was paused, resuming to send new microphone track');
+				this.producers.audio.resume();
+				this.muteState.microphone = false;
+			}
+
+			// Stop old stream
+			if (this.streams.microphone) {
+				this.streams.microphone.getTracks().forEach((track) => track.stop());
+			}
+
+			// Store new stream
+			this.streams.microphone = stream;
+
+			this.logger.info('Microphone changed successfully');
+
+			this.emit('device:changed', { type: 'microphone', deviceId, stream });
+
+			return stream;
+		} catch (error) {
+			this.logger.error('Failed to change microphone:', error);
+			throw wrapError(error, 'changeMicrophone');
+		}
+	}
+
+	/**
+	 * Mute camera (pause producer)
+	 */
+	async muteCamera() {
+		if (!this.producers.video) {
+			this.logger.warn('No camera producer to mute');
+			return;
+		}
+
+		this.logger.info('Muting camera');
+		this.producers.video.pause();
+		this.muteState.camera = true;
+		// Note: Mute state is persisted via REST API call from the client app
+	}
+
+	/**
+	 * Unmute camera (resume producer)
+	 */
+	async unmuteCamera() {
+		if (!this.producers.video) {
+			this.logger.warn('No camera producer to unmute');
+			return;
+		}
+
+		this.logger.info('Unmuting camera');
+		this.producers.video.resume();
+		this.muteState.camera = false;
+		// Note: Mute state is persisted via REST API call from the client app
+	}
+
+	/**
+	 * Mute microphone (pause producer)
+	 */
+	async muteMicrophone() {
+		if (!this.producers.audio) {
+			this.logger.warn('No microphone producer to mute');
+			return;
+		}
+
+		this.logger.info('Muting microphone');
+		this.producers.audio.pause();
+		this.muteState.microphone = true;
+		// Note: Mute state is persisted via REST API call from the client app
+	}
+
+	/**
+	 * Unmute microphone (resume producer)
+	 */
+	async unmuteMicrophone() {
+		if (!this.producers.audio) {
+			this.logger.warn('No microphone producer to unmute');
+			return;
+		}
+
+		this.logger.info('Unmuting microphone');
+		this.producers.audio.resume();
+		this.muteState.microphone = false;
+		// Note: Mute state is persisted via REST API call from the client app
+	}
+
+	/**
+	 * Get video constraints based on resolution preset
+	 * @private
+	 */
+	_getVideoConstraints(options = {}) {
+		const resolutions = {
+			'480p': { width: 640, height: 480 },
+			'720p': { width: 1280, height: 720 },
+			'1080p': { width: 1920, height: 1080 },
+		};
+
+		const resolution = resolutions[options.resolution] || resolutions['1080p']; // Default to 1080p for maximum quality
+
+		// Use ideal + max constraints like the old working /video system
+		// Do NOT use min - it causes OverconstrainedError on many cameras
+		// Browser will give us the best resolution it can up to the max
+		const constraints = {
+			width: {
+				ideal: resolution.width,
+				max: resolution.width
+			},
+			height: {
+				ideal: resolution.height,
+				max: resolution.height
+			},
+			frameRate: { ideal: options.frameRate || 30 },
+			aspectRatio: { ideal: 16 / 9 }
+		};
+
+		// Use facingMode if provided (mobile), otherwise use deviceId (desktop)
+		if (options.facingMode) {
+			constraints.facingMode = { exact: options.facingMode };
+		} else if (options.deviceId) {
+			constraints.deviceId = { exact: options.deviceId };
+		}
+
+		return constraints;
+	}
+
+	/**
+	 * Get local stream by type
+	 * @param {string} type - Stream type (camera, microphone, screenShare)
+	 * @returns {MediaStream|null}
+	 */
+	getStream(type) {
+		// Special case: return raw microphone stream for muted-speaking detection
+		if (type === 'microphone-raw') {
+			return this.rawMicrophoneStream || null;
+		}
+		return this.streams[type] || null;
+	}
+
+	/**
+	 * Check if camera is active
+	 * @returns {boolean}
+	 */
+	get isCameraActive() {
+		return !!this.streams.camera && !!this.producers.video;
+	}
+
+	/**
+	 * Check if microphone is active
+	 * @returns {boolean}
+	 */
+	get isMicrophoneActive() {
+		return !!this.streams.microphone && !!this.producers.audio;
+	}
+
+	/**
+	 * Check if screen share is active
+	 * @returns {boolean}
+	 */
+	get isScreenShareActive() {
+		return !!this.streams.screenShare && !!this.producers.screenShare;
+	}
+
+	/**
+	 * Check if camera is muted
+	 * @returns {boolean}
+	 */
+	get isCameraMuted() {
+		return this.muteState.camera;
+	}
+
+	/**
+	 * Check if microphone is muted
+	 * @returns {boolean}
+	 */
+	get isMicrophoneMuted() {
+		return this.muteState.microphone;
+	}
+
+	/**
+	 * Clean up all local streams
+	 */
+	async cleanup() {
+		this.logger.info('Cleaning up local streams...');
+
+		await this.stopCamera();
+		await this.stopMicrophone();
+		await this.stopScreenShare();
+
+		this.logger.info('Local streams cleanup complete');
+	}
+}