@marianmeres/webrtc 1.2.5 → 1.3.0

package/AGENTS.md

@@ -159,6 +159,15 @@ interface WebRtcManagerConfig {
 }
 ```
 
+### GatherIceCandidatesOptions Interface
+
+```typescript
+interface GatherIceCandidatesOptions {
+  timeout?: number;                                    // Timeout in ms (default: 10000)
+  onCandidate?: (candidate: RTCIceCandidate | null) => void;  // Called for each candidate
+}
+```
+
 ### Properties (Getters)
 
 | Property | Type | Description |
@@ -205,6 +214,7 @@ interface WebRtcManagerConfig {
 | setRemoteDescription | `(description: RTCSessionDescriptionInit): Promise<boolean>` | Set remote SDP |
 | addIceCandidate | `(candidate: RTCIceCandidateInit \| null): Promise<boolean>` | Add ICE candidate |
 | iceRestart | `(): Promise<boolean>` | Perform ICE restart |
+| gatherIceCandidates | `(options?: GatherIceCandidatesOptions): Promise<void>` | Wait for ICE gathering to complete |
 | getLocalDescription | `(): RTCSessionDescription \| null` | Get local SDP |
 | getRemoteDescription | `(): RTCSessionDescription \| null` | Get remote SDP |
 | getStats | `(): Promise<RTCStatsReport \| null>` | Get connection statistics |

package/README.md

@@ -95,6 +95,35 @@ await manager.setLocalDescription(offer)
 await manager.setRemoteDescription(answer)
 await manager.addIceCandidate(candidate)
 await manager.iceRestart()                     // Trigger ICE restart
+await manager.gatherIceCandidates(options)     // Wait for ICE gathering to complete
+```
+
+### gatherIceCandidates(options?)
+
+Wait for ICE gathering to complete. Useful for HTTP POST signaling patterns where you need all ICE candidates bundled in the local description before sending to the server.
+
+**Options:** `timeout` (ms, default 10000), `onCandidate` (callback for each candidate)
+
+```typescript
+const offer = await manager.createOffer();
+await manager.setLocalDescription(offer);
+await manager.gatherIceCandidates({ timeout: 5000 });
+// Now manager.peerConnection.localDescription has all ICE candidates bundled
+```
+
+**Error Handling:** A timeout rejection does *not* transition the FSM to ERROR state. This is intentional - `gatherIceCandidates()` is a utility method, and a timeout means "gathering didn't complete in time", not "the connection failed". The consumer decides how to handle it:
+
+```typescript
+try {
+  await manager.gatherIceCandidates({ timeout: 5000 });
+} catch (e) {
+  if (e.message === "ICE gathering timeout") {
+    // Options:
+    // 1. Retry with longer timeout
+    // 2. Proceed anyway - localDescription may have partial candidates
+    // 3. Treat as fatal: manager.reset()
+  }
+}
 ```
 
 ### Data Channel Methods
@@ -105,6 +134,54 @@ const dc = manager.getDataChannel(label)
 manager.sendData(label, data)                  // Returns boolean
 ```
 
+### Working with External Audio Streams
+
+You might want to keep `enableMicrophone: false` even when your application uses audio. Common scenarios include:
+
+- **Pre-acquired stream**: You may have obtained the audio stream earlier in the application flow (e.g., during a permissions check, in a lobby/waiting room, or for local audio preview before joining)
+- **Custom audio processing**: You want to apply audio effects, noise suppression, or other processing via Web Audio API before transmitting
+- **Multiple sources**: You need to mix audio from multiple sources (microphone + system audio, multiple microphones, background music, etc.)
+- **Fine-grained privacy control**: You want explicit control over exactly when the microphone activates
+- **Testing**: You want to inject synthetic audio (e.g., oscillator tones) for automated testing
+
+To use your own audio stream, access the `peerConnection` directly and add tracks after initialization:
+
+```typescript
+const manager = new WebRtcManager(factory, {
+  peerConfig: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
+  enableMicrophone: false, // We'll handle the audio stream ourselves
+});
+
+// Your pre-acquired or processed audio stream
+const myAudioStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+// Or a processed stream via Web Audio API
+const audioCtx = new AudioContext();
+const source = audioCtx.createMediaStreamSource(myAudioStream);
+const gainNode = audioCtx.createGain();
+gainNode.gain.value = 0.8;
+source.connect(gainNode);
+const destination = audioCtx.createMediaStreamDestination();
+gainNode.connect(destination);
+const processedStream = destination.stream;
+
+// Initialize the manager
+await manager.initialize();
+
+// Add your audio track to the peer connection
+const pc = manager.peerConnection;
+if (pc) {
+  processedStream.getAudioTracks().forEach((track) => {
+    pc.addTrack(track, processedStream);
+  });
+}
+
+// Continue with normal connection flow
+await manager.connect();
+const offer = await manager.createOffer();
+// ...
+```
+
 ### Event Subscription
 
 ```typescript

