@unboundcx/video-sdk-client 1.1.0

package/managers/RemoteMediaManager.js

@@ -0,0 +1,972 @@
+import { EventEmitter } from '../utils/EventEmitter.js';
+import { Logger } from '../utils/Logger.js';
+import { AudioMixer } from '../AudioMixer.js';
+
+/**
+ * Manages remote participants and their media streams
+ *
+ * Events:
+ * - 'participant:added' - New remote participant
+ * - 'participant:removed' - Participant left
+ * - 'participant:updated' - Participant data changed
+ * - 'stream:added' - New remote stream
+ * - 'stream:removed' - Remote stream ended
+ */
+export class RemoteMediaManager extends EventEmitter {
+	/**
+	 * @param {Object} options
+	 * @param {MediasoupManager} options.mediasoup - Mediasoup manager instance
+	 * @param {ConnectionManager} options.connection - Connection manager instance
+	 * @param {boolean} options.debug - Enable debug logging
+	 */
+	constructor(options) {
+		super();
+
+		this.mediasoup = options.mediasoup;
+		this.connection = options.connection;
+		this.videoClient = options.videoClient; // Reference to parent VideoMeetingClient
+		this.logger = new Logger('SDK:RemoteMediaManager', options.debug);
+
+		// Map of participants: participantId -> participant data
+		this.participants = new Map();
+
+		// Map of streams: participantId -> { video, audio, screenShare }
+		this.streams = new Map();
+
+		// Map of consumers: consumerId -> { consumer, participantId, type }
+		this.consumers = new Map();
+
+		// Queue for producers that arrived before transports were ready
+		this.pendingProducers = [];
+
+		// Server event listeners will be set up after socket connects
+		this.listenersSetup = false;
+
+		// Map of video element observers: participantId -> { element, observer, lastWidth, lastHeight }
+		this.videoElementTracking = new Map();
+
+		// Map of local mute states for remote streams: `${participantId}:${type}` -> boolean
+		this.localMuteStates = new Map();
+
+		// Audio mixer for scalable audio (30+ participants)
+		this.audioMixer = new AudioMixer();
+		this.useAudioMixer = false; // Will be enabled automatically when participant count >= 30
+		this.MIXER_THRESHOLD = 30; // Threshold for switching to audio mixer
+
+		// Map of participant volumes: participantId -> volume (0.0 to 1.0)
+		this.participantVolumes = new Map();
+	}
+
+	/**
+	 * Setup listeners for server events (call after socket is connected)
+	 * @private
+	 */
+	_setupServerListeners() {
+		if (this.listenersSetup) {
+			this.logger.warn('Server listeners already set up');
+			return;
+		}
+
+		if (!this.connection.socket) {
+			this.logger.warn('Socket not connected yet, cannot set up listeners');
+			return;
+		}
+
+		this.logger.info('Setting up server event listeners');
+
+		// All participants list (sent when you join or when participants change)
+		this.connection.onServerEvent('participant.all', (data) => {
+			this.logger.info('Received all participants');
+			if (data.participants && typeof data.participants === 'object') {
+				// participants is an object: { participantId: {...}, participantId2: {...} }
+				Object.entries(data.participants).forEach(([participantId, participant]) => {
+					// Skip ourselves
+					const myParticipantId = this.videoClient?.joinData?.participant?.id;
+					if (participantId === myParticipantId) {
+						return;
+					}
+
+					// Initialize this participant if not already tracked
+					if (!this.participants.has(participantId)) {
+						this._handleParticipantJoined({ id: participantId, ...participant });
+					}
+				});
+			}
+		});
+
+		// New participant joined
+		this.connection.onServerEvent('participant:joined', (data) => {
+			this.logger.info('Participant joined:', data.participant.id);
+			this._handleParticipantJoined(data.participant);
+		});
+
+		// Participant left
+		this.connection.onServerEvent('participant:left', (data) => {
+			this.logger.info('Participant left:', data.participantId);
+			this._handleParticipantLeft(data.participantId);
+		});
+
+		// Participant updated
+		this.connection.onServerEvent('participant:updated', (data) => {
+			this.logger.log('Participant updated:', data.participant.id);
+			this._handleParticipantUpdated(data.participant);
+		});
+
+		// New producer created (someone started publishing)
+		this.connection.onServerEvent('media.producer.created', (data) => {
+			this.logger.info('Producer created:', data.producer.id, 'by', data.participant.id);
+
+			// Don't consume our own producers (loopback not needed)
+			const myParticipantId = this.videoClient?.joinData?.participant?.id;
+			if (myParticipantId && data.participant.id === myParticipantId) {
+				this.logger.info('Ignoring own producer - no loopback:', data.producer.id);
+				return;
+			}
+
+			this._handleProducerCreated(data.producer, data.participant);
+		});
+
+		// Producer closed (someone stopped publishing)
+		this.connection.onServerEvent('media.producer.closed', (data) => {
+			this.logger.info('Producer closed:', data.producerId);
+			this._handleProducerClosed(data.producerId, data.participantId);
+		});
+
+		// Consumer closed (server closed our consumer for a remote producer)
+		this.connection.onServerEvent('participant.consumer.close', (data) => {
+			this.logger.info('Consumer closed by server:', data.consumer?.id, 'for participant:', data.participant?.id);
+			if (data.consumer?.id) {
+				this._handleConsumerClosed(data.consumer.id);
+			}
+		});
+
+		// Note: Mute/unmute events are handled via 'participant.update' events
+		// which are listened to in VideoMeetingClient and forwarded to the app
+
+		this.listenersSetup = true;
+		this.logger.info('Server event listeners set up successfully');
+	}
+
+	/**
+	 * Handle new participant joined
+	 * @private
+	 */
+	_handleParticipantJoined(participant) {
+		// Store participant data
+		this.participants.set(participant.id, participant);
+
+		// Initialize streams object for this participant
+		this.streams.set(participant.id, {
+			video: null,
+			audio: null,
+			screenShare: null,
+		});
+
+		this.emit('participant:added', { participant });
+
+		// Check if we should enable audio mixer
+		this._checkAudioMixerThreshold();
+	}
+
+	/**
+	 * Handle participant left
+	 * @private
+	 */
+	_handleParticipantLeft(participantId) {
+		// Remove participant
+		const participant = this.participants.get(participantId);
+		this.participants.delete(participantId);
+
+		// Clean up all streams for this participant
+		const streams = this.streams.get(participantId);
+		if (streams) {
+			Object.entries(streams).forEach(([type, stream]) => {
+				if (stream) {
+					this.emit('stream:removed', { participantId, type, stream });
+				}
+			});
+		}
+		this.streams.delete(participantId);
+
+		// Clean up consumers
+		for (const [consumerId, data] of this.consumers) {
+			if (data.participantId === participantId) {
+				data.consumer.close();
+				this.consumers.delete(consumerId);
+			}
+		}
+
+		// Remove from audio mixer if enabled
+		if (this.useAudioMixer) {
+			this.audioMixer.removeParticipant(participantId);
+		}
+
+		// Remove volume setting
+		this.participantVolumes.delete(participantId);
+
+		this.emit('participant:removed', { participantId, participant });
+
+		// Check if we should disable audio mixer
+		this._checkAudioMixerThreshold();
+	}
+
+	/**
+	 * Handle participant updated
+	 * @private
+	 */
+	_handleParticipantUpdated(participant) {
+		// Update participant data
+		this.participants.set(participant.id, participant);
+
+		this.emit('participant:updated', { participant });
+	}
+
+	/**
+	 * Handle new producer created by remote participant
+	 * @private
+	 */
+	async _handleProducerCreated(producer, participant) {
+		try {
+			// Don't consume our own producers
+			const localParticipantId = this.connection.socketId;
+			if (participant.id === localParticipantId) {
+				this.logger.log('Ignoring own producer');
+				return;
+			}
+
+			// Wait for device and transports to be ready before consuming
+			// Transports are created when media.transports event arrives from server
+			if (!this.mediasoup.device.loaded || !this.mediasoup.recvTransport) {
+				this.logger.warn('Device or transport not ready yet, queuing producer:', producer.id);
+				this.pendingProducers.push({ producer, participant });
+				return;
+			}
+
+			// Emit event to let UI know we're attempting to consume a stream
+			const streamType = producer.producerType || producer.type || 'unknown';
+			this.emit('stream:consuming', {
+				participantId: participant.id,
+				type: streamType,
+				producerId: producer.id,
+			});
+
+			// Consume the producer (with retry logic)
+			const consumer = await this.mediasoup.consume(
+				producer.id,
+				participant.id
+			);
+
+			// Store consumer
+			this.consumers.set(consumer.id, {
+				consumer,
+				participantId: participant.id,
+				producerId: producer.id,
+				type: producer.producerType || producer.type || consumer.kind,
+			});
+
+			// Get the media stream from the consumer
+			const stream = new MediaStream([consumer.track]);
+
+			// Store stream by type
+			const participantStreams = this.streams.get(participant.id);
+			if (participantStreams) {
+				const streamType = producer.producerType || producer.type || consumer.kind;
+				participantStreams[streamType] = stream;
+			}
+
+			this.logger.info('RemoteMediaManager :: Stream Consumed ::', {
+				participantId: participant.id,
+				type: producer.producerType || producer.type || consumer.kind,
+				consumerId: consumer.id,
+			});
+
+			const finalStreamType = producer.producerType || producer.type || consumer.kind;
+
+			// Add audio stream to mixer if enabled and it's an audio stream
+			if (this.useAudioMixer && finalStreamType === 'audio') {
+				const volume = this.participantVolumes.get(participant.id) || 1.0;
+				this.audioMixer.addParticipant(participant.id, stream, volume);
+			}
+
+			// Emit stream added event
+			this.emit('stream:added', {
+				participantId: participant.id,
+				type: finalStreamType,
+				stream,
+				consumer,
+			});
+
+			// Handle consumer close
+			consumer.on('transportclose', () => {
+				this.logger.warn('Consumer transport closed:', consumer.id);
+				this._handleConsumerClosed(consumer.id);
+			});
+
+			consumer.on('trackended', () => {
+				this.logger.warn('Consumer track ended:', consumer.id);
+				this._handleConsumerClosed(consumer.id);
+			});
+
+		} catch (error) {
+			const streamType = producer.producerType || producer.type || 'unknown';
+			this.logger.error('RemoteMediaManager :: Failed to Consume Producer ::', {
+				participantId: participant.id,
+				producerId: producer.id,
+				type: streamType,
+				error: error.message
+			});
+
+			// Emit failure event so UI can show error or retry later
+			this.emit('stream:consume-failed', {
+				participantId: participant.id,
+				type: streamType,
+				producerId: producer.id,
+				error: error.message,
+				canRetryManually: true
+			});
+		}
+	}
+
+	/**
+	 * Handle producer closed by remote participant
+	 * @private
+	 */
+	_handleProducerClosed(producerId, participantId) {
+		// Find and close the consumer for this producer
+		for (const [consumerId, data] of this.consumers) {
+			if (data.producerId === producerId) {
+				this._handleConsumerClosed(consumerId);
+				break;
+			}
+		}
+	}
+
+	/**
+	 * Handle consumer closed
+	 * @private
+	 */
+	_handleConsumerClosed(consumerId) {
+		const consumerData = this.consumers.get(consumerId);
+		if (!consumerData) return;
+
+		const { consumer, participantId, type } = consumerData;
+
+		// Close consumer
+		consumer.close();
+		this.consumers.delete(consumerId);
+
+		// Remove stream
+		const participantStreams = this.streams.get(participantId);
+		if (participantStreams && participantStreams[type]) {
+			const stream = participantStreams[type];
+			participantStreams[type] = null;
+
+			this.emit('stream:removed', { participantId, type, stream });
+		}
+
+		this.logger.info('Consumer closed:', consumerId);
+	}
+
+	/**
+	 * Get participant by ID
+	 * @param {string} participantId - Participant ID
+	 * @returns {Object|null} Participant data
+	 */
+	getParticipant(participantId) {
+		return this.participants.get(participantId) || null;
+	}
+
+	/**
+	 * Get all participants
+	 * @returns {Array<Object>} Array of participant data
+	 */
+	getAllParticipants() {
+		return Array.from(this.participants.values());
+	}
+
+	/**
+	 * Get stream for a participant
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (video, audio, screenShare)
+	 * @returns {MediaStream|null}
+	 */
+	getStream(participantId, type) {
+		const streams = this.streams.get(participantId);
+		return streams ? streams[type] : null;
+	}
+
+	/**
+	 * Get all streams for a participant
+	 * @param {string} participantId - Participant ID
+	 * @returns {Object|null} Object with video, audio, screenShare streams
+	 */
+	getStreams(participantId) {
+		return this.streams.get(participantId) || null;
+	}
+
+	/**
+	 * Check if participant has active video
+	 * @param {string} participantId - Participant ID
+	 * @returns {boolean}
+	 */
+	hasVideo(participantId) {
+		const streams = this.streams.get(participantId);
+		return !!(streams && streams.video);
+	}
+
+	/**
+	 * Check if participant has active audio
+	 * @param {string} participantId - Participant ID
+	 * @returns {boolean}
+	 */
+	hasAudio(participantId) {
+		const streams = this.streams.get(participantId);
+		return !!(streams && streams.audio);
+	}
+
+	/**
+	 * Check if participant is sharing screen
+	 * @param {string} participantId - Participant ID
+	 * @returns {boolean}
+	 */
+	hasScreenShare(participantId) {
+		const streams = this.streams.get(participantId);
+		return !!(streams && streams.screenShare);
+	}
+
+	/**
+	 * Get participant count
+	 * @returns {number}
+	 */
+	get participantCount() {
+		return this.participants.size;
+	}
+
+	/**
+	 * Process pending producers that arrived before transports were ready
+	 * This should be called after transports are created
+	 */
+	async processPendingProducers() {
+		if (this.pendingProducers.length === 0) {
+			return;
+		}
+
+		this.logger.info(`Processing ${this.pendingProducers.length} pending producers`);
+
+		// Process all pending producers
+		const pending = [...this.pendingProducers];
+		this.pendingProducers = [];
+
+		for (const { producer, participant } of pending) {
+			try {
+				await this._handleProducerCreated(producer, participant);
+			} catch (error) {
+				this.logger.error('Failed to process pending producer:', producer.id, error);
+			}
+		}
+	}
+
+	/**
+	 * Calculate optimal spatial layer based on video element dimensions
+	 * @private
+	 * @param {number} width - Video element width in pixels
+	 * @param {number} height - Video element height in pixels
+	 * @returns {number} - Optimal spatial layer (0-2)
+	 */
+	_calculateOptimalSpatialLayer(width, height) {
+		// Use the larger dimension to determine quality
+		const maxDimension = Math.max(width, height);
+
+		// Spatial layer mapping (assumes standard simulcast layers):
+		// Layer 0: 320x180  - for thumbnails < 240px
+		// Layer 1: 960x540  - for medium tiles 240px - 540px
+		// Layer 2: 1920x1080 - for large tiles/fullscreen > 540px
+
+		if (maxDimension <= 240) {
+			return 0; // Low quality for small thumbnails
+		} else if (maxDimension <= 540) {
+			return 1; // Medium quality for smaller grid tiles
+		} else {
+			return 2; // High quality (1080p) for anything larger
+		}
+	}
+
+	/**
+	 * Track a video element and automatically adjust consumer layers on resize
+	 * @param {string} participantId - Participant ID
+	 * @param {HTMLVideoElement} videoElement - Video element to track
+	 */
+	trackVideoElement(participantId, videoElement) {
+		if (!videoElement) {
+			this.logger.warn('Cannot track null video element for participant:', participantId);
+			return;
+		}
+
+		// Clean up any existing tracking for this participant
+		this.untrackVideoElement(participantId);
+
+		// Get the video consumer for this participant
+		const videoConsumer = this._getVideoConsumerForParticipant(participantId);
+		if (!videoConsumer) {
+			this.logger.warn('No video consumer found for participant:', participantId);
+			return;
+		}
+
+		// Create ResizeObserver to track element size changes
+		const observer = new ResizeObserver((entries) => {
+			for (const entry of entries) {
+				const { width, height } = entry.contentRect;
+
+				// Only update if size changed significantly (avoid tiny changes)
+				const tracking = this.videoElementTracking.get(participantId);
+				if (tracking) {
+					const widthDiff = Math.abs(width - tracking.lastWidth);
+					const heightDiff = Math.abs(height - tracking.lastHeight);
+
+					// Threshold: 50px change to avoid excessive updates
+					if (widthDiff < 50 && heightDiff < 50) {
+						return;
+					}
+
+					tracking.lastWidth = width;
+					tracking.lastHeight = height;
+				}
+
+				// Calculate optimal layer
+				const optimalLayer = this._calculateOptimalSpatialLayer(width, height);
+
+				// Update consumer preferred layers
+				this._updateConsumerLayers(videoConsumer, optimalLayer);
+
+				this.logger.log('Video element resized', {
+					participantId,
+					width: Math.round(width),
+					height: Math.round(height),
+					spatialLayer: optimalLayer,
+				});
+			}
+		});
+
+		// Start observing
+		observer.observe(videoElement);
+
+		// Store tracking info
+		this.videoElementTracking.set(participantId, {
+			element: videoElement,
+			observer,
+			lastWidth: videoElement.clientWidth,
+			lastHeight: videoElement.clientHeight,
+		});
+
+		// Set initial layer based on current size
+		const initialLayer = this._calculateOptimalSpatialLayer(
+			videoElement.clientWidth,
+			videoElement.clientHeight
+		);
+		this._updateConsumerLayers(videoConsumer, initialLayer);
+
+		this.logger.info('Started tracking video element', {
+			participantId,
+			width: videoElement.clientWidth,
+			height: videoElement.clientHeight,
+			initialLayer,
+		});
+	}
+
+	/**
+	 * Stop tracking a video element
+	 * @param {string} participantId - Participant ID
+	 */
+	untrackVideoElement(participantId) {
+		const tracking = this.videoElementTracking.get(participantId);
+		if (tracking) {
+			tracking.observer.disconnect();
+			this.videoElementTracking.delete(participantId);
+			this.logger.log('Stopped tracking video element for participant:', participantId);
+		}
+	}
+
+	/**
+	 * Get video consumer for a participant
+	 * @private
+	 * @param {string} participantId - Participant ID
+	 * @returns {Object|null} Consumer object
+	 */
+	_getVideoConsumerForParticipant(participantId) {
+		for (const [consumerId, data] of this.consumers) {
+			if (data.participantId === participantId && data.type === 'video') {
+				return data.consumer;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Update consumer preferred layers
+	 * @private
+	 * @param {Object} consumer - Mediasoup consumer
+	 * @param {number} spatialLayer - Desired spatial layer (0-2)
+	 */
+	async _updateConsumerLayers(consumer, spatialLayer) {
+		if (!consumer || typeof consumer.setPreferredLayers !== 'function') {
+			// This is normal for audio consumers - they don't support simulcast
+			this.logger.log('RemoteMediaManager :: Skip Layer Update :: Consumer does not support simulcast layers (likely audio)');
+			return;
+		}
+
+		// Check if the consumer has multiple layers available (simulcast enabled)
+		// If there's only one layer, no point in setting preferred layers
+		if (consumer.rtpParameters?.encodings?.length <= 1) {
+			this.logger.log('RemoteMediaManager :: Skip Layer Update :: Consumer has single layer (simulcast not enabled)');
+			return;
+		}
+
+		try {
+			// Set preferred layers: spatialLayer and temporalLayer
+			// temporalLayer 2 = highest frame rate for the spatial layer
+			await consumer.setPreferredLayers({
+				spatialLayer: spatialLayer,
+				temporalLayer: 2,
+			});
+
+			this.logger.log('RemoteMediaManager :: Updated Consumer Layers ::', {
+				consumerId: consumer.id,
+				spatialLayer,
+				temporalLayer: 2,
+			});
+		} catch (error) {
+			this.logger.error('RemoteMediaManager :: Failed to Update Consumer Layers ::', error);
+		}
+	}
+
+	/**
+	 * Clean up all remote media
+	 */
+	async cleanup() {
+		this.logger.info('Cleaning up remote media...');
+
+		// Stop tracking all video elements
+		for (const participantId of this.videoElementTracking.keys()) {
+			this.untrackVideoElement(participantId);
+		}
+
+		// Close all consumers
+		for (const [consumerId, data] of this.consumers) {
+			try {
+				data.consumer.close();
+			} catch (error) {
+				this.logger.error('Error closing consumer:', consumerId, error);
+			}
+		}
+
+		this.consumers.clear();
+		this.participants.clear();
+		this.streams.clear();
+		this.localMuteStates.clear();
+
+		this.logger.info('Remote media cleanup complete');
+	}
+
+	/**
+	 * Locally mute a remote stream (for the local user only, doesn't affect other viewers)
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (audio, screenShareAudio)
+	 * @returns {boolean} Success
+	 */
+	localMuteRemoteStream(participantId, type) {
+		const key = `${participantId}:${type}`;
+		const streams = this.streams.get(participantId);
+
+		if (!streams) {
+			this.logger.warn('No streams found for participant:', participantId);
+			return false;
+		}
+
+		// Get the stream for the specified type
+		const stream = streams[type];
+
+		if (!stream) {
+			this.logger.warn('Stream not found:', type, 'for participant:', participantId);
+			return false;
+		}
+
+		// Mute audio tracks
+		const audioTracks = stream.getAudioTracks();
+		if (audioTracks.length === 0) {
+			this.logger.warn('No audio tracks found in stream:', type);
+			return false;
+		}
+
+		audioTracks.forEach(track => {
+			track.enabled = false;
+		});
+
+		this.localMuteStates.set(key, true);
+		this.logger.info('Locally muted remote stream:', participantId, type);
+
+		this.emit('local-mute-changed', { participantId, type, muted: true });
+
+		return true;
+	}
+
+	/**
+	 * Locally unmute a remote stream (for the local user only)
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (audio, screenShareAudio)
+	 * @returns {boolean} Success
+	 */
+	localUnmuteRemoteStream(participantId, type) {
+		const key = `${participantId}:${type}`;
+		const streams = this.streams.get(participantId);
+
+		if (!streams) {
+			this.logger.warn('No streams found for participant:', participantId);
+			return false;
+		}
+
+		// Get the stream for the specified type
+		const stream = streams[type];
+
+		if (!stream) {
+			this.logger.warn('Stream not found:', type, 'for participant:', participantId);
+			return false;
+		}
+
+		// Unmute audio tracks
+		const audioTracks = stream.getAudioTracks();
+		if (audioTracks.length === 0) {
+			this.logger.warn('No audio tracks found in stream:', type);
+			return false;
+		}
+
+		audioTracks.forEach(track => {
+			track.enabled = true;
+		});
+
+		this.localMuteStates.set(key, false);
+		this.logger.info('Locally unmuted remote stream:', participantId, type);
+
+		this.emit('local-mute-changed', { participantId, type, muted: false });
+
+		return true;
+	}
+
+	/**
+	 * Toggle local mute state for a remote stream
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (audio, screenShareAudio)
+	 * @returns {boolean} New mute state
+	 */
+	toggleLocalMuteRemoteStream(participantId, type) {
+		const key = `${participantId}:${type}`;
+		const currentlyMuted = this.localMuteStates.get(key) || false;
+
+		if (currentlyMuted) {
+			this.localUnmuteRemoteStream(participantId, type);
+		} else {
+			this.localMuteRemoteStream(participantId, type);
+		}
+
+		return this.localMuteStates.get(key) || false;
+	}
+
+	/**
+	 * Get local mute state for a remote stream
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type
+	 * @returns {boolean} Mute state
+	 */
+	isLocallyMuted(participantId, type) {
+		const key = `${participantId}:${type}`;
+		return this.localMuteStates.get(key) || false;
+	}
+
+	/**
+	 * Set volume for a specific participant (0.0 to 1.0)
+	 * Works with both audio elements and audio mixer
+	 * @param {string} participantId - Participant ID
+	 * @param {number} volume - Volume level (0.0 to 1.0)
+	 * @returns {boolean} Success status
+	 */
+	setParticipantVolume(participantId, volume) {
+		// Clamp volume
+		const clampedVolume = Math.max(0, Math.min(1, volume));
+
+		console.log('SDK :: RemoteMediaManager :: setParticipantVolume:', {
+			participantId,
+			originalVolume: volume,
+			clampedVolume,
+			useAudioMixer: this.useAudioMixer,
+			mixerInitialized: this.audioMixer?.isInitialized
+		});
+
+		// Store volume setting
+		this.participantVolumes.set(participantId, clampedVolume);
+
+		// Apply to audio mixer if enabled
+		if (this.useAudioMixer && this.audioMixer.isInitialized) {
+			console.log('SDK :: RemoteMediaManager :: Using AudioMixer for volume control');
+			return this.audioMixer.setParticipantVolume(participantId, clampedVolume);
+		}
+
+		// If not using mixer, volume control happens at app level (audio elements)
+		// Emit event so app can update audio element volume
+		console.log('SDK :: RemoteMediaManager :: Emitting participant:volume-changed event');
+		this.emit('participant:volume-changed', {
+			participantId,
+			volume: clampedVolume,
+		});
+
+		return true;
+	}
+
+	/**
+	 * Get volume for a specific participant
+	 * @param {string} participantId - Participant ID
+	 * @returns {number} Volume level (0.0 to 1.0)
+	 */
+	getParticipantVolume(participantId) {
+		if (this.useAudioMixer && this.audioMixer.isInitialized) {
+			const mixerVolume = this.audioMixer.getParticipantVolume(participantId);
+			if (mixerVolume !== null) {
+				return mixerVolume;
+			}
+		}
+		// Fix: Use ?? instead of || to allow 0 as valid volume (0 is falsy but valid)
+		const volume = this.participantVolumes.get(participantId);
+		return volume !== undefined ? volume : 1.0;
+	}
+
+	/**
+	 * Retry consuming a failed producer
+	 * Public method to allow manual retry from UI
+	 * @param {string} producerId - Producer ID to retry
+	 * @param {string} participantId - Participant ID
+	 * @returns {Promise<boolean>} Success status
+	 */
+	async retryConsumeProducer(producerId, participantId) {
+		this.logger.info('RemoteMediaManager :: Manually Retrying Producer ::', {
+			producerId,
+			participantId
+		});
+
+		try {
+			// Find the producer in pending list or create a minimal producer object
+			const pendingProducer = this.pendingProducers.find(
+				p => p.producer.id === producerId && p.participant.id === participantId
+			);
+
+			if (pendingProducer) {
+				// Remove from pending and retry
+				this.pendingProducers = this.pendingProducers.filter(
+					p => !(p.producer.id === producerId && p.participant.id === participantId)
+				);
+				await this._handleProducerCreated(pendingProducer.producer, pendingProducer.participant);
+			} else {
+				// Create minimal producer object for retry
+				const participant = this.participants.get(participantId);
+				if (!participant) {
+					throw new Error('Participant not found');
+				}
+
+				await this._handleProducerCreated({ id: producerId }, participant);
+			}
+
+			return true;
+		} catch (error) {
+			this.logger.error('RemoteMediaManager :: Manual Retry Failed ::', error);
+			return false;
+		}
+	}
+
+	/**
+	 * Check if audio mixer should be enabled based on participant count
+	 * @private
+	 */
+	async _checkAudioMixerThreshold() {
+		const participantCount = this.participants.size;
+
+		// Should we enable the mixer?
+		const shouldUseMixer = participantCount >= this.MIXER_THRESHOLD;
+
+		// Already in correct state
+		if (shouldUseMixer === this.useAudioMixer) {
+			return;
+		}
+
+		if (shouldUseMixer && !this.useAudioMixer) {
+			// Enable mixer
+			this.logger.info(`Enabling audio mixer (${participantCount} participants >= ${this.MIXER_THRESHOLD})`);
+			await this._enableAudioMixer();
+		} else if (!shouldUseMixer && this.useAudioMixer) {
+			// Disable mixer
+			this.logger.info(`Disabling audio mixer (${participantCount} participants < ${this.MIXER_THRESHOLD})`);
+			await this._disableAudioMixer();
+		}
+	}
+
+	/**
+	 * Enable audio mixer
+	 * @private
+	 */
+	async _enableAudioMixer() {
+		try {
+			// Initialize mixer if not already
+			if (!this.audioMixer.isInitialized) {
+				await this.audioMixer.initialize();
+			}
+
+			// Resume context (may be suspended due to autoplay policy)
+			await this.audioMixer.resume();
+
+			// Add all current audio streams to mixer
+			for (const [participantId, streams] of this.streams) {
+				if (streams.audio) {
+					const volume = this.participantVolumes.get(participantId) || 1.0;
+					this.audioMixer.addParticipant(participantId, streams.audio, volume);
+				}
+			}
+
+			this.useAudioMixer = true;
+
+			// Emit event so app knows to stop using audio elements
+			this.emit('audio-mixer:enabled', {
+				participantCount: this.participants.size,
+			});
+
+			this.logger.info('Audio mixer enabled');
+		} catch (err) {
+			this.logger.error('Failed to enable audio mixer:', err);
+		}
+	}
+
+	/**
+	 * Disable audio mixer
+	 * @private
+	 */
+	async _disableAudioMixer() {
+		try {
+			// Clear all participants from mixer
+			this.audioMixer.clear();
+
+			this.useAudioMixer = false;
+
+			// Emit event so app knows to use audio elements again
+			this.emit('audio-mixer:disabled', {
+				participantCount: this.participants.size,
+			});
+
+			this.logger.info('Audio mixer disabled');
+		} catch (err) {
+			this.logger.error('Failed to disable audio mixer:', err);
+		}
+	}
+
+	/**
+	 * Get whether audio mixer is currently active
+	 * @returns {boolean}
+	 */
+	isAudioMixerEnabled() {
+		return this.useAudioMixer;
+	}
+}