@unboundcx/video-sdk-client 1.1.0

package/VideoMeetingClient.js

@@ -0,0 +1,1210 @@
+import { EventEmitter } from './utils/EventEmitter.js';
+import { Logger } from './utils/Logger.js';
+import { ConnectionManager } from './managers/ConnectionManager.js';
+import { MediasoupManager } from './managers/MediasoupManager.js';
+import { LocalMediaManager } from './managers/LocalMediaManager.js';
+import { RemoteMediaManager } from './managers/RemoteMediaManager.js';
+import { StateError, RoomError } from './utils/errors.js';
+
+/**
+ * Main SDK client for video meeting functionality
+ *
+ * @example
+ * const client = new VideoMeetingClient({
+ *   serverUrl: 'wss://video.example.com',
+ *   debug: true
+ * });
+ *
+ * await client.connect(authToken);
+ * await client.joinRoom(roomId);
+ * await client.publishCamera();
+ *
+ * client.on('stream:added', ({ participantId, stream, type }) => {
+ *   // Handle remote stream
+ * });
+ */
+export class VideoMeetingClient extends EventEmitter {
+	/**
+	 * @param {Object} options
+	 * @param {string} [options.serverUrl] - WebSocket server URL (optional if using joinFromApiResponse)
+	 * @param {boolean} [options.debug=false] - Enable debug logging
+	 */
+	constructor(options = {}) {
+		super();
+
+		this.logger = new Logger('SDK:VideoMeetingClient', options.debug);
+		this.state = 'disconnected'; // disconnected, connecting, connected, waiting-room, in-meeting
+		this.currentRoomId = null;
+		this.joinData = null; // Store video.join() response data
+		this.debug = options.debug;
+		this.isGuest = false;
+		this.inWaitingRoom = false;
+
+		// Managers will be initialized when we have connection info
+		this.connection = null;
+		this.mediasoup = null;
+		this.localMedia = null;
+		this.remoteMedia = null;
+
+		// If serverUrl provided, initialize managers now (old behavior)
+		if (options.serverUrl) {
+			this._initializeManagers(options.serverUrl);
+		}
+
+		this.logger.info('VideoMeetingClient initialized');
+	}
+
+	/**
+	 * Initialize managers with server URL
+	 * @private
+	 */
+	_initializeManagers(serverUrl) {
+		this.connection = new ConnectionManager({
+			serverUrl,
+			debug: this.debug,
+		});
+
+		this.mediasoup = new MediasoupManager({
+			connection: this.connection,
+			debug: this.debug,
+		});
+
+		this.localMedia = new LocalMediaManager({
+			mediasoup: this.mediasoup,
+			debug: this.debug,
+		});
+
+		this.remoteMedia = new RemoteMediaManager({
+			mediasoup: this.mediasoup,
+			connection: this.connection,
+			videoClient: this, // Pass reference to access joinData
+			debug: this.debug,
+		});
+
+		// Proxy manager events to SDK events
+		this._setupEventProxies();
+	}
+
+	/**
+	 * Setup event proxies from managers to SDK
+	 * @private
+	 */
+	_setupEventProxies() {
+		// Connection events
+		this.connection.on('connected', () => {
+			this._setState('connected');
+			this.emit('connected');
+		});
+
+		this.connection.on('disconnected', (data) => {
+			this._setState('disconnected');
+			this.emit('disconnected', data);
+		});
+
+		this.connection.on('error', (error) => {
+			this.emit('error', error);
+		});
+
+		// Local media events
+		this.localMedia.on('stream:added', (data) => {
+			this.emit('local-stream:added', data);
+		});
+
+		this.localMedia.on('stream:removed', (data) => {
+			this.emit('local-stream:removed', data);
+		});
+
+		this.localMedia.on('device:changed', (data) => {
+			this.emit('device:changed', data);
+		});
+
+		// Remote media events
+		this.remoteMedia.on('participant:added', (data) => {
+			this.emit('participant:joined', data);
+		});
+
+		this.remoteMedia.on('participant:removed', (data) => {
+			this.emit('participant:left', data);
+		});
+
+		this.remoteMedia.on('participant:updated', (data) => {
+			this.emit('participant:updated', data);
+		});
+
+		this.remoteMedia.on('stream:added', (data) => {
+			this.emit('stream:added', data);
+		});
+
+		this.remoteMedia.on('stream:removed', (data) => {
+			this.emit('stream:removed', data);
+		});
+
+		// Stream consuming events (for retry logic and error handling)
+		this.remoteMedia.on('stream:consuming', (data) => {
+			this.emit('stream:consuming', data);
+		});
+
+		this.remoteMedia.on('stream:consume-failed', (data) => {
+			this.emit('stream:consume-failed', data);
+		});
+
+		// Volume control events
+		this.remoteMedia.on('participant:volume-changed', (data) => {
+			this.emit('participant:volume-changed', data);
+		});
+	}
+
+	/**
+	 * Setup room/participant event listeners
+	 * @private
+	 */
+	_setupRoomEventListeners() {
+		// Room events
+		this.connection.onServerEvent('room.closed', (data) => {
+			this.logger.info('Room closed', data);
+			this._setState('disconnected');
+			this.emit('room:closed', data);
+		});
+
+		this.connection.onServerEvent('room.update', (data) => {
+			this.logger.info('Room updated', data);
+			this.emit('room:updated', data);
+		});
+
+		// Participant events
+		this.connection.onServerEvent('participant.all', (data) => {
+			this.logger.info('All participants', data);
+			this.emit('participants:list', data);
+		});
+
+		this.connection.onServerEvent('participant.leave', (data) => {
+			this.logger.info('Participant left', data);
+			this.emit('participant:left', data);
+		});
+
+		this.connection.onServerEvent('participant.remove', (data) => {
+			this.logger.info('Participant removed', data);
+			this.emit('participant:removed', data);
+		});
+
+		this.connection.onServerEvent('participant.update', (data) => {
+			this.logger.info('Participant updated', data);
+			this.emit('participant:updated', data);
+		});
+
+		// Producer close event (for quality adaptation / reconnect)
+		this.connection.onServerEvent('participant.producer.close', async (data) => {
+			this.logger.info('Producer close requested', data);
+			await this._handleProducerCloseRequest(data);
+		});
+
+		// Waiting room events
+		this.connection.onServerEvent('room.waitingRoom.admit', (data) => {
+			this.logger.info('Admitted from waiting room', data);
+			this.inWaitingRoom = false;
+			this._setState('in-meeting');
+			this.emit('waitingRoom:admitted', data);
+		});
+
+		// Keepalive events
+		this.connection.onServerEvent('keepalive.send', (data) => {
+			this.emit('keepalive:received', data);
+			this.connection.emit('keepalive.ack', data);
+		});
+
+		this.connection.onServerEvent('keepalive.alert', (data) => {
+			this.emit('keepalive:alert', data);
+		});
+	}
+
+	/**
+	 * Connect to the server
+	 * @param {Object|string} auth - Authentication token or auth object
+	 * @returns {Promise<void>}
+	 */
+	async connect(auth = {}) {
+		if (this.state !== 'disconnected') {
+			throw new StateError(
+				'Cannot connect: already connected or connecting',
+				this.state,
+				'disconnected'
+			);
+		}
+
+		this.logger.info('Connecting to server...');
+		this._setState('connecting');
+
+		try {
+			// Normalize auth to object format
+			const authObj = typeof auth === 'string' ? { token: auth } : auth;
+
+			// Connect to server
+			await this.connection.connect(authObj);
+
+			// Load mediasoup device
+			await this.mediasoup.loadDevice();
+
+			this.logger.info('Connected successfully');
+			this._setState('connected');
+
+		} catch (error) {
+			this.logger.error('Connection failed:', error);
+			this._setState('disconnected');
+			throw error;
+		}
+	}
+
+	/**
+	 * Disconnect from server
+	 * @returns {Promise<void>}
+	 */
+	async disconnect() {
+		this.logger.info('Disconnecting...');
+
+		try {
+			// Leave room if in one
+			if (this.state === 'in-room') {
+				await this.leaveRoom();
+			}
+
+			// Clean up managers
+			await this.localMedia.cleanup();
+			await this.remoteMedia.cleanup();
+			await this.mediasoup.cleanup();
+
+			// Disconnect socket
+			await this.connection.disconnect();
+
+			this._setState('disconnected');
+			this.logger.info('Disconnected successfully');
+
+		} catch (error) {
+			this.logger.error('Disconnect error:', error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Join meeting directly from API response (api.video.joinRoom)
+	 * This method extracts server info, connects, and determines if user needs to wait
+	 *
+	 * @param {Object} joinResponse - Response from api.video.joinRoom(room, password, email)
+	 * @param {Object} options - Additional options
+	 * @param {boolean} options.enterWaitingRoom - For guests, enter waiting room (default: auto-detect)
+	 * @returns {Promise<Object>} Join data
+	 *
+	 * @example
+	 * const joinResponse = await api.video.joinRoom('room-123', 'password', 'user@example.com');
+	 * await client.joinFromApiResponse(joinResponse);
+	 *
+	 * // For guests in waiting room:
+	 * client.on('waitingRoom:entered', () => showWaitingRoomUI());
+	 * client.on('waitingRoom:admitted', () => showMeetingUI());
+	 */
+	async joinFromApiResponse(joinResponse, options = {}) {
+		this.logger.info('Joining from API response');
+
+		try {
+			// Extract data from API response
+			const { server, authorization, videoRoom, participant } = joinResponse;
+
+			if (!server?.url || !server?.socketPort) {
+				throw new Error('Invalid join response: missing server info');
+			}
+
+			// Store join data for later use
+			this.joinData = {
+				videoRoom,
+				participant,
+				server,
+				authorization
+			};
+
+			// Detect if this is a guest (no host privileges)
+			this.isGuest = !participant.isHost && !participant.isModerator;
+
+			// Build server URL - use https:// (not wss://) to allow Socket.io to handle upgrade
+			// This ensures cookies are sent during the HTTP handshake for authentication
+			const serverUrl = `https://${server.url}:${server.socketPort}`;
+
+			this.logger.info('Connecting to video server:', serverUrl);
+
+			// Initialize managers if not already done
+			if (!this.connection) {
+				this._initializeManagers(serverUrl);
+			}
+
+			// Connect with authorization (matches old videoCreateSocket.js format)
+			// NOTE: Using cookie-based auth, so only send namespace, roomId, participantId
+			// The HTTP cookie set by api.video.joinRoom() handles authentication
+			this._setState('connecting');
+
+			const authData = {
+				namespace: authorization.namespace,
+				roomId: videoRoom.id,
+				participantId: participant.id
+			};
+
+			this.logger.info('Connecting with auth (cookie-based):', authData);
+			await this.connection.connect(authData);
+
+			this._setState('connected');
+
+			// Setup remote media listeners and room event listeners
+			this.logger.info('Setting up event listeners');
+			this.remoteMedia._setupServerListeners();
+			this._setupRoomEventListeners();
+
+			// ALWAYS emit room.waitingRoom first to initialize room on video server
+			// The server requires this event to set up the room before any joins
+			this.logger.info('Emitting room.waitingRoom to initialize room on server');
+			this.connection.emit('room.waitingRoom', {});
+
+			// Enter waiting-room state for everyone (hosts and guests)
+			// This allows users to set up their devices while room initializes
+			this.inWaitingRoom = true;
+			this._setState('waiting-room');
+
+			this.logger.info('Entering waiting room - waiting for room to be ready');
+
+			this.emit('waitingRoom:entered', {
+				roomId: videoRoom.id,
+				participant,
+				isHost: participant.isHost,
+				canJoinImmediately: !this.isGuest // Hosts can join once ready, guests need admission
+			});
+
+			// Listen for media.routerCapabilities to know when room is ready
+			this.connection.onServerEvent('media.routerCapabilities', (data) => {
+				this.logger.info('Room is ready - received media.routerCapabilities');
+				this.emit('waitingRoom:ready', {
+					roomId: videoRoom.id,
+					participant
+				});
+			});
+
+			// Return - user must explicitly call joinMeeting() when ready
+			// For hosts: after they click "Join Meeting" button (once room is ready)
+			// For guests: after host admits them (room.waitingRoom.admit event)
+			return {
+				...this.joinData,
+				inWaitingRoom: true
+			};
+
+		} catch (error) {
+			this.logger.error('Failed to join from API response:', error);
+			this._setState('disconnected');
+			throw new RoomError(`Failed to join meeting: ${error.message}`);
+		}
+	}
+
+	/**
+	 * Public method to join meeting from waiting room
+	 * Call this after user clicks "Join Meeting" button
+	 */
+	async joinMeeting() {
+		if (this.state !== 'waiting-room') {
+			throw new StateError('Must be in waiting room to join meeting');
+		}
+
+		await this._joinMeeting();
+	}
+
+	/**
+	 * Internal method to join meeting (after connection established)
+	 * @private
+	 */
+	async _joinMeeting() {
+		this.logger.info('Joining meeting:', this.joinData.videoRoom.friendlyName);
+		this._setState('joining');
+
+		// Setup transport listener BEFORE emitting room.join (but handler will wait for device)
+		this._setupMediaEventListeners();
+
+		// Send room.join event to video server (emit, not request - no callback)
+		this.logger.info('Emitting room.join event');
+		this.connection.emit('room.join', {});
+
+		// Load mediasoup device (will wait for media.routerCapabilities event)
+		this.logger.info('Waiting for media.routerCapabilities...');
+		await this.mediasoup.loadDevice();
+		this.logger.info('Device loaded successfully');
+
+		// Wait for media.transports event (listener will create transports now that device is loaded)
+		this.logger.info('Waiting for media.transports...');
+		await this._waitForTransports();
+
+		// Process any producers that arrived before transports were ready
+		this.logger.info('Processing pending producers...');
+		await this.remoteMedia.processPendingProducers();
+
+		this.currentRoomId = this.joinData.videoRoom.id;
+		this._setState('in-meeting');
+
+		this.logger.info('Successfully joined meeting');
+		this.emit('meeting:joined', {
+			roomId: this.joinData.videoRoom.id,
+			joinData: this.joinData
+		});
+	}
+
+	/**
+	 * Join a meeting room (legacy method - requires manual connect first)
+	 * @param {string} roomId - Room ID to join
+	 * @param {Object} options - Join options
+	 * @returns {Promise<Object>} Room data
+	 */
+	async joinRoom(roomId, options = {}) {
+		if (this.state !== 'connected') {
+			throw new StateError(
+				'Cannot join room: not connected to server',
+				this.state,
+				'connected'
+			);
+		}
+
+		this.logger.info('Joining room:', roomId);
+		this._setState('joining');
+
+		try {
+			// Send join request to server
+			const response = await this.connection.request('room.join', {
+				roomId,
+				...options,
+			});
+
+			this.currentRoomId = roomId;
+			this._setState('in-room');
+
+			this.logger.info('Joined room successfully');
+			this.emit('room:joined', { roomId, data: response });
+
+			return response;
+
+		} catch (error) {
+			this.logger.error('Failed to join room:', error);
+			this._setState('connected');
+			throw new RoomError(`Failed to join room: ${error.message}`, roomId);
+		}
+	}
+
+	/**
+	 * Leave the current room
+	 * @returns {Promise<void>}
+	 */
+	async leaveRoom() {
+		if (this.state !== 'in-room') {
+			throw new StateError(
+				'Cannot leave room: not in a room',
+				this.state,
+				'in-room'
+			);
+		}
+
+		this.logger.info('Leaving room:', this.currentRoomId);
+
+		try {
+			// Stop all local media
+			await this.localMedia.cleanup();
+
+			// Notify server
+			await this.connection.request('room.leave', {
+				roomId: this.currentRoomId,
+			});
+
+			// Clean up remote media
+			await this.remoteMedia.cleanup();
+
+			const roomId = this.currentRoomId;
+			this.currentRoomId = null;
+			this._setState('connected');
+
+			this.logger.info('Left room successfully');
+			this.emit('room:left', { roomId });
+
+		} catch (error) {
+			this.logger.error('Failed to leave room:', error);
+			throw error;
+		}
+	}
+
+	// ========== Local Media Methods ==========
+
+	/**
+	 * Publish camera stream
+	 * @param {Object} options - Camera options
+	 * @param {string} options.deviceId - Camera device ID
+	 * @param {string} options.resolution - Resolution (480p, 720p, 1080p)
+	 * @param {number} options.frameRate - Frame rate
+	 * @returns {Promise<MediaStream>}
+	 */
+	async publishCamera(options = {}) {
+		this._ensureInRoom();
+		return await this.localMedia.publishCamera(options);
+	}
+
+	/**
+	 * Publish microphone stream
+	 * @param {Object} options - Microphone options
+	 * @param {string} options.deviceId - Microphone device ID
+	 * @returns {Promise<MediaStream>}
+	 */
+	async publishMicrophone(options = {}) {
+		this._ensureInRoom();
+		return await this.localMedia.publishMicrophone(options);
+	}
+
+	/**
+	 * Publish screen share
+	 * @param {Object} options - Screen share options
+	 * @param {boolean} options.audio - Include system audio
+	 * @returns {Promise<MediaStream>}
+	 */
+	async publishScreenShare(options = {}) {
+		this._ensureInRoom();
+		return await this.localMedia.publishScreenShare(options);
+	}
+
+	/**
+	 * Stop camera
+	 * @returns {Promise<void>}
+	 */
+	async stopCamera() {
+		return await this.localMedia.stopCamera();
+	}
+
+	/**
+	 * Stop microphone
+	 * @returns {Promise<void>}
+	 */
+	async stopMicrophone() {
+		return await this.localMedia.stopMicrophone();
+	}
+
+	/**
+	 * Stop screen share
+	 * @returns {Promise<void>}
+	 */
+	async stopScreenShare() {
+		return await this.localMedia.stopScreenShare();
+	}
+
+	/**
+	 * Enable screenshare audio (add audio to existing screenshare)
+	 * @returns {Promise<void>}
+	 */
+	async enableScreenShareAudio() {
+		return await this.localMedia.enableScreenShareAudio();
+	}
+
+	/**
+	 * Disable screenshare audio (remove audio from existing screenshare)
+	 * @returns {Promise<void>}
+	 */
+	async disableScreenShareAudio() {
+		return await this.localMedia.disableScreenShareAudio();
+	}
+
+	/**
+	 * Mute screenshare audio
+	 * @returns {Promise<void>}
+	 */
+	async muteScreenShareAudio() {
+		return await this.localMedia.muteScreenShareAudio();
+	}
+
+	/**
+	 * Unmute screenshare audio
+	 * @returns {Promise<void>}
+	 */
+	async unmuteScreenShareAudio() {
+		return await this.localMedia.unmuteScreenShareAudio();
+	}
+
+	/**
+	 * Toggle screenshare audio mute state
+	 * @returns {Promise<boolean>} New mute state
+	 */
+	async toggleScreenShareAudioMute() {
+		return await this.localMedia.toggleScreenShareAudioMute();
+	}
+
+	/**
+	 * Change camera device
+	 * @param {string} deviceId - New camera device ID
+	 * @returns {Promise<MediaStream>}
+	 */
+	async changeCamera(deviceId) {
+		return await this.localMedia.changeCamera(deviceId);
+	}
+
+	/**
+	 * Change microphone device
+	 * @param {string} deviceId - New microphone device ID
+	 * @returns {Promise<MediaStream>}
+	 */
+	async changeMicrophone(deviceId) {
+		return await this.localMedia.changeMicrophone(deviceId);
+	}
+
+	/**
+	 * Update camera background effect
+	 * @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 (for type: 'image')
+	 * @returns {Promise<MediaStream>}
+	 *
+	 * @example
+	 * // Apply blur
+	 * await client.updateCameraBackground({ type: 'blur', blurLevel: 8 });
+	 *
+	 * // Apply virtual background
+	 * await client.updateCameraBackground({
+	 *   type: 'image',
+	 *   imageUrl: '/images/backgrounds/office.jpg'
+	 * });
+	 *
+	 * // Remove background effect
+	 * await client.updateCameraBackground({ type: 'none' });
+	 */
+	async updateCameraBackground(options) {
+		this._ensureInRoom();
+		return await this.localMedia.updateCameraBackground(options);
+	}
+
+	/**
+	 * Mute camera
+	 * @returns {Promise<void>}
+	 */
+	async muteCamera() {
+		return await this.localMedia.muteCamera();
+	}
+
+	/**
+	 * Unmute camera
+	 * @returns {Promise<void>}
+	 */
+	async unmuteCamera() {
+		return await this.localMedia.unmuteCamera();
+	}
+
+	/**
+	 * Mute microphone
+	 * @returns {Promise<void>}
+	 */
+	async muteMicrophone() {
+		return await this.localMedia.muteMicrophone();
+	}
+
+	/**
+	 * Unmute microphone
+	 * @returns {Promise<void>}
+	 */
+	async unmuteMicrophone() {
+		return await this.localMedia.unmuteMicrophone();
+	}
+
+	// ========== Device Management ==========
+
+	/**
+	 * Get available media devices
+	 * @returns {Promise<Object>} Object with cameras, microphones, speakers
+	 */
+	async getDevices() {
+		return await this.localMedia.getDevices();
+	}
+
+	/**
+	 * Get local stream
+	 * @param {string} type - Stream type (camera, microphone, screenShare)
+	 * @returns {MediaStream|null}
+	 */
+	getLocalStream(type) {
+		return this.localMedia.getStream(type);
+	}
+
+	/**
+	 * Track a video element for automatic quality adjustment based on size
+	 * @param {string} participantId - Participant ID
+	 * @param {HTMLVideoElement} videoElement - Video element to track
+	 */
+	trackVideoElement(participantId, videoElement) {
+		if (!this.remoteMedia) {
+			this.logger.warn('RemoteMedia not initialized');
+			return;
+		}
+		this.remoteMedia.trackVideoElement(participantId, videoElement);
+	}
+
+	/**
+	 * Stop tracking a video element
+	 * @param {string} participantId - Participant ID
+	 */
+	untrackVideoElement(participantId) {
+		if (!this.remoteMedia) {
+			return;
+		}
+		this.remoteMedia.untrackVideoElement(participantId);
+	}
+
+	/**
+	 * Locally mute a remote participant's stream (only for local user, doesn't affect others)
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (audio, screenShareAudio)
+	 * @returns {boolean} Success
+	 */
+	localMuteRemoteStream(participantId, type = 'audio') {
+		if (!this.remoteMedia) {
+			this.logger.warn('RemoteMedia not initialized');
+			return false;
+		}
+		return this.remoteMedia.localMuteRemoteStream(participantId, type);
+	}
+
+	/**
+	 * Locally unmute a remote participant's stream
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (audio, screenShareAudio)
+	 * @returns {boolean} Success
+	 */
+	localUnmuteRemoteStream(participantId, type = 'audio') {
+		if (!this.remoteMedia) {
+			this.logger.warn('RemoteMedia not initialized');
+			return false;
+		}
+		return this.remoteMedia.localUnmuteRemoteStream(participantId, type);
+	}
+
+	/**
+	 * Toggle local mute state for a remote participant's stream
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (audio, screenShareAudio)
+	 * @returns {boolean} New mute state
+	 */
+	toggleLocalMuteRemoteStream(participantId, type = 'audio') {
+		if (!this.remoteMedia) {
+			this.logger.warn('RemoteMedia not initialized');
+			return false;
+		}
+		return this.remoteMedia.toggleLocalMuteRemoteStream(participantId, type);
+	}
+
+	/**
+	 * Check if a remote stream is locally muted
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (audio, screenShareAudio)
+	 * @returns {boolean} Mute state
+	 */
+	isRemoteStreamLocallyMuted(participantId, type = 'audio') {
+		if (!this.remoteMedia) {
+			return false;
+		}
+		return this.remoteMedia.isLocallyMuted(participantId, type);
+	}
+
+	/**
+	 * Set callback for stats updates (for local UI display)
+	 * @param {Function} callback - Callback function that receives stats data
+	 */
+	setStatsCallback(callback) {
+		if (this.mediasoup && this.mediasoup.statsCollector) {
+			this.mediasoup.statsCollector.setStatsCallback(callback);
+		}
+	}
+
+	// ========== Remote Participant Methods ==========
+
+	/**
+	 * Get participant by ID
+	 * @param {string} participantId - Participant ID
+	 * @returns {Object|null}
+	 */
+	getParticipant(participantId) {
+		return this.remoteMedia.getParticipant(participantId);
+	}
+
+	/**
+	 * Get all participants
+	 * @returns {Array<Object>}
+	 */
+	getAllParticipants() {
+		return this.remoteMedia.getAllParticipants();
+	}
+
+	/**
+	 * Get remote stream
+	 * @param {string} participantId - Participant ID
+	 * @param {string} type - Stream type (video, audio, screenShare)
+	 * @returns {MediaStream|null}
+	 */
+	getRemoteStream(participantId, type) {
+		return this.remoteMedia.getStream(participantId, type);
+	}
+
+	/**
+	 * Get all streams for a participant
+	 * @param {string} participantId - Participant ID
+	 * @returns {Object|null}
+	 */
+	getRemoteStreams(participantId) {
+		return this.remoteMedia.getStreams(participantId);
+	}
+
+	// ========== Logging Control ==========
+
+	/**
+	 * Set verbose logging for specific categories
+	 * @param {string} category - Category name (stats, keepalive, performance) or 'all'
+	 * @param {boolean} enabled - Enable or disable this category
+	 */
+	setVerboseLogging(category, enabled) {
+		if (category === 'all') {
+			Logger.setVerbose(enabled);
+		} else {
+			Logger.setFilter(category, enabled);
+		}
+	}
+
+	// ========== State Getters ==========
+
+	/**
+	 * Get current state
+	 * @returns {string}
+	 */
+	getState() {
+		return this.state;
+	}
+
+	/**
+	 * Check if connected to server
+	 * @returns {boolean}
+	 */
+	isConnected() {
+		return this.state !== 'disconnected' && this.connection.connected;
+	}
+
+	/**
+	 * Check if in a room
+	 * @returns {boolean}
+	 */
+	isInRoom() {
+		return this.state === 'in-room';
+	}
+
+	/**
+	 * Get current room ID
+	 * @returns {string|null}
+	 */
+	getRoomId() {
+		return this.currentRoomId;
+	}
+
+	/**
+	 * Check if camera is active
+	 * @returns {boolean}
+	 */
+	isCameraActive() {
+		return this.localMedia.isCameraActive;
+	}
+
+	/**
+	 * Check if microphone is active
+	 * @returns {boolean}
+	 */
+	isMicrophoneActive() {
+		return this.localMedia.isMicrophoneActive;
+	}
+
+	/**
+	 * Check if screen share is active
+	 * @returns {boolean}
+	 */
+	isScreenShareActive() {
+		return this.localMedia.isScreenShareActive;
+	}
+
+	/**
+	 * Check if camera is muted
+	 * @returns {boolean}
+	 */
+	isCameraMuted() {
+		return this.localMedia.isCameraMuted;
+	}
+
+	/**
+	 * Check if microphone is muted
+	 * @returns {boolean}
+	 */
+	isMicrophoneMuted() {
+		return this.localMedia.isMicrophoneMuted;
+	}
+
+	/**
+	 * Get participant count
+	 * @returns {number}
+	 */
+	getParticipantCount() {
+		return this.remoteMedia.participantCount;
+	}
+
+	/**
+	 * Get video room info from join data
+	 * @returns {Object|null}
+	 */
+	getVideoRoom() {
+		return this.joinData?.videoRoom || null;
+	}
+
+	/**
+	 * Get current participant info from join data
+	 * @returns {Object|null}
+	 */
+	getCurrentParticipant() {
+		return this.joinData?.participant || null;
+	}
+
+	/**
+	 * Get server info from join data
+	 * @returns {Object|null}
+	 */
+	getServerInfo() {
+		return this.joinData?.server || null;
+	}
+
+	/**
+	 * Get full join data (videoRoom, participant, server, authorization)
+	 * @returns {Object|null}
+	 */
+	getJoinData() {
+		return this.joinData;
+	}
+
+	// ========== Private Helpers ==========
+
+	/**
+	 * Set SDK state and emit event
+	 * @private
+	 */
+	_setState(newState) {
+		const oldState = this.state;
+		this.state = newState;
+		this.logger.info(`State changed: ${oldState} -> ${newState}`);
+		this.emit('state:changed', { from: oldState, to: newState });
+	}
+
+	/**
+	 * Ensure we're in a room, throw if not
+	 * @private
+	 */
+	_ensureInRoom() {
+		if (this.state !== 'in-room' && this.state !== 'in-meeting') {
+			throw new StateError(
+				'Not in a room. Call joinRoom() first.',
+				this.state,
+				'in-room or in-meeting'
+			);
+		}
+	}
+
+	/**
+	 * Setup listeners for media events from server
+	 * @private
+	 */
+	_setupMediaEventListeners() {
+		this.logger.info('Setting up media event listeners');
+
+		// Listen for media.transports event
+		this._transportsPromise = new Promise((resolve) => {
+			this._transportsResolve = resolve;
+		});
+
+		this.connection.onServerEvent('media.transports', async (data) => {
+			this.logger.info('Received media.transports', {
+				hasSend: !!data?.sendTransportOptions,
+				hasRecv: !!data?.recvTransportOptions
+			});
+
+			const { sendTransportOptions, recvTransportOptions } = data;
+
+			// Store transport data for later if device not loaded yet
+			this._pendingTransportData = data;
+
+			// Wait for device to be loaded before creating transports
+			if (!this.mediasoup.device.loaded) {
+				this.logger.warn('Device not loaded yet, storing transport data and waiting...');
+
+				// Poll for device to be loaded (with timeout)
+				let attempts = 0;
+				while (!this.mediasoup.device.loaded && attempts < 50) {
+					await new Promise(resolve => setTimeout(resolve, 100));
+					attempts++;
+				}
+
+				if (!this.mediasoup.device.loaded) {
+					this.logger.error('Device still not loaded after 5 seconds');
+					if (this._transportsResolve) {
+						this._transportsResolve();
+					}
+					return;
+				}
+				this.logger.info('Device now loaded, proceeding with transport creation');
+			}
+
+			// Create transports
+			try {
+				if (sendTransportOptions) {
+					this.mediasoup.sendTransport = this.mediasoup.device.createSendTransport(sendTransportOptions);
+					this.mediasoup._setupSendTransportListeners(); // Not async - just sets up event listeners
+					this.logger.info('Send transport created');
+				}
+
+				if (recvTransportOptions) {
+					this.mediasoup.recvTransport = this.mediasoup.device.createRecvTransport(recvTransportOptions);
+					this.mediasoup._setupRecvTransportListeners(); // Not async - just sets up event listeners
+					this.logger.info('Receive transport created');
+				}
+
+				// Resolve the promise
+				if (this._transportsResolve) {
+					this._transportsResolve();
+				}
+			} catch (error) {
+				this.logger.error('Failed to create transports:', error);
+				if (this._transportsResolve) {
+					this._transportsResolve();
+				}
+			}
+		});
+	}
+
+	/**
+	 * Wait for media.transports event from server
+	 * @private
+	 */
+	async _waitForTransports() {
+		const timeout = setTimeout(() => {
+			throw new Error('Timeout waiting for media.transports');
+		}, 10000);
+
+		await this._transportsPromise;
+		clearTimeout(timeout);
+		this.logger.info('Transports ready');
+	}
+
+	/**
+	 * Handle server request to close and reconnect producer
+	 * This happens during quality adaptation
+	 * @private
+	 */
+	async _handleProducerCloseRequest(data) {
+		const { producer } = data;
+		const { type, reconnect } = producer;
+
+		this.logger.info('Handling producer close request:', { type, reconnect });
+
+		if (!type) {
+			this.logger.error('Producer close request missing type');
+			return;
+		}
+
+		// Get the current stream for this producer before closing
+		const currentStream = this.localMedia.streams[type === 'video' ? 'camera' : type];
+		const currentProducer = this.localMedia.producers[type];
+
+		if (!currentProducer) {
+			this.logger.warn('No producer found to close:', type);
+			return;
+		}
+
+		// Close the producer on mediasoup
+		await this.mediasoup.closeProducer(type);
+
+		// If reconnect flag is true, republish with the same stream
+		if (reconnect && currentStream) {
+			this.logger.info('Reconnecting producer:', type);
+
+			try {
+				// Clone the stream to avoid issues with the old one
+				const clonedStream = currentStream.clone();
+
+				// Republish based on type
+				if (type === 'video') {
+					// Stop the old stream tracks
+					currentStream.getTracks().forEach(track => track.stop());
+
+					// Start camera with the cloned stream
+					await this.localMedia.startCamera({
+						existingStream: clonedStream,
+						// Preserve current background if any
+						background: this.localMedia.currentBackgroundOptions
+					});
+				} else if (type === 'audio') {
+					// Stop the old stream tracks
+					currentStream.getTracks().forEach(track => track.stop());
+
+					// Start microphone with the cloned stream
+					await this.localMedia.startMicrophone({
+						existingStream: clonedStream
+					});
+				}
+
+				this.logger.info('Producer reconnected successfully:', type);
+			} catch (error) {
+				this.logger.error('Failed to reconnect producer:', type, error);
+				// Emit error event so UI can handle it
+				this.emit('producer:reconnect:failed', { type, error });
+			}
+		}
+	}
+
+	/**
+	 * Set volume for a specific participant (0.0 to 1.0)
+	 * Works seamlessly with both audio elements (< 30 participants) and audio mixer (30+ participants)
+	 * @param {string} participantId - Participant ID
+	 * @param {number} volume - Volume level (0.0 to 1.0)
+	 * @returns {boolean} Success status
+	 */
+	setParticipantVolume(participantId, volume) {
+		return this.remoteMedia.setParticipantVolume(participantId, volume);
+	}
+
+	/**
+	 * Get volume for a specific participant
+	 * @param {string} participantId - Participant ID
+	 * @returns {number} Volume level (0.0 to 1.0)
+	 */
+	getParticipantVolume(participantId) {
+		return this.remoteMedia.getParticipantVolume(participantId);
+	}
+
+	/**
+	 * Check if audio mixer is currently enabled
+	 * Audio mixer is automatically enabled when participant count >= 30
+	 * @returns {boolean}
+	 */
+	isAudioMixerEnabled() {
+		return this.remoteMedia.isAudioMixerEnabled();
+	}
+
+	/**
+	 * Retry consuming a failed producer stream
+	 * Use this when a stream:consume-failed event is received
+	 * @param {string} producerId - Producer ID to retry
+	 * @param {string} participantId - Participant ID
+	 * @returns {Promise<boolean>} Success status
+	 *
+	 * @example
+	 * client.on('stream:consume-failed', async ({ producerId, participantId }) => {
+	 *   console.warn('Stream failed to load, retrying...');
+	 *   await client.retryConsumeStream(producerId, participantId);
+	 * });
+	 */
+	async retryConsumeStream(producerId, participantId) {
+		if (!this.remoteMedia) {
+			this.logger.warn('RemoteMedia not initialized');
+			return false;
+		}
+		return await this.remoteMedia.retryConsumeProducer(producerId, participantId);
+	}
+}