avcon-sdk-srs/index.d.ts

Avcon SRS SDK

export interface ISdkConfig {
  schema: 'https' | 'http';
  httpApiPort: number;
  httpsApiPort: number;
  publishApi: string;
  playApi: string;
}

export enum RTCInstanceStatus {
  /** RTC 待机中 */
  Pendding = 1,
  /** RTC 连接中 */
  Connecting = 2,
  /** RTC 已连接 */
  Connected = 3,
  /** RTC 已断开 */
  Disconnected = 4,
}

/**
 * AvconSrsSdkBase类是WebRTC连接的基础类，提供了初始化设置、关闭连接、设置和获取媒体流约束、获取WebRTC统计信息等功能
 */
declare class AvconSrsSdkBase {
  // 媒体流约束条件
  constraints: MediaStreamConstraints;
  // WebRTC实例状态
  status: RTCInstanceStatus;
  // RTCPeerConnection实例，用于管理对等连接
  RTCPeerConnection: RTCPeerConnection | null;
  // 媒体流
  stream: MediaStream;
  // 音频发送器
  audioSender: RTCRtpSender | null;
  // 视频发送器
  videoSender: RTCRtpSender | null;

  /**
   * 初始化WebRTC连接
   */
  init(): void;

  /**
   * 关闭WebRTC连接
   */
  close(): void;

  /**
   * 设置媒体流约束条件
   * @param constraints 媒体流约束条件
   */
  setConstraints(constraints: MediaStreamConstraints): void;

  /**
   * 获取WebRTC统计信息
   * @param selector 可选的MediaStreamTrack，用于筛选统计信息
   * @returns Promise，解析为RTCStatsReport对象
   */
  getWebRTCStats(selector?: MediaStreamTrack | null): Promise<RTCStatsReport>;

  /**
   * 获取当前的媒体流约束条件
   * @returns MediaStreamConstraints对象
   */
  getConstraints(): MediaStreamConstraints;

  /**
   * 获取WebRTC实例的状态
   * @returns RTCInstanceStatus对象
   */
  getStatus(): RTCInstanceStatus;

  /**
   * 设置并获取RTC描述，包括媒体流信息和对等连接信息
   * @param streamUrl 流媒体URL
   * @param defaultApi SRS信令接口API地址
   * @returns 返回一个Promise对象，解析为 session。
   */
  setRTCDescription(streamUrl: string, defaultApi: string): Promise<any>;
}

/**
 * 发布者，用于发布媒体流
 */
declare class SrsPublisher extends AvconSrsSdkBase {
  /**
   * 发布媒体流到指定URL
   * @param url 媒体服务器的URL
   * @param constraints 媒体流的约束条件，如音频、视频的设置，该参数会修改整个publisher的约束条件
   * @param contentHint 可选，默认“detail”，视频优先保证清晰度，“motion”视频优先保证流畅性
   * @returns 返回一个Promise，解析为MediaStream对象
   */
  async publish(url: string, constraints?: MediaStreamConstraints, contentHint?: 'detail' | 'motion'): Promise<MediaStream>;
  
  /**
   * 关闭音频轨道，停止音频采集
   */
  closeAudio(): void;

  /**
   * 关闭视频轨道，停止视频采集
   */
  closeVideo(): void;

  /**
   * 打开音频轨道，开始音频采集
   */
  openAudio(): void;

  /**
   * 打开视频轨道，开始视频采集
   */
  openVideo(): void;

  /**
   * 更换音频轨道
   * @param newTrack 新的音频轨道
   * @returns 返回一个Promise
   */
  async changeAudioTrack(newTrack: MediaStreamTrack): Promise<void>;

  /**
   * 更换视频轨道
   * @param newTrack 新的视频轨道
   * @returns 返回一个Promise
   */
  async changeVideoTrack(newTrack: MediaStreamTrack): Promise<void>;

  /**
   * 重新发布视频流
   * 
   * 该方法会根据publisher设置的约束条件重新获取设备的视频轨道，并替换已有的视频轨道
   * 
   * @returns 返回一个Promise
   */
  async rePublishVideo(): Promise<void>;
}

/**
 * 屏幕分享发布者，用于发布屏幕共享媒体流
 */
declare class SrsScreenPublisher extends AvconSrsSdkBase {
  /**
   * 将屏幕内容发布到指定的URL
   * 
   * @param url 发布的目标URL，通常是一个流媒体服务器地址
   * @param constraints 可选的媒体流约束条件，用于指定音频、视频的采集参数
   * @returns 返回一个 Promise，解析为 MediaStream 对象，表示发布的媒体流
   */
  publish(url: string, constraints?: MediaStreamConstraints): Promise<MediaStream>;
}

/**
 * 播放器，用于播放媒体流
 */
declare class SrsPlayer extends AvconSrsSdkBase {
  /**
   * webRTC拉流方法，指定URL，从srs流媒体器拉取音视频流。
   * @param url 流媒体的URL，不能为空。
   * @returns 返回一个Promise对象，解析为 session。
   */
  async play(url: string): Promise<{ session: string }>;
}

declare class AcvconSrsSdk {
  private sdkConfig: ISdkConfig;

  /**
   * 设置SDK配置
   * 该方法通过传递一个对象来更新SDK的配置这个对象只需要包含需要更新的配置属性
   * 
   * @param sdkConfig - 一个部分或全部配置属性的对象，用于更新SDK的配置
   *                    未提供的属性将不会改变当前的配置
   */
  setConfig(sdkConfig: Partial<ISdkConfig>): void;

  /**
   * 获取SDK配置
   * 此方法用于获取当前SDK的配置信息，该配置信息是SDK运行所必需的
   * 它包括但不限于API密钥、服务端地址等关键信息
   * 
   * @returns {ISdkConfig} 返回一个ISdkConfig接口类型的对象，该对象包含了SDK的配置信息
   */
  getConfig(): ISdkConfig;

  /**
   * 创建一个SrsPublisher发布者实例
   * 
   * 根据指定的媒体流约束条件，创建一个用于发布媒体流的SrsPublisher实例
   * 这个函数主要负责根据约束条件获取媒体流，并初始化一个SrsPublisher实例用于后续的媒体流发布
   * 
   * @param constraints 可选的媒体流约束条件，用于指定所需媒体流的特性，如音频、视频等
   * @returns 返回一个SrsPublisher实例，用于进行媒体流的发布
   */
  createPublisher(constraints?: MediaStreamConstraints): SrsPublisher;

  /**
   * 创建一个屏幕发布者实例，用于屏幕共享或屏幕捕获
   * 
   * 根据指定的媒体流约束条件，创建一个用于发布媒体流的SrsScreenPublisher实例
   * 这个函数主要负责根据约束条件获取媒体流，并初始化一个SrsScreenPublisher实例用于后续的媒体流发布
   * 
   * @param constraints 可选的媒体流约束条件，用于指定所需的媒体轨道特性
   * @returns 返回一个SrsScreenPublisher实例，用于进行屏幕共享操作
   */
  createScreenPublisher(constraints?: MediaStreamConstraints): SrsScreenPublisher;

  /**
   * 创建并返回一个SrsPlayer实例
   * 
   * SrsPlayer是一种媒体播放器的实现，该函数用于实例化这种播放器对象
   * 它不接受任何参数，且返回值为SrsPlayer类型
   */
  createPlayer(): SrsPlayer;
}

/**
 * 音视频SDK
 */
export default {} as AcvconSrsSdk;