@tencentcloud/sdk-mcp 1.3.4 → 1.3.5

package/resource/doc/rtcengine/web/plugin/28-advanced-beauty.md

@@ -0,0 +1,349 @@
+## 功能描述
+
+本文主要描述如何使用美颜插件。
+
+## 前提条件
+
+- 需要使用美颜功能的 sdkAppId 已开通专业版包月套餐。请参见文档 [包月套餐计费说明](https://www.tencentcloud.com/zh/document/product/647/56025)
+- [TRTC SDK](https://www.npmjs.com/package/trtc-sdk-v5) 版本需要 >= 5.5.0
+- 各平台系统及配置要求如下表：
+
+
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >平台</td>
+
+<td rowspan="1" colSpan="1" >操作系统</td>
+
+<td rowspan="1" colSpan="1" >浏览器版本</td>
+
+<td rowspan="1" colSpan="1" >fps</td>
+
+<td rowspan="1" colSpan="1" >推荐配置</td>
+
+<td rowspan="1" colSpan="1" >备注</td>
+</tr>
+
+<tr>
+<td rowspan="8" colSpan="1" >Web</td>
+
+<td rowspan="2" colSpan="1" >Windows</td>
+
+<td rowspan="2" colSpan="1" >Chrome 90+<br>Firefox 90+<br>Edge 97+</td>
+
+<td rowspan="1" colSpan="1" >30</td>
+
+<td rowspan="1" colSpan="1" >内存：16GB<br>CPU：i5-10500<br>GPU：独显 2GB</td>
+
+<td rowspan="3" colSpan="1" >建议使用最新版 Chrome 浏览器<br> <b> （开启浏览器硬件加速）</b></td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >15</td>
+
+<td rowspan="1" colSpan="1" >内存：8GB<br>CPU：i3-8300<br>GPU：intel 核显 1GB</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Mac</td>
+
+<td rowspan="1" colSpan="1" >Chrome 98+<br>Firefox 96+<br>Safari 14+</td>
+
+<td rowspan="1" colSpan="1" >30</td>
+
+<td rowspan="1" colSpan="1" >2019年 MacBook<br>内存：16GB(2667MHz)<br>CPU：i7(6核 2.60GHz)<br>GPU：AMD Radeon 5300M</td>
+</tr>
+
+<tr>
+<td rowspan="3" colSpan="1" >Android</td>
+
+<td rowspan="3" colSpan="1" >微信内嵌浏览器<br>Chrome<br>火狐浏览器<br>小米浏览器<br>华为浏览器</td>
+
+<td rowspan="1" colSpan="1" >30</td>
+
+<td rowspan="1" colSpan="1" >高端机（高通骁龙 8 Gen1 等）</td>
+
+<td rowspan="3" colSpan="1" >建议使用微信内嵌、Chrome 或火狐浏览器等主流浏览器<br>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >20</td>
+
+<td rowspan="1" colSpan="1" >中端机（天玑 8000-MAX 等）</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >10</td>
+
+<td rowspan="1" colSpan="1" >低端机（高通骁龙 660 等）</td>
+</tr>
+
+<tr>
+<td rowspan="2" colSpan="1" >iOS</td>
+
+<td rowspan="2" colSpan="1" >微信内嵌浏览器<br>Chrome<br>Safari<br>Firefox</td>
+
+<td rowspan="1" colSpan="1" >30</td>
+
+<td rowspan="1" colSpan="1" >iPhone 13</td>
+
+<td rowspan="2" colSpan="1" >- 要求 iOS 14.4 以上系统<br>- 建议使用 Chrome 或 Safari 浏览器<br>- <b> 不支持 QQ 浏览器</b></td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >20</td>
+
+<td rowspan="1" colSpan="1" >iPhone xr</td>
+</tr>
+
+</tr>
+</table>
+
+## 使用步骤
+
+### 一、注册插件
+
+在使用之前，首先需要注册插件。以下是注册插件的示例代码：
+
+```js
+import TRTC from 'trtc-sdk-v5';
+import { Beauty } from 'trtc-sdk-v5/plugins/video-effect/beauty';
+
+const trtc = TRTC.create({ plugins: [Beauty] });
+```
+
+### 二、开启本地摄像头
+
+```js
+await trtc.startLocalVideo({
+  view: 'local-video' // 填入自己业务需要的 div id
+});
+```
+
+### 三、使用美颜和内置 2D 特效
+
+#### 美颜效果
+
+美颜功能的开启、更新和停止通过三个接口来控制
+
+- `trtc.startPlugin('Beauty', options)` 开启美颜
+- `trtc.updatePlugin('Beauty', options)` 更新美颜参数
+- `trtc.stopPlugin('Beauty')` 停止美颜
+
+其中 `options` 参数支持 6 种美颜参数：
+
+```ts
+type BeautifyOptions = {
+  whiten?: number; // 美白 0-1
+  dermabrasion?: number; // 磨皮 0-1
+  lift?: number; // 窄脸 0-1
+  shave?: number; // 削脸 0-1
+  eye?: number; // 大眼 0-1
+  chin?: number; // 下巴 0-1
+}
+```
+
+#### 内置 2D 特效贴纸
+
+本插件提供内置的 2D 特效贴纸，下面是列表
+
+| 特效 ID            | 名称        |
+|---------------------|--------------------|
+| EDE5D18065451445    | 奶瓶面膜 |
+| 7A62218064EF7959    | 毛毡发箍     |
+| B4D63180653948C3    | 刘海发带     |
+| D7C6418064B90F4C    | 可爱喵        |
+| 1D6EB18069D76A62    | 波点女孩    |
+| CBE7618065D9D76F    | 爱心烟花    |
+| 9B86618065596018    | 可爱猪猪        |
+| 428C518065369ACF    | 双麻花     |
+| B30E218064F7B397    | 元气贴纸   |
+| AE3C81806521B49B    | 兔兔酱      |
+
+可以在参数中传入 `EffectListOptions` 类型的数组，将 `EffectId` 填入 `id` 字段，`intensity` 用于控制透明度。传入的 `EffectId` 对应的贴纸将会生效。更多信息请参考示例代码。
+
+```ts
+type EffectListOptions = {
+  id: string;
+  intensity?: number; // specify the strength of the effect
+}
+```
+
+## 示例代码
+
+以下是代码示例：
+
+开启插件时，`options` 还需要额外携带当前用户的登录信息（sdkAppId、userId、userSig）用作校验。
+
+```javascript
+// 开启插件
+const options = {
+  sdkAppId: 0,
+  userId: '',
+  userSig: '',
+
+  whiten: 0.5; // 美白 0-1
+  dermabrasion: 0.5; // 磨皮 0-1
+  lift: 0.5; // 窄脸 0-1
+  shave: 0.5; // 削脸 0-1
+  eye: 0.5; // 大眼 0-1
+  chin: 0.5; // 下巴 0-1
+
+  // 特效数组
+  effect: [{
+    id: '7A62218064EF7959', // 特效 ID
+    intensity: 0.7 // 生效强度
+  }]
+}
+try {
+  await trtc.startPlugin('Beauty', options);
+} catch (error) {
+  console.error('Beauty start failed', error);
+}
+```
+
+```javascript
+// 更新美颜参数
+const options = {
+  whiten: 0.5; // 美白 0-1
+  dermabrasion: 0.5; // 磨皮 0-1
+  lift: 0.5; // 窄脸 0-1
+  shave: 0.5; // 削脸 0-1
+  eye: 0.5; // 大眼 0-1
+  chin: 0.5; // 下巴 0-1
+
+  effect: [{
+    id: '7A62218064EF7959',
+    intensity: 0.7,
+  },{
+    id: 'D7C6418064B90F4C',
+    intensity: 0.7
+  }]
+}
+try {
+  await trtc.updatePlugin('Beauty', options);
+} catch (error) {
+  console.error('Beauty update failed', error);
+}
+```
+
+```javascript
+// 停止美颜
+try {
+  await trtc.stopPlugin('Beauty');
+} catch (error) {
+  console.error('Beauty stop failed', error);
+}
+```
+
+## API 说明
+
+### trtc.startPlugin('Beauty', options)
+
+用于开启美颜
+
+#### options
+
+| Name   | Type      | Attributes   | Description                         |
+|--------|-----------|--------------|-------------------------------------|
+| sdkAppId     | `number`  |    必填          | 当前应用 ID |
+| userId    | `string`  |     必填         | 当前用户 ID                              |
+| userSig   | `string` | 必填 | 用户 ID 对应的 UserSig                     |
+| whiten   | `number` | 选填 | 美白 ，取值范围 [0,1]                  |
+| dermabrasion   | `number` | 选填 | 磨皮 ，取值范围 [0,1]                    |
+| lift   | `number` | 选填 | 窄脸 ，取值范围 [0,1]                    |
+| shave   | `number` | 选填 | 削脸 ，取值范围 [0,1]                   |
+| eye   | `number` | 选填 | 大眼 ，取值范围 [0,1]                    |
+| chin   | `number` | 选填 | 下巴，取值范围 [0,1]                 |
+| effect       | `Array<EffectListOptions>` | 选填   | 特效列表    |
+| onError    | `(error) => {}`  |     选填           | 运行过程中发生错误的回调 <br> - error.code=10000003 渲染耗时长 <br>  - error.code=10000006 浏览器特性支持不足，可能会出现卡顿情况 <br> 推荐处理方法可参考文末常见问题                         |
+
+EffectListOptions:
+
+| Name       | Type     | Attributes | Description                       |
+|------------|----------|------------|-----------------------------------|
+| id   | `number` | 必填   | 特效 ID          |
+| intensity     | `string` | 选填   | 生效强度                |
+
+| 特效 ID              | 名称        |
+|---------------------|--------------------|
+| EDE5D18065451445    | 奶瓶面膜 |
+| 7A62218064EF7959    | 毛毡发箍     |
+| B4D63180653948C3    | 刘海发带     |
+| D7C6418064B90F4C    | 可爱喵        |
+| 1D6EB18069D76A62    | 波点女孩    |
+| CBE7618065D9D76F    | 爱心烟花    |
+| 9B86618065596018    | 可爱猪猪        |
+| 428C518065369ACF    | 双麻花     |
+| B30E218064F7B397    | 元气贴纸   |
+| AE3C81806521B49B    | 兔兔酱      |
+
+### trtc.updatePlugin('Beauty', options)
+
+可修改美颜参数
+
+#### options
+
+| Name   | Type      | Attributes   | Description                         |
+|--------|-----------|--------------|-------------------------------------|
+| whiten   | `number` | 选填 | 美白 ，取值范围 [0,1]                  |
+| dermabrasion   | `number` | 选填 | 磨皮 ，取值范围 [0,1]                    |
+| lift   | `number` | 选填 | 窄脸 ，取值范围 [0,1]                    |
+| shave   | `number` | 选填 | 削脸 ，取值范围 [0,1]                   |
+| eye   | `number` | 选填 | 大眼 ，取值范围 [0,1]                    |
+| chin   | `number` | 选填 | 下巴，取值范围 [0,1]                 |
+| effect       | `Array<EffectListOptions>` | 选填   | 特效列表    |
+
+EffectListOptions:
+
+| Name       | Type     | Attributes | Description                       |
+|------------|----------|------------|-----------------------------------|
+| id   | `number` | 必填   | 特效 ID          |
+| intensity     | `string` | 选填   | 生效强度                |
+
+| 特效 ID              | 名称        |
+|---------------------|--------------------|
+| EDE5D18065451445    | 奶瓶面膜 |
+| 7A62218064EF7959    | 毛毡发箍     |
+| B4D63180653948C3    | 刘海发带     |
+| D7C6418064B90F4C    | 可爱喵        |
+| 1D6EB18069D76A62    | 波点女孩    |
+| CBE7618065D9D76F    | 爱心烟花    |
+| 9B86618065596018    | 可爱猪猪        |
+| 428C518065369ACF    | 双麻花     |
+| B30E218064F7B397    | 元气贴纸   |
+| AE3C81806521B49B    | 兔兔酱      |
+
+### trtc.stopPlugin('Beauty')
+
+关闭美颜
+
+## 常见问题
+
+**1. 在 Chrome 中运行 Demo 发现画面颠倒且卡顿**
+
+本插件使用 GPU 进行加速，您需要在浏览器设置中找到使用硬件加速模式并启用。可以将 `chrome://settings/system` 复制到浏览器地址栏，并且打开硬件加速模式。
+
+**2. 当设备性能不足造成延迟高，提示渲染耗时长**
+
+可通过监听事件，降低视频分辨率或者帧率。
+
+```javascript
+async function onError(error) {
+  const { code } = error;
+  if (code === 10000003 || code === 10000006) {
+    // 降低分辨率帧率
+    await trtc.updateLocalVideo({
+      option: {
+        profile: '480p_2'
+      },
+    });
+    // await trtc.stopPlugin('Beauty'); // 或者关闭插件
+  }
+}
+
+await trtc.startPlugin('Beauty', {
+  ...// 其他参数
+  onError,
+});
+```

package/resource/doc/rtcengine/web/plugin/29-advanced-water-mark.md

@@ -0,0 +1,149 @@
+## 功能描述
+
+本文主要介绍如何使用水印插件在视频流上添加图片水印。
+
+## 前提条件
+
+- TRTC Web SDK 版本 >= 5.3.2。
+
+## 实现流程
+
+### 引入并注册插件
+
+```javascript
+import { Watermark } from 'trtc-sdk-v5/plugins/video-effect/watermark';
+
+let trtc = TRTC.create({ plugins: [Watermark] });
+```
+
+### 开启本地摄像头
+
+```javascript
+await trtc.startLocalVideo({
+  view: 'local-video'
+  option: {
+    mirror: false
+  }
+});
+```
+
+### 开启水印插件
+
+```javascript
+await trtc.startPlugin('Watermark', {
+  imageUrl: 'https://web.sdk.qcloud.com/trtc/webrtc/test/qer-test/watermark/trtc-watermark-test.png'
+});
+```
+
+跑通后可将测试图片 url 换为您自己的水印图片，推荐为可透明的 png 格式。
+
+### 关闭水印
+
+```javascript
+await trtc.stopPlugin('Watermark');
+```
+
+## API 说明
+
+### trtc.startPlugin('Watermark', options)
+
+用于开启水印
+
+#### options
+
+| Name   | Type      | Attributes   | Description                         |
+|--------|-----------|--------------|-------------------------------------|
+| imageUrl     | `string`  |    必填          | 图片水印地址 |
+| x    | `string`  |     选填         | 水印左边距                              |
+| y   | `string` | 选填 | 水印上边距                     |
+| size     | `string \| number \| object` |    选填          | 传入字符串时：<br> - `"cover"` 缩放背景图片以完全覆盖背景区，可能背景图片部分看不见。 <br> - `"contain"` 缩放背景图片以完全装入背景区，可能背景区部分空白。 <br> 传入数字时： <br> - `x` 表示缩放背景图片 x 倍。如 0.5，取值范围为 `(0,1]` <br> 传入对象时：<br> - 可以传入 `{width: 200, height: 300}` 来手动指定 <br> 默认为 `cover`|
+
+**Example:**
+
+```javascript
+await trtc.startPlugin('Watermark', {
+  imageUrl: 'https://web.sdk.qcloud.com/trtc/webrtc/test/qer-test/watermark/tv2.png',
+  size: 'contain'
+});
+```
+
+```javascript
+await trtc.startPlugin('Watermark', {
+  imageUrl: 'https://web.sdk.qcloud.com/trtc/webrtc/test/qer-test/watermark/tv2.png',
+  size: 'cover'
+});
+```
+
+```javascript
+await trtc.startPlugin('Watermark', {
+  imageUrl: 'https://web.sdk.qcloud.com/trtc/webrtc/test/qer-test/watermark/tv2.png',
+  x: 0,
+  y: 0,
+  size: 0.5
+});
+```
+
+```javascript
+await trtc.startPlugin('Watermark', {
+  imageUrl: 'https://web.sdk.qcloud.com/trtc/webrtc/test/qer-test/watermark/tv2.png',
+  x: 0,
+  y: 0,
+  size: {
+    width: 100,
+    height: 200
+  }
+});
+```
+
+### trtc.updatePlugin('Watermark')
+
+更新水印的图片、位置、大小。
+
+#### options
+
+| Name   | Type      | Attributes   | Description                         |
+|--------|-----------|--------------|-------------------------------------|
+| imageUrl     | `string`  |    必填          | 图片水印地址 |
+| x    | `string`  |     选填         | 水印左边距                              |
+| y   | `string` | 选填 | 水印上边距                     |
+| size     | `string \| number \| object` |    选填          | 传入字符串时：<br> - `"cover"` 缩放背景图片以完全覆盖背景区，可能背景图片部分看不见。 <br> - `"contain"` 缩放背景图片以完全装入背景区，可能背景区部分空白。 <br> 传入数字时： <br> - `x` 表示缩放背景图片 x 倍。如 0.5，取值范围为 `(0,1]` <br> 传入对象时：<br> - 可以传入 `{width: 200, height: 300}` 来手动指定 <br> 默认为 `cover`|
+
+```javascript
+await trtc.updatePlugin('Watermark', {
+  imageUrl: 'https://web.sdk.qcloud.com/trtc/webrtc/test/qer-test/watermark/tv2.png',
+  x: 100,
+  y: 200,
+  size: {
+    width: 50,
+    height: 50
+  }
+});
+```
+
+### trtc.stopPlugin('Watermark')
+
+关闭水印
+
+**Example:**
+
+```javascript
+await trtc.stopPlugin('Watermark');
+```
+
+## 常见问题
+
+**1. 水印是镜像的？**
+
+本地预览的镜像是默认开启的，因此水印也会被镜像，可以将本地预览镜像关闭。
+
+```javascript
+await trtc.updateLocalVideo({
+  option: {
+    mirror: false
+  }
+});
+```
+
+**2. 更新水印画面会黑一下？**
+
+更新 SDK 到 v5.8.6 以上。

package/resource/doc/rtcengine/web/plugin/30-advanced-cross-room-link.md

@@ -0,0 +1,96 @@
+## 功能描述
+
+默认情况下，不同房间的音视频流是相互隔离的，只有同一房间内的用户可以进行音视频通话。跨房连麦功能允许不同房间的用户进行音视频通话。
+
+在直播场景中，该功能支持主播之间的通话，并让双方观众观看对方主播。本文介绍如何使用 CrossRoom 插件实现跨房连麦。
+
+跨房连麦支持两种模式：
+- **房间级连麦**：与目标房间的所有主播连麦。
+- **用户级连麦**：与目标房间的某个主播连麦。
+
+## 工作原理
+
+- **房间级连麦**：将当前房间所有主播的音视频流额外推送到目标房间，同时将目标房间所有主播的音视频流额外推送到当前房间。
+- **用户级连麦**：将当前房间自己的音视频流额外推送到目标房间，同时将目标房间指定主播的音视频流额外推送到当前房间。
+
+## 使用步骤
+
+> **注意**：确保您的 SDK 版本 >= v5.8.0
+
+### 1. 开始跨房连麦
+
+```js
+import { CrossRoom } from 'trtc-sdk-v5/plugins/cross-room';
+
+const trtc = TRTC.create({ plugins: [CrossRoom] });
+
+await trtc.enterRoom({ sdkAppId, userId: 'user1', userSig, roomId: 7777 });
+
+// 将当前房间 7777 的 user1 和目标房间 8888 的 user2 连接。user2 的流会推送到 7777 房间，user1 的流会推送到 8888 房间。
+await trtc.startPlugin('CrossRoom', {
+  roomId: 8888,
+  // 与 roomId 二选一
+  // strRoomId: '8888'
+  userId: 'user2' // 不传则表示房间级跨房连麦
+});
+```
+
+#### 参数说明
+
+| 参数名      | 类型     | 必填 | 说明                                   |
+|-------------|----------|------|----------------------------------------|
+| roomId      | Number   | 否  | 目标房间 ID。                         |
+| strRoomId      | String   | 否   | 目标房间 string 类型 ID，与 roomId 二选一。                         |
+| userId      | String   | 否   | 目标房间的主播 ID，不传表示房间级连麦。|
+
+---
+
+### 2. 更新跨房连麦对端主播的 mute 状态
+
+开启跨房连麦后，对端房间主播的流会推送到当前房间，当前房间内的所有用户都能接收到该主播的音视频流。
+
+通过以下接口，您可以限制跨房主播在当前房间的上行能力（音频/主路视频/辅路视频），影响房间内所有用户。
+
+禁用某种上行能力后，当前房间内的用户将无法接收对应的音视频流，也无法订阅。
+
+```js
+await trtc.updatePlugin('CrossRoom', {
+  updateList: [{
+    roomId: 8888,
+    // strRoomId: '8888'
+    userId: 'user2', // 不传则表示房间级跨房连麦
+    muteAudio: true,
+    muteVideo: false,
+    muteSubStream: false,
+  }]
+});
+```
+
+#### 参数说明
+
+| 参数名         | 类型     | 必填 | 说明                                   |
+|----------------|----------|------|----------------------------------------|
+| updateList     | Array    | 是   | 包含需要更新的跨房主播 mute 状态的列表 |
+| updateList[0].roomId         | Number   | 否  | 目标房间 ID。                         |
+| updateList[0].strRoomId         | Number   | 否   | 目标房间 string 类型 ID，与 roomId 二选一。                         |
+| updateList[0].userId         | String   | 否   | 目标房间的主播 ID，不传表示房间级连麦。|
+| updateList[0].muteAudio      | Boolean  | 否   | 是否停止跨房主播的音频流。                      |
+| updateList[0].muteVideo      | Boolean  | 否   | 是否停止跨房主播的主路视频流。                  |
+| updateList[0].muteSubStream  | Boolean  | 否   | 是否停止跨房主播的辅路视频流。                  |
+
+---
+
+### 3. 停止跨房连麦
+
+```js
+await trtc.stopPlugin('CrossRoom', { roomId: 8888 }); // 停止指定房间的跨房连麦
+
+await trtc.stopPlugin('CrossRoom'); // 停止当前用户发起的所有跨房连麦
+```
+
+#### 参数说明
+
+| 参数名      | 类型     | 必填 | 说明                                   |
+|-------------|----------|------|----------------------------------------|
+| roomId      | Number   | 否   | 目标房间 ID。                         |
+| strRoomId   | String   | 否   | 目标房间 string 类型 ID，与 roomId 二选一          |