@tencentcloud/sdk-mcp 1.3.4 → 1.3.6

package/resource/doc/rtcengine/web/plugin/22-advanced-audio-mixer.md

@@ -0,0 +1,220 @@
+## 功能描述
+
+本文将介绍如何在通话过程中增加背景音乐的功能，点击 [体验 demo](https://web.sdk.qcloud.com/trtc/webrtc/demo/api-sample/improve-audio-mixer.html?roomID=43222) 进行体验。
+
+## 前提条件
+
+- TRTC 版本 > 5.1.0
+- 支持在通话中添加背景音乐的平台如下
+
+  |  操作系统   | 浏览器类型            | 浏览器最低版本要求 |
+  |:-------:|:-----------------|:---------:|
+  | Mac OS  | 桌面版 Chrome 浏览器   |    56+    |
+  | Mac OS  | 桌面版 Safari 浏览器   |    11+    |
+  | Mac OS  | 桌面版 Firefox 浏览器  |    56+    |
+  | Mac OS  | 桌面版 Edge         |    80+    |
+  | Windows | 桌面版 Chrome 浏览器   |    56+    |
+  | Windows | 桌面版 QQ 浏览器（极速模式） |   10.4+   |
+  | Windows | 桌面版 Firefox 浏览器  |    56+    |
+  | Windows | 桌面版 Edge         |    80+    |
+  |   iOS   | 移动版 Safari 浏览器   |    14+    |
+  |   iOS   | 微信内嵌网页           |     ✖     |
+  | Android | 移动版 Chrome 浏览器   |    81+    |
+  | Android | 微信内嵌网页(TBS 内核)   |     ✔     |
+  | Android | 移动版 QQ 浏览器       |     ✖     |
+
+## 实现流程
+
+### 1. 进房并打开麦克风
+
+```js
+const trtc = TRTC.create();
+await trtc.enterRoom({ roomId: 8888, sdkAppId, userId, userSig });
+await trtc.startLocalAudio();
+```
+
+### 2. 开启一首背景音乐
+
+如开启 `../assets/count.mp3`，使用 `trtc.startPlugin` 方法，将其 id 设置为 `count`，后续操作这个 id 即操作这个音乐。
+
+```javascript
+await trtc.startPlugin('AudioMixer', {
+  id: 'count',
+  url: '../assets/count.mp3'
+})
+```
+
+除此之外还可以传入 loop、volume、事件监听等参数，详见后文 API 说明部分。
+
+### 3. 按需更新背景音乐
+
+如果需要对音乐进行进一步操作，可以根据上一步注册的音乐 id，调用 `trtc.updatePlugin` 接口来进行。
+
+除 loop、volume、事件监听等参数之外，updatePlugin 还可以执行音乐暂停、恢复、跳转操作。详见后文 API 说明部分。
+
+```javascript
+// 取消循环播放
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  loop: false
+})
+// 设置音量
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  volume: 1
+})
+// 将 count 音乐暂停
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  operation: 'pause'
+})
+// 将 count 音乐恢复
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  operation: 'resume'
+})
+// 将 count 音乐从第 5s 开始播放
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  seekFrom: 5
+})
+```
+
+### 4. 关闭背景音乐
+
+注意，音乐播放一旦 start 后，无法自行 stop，因此需要此接口来关闭某个不需要使用的音乐。关闭后方可再次 start。
+
+```javascript
+await trtc.stopPlugin('AudioMixer', {
+  id: 'count'
+})
+```
+
+```js
+// bad: 连续 start 相同 id 两次
+startPlugin({ id: 'bgm1', url: './xxx.mp3' })
+startPlugin({ id: 'bgm1', url: './xxx.mp3' }) 
+
+// good: start 后用 update 
+startPlugin({ id: 'bgm1', url: './xxx.mp3' })
+updatePlugin({ id: 'bgm1' }) 
+
+// good: 可以同时开启两个背景音乐
+startPlugin({ id: 'bgm1' })
+startPlugin({ id: 'bgm2' }) 
+
+// good: stop 后下次可以正常再开启
+startPlugin({ id: 'bgm1' })
+stopPlugin({ id: 'bgm1' }) 
+startPlugin({ id: 'bgm1' }) 
+```
+
+## API 说明
+
+### trtc.startPlugin('AudioMixer', options)
+
+用于增加一个背景音乐
+
+#### options
+
+| Name   | Type      | Attributes   | Description                         |
+|--------|-----------|--------------|-------------------------------------|
+| id     | `string`  |              | 给当前传入的音乐 url 自定义一个唯一的 ID， 例如： 'bgm' |
+| url    | `string`  |              | 音乐文件地址，与下方的 track 字段必须二选一填入，若同时传入，以 url 为准                            |
+| track | `MediaStreamAudioTrack`  | | 自 v5.4.3+ 支持，与 url 二选一，可以传入从 `<audio/>` 标签中提取的 ，若同时传入，以 url 为准                  |
+| loop   | `boolean` | `<optional>` | 是否循环播放，默认为 false                     |
+| volume | `number`  | `<optional>` | 设置初始音量，默认为 1 (0-1)。暂不支持 iOS。               |
+| playbackRate | `number`  | `<optional>` | 设置播放速率，默认为 1.0                  |
+| onDurationChange | `function`  | `<optional>` | 回调函数，音乐加载完会执行，参数为 (duration: number) 标识音乐总时长 |
+| onTimeUpdate | `function`  | `<optional>` | 回调函数，音乐播放过程中会持续触发，参数为 (currentTime: number, duration: number) 标识音乐当前进度和总时长 |
+| onEnded | `function`  | `<optional>` | 回调函数，音乐结束会执行（注意 loop 时每次播放到音乐末尾不会执行），无参数 |
+
+**Example:**
+
+```javascript
+await trtc.startPlugin('AudioMixer', {
+  id: 'count',
+  url: '../assets/count.mp3',
+  loop: true,
+  volume: 0.2,
+  playbackRate: 1.5
+})
+```
+
+使用回调：
+
+```js
+await trtc.startPlugin('AudioMixer', {
+  id: 'wow',
+  url: '../assets/music/wow.mp3',
+  onDurationChange: (duration) => {
+    console.warn(`duration: ${duration}`);
+  },
+  onTimeUpdate: (currentTime, duration) => {
+    console.warn(`currentTime/duration: ${currentTime}/${duration}`);
+  },
+  onEnded: () => {
+    console.warn('ended');
+  }
+});
+```
+
+### trtc.updatePlugin('AudioMixer', options)
+
+#### options
+
+| Name      | Type      | Attributes   | Description                           |
+|-----------|-----------|--------------|---------------------------------------|
+| id        | `string`  |              | 调用 startPlugin 时定义的背景音乐文件的 ID         |
+| loop      | `boolean` | `<optional>` | 是否循环播放，默认为false                       |
+| volume    | `number`  | `<optional>` | 设置初始音量，默认为1 (0-1)                     |
+| seekFrom  | `number`  | `<optional>` | 从第几秒开始 seek 播放，此功能需要背景音乐资源文件的请求支持[范围请求](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Range_requests)                        |
+| operation | `number`  | `<optional>` | 对背景音乐的操作: 'pause' ｜ 'resume' ｜ 'stop' |
+| playbackRate | `number`  | `<optional>` | 设置播放速率，默认为 1.0                  |
+| onDurationChange | `function`  | `<optional>` | 回调函数，音乐加载完会执行，参数为 (duration: number) 标识音乐总时长 |
+| onTimeUpdate | `function`  | `<optional>` | 回调函数，音乐播放过程中会持续触发，参数为 (currentTime: number, duration: number) 标识音乐当前进度和总时长 |
+| onEnded | `function`  | `<optional>` | 回调函数，音乐结束会执行（注意 loop 时每次播放到音乐末尾不会执行），无参数 |
+
+**Example:**
+
+```javascript
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  loop: true,
+  volume: 0.2,
+  operation: 'pause'
+})
+```
+
+### trtc.stopPlugin('AudioMixer', options)
+
+关闭某个背景音乐。
+
+#### options
+
+| Name      | Type      | Attributes   | Description                   |
+|-----------|-----------|--------------|-------------------------------|
+| id        | `string`  |              | 调用 startPlugin 时定义的背景音乐文件的 ID |
+
+**Example:**
+
+```javascript
+await trtc.stopPlugin('AudioMixer', {
+  id: 'count'
+})
+```
+
+## 常见问题
+
+**1. 出现跨域错误**
+
+例如：Access to audio at XXX from origin XXX has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is
+present on the requested resource.
+
+解决：您需要配置线上音乐文件的 CORS 协议。
+
+**2. 音频格式不对，浏览器无法播放**
+
+例如：NotSupportedError: The operation is not supported.
+
+解决：您需要使用浏览器支持的音频格式。

package/resource/doc/rtcengine/web/plugin/23-advanced-support-detection.md

@@ -0,0 +1,217 @@
+## 浏览器环境检测
+
+在开始音视频通话之前，建议您先使用 {@link TRTC.isSupported TRTC.isSupported} 接口检测 SDK 是否支持当前网页。如果 SDK 不支持当前浏览器，建议用户使用最新版的 Chrome 浏览器、Edge 浏览器、Safari 浏览器、Firefox 浏览器。
+
+```javascript
+TRTC.isSupported().then(checkResult => {
+  // 不支持使用 SDK，引导用户使用最新版的 Chrome 浏览器。
+  if (!checkResult.result) {}
+  // 不支持发布视频
+  if (!checkResult.detail.isH264EncodeSupported) {}
+  // 不支持拉视频
+  if (!checkResult.detail.isH264DecodeSupported) {}
+})
+```
+
+⚠️ `TRTC.isSupported` 返回的检测结果为 false 时，可能是以下原因：
+
+1. 网页使用了 http 协议。浏览器不允许 http 协议的网站采集摄像头和麦克风，您需要使用 https 协议部署您的网页。
+2. 当前浏览器不支持 WebRTC 相关能力，您需要引导用户使用推荐的浏览器 {@tutorial 05-info-browser}
+3. Firefox 浏览器安装完成后需要动态加载 H264 编解码器，因此会出现短暂的检测结果为 false 的情况，请稍等再试或引导使用其他浏览器。
+
+## 通话前设备检测
+
+### 方案一：使用设备检测插件（包括默认 UI）
+
+检测用户的媒体设备（摄像头、麦克风、扬声器）以及网络，建议在用户进房之前使用，支持移动端适配。
+
+> - 该插件需要：TRTC Web SDK 版本 >= 5.8.0。
+> - 该插件包括默认的 UI，若 UI 不符合您的产品设计需求，可以参考方案二自定义 UI 实现。
+
+#### 实现流程
+
+```javascript
+import { DeviceDetector } from 'trtc-sdk-v5/plugins/device-detector';
+const trtc = TRTC.create({ plugins: [DeviceDetector] });
+
+// 1. Test Media Device Only
+const result = await trtc.startPlugin('DeviceDetector');
+
+// 2. Test Media Device & Network Quality
+const options = { 
+    networkDetect: { sdkAppId, userId, userSig }
+}
+const resultWithNetwork = await trtc.startPlugin('DeviceDetector', options);
+```
+
+#### API
+
+##### trtc.startPlugin('DeviceDetector', options)
+
+第一个参数为'DeviceDetector'字符串，用于开启设备检测插件。
+
+##### options
+
+| Name            | Type   | Attributes | Description                                                  |
+| --------------- | ------ | ---------- | ------------------------------------------------------------ |
+| language       | 'auto' \| 'zh' \| 'en' | 选填        | 选填。设置 UI 的语言，支持中文和英文。默认为 'auto'，表示根据当前浏览器语言自动判断。'zh' 表示使用中文, 'en' 表示使用英文。|
+| allowSkip       | boolean | 选填        | 选填。默认为 true，会显示跳过按钮。若为 false，则不显示跳过按钮，用户必须完成每一步检测才能进行下一步。|
+| cameraDetect    | object  | 选填        | 选填。摄像头检测选项，详见下文 cameraDetect 选项|
+| networkDetect   | object  | 选填        | 选填。网络检测选项，详见下文 networkDetect 选项|
+
+###### options.cameraDetect(optional)
+| Name            | Type   | Attributes | Description                                                  |
+| --------------- | ------ | ---------- | ------------------------------------------------------------ |
+| mirror          | boolean | 选填        | 选填。为true时，在摄像头检测环节会开启画面镜像，并显示镜像画面的复选框 |
+
+###### options.networkDetect(optional)
+
+| Name            | Type   | Attributes | Description                                                  |
+| --------------- | ------ | ---------- | ------------------------------------------------------------ |
+| sdkAppId        | string | 必填       | 从控制台获得，你的sdkAppId                                   |
+| userId          | string | 必填       | 上行用户ID, 自行决定，与downlinkUserId不一致，与用于生成userSig的userId一致 |
+| userSig         | string | 必填       | userSig 签名，由sdkAppId，userId，sdkSecretKey作为参数生成，生产环境由向服务器请求生成，参考：[UserSig](https://trtc.io/document/35166) |
+| downlinkUserId  | string | 选填       | 下行用户ID, 自行决定，与userId不一致，与用于生成downlinkUserSig的userId一致。填写 downlinkUserId 和 downlinkUserSig将进行下行网络测试 |
+| downlinkUserSig | string | 选填       | userSig 签名，由sdkAppId，downlinkUserId，sdkSecretKey作为参数生成，生产环境由向服务器请求生成，参考：[UserSig](https://trtc.io/document/35166) |
+| roomId          | number | 选填       | 选填，默认为8080，数字类型的房间号，取值要求为 [1, 4294967294] 的整数 |
+
+##### startPlugin 返回结果
+
+| Name           | Type     | Description                                                  |
+| -------------- | -------- | ------------------------------------------------------------ |
+| **camera**     | `object` | { isSuccess: boolean, device: { deviceId: string, groupId: string, kind: "videoinput", label: string }} |
+| **microphone** | `object` | { isSuccess: boolean, device: { deviceId: string, groupId: string, kind: "audioinput", label: string }} |
+| **speaker**    | `object` | { isSuccess: boolean, device: { deviceId: string, groupId: string, kind: "audiooutput", label: string }} |
+| **network**    | `object` | 网络检测结果(startPlugin传入networkDetect才检测返回)<br />{ isSuccess: boolean, result: { quality: number , rtt: number}} <br />quality为网络质量，默认为上行网络质量，传入下行userId和userSig时为上下行网络质量中较差值<br />**网络质量**<br />0：网络状况未知，表示当前 TRTC 实例还没有建立上行/下行连接 <br />1：网络状况极佳 <br />2：网络状况较好 <br />3：网络状况一般 <br />4：网络状况差 <br />5：网络状况极差 <br />6：网络连接已断开 注意：若下行网络质量为此值，则表示所有下行连接都断开了 |
+
+#### 插件 Demo
+
+<iframe allow="microphone; camera; display-capture;" height="700" style="width:100%" scrolling="no" title="Device Detector" src="https://codepen.io/TRTC/embed/eYwVVja?default-tab=" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+  See the Pen <a href="https://codepen.io/TRTC/pen/eYwVVja">
+  Device Detector</a> by TRTC (<a href="https://codepen.io/TRTC">@TRTC</a>)
+  on <a href="https://codepen.io">CodePen</a>.
+</iframe>
+
+### 方案二：基于 SDK API 自行实现设备检测（自定义 UI）
+
+若方案一的设备检测插件的默认 UI 不符合您的需求，你可以选择方案二来自定义 UI。
+
+#### 1. 检查设备权限
+
+从 v5.13.0+ 开始，SDK 提供了 `TRTC.getPermissions` 接口，用于检查、请求和监听设备权限。
+
+```javascript
+const { camera, microphone } = await TRTC.getPermissions({
+  request: true, // 如果为 true，调用该接口可能会短暂打开摄像头来获取摄像头权限，以保证正常获取摄像头列表，随后 SDK 会自动释放采集。
+  types: ['camera', 'microphone'] // 请求获取的设备类型。
+});
+console.log(camera, microphone); // 'granted' | 'denied' | 'prompt' | null. null 表示不支持查询。
+
+// 监听设备权限变化
+trtc.on(TRTC.EVENT.PERMISSION_STATE_CHANGE, event => {
+  console.log(event.camera, event.microphone);
+});
+// 释放监听
+trtc.off(TRTC.EVENT.PERMISSION_STATE_CHANGE);
+```
+
+#### 2. 设备连接
+
+设备连接的目的是检测用户使用的机器是否有摄像头、麦克风或扬声器，是否在联网状态。如果有摄像头，麦克风或扬声器设备，尝试获取音视频流并引导用户授予摄像头，麦克风的访问权限。
+
++ 判断设备是否有摄像头，麦克风或扬声器
+
+  ```javascript
+  import TRTC from 'trtc-sdk-v5';
+  
+  const cameraList = await TRTC.getCameraList();
+  const micList = await TRTC.getMicrophoneList();
+  const hasCameraDevice = cameraList.some(camera => camera.deviceId !== '');
+  const hasMicrophoneDevice = micList.some(mic => mic.deviceId !== '');
+  // 移动端设备不支持获取扬声器设备，移动端检测扬声器可以不获取扬声器
+  const speakerList = await TRTC.getSpeakerList();
+  const hasSpeakerDevice = speakerList.some(speaker => speaker.deviceId !== '');
+  ```
+
+#### 3. 摄像头检测
+
+​检测原理：打开摄像头，并在页面中渲染摄像头画面。您可以在页面中提供 2 个按钮，让用户确认是否能看到摄像头画面。
+
++ 打开摄像头
+
+  ```javascript
+  trtc.startLocalVideo({ view: 'camera-video', publish: false });
+  ```
+
++ 切换摄像头
+
+  ```javascript
+  trtc.updateLocalVideo({ option: { cameraId } });
+  ```
+
++ 检测完成后关闭摄像头
+
+  ```javascript
+  trtc.stopLocalVideo();
+  ```
+
+#### 4. 麦克风检测
+
+​检测原理：打开麦克风，并获取麦克风音量。监听麦克风音量事件，并将实时音量渲染到页面中，引导用户说话，确认是否能看到音量条变化。
+
++ 打开麦克风
+
+  ```javascript
+  trtc.on(TRTC.EVENT.AUDIO_VOLUME, event => {
+    event.result.forEach(({ userId, volume }) => {
+        const isMe = userId === ''; // 当 userId 为空串时，代表本地麦克风音量。
+        if (isMe) {
+            console.log(`my volume: ${volume}`);
+            // 将麦克风音量渲染到页面中
+        }
+    })
+  });
+  // 开启音量回调，并设置每 200ms 触发一次事件
+  trtc.enableAudioVolumeEvaluation(200);
+  trtc.startLocalAudio({ publish: false });
+  ```
+
++ 切换麦克风
+
+  ```javascript
+  trtc.updateLocalAudio({ option: { microphoneId }});
+  ```
+
++ 检测完成后释放麦克风占用
+
+  ```javascript
+  trtc.stopLocalAudio();
+  ```
+
+#### 5. 扬声器检测
+
+​	检测原理：通过 audio 标签播放一个 mp3 媒体文件
+
++ 创建 audio 标签，提醒用户调高播放音量，播放 mp3 确认扬声器设备是否正常。
+
+  ```html
+  <audio id="audio-player" src="xxxxx" controls></audio>
+  ```
+
++ 检测结束后停止播放
+
+  ```javascript
+  const audioPlayer = document.getElementById('audio-player');
+  if (!audioPlayer.paused) {
+      audioPlayer.pause();
+  }
+  audioPlayer.currentTime = 0;
+  ```
+
+#### 6. 网络检测
+
+参考：[通话前的网络质量检测](./tutorial-24-advanced-network-quality.html)
+
+## TRTC 能力检测页面
+
+您可以在当前使用 TRTC SDK 的地方，使用 [TRTC 检测页面](https://web.sdk.qcloud.com/trtc/webrtc/demo/detect/index.html) ，可用于探测当前环境，还可以点击生成报告按钮，得到当前环境的报告，用于环境检测，或者问题排查。

package/resource/doc/rtcengine/web/plugin/24-advanced-network-quality.md

@@ -0,0 +1,137 @@
+在进房之前或在通话过程中，检测用户的网络质量，可以判断用户当下的网络质量情况。若用户网络质量太差，应建议用户检查网络或尝试更换网络，以保证正常通话质量。
+
+本文主要介绍如何基于 [NETWORK_QUALITY](./module-EVENT.html#.NETWORK_QUALITY) 事件实现通话过程及通话前网络质量检测。
+
+## 通话过程中的网络质量检测
+
+参考： {@link module:EVENT.NETWORK_QUALITY NETWORK_QUALITY}
+
+```js
+const trtc = TRTC.create();
+trtc.on(TRTC.EVENT.NETWORK_QUALITY, event => {
+   console.log(`network-quality, uplinkNetworkQuality:${event.uplinkNetworkQuality}, downlinkNetworkQuality: ${event.downlinkNetworkQuality}`)
+   console.log(`uplink rtt:${event.uplinkRTT} loss:${event.uplinkLoss}`)
+   console.log(`downlink rtt:${event.downlinkRTT} loss:${event.downlinkLoss}`)
+})
+```
+
+## 通话前的网络质量检测
+
+通话前的网络质量检测需要借助 {@link module:EVENT.NETWORK_QUALITY NETWORK_QUALITY} 事件实现。
+
+### 实现流程
+
+1. 调用 [TRTC.create](./TRTC.html#.createTRTC) 创建两个 trtc 对象，分别称为 uplinkTRTC 和 downlinkTRTC。
+2. 这两个 TRTC 都进入同一个房间。
+3. 使用 uplinkTRTC 进行推流，监听 [NETWORK_QUALITY](./module-EVENT.html#.NETWORK_QUALITY) 事件来检测上行网络质量。
+4. 使用 downlinkTRTC 进行拉流，监听 [NETWORK_QUALITY](./module-EVENT.html#.NETWORK_QUALITY) 事件来检测下行网络质量。
+5. 整个过程可持续 15s 左右，最后取平均网络质量，从而大致判断出上下行网络情况。
+
+> !
+> - 检测过程将产生少量的[基础服务费用](https://cloud.tencent.com/document/product/647/17157#.E5.9F.BA.E7.A1.80.E6.9C.8D.E5.8A.A1)。如果未指定推流分辨率，则默认以 640*480 的分辨率推流。
+
+### API 调用时序
+
+![network-quality-call-sequence](./assets/network-quality-call-sequence.png)
+
+### 代码示例
+
+```js
+let uplinkTRTC = null; // 用于检测上行网络质量
+let downlinkTRTC = null; // 用于检测下行网络质量
+let localStream = null; // 用于测试的流
+let testResult = {
+  // 记录上行网络质量数据
+  uplinkNetworkQualities: [],
+  // 记录下行网络质量数据
+  downlinkNetworkQualities: [],
+  average: {
+    uplinkNetworkQuality: 0,
+    downlinkNetworkQuality: 0
+  }
+}
+
+// 1. 检测上行网络质量
+async function testUplinkNetworkQuality() {
+  uplinkTRTC = TRTC.create();
+
+  uplinkTRTC.enterRoom({
+    roomId: 8080,
+    sdkAppId: 0, // 填写 sdkAppId
+    userId: 'user_uplink_test',
+    userSig: '', // uplink_test 的 userSig
+    scene: 'rtc'
+  })
+
+  uplinkTRTC.on(TRTC.EVENT.NETWORK_QUALITY, event => {
+    const { uplinkNetworkQuality } = event;
+    testResult.uplinkNetworkQualities.push(uplinkNetworkQuality);
+  });
+
+  uplinkTRTC.startLocalVideo();
+}
+
+// 2. 检测下行网络质量
+async function testDownlinkNetworkQuality() {
+  downlinkTRTC = TRTC.create();
+  downlinkTRTC.enterRoom({
+    roomId: 8080,
+    sdkAppId: 0, // 填写 sdkAppId
+    userId: 'user_downlink_test',
+    userSig: '', // userSig
+    scene: 'rtc',
+    autoReceiveVideo: true
+  });
+
+  downlinkTRTC.on(TRTC.EVENT.NETWORK_QUALITY, event => {
+    const { downlinkNetworkQuality } = event;
+    testResult.downlinkNetworkQualities.push(downlinkNetworkQuality);
+  })
+}
+
+// 3. 开始检测
+testUplinkNetworkQuality();
+testDownlinkNetworkQuality();
+
+// 4. 15s 后停止检测，计算平均网络质量
+setTimeout(() => {
+  // 计算上行平均网络质量
+  const validUplinkNetworkQualitiesList = testResult.uplinkNetworkQualities.filter(value => value >= 1 && value <= 5);
+  if (validUplinkNetworkQualitiesList.length > 0) {
+    testResult.average.uplinkNetworkQuality = Math.ceil(
+      validUplinkNetworkQualitiesList.reduce((value, current) => value + current, 0) / validUplinkNetworkQualitiesList.length
+    );
+  }
+  
+  const validDownlinkNetworkQualitiesList = testResult.uplinkNetworkQualities.filter(value => value >= 1 && value <= 5);
+  if (validDownlinkNetworkQualitiesList.length > 0) {
+    // 计算下行平均网络质量
+    testResult.average.downlinkNetworkQuality = Math.ceil(
+      validDownlinkNetworkQualitiesList.reduce((value, current) => value + current, 0) / validDownlinkNetworkQualitiesList.length
+    );
+  }
+    
+  // 检测结束，清理相关状态。
+  uplinkTRTC.exitRoom();
+  downlinkTRTC.exitRoom();
+}, 15 * 1000);
+```
+
+## 结果分析
+
+经过上述步骤，可以拿到上行平均网络质量、下行平均网络质量。网络质量的枚举值如下所示：
+
+| 数值 | 含义                                                         |
+| :--- | :----------------------------------------------------------- |
+| 0    | 网络状况未知，表示当前 TRTC 实例还没有建立上行/下行连接    |
+| 1    | 网络状况极佳                                                 |
+| 2    | 网络状况较好                                                 |
+| 3    | 网络状况一般                                                 |
+| 4    | 网络状况差                                                   |
+| 5    | 网络状况极差                                                 |
+| 6    | 网络连接已断开 注意：若下行网络质量为此值，则表示所有下行连接都断开了 |
+
+> 建议：当网络质量大于3时，应引导用户检查网络并尝试更换网络环境，否则难以保证正常的音视频通话。
+> 也可通过下述策略来降低带宽消耗：
+> - 若上行网络质量大于3，则可通过 [TRTC.updateLocalVideo()](./TRTC.html#updateLocalVideo) 接口降低码率 或 [TRTC.stopLocalVideo()](./TRTC.html#stopLocalVideo) 方式关闭视频，以降低上行带宽消耗。
+> - 若下行网络质量大于3，则可通过订阅小流（参考：[开启大小流传输](./tutorial-27-advanced-small-stream.html)）或者只订阅音频的方式，以降低下行带宽消耗。

package/resource/doc/rtcengine/web/plugin/25-advanced-device-change.md

@@ -0,0 +1,97 @@
+## 功能描述
+
+本文主要介绍如何检测用户的设备插入、拔出、启动的行为。以及如何处理设备采集异常。
+
+> **关于 SDK 自动恢复采集**<br>
+> SDK 会检测摄像头、麦克风的插拔行为，并在恰当时机，自动恢复采集。具体逻辑如下：
+> 1. 若当前正在推流的摄像头/麦克风被拔出，SDK 会尝试使用剩余可用的媒体设备，恢复采集。
+> 2. 若摄像头/麦克风被拔出后，没有可用的媒体设备。SDK 会检测设备插入行为，若插入了新的可用的媒体设备，SDK 会尝试使用新插入的媒体设备，恢复采集并推流。
+> 3. 若恢复失败，则会抛出错误 [TRTC.ERROR_CODE.DEVICE_ERROR](./module-ERROR_CODE.html#.DEVICE_ERROR)，extraCode 为 5308，5309。
+
+
+## 实现流程
+
+### 检测设备插入、拔出、启动
+
+```js
+trtc.on(TRTC.EVENT.DEVICE_CHANGED, (event) => {
+  // 设备插入
+  if (event.action === 'add') {
+    // 摄像头插入
+    if (event.type === 'camera') {}
+  } else if (event.action === 'remove') {
+    // 设备拔出
+  } else if (event.action === 'active') {
+    // 设备启动
+  }
+  console.log(`${event.type}(${event.device.label}) ${event.action}`);
+});
+```
+
+### 判断是否当前正在使用的设备被拔出
+
+```js
+trtc.on(TRTC.EVENT.DEVICE_CHANGED, (event) => {
+  if (event.action === 'remove') {
+    if (event.type === 'camera') {
+      const currentCameraId = trtc.getVideoTrack()?.getSettings()?.deviceId;
+      if (event.device.deviceId === currentCameraId) {
+        // 当前正在使用的摄像头被拔出。
+      }
+    } else if (event.type === 'microphone') {
+      const currentMicId = trtc.getAudioTrack()?.getSettings()?.deviceId;
+      if (event.device.deviceId === currentMicId) {
+        // 当前正在使用的麦克风被拔出。
+      }
+    }
+  }
+});
+```
+
+### 在用户插入新设备时，自动切换到使用新设备。
+
+```js
+trtc.on(TRTC.EVENT.DEVICE_CHANGED, (event) => {
+  if (event.action === 'add') {
+    if (event.type === 'camera') {
+      // 插入摄像头后，自动切换到新的摄像头
+      trtc.updateLocalVideo({ option: { cameraId: event.device.deviceId }});
+    }
+  }
+});
+```
+
+### 处理设备采集异常
+
+监听设备采集异常事件
+
+```js
+trtc.on(TRTC.EVENT.VIDEO_PLAY_STATE_CHANGED, event => {
+  // 本地摄像头采集异常，此时 SDK 会尝试自动恢复采集，您可以引导用户检查摄像头是否正常。
+  if (event.userId === '' && event.streamType === TRTC.TYPE.STREAM_TYPE_MAIN && (event.reason === 'mute' || event.reason === 'ended')) {}
+});
+
+trtc.on(TRTC.EVENT.AUDIO_PLAY_STATE_CHANGED, event => {
+  // 本地麦克风采集异常，此时 SDK 会尝试自动恢复采集，您可以引导用户检查麦克风是否正常。
+  if (event.userId === '' && (event.reason === 'mute' || event.reason === 'ended')) {}
+});
+```
+
+监听 SDK 自动恢复采集失败事件
+```js
+trtc.on(TRTC.EVENT.ERROR, error => {
+  if (error.code === TRTC.ERROR_CODE.DEVICE_ERROR) {
+    // 摄像头恢复采集失败
+    if (error.extraCode === 5308) {
+      // 引导用户检查设备后，调用 updateLocalVideo 传入 cameraId 重新采集。
+      trtc.updateLocalVideo({ option: { cameraId: '' }});
+    }
+
+    // 麦克风恢复采集失败
+    if (error.extraCode === 5309) {
+      // 引导用户检查设备后，调用 updateLocalAudio 传入 microphoneId 重新采集。
+      trtc.updateLocalAudio({ option: { microphoneId: '' }});
+    }
+  }
+})
+```