@daydreamlive/browser 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -1,127 +1,179 @@
+/**
+ * Configuration for automatic reconnection behavior.
+ */
+interface ReconnectConfig {
+    /** Whether automatic reconnection is enabled. Defaults to `true`. */
+    enabled?: boolean;
+    /** Maximum number of reconnection attempts before giving up. */
+    maxAttempts?: number;
+    /** Base delay in milliseconds between reconnection attempts. Used for exponential backoff. */
+    baseDelayMs?: number;
+}
+/**
+ * Information about the current reconnection attempt.
+ * Emitted with the `reconnect` event.
+ */
+interface ReconnectInfo {
+    /** Current attempt number (1-indexed). */
+    attempt: number;
+    /** Maximum number of attempts before giving up. */
+    maxAttempts: number;
+    /** Delay in milliseconds before this reconnection attempt. */
+    delayMs: number;
+}
+/**
+ * Video encoding configuration.
+ */
+interface VideoConfig {
+    /** Target video bitrate in bits per second. Defaults to 300,000 (300 kbps). */
+    bitrate?: number;
+    /** Maximum frame rate for the video track. */
+    maxFramerate?: number;
+}
+/**
+ * Audio encoding configuration.
+ */
+interface AudioConfig {
+    /** Target audio bitrate in bits per second. Defaults to 64,000 (64 kbps). */
+    bitrate?: number;
+}
+/**
+ * Error interface for all Daydream SDK errors.
+ * Extends the standard Error with a code and optional cause.
+ */
+interface DaydreamError extends Error {
+    /** Error code identifying the type of error. */
+    code: DaydreamErrorCode;
+    /** The underlying cause of the error, if any. */
+    cause?: unknown;
+}
+/**
+ * Error codes for Daydream SDK errors.
+ * - `NETWORK_ERROR`: Network-related failure (e.g., fetch failed)
+ * - `CONNECTION_FAILED`: WebRTC connection failed to establish
+ * - `STREAM_NOT_FOUND`: The requested stream does not exist
+ * - `UNAUTHORIZED`: Authentication or authorization failed
+ * - `UNKNOWN`: An unexpected error occurred
+ */
+type DaydreamErrorCode = "NETWORK_ERROR" | "CONNECTION_FAILED" | "STREAM_NOT_FOUND" | "UNAUTHORIZED" | "UNKNOWN";
+/**
+ * Default ICE servers used for WebRTC connections.
+ * Includes Google and Cloudflare STUN servers.
+ */
+declare const DEFAULT_ICE_SERVERS: RTCIceServer[];
+/** Default video bitrate in bits per second (300 kbps). */
+declare const DEFAULT_VIDEO_BITRATE = 300000;
+/** Default audio bitrate in bits per second (64 kbps). */
+declare const DEFAULT_AUDIO_BITRATE = 64000;
+
+/**
+ * Possible states of a broadcast session.
+ * - `connecting`: Initial connection in progress
+ * - `live`: Successfully connected and streaming
+ * - `reconnecting`: Connection lost, attempting to reconnect
+ * - `ended`: Broadcast has been stopped
+ * - `error`: An error occurred during connection
+ */
 type BroadcastState = "connecting" | "live" | "reconnecting" | "ended" | "error";
-type PlayerState = "connecting" | "playing" | "buffering" | "ended" | "error";
+/**
+ * Result extracted from a WHIP response.
+ */
 interface WHIPResponseResult {
+    /** The WHEP playback URL for viewers to connect to this broadcast. */
     whepUrl?: string;
 }
+/**
+ * Options for creating a broadcast session.
+ *
+ * @example
+ * ```ts
+ * const broadcast = createBroadcast({
+ *   whipUrl: "https://livepeer.studio/webrtc/...",
+ *   stream: await navigator.mediaDevices.getUserMedia({ video: true, audio: true }),
+ *   video: { bitrate: 1_000_000 },
+ * });
+ * ```
+ */
 interface BroadcastOptions {
+    /** WHIP endpoint URL for publishing the stream. */
     whipUrl: string;
+    /** MediaStream to broadcast (typically from getUserMedia or canvas). */
     stream: MediaStream;
+    /** Reconnection behavior configuration. */
     reconnect?: ReconnectConfig;
+    /** Video encoding settings. */
     video?: VideoConfig;
+    /** Audio encoding settings. */
     audio?: AudioConfig;
+    /** Custom ICE servers for WebRTC connection. */
     iceServers?: RTCIceServer[];
+    /** Timeout in milliseconds for the initial connection. */
     connectionTimeout?: number;
+    /** Callback invoked periodically with WebRTC stats. */
     onStats?: (report: RTCStatsReport) => void;
+    /** Interval in milliseconds for stats collection. */
     statsIntervalMs?: number;
+    /** Callback to extract data from the WHIP response (e.g., playback URL). */
     onResponse?: (response: Response) => WHIPResponseResult | void;
 }
