stinky-moq-js 0.1.18 → 0.1.20

package/README.md

@@ -22,84 +22,109 @@ npm install stinky-moq-js
 ## Quick Start
 
 ```typescript
-import { MoQSession, SessionState } from 'stinky-moq-js';
+import { MoqSessionBroadcaster, MoqSessionSubscriber } from 'stinky-moq-js';
 
-// Create a session
-const session = new MoQSession({
-  relayUrl: 'wss://relay.quic.video',
-  namespace: 'my-app',
-  reconnection: {
-    delay: 1000  // Reconnect delay in ms
-  }
+// Create a broadcaster
+const broadcaster = new MoqSessionBroadcaster(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'my-app/user-123'
+  },
+  [
+    { trackName: 'video', priority: 10, type: 'video' },
+    { trackName: 'audio', priority: 5, type: 'audio' }
+  ]
+);
+
+// Create a subscriber
+const subscriber = new MoqSessionSubscriber(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'my-app/user-456'
+  },
+  [
+    { trackName: 'video', priority: 10 },
+    { trackName: 'audio', priority: 5 }
+  ]
+);
+
+// Listen to events
+broadcaster.on('stateChange', (status) => {
+  console.log('Broadcaster state:', status.state);
 });
 
-// Listen to session events
-session.on('stateChange', (status) => {
-  console.log('Session state:', status.state);
+subscriber.on('data', (trackName, data) => {
+  console.log(`Received ${data.length} bytes from ${trackName}`);
 });
 
-session.on('error', (error) => {
-  console.error('Session error:', error);
-});
+// Connect
+await broadcaster.connect();
+await subscriber.connect();
 
-// Listen for broadcast discoveries
-session.on('broadcastAnnounced', (announcement) => {
-  console.log('Found broadcast:', announcement.path);
-});
-
-// Connect to the relay
-await session.connect();
+// Send data
+broadcaster.send('video', videoData, true);
 ```
 
 ## Working with Broadcasts
 
 ```typescript
-// Define what you want to broadcast
-const broadcasts = [
-  { trackName: 'my-video-track', priority: 1 },
-  { trackName: 'my-audio-track', priority: 2 }
-];
-
-// Apply the configuration
-session.updateBroadcasts(broadcasts);
-
-// Listen to broadcast events through the session
-session.on('broadcastStateChange', (trackName, status) => {
+// Create a broadcaster with track configurations
+const broadcaster = new MoqSessionBroadcaster(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'my-app/user-123'
+  },
+  [
+    { trackName: 'video', priority: 10, type: 'video' },
+    { trackName: 'audio', priority: 5, type: 'audio' }
+  ]
+);
+
+// Listen to broadcast events
+broadcaster.on('broadcastStateChange', (trackName, status) => {
   console.log(`Broadcast ${trackName} state:`, status.state);
   console.log('Bytes sent:', status.bytesSent);
 });
 
-session.on('broadcastError', (trackName, error) => {
+broadcaster.on('broadcastError', (trackName, error) => {
   console.error(`Broadcast error on ${trackName}:`, error.message);
 });
 
-// Send binary data through the session
-const data = new Uint8Array([1, 2, 3, 4, 5]);
-await session.send('my-video-track', data);
-```
-
-## Working with Subscriptions
-
-```typescript
-// Define what you want to subscribe to
-const subscriptions = [
-  { trackName: 'remote-video-track', priority: 1 },
-  { trackName: 'remote-audio-track', priority: 2, retry: { delay: 2000 } }
-];
-
-// Apply the configuration  
-session.updateSubscriptions(subscriptions);
+// Connect and send data
+await broadcaster.connect();
 
-// Listen to incoming data through the session
-session.on('data', (trackName, data) => {
+// Send binary data (newGroup: true for keyframes/new groups)
+const videoData = new Uint8Array([1, 2, 3, 4, 5]);
+broCreate a subscriber with track configurations
+const subscriber = new MoqSessionSubscriber(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'my-app/user-456'
+  },
+  [
+    { trackName: 'video', priority: 10 },
+    { trackName: 'audio', priority: 5, retry: { delay: 2000 } }
+  ]
+);
+
+// Listen to incoming data
+subscriber.on('data', (trackName, data) => {
   console.log('Received data from:', trackName);
   console.log('Data length:', data.length);
 });
 
-// Listen to subscription status through the session
-session.on('subscriptionStateChange', (trackName, status) => {
+// Listen to subscription status
+subscriber.on('subscriptionStateChange', (trackName, status) => {
   console.log(`Subscription ${trackName} state:`, status.state);
   console.log('Bytes received:', status.bytesReceived);
+});
+
+subscriber.on('subscriptionError', (trackName, error) => {
+  console.error(`Subscription error on ${trackName}:`, error.message);
+});
+
+// Connect to start receiving data
+await subscriber.connect( console.log('Bytes received:', status.bytesReceived);
   console.log('Retry attempts:', status.retryAttempts);
 });
 
@@ -120,6 +145,8 @@ interface MoQSessionConfig {
     delay?: number;              // Delay between attempts in ms (default: 1000)
   };
   connectionTimeout?: number;    // Connection timeout in ms (default: 10000)
+  discoveryOnly?: boolean;       // (Subscriber only) Only discover broadcasts, 
+                                 // don't auto-subscribe (default: false)
 }
 ```
 
