@tencent-rtc/mcp 1.3.3 → 1.3.5

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

@@ -0,0 +1,175 @@
+## Function Description
+
+This article will introduce how to add background music during a call. [Experience demo](https://web.sdk.qcloud.com/trtc/webrtc/demo/api-sample/improve-audio-mixer.html?roomID=43222).
+
+## Prerequisites
+
+TRTC version 5.1+
+
+The following platforms support adding background music during a call:
+
+| Operating System | Browser Type        | Minimum Browser Version |
+|------------------|---------------------|-------------------------|
+| Mac OS           | Desktop Chrome      | 56+                     |
+| Mac OS           | Desktop Safari      | 11+                     |
+| Mac OS           | Desktop Firefox     | 56+                     |
+| Mac OS           | Desktop Edge        | 80+                     |
+| Windows          | Desktop Chrome      | 56+                     |
+| Windows          | Desktop QQ Browser  | 10.4+                   |
+| Windows          | Desktop Firefox     | 56+                     |
+| Windows          | Desktop Edge        | 80+                     |
+| iOS              | Mobile Safari       | 14+                     |
+| iOS              | WeChat Embedded Web | ✖                       |
+| Android          | Mobile Chrome       | 81+                     |
+| Android          | WeChat Embedded Web | ✔                       |
+| Android          | Mobile QQ Browser   | ✖                       |
+
+## Implementation Process
+
+### Start Background Music
+
+> !
+>
+> - When playing online sound effect files, the sound effect files must support `CORS` and the access protocol must be `https`.
+> - Supported formats include MP3, AAC (and other audio formats supported by browsers).
+> - Before any user interaction, browsers prohibit web pages from playing media with sound. It is recommended to guide users to perform a click action before calling this interface.
+> - Reference: [Autoplay_guide](https://developer.mozilla.org/en-US/docs/Web/Media/Autoplay_guide).
+
+```javascript
+await trtc.startPlugin('AudioMixer', {
+  id: 'count',
+  url: '../assets/count.mp3',
+  loop: true,
+  volume: 0.2
+})
+```
+
+### Update Background Music
+Perform operations on the background music.
+
+```javascript
+// disable loop playback
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  loop: false
+})
+// volume setting
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  volume: 1
+})
+// pause music `count`
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  loop: true,
+  volume: 0.2,
+  operation: 'pause'
+})
+// resume music `count`
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  operation: 'resume'
+})
+// play `count` from 5s
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  seekFrom: 5
+})
+```
+
+### Stop Background Music
+
+Stop a background music that is not needed.
+
+```javascript
+await trtc.stopPlugin('AudioMixer', {
+  id: 'count'
+})
+```
+
+## API
+
+### trtc.startPlugin('AudioMixer', options)
+
+Start background music.
+
+#### options
+
+| Name   | Type      | Attributes   | Description                                 |
+|--------|-----------|--------------|---------------------------------------------|
+| id     | `string`  |              | Set a unique ID for each incoming music URL |
+| url    | `string`  |   | Music file URL. One of url and track must be passed in. If both are passed in, the url will be selected first.                            |
+| track | `MediaStreamAudioTrack`  |  | Since v5.4.3+, one of url and track must be passed in. can pass in a track extracted from the `<audio/>` tag. If both are passed in, the url will be selected first. |
+| loop   | `boolean` | `<optional>` | Whether to loop play, default is false      |
+| volume | `number`  | `<optional>` | Set the initial volume, default is 1 (0-1). Not support iOS.  |
+| playbackRate | `number`  | `<optional>` | Set the playback rate, the default is 1.0                |
+| onDurationChange | `function`  | `<optional>` | Callback function, which will be executed after the music is loaded. The parameter is (duration: number) which indicates the total duration of the music |
+| onTimeUpdate | `function`  | `<optional>` | Callback function, which will be executed after the music is loaded. The parameter is (duration: number) which indicates the total duration of the music |
+| onEnded | `function`  | `<optional>` | Callback function, executed when the music ends (note that it will not be executed every time the music ends during loop), no parameters |
+
+```javascript
+await trtc.startPlugin('AudioMixer', {
+  id: 'count',
+  url: '../assets/count.mp3',
+  loop: true,
+  volume: 0.2
+})
+```
+
+### trtc.updatePlugin('AudioMixer', options)
+
+Update background music.
+
+#### options
+
+| Name      | Type      | Attributes   | Description                                                             |
+|-----------|-----------|--------------|-------------------------------------------------------------------------|
+| id        | `string`  |              | The unique ID for each incoming music URL you set when call startPlugin |
+| loop      | `boolean` | `<optional>` | Whether to loop play, default is false                                  |
+| volume    | `number`  | `<optional>` | Set the initial volume, default is 1 (0-1)                              |
+| seekFrom  | `number`  | `<optional>` | Start seeking playback from which second, this parameter requires the music resource file to support [HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests).                               |
+| operation | `number`  | `<optional>` | Operation on the background music: 'pause' ｜ 'resume' ｜ 'stop'          |
+
+**Example:**
+
+```javascript
+await trtc.updatePlugin('AudioMixer', {
+  id: 'count',
+  loop: true,
+  volume: 0.2,
+  operation: 'pause'
+})
+```
+
+### trtc.stopPlugin('AudioMixer', options)
+
+Stop a background music that is not needed.
+
+#### options
+
+| Name | Type     | Attributes | Description                                                             |
+|------|----------|------------|-------------------------------------------------------------------------|
+| id   | `string` |            | The unique ID for each incoming music URL you set when call startPlugin |
+
+**Example:**
+
+```javascript
+await trtc.stopPlugin('AudioMixer', {
+  id: 'count'
+})
+```
+
+## Frequently Asked Questions
+
+**1. Cross-Origin Error**
+
+For example: 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.
+
+Solution: You need to configure the CORS protocol for your online music files.
+
+**2. Incorrect Audio Format, Unable to Play in Browser**
+
+For example: NotSupportedError: The operation is not supported.
+
+Solution: You need to use an audio format supported by the browser.

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

@@ -0,0 +1,221 @@
+## Browser Environment Check
+
+Before calling the communication capabilities of the SDK, we recommend you use the `{@link TRTC.isSupported TRTC.isSupported}` API to check whether the SDK supports the current browser first, and if not, please recommend the user to use a supported browser(Chrome 56+, Edge 80+, Firefox 56+, Safari 11+).
+
+```javascript
+TRTC.isSupported().then(checkResult => {
+  // Not supported, guide the user to use a supported browser(Chrome 56+, Edge 80+, Firefox 56+, Safari 11+).
+  if (!checkResult.result) {}
+  // Not support to publish video
+  if (!checkResult.detail.isH264EncodeSupported) {}
+  // Not support to subscribe video
+  if (!checkResult.detail.isH264DecodeSupported) {}
+})
+```
+
+⚠️ If the check result returned by `TRTC.isSupported` is `false`, this may be because:
+
+1. The web page uses the http protocol. Browsers do not allow http protocol sites to capture cameras and microphones, you need to deploy your page using the https protocol.
+2. The current browser does not support WebRTC, you need to guide the user to use the recommended browser {@tutorial 05-info-browser}.
+3. Firefox browser needs to load H264 codec dynamically after installation, so the detection result will be false for a short period of time, please wait and try again or guide to use other browsers.
+
+## Media Device Test
+
+### Option 1: Use Device Detector Plugin (including default UI)
+
+The device detector plugin is used to test the user's media device(camera, microphone, speaker) and network which is recommended to be used before the user enters the room. 
+
+> - Support TRTC Web SDK version >= v5.8.0
+> - The plugin includes a default UI. If the UI does not meet your product design requirements, you can refer to Option 2 for a custom UI implementation.
+
+#### Usage
+
+```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 Description
+
+##### trtc.startPlugin('DeviceDetector', options)
+
+##### options
+
+| Name            | Type   | Attributes | Description                                                  |
+| --------------- | ------ | ---------- | ------------------------------------------------------------ |
+| language       | 'auto' \| 'zh' \| 'en' | Optional        | Optional. Set the language of the UI, supporting Chinese and English. The default is 'auto', which means automatically judging based on the current browser language. 'zh' means using Chinese, 'en' means using English.|
+| allowSkip       | boolean | Optional        | Optional. The default value is true, which will display the skip button. If false, the skip button will not be displayed, and the user must complete each step of the detection before proceeding to the next step.|
+| cameraDetect    | object  | Optional        | Optional. Camera detection options, see cameraDetect options below|
+| networkDetect   | object  | Optional        | Optional. Network detection options, see networkDetect options below|
+
+
+###### options.mirror(optional)
+
+Enable the mirror checkbox during camera detection
+
+###### options.cameraDetect(optional)
+| Name   | Type    | Attributes | Description                                                                                                                                    |
+| ------ | ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| mirror | boolean | Optional   | Optional. When true, the mirror image will be enabled during the camera detection phase, and a checkbox for the mirror image will be displayed |
+
+###### options.networkDetect(optional)
+
+| Name            | Type   | Attributes | Description                                                                                                                                                           |
+| --------------- | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| sdkAppId        | string | required   | Your sdkAppId                                                                                                                                                         |
+| userId          | string | required   | The userId for testing uplink network quality. It should be different from downlinkUserId.                                                                            |
+| userSig         | string | required   | The [UserSig](https://trtc.io/document/35166) of the userId.                                                                                                          |
+| downlinkUserId  | string | required   | The userId for testing downlink network quality. It should be different from userId. Fill in downlinkUserId and downlinkUserSig will perform a downlink network test. |
+| downlinkUserSig | string | required   | The [UserSig](https://trtc.io/document/35166) of the downlinkUserId.                                                                                                  |
+| roomId          | number | optional   | Optional. The default value is 8080. The value must be an integer of [1, 4294967294]                                                                                  |
+
+##### trtc.stopPlugin('DeviceDetector')
+
+| 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` | { isSuccess: boolean, result: { quality: number , rtt: number }}<br />The quality is uplink network quality. When the downlinkUserId and downlinkUserSig passed, the quality is the worse one of the upstream and downstream network quality<br />**Network Quality Values**<br />0: The network quality is unknown, indicating that the current TRTC instance has not established a media connection<br />1:  The network quality is excellent<br />2:  The network quality is good<br />3:  The network quality is average<br />4:  The network quality is poor<br />5:  The network quality is extremely poor<br />6:  The network connection has been disconnected. |
+
+#### Plugin 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>
+
+### Option 2: Implement Device Detection Based on SDK API (Custom UI)
+
+If the default UI of the device detection plugin in Option 1 does not meet your requirements, you can choose Option 2 to customize the UI.
+
+#### 1. Check Device Permission
+
+Since v5.13.0+, SDK provides the `TRTC.getPermissions` interface, which is used to check, request, and listen to device permissions.
+
+```javascript
+const { camera, microphone } = await TRTC.getPermissions({
+  request: true, // If true, the interface may temporarily open the camera to obtain the camera permission, and then the SDK will automatically release the capture.
+  types: ['camera', 'microphone'] // The types of permission to request.
+});
+console.log(camera, microphone); // 'granted' | 'denied' | 'prompt' | null. null means the permission is not supported query.
+
+// Listen to device permission changes
+trtc.on(TRTC.EVENT.PERMISSION_STATE_CHANGE, event => {
+  console.log(event.camera, event.microphone);
+});
+// Release the listener
+trtc.off(TRTC.EVENT.PERMISSION_STATE_CHANGE);
+```
+
+#### 2. Device Connection
+
+The device connection checks if the user's device has a camera, microphone, and speaker. It also verifies the network connection. If the camera and microphone are present, the system will attempt to access the audio/video streams and prompt the user to grant permission for camera and microphone access.
+
++ Check whether the device has a camera, microphone device
+
+  ```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 !== '');
+  // Mobile devices do not support getting speaker devices, so mobile devices can skip getting speaker devices
+  const speakerList = await TRTC.getSpeakerList();
+  const hasSpeakerDevice = speakerList.some(speaker => speaker.deviceId !== '');
+  ```
+
+#### 3. Camera Detection
+
+Detection principle: Turn on the camera and render the camera image on the page. You can provide two buttons on the page to allow the user to confirm whether they can see the camera image.
+
++ Turn on the camera
+
+  ```javascript
+  trtc.startLocalVideo({ view: 'camera-video', publish: false });
+  ```
+
++ Switch the camera
+
+  ```javascript
+  trtc.updateLocalVideo({ option: { cameraId } });
+  ```
+
++ Close the camera after detection is completed
+
+  ```javascript
+  trtc.stopLocalVideo();
+  ```
+
+#### 4. Microphone Detection
+
+Detection principle: Open the microphone and obtain the microphone volume. Listen to the microphone volume event and render the real-time volume to the page, guide the user to speak, and confirm whether they can see the volume bar change.
+
++ Turn on the microphone
+
+  ```javascript
+  trtc.on(TRTC.EVENT.AUDIO_VOLUME, event => {
+    event.result.forEach(({ userId, volume }) => {
+        const isMe = userId === '';
+        if (isMe) {
+            console.log(`my volume: ${volume}`);
+            // Render the microphone volume to your page.
+        }
+    })
+  });
+  // 开启音量回调，并设置每 200ms 触发一次事件
+  trtc.enableAudioVolumeEvaluation(200);
+  trtc.startLocalAudio({ publish: false });
+  ```
+
++ Switch the microphone
+
+  ```javascript
+  trtc.updateLocalAudio({ option: { microphoneId }});
+  ```
+
++ Release the microphone usage after detection is completed
+
+  ```javascript
+  trtc.stopLocalAudio();
+  ```
+
+#### 5. Speaker Detection
+
+Detection principle: Play an mp3 media file through an audio tag
+
++ Create an audio tag, remind the user to turn up the playback volume, play the mp3 to confirm whether the speaker device is normal.
+
+  ```html
+  <audio id="audio-player" src="xxxxx" controls></audio>
+  ```
+
++ Stop playback after detection is completed
+
+  ```javascript
+  const audioPlayer = document.getElementById('audio-player');
+  if (!audioPlayer.paused) {
+      audioPlayer.pause();
+  }
+  audioPlayer.currentTime = 0;
+  ```
+
+#### 6. Network Detection
+
+Reference: [Network Quality Detection before enterRoom](./tutorial-24-advanced-network-quality.html)
+
+## TRTC Capability Detection Page
+
+You can use the [TRTC Detection Page](https://web.sdk.qcloud.com/trtc/webrtc/demo/detect/index.html) where you are currently using the TRTC SDK to detect the current environment. You can also click the "Generate Report" button to get a report of the current environment for environment detection or troubleshooting.
+

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

@@ -0,0 +1,140 @@
+
+Before entering the room or during the call, you can check the user's network quality to determine the current network quality. If the user's network quality is too poor, it is recommended that the user change the network environment to ensure normal call quality.
+
+This article mainly introduces how to implement network quality detection before the call or during the call based on the [NETWORK_QUALITY](./module-EVENT.html#.NETWORK_QUALITY) event.
+
+## Detect network quality during the call
+
+See: {@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}`)
+})
+```
+
+## Detect network quality before the call
+
+### Implementation process
+
+1. Call [TRTC.create](./TRTC.html#.createTRTC) to create two TRTC objects, referred to as uplinkTRTC and downlinkTRTC.
+2. Both TRTC objects enter the same room.
+3. Use uplinkTRTC to startLocalVideo, and listen to the [NETWORK_QUALITY](./module-EVENT.html#.NETWORK_QUALITY) event to detect the uplink network quality.
+4. Use downlinkTRTC to startRemoteVideo, and listen to the [NETWORK_QUALITY](./module-EVENT.html#.NETWORK_QUALITY) event to detect the downlink network quality.
+5. The entire process lasts for about 15 seconds, and finally takes the average network quality to roughly determine the uplink and downlink network conditions.
+
+> !
+> - The detection process will generate a small amount of [basic service fees](https://trtc.io/document/59806?platform=android&product=rtcengine&menulabel=coresdk). If the push stream resolution is not specified, it defaults to pushing the stream with a resolution of 640*480.
+
+### API call sequence
+
+![network-quality-call-sequence](./assets/network-quality-call-sequence.png)
+
+### Code example
+
+```js
+let uplinkTRTC = null; // Used to detect uplink network quality
+let downlinkTRTC = null; // Used to detect downlink network quality
+let localStream = null; // Stream used for testing
+let testResult = {
+  // Record uplink network quality data
+  uplinkNetworkQualities: [],
+  // Record downlink network quality data
+  downlinkNetworkQualities: [],
+  average: {
+    uplinkNetworkQuality: 0,
+    downlinkNetworkQuality: 0
+  }
+}
+
+// 1. Test uplink network quality
+async function testUplinkNetworkQuality() {
+  uplinkTRTC = TRTC.create();
+
+  uplinkTRTC.enterRoom({
+    roomId: 8080,
+    sdkAppId: 0, // Fill in sdkAppId
+    userId: 'user_uplink_test',
+    userSig: '', // userSig of uplink_test
+    scene: 'rtc'
+  })
+
+  uplinkTRTC.on(TRTC.EVENT.NETWORK_QUALITY, event => {
+    const { uplinkNetworkQuality } = event;
+    testResult.uplinkNetworkQualities.push(uplinkNetworkQuality);
+  });
+
+  uplinkTRTC.startLocalVideo();
+}
+
+
+
+// 2. Detect downlink network quality
+async function testDownlinkNetworkQuality() {
+  downlinkTRTC = TRTC.create();
+  downlinkTRTC.enterRoom({
+    roomId: 8080,
+    sdkAppId: 0, // Fill in 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. Start detection
+testUplinkNetworkQuality();
+testDownlinkNetworkQuality();
+
+// 4. Stop detection after 15s and calculate the average network quality
+setTimeout(() => {
+  // Calculate the average uplink network quality
+  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) {
+    // Calculate the average downlink network quality
+    testResult.average.downlinkNetworkQuality = Math.ceil(
+      validDownlinkNetworkQualitiesList.reduce((value, current) => value + current, 0) / validDownlinkNetworkQualitiesList.length
+    );
+  }
+    
+  // Detection is over, clean up related states.
+  uplinkTRTC.exitRoom();
+  downlinkTRTC.exitRoom();
+}, 15 * 1000);
+```
+
+## Result Analysis
+
+After the above steps, you can get the average uplink network quality and the average downlink network quality. The enumeration values of network quality are as follows:
+
+| Value | Meaning |
+| :--- | :----------------------------------------------------------- |
+| 0    | The network condition is unknown, indicating that the current TRTC instance has not established an uplink/downlink connection |
+| 1    | The network condition is excellent |
+| 2    | The network condition is good |
+| 3    | The network condition is average |
+| 4    | The network condition is poor |
+| 5    | The network condition is extremely poor |
+| 6    | The network connection has been disconnected. Note: If the downlink network quality is this value, it means that all downlink connections have been disconnected. |
+
+> Suggestion: When the network quality is greater than 3, it is recommended to guide the user to check the network and try to change the network environment, otherwise it is difficult to ensure normal audio and video communication.
+> You can also reduce bandwidth consumption through the following strategies:
+> - If the uplink network quality is greater than 3, you can reduce the bitrate through the [TRTC.updateLocalVideo()](./TRTC.html#updateLocalVideo) interface or close the video through the [TRTC.stopLocalVideo()](./TRTC.html#stopLocalVideo) method to reduce uplink bandwidth consumption.
+> - If the downlink network quality is greater than 3, you can reduce the downlink bandwidth consumption by subscribing to a small stream (refer to: [Enable Small Stream Transmission](./tutorial-27-advanced-small-stream.html)) or only subscribing to audio.
+
+

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

@@ -0,0 +1,99 @@
+
+## Function Description
+
+This article mainly introduces how to detect the behavior of users inserting, unplugging, and starting devices. And how to handle device collection exceptions.
+
+> **About SDK automatic recovery collection**<br>
+> The SDK will detect the insertion and removal behavior of the camera and microphone, and automatically recover the collection at the appropriate time. The specific logic is as follows:
+> 1. If the currently streaming camera/microphone is unplugged, the SDK will try to use the remaining available media devices to restore the collection.
+> 2. If the camera/microphone is unplugged and there are no available media devices, the SDK will detect the device insertion behavior. If a new available media device is inserted, the SDK will try to use the newly inserted media device to restore the collection and push the stream.
+> 3. If the recovery fails, an error [TRTC.ERROR_CODE.DEVICE_ERROR](./module-ERROR_CODE.html#.DEVICE_ERROR) will be thrown, and the extraCode will be 5308 and 5309.
+
+
+## Implementation Process
+
+### Detect device insertion, removal, and startup
+
+```js
+trtc.on(TRTC.EVENT.DEVICE_CHANGED, (event) => {
+  // Device insertion
+  if (event.action === 'add') {
+    // Camera insertion
+    if (event.type === 'camera') {}
+  } else if (event.action === 'remove') {
+    // Device unplugged
+  } else if (event.action === 'active') {
+    // Device startup
+  }
+  console.log(`${event.type}(${event.device.label}) ${event.action}`);
+});
+```
+
+### Check if the currently used device is unplugged
+
+```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) {
+        // The currently used camera is unplugged.
+      }
+    } else if (event.type === 'microphone') {
+      const currentMicId = trtc.getAudioTrack()?.getSettings()?.deviceId;
+      if (event.device.deviceId === currentMicId) {
+        // The currently used microphone is unplugged.
+      }
+    }
+  }
+});
+```
+
+### Automatically switch to using new devices when users insert new devices.
+
+```js
+trtc.on(TRTC.EVENT.DEVICE_CHANGED, (event) => {
+  if (event.action === 'add') {
+    if (event.type === 'camera') {
+      // After inserting the camera, automatically switch to the new camera
+      trtc.updateLocalVideo({ option: { cameraId: event.device.deviceId }});
+    }
+  }
+});
+```
+
+### Handling device collection exceptions
+
+Listen for device collection exception events
+
+```js
+trtc.on(TRTC.EVENT.VIDEO_PLAY_STATE_CHANGED, event => {
+  // Local camera collection exception, at this time the SDK will try to automatically recover the collection, you can guide the user to check whether the camera is normal.
+  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 => {
+  // Local microphone collection exception, at this time the SDK will try to automatically recover the collection, you can guide the user to check whether the microphone is normal.
+  if (event.userId === '' && (event.reason === 'mute' || event.reason === 'ended')) {}
+});
+```
+
+Listen for SDK automatic recovery collection failure events
+```js
+trtc.on(TRTC.EVENT.ERROR, error => {
+  if (error.code === TRTC.ERROR_CODE.DEVICE_ERROR) {
+    // Camera recovery collection failed
+    if (error.extraCode === 5308) {
+      // After guiding the user to check the device, call updateLocalVideo and pass in cameraId to recollect.
+      trtc.updateLocalVideo({ option: { cameraId: '' }});
+    }
+
+    // Microphone recovery collection failed
+    if (error.extraCode === 5309) {
+      // After guiding the user to check the device, call updateLocalAudio and pass in microphoneId to recollect.
+      trtc.updateLocalAudio({ option: { microphoneId: '' }});
+    }
+  }
+})
+```
+