+/**
+ * Event map for Broadcast class events.
+ * Use with `broadcast.on(event, callback)`.
+ */
+interface BroadcastEventMap {
+    /** Emitted when the broadcast state changes. */
+    stateChange: (state: BroadcastState) => void;
+    /** Emitted when an error occurs. */
+    error: (error: DaydreamError) => void;
+    /** Emitted when a reconnection attempt starts. */
+    reconnect: (info: ReconnectInfo) => void;
+}
+
+/**
+ * Possible states of a player session.
+ * - `connecting`: Initial connection in progress
+ * - `playing`: Successfully connected and receiving stream
+ * - `buffering`: Connection interrupted, attempting to reconnect
+ * - `ended`: Playback has been stopped
+ * - `error`: An error occurred during connection
+ */
+type PlayerState = "connecting" | "playing" | "buffering" | "ended" | "error";
+/**
+ * Options for creating a player session.
+ *
+ * @example
+ * ```ts
+ * const player = createPlayer("https://livepeer.studio/webrtc/...", {
+ *   reconnect: { maxAttempts: 10 },
+ * });
+ * ```
+ */
 interface PlayerOptions {
+    /** Reconnection behavior configuration. */
     reconnect?: ReconnectConfig;
+    /** Custom ICE servers for WebRTC connection. */
     iceServers?: RTCIceServer[];
+    /** Timeout in milliseconds for the initial connection. */
     connectionTimeout?: number;
+    /** Skip ICE gathering to speed up connection (may not work with all servers). */
     skipIceGathering?: boolean;
+    /** Callback invoked periodically with WebRTC stats. */
     onStats?: (report: RTCStatsReport) => void;
+    /** Interval in milliseconds for stats collection. */
     statsIntervalMs?: number;
 }
-interface ReconnectConfig {
-    enabled?: boolean;
-    maxAttempts?: number;
-    baseDelayMs?: number;
-}
-interface ReconnectInfo {
-    attempt: number;
-    maxAttempts: number;
-    delayMs: number;
-}
-interface VideoConfig {
-    bitrate?: number;
-    maxFramerate?: number;
-}
-interface AudioConfig {
-    bitrate?: number;
-}
-interface BroadcastEventMap {
-    stateChange: (state: BroadcastState) => void;
-    error: (error: DaydreamError) => void;
-    reconnect: (info: ReconnectInfo) => void;
-}
+/**
+ * Event map for Player class events.
+ * Use with `player.on(event, callback)`.
+ */
 interface PlayerEventMap {
+    /** Emitted when the player state changes. */
     stateChange: (state: PlayerState) => void;
+    /** Emitted when an error occurs. */
     error: (error: DaydreamError) => void;
+    /** Emitted when a reconnection attempt starts. */
     reconnect: (info: ReconnectInfo) => void;
 }