@@ -129,6 +156,7 @@ interface MoQSessionConfig {
 interface BroadcastConfig {
   trackName: string;    // Track name for the broadcast
   priority?: number;    // Priority for the track (default: 0)
+  type: 'video' | 'audio' | 'data';  // Type of track
 }
 ```
 
@@ -149,7 +177,7 @@ interface SubscriptionConfig {
 ### Session Status
 
 ```typescript
-const status = session.status;
+const status = broadcaster.status;  // or subscriber.status
 console.log({
   state: status.state,              // SessionState enum
   reconnectAttempts: status.reconnectAttempts,
@@ -161,30 +189,29 @@ console.log({
 ### Broadcast Status
 
 ```typescript
-const status = session.getBroadcastStatus('my-track');
-if (status) {
+// Broadcasters track individual broadcast status
+broadcaster.on('broadcastStateChange', (trackName, status) => {
   console.log({
     state: status.state,         // BroadcastState enum
     trackName: status.trackName,
     bytesSent: status.bytesSent,
     lastError: status.lastError
   });
-}
+});
 ```
 
 ### Subscription Status
 
 ```typescript
-const status = session.getSubscriptionStatus('remote-track');
-if (status) {
+// Subscribers track individual subscription status
+subscriber.on('subscriptionStateChange', (trackName, status) => {
   console.log({
     state: status.state,              // SubscriptionState enum
     trackName: status.trackName,
     bytesReceived: status.bytesReceived,
-    retryAttempts: status.retryAttempts,
     lastError: status.lastError
   });
-}
+});
 ```
 
 ## States
@@ -203,27 +230,26 @@ if (status) {
 
 ### Subscription States
 - `PENDING`: Waiting to subscribe
-- `SUBSCRIBED`: Successfully subscribed
-- `RETRYING`: Retrying after failure
-- `FAILED`: Subscription failed completely
-
+- `IDLE`: Not subscribed
+- `SUBSCRIBED`: Successfully subscribed and receiving data
+- `FAILED`: Subscription failed
 ## Error Handling
 
 ```typescript
 // Session errors
 session.on('error', (error) => {
   console.error('Session error:', error.message);
+broadcaster.on('error', (error) => {
+  console.error('Session error:', error.message);
 });
 
 // Broadcast errors (per track)
-session.on('broadcastError', (trackName, error) => {
+broadcaster.on('broadcastError', (trackName, error) => {
   console.error(`Broadcast error on ${trackName}:`, error.message);
 });
 
 // Subscription errors (per track)
-session.on('subscriptionError', (trackName, error) => {
-  console.error(`Subscription error on ${trackName}:`, error.message);
-});
+subscriber
 ```
 
 ## Cleanup
@@ -231,145 +257,191 @@ session.on('subscriptionError', (trackName, error) => {
 ```typescript
 // Remove all broadcasts and subscriptions
 session.updateBroadcasts([]);  // Empty array removes all
-session.updateSubscriptions([]);
+sesDisconnect and cleanup
+broadcaster.disconnect();
+subscriber.dispose
+## Broadcast Discovery
 
-// Or disconnect to cleanup everything
-await session.disconnect();
-```
+The library automatically discovers available broadcasts via MoQ announcements. This is essential for building multi-user applications like video chat rooms.
 
-## Broadcast Discovery
+### Discovery-Only Mode (Room-Level Discovery)
 
-The library automatically discovers available broadcasts via MoQ announcements:
+Use `discoveryOnly: true` to discover broadcasts without automatically subscribing. This is perfect for room-level discovery where you want to find all users in a room and then selectively subscribe to them:
 
 ```typescript
-// Listen for broadcast announcements
-session.on('broadcastAnnounced', (announcement) => {
-  console.log('Found broadcast:', announcement.path);
+// Create a discovery subscriber for a room
+const roomDiscovery = new MoqSessionSubscriber(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'lobby',  // Room prefix
+    discoveryOnly: true   // Only discover, don't auto-subscribe
+  },
+  [] // No subscriptions needed for discovery
+);
+
+// Listen for user announcements
+roomDiscovery.on('broadcastAnnounced', (announcement) => {
+  console.log('User broadcast:', announcement.path);  // e.g., "lobby/user/abc123"
   console.log('Is active:', announcement.active);
   
-  // Subscribe to discovered broadcast
   if (announcement.active) {
-    session.updateSubscriptions([
-      { trackName: announcement.path }
-    ]);
+    // Manually create a subscription to this user's tracks
+    const userSubscriber = new MoqSessionSubscriber(
+      {
+        relayUrl: 'https://relay.quic.video',
+        namespace: announcement.path,  // e.g., "lobby/user/abc123"
+        discoveryOnly: false
+      },
+      [
+        { trackName: 'video', priority: 10 },
+        { trackName: 'audio', priority: 5 }
+      ]
+    );
+    
+    await userSubscriber.connect();
+  } else {
+    // User left - clean up their subscription
+    console.log('User left:', announcement.path);
   }
 });
-```
 
-## Dynamic Track Management
+await roomDiscovery.connect();
+```
 
-The library provides a declarative API for managing broadcasts and subscriptions. Simply define the desired state and the library handles all add/remove/update operations automatically:
+### Multi-User Video Chat Room Example
 
-### Managing Broadcasts Dynamically
+Here's a complete example of building a video chat room with discovery:
 
 ```typescript
-// Define the desired state of broadcasts
-const desiredBroadcasts = [
-  { trackName: 'video', priority: 1 },
-  { trackName: 'audio', priority: 2 },
-  { trackName: 'metadata', priority: 0 }
-];
-
-// Apply the desired state - library handles add/remove/update automatically
-session.updateBroadcasts(desiredBroadcasts);
-
-// Later, change the desired state
-const newBroadcasts = [
-  { trackName: 'video', priority: 1 },  // Kept
-  { trackName: 'chat', priority: 0 }    // Audio and metadata removed, chat added
-];
-
-session.updateBroadcasts(newBroadcasts);
-```
+// Namespace structure: {room}/user/{userId}
+const roomName = 'lobby';
+const myUserId = 'user-123';
 
-### Managing Subscriptions Dynamically
+// 1. Create a broadcaster for your own tracks
+const myBroadcaster = new MoqSessionBroadcaster(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: `${roomName}/user/${myUserId}`
+  },
+  [
+    { trackName: 'video', priority: 10, type: 'video' },
+    { trackName: 'audio', priority: 5, type: 'audio' }
+  ]
+);
+
+await myBroadcaster.connect();
+
+// 2. Create a discovery subscriber to find other users
+const roomDiscovery = new MoqSessionSubscriber(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: roomName,
+    discoveryOnly: true
+  },
+  []
+);
+
+// Track active users
+const activeUsers = new Map();
+
+roomDiscovery.on('broadcastAnnounced', async (announcement) => {
+  const userPath = announcement.path;  // e.g., "lobby/user/xyz789"
+  
+  // Skip our own broadcast
+  if (userPath === `${roomName}/user/${myUserId}`) return;
+  
+  if (announcement.active) {
+    // New user joined - subscribe to their tracks
+    const userSubscriber = new MoqSessionSubscriber(
+      {
+        relayUrl: 'https://relay.quic.video',
+        namespace: userPath
+      },
+      [
+        { trackName: 'video', priority: 10 },
+        { trackName: 'audio', priority: 5 }
+      ]
+    );
+    
+    userSubscriber.on('data', (trackName, data) => {
+      console.log(`Received ${trackName} from ${userPath}:`, data.length, 'bytes');
+      // Process video/audio data
+    });
+    
+    await userSubscriber.connect();
+    activeUsers.set(userPath, userSubscriber);
+    
+    console.log(`User joined: ${userPath}`);
+  } else {
+    // User left - clean up
+    const userSubscriber = activeUsers.get(userPath);
+    if (userSubscriber) {
+      userSubscriber.dispose();
+      activeUsers.delete(userPath);
+      console.log(`User left: ${userPath}`);
+    }
+  }
+});
 
-```typescript
-// Define what you want to subscribe to
-const desiredSubscriptions = [
-  { trackName: 'remote-video', priority: 1 },
-  { trackName: 'remote-audio', priority: 2, retry: { delay: 1000 } },
-  { trackName: 'remote-chat', priority: 0 }
-];
-
-// Apply the desired state
-session.updateSubscriptions(desiredSubscriptions);
-
-// Update subscriptions based on user preferences
-const userPreferences = {
-  videoEnabled: true,
-  audioEnabled: false,
-  chatEnabled: true
-};
-
-const activeSubscriptions = [
-  ...(userPreferences.videoEnabled ? [{ trackName: 'remote-video', priority: 1 }] : []),
-  ...(userPreferences.audioEnabled ? [{ trackName: 'remote-audio', priority: 2 }] : []),
-  ...(userPreferences.chatEnabled ? [{ trackName: 'remote-chat', priority: 0 }] : [])
-];
-
-session.updateSubscriptions(activeSubscriptions);
+await roomDiscovery.connect();
+
+// 3. Broadcast your video/audio
+myBroadcaster.send('video', videoData, true);
+myBroadcaster.send('audio', audioData, false);
 ```
 
-### Benefits of Declarative API
+### How Discovery Works
 
-- **Cleaner State Management**: Just declare what you want, not how to get there
-- **Automatic Cleanup**: Tracks not in the desired state are automatically removed
-- **Idempotent**: Calling `updateBroadcasts`/`updateSubscriptions` multiple times with the same config is safe
-- **Less Error-Prone**: No need to manually track what's been added/removed
-- **Reactive Updates**: Easy to update based on user preferences or external state changes
+The discovery mechanism uses the MoQ `announced()` method under the hood:
 
-## Advanced Usage
+- **Discovery uses `announced(prefix)`**: Listens for all broadcasts matching a prefix (e.g., `lobby`)
+- **Subscriptions use `consume(path)`**: Subscribes to tracks from a specific broadcast path (e.g., `lobby/user/abc123`)
+- **These are separate operations**: Discovery doesn't require consuming, allowing efficient room-level discovery
+- **Active/Inactive events**: Announcements include an `active` flag - `true` when a broadcast starts, `false` when it ends
+
+## Dynamic Track Management
 
-### Managing Multiple Tracks
+You can add or remove subscriptions dynamically:
 
 ```typescript
-// Define multiple tracks at once
-const broadcasts = [
-  { trackName: 'video', priority: 1 },
-  { trackName: 'audio', priority: 2 },
-  { trackName: 'screen', priority: 3 }
-];
-
-const subscriptions = [
-  { trackName: 'remote-video', priority: 1 },
-  { trackName: 'remote-audio', priority: 2 },
-  { trackName: 'remote-screen', priority: 3 }
-];
-
-session.updateBroadcasts(broadcasts);
-session.updateSubscriptions(subscriptions);
-
-// Get all active track names
-const allBroadcasts = session.getAllBroadcastTrackNames();
-const allSubscriptions = session.getAllSubscriptionTrackNames();
-console.log('Broadcasting:', allBroadcasts);
-console.log('Subscribed to:', allSubscriptions);
+// Add a subscription
+subscriber.addSubscription({ trackName: 'chat', priority: 0 });
+
+// Remove a subscription
+subscriber.removeSubscription('chat');
+
+// Update all subscriptions at once
+subscriber.updateSubscriptions([
+  { trackName: 'video', priority: 10 },
+  { trackName: 'audio', priority: 5 }
+]);
 ```
 
+## Advanced Usage
+
 ### Infinite Retry Logic
 
 Both reconnection and subscription retries run infinitely with configurable delays:
 
 ```typescript
 // Session with custom reconnection delay
-const session = new MoQSession({
-  relayUrl: 'wss://relay.quic.video',
-  namespace: 'persistent-app',
-  reconnection: {
-    delay: 5000  // Wait 5 seconds between reconnection attempts
-  }
-});
-
-// Subscription with custom retry delay
-session.updateSubscriptions([
+const subscriber = new MoqSessionSubscriber(
   {
-    trackName: 'important-track',
-    retry: {
-      delay: 3000  // Wait 3 seconds between retry attempts
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'persistent-app',
+    reconnection: {
+      delay: 5000  // Wait 5 seconds between reconnection attempts
     }
-  }
-]);
+  },
+  [
+    {
+      trackName: 'important-track',
+      retry: {
+        delay: 3000  // Wait 3 seconds between retry attempts
+      }
+    }
+  ]
+);
 ```
 
 ### Bidirectional Communication
@@ -400,47 +472,72 @@ sessionA.on('data', (trackName, data) => {
 const sessionB = new MoQSession({
   relayUrl: 'wss://relay.quic.video',
   namespace: 'app-b'
-});
-
-await sessionB.connect();
+});users:
 
-// Set up tracks
-sessionB.updateSubscriptions([{ trackName: 'data-from-a' }]);
-sessionB.updateBroadcasts([{ trackName: 'data-from-b' }]);
+```typescript
+// User A: Broadcaster and Subscriber
+const broadcasterA = new MoqSessionBroadcaster(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'app/user-a'
+  },
+  [
+    { trackName: 'video', priority: 10, type: 'video' },
+    { trackName: 'audio', priority: 5, type: 'audio' }
+  ]
+);
+
+const subscriberA = new MoqSessionSubscriber(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'app/user-b'
+  },
+  [
+    { trackName: 'video', priority: 10 },
+    { trackName: 'audio', priority: 5 }
+  ]
+);
+
+// User B: Broadcaster and Subscriber
+const broadcasterB = new MoqSessionBroadcaster(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'app/user-b'
+  },
+  [
+    { trackName: 'video', priority: 10, type: 'video' },
+    { trackName: 'audio', priority: 5, type: 'audio' }
+  ]
+);
+
+const subscriberB = new MoqSessionSubscriber(
+  {
+    relayUrl: 'https://relay.quic.video',
+    namespace: 'app/user-a'
+  },
+  [
+    { trackName: 'video', priority: 10 },
+    { trackName: 'audio', priority: 5 }
+  ]
+);
+
+// Connect all sessions
+await Promise.all([
+  broadcasterA.connect(),
+  subscriberA.connect(),
+  broadcasterB.connect(),
+  subscriberB.connect()
+]);
 
-// Listen for data from App A
-sessionB.on('data', (trackName, data) => {
-  if (trackName === 'data-from-a') {
-    console.log('App B received data from App A:', data);
-  }
+// Listen for incoming data
+subscriberA.on('data', (trackName, data) => {
+  console.log('User A received:', trackName, data.length);
 });
 
-// Send data from App A to App B
-await sessionA.send('data-from-a', new TextEncoder().encode('Hello from A'));
-
-// Send data from App B to App A
-await sessionB.send('data-from-b', new TextEncoder().encode('Hello from B'));
-```
-```
-
-## Dependencies
-
-This library is built on top of:
-- [@kixelated/moq](https://github.com/kixelated/moq-js) v0.9.1 - Core MoQ implementation
-- Uses the `moq-lite-draft-04` specification (not the standard IETF MoQ draft)
-- WebTransport only (no WebSocket fallback)
-
-## Browser Support
-
-Requires modern browsers with WebTransport support:
-- Chrome 97+
-- Edge 97+
-- Safari 15.4+ (with WebTransport enabled)
-
-## License
-
-MIT
-
-## Contributing
+subscriberB.on('data', (trackName, data) => {
+  console.log('User B received:', trackName, data.length);
+});
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+// Send data
+broadcasterA.send('video', videoDataA, true);
+broadcasterB.send('video', videoDataB, true