@videosdk.live/js-sdk/stream.d.ts

<h1 align="center"> <img src="https://cdn.videosdk.live/docs/images/javascript/api_ref/js_api_ref.png"/><br/> </h1>

/**
 * The `Stream` class is responsible for handling audio, video, and screen-sharing streams.
 */
export class Stream {
  /**
   * This represents a unique identifier assigned to the stream.
   */
  id: string;

  /**
   * This represents the kind of the stream.
   */
  kind: "audio" | "video" | "share" | "shareAudio";

  /**
   * This represents the codec used to encode and decode the stream.
   */
  codec: string;

  /**
   * This represents the underlying media track associated with the stream.
   */
  track: MediaStreamTrack;

  /**
   * This represents the surface type of a screen-share stream — whether the shared source is an entire screen (`"monitor"`), an application window (`"window"`), or a browser tab (`"browser"`).
   *
   * > **Note**
   * >
   * > This is available for screen-share streams of both local and remote participants. It will be `undefined` for audio, video, or any non-screen-share stream, and on browsers that do not support this feature.
   */
  displaySurface: "monitor" | "window" | "browser" | undefined;

  /**
   * This represents whether the stream is currently paused.
   */
  paused: boolean;

  /**
   * - This method can be used to resume the stream for a remote participant.
   *
   * @throws
   * - {@link Errors.ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED} — called before meeting is joined
   * - {@link Errors.ERROR_MEETING_RECONNECTING} — meeting is reconnecting
   * - {@link Errors.ERROR_ACTION_NOT_SUPPORTED} — stream has no active consumer (also thrown on a local stream)
   * - {@link Errors.ERROR_ALREADY_IN_REQUESTED_STATE} — stream is already resumed
   * - {@link Errors.RESUME_STREAM_FAILED} — server rejected the resume request
   */
  resume(): Promise<void>;

  /**
   * - This method can be used to pause the stream for a remote participant.
   *
   * @throws
   * - {@link Errors.ERROR_ACTION_PERFORMED_BEFORE_MEETING_JOINED} — called before meeting is joined
   * - {@link Errors.ERROR_MEETING_RECONNECTING} — meeting is reconnecting
   * - {@link Errors.ERROR_ACTION_NOT_SUPPORTED} — stream has no active consumer (also thrown on a local stream)
   * - {@link Errors.ERROR_ALREADY_IN_REQUESTED_STATE} — stream is already paused
   * - {@link Errors.PAUSE_STREAM_FAILED} — server rejected the pause request
   */
  pause(): Promise<void>;

  /**
   * Registers an event listener.
   * @param eventType Event name to which you want to subscribe.
   * @param listener A callback function that is executed when the specified event is emitted.
   *
   * To view the complete list of available events and their details, refer to {@link StreamEvent}.
   *
   * @throws
   * - {@link Errors.ERROR_INVALID_PARAMETER} — unsupported event name
   */
  on(eventType: "state", listener: (data: any) => void): void;

  /**
   * Removes an event listener that was previously registered.
   *
   * @param eventType Event name to which you want to unsubscribe.
   * @param listener Callback function which was passed while subscribing to the event.
   *
   * To view the complete list of available events and their details, refer to  {@link StreamEvent}.
   *
   * @throws
   * - {@link Errors.ERROR_INVALID_PARAMETER} — unsupported event name
   */
  off(eventType: "state", listener: (data: any) => void): void;
}

export type StreamEvent = {
  /**
   * @event
   *
   * - Triggered when the state of a video or screen-share stream changes.
   *
   * - This event helps track whether the stream is active, stuck, frozen,recovered, or ended.
   *
   * > **Note**
   * >
   * > This event is emitted **only for remote participants** and applies
   * > specifically to **video and screen-share streams**.
   *
   * @param data
   *
   * @param data.state
   * The current state of the stream:
   *
   * - `"active"` — The stream is functioning normally.
   * - `"stuck"` — The stream is no longer progressing as expected.
   * - `"freeze-detected"` — A freeze in the video stream has been detected.
   * - `"freeze-resolved"` — The previously detected freeze has been resolved.
   * - `"ended"` — The stream has ended.
   *
   * @param data.timestamp
   * Timestamp (in milliseconds since epoch) indicating when the state change occurred.
   *
   * @example
   * ```ts
   * stream.on("state", ({ state, timestamp }) => {
   *   // Handle stream state changes
   * });
   * ```
   * @returns
   */
  state: (data: {
    state: string;
    timestamp: number;
  }) => void;
};