yao-test-npm v1.0.0

产品介绍

TODO

接口说明

引入 SDK

SDK 提供了两种引入方式，可以直接下载 JS 文件，也可以通过 npm 完成引入。

1. npm 引入

首先使用 npm 来将 SDK 安装到项目中。

npm install --save qn-rtplayer-web

然后在项目中使用 import 语法引入。

import { QNRTPlayer } from "qn-rtplayer-web";
const player = new QNRTPlayer();

2. 直接导入 JS 文件

每次发布版本，我们都会将最新的 SDK JS 文件放在我们的 Github 上，点击连接即可获取当前最新的 SDK JS 文件。

所以，每次想要升级版本时，只需要访问我们的 Github 页面，然后替换一下自己的 JS 文件即可。

SDK 的 JS 文件在导入页面后，会自动创建一个全局对象 QNRTPlayer，这个对象的成员包括了 SDK 所导出的所有模块和对象。

const player = new QNRTPlayer.QNRTPlayer();

快速开始

使用 SDK 非常简单，完成以下几个步骤即可。

import { QNRTPlayer } from "qn-rtplayer-web";

// 1. 创建 QNRTPlayer 对象
const player = new QNRTPlayer();

// 2. 初始化配置信息
player.init();

// 3. 传入播放地址及容器，开始播放
player.play(
  "webrtc://...",
  document.getElementById("container");
);

API 参考

init

/**
 * 传入配置对象，完成初始化配置
 * @param {Config} config - 配置对象
 */
public init(config: Config): void

其中，配置对象 Config 的结构如下：

interface Config {
  /**
   * 配置到媒体元素上的 class 值
   */
  className?: string;

  /**
   * 媒体宽度，合法的 CSS 字符串值
   */
  width?: string;

  /**
   * 媒体高度，合法的 CSS 字符串值
   */
  height?: string;

  /**
   * 合法的 CSS object-fit 值
   */
  objectFit?: string;

  /**
   * 音量 0-1 范围
   */
  volumn?: number;

  /**
   * 是否开启 video 媒体元素控制 UI
   */
  controls?: boolean;

  /**
   * opens the inline mode of ios and WeChat on the mobile phone
   * see: https://webkit.org/blog/6784/new-video-policies-for-ios/
   */
  playsinline?: boolean;
}

配置对象在 SDK 中的默认值如下：

const DEFAULT_CONFIG: Required<Config> = {
  className: 'qn-rtplayer-media',
  width: '100%',
  height: '100%',
  objectFit: 'contain',
  volumn: 0.6,
  controls: false,
  playsinline: true,
};

setConfig

在播放之后，如果想要动态修改播放器的配置信息，SDK 还提供了 setConfig 方法，传入相应修改值即可完成修改，函数签名如下。

/**
 * 修改配置
 * @param {Partial<Config>} config
 */
public setConfig(config: Partial<Config>)

getConfig

/**
 * 获取当前播放器配置信息
 * @return {Config} config
 */
public getConfig(): Config

play

在调用 init 方法之后，再调用 play 方法，即可开始播放。

/**
 * 播放
 * @param {string} url 播放地址
 * @param {HTMLElement} container 容器
 */
public async play(url: string, container: HTMLElement): Promise<void>

建议将该方法放在用户点击回调函数中，防止浏览器自动播放策略阻止播放。

pause

/**
 * 暂停
 */
public pause(): void

resume

/**
  * 恢复播放
  */
public resume(): void

hasAudio

/**
 * 是否存在音频流
 * @return {boolean}
 */
public hasAudio(): boolean

hasVideo

/**
 * 是否存在视频流
 * @return {boolean}
 */
public hasVideo(): boolean

setAudioVolume

/**
 * 设置音量
 * @param {Number} volume - 音量，范围 0-1
 */
public setAudioVolume(volume: number)

getAudioVolume

/**
 * 获取当前音量
 * @return {number | undefined} - 音量，范围 0-1
 */
public getAudioVolume(): number

muteAudio

/**
 * 静音音频
 */
public muteAudio(): void

unmuteAudio

/**
 * 取消音频静音
 */
public unmuteAudio(): void

muteVideo

/**
 * 仅播放音频，不播放视频
 */
public muteVideo(): void

unmuteVideo

/**
 * 正常播放视频
 */
public unmuteVideo(): void

isPlaying

/**
 * 当前是否处于播放状态
 * @return {boolean}
 */
public isPlaying(): boolean

stop

/**
 * 停止播放
 */
public stop(): void

release

/**
 * 释放状态
 */
public release(): void

注意，调用 release 方法之后，SDK 会清空所有状态，如果想要再次播放，需要重新调用 init 方法。

log 事件

监听 log 事件可以获取 SDK 的日志信息。

player.on('log', (data: SDKLogInfo) => {
    // ...
});

其中，SDKLogInfo 的结构如下：

interface SDKLogInfo {
  time: string;
  level: LogLevel;
  msg: string;
  id: string;
}

type LogLevel = 'disable' | 'error' | 'warning' | 'debug' | 'log';

stats 事件

监听 stats 事件，可以获得当前媒体流的状态数据。

player.on('stats', (data: StatReport) => {
  // ...
});

其中，StatReport 的结构如下：

interface StatReport {
  /**
   * 音频码率（kbps）
   */
  audioBitrate: number;

  /**
   * 视频码率（kbps）
   */
  videoBitrate: number;
}

error 事件

SDK 内部对常见的错误进行了封装，可以通过监听 error 事件获取错误信息。

当连接因网络等原因异常断开时，会触发 disconnect 事件。

player.on('error', (error: SDKError) => {
  // ...
});

其中，SDKError 的格式为：

interface SDKError {
  code: number;
  errorType: string;
  msg: string;
}

SDKError 中使用 code 与不同类型的错误做了分类，不同 code 的含义具体如下：