@daydreamlive/browser 0.3.0 → 0.3.2

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/types.ts
+// src/types/common.ts
 var DEFAULT_ICE_SERVERS = [
   { urls: "stun:stun.l.google.com:19302" },
   { urls: "stun:stun1.l.google.com:19302" },
@@ -9,6 +9,12 @@ var DEFAULT_AUDIO_BITRATE = 64e3;
 
 // src/errors.ts
 var BaseDaydreamError = class extends Error {
+  /**
+   * Creates a new DaydreamError.
+   * @param code - Error code
+   * @param message - Human-readable error message
+   * @param cause - Optional underlying cause
+   */
   constructor(code, message, cause) {
     super(message);
     this.name = "DaydreamError";
@@ -417,7 +423,7 @@ var TypedEventEmitter = class {
       this.listeners.set(event, /* @__PURE__ */ new Set());
     }
     this.listeners.get(event).add(handler);
-    return this;
+    return () => this.off(event, handler);
   }
   off(event, handler) {
     this.listeners.get(event)?.delete(handler);
@@ -467,6 +473,10 @@ var BROADCAST_TRANSITIONS = {
   error: ["connecting"]
 };
 var Broadcast = class extends TypedEventEmitter {
+  /**
+   * Creates a new Broadcast instance.
+   * @param config - Broadcast configuration
+   */
   constructor(config) {
     super();
     this._whepUrl = null;
@@ -489,15 +499,19 @@ var Broadcast = class extends TypedEventEmitter {
       (_from, to) => this.emit("stateChange", to)
     );
   }
+  /** Current broadcast state. */
   get state() {
     return this.stateMachine.current;
   }
+  /** WHEP playback URL for viewers, available after connecting. */
   get whepUrl() {
     return this._whepUrl;
   }
+  /** The MediaStream being broadcast. */
   get stream() {
     return this.currentStream;
   }
+  /** Information about the current reconnection attempt, or null if not reconnecting. */
   get reconnectInfo() {
     if (this.state !== "reconnecting") return null;
     const baseDelay = this.reconnectConfig.baseDelayMs ?? 1e3;
@@ -508,6 +522,10 @@ var Broadcast = class extends TypedEventEmitter {
       delayMs: delay
     };
   }
+  /**
+   * Establishes the WebRTC connection and starts broadcasting.
+   * @throws {DaydreamError} If connection fails
+   */
   async connect() {
     try {
       const result = await this.whipClient.connect(this.currentStream);
@@ -523,15 +541,28 @@ var Broadcast = class extends TypedEventEmitter {
       throw daydreamError;
     }
   }
+  /**
+   * Stops the broadcast and disconnects.
+   * After calling this, the instance cannot be reused.
+   */
   async stop() {
     this.stateMachine.force("ended");
     this.clearTimeouts();
     await this.whipClient.disconnect();
     this.clearListeners();
   }
+  /**
+   * Sets the maximum frame rate for the video track.
+   * @param fps - Maximum frame rate, or undefined to remove the limit
+   */
   setMaxFramerate(fps) {
     this.whipClient.setMaxFramerate(fps);
   }
+  /**
+   * Replaces the current MediaStream with a new one.
+   * The tracks are replaced in-place if connected, otherwise just stored.
+   * @param newStream - The new MediaStream to use
+   */
   async replaceStream(newStream) {
     if (!this.whipClient.isConnected()) {
       this.currentStream = newStream;
@@ -863,6 +894,10 @@ var PLAYER_TRANSITIONS = {
   error: ["connecting"]
 };
 var Player = class extends TypedEventEmitter {
+  /**
+   * Creates a new Player instance.
+   * @param config - Player configuration
+   */
   constructor(config) {
     super();
     this._stream = null;
@@ -886,12 +921,15 @@ var Player = class extends TypedEventEmitter {
       (_from, to) => this.emit("stateChange", to)
     );
   }
+  /** Current player state. */
   get state() {
     return this.stateMachine.current;
   }
+  /** The received MediaStream, or null if not connected. */
   get stream() {
     return this._stream;
   }
+  /** Information about the current reconnection attempt, or null if not buffering. */
   get reconnectInfo() {
     if (this.state !== "buffering") return null;
     const baseDelay = this.reconnectConfig.baseDelayMs ?? 200;
@@ -905,6 +943,10 @@ var Player = class extends TypedEventEmitter {
       delayMs: delay
     };
   }
+  /**
+   * Establishes the WebRTC connection and starts receiving the stream.
+   * @throws {DaydreamError} If connection fails after all retry attempts
+   */
   async connect() {
     try {
       this._stream = await this.whepClient.connect();
@@ -922,11 +964,19 @@ var Player = class extends TypedEventEmitter {
       throw daydreamError;
     }
   }
+  /**
+   * Attaches the received stream to a video element.
+   * @param video - The HTMLVideoElement to display the stream
+   */
   attachTo(video) {
     if (this._stream) {
       video.srcObject = this._stream;
     }
   }
+  /**
+   * Stops playback and disconnects.
+   * After calling this, the instance cannot be reused.
+   */
   async stop() {
     this.stateMachine.force("ended");
     this.clearTimeouts();
@@ -1784,30 +1834,7 @@ function createVisibilityHandler(options) {
 }
 
 // src/Compositor.ts
-var CompositorEventEmitter = class {
-  constructor() {
-    this.listeners = /* @__PURE__ */ new Map();
-  }
-  on(event, handler) {
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, /* @__PURE__ */ new Set());
-    }
-    this.listeners.get(event).add(handler);
-    return () => this.off(event, handler);
-  }
-  off(event, handler) {
-    this.listeners.get(event)?.delete(handler);
-  }
-  emit(event, ...args) {
-    this.listeners.get(event)?.forEach((handler) => {
-      handler(...args);
-    });
-  }
-  clearListeners() {
-    this.listeners.clear();
-  }
-};
-var Compositor = class extends CompositorEventEmitter {
+var Compositor = class extends TypedEventEmitter {
   constructor(options = {}) {
     super();
     this._activeId = null;
@@ -1875,10 +1902,20 @@ var Compositor = class extends CompositorEventEmitter {
   // ============================================================================
   // Source Registry
   // ============================================================================
+  /**
+   * Registers a source with a unique ID.
+   * @param id - Unique identifier for the source
+   * @param source - The source configuration (video or canvas element)
+   */
   register(id, source) {
     if (this.destroyed) return;
     this.registry.register(id, source);
   }
+  /**
+   * Unregisters a source by ID.
+   * If the source is currently active, it will be deactivated first.
+   * @param id - The source ID to unregister
+   */
   unregister(id) {
     if (this.destroyed) return;
     const wasActive = this._activeId === id;
@@ -1890,18 +1927,38 @@ var Compositor = class extends CompositorEventEmitter {
       this.emit("activated", null, void 0);
     }
   }
+  /**
+   * Gets a registered source by ID.
+   * @param id - The source ID
+   * @returns The source, or undefined if not found
+   */
   get(id) {
     return this.registry.get(id);
   }
+  /**
+   * Checks if a source is registered.
+   * @param id - The source ID to check
+   * @returns True if the source is registered
+   */
   has(id) {
     return this.registry.has(id);
   }
+  /**
+   * Lists all registered sources.
+   * @returns Array of source entries with id and source
+   */
   list() {
     return this.registry.list();
   }
   // ============================================================================
   // Active Source Management
   // ============================================================================
+  /**
+   * Activates a registered source for rendering.
+   * Only one source can be active at a time.
+   * @param id - The source ID to activate
+   * @throws {Error} If the source is not registered
+   */
   activate(id) {
     if (this.destroyed) return;
     const source = this.registry.get(id);
@@ -1914,6 +1971,10 @@ var Compositor = class extends CompositorEventEmitter {
     this.scheduler.start(videoEl);
     this.emit("activated", id, source);
   }
+  /**
+   * Deactivates the current source.
+   * The compositor will stop rendering until another source is activated.
+   */
   deactivate() {
     if (this.destroyed) return;
     this._activeId = null;
@@ -1921,18 +1982,27 @@ var Compositor = class extends CompositorEventEmitter {
     this.scheduler.stop();
     this.emit("activated", null, void 0);
   }
+  /** ID of the currently active source, or null if none. */
   get activeId() {
     return this._activeId;
   }
   // ============================================================================
   // Output Stream
   // ============================================================================
+  /** The composited output MediaStream. Can be used with Broadcast or other consumers. */
   get stream() {
     return this.outputStream;
   }
   // ============================================================================
   // Settings
   // ============================================================================
+  /**
+   * Resizes the output canvas.
+   * This recreates the output stream, so consumers may need to be updated.
+   * @param width - New width in logical pixels
+   * @param height - New height in logical pixels
+   * @param dpr - Optional device pixel ratio (defaults to window.devicePixelRatio, capped at 2)
+   */
   resize(width, height, dpr) {
     if (this.destroyed) return;
     const effectiveDpr = Math.min(
@@ -1942,9 +2012,15 @@ var Compositor = class extends CompositorEventEmitter {
     this.renderer.resize(width, height, effectiveDpr);
     this.recreateStream();
   }
+  /** Current output size configuration. */
   get size() {
     return this.renderer.size;
   }
+  /**
+   * Sets the rendering frame rate.
+   * This recreates the output stream, so consumers may need to be updated.
+   * @param fps - Frame rate (minimum 1)
+   */
   setFps(fps) {
     if (this.destroyed) return;
     const next = Math.max(1, fps);
@@ -1953,9 +2029,15 @@ var Compositor = class extends CompositorEventEmitter {
     this.scheduler.setFps(next);
     this.recreateStream();
   }
+  /** Current rendering frame rate. */
   get fps() {
     return this._fps;
   }
+  /**
+   * Sets the frame rate for sending to the stream.
+   * Can be different from the rendering FPS (e.g., render at 60fps, send at 30fps).
+   * @param fps - Frame rate (minimum 1)
+   */
   setSendFps(fps) {
     if (this.destroyed) return;
     const next = Math.max(1, fps);
@@ -1963,20 +2045,34 @@ var Compositor = class extends CompositorEventEmitter {
     this._sendFps = next;
     this.scheduler.setSendFps(next);
   }
+  /** Current send frame rate. */
   get sendFps() {
     return this._sendFps;
   }
   // ============================================================================
   // Audio
   // ============================================================================
+  /**
+   * Adds an audio track to the output stream.
+   * @param track - The MediaStreamTrack to add (must be an audio track)
+   */
   addAudioTrack(track) {
     if (this.destroyed) return;
     this.audioManager.addTrack(track);
   }
+  /**
+   * Removes an audio track from the output stream.
+   * @param trackId - The track ID to remove
+   */
   removeAudioTrack(trackId) {
     if (this.destroyed) return;
     this.audioManager.removeTrack(trackId);
   }
+  /**
+   * Manually unlocks the audio context.
+   * Usually not needed as audio is auto-unlocked on user interaction.
+   * @returns True if the audio context was successfully unlocked
+   */
   unlockAudio() {
     if (this.destroyed) return Promise.resolve(false);
     return this.audioManager.unlock();
@@ -1984,6 +2080,10 @@ var Compositor = class extends CompositorEventEmitter {
   // ============================================================================
   // Lifecycle
   // ============================================================================
+  /**
+   * Destroys the compositor and releases all resources.
+   * After calling this, the instance cannot be reused.
+   */
   destroy() {
     if (this.destroyed) return;
     this.destroyed = true;