@unboundcx/video-sdk-client 1.1.0 → 2.0.1

package/managers/MediasoupManager.js

@@ -1,8 +1,8 @@
-import { Device } from 'mediasoup-client';
-import { EventEmitter } from '../utils/EventEmitter.js';
-import { Logger } from '../utils/Logger.js';
-import { MediasoupError, StateError } from '../utils/errors.js';
-import { StatsCollector } from './StatsCollector.js';
+import { Device } from "mediasoup-client";
+import { EventEmitter } from "../utils/EventEmitter.js";
+import { Logger } from "../utils/Logger.js";
+import { MediasoupError, StateError } from "../utils/errors.js";
+import { StatsCollector } from "./StatsCollector.js";
 
 /**
  * Manages mediasoup Device and Transports
@@ -16,774 +16,1060 @@ import { StatsCollector } from './StatsCollector.js';
  * - 'consumer:created' - Consumer created
  */
 export class MediasoupManager extends EventEmitter {
-	/**
-	 * @param {Object} options
-	 * @param {ConnectionManager} options.connection - Connection manager instance
-	 * @param {boolean} options.debug - Enable debug logging
-	 */
-	constructor(options) {
-		super();
-
-		this.connection = options.connection;
-		this.logger = new Logger('SDK:MediasoupManager', options.debug);
-
-		this.device = new Device();
-		this.sendTransport = null;
-		this.recvTransport = null;
-		this.producers = new Map(); // Map<type, Producer>
-		this.consumers = new Map(); // Map<consumerId, Consumer>
-
-		// Initialize stats collector
-		this.statsCollector = new StatsCollector(this.logger);
-		this.virtualBackgroundStore = null; // Will be set externally
-	}
-
-	/**
-	 * Load device with router RTP capabilities
-	 * This sets up a listener for media.routerCapabilities event from server
-	 * @returns {Promise<void>}
-	 */
-	async loadDevice() {
-		if (this.device.loaded) {
-			this.logger.warn('Device already loaded');
-			return;
-		}
-
-		this.logger.info('Waiting for media.routerCapabilities from server...');
-
-		return new Promise((resolve, reject) => {
-			const timeout = setTimeout(() => {
-				reject(new MediasoupError('Timeout waiting for router capabilities'));
-			}, 10000);
-
-			// Listen for media.routerCapabilities event from server
-			this.connection.onServerEvent('media.routerCapabilities', async (data) => {
-				try {
-					clearTimeout(timeout);
-
-					this.logger.info('Received media.routerCapabilities', {
-						hasCapabilities: !!data?.routerRtpCapabilities,
-						codecCount: data?.routerRtpCapabilities?.codecs?.length || 0
-					});
-
-					const { routerRtpCapabilities } = data;
-
-					if (!routerRtpCapabilities) {
-						throw new MediasoupError('No router capabilities in server response');
-					}
-
-					// Debug: Log router codecs
-					this.logger.info('Router Video Codecs:',
-						routerRtpCapabilities.codecs
-							.filter(c => c.kind === 'video')
-							.map(c => `${c.mimeType} (params: ${JSON.stringify(c.parameters || {})})`)
-					);
-
-					// Load device
-					await this.device.load({ routerRtpCapabilities });
-
-					this.logger.info('Device loaded successfully', {
-						codecs: this.device.rtpCapabilities.codecs.length,
-						canProduce: {
-							video: this.device.canProduce('video'),
-							audio: this.device.canProduce('audio')
-						}
-					});
-
-					// Debug: Log device codecs
-					this.logger.info('Device Video Codecs:',
-						this.device.rtpCapabilities.codecs
-							.filter(c => c.kind === 'video')
-							.map(c => c.mimeType)
-					);
-
-					this.emit('device:loaded', {
-						rtpCapabilities: this.device.rtpCapabilities
-					});
-
-					resolve();
-
-				} catch (error) {
-					this.logger.error('Failed to load device:', error);
-					reject(new MediasoupError('Failed to load device', 'loadDevice', error));
-				}
-			});
-		});
-	}
-
-	/**
-	 * Create send transport for publishing media
-	 * @returns {Promise<Transport>}
-	 */
-	async createSendTransport() {
-		if (!this.device.loaded) {
-			throw new StateError('Device not loaded', 'not-loaded', 'loaded');
-		}
-
-		if (this.sendTransport) {
-			this.logger.warn('Send transport already exists');
-			return this.sendTransport;
-		}
-
-		this.logger.info('Creating send transport...');
-
-		try {
-			// Request transport options from server
-			const transportOptions = await this.connection.request('media.createSendTransport');
-
-			// Create transport
-			this.sendTransport = this.device.createSendTransport(transportOptions);
-
-			// Setup transport event handlers
-			this._setupSendTransportListeners(this.sendTransport);
-
-			this.emit('transport:created', { direction: 'send', id: this.sendTransport.id });
-
-			return this.sendTransport;
-
-		} catch (error) {
-			this.logger.error('Failed to create send transport:', error);
-			throw new MediasoupError('Failed to create send transport', 'createSendTransport', error);
-		}
-	}
-
-	/**
-	 * Create receive transport for consuming media
-	 * @returns {Promise<Transport>}
-	 */
-	async createRecvTransport() {
-		if (!this.device.loaded) {
-			throw new StateError('Device not loaded', 'not-loaded', 'loaded');
-		}
-
-		if (this.recvTransport) {
-			this.logger.warn('Receive transport already exists');
-			return this.recvTransport;
-		}
-
-		this.logger.info('Creating receive transport...');
-
-		try {
-			// Request transport options from server
-			const transportOptions = await this.connection.request('media.createRecvTransport');
-
-			// Create transport
-			this.recvTransport = this.device.createRecvTransport(transportOptions);
-
-			// Setup transport event handlers
-			this._setupRecvTransportListeners(this.recvTransport);
-
-			this.emit('transport:created', { direction: 'recv', id: this.recvTransport.id });
-
-			return this.recvTransport;
-
-		} catch (error) {
-			this.logger.error('Failed to create receive transport:', error);
-			throw new MediasoupError('Failed to create receive transport', 'createRecvTransport', error);
-		}
-	}
-
-	/**
-	 * Setup send transport event listeners (matches your server's emit/on pattern)
-	 * @private
-	 */
-	_setupSendTransportListeners() {
-		const transport = this.sendTransport;
-		const socket = this.connection.socket; // Cache socket reference like old system
-
-		// Connect event - DTLS parameters need to be sent to server
-		transport.on('connect', ({ dtlsParameters }, callback, errback) => {
-			this.logger.log('Send transport connecting...');
-
-			// Emit to server
-			socket.emit('media.connectSendTransport', {
-				transportId: transport.id,
-				dtlsParameters
-			});
-
-			// Listen for success/error responses
-			socket.once('media.connectSendTransport.success', () => {
-				socket.off('media.connectSendTransport.error');
-				this.logger.info('Send transport connected');
-				this.emit('transport:connected', { direction: 'send', id: transport.id });
-
-				// Start stats collection for send transport
-				this.statsCollector.startSendStats(
-					transport,
-					socket,
-					this.virtualBackgroundStore
-				);
-
-				callback();
-			});
-
-			socket.once('media.connectSendTransport.error', (error) => {
-				socket.off('media.connectSendTransport.success');
-				this.logger.error('Failed to connect send transport:', error);
-				errback(error);
-			});
-		});
-
-		// Produce event - New track needs to be registered with server
-		transport.on('produce', ({ kind, rtpParameters, appData }, callback, errback) => {
-			this.logger.log('Producing', kind);
-
-			// Emit produce request to server
-			socket.emit('media.produce', {
-				transportId: transport.id,
-				rtpParameters,
-				producerType: appData?.type || kind,  // Fixed: use appData.type (matches LocalMediaManager)
-			});
-
-			// Listen for success/error responses - use socket directly
-			socket.once('media.produce.success', ({ producerId }) => {
-				socket.off('media.produce.error');
-				this.logger.info('Producer created:', producerId);
-				callback({ id: producerId });
-			});
-
-			socket.once('media.produce.error', (error) => {
-				socket.off('media.produce.success');
-				this.logger.error('Failed to create producer:', error);
-				errback(error);
-			});
-		});
-
-		// Connection state change
-		transport.on('connectionstatechange', (state) => {
-			this.logger.info('Send transport state:', state);
-
-			if (state === 'failed' || state === 'closed') {
-				this.emit('transport:closed', { direction: 'send', id: transport.id, state });
-			}
-		});
-	}
-
-	/**
-	 * Setup receive transport event listeners (matches your server's emit/on pattern)
-	 * @private
-	 */
-	_setupRecvTransportListeners() {
-		const transport = this.recvTransport;
-
-		// Connect event
-		transport.on('connect', ({ dtlsParameters }, callback, errback) => {
-			this.logger.log('Receive transport connecting...');
-
-			// Emit to server
-			this.connection.emit('media.connectRecvTransport', {
-				transportId: transport.id,
-				dtlsParameters
-			});
-
-			// Listen for success/error responses
-			this.connection.socket.once('media.connectRecvTransport.success', () => {
-				this.connection.socket.off('media.connectRecvTransport.error');
-				this.logger.info('Receive transport connected');
-				this.emit('transport:connected', { direction: 'recv', id: transport.id });
-
-				// Start stats collection for recv transport
-				this.statsCollector.startRecvStats(
-					transport,
-					this.connection.socket,
-					this.virtualBackgroundStore
-				);
-
-				callback();
-			});
-
-			this.connection.socket.once('media.connectRecvTransport.error', (error) => {
-				this.connection.socket.off('media.connectRecvTransport.success');
-				this.logger.error('Failed to connect receive transport:', error);
-				errback(error);
-			});
-		});
-
-		// Connection state change
-		transport.on('connectionstatechange', (state) => {
-			this.logger.info('Receive transport state:', state);
-
-			if (state === 'failed' || state === 'closed') {
-				this.emit('transport:closed', { direction: 'recv', id: transport.id, state });
-			}
-		});
-	}
-
-	/**
-	 * Produce media (send to server)
-	 * @param {MediaStreamTrack} track - Media track to produce
-	 * @param {Object} options - Producer options
-	 * @returns {Promise<Producer>}
-	 */
-	async produce(track, options = {}) {
-
-		if (!this.sendTransport) {
-			await this.createSendTransport();
-		}
-
-		this.logger.info('Producing track:', track.kind, track.id);
-		this.logger.info('Produce options received:', {
-			simulcast: options.simulcast,
-			hasSimulcastOption: 'simulcast' in options,
-			willEnableSimulcast: track.kind === 'video' && options.simulcast !== false
-		});
-
-		try {
-			// Match old working system exactly - minimal options
-			const produceOptions = {
-				track
-			};
-
-			// Only add appData if provided (match old system pattern)
-			if (options.appData) {
-				produceOptions.appData = options.appData;
-			}
-
-			// Add simulcast encodings for video tracks (enabled by default, can be disabled)
-			if (track.kind === 'video' && options.simulcast !== false) {
-				// Get track settings to determine base resolution
-				const settings = track.getSettings();
-				const baseWidth = settings.width || 1920;
-				const baseHeight = settings.height || 1080;
-
-				// Check if user has set a max resolution preference
-				const maxResolution = options.maxResolution || '1080p'; // Default to 1080p
-
-				// 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;
-				}
-
-				// Adaptive simulcast configuration based on target resolution
-				if (baseWidth >= 1280) {
-					// High resolution camera (720p+) - Use 3-layer simulcast
-					produceOptions.encodings = [
-						{ rid: 'l', maxBitrate: 200000, scaleResolutionDownBy: baseWidth / (targetWidth / 4) },
-						{ rid: 'm', maxBitrate: 700000, scaleResolutionDownBy: baseWidth / (targetWidth / 2) },
-						{ rid: 'h', maxBitrate: targetBitrate, scaleResolutionDownBy: baseWidth / targetWidth }
-					];
-					this.logger.info('VIDEO_QUALITY :: 3-layer simulcast for high-res camera', {
-						baseResolution: `${baseWidth}×${baseHeight}`,
-						maxResolution: maxResolution,
-						targetResolution: `${targetWidth}×${targetHeight}`,
-						layers: [
-							`l: ${Math.round(targetWidth/4)}×${Math.round(targetHeight/4)} @ 200kbps`,
-							`m: ${Math.round(targetWidth/2)}×${Math.round(targetHeight/2)} @ 700kbps`,
-							`h: ${targetWidth}×${targetHeight} @ ${(targetBitrate/1000000).toFixed(1)}Mbps`
-						]
-					});
-				} else if (baseWidth >= 640) {
-					// Medium resolution camera (640×360 to 1280×720) - Use 2-layer
-					// Don't scale down too much on already low-res cameras
-					produceOptions.encodings = [
-						{ rid: 'l', maxBitrate: 200000, scaleResolutionDownBy: 2.0 },
-						{ rid: 'h', maxBitrate: 1200000, scaleResolutionDownBy: 1.0 }
-					];
-					this.logger.info('VIDEO_QUALITY :: 2-layer simulcast for medium-res camera', {
-						baseResolution: `${baseWidth}×${baseHeight}`,
-						layers: [
-							`l: ${Math.round(baseWidth/2)}×${Math.round(baseHeight/2)} @ 200kbps`,
-							`h: ${baseWidth}×${baseHeight} @ 1.2Mbps`
-						]
-					});
-				} else {
-					// Very low resolution camera (<640) - Single layer, higher bitrate
-					produceOptions.encodings = [
-						{ rid: 'h', maxBitrate: 800000, scaleResolutionDownBy: 1.0 }
-					];
-					this.logger.info('VIDEO_QUALITY :: Single layer for low-res camera', {
-						baseResolution: `${baseWidth}×${baseHeight}`,
-						bitrate: '800kbps'
-					});
-				}
-			}
-
-			this.logger.info('Calling transport.produce with options:', {
-				trackKind: track.kind,
-				trackId: track.id,
-				hasEncodings: !!produceOptions.encodings,
-				encodingsCount: produceOptions.encodings?.length,
-				encodings: produceOptions.encodings
-			});
-
-			// Log track settings before producing
-			if (track.kind === 'video') {
-				const settings = track.getSettings();
-				this.logger.info('Video track settings before produce:', {
-					width: settings.width,
-					height: settings.height,
-					frameRate: settings.frameRate,
-					facingMode: settings.facingMode
-				});
-			}
-
-			this.logger.info('About to call sendTransport.produce() - this will trigger the produce event');
-
-			const producer = await this.sendTransport.produce(produceOptions);
-			this.logger.info('sendTransport.produce() succeeded - producer created:', producer.id);
-
-			// Store producer
-			const type = options.appData?.type || track.kind;
-			this.producers.set(type, producer);
-
-			this.emit('producer:created', { producer, type });
-
-			// Handle producer events
-			producer.on('transportclose', () => {
-				this.logger.warn('Producer transport closed:', producer.id);
-				this.producers.delete(type);
-			});
-
-			producer.on('trackended', () => {
-				this.logger.warn('Producer track ended:', producer.id);
-			});
-
-			return producer;
-
-		} catch (error) {
-			this.logger.error('Failed to produce:', error);
-			throw new MediasoupError('Failed to produce media', 'produce', error);
-		}
-	}
-
-	/**
-	 * Consume media (receive from server)
-	 * @param {string} producerId - Producer ID to consume
-	 * @param {string} participantId - Participant ID
-	 * @param {Object} options - Consume options
-	 * @param {number} options.retryAttempt - Current retry attempt (for internal use)
-	 * @returns {Promise<Consumer>}
-	 */
-	async consume(producerId, participantId, options = {}) {
-		if (!this.recvTransport) {
-			await this.createRecvTransport();
-		}
-
-		const retryAttempt = options.retryAttempt || 0;
-		const maxRetries = 3;
-
-		this.logger.info('Consuming producer:', producerId, retryAttempt > 0 ? `(attempt ${retryAttempt + 1}/${maxRetries + 1})` : '');
-
-		try {
-			// Wait for media.consumer.created event from server
-			const consumerParams = await new Promise((resolve, reject) => {
-				const timeout = setTimeout(() => {
-					this.connection.socket.off('media.consumer.created', responseHandler);
-					reject(new Error('Timeout waiting for media.consumer.created'));
-				}, 5000);
-
-				const responseHandler = (data) => {
-					// Check if this response is for our producer request
-					if (data.producer?.id === producerId) {
-						clearTimeout(timeout);
-						this.connection.socket.off('media.consumer.created', responseHandler);
-
-						// Extract consumer params needed by mediasoup
-						const params = {
-							id: data.consumer.id,
-							kind: data.consumer.kind,
-							rtpParameters: data.consumer.rtpParameters,
-							producerId: producerId
-						};
-						resolve(params);
-					}
-				};
-
-				this.connection.socket.on('media.consumer.created', responseHandler);
-
-				// Emit request to server with expected structure
-				this.connection.socket.emit('media.consumer.create', {
-					producer: { id: producerId },
-					consumer: { rtpCapabilities: this.device.rtpCapabilities },
-					participant: { id: participantId }
-				});
-			});
-
-			// Create consumer - this is where duplicate msid errors occur
-			const consumer = await this.recvTransport.consume(consumerParams);
-
-			// Store consumer
-			this.consumers.set(consumer.id, consumer);
-
-			// Register track for stats collection
-			if (consumer.track) {
-				this.statsCollector.registerTrack(
-					consumer.track.id,
-					participantId,
-					consumer.kind
-				);
-			}
-
-			this.emit('consumer:created', { consumer, producerId, participantId });
-
-			// Handle consumer events
-			consumer.on('transportclose', () => {
-				this.logger.warn('Consumer transport closed:', consumer.id);
-				this.consumers.delete(consumer.id);
-
-				// Unregister track from stats
-				if (consumer.track) {
-					this.statsCollector.unregisterTrack(consumer.track.id);
-				}
-			});
-
-			consumer.on('trackended', () => {
-				this.logger.warn('Consumer track ended:', consumer.id);
-			});
-
-			// Consumer starts unpaused on server (paused: false)
-			// No need to resume
-
-			return consumer;
-
-		} catch (error) {
-			// Check if this is a duplicate msid error or other SDP-related error
-			const isDuplicateMsidError = error.message?.includes('Duplicate a=msid') ||
-			                              error.message?.includes('setRemoteDescription') ||
-			                              error.name === 'OperationError';
-
-			// Retry logic for duplicate msid errors
-			if (isDuplicateMsidError && retryAttempt < maxRetries) {
-				const backoffDelay = Math.min(1000 * Math.pow(2, retryAttempt), 5000); // Exponential backoff: 1s, 2s, 4s
-				this.logger.warn(`MediasoupManager :: Consume Failed :: Duplicate msid or SDP error detected, retrying in ${backoffDelay}ms (attempt ${retryAttempt + 1}/${maxRetries})`);
-
-				// Wait before retrying
-				await new Promise(resolve => setTimeout(resolve, backoffDelay));
-
-				// Retry with incremented attempt counter
-				return this.consume(producerId, participantId, { retryAttempt: retryAttempt + 1 });
-			}
-
-			this.logger.error('Failed to consume:', error);
-			throw new MediasoupError('Failed to consume media', 'consume', error);
-		}
-	}
-
-	/**
-	 * Close a producer
-	 * @param {string} type - Producer type (video, audio, screenshare)
-	 */
-	async closeProducer(type) {
-		const producer = this.producers.get(type);
-		if (!producer) {
-			this.logger.warn('Producer not found:', type);
-			return;
-		}
-
-		this.logger.info('Closing producer:', type);
-
-		try {
-			producer.close();
-			this.producers.delete(type);
-
-			// Notify server with correct event name and format
-			await this.connection.request('media.produce.close', {
-				producer: {
-					id: producer.id,
-					producerType: type
-				}
-			});
-
-		} catch (error) {
-			this.logger.error('Failed to close producer:', error);
-		}
-	}
-
-	/**
-	 * Replace track in an existing producer
-	 * @param {string} type - Producer type
-	 * @param {MediaStreamTrack} newTrack - New track to replace with
-	 */
-	async replaceTrack(type, newTrack) {
-		const producer = this.producers.get(type);
-		if (!producer) {
-			this.logger.warn('Producer not found:', type);
-			throw new Error(`Producer not found: ${type}`);
-		}
-
-		this.logger.info('Replacing track for producer:', type);
-
-		try {
-			await producer.replaceTrack({ track: newTrack });
-			this.logger.info('Track replaced successfully for producer:', type);
-		} catch (error) {
-			this.logger.error('Failed to replace track:', error);
-			throw error;
-		}
-	}
-
-	/**
-	 * Pause a producer (mute)
-	 * @param {string} type - Producer type
-	 */
-	async pauseProducer(type) {
-		const producer = this.producers.get(type);
-		if (!producer) {
-			this.logger.warn('Producer not found:', type);
-			return;
-		}
-
-		this.logger.info('Pausing producer:', type);
-
-		try {
-			await producer.pause();
-
-			// Notify server
-			await this.connection.request('media.producer.pause', {
-				producer: {
-					id: producer.id,
-					producerType: type
-				}
-			});
-
-			this.logger.info('Producer paused:', type);
-		} catch (error) {
-			this.logger.error('Failed to pause producer:', error);
-			throw error;
-		}
-	}
-
-	/**
-	 * Resume a producer (unmute)
-	 * @param {string} type - Producer type
-	 */
-	async resumeProducer(type) {
-		const producer = this.producers.get(type);
-		if (!producer) {
-			this.logger.warn('Producer not found:', type);
-			return;
-		}
-
-		this.logger.info('Resuming producer:', type);
-
-		try {
-			await producer.resume();
-
-			// Notify server
-			await this.connection.request('media.producer.resume', {
-				producer: {
-					id: producer.id,
-					producerType: type
-				}
-			});
-
-			this.logger.info('Producer resumed:', type);
-		} catch (error) {
-			this.logger.error('Failed to resume producer:', error);
-			throw error;
-		}
-	}
-
-	/**
-	 * Close a consumer
-	 * @param {string} consumerId - Consumer ID
-	 */
-	async closeConsumer(consumerId) {
-		const consumer = this.consumers.get(consumerId);
-		if (!consumer) {
-			this.logger.warn('Consumer not found:', consumerId);
-			return;
-		}
-
-		this.logger.info('Closing consumer:', consumerId);
-
-		try {
-			consumer.close();
-			this.consumers.delete(consumerId);
-
-		} catch (error) {
-			this.logger.error('Failed to close consumer:', error);
-		}
-	}
-
-	/**
-	 * Clean up all resources
-	 */
-	async cleanup() {
-		this.logger.info('Cleaning up mediasoup resources...');
-
-		// Stop stats collection
-		this.statsCollector.stopAll();
-
-		// Close all producers
-		for (const [type, producer] of this.producers) {
-			try {
-				producer.close();
-			} catch (error) {
-				this.logger.error('Error closing producer:', type, error);
-			}
-		}
-		this.producers.clear();
-
-		// Close all consumers
-		for (const [id, consumer] of this.consumers) {
-			try {
-				consumer.close();
-			} catch (error) {
-				this.logger.error('Error closing consumer:', id, error);
-			}
-		}
-		this.consumers.clear();
-
-		// Close transports
-		if (this.sendTransport) {
-			this.sendTransport.close();
-			this.sendTransport = null;
-		}
-
-		if (this.recvTransport) {
-			this.recvTransport.close();
-			this.recvTransport = null;
-		}
-
-		this.logger.info('Cleanup complete');
-	}
-
-	/**
-	 * Set virtual background store getter for stats collection
-	 * @param {Function} getter - Function that returns virtual background state
-	 */
-	setVirtualBackgroundStore(getter) {
-		this.virtualBackgroundStore = getter;
-	}
-
-	/**
-	 * Get producer by type
-	 * @param {string} type - Producer type
-	 * @returns {Producer|null}
-	 */
-	getProducer(type) {
-		return this.producers.get(type) || null;
-	}
-
-	/**
-	 * Check if device is loaded
-	 * @returns {boolean}
-	 */
-	get isDeviceLoaded() {
-		return this.device.loaded;
-	}
-
-	/**
-	 * Check if device can produce video
-	 * @returns {boolean}
-	 */
-	get canProduceVideo() {
-		return this.device.loaded && this.device.canProduce('video');
-	}
-
-	/**
-	 * Check if device can produce audio
-	 * @returns {boolean}
-	 */
-	get canProduceAudio() {
-		return this.device.loaded && this.device.canProduce('audio');
-	}
+  /**
+   * @param {Object} options
+   * @param {ConnectionManager} options.connection - Connection manager instance
+   * @param {boolean} options.debug - Enable debug logging
+   */
+  constructor(options) {
+    super();
+
+    this.connection = options.connection;
+    this.logger = new Logger("SDK:MediasoupManager", options.debug);
+
+    this.device = new Device();
+    this.sendTransport = null;
+    this.recvTransport = null;
+    this.producers = new Map(); // Map<type, Producer>
+    this.consumers = new Map(); // Map<consumerId, Consumer>
+
+    // Initialize stats collector
+    this.statsCollector = new StatsCollector(this.logger);
+    this.virtualBackgroundStore = null; // Will be set externally
+
+    // Timestamps for tracking transport ICE failure duration. Used by
+    // recreateStaleTransports() on Socket.IO reconnect to decide whether
+    // a network blip was long enough (>10s) to kill WebRTC state, in
+    // which case we must recreate transports rather than expect ICE to
+    // recover on its own.
+    this._sendFailedAt = null;
+    this._recvFailedAt = null;
+  }
+
+  /**
+   * Load device with router RTP capabilities
+   * This sets up a listener for media.routerCapabilities event from server
+   * @returns {Promise<void>}
+   */
+  async loadDevice() {
+    if (this.device.loaded) {
+      this.logger.warn("Device already loaded");
+      return;
+    }
+
+    this.logger.info("Waiting for media.routerCapabilities from server...");
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new MediasoupError("Timeout waiting for router capabilities"));
+      }, 10000);
+
+      // Listen for media.routerCapabilities event from server
+      this.connection.onServerEvent(
+        "media.routerCapabilities",
+        async (data) => {
+          try {
+            clearTimeout(timeout);
+
+            this.logger.info("Received media.routerCapabilities", {
+              hasCapabilities: !!data?.routerRtpCapabilities,
+              codecCount: data?.routerRtpCapabilities?.codecs?.length || 0,
+            });
+
+            const { routerRtpCapabilities } = data;
+
+            if (!routerRtpCapabilities) {
+              throw new MediasoupError(
+                "No router capabilities in server response",
+              );
+            }
+
+            // Debug: Log router codecs
+            this.logger.info(
+              "Router Video Codecs:",
+              routerRtpCapabilities.codecs
+                .filter((c) => c.kind === "video")
+                .map(
+                  (c) =>
+                    `${c.mimeType} (params: ${JSON.stringify(c.parameters || {})})`,
+                ),
+            );
+
+            // Load device
+            await this.device.load({ routerRtpCapabilities });
+
+            this.logger.info("Device loaded successfully", {
+              codecs: this.device.rtpCapabilities.codecs.length,
+              canProduce: {
+                video: this.device.canProduce("video"),
+                audio: this.device.canProduce("audio"),
+              },
+            });
+
+            // Debug: Log device codecs
+            this.logger.info(
+              "Device Video Codecs:",
+              this.device.rtpCapabilities.codecs
+                .filter((c) => c.kind === "video")
+                .map((c) => c.mimeType),
+            );
+
+            this.emit("device:loaded", {
+              rtpCapabilities: this.device.rtpCapabilities,
+            });
+
+            resolve();
+          } catch (error) {
+            this.logger.error("Failed to load device:", error);
+            reject(
+              new MediasoupError("Failed to load device", "loadDevice", error),
+            );
+          }
+        },
+      );
+    });
+  }
+
+  /**
+   * Create send transport for publishing media
+   * @returns {Promise<Transport>}
+   */
+  async createSendTransport() {
+    if (!this.device.loaded) {
+      throw new StateError("Device not loaded", "not-loaded", "loaded");
+    }
+
+    if (this.sendTransport) {
+      this.logger.warn("Send transport already exists");
+      return this.sendTransport;
+    }
+
+    this.logger.info("Creating send transport...");
+
+    try {
+      // Request transport options from server
+      const transportOptions = await this.connection.request(
+        "media.createSendTransport",
+      );
+
+      // Create transport
+      this.sendTransport = this.device.createSendTransport(transportOptions);
+
+      // Setup transport event handlers
+      this._setupSendTransportListeners(this.sendTransport);
+
+      this.emit("transport:created", {
+        direction: "send",
+        id: this.sendTransport.id,
+      });
+
+      return this.sendTransport;
+    } catch (error) {
+      this.logger.error("Failed to create send transport:", error);
+      throw new MediasoupError(
+        "Failed to create send transport",
+        "createSendTransport",
+        error,
+      );
+    }
+  }
+
+  /**
+   * Create receive transport for consuming media
+   * @returns {Promise<Transport>}
+   */
+  async createRecvTransport() {
+    if (!this.device.loaded) {
+      throw new StateError("Device not loaded", "not-loaded", "loaded");
+    }
+
+    if (this.recvTransport) {
+      this.logger.warn("Receive transport already exists");
+      return this.recvTransport;
+    }
+
+    this.logger.info("Creating receive transport...");
+
+    try {
+      // Request transport options from server
+      const transportOptions = await this.connection.request(
+        "media.createRecvTransport",
+      );
+
+      // Create transport
+      this.recvTransport = this.device.createRecvTransport(transportOptions);
+
+      // Setup transport event handlers
+      this._setupRecvTransportListeners(this.recvTransport);
+
+      this.emit("transport:created", {
+        direction: "recv",
+        id: this.recvTransport.id,
+      });
+
+      return this.recvTransport;
+    } catch (error) {
+      this.logger.error("Failed to create receive transport:", error);
+      throw new MediasoupError(
+        "Failed to create receive transport",
+        "createRecvTransport",
+        error,
+      );
+    }
+  }
+
+  /**
+   * Setup send transport event listeners (matches your server's emit/on pattern)
+   * @private
+   */
+  _setupSendTransportListeners() {
+    const transport = this.sendTransport;
+    const socket = this.connection.socket; // Cache socket reference like old system
+
+    // Connect event - DTLS parameters need to be sent to server
+    transport.on("connect", ({ dtlsParameters }, callback, errback) => {
+      this.logger.log("Send transport connecting...");
+
+      // Emit to server
+      socket.emit("media.connectSendTransport", {
+        transportId: transport.id,
+        dtlsParameters,
+      });
+
+      // Listen for success/error responses
+      socket.once("media.connectSendTransport.success", () => {
+        socket.off("media.connectSendTransport.error");
+        this.logger.info("Send transport connected");
+        this.emit("transport:connected", {
+          direction: "send",
+          id: transport.id,
+        });
+
+        // Start stats collection for send transport
+        this.statsCollector.startSendStats(
+          transport,
+          socket,
+          this.virtualBackgroundStore,
+        );
+
+        callback();
+      });
+
+      socket.once("media.connectSendTransport.error", (error) => {
+        socket.off("media.connectSendTransport.success");
+        this.logger.error("Failed to connect send transport:", error);
+        errback(error);
+      });
+    });
+
+    // Produce event - New track needs to be registered with server
+    transport.on(
+      "produce",
+      ({ kind, rtpParameters, appData }, callback, errback) => {
+        this.logger.log("Producing", kind);
+
+        // Emit produce request to server
+        socket.emit("media.produce", {
+          transportId: transport.id,
+          rtpParameters,
+          producerType: appData?.type || kind, // Fixed: use appData.type (matches LocalMediaManager)
+        });
+
+        // Listen for success/error responses - use socket directly
+        socket.once("media.produce.success", ({ producerId }) => {
+          socket.off("media.produce.error");
+          this.logger.info("Producer created:", producerId);
+          callback({ id: producerId });
+        });
+
+        socket.once("media.produce.error", (error) => {
+          socket.off("media.produce.success");
+          this.logger.error("Failed to create producer:", error);
+          errback(error);
+        });
+      },
+    );
+
+    // Connection state change
+    transport.on("connectionstatechange", (state) => {
+      this.logger.info("Send transport state:", state);
+
+      if (state === "failed" || state === "disconnected") {
+        if (!this._sendFailedAt) this._sendFailedAt = Date.now();
+      } else if (state === "connected" || state === "completed") {
+        this._sendFailedAt = null;
+      }
+
+      // Always surface raw transport state so the connection-health monitor
+      // can react to disconnected (transient) as well as failed/closed.
+      this.emit("transport:state", {
+        direction: "send",
+        id: transport.id,
+        state,
+      });
+
+      if (state === "failed" || state === "closed") {
+        this.emit("transport:closed", {
+          direction: "send",
+          id: transport.id,
+          state,
+        });
+      }
+    });
+  }
+
+  /**
+   * Setup receive transport event listeners (matches your server's emit/on pattern)
+   * @private
+   */
+  _setupRecvTransportListeners() {
+    const transport = this.recvTransport;
+
+    // Connect event
+    transport.on("connect", ({ dtlsParameters }, callback, errback) => {
+      this.logger.log("Receive transport connecting...");
+
+      // Emit to server
+      this.connection.emit("media.connectRecvTransport", {
+        transportId: transport.id,
+        dtlsParameters,
+      });
+
+      // Listen for success/error responses
+      this.connection.socket.once("media.connectRecvTransport.success", () => {
+        this.connection.socket.off("media.connectRecvTransport.error");
+        this.logger.info("Receive transport connected");
+        this.emit("transport:connected", {
+          direction: "recv",
+          id: transport.id,
+        });
+
+        // Start stats collection for recv transport
+        this.statsCollector.startRecvStats(
+          transport,
+          this.connection.socket,
+          this.virtualBackgroundStore,
+        );
+
+        callback();
+      });
+
+      this.connection.socket.once(
+        "media.connectRecvTransport.error",
+        (error) => {
+          this.connection.socket.off("media.connectRecvTransport.success");
+          this.logger.error("Failed to connect receive transport:", error);
+          errback(error);
+        },
+      );
+    });
+
+    // Connection state change
+    transport.on("connectionstatechange", (state) => {
+      this.logger.info("Receive transport state:", state);
+
+      if (state === "failed" || state === "disconnected") {
+        if (!this._recvFailedAt) this._recvFailedAt = Date.now();
+      } else if (state === "connected" || state === "completed") {
+        this._recvFailedAt = null;
+      }
+
+      this.emit("transport:state", {
+        direction: "recv",
+        id: transport.id,
+        state,
+      });
+
+      if (state === "failed" || state === "closed") {
+        this.emit("transport:closed", {
+          direction: "recv",
+          id: transport.id,
+          state,
+        });
+      }
+    });
+  }
+
+  /**
+   * After Socket.IO reconnects, check whether the underlying WebRTC
+   * transports have been in a `failed`/`disconnected` state long enough
+   * (>10s) that ICE won't recover on its own. If so, close both transports
+   * and signal the consumer to re-run the `room.join` flow (which yields
+   * fresh routerCapabilities + transport options + producer list from the
+   * server).
+   *
+   * Without this, a long network blip leaves the client with a live
+   * Socket.IO connection but dead WebRTC media — audio and video look
+   * broken to the user even though signaling is fine.
+   *
+   * @returns {boolean} true if transports were recreated
+   */
+  async recreateStaleTransports() {
+    const STALE_THRESHOLD_MS = 10_000;
+    const now = Date.now();
+
+    const sendStale =
+      this._sendFailedAt && now - this._sendFailedAt > STALE_THRESHOLD_MS;
+    const recvStale =
+      this._recvFailedAt && now - this._recvFailedAt > STALE_THRESHOLD_MS;
+
+    if (!sendStale && !recvStale) {
+      return false;
+    }
+
+    this.logger.warn("Transports stale after reconnect — recreating", {
+      sendFailedAt: this._sendFailedAt,
+      recvFailedAt: this._recvFailedAt,
+      now,
+    });
+
+    // Stop stats; close producers, consumers, transports.
+    this.statsCollector.stopAll();
+
+    for (const [type, producer] of this.producers) {
+      try {
+        producer.close();
+      } catch (err) {
+        this.logger.error("closing producer", type, err);
+      }
+    }
+    this.producers.clear();
+
+    for (const [id, consumer] of this.consumers) {
+      try {
+        consumer.close();
+      } catch (err) {
+        this.logger.error("closing consumer", id, err);
+      }
+    }
+    this.consumers.clear();
+
+    if (this.sendTransport) {
+      try {
+        this.sendTransport.close();
+      } catch (err) {
+        this.logger.error("closing sendTransport", err);
+      }
+      this.sendTransport = null;
+    }
+    if (this.recvTransport) {
+      try {
+        this.recvTransport.close();
+      } catch (err) {
+        this.logger.error("closing recvTransport", err);
+      }
+      this.recvTransport = null;
+    }
+
+    this._sendFailedAt = null;
+    this._recvFailedAt = null;
+
+    // Consumer (VideoMeetingClient) reacts to this and drives the
+    // re-join — it owns the room.join emission + the _transportsPromise
+    // wiring.
+    this.emit("transports:recreated-needed");
+
+    return true;
+  }
+
+  /**
+   * Produce media (send to server)
+   * @param {MediaStreamTrack} track - Media track to produce
+   * @param {Object} options - Producer options
+   * @returns {Promise<Producer>}
+   */
+  async produce(track, options = {}) {
+    if (!this.sendTransport) {
+      await this.createSendTransport();
+    }
+
+    this.logger.info("Producing track:", track.kind, track.id);
+    this.logger.info("Produce options received:", {
+      simulcast: options.simulcast,
+      hasSimulcastOption: "simulcast" in options,
+      willEnableSimulcast:
+        track.kind === "video" && options.simulcast !== false,
+    });
+
+    try {
+      // Match old working system exactly - minimal options
+      const produceOptions = {
+        track,
+      };
+
+      // Only add appData if provided (match old system pattern)
+      if (options.appData) {
+        produceOptions.appData = options.appData;
+      }
+
+      // Add simulcast encodings for video tracks (enabled by default, can be disabled)
+      if (track.kind === "video" && options.simulcast !== false) {
+        // Get track settings to determine base resolution
+        const settings = track.getSettings();
+        const baseWidth = settings.width || 1920;
+        const baseHeight = settings.height || 1080;
+
+        // Check if user has set a max resolution preference
+        const maxResolution = options.maxResolution || "1080p"; // Default to 1080p
+
+        // 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;
+        }
+
+        // Adaptive simulcast configuration based on target resolution
+        if (baseWidth >= 1280) {
+          // High resolution camera (720p+) - Use 3-layer simulcast
+          produceOptions.encodings = [
+            {
+              rid: "l",
+              maxBitrate: 200000,
+              scaleResolutionDownBy: baseWidth / (targetWidth / 4),
+            },
+            {
+              rid: "m",
+              maxBitrate: 700000,
+              scaleResolutionDownBy: baseWidth / (targetWidth / 2),
+            },
+            {
+              rid: "h",
+              maxBitrate: targetBitrate,
+              scaleResolutionDownBy: baseWidth / targetWidth,
+            },
+          ];
+          this.logger.info(
+            "VIDEO_QUALITY :: 3-layer simulcast for high-res camera",
+            {
+              baseResolution: `${baseWidth}×${baseHeight}`,
+              maxResolution: maxResolution,
+              targetResolution: `${targetWidth}×${targetHeight}`,
+              layers: [
+                `l: ${Math.round(targetWidth / 4)}×${Math.round(targetHeight / 4)} @ 200kbps`,
+                `m: ${Math.round(targetWidth / 2)}×${Math.round(targetHeight / 2)} @ 700kbps`,
+                `h: ${targetWidth}×${targetHeight} @ ${(targetBitrate / 1000000).toFixed(1)}Mbps`,
+              ],
+            },
+          );
+        } else if (baseWidth >= 640) {
+          // Medium resolution camera (640×360 to 1280×720) - Use 2-layer
+          // Don't scale down too much on already low-res cameras
+          produceOptions.encodings = [
+            { rid: "l", maxBitrate: 200000, scaleResolutionDownBy: 2.0 },
+            { rid: "h", maxBitrate: 1200000, scaleResolutionDownBy: 1.0 },
+          ];
+          this.logger.info(
+            "VIDEO_QUALITY :: 2-layer simulcast for medium-res camera",
+            {
+              baseResolution: `${baseWidth}×${baseHeight}`,
+              layers: [
+                `l: ${Math.round(baseWidth / 2)}×${Math.round(baseHeight / 2)} @ 200kbps`,
+                `h: ${baseWidth}×${baseHeight} @ 1.2Mbps`,
+              ],
+            },
+          );
+        } else {
+          // Very low resolution camera (<640) - Single layer, higher bitrate
+          produceOptions.encodings = [
+            { rid: "h", maxBitrate: 800000, scaleResolutionDownBy: 1.0 },
+          ];
+          this.logger.info("VIDEO_QUALITY :: Single layer for low-res camera", {
+            baseResolution: `${baseWidth}×${baseHeight}`,
+            bitrate: "800kbps",
+          });
+        }
+      }
+
+      this.logger.info("Calling transport.produce with options:", {
+        trackKind: track.kind,
+        trackId: track.id,
+        hasEncodings: !!produceOptions.encodings,
+        encodingsCount: produceOptions.encodings?.length,
+        encodings: produceOptions.encodings,
+      });
+
+      // Log track settings before producing
+      if (track.kind === "video") {
+        const settings = track.getSettings();
+        this.logger.info("Video track settings before produce:", {
+          width: settings.width,
+          height: settings.height,
+          frameRate: settings.frameRate,
+          facingMode: settings.facingMode,
+        });
+      }
+
+      this.logger.info(
+        "About to call sendTransport.produce() - this will trigger the produce event",
+      );
+
+      const producer = await this.sendTransport.produce(produceOptions);
+      this.logger.info(
+        "sendTransport.produce() succeeded - producer created:",
+        producer.id,
+      );
+
+      // Store producer
+      const type = options.appData?.type || track.kind;
+      this.producers.set(type, producer);
+
+      this.emit("producer:created", { producer, type });
+
+      // Handle producer events
+      producer.on("transportclose", () => {
+        this.logger.warn("Producer transport closed:", producer.id);
+        this.producers.delete(type);
+      });
+
+      producer.on("trackended", () => {
+        this.logger.warn("Producer track ended:", producer.id);
+      });
+
+      return producer;
+    } catch (error) {
+      this.logger.error("Failed to produce:", error);
+      throw new MediasoupError("Failed to produce media", "produce", error);
+    }
+  }
+
+  /**
+   * Consume media (receive from server)
+   * @param {string} producerId - Producer ID to consume
+   * @param {string} participantId - Participant ID
+   * @param {Object} options - Consume options
+   * @param {number} options.retryAttempt - Current retry attempt (for internal use)
+   * @returns {Promise<Consumer>}
+   */
+  async consume(producerId, participantId, options = {}) {
+    if (!this.recvTransport) {
+      await this.createRecvTransport();
+    }
+
+    const retryAttempt = options.retryAttempt || 0;
+    const maxRetries = 3;
+
+    this.logger.info(
+      "Consuming producer:",
+      producerId,
+      retryAttempt > 0 ? `(attempt ${retryAttempt + 1}/${maxRetries + 1})` : "",
+    );
+
+    try {
+      // Wait for media.consumer.created event from server
+      const consumerParams = await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          this.connection.socket.off("media.consumer.created", responseHandler);
+          reject(new Error("Timeout waiting for media.consumer.created"));
+        }, 5000);
+
+        const responseHandler = (data) => {
+          // Check if this response is for our producer request
+          if (data.producer?.id === producerId) {
+            clearTimeout(timeout);
+            this.connection.socket.off(
+              "media.consumer.created",
+              responseHandler,
+            );
+
+            // Extract consumer params needed by mediasoup
+            const params = {
+              id: data.consumer.id,
+              kind: data.consumer.kind,
+              rtpParameters: data.consumer.rtpParameters,
+              producerId: producerId,
+            };
+            resolve(params);
+          }
+        };
+
+        this.connection.socket.on("media.consumer.created", responseHandler);
+
+        // Emit request to server with expected structure
+        this.connection.socket.emit("media.consumer.create", {
+          producer: { id: producerId },
+          consumer: { rtpCapabilities: this.device.rtpCapabilities },
+          participant: { id: participantId },
+        });
+      });
+
+      // Create consumer - this is where duplicate msid errors occur
+      const consumer = await this.recvTransport.consume(consumerParams);
+
+      // Tag for later lookup by QualityMonitor / setPeerPreferredLayer.
+      // mediasoup-client's appData is a plain object on the consumer.
+      consumer.appData = { ...(consumer.appData || {}), participantId };
+
+      // Store consumer
+      this.consumers.set(consumer.id, consumer);
+
+      // Register track for stats collection
+      if (consumer.track) {
+        this.statsCollector.registerTrack(
+          consumer.track.id,
+          participantId,
+          consumer.kind,
+        );
+      }
+
+      this.emit("consumer:created", { consumer, producerId, participantId });
+
+      // Handle consumer events
+      consumer.on("transportclose", () => {
+        this.logger.warn("Consumer transport closed:", consumer.id);
+        this.consumers.delete(consumer.id);
+
+        // Unregister track from stats
+        if (consumer.track) {
+          this.statsCollector.unregisterTrack(consumer.track.id);
+        }
+      });
+
+      consumer.on("trackended", () => {
+        this.logger.warn("Consumer track ended:", consumer.id);
+      });
+
+      // Consumer starts unpaused on server (paused: false)
+      // No need to resume
+
+      return consumer;
+    } catch (error) {
+      // Check if this is a duplicate msid error or other SDP-related error
+      const isDuplicateMsidError =
+        error.message?.includes("Duplicate a=msid") ||
+        error.message?.includes("setRemoteDescription") ||
+        error.name === "OperationError";
+
+      // Retry logic for duplicate msid errors
+      if (isDuplicateMsidError && retryAttempt < maxRetries) {
+        const backoffDelay = Math.min(1000 * Math.pow(2, retryAttempt), 5000); // Exponential backoff: 1s, 2s, 4s
+        this.logger.warn(
+          `MediasoupManager :: Consume Failed :: Duplicate msid or SDP error detected, retrying in ${backoffDelay}ms (attempt ${retryAttempt + 1}/${maxRetries})`,
+        );
+
+        // Wait before retrying
+        await new Promise((resolve) => setTimeout(resolve, backoffDelay));
+
+        // Retry with incremented attempt counter
+        return this.consume(producerId, participantId, {
+          retryAttempt: retryAttempt + 1,
+        });
+      }
+
+      this.logger.error("Failed to consume:", error);
+      throw new MediasoupError("Failed to consume media", "consume", error);
+    }
+  }
+
+  /**
+   * Close a producer
+   * @param {string} type - Producer type (video, audio, screenshare)
+   */
+  async closeProducer(type) {
+    const producer = this.producers.get(type);
+    if (!producer) {
+      this.logger.warn("Producer not found:", type);
+      return;
+    }
+
+    this.logger.info("Closing producer:", type);
+
+    try {
+      producer.close();
+      this.producers.delete(type);
+
+      // Notify server with correct event name and format
+      await this.connection.request("media.produce.close", {
+        producer: {
+          id: producer.id,
+          producerType: type,
+        },
+      });
+    } catch (error) {
+      this.logger.error("Failed to close producer:", error);
+    }
+  }
+
+  /**
+   * Replace track in an existing producer
+   * @param {string} type - Producer type
+   * @param {MediaStreamTrack} newTrack - New track to replace with
+   */
+  async replaceTrack(type, newTrack) {
+    const producer = this.producers.get(type);
+    if (!producer) {
+      this.logger.warn("Producer not found:", type);
+      throw new Error(`Producer not found: ${type}`);
+    }
+
+    this.logger.info("Replacing track for producer:", type);
+
+    try {
+      await producer.replaceTrack({ track: newTrack });
+      this.logger.info("Track replaced successfully for producer:", type);
+    } catch (error) {
+      this.logger.error("Failed to replace track:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Pause a producer (mute)
+   * @param {string} type - Producer type
+   */
+  async pauseProducer(type) {
+    const producer = this.producers.get(type);
+    if (!producer) {
+      this.logger.warn("Producer not found:", type);
+      return;
+    }
+
+    this.logger.info("Pausing producer:", type);
+
+    try {
+      await producer.pause();
+
+      // Notify server
+      await this.connection.request("media.producer.pause", {
+        producer: {
+          id: producer.id,
+          producerType: type,
+        },
+      });
+
+      this.logger.info("Producer paused:", type);
+    } catch (error) {
+      this.logger.error("Failed to pause producer:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Resume a producer (unmute)
+   * @param {string} type - Producer type
+   */
+  async resumeProducer(type) {
+    const producer = this.producers.get(type);
+    if (!producer) {
+      this.logger.warn("Producer not found:", type);
+      return;
+    }
+
+    this.logger.info("Resuming producer:", type);
+
+    try {
+      await producer.resume();
+
+      // Notify server
+      await this.connection.request("media.producer.resume", {
+        producer: {
+          id: producer.id,
+          producerType: type,
+        },
+      });
+
+      this.logger.info("Producer resumed:", type);
+    } catch (error) {
+      this.logger.error("Failed to resume producer:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Close a consumer
+   * @param {string} consumerId - Consumer ID
+   */
+  async closeConsumer(consumerId) {
+    const consumer = this.consumers.get(consumerId);
+    if (!consumer) {
+      this.logger.warn("Consumer not found:", consumerId);
+      return;
+    }
+
+    this.logger.info("Closing consumer:", consumerId);
+
+    try {
+      consumer.close();
+      this.consumers.delete(consumerId);
+    } catch (error) {
+      this.logger.error("Failed to close consumer:", error);
+    }
+  }
+
+  /**
+   * Clean up all resources
+   */
+  async cleanup() {
+    this.logger.info("Cleaning up mediasoup resources...");
+
+    // Stop stats collection
+    this.statsCollector.stopAll();
+
+    // Close all producers
+    for (const [type, producer] of this.producers) {
+      try {
+        producer.close();
+      } catch (error) {
+        this.logger.error("Error closing producer:", type, error);
+      }
+    }
+    this.producers.clear();
+
+    // Close all consumers
+    for (const [id, consumer] of this.consumers) {
+      try {
+        consumer.close();
+      } catch (error) {
+        this.logger.error("Error closing consumer:", id, error);
+      }
+    }
+    this.consumers.clear();
+
+    // Close transports
+    if (this.sendTransport) {
+      this.sendTransport.close();
+      this.sendTransport = null;
+    }
+
+    if (this.recvTransport) {
+      this.recvTransport.close();
+      this.recvTransport = null;
+    }
+
+    this.logger.info("Cleanup complete");
+  }
+
+  /**
+   * Set virtual background store getter for stats collection
+   * @param {Function} getter - Function that returns virtual background state
+   */
+  setVirtualBackgroundStore(getter) {
+    this.virtualBackgroundStore = getter;
+  }
+
+  /**
+   * Get producer by type
+   * @param {string} type - Producer type
+   * @returns {Producer|null}
+   */
+  getProducer(type) {
+    return this.producers.get(type) || null;
+  }
+
+  /**
+   * Get the local video (camera) producer. Used by QualityMonitor to
+   * apply simulcast layer caps via the producer's RTCRtpSender.
+   * @returns {Producer|null}
+   */
+  getVideoProducer() {
+    return this.producers.get("video") || this.producers.get("camera") || null;
+  }
+
+  /**
+   * Ask the SFU to forward a lower simulcast layer of the given peer's
+   * video producer to us. spatialLayer 0=low, 1=mid, 2=high.
+   *
+   * mediasoup's consumer.setPreferredLayers is server-side only; the
+   * client signals the request and the SFU applies it. We send via the
+   * existing `media.consumer.setPreferredLayers` event handled by the
+   * pod. Returns true if the event was sent.
+   * @param {string} peerParticipantId
+   * @param {number} spatialLayer
+   */
+  setPeerPreferredLayer(peerParticipantId, spatialLayer) {
+    if (!this.connection?.socket) return false;
+    // 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.
+    let sent = false;
+    for (const consumer of this.consumers.values()) {
+      if (consumer.kind !== "video") continue;
+      if (consumer.appData?.participantId !== peerParticipantId) continue;
+      this.connection.socket.emit("media.consumer.setPreferredLayers", {
+        consumer: { id: consumer.id },
+        preferredLayers: { spatialLayer, temporalLayer: 2 },
+      });
+      sent = true;
+    }
+    return sent;
+  }
+
+  /**
+   * Pause/resume the local consumer AND ask the SFU to stop/start
+   * forwarding bytes for this peer's video. Local pause alone would
+   * stop rendering but the SFU keeps shipping bytes — server-side
+   * pause is what actually frees downlink bandwidth. Scoped to
+   * kind='video' so screenshares aren't affected.
+   *
+   * @param {string} peerParticipantId
+   * @param {boolean} paused — true to pause, false to resume
+   * @returns {boolean} whether at least one consumer was matched
+   */
+  setPeerVideoPaused(peerParticipantId, paused) {
+    if (!this.connection?.socket) return false;
+    const event = paused ? "media.consumer.pause" : "media.consumer.resume";
+    let matched = false;
+    for (const consumer of this.consumers.values()) {
+      if (consumer.kind !== "video") continue;
+      if (consumer.appData?.participantId !== peerParticipantId) continue;
+      try {
+        if (paused) consumer.pause();
+        else consumer.resume();
+      } catch (_e) {}
+      this.connection.socket.emit(event, { consumer: { id: consumer.id } });
+      matched = true;
+    }
+    return matched;
+  }
+
+  /**
+   * Apply pause/resume to every remote video consumer at once. Used by
+   * the "pause all incoming video" control. Returns the count of
+   * consumers affected.
+   * @param {boolean} paused
+   */
+  setAllRemoteVideoPaused(paused) {
+    if (!this.connection?.socket) return 0;
+    const event = paused ? "media.consumer.pause" : "media.consumer.resume";
+    let count = 0;
+    for (const consumer of this.consumers.values()) {
+      if (consumer.kind !== "video") continue;
+      try {
+        if (paused) consumer.pause();
+        else consumer.resume();
+      } catch (_e) {}
+      this.connection.socket.emit(event, { consumer: { id: consumer.id } });
+      count++;
+    }
+    return count;
+  }
+
+  /**
+   * Check if device is loaded
+   * @returns {boolean}
+   */
+  get isDeviceLoaded() {
+    return this.device.loaded;
+  }
+
+  /**
+   * Check if device can produce video
+   * @returns {boolean}
+   */
+  get canProduceVideo() {
+    return this.device.loaded && this.device.canProduce("video");
+  }
+
+  /**
+   * Check if device can produce audio
+   * @returns {boolean}
+   */
+  get canProduceAudio() {
+    return this.device.loaded && this.device.canProduce("audio");
+  }
 }