package/dist/types.d.ts

@@ -156,3 +156,13 @@ export interface WebRtcEvents {
     /** Emitted when an error occurs. Payload: the Error object. */
     error: Error;
 }
+/**
+ * Options for waiting for ICE gathering to complete.
+ * Used with gatherIceCandidates() for HTTP POST signaling patterns.
+ */
+export interface GatherIceCandidatesOptions {
+    /** Timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Called for each ICE candidate as it's gathered */
+    onCandidate?: (candidate: RTCIceCandidate | null) => void;
+}

package/dist/webrtc-manager.d.ts

@@ -1,4 +1,4 @@
-import { type WebRtcFactory, type WebRtcManagerConfig, WebRtcState, type WebRtcEvents } from "./types.js";
+import { type WebRtcFactory, type WebRtcManagerConfig, WebRtcState, type WebRtcEvents, type GatherIceCandidatesOptions } from "./types.js";
 /**
  * WebRTC connection manager with FSM-based lifecycle and event-driven architecture.
  *
@@ -203,6 +203,13 @@ export declare class WebRtcManager<TContext = unknown> {
      * @returns True if successful, false otherwise.
      */
     iceRestart(): Promise<boolean>;
+    /**
+     * Wait for ICE gathering to complete.
+     * Use this for HTTP POST signaling patterns where you need all ICE candidates
+     * bundled in the local description before sending to the server.
+     * @param options - Optional configuration for timeout and candidate callback.
+     */
+    gatherIceCandidates(options?: GatherIceCandidatesOptions): Promise<void>;
     /**
      * Returns the current local session description.
      * @returns The local description, or null if not set.

package/dist/webrtc-manager.js

@@ -675,6 +675,52 @@ export class WebRtcManager {
             return false;
         }
     }
+    /**
+     * Wait for ICE gathering to complete.
+     * Use this for HTTP POST signaling patterns where you need all ICE candidates
+     * bundled in the local description before sending to the server.
+     * @param options - Optional configuration for timeout and candidate callback.
+     */
+    gatherIceCandidates(options = {}) {
+        const { timeout = 10000, onCandidate } = options;
+        if (!this.#pc) {
+            return Promise.reject(new Error("Peer connection not initialized"));
+        }
+        const pc = this.#pc;
+        if (pc.iceGatheringState === "complete") {
+            this.#logDebug("ICE gathering already complete");
+            return Promise.resolve();
+        }
+        this.#logDebug("Waiting for ICE gathering to complete...");
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("ICE gathering timeout"));
+            }, timeout);
+            const cleanup = () => {
+                clearTimeout(timer);
+                pc.removeEventListener("icegatheringstatechange", checkState);
+                pc.removeEventListener("icecandidate", handleCandidate);
+            };
+            const checkState = () => {
+                if (pc.iceGatheringState === "complete") {
+                    this.#logDebug("ICE gathering complete (via state change)");
+                    cleanup();
+                    resolve();
+                }
+            };
+            const handleCandidate = (event) => {
+                onCandidate?.(event.candidate);
+                if (event.candidate === null) {
+                    this.#logDebug("ICE gathering complete (null candidate)");
+                    cleanup();
+                    resolve();
+                }
+            };
+            pc.addEventListener("icegatheringstatechange", checkState);
+            pc.addEventListener("icecandidate", handleCandidate);
+        });
+    }
     /**
      * Returns the current local session description.
      * @returns The local description, or null if not set.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/webrtc",
-	"version": "1.2.5",
+	"version": "1.3.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",