-interface DaydreamError extends Error {
-    code: DaydreamErrorCode;
-    cause?: unknown;
-}
-type DaydreamErrorCode = "NETWORK_ERROR" | "CONNECTION_FAILED" | "STREAM_NOT_FOUND" | "UNAUTHORIZED" | "UNKNOWN";
-declare const DEFAULT_ICE_SERVERS: RTCIceServer[];
-declare const DEFAULT_VIDEO_BITRATE = 300000;
-declare const DEFAULT_AUDIO_BITRATE = 64000;
-type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
-type FitMode = "contain" | "cover";
-type ContentHint = "detail" | "motion" | "";
-type VideoSource = {
-    kind: "video";
-    element: HTMLVideoElement;
-    fit?: FitMode;
-    contentHint?: ContentHint;
-};
-type CanvasSource = {
-    kind: "canvas";
-    element: HTMLCanvasElement;
-    fit?: FitMode;
-    contentHint?: ContentHint;
-};
-type Source = VideoSource | CanvasSource;
-type Size = {
-    width: number;
-    height: number;
-    dpr: number;
-};
-interface CompositorOptions {
-    width?: number;
-    height?: number;
-    fps?: number;
-    dpr?: number;
-    sendFps?: number;
-    keepalive?: boolean;
-    autoUnlockAudio?: boolean;
-    unlockEvents?: string[];
-    disableSilentAudio?: boolean;
-    onSendFpsChange?: (fps: number) => void;
-}
-type CompositorEvent = "activated" | "registered" | "unregistered";
-interface CompositorEventMap {
-    activated: (id: string | null, source: Source | undefined) => void;
-    registered: (id: string, source: Source) => void;
-    unregistered: (id: string) => void;
-}
-interface Compositor$1 {
-    register(id: string, source: Source): void;
-    unregister(id: string): void;
-    get(id: string): Source | undefined;
-    has(id: string): boolean;
-    list(): Array<{
-        id: string;
-        source: Source;
-    }>;
-    activate(id: string): void;
-    deactivate(): void;
-    readonly activeId: string | null;
-    readonly stream: MediaStream;
-    resize(width: number, height: number, dpr?: number): void;
-    readonly size: Size;
-    setFps(fps: number): void;
-    readonly fps: number;
-    setSendFps(fps: number): void;
-    readonly sendFps: number;
-    addAudioTrack(track: MediaStreamTrack): void;
-    removeAudioTrack(trackId: string): void;
-    unlockAudio(): Promise<boolean>;
-    destroy(): void;
-    on<E extends CompositorEvent>(event: E, cb: CompositorEventMap[E]): () => void;
-}
 
 interface PeerConnectionFactory {
     create(config: RTCConfiguration): RTCPeerConnection;
@@ -164,18 +216,45 @@ declare class TypedEventEmitter<EventMap extends {
     [K in keyof EventMap]: (...args: any[]) => void;
 }> {
     private listeners;
-    on<E extends keyof EventMap>(event: E, handler: EventMap[E]): this;
+    on<E extends keyof EventMap>(event: E, handler: EventMap[E]): () => void;
     off<E extends keyof EventMap>(event: E, handler: EventMap[E]): this;
     protected emit<E extends keyof EventMap>(event: E, ...args: Parameters<EventMap[E]>): void;
     protected clearListeners(): void;
 }
 
+/**
+ * Low-level configuration for the Broadcast class.
+ * For most use cases, prefer using {@link createBroadcast} with {@link BroadcastOptions}.
+ */
 interface BroadcastConfig {
+    /** WHIP endpoint URL for publishing the stream. */
     whipUrl: string;
+    /** MediaStream to broadcast. */
     stream: MediaStream;
+    /** Reconnection behavior configuration. */
     reconnect?: ReconnectConfig;
+    /** Advanced WHIP client configuration. */
     whipConfig?: Partial<WHIPClientConfig>;
 }
+/**
+ * Manages a WebRTC broadcast session using WHIP protocol.
+ *
+ * Handles connection establishment, reconnection logic, and stream management.
+ * Emits events for state changes, errors, and reconnection attempts.
+ *
+ * @example
+ * ```ts
+ * const broadcast = new Broadcast({
+ *   whipUrl: "https://example.com/whip",
+ *   stream: mediaStream,
+ * });
+ *
+ * broadcast.on("stateChange", (state) => console.log("State:", state));
+ * await broadcast.connect();
+ * ```
+ *
+ * @see {@link createBroadcast} for a simpler factory function
+ */
 declare class Broadcast extends TypedEventEmitter<BroadcastEventMap> {
     private _whepUrl;
     private readonly stateMachine;
@@ -185,14 +264,39 @@ declare class Broadcast extends TypedEventEmitter<BroadcastEventMap> {
     private reconnectAttempts;
     private reconnectTimeout;
     private disconnectedGraceTimeout;
+    /**
+     * Creates a new Broadcast instance.
+     * @param config - Broadcast configuration
+     */
     constructor(config: BroadcastConfig);
+    /** Current broadcast state. */
     get state(): BroadcastState;
+    /** WHEP playback URL for viewers, available after connecting. */
     get whepUrl(): string | null;
+    /** The MediaStream being broadcast. */
     get stream(): MediaStream;
+    /** Information about the current reconnection attempt, or null if not reconnecting. */
     get reconnectInfo(): ReconnectInfo | null;
+    /**
+     * Establishes the WebRTC connection and starts broadcasting.
+     * @throws {DaydreamError} If connection fails
+     */
     connect(): Promise<void>;
+    /**
+     * Stops the broadcast and disconnects.
+     * After calling this, the instance cannot be reused.
+     */
     stop(): Promise<void>;
+    /**
+     * Sets the maximum frame rate for the video track.
+     * @param fps - Maximum frame rate, or undefined to remove the limit
+     */
     setMaxFramerate(fps?: number): void;
+    /**
+     * 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
+     */
     replaceStream(newStream: MediaStream): Promise<void>;
     private setupConnectionMonitoring;
     private clearGraceTimeout;
@@ -214,11 +318,37 @@ interface WHEPClientConfig {
     mediaStreamFactory?: MediaStreamFactory;
 }
 
+/**
+ * Low-level configuration for the Player class.
+ * For most use cases, prefer using {@link createPlayer} with {@link PlayerOptions}.
+ */
 interface PlayerConfig {
+    /** WHEP endpoint URL for receiving the stream. */
     whepUrl: string;
+    /** Reconnection behavior configuration. */
     reconnect?: ReconnectConfig;
+    /** Advanced WHEP client configuration. */
     whepConfig?: Partial<WHEPClientConfig>;
 }
+/**
+ * Manages a WebRTC playback session using WHEP protocol.
+ *
+ * Handles connection establishment, reconnection logic, and stream management.
+ * Emits events for state changes, errors, and reconnection attempts.
+ *
+ * @example
+ * ```ts
+ * const player = new Player({
+ *   whepUrl: "https://example.com/whep/stream-id",
+ * });
+ *
+ * player.on("stateChange", (state) => console.log("State:", state));
+ * await player.connect();
+ * player.attachTo(videoElement);
+ * ```
+ *
+ * @see {@link createPlayer} for a simpler factory function
+ */
 declare class Player extends TypedEventEmitter<PlayerEventMap> {
     private readonly stateMachine;
     private _stream;
@@ -229,12 +359,31 @@ declare class Player extends TypedEventEmitter<PlayerEventMap> {
     private reconnectAttempts;
     private reconnectTimeout;
     private disconnectedGraceTimeout;
+    /**
+     * Creates a new Player instance.
+     * @param config - Player configuration
+     */
     constructor(config: PlayerConfig);
+    /** Current player state. */
     get state(): PlayerState;
+    /** The received MediaStream, or null if not connected. */
     get stream(): MediaStream | null;
+    /** Information about the current reconnection attempt, or null if not buffering. */
     get reconnectInfo(): ReconnectInfo | null;
+    /**
+     * Establishes the WebRTC connection and starts receiving the stream.
+     * @throws {DaydreamError} If connection fails after all retry attempts
+     */
     connect(): Promise<void>;
+    /**
+     * Attaches the received stream to a video element.
+     * @param video - The HTMLVideoElement to display the stream
+     */
     attachTo(video: HTMLVideoElement): void;
+    /**
+     * Stops playback and disconnects.
+     * After calling this, the instance cannot be reused.
+     */
     stop(): Promise<void>;
     private setupConnectionMonitoring;
     private clearGraceTimeout;
@@ -244,32 +393,237 @@ declare class Player extends TypedEventEmitter<PlayerEventMap> {
     private calculateReconnectDelay;
 }
 
+/**
+ * Base class for all Daydream SDK errors.
+ * Extends the standard Error with a code and optional cause for error chaining.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await broadcast.connect();
+ * } catch (err) {
+ *   if (err instanceof BaseDaydreamError) {
+ *     console.log("Error code:", err.code);
+ *     console.log("Cause:", err.cause);
+ *   }
+ * }
+ * ```
+ */
 declare class BaseDaydreamError extends Error implements DaydreamError {
+    /** Error code identifying the type of error. */
     readonly code: DaydreamErrorCode;
+    /** The underlying cause of the error, if any. */
     readonly cause?: unknown;
+    /**
+     * Creates a new DaydreamError.
+     * @param code - Error code
+     * @param message - Human-readable error message
+     * @param cause - Optional underlying cause
+     */
     constructor(code: DaydreamErrorCode, message: string, cause?: unknown);
 }
+/**
+ * Error thrown when a network request fails (e.g., fetch failed, timeout).
+ */
 declare class NetworkError extends BaseDaydreamError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Error thrown when a WebRTC connection fails to establish.
+ */
 declare class ConnectionError extends BaseDaydreamError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Error thrown when the requested stream does not exist (404).
+ */
 declare class StreamNotFoundError extends BaseDaydreamError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * Error thrown when authentication or authorization fails (401/403).
+ */
 declare class UnauthorizedError extends BaseDaydreamError {
     constructor(message: string, cause?: unknown);
 }
 
-declare class CompositorEventEmitter {
-    private listeners;
-    on<E extends CompositorEvent>(event: E, handler: CompositorEventMap[E]): () => void;
-    off<E extends CompositorEvent>(event: E, handler: CompositorEventMap[E]): void;
-    protected emit<E extends CompositorEvent>(event: E, ...args: Parameters<CompositorEventMap[E]>): void;
-    protected clearListeners(): void;
+/**
+ * 2D rendering context type, supporting both regular canvas and OffscreenCanvas.
+ */
+type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/**
+ * How to fit the source content within the output canvas.
+ * - `contain`: Scale to fit entirely within bounds (may have letterboxing)
+ * - `cover`: Scale to fill bounds completely (may crop edges)
+ */
+type FitMode = "contain" | "cover";
+/**
+ * Content hint for the video track, indicating the type of content.
+ * - `detail`: Optimize for sharp details (e.g., text, screen sharing)
+ * - `motion`: Optimize for smooth motion (e.g., video, animation)
+ * - `""`: No hint (browser default)
+ */
+type ContentHint = "detail" | "motion" | "";
+/**
+ * A video element source for the compositor.
+ */
+type VideoSource = {
+    kind: "video";
+    /** The HTMLVideoElement to capture frames from. */
+    element: HTMLVideoElement;
+    /** How to fit the video within the output canvas. */
+    fit?: FitMode;
+    /** Content hint for encoding optimization. */
+    contentHint?: ContentHint;
+};
+/**
+ * A canvas element source for the compositor.
+ */
+type CanvasSource = {
+    kind: "canvas";
+    /** The HTMLCanvasElement to capture frames from. */
+    element: HTMLCanvasElement;
+    /** How to fit the canvas within the output canvas. */
+    fit?: FitMode;
+    /** Content hint for encoding optimization. */
+    contentHint?: ContentHint;
+};
+/**
+ * A source that can be registered with the compositor.
+ * Either a video element or a canvas element.
+ */
+type Source = VideoSource | CanvasSource;
+/**
+ * Size configuration for the compositor output.
+ */
+type Size = {
+    /** Output width in logical pixels. */
+    width: number;
+    /** Output height in logical pixels. */
+    height: number;
+    /** Device pixel ratio for high-DPI rendering. Capped at 2. */
+    dpr: number;
+};
+/**
+ * Options for creating a compositor instance.
+ *
+ * @example
+ * ```ts
+ * const compositor = createCompositor({
+ *   width: 1280,
+ *   height: 720,
+ *   fps: 30,
+ * });
+ * ```
+ */
+interface CompositorOptions {
+    /** Output width in logical pixels. Defaults to 512. */
+    width?: number;
+    /** Output height in logical pixels. Defaults to 512. */
+    height?: number;
+    /** Rendering frame rate. Defaults to 30. */
+    fps?: number;
+    /** Device pixel ratio. Defaults to window.devicePixelRatio, capped at 2. */
+    dpr?: number;
+    /** Frame rate for sending to the stream (can differ from rendering fps). */
+    sendFps?: number;
+    /** Continue rendering when the page is hidden. Defaults to true. */
+    keepalive?: boolean;
+    /** Automatically unlock audio context on user interaction. Defaults to true. */
+    autoUnlockAudio?: boolean;
+    /** Events that trigger audio unlock. Defaults to ["pointerdown", "click", "touchstart", "keydown"]. */
+    unlockEvents?: string[];
+    /** Disable silent audio track (used for keeping audio context alive). */
+    disableSilentAudio?: boolean;
+    /** Callback when sendFps changes (e.g., due to visibility changes). */
+    onSendFpsChange?: (fps: number) => void;
+}
+/**
+ * Event names emitted by the compositor.
+ */
+type CompositorEvent = "activated" | "registered" | "unregistered";
+/**
+ * Event map for Compositor class events.
+ * Use with `compositor.on(event, callback)`.
+ */
+interface CompositorEventMap {
+    /** Emitted when a source is activated or deactivated. */
+    activated: (id: string | null, source: Source | undefined) => void;
+    /** Emitted when a source is registered. */
+    registered: (id: string, source: Source) => void;
+    /** Emitted when a source is unregistered. */
+    unregistered: (id: string) => void;
+}
+/**
+ * Interface for the Compositor class.
+ * Manages multiple video/canvas sources and composites them into a single output stream.
+ */
+interface Compositor$1 {
+    /** Register a source with a unique ID. */
+    register(id: string, source: Source): void;
+    /** Unregister a source by ID. */
+    unregister(id: string): void;
+    /** Get a registered source by ID. */
+    get(id: string): Source | undefined;
+    /** Check if a source is registered. */
+    has(id: string): boolean;
+    /** List all registered sources. */
+    list(): Array<{
+        id: string;
+        source: Source;
+    }>;
+    /** Activate a registered source for rendering. */
+    activate(id: string): void;
+    /** Deactivate the current source. */
+    deactivate(): void;
+    /** ID of the currently active source, or null if none. */
+    readonly activeId: string | null;
+    /** The composited output MediaStream. */
+    readonly stream: MediaStream;
+    /** Resize the output canvas. */
+    resize(width: number, height: number, dpr?: number): void;
+    /** Current output size. */
+    readonly size: Size;
+    /** Set the rendering frame rate. */
+    setFps(fps: number): void;
+    /** Current rendering frame rate. */
+    readonly fps: number;
+    /** Set the frame rate for sending to the stream. */
+    setSendFps(fps: number): void;
+    /** Current send frame rate. */
+    readonly sendFps: number;
+    /** Add an audio track to the output stream. */
+    addAudioTrack(track: MediaStreamTrack): void;
+    /** Remove an audio track by track ID. */
+    removeAudioTrack(trackId: string): void;
+    /** Manually unlock the audio context. Returns true if successful. */
+    unlockAudio(): Promise<boolean>;
+    /** Destroy the compositor and release all resources. */
+    destroy(): void;
+    /** Subscribe to compositor events. Returns an unsubscribe function. */
+    on<E extends CompositorEvent>(event: E, cb: CompositorEventMap[E]): () => void;
 }
-declare class Compositor extends CompositorEventEmitter implements Compositor$1 {
+
+/**
+ * Composites multiple video/canvas sources into a single output MediaStream.
+ *
+ * The Compositor manages a registry of sources, renders the active source to an internal
+ * canvas, and provides the output as a capturable MediaStream. It handles frame scheduling,
+ * visibility changes (reducing FPS when the page is hidden), and audio track management.
+ *
+ * @example
+ * ```ts
+ * const compositor = createCompositor({ width: 1280, height: 720, fps: 30 });
+ *
+ * // Register and activate a video source
+ * compositor.register("camera", { kind: "video", element: videoElement, fit: "cover" });
+ * compositor.activate("camera");
+ *
+ * // Use the output stream for broadcasting
+ * const broadcast = createBroadcast({ whipUrl, stream: compositor.stream });
+ * ```
+ */
+declare class Compositor extends TypedEventEmitter<CompositorEventMap> implements Compositor$1 {
     private readonly registry;
     private readonly renderer;
     private readonly scheduler;
@@ -282,38 +636,174 @@ declare class Compositor extends CompositorEventEmitter implements Compositor$1
     private outputStream;
     private destroyed;
     constructor(options?: CompositorOptions);
+    /**
+     * 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: string, source: Source): void;
+    /**
+     * 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: string): void;
+    /**
+     * Gets a registered source by ID.
+     * @param id - The source ID
+     * @returns The source, or undefined if not found
+     */
     get(id: string): Source | undefined;
+    /**
+     * Checks if a source is registered.
+     * @param id - The source ID to check
+     * @returns True if the source is registered
+     */
     has(id: string): boolean;
+    /**
+     * Lists all registered sources.
+     * @returns Array of source entries with id and source
+     */
     list(): Array<{
         id: string;
         source: Source;
     }>;
+    /**
+     * 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: string): void;
+    /**
+     * Deactivates the current source.
+     * The compositor will stop rendering until another source is activated.
+     */
     deactivate(): void;
+    /** ID of the currently active source, or null if none. */
     get activeId(): string | null;
+    /** The composited output MediaStream. Can be used with Broadcast or other consumers. */
     get stream(): MediaStream;
+    /**
+     * 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: number, height: number, dpr?: number): void;
+    /** Current output size configuration. */
     get size(): 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: number): void;
+    /** Current rendering frame rate. */
     get fps(): number;
+    /**
+     * 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: number): void;
+    /** Current send frame rate. */
     get sendFps(): number;
+    /**
+     * Adds an audio track to the output stream.
+     * @param track - The MediaStreamTrack to add (must be an audio track)
+     */
     addAudioTrack(track: MediaStreamTrack): void;
+    /**
+     * Removes an audio track from the output stream.
+     * @param trackId - The track ID to remove
+     */
     removeAudioTrack(trackId: string): void;
+    /**
+     * 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(): Promise<boolean>;
+    /**
+     * Destroys the compositor and releases all resources.
+     * After calling this, the instance cannot be reused.
+     */
     destroy(): void;
     private createOutputStream;
     private recreateStream;
     private applyVideoTrackConstraints;
     private requestVideoTrackFrame;
 }
+/**
+ * Creates a new Compositor instance with the given options.
+ *
+ * @param options - Compositor configuration
+ * @returns A new Compositor instance
+ *
+ * @example
+ * ```ts
+ * const compositor = createCompositor({
+ *   width: 1280,
+ *   height: 720,
+ *   fps: 30,
+ * });
+ *
+ * compositor.register("camera", { kind: "video", element: videoEl, fit: "cover" });
+ * compositor.activate("camera");
+ *
+ * // Use compositor.stream for broadcasting
+ * ```
+ */
 declare function createCompositor(options?: CompositorOptions): Compositor;
 
+/**
+ * Response handler for Livepeer WHIP endpoints.
+ * Extracts the playback URL from the `livepeer-playback-url` header.
+ *
+ * @param response - The WHIP response
+ * @returns Object containing the WHEP playback URL
+ */
 declare const livepeerResponseHandler: (response: Response) => WHIPResponseResult;
+/**
+ * Broadcast options for Livepeer, with the response handler pre-configured.
+ */
 type LivepeerBroadcastOptions = Omit<BroadcastOptions, "onResponse">;
+/**
+ * Creates a Broadcast instance configured for Livepeer.
+ * Automatically extracts the playback URL from the response.
+ *
+ * @param options - Broadcast options (without onResponse)
+ * @returns A new Broadcast instance
+ *
+ * @example
+ * ```ts
+ * const broadcast = createBroadcast({
+ *   whipUrl: "https://livepeer.studio/webrtc/...",
+ *   stream: mediaStream,
+ * });
+ *
+ * await broadcast.connect();
+ * console.log("Playback URL:", broadcast.whepUrl);
+ * ```
+ */
 declare function createBroadcast(options: LivepeerBroadcastOptions): Broadcast;
+/**
+ * Creates a Player instance for receiving a WebRTC stream.
+ *
+ * @param whepUrl - WHEP endpoint URL
+ * @param options - Optional player configuration
+ * @returns A new Player instance
+ *
+ * @example
+ * ```ts
+ * const player = createPlayer("https://livepeer.studio/webrtc/...");
+ *
+ * await player.connect();
+ * player.attachTo(videoElement);
+ * ```
+ */
 declare function createPlayer(whepUrl: string, options?: PlayerOptions): Player;
 
 export { type AudioConfig, BaseDaydreamError, Broadcast, type BroadcastConfig, type BroadcastEventMap, type BroadcastOptions, type BroadcastState, type CanvasSource, type Compositor$1 as Compositor, type CompositorEvent, type CompositorEventMap, type CompositorOptions, ConnectionError, type ContentHint, type Ctx2D, DEFAULT_AUDIO_BITRATE, DEFAULT_ICE_SERVERS, DEFAULT_VIDEO_BITRATE, type DaydreamError, type DaydreamErrorCode, type FitMode, type LivepeerBroadcastOptions, NetworkError, Player, type PlayerConfig, type PlayerEventMap, type PlayerOptions, type PlayerState, type ReconnectConfig, type ReconnectInfo, type Size, type Source, StreamNotFoundError, UnauthorizedError, type VideoConfig, type VideoSource, type WHIPResponseResult, createBroadcast, createCompositor, createPlayer, livepeerResponseHandler };