@unboundcx/video-sdk-client 1.1.0

package/AudioMixer.js

@@ -0,0 +1,235 @@
+/**
+ * AudioMixer - Web Audio API based mixer for scalable audio handling
+ * Handles multiple audio streams efficiently by mixing them in a single audio context
+ * Used automatically for meetings with 30+ participants
+ */
+
+export class AudioMixer {
+	constructor() {
+		this.audioContext = null;
+		this.masterGain = null;
+		this.participants = new Map(); // Map<participantId, { source, gainNode, stream }>
+		this.isInitialized = false;
+	}
+
+	/**
+	 * Initialize the audio context and master gain
+	 */
+	async initialize() {
+		if (this.isInitialized) {
+			console.log('SDK :: AudioMixer :: Already initialized');
+			return;
+		}
+
+		try {
+			// Create audio context
+			this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
+
+			// Create master gain node (output)
+			this.masterGain = this.audioContext.createGain();
+			this.masterGain.gain.value = 1.0;
+			this.masterGain.connect(this.audioContext.destination);
+
+			this.isInitialized = true;
+			console.log('SDK :: AudioMixer :: Initialized successfully', {
+				sampleRate: this.audioContext.sampleRate,
+				state: this.audioContext.state,
+			});
+
+			// Handle audio context state changes
+			this.audioContext.addEventListener('statechange', () => {
+				console.log('SDK :: AudioMixer :: State changed:', this.audioContext.state);
+			});
+		} catch (err) {
+			console.error('SDK :: AudioMixer :: Failed to initialize:', err);
+			throw err;
+		}
+	}
+
+	/**
+	 * Resume audio context (needed for user interaction requirement)
+	 */
+	async resume() {
+		if (this.audioContext && this.audioContext.state === 'suspended') {
+			await this.audioContext.resume();
+			console.log('SDK :: AudioMixer :: Context resumed');
+		}
+	}
+
+	/**
+	 * Add a participant's audio stream to the mixer
+	 */
+	addParticipant(participantId, stream, volume = 1.0) {
+		if (!this.isInitialized) {
+			console.error('SDK :: AudioMixer :: Not initialized');
+			return false;
+		}
+
+		// Remove existing participant if already added
+		if (this.participants.has(participantId)) {
+			this.removeParticipant(participantId);
+		}
+
+		try {
+			// Create media stream source
+			const source = this.audioContext.createMediaStreamSource(stream);
+
+			// Create gain node for this participant (for individual volume control)
+			const gainNode = this.audioContext.createGain();
+			gainNode.gain.value = volume;
+
+			// Connect: source -> gainNode -> masterGain -> destination
+			source.connect(gainNode);
+			gainNode.connect(this.masterGain);
+
+			// Store participant info
+			this.participants.set(participantId, {
+				source,
+				gainNode,
+				stream,
+			});
+
+			console.log('SDK :: AudioMixer :: Added participant:', participantId, {
+				volume,
+				participantCount: this.participants.size,
+			});
+
+			return true;
+		} catch (err) {
+			console.error('SDK :: AudioMixer :: Failed to add participant:', participantId, err);
+			return false;
+		}
+	}
+
+	/**
+	 * Remove a participant's audio stream from the mixer
+	 */
+	removeParticipant(participantId) {
+		const participant = this.participants.get(participantId);
+		if (!participant) {
+			return false;
+		}
+
+		try {
+			// Disconnect nodes
+			participant.source.disconnect();
+			participant.gainNode.disconnect();
+
+			// Remove from map
+			this.participants.delete(participantId);
+
+			console.log('SDK :: AudioMixer :: Removed participant:', participantId, {
+				participantCount: this.participants.size,
+			});
+
+			return true;
+		} catch (err) {
+			console.error('SDK :: AudioMixer :: Failed to remove participant:', participantId, err);
+			return false;
+		}
+	}
+
+	/**
+	 * Set volume for a specific participant (0.0 to 1.0)
+	 */
+	setParticipantVolume(participantId, volume) {
+		const participant = this.participants.get(participantId);
+		if (!participant) {
+			console.warn('SDK :: AudioMixer :: Participant not found:', participantId);
+			return false;
+		}
+
+		try {
+			// Clamp volume between 0 and 1
+			const clampedVolume = Math.max(0, Math.min(1, volume));
+			participant.gainNode.gain.value = clampedVolume;
+
+			console.log('SDK :: AudioMixer :: Set volume:', participantId, clampedVolume);
+			return true;
+		} catch (err) {
+			console.error('SDK :: AudioMixer :: Failed to set volume:', participantId, err);
+			return false;
+		}
+	}
+
+	/**
+	 * Get current volume for a participant
+	 */
+	getParticipantVolume(participantId) {
+		const participant = this.participants.get(participantId);
+		return participant ? participant.gainNode.gain.value : null;
+	}
+
+	/**
+	 * Set master volume (affects all participants)
+	 */
+	setMasterVolume(volume) {
+		if (!this.masterGain) {
+			return false;
+		}
+
+		const clampedVolume = Math.max(0, Math.min(1, volume));
+		this.masterGain.gain.value = clampedVolume;
+		console.log('SDK :: AudioMixer :: Set master volume:', clampedVolume);
+		return true;
+	}
+
+	/**
+	 * Get master volume
+	 */
+	getMasterVolume() {
+		return this.masterGain ? this.masterGain.gain.value : null;
+	}
+
+	/**
+	 * Check if a participant is in the mixer
+	 */
+	hasParticipant(participantId) {
+		return this.participants.has(participantId);
+	}
+
+	/**
+	 * Get number of participants in mixer
+	 */
+	getParticipantCount() {
+		return this.participants.size;
+	}
+
+	/**
+	 * Clear all participants and reset
+	 */
+	clear() {
+		console.log('SDK :: AudioMixer :: Clearing all participants');
+
+		// Remove all participants
+		for (const participantId of this.participants.keys()) {
+			this.removeParticipant(participantId);
+		}
+
+		this.participants.clear();
+	}
+
+	/**
+	 * Cleanup and close the audio context
+	 */
+	async destroy() {
+		console.log('SDK :: AudioMixer :: Destroying');
+
+		// Clear all participants
+		this.clear();
+
+		// Close audio context
+		if (this.audioContext) {
+			try {
+				await this.audioContext.close();
+				console.log('SDK :: AudioMixer :: Audio context closed');
+			} catch (err) {
+				console.error('SDK :: AudioMixer :: Failed to close audio context:', err);
+			}
+		}
+
+		this.audioContext = null;
+		this.masterGain = null;
+		this.isInitialized = false;
+	}
+}

package/README.md

@@ -0,0 +1,400 @@
+# Video Meeting SDK
+
+A standalone, framework-agnostic SDK for building video conferencing applications with mediasoup.
+
+## Features
+
+- 🎥 Camera, microphone, and screen sharing
+- 👥 Multi-party video conferencing
+- 🔄 Real-time media stream management
+- 🎨 Virtual backgrounds with blur and custom images (MediaPipe)
+- 📡 Simulcast for adaptive bitrate (3 quality layers)
+- 🎯 Simple, promise-based API
+- 📦 Framework agnostic (works with React, Vue, Svelte, vanilla JS)
+- 🔌 Socket.io + mediasoup integration
+- 🖼️ No UI dependencies - bring your own interface
+- ✅ Mac, Windows, Linux support (latest mediasoup v3.16+)
+
+## Installation
+
+```bash
+npm install @unboundcx/video-sdk
+```
+
+**Note:** This SDK connects to Unbound's managed video server infrastructure. You don't need to set up your own media servers.
+
+## Quick Start
+
+### Option 1: Using with Unbound SDK (Recommended)
+
+```javascript
+import { VideoMeetingClient } from '@unboundcx/video-sdk';
+import { UnboundSDK } from '@unboundcx/sdk';
+
+// Initialize SDK
+const sdk = new UnboundSDK('your-namespace', 'api.yourdomain.com');
+
+// Initialize Video Client
+const client = new VideoMeetingClient({ debug: true });
+
+// Join using Unbound SDK API response
+const joinResponse = await sdk.video.joinRoom('room-123', 'password', 'user@example.com');
+await client.joinFromApiResponse(joinResponse);
+
+// Publish local media
+const videoStream = await client.publishCamera({ resolution: '720p' });
+await client.publishMicrophone();
+
+// Listen for remote participants
+client.on('stream:added', ({ participantId, stream, type }) => {
+    const videoElement = document.getElementById(`video-${participantId}`);
+    videoElement.srcObject = stream;
+});
+
+// Leave meeting
+await client.leaveRoom();
+await client.disconnect();
+```
+
+### Option 2: Direct Integration (Custom Backend)
+
+If you're building your own backend (not using Unbound's video server):
+
+```javascript
+import { VideoMeetingClient } from '@unboundcx/video-sdk';
+
+// Initialize - no serverUrl needed, will be provided by your join API
+const client = new VideoMeetingClient({ debug: true });
+
+// Your custom API should return the same format as Unbound SDK
+const joinResponse = await yourApi.joinVideoRoom('room-123');
+// joinResponse should include: { videoRoom, server, participant, authorization }
+
+await client.joinFromApiResponse(joinResponse);
+
+// Publish local camera
+const videoStream = await client.publishCamera();
+
+// Listen for remote participants
+client.on('participant:joined', (participant) => {
+    console.log('Participant joined:', participant.id);
+});
+
+client.on('stream:added', ({ participantId, stream, type }) => {
+    const videoElement = document.getElementById(`video-${participantId}`);
+    videoElement.srcObject = stream;
+});
+
+// Leave meeting
+await client.leaveRoom();
+await client.disconnect();
+```
+
+**Note:** This SDK is designed to work with Unbound's video server infrastructure. For custom backends, you'll need to implement compatible server-side APIs.
+
+## API Documentation
+
+### Constructor
+
+```javascript
+new VideoMeetingClient(options)
+```
+
+**Options:**
+- `serverUrl` (string, optional) - WebSocket server URL (not required if using `joinFromApiResponse`)
+- `debug` (boolean, optional) - Enable debug logging
+
+### Methods
+
+#### Connection
+
+**`joinFromApiResponse(joinResponse)`** ⭐ Recommended
+- Joins a meeting using the response from `api.video.joinRoom()`
+- Automatically extracts server URL, auth token, and room info
+- Connects to video server and joins room in one call
+- Returns: `Promise<Object>` - Full join data including videoRoom, participant, server info
+
+**Example:**
+```javascript
+const joinResponse = await api.video.joinRoom('room-123', 'password', 'user@example.com');
+await client.joinFromApiResponse(joinResponse);
+
+// Access join data
+const videoRoom = client.getVideoRoom();
+const participant = client.getCurrentParticipant();
+```
+
+**`connect(authToken)`**
+- Connect to server (manual method)
+- Returns: `Promise<void>`
+
+**`disconnect()`**
+- Disconnect from server
+- Returns: `Promise<void>`
+
+**`joinRoom(roomId, options?)`**
+- Join a meeting room (manual method, requires `connect()` first)
+- Returns: `Promise<Object>` - Room data
+
+**`leaveRoom()`**
+- Leave current room
+- Returns: `Promise<void>`
+
+#### Local Media
+
+**`publishCamera(options?)`** - Start publishing camera
+- `options.resolution` - '480p', '720p', '1080p' (default: '720p')
+- `options.frameRate` - Frame rate (default: 24)
+- `options.deviceId` - Specific camera device ID
+- `options.background` - Virtual background options:
+  - `{ type: 'blur', blurLevel: 8 }` - Blur background
+  - `{ type: 'image', imageUrl: '/path/to/image.jpg' }` - Virtual background
+  - `{ type: 'none' }` - No effect (default)
+- `options.simulcast` - Enable simulcast (default: true for video)
+- Returns: `Promise<MediaStream>`
+
+**Example:**
+```javascript
+// Publish with blur background
+await client.publishCamera({
+  resolution: '720p',
+  background: { type: 'blur', blurLevel: 8 }
+});
+
+// Publish with virtual background
+await client.publishCamera({
+  background: {
+    type: 'image',
+    imageUrl: '/images/backgrounds/office.jpg'
+  }
+});
+```
+
+**`updateCameraBackground(options)`** - Change background on active camera
+- `options.type` - 'none', 'blur', or 'image'
+- `options.blurLevel` - Blur amount in pixels (default: 8)
+- `options.imageUrl` - Background image URL
+- Returns: `Promise<MediaStream>`
+
+**Other Methods:**
+- `publishMicrophone(options?)` - Start publishing microphone
+- `publishScreenShare()` - Start screen sharing
+- `stopCamera()` - Stop camera stream
+- `stopMicrophone()` - Stop microphone stream
+- `stopScreenShare()` - Stop screen sharing
+- `changeCamera(deviceId)` - Switch to different camera
+- `changeMicrophone(deviceId)` - Switch to different microphone
+- `muteCamera()` - Mute camera
+- `unmuteCamera()` - Unmute camera
+- `muteMicrophone()` - Mute microphone
+- `unmuteMicrophone()` - Unmute microphone
+
+#### Device Management
+- `getDevices()` - Get available media devices
+- `getLocalStream(type)` - Get local stream by type
+
+#### State and Info
+- `getState()` - Get current SDK state ('disconnected', 'connecting', 'connected', 'joining', 'in-room')
+- `isConnected()` - Check if connected to server
+- `isInRoom()` - Check if currently in a room
+- `isCameraActive()` - Check if camera is active
+- `isMicrophoneActive()` - Check if microphone is active
+- `isCameraMuted()` - Check if camera is muted
+- `isMicrophoneMuted()` - Check if microphone is muted
+- `getParticipantCount()` - Get number of remote participants
+
+#### Join Data Access (when using `joinFromApiResponse`)
+- `getVideoRoom()` - Get video room info (id, name, friendlyName, waitingRoom, etc.)
+- `getCurrentParticipant()` - Get current participant info (id, name, email, isHost, etc.)
+- `getServerInfo()` - Get server info (url, serverId, socketPort)
+- `getJoinData()` - Get full join data (videoRoom, participant, server, authorization)
+
+### Events
+
+```javascript
+client.on('event-name', (data) => {
+    // Handle event
+});
+```
+
+**Connection Events:**
+- `connected` - Connected to server
+- `disconnected` - Disconnected from server
+- `error` - Connection error
+
+**Room Events:**
+- `room:joined` - Successfully joined room
+- `room:left` - Left the room
+- `participant:joined` - New participant joined
+- `participant:left` - Participant left
+- `participant:updated` - Participant state changed
+
+**Media Events:**
+- `stream:added` - New media stream available
+- `stream:removed` - Media stream removed
+- `local-stream:added` - Local stream started
+- `local-stream:removed` - Local stream stopped
+
+**State Events:**
+- `state:changed` - SDK state changed
+
+## Example: Complete Video Call
+
+```javascript
+import { VideoMeetingClient } from '@yourcompany/video-sdk';
+
+class VideoCall {
+    constructor() {
+        this.client = new VideoMeetingClient({
+            serverUrl: 'wss://video.example.com',
+            debug: true
+        });
+
+        this.setupEventListeners();
+    }
+
+    setupEventListeners() {
+        // Handle remote streams
+        this.client.on('stream:added', ({ participantId, stream, type }) => {
+            this.addRemoteStream(participantId, stream, type);
+        });
+
+        this.client.on('stream:removed', ({ participantId, type }) => {
+            this.removeRemoteStream(participantId, type);
+        });
+
+        // Handle participants
+        this.client.on('participant:joined', (participant) => {
+            this.addParticipantUI(participant);
+        });
+
+        this.client.on('participant:left', ({ participantId }) => {
+            this.removeParticipantUI(participantId);
+        });
+
+        // Handle errors
+        this.client.on('error', (error) => {
+            console.error('SDK Error:', error);
+            this.showErrorMessage(error.message);
+        });
+    }
+
+    async start(roomId, authToken) {
+        try {
+            // Connect to server
+            await this.client.connect(authToken);
+
+            // Join room
+            await this.client.joinRoom(roomId);
+
+            // Start local media
+            const videoStream = await this.client.publishCamera({
+                resolution: '720p'
+            });
+            const audioStream = await this.client.publishMicrophone();
+
+            // Display local video
+            this.showLocalVideo(videoStream);
+
+        } catch (error) {
+            console.error('Failed to start call:', error);
+            throw error;
+        }
+    }
+
+    async toggleCamera() {
+        if (this.client.isCameraMuted()) {
+            await this.client.unmuteCamera();
+        } else {
+            await this.client.muteCamera();
+        }
+    }
+
+    async toggleMicrophone() {
+        if (this.client.isMicrophoneMuted()) {
+            await this.client.unmuteMicrophone();
+        } else {
+            await this.client.muteMicrophone();
+        }
+    }
+
+    async startScreenShare() {
+        try {
+            await this.client.publishScreenShare();
+        } catch (error) {
+            if (error.name === 'NotAllowedError') {
+                console.log('Screen share permission denied');
+            }
+        }
+    }
+
+    async end() {
+        await this.client.leaveRoom();
+        await this.client.disconnect();
+    }
+
+    // UI methods (implement based on your framework)
+    addRemoteStream(participantId, stream, type) { }
+    removeRemoteStream(participantId, type) { }
+    addParticipantUI(participant) { }
+    removeParticipantUI(participantId) { }
+    showLocalVideo(stream) { }
+    showErrorMessage(message) { }
+}
+
+// Usage
+const videoCall = new VideoCall();
+await videoCall.start('room-123', 'auth-token-xyz');
+```
+
+## Architecture
+
+The SDK is composed of several managers:
+
+- **MediasoupManager** - Manages mediasoup Device and Transports
+- **LocalMediaManager** - Handles camera, microphone, screen share
+- **RemoteMediaManager** - Manages remote participant streams
+- **ConnectionManager** - Socket.io connection and signaling
+
+## State Machine
+
+```
+disconnected -> connecting -> connected -> joining -> in-room -> leaving -> connected
+                     ↓                          ↓
+                   error                      error
+```
+
+## Error Handling
+
+All errors are wrapped in custom error classes:
+
+```javascript
+try {
+    await client.publishCamera();
+} catch (error) {
+    if (error.name === 'DeviceNotFoundError') {
+        console.log('Camera not found');
+    } else if (error.name === 'PermissionDeniedError') {
+        console.log('Camera permission denied');
+    } else if (error.name === 'ConnectionError') {
+        console.log('Connection failed');
+    }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+## License
+
+MIT