@tencentcloud/sdk-mcp 1.3.4 → 1.3.6

package/resource/doc/livekit/live/ios/workflow.md

@@ -0,0 +1,352 @@
+# Native Live AtomicXCore 代码生成工作流指令 (iOS)
+
+## 🚨 核心原则（最高优先级）
+
+**Agent 必须确保生成的代码可以成功编译运行，严禁将无法编译的代码交付给用户！**
+
+### ⚠️ 强制编译验证（必须执行，不可省略）
+
+**🚫 严禁行为**：
+- ❌ 只用 `read_lints` 检查就认为代码正确
+- ❌ 用 `grep` 过滤编译输出（会导致命令被跳过）
+- ❌ 跳过编译验证直接交付代码
+
+**✅ 唯一正确的验证方式**：
+
+```bash
+# 步骤 1: 安装依赖（如需要）
+cd <项目目录> && pod install
+
+# 步骤 2: 编译验证（使用 tail 限制输出）
+cd <项目目录> && xcodebuild build \
+  -scheme <SchemeName> \
+  -workspace <WorkspaceName>.xcworkspace \
+  -destination 'generic/platform=iOS' \
+  CODE_SIGNING_ALLOWED=NO 2>&1 | tail -150
+
+
+**判断标准**：
+- ✅ 输出包含 `BUILD SUCCEEDED` → 编译通过，可交付
+- ❌ 输出包含 `BUILD FAILED` 或 `error:` → 必须修复后重新编译
+
+**常见错误与修复**：
+| 错误关键字 | 原因 | 修复方式 |
+|-----------|------|---------|
+| `No such module 'xxx'` | Pod 依赖缺失 | 添加到 Podfile 后执行 `pod install` |
+| `Cannot find 'xxx' in scope` | Import 缺失 | 添加 `import xxx` |
+| `Use of unresolved identifier` | API 名称错误 | 查阅文档确认正确 API |
+| `NSCameraUsageDescription` | Info.plist 权限缺失 | 添加权限描述 |
+
+**验证循环（必须遵守）**：
+```
+执行编译 → 失败 → 分析错误 → 修复代码 → 重新执行编译 → ... → BUILD SUCCEEDED → 交付
+```
+
+---
+
+## 📋 指令目的与架构
+
+为 Agent 提供实现 Native (iOS) Live AtomicXCore 核心功能的**代码生成蓝图**。
+
+**核心架构**：
+*   **容器**：`LiveCoreView` (视图层)
+*   **状态**：`Store` (数据驱动)
+*   **事件**：`Publisher` (Combine 订阅)
+
+**功能依赖逻辑（重要）**：
+1.  **基础先行**：必须先使用本工具（`get_native_live_uikit_integration`）完成基础直播（开播/观看/列表）。
+2.  **互动叠加**：如果用户需求包含"连麦"、"PK"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_native_live_uikit_interaction`）。
+3.  **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
+
+---
+
+## ⚙️ 自动化工作流步骤（必须创建为 TODO 任务）
+
+**🚨 Agent 必须将以下步骤创建为 TODO 任务列表，逐一完成并打勾：**
+
+### 步骤 1: 前置准备
+1.  **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
+    *   主播: `anchor001`, `anchor002`, `anchor003`
+    *   观众: `user001`, `user002`, `user003`
+2.  **环境检查**：检查 `Podfile`，若缺失以下依赖则自动添加：
+    ```ruby
+    pod 'AtomicXCore'
+    ```
+3.  **权限注入**：在 `Info.plist` 中添加摄像头、麦克风权限描述：
+    ```xml
+    <key>NSCameraUsageDescription</key>
+    <string>需要访问您的相机权限，开启后录制的视频才会有画面</string>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>需要访问您的麦克风权限，开启后录制的视频才会有声音</string>
+    ```
+
+### 步骤 2: 代码生成
+**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
+*   **仅主播**：生成 `AnchorViewController`
+*   **仅观众**：生成 `AudienceViewController`
+*   **主播+观众**：生成 `MainViewController` (入口选择) + `AnchorViewController` + `AudienceViewController`
+
+### 步骤 3: 🚨 编译验证（强制执行，不可跳过）
+**此步骤必须作为独立 TODO 任务执行，不能省略或合并！**
+
+**执行命令**：
+```bash
+cd <项目目录>/ios && pod install && \
+xcodebuild build -scheme <SchemeName> -workspace <WorkspaceName>.xcworkspace \
+  -destination 'platform=iOS Simulator,name=iPhone 16' \
+  CODE_SIGNING_ALLOWED=NO 2>&1 | tail -150
+```
+
+**判断与处理**：
+*   输出包含 **BUILD SUCCEEDED** → 进入步骤 4
+*   输出包含 **BUILD FAILED** 或 **error:** → 分析错误 → 修复代码 → **重新执行本命令**，循环直到成功
+
+### 步骤 4: 交付结果
+确认编译通过后，向用户交付代码。
+
+---
+
+## 🚫 代码生成约束（严格遵守）
+
+### 1. 通用代码约束
+*   **严禁修改 Import**：文档中的 import 路径经过验证，绝对不可修改。
+*   **严禁臆造 API**：如果文档没写，绝对不能自己发明方法名或参数名。
+*   **必须查阅 API 文档**：涉及数据模型字段（如 `LiveInfo`），必须查看文档确认字段名（例如确认是 `liveOwner.userName` 而不是 `name`）。
+
+### 2. 🧩 Store 与 Publisher 管理约束（生命周期安全）
+**核心原因**：SDK 使用 Combine 的 `Publisher` 进行状态订阅。不正确的生命周期管理会导致监听失效或内存泄漏。
+
+*   **订阅管理原则**：所有 `AnyCancellable` **必须声明为 ViewController 的成员变量** `cancellableSet`。
+*   **严禁忽略返回值**：禁止不存储 `.sink {}` 返回的 `AnyCancellable`。
+*   **成对原则**：在 `viewDidLoad` 中设置订阅，订阅会随 `cancellableSet` 在 `deinit` 时自动释放。
+
+### 3. ⏱️ 超时时间限制（关键技术点）
+**必须严格遵守以下参数限制，优先使用文档示例中的值：**
+
+#### A. 观众连麦 (`CoGuestStore`)
+*   **规则**：
+    *   可选参数，不填则不检查超时。
+    *   若填写，范围必须在 **5 - 1800 秒**之间。
+*   **正确示例**：
+    ```swift
+    // ✅ 推荐：跟随文档示例（如 30秒）
+    CoGuestStore.shared.applyForSeat(seatIndex: -1, timeout: 30) { ... }
+    // ✅ 合法：不检查超时
+    CoGuestStore.shared.applyForSeat(seatIndex: -1, timeout: 0) { ... }
+    ```
+*   **错误示例**：❌ `timeout: 3` (太短)，❌ `timeout: 2000` (太长)。
+
+#### B. 主播连线/PK (`CoHostStore`)
+*   **规则**：
+    *   **最大值 30 秒**（后台硬限制）。
+*   **正确示例**：
+    ```swift
+    // ✅ 推荐：使用最大值
+    CoHostStore.shared.requestHostConnection(..., timeout: 30) { ... }
+    ```
+*   **错误示例**：❌ `timeout: 60` (会导致请求失败)。
+
+### 4. 🎨 扩展功能约束（美颜/音效/UI）
+
+#### A. 音效 (Audio Effect)
+*   **变声枚举 (`AudioChangerType`)**：
+    *   ✅ **允许**：`.child, .littleGirl, .man, .ethereal` 等标准枚举。
+    *   ❌ **禁止**：`.uncle, .loli, .girl, .boy` (这些是旧版或错误的枚举)。
+*   **混响枚举 (`AudioReverbType`)**：
+    *   ✅ **允许**：`.ktv, .smallRoom, .metallic` 等。
+    *   ❌ **禁止**：`.room, .hall, .low`。
+
+#### B. 美颜 (Beauty)
+*   **参数范围**：**0.0 - 9.0** (Float)。
+    *   ❌ 不是 0-1 (Float)，也不是 0-100 (Int)。
+*   **UI 映射公式**：`sliderValue / 100.0 * 9.0`。
+
+#### C. 弹幕、礼物与布局 (Barrage, Gift & UI)
+*   **层级要求**：弹幕列表和全屏礼物动画必须使用 `UIView` 覆盖在视频层 `LiveCoreView` **之上**。
+*   **禁止分割**：严禁将屏幕分割为"上视频、下弹幕"，必须是叠加模式。
+
+##### 弹幕输入框 (Barrage Input)
+*   **位置**：固定在屏幕底部左侧，与功能按钮（礼物、连麦等）同行。
+*   **样式**：半透明圆角背景 + 占位文字「说点什么...」。
+*   **键盘适配**：
+    *   键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
+    *   视频画面 `LiveCoreView` 约束固定为 `edges.equalToSuperview()`，禁止变形或上移。
+    *   **严禁**使用 `UIScrollView.contentInsetAdjustmentBehavior` 或自动调整约束。
+
+##### 弹幕显示流 (Barrage Display Flow)
+```
+发送弹幕:
+用户输入 → 点击发送/回车 → BarrageStore.sendTextMessage(text) → 本地立即插入弹幕列表
+
+接收弹幕:
+订阅 BarrageStore.barrageState.$barrageList → 收到新消息 → 插入弹幕列表 → 滚动到底部
+```
+*   **数据源**：订阅 `BarrageStore.shared.barrageState.$barrageList`。
+*   **本地回显**：发送成功后**立即**在本地弹幕列表插入，无需等待服务器回调。
+*   **滚动行为**：新消息到达时自动滚动到底部（`scrollToRow(at: lastIndex, animated: true)`）。
+*   **消息格式**：`[昵称]: [消息内容]`，昵称使用主题色，内容使用白色。
+
+*   **礼物弹幕 (Gift Barrage)**：**如果用户需要集成礼物弹幕**，`onReceiveGift` 事件触发时，**主播端和观众端**都必须在弹幕列表（Message List）中插入礼物消息。严禁仅在观众端显示礼物文本。
+
+##### 全屏礼物动画 (Full-screen Gift Animation)
+**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
+
+*   **层级**：全屏礼物动画视图必须覆盖在 `LiveCoreView` **之上**，使用独立的 `UIView` 容器。
+*   **布局**：约束为 `edges.equalToSuperview()`，覆盖整个屏幕。
+*   **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**主播端和观众端**都必须播放全屏动画。严禁只在观众端播放。
+
+### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
+
+**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
+
+### 1. 全局视觉风格 (Global Aesthetics)
+*   **沉浸式暗黑**：直播页背景必须为 `.black`，视频层 (`LiveCoreView`) 必须**全屏铺满** (`edges.equalToSuperview()`) 且位于最底层。
+*   **安全区域**：所有悬浮 UI 必须约束在 `safeAreaLayoutGuide` 内部，严禁被刘海屏或底部 Home 条遮挡。
+*   **文字可读性**：视频之上的白色文字（如弹幕、ID）必须添加**黑色阴影** (`shadowColor = .black, offset = 0x1`)。
+*   **错误提示**：统一使用 **Toast**，禁止使用模态 Alert 打断用户。
+
+### 2. 通用组件规范 (Component Standards)
+*   **顶部胶囊 (Glass Capsule)**：
+    *   **样式**：**磨砂玻璃背景** (`UIBlurEffect.dark`) + **全圆角**。
+    *   **应用**：仅用于顶部左侧展示“主播头像+ID+热度”。
+*   **通用按钮 (Flat Buttons)**：
+    *   **样式**：**“文字 + 圆角矩形背景”**。视觉风格扁平简约，背景色为半透明黑或主题色。
+    *   **关闭按钮**：特例，使用圆形磨砂玻璃图标。
+*   **弹出面板 (Floating Panels)**：
+    *   **样式**：仅顶部大圆角 (`maskedCorners = [.layerMinXMinYCorner, .layerMaxXMinYCorner]`)。
+    *   **禁忌**：底部禁止出现非透明的实色背景块，必须保持悬浮感。
+
+### 3. 直播间布局蓝图 (Live Room Layout)
+**⚠️ 动态布局原则：仅渲染用户实际集成的功能按钮。若用户未请求某功能（如PK/美颜），严禁添加对应的空按钮**
+
+#### A. 顶部栏 (Top Bar)
+*   **左侧 [房间信息]**：使用 **磨砂胶囊** 包裹 [主播头像 | 主播昵称]。
+*   **右侧 [控制区]**：横向排列 [在线观众人数] + [关闭图标(X)]。
+
+#### B. 底部栏 (Bottom Bar) - 根据状态动态切换
+*   **预览模式 (Preview)**：
+    *   内容**向右靠拢**：[美颜] [音效] [开始直播(主按钮)]。
+*   **直播模式 (Anchor Live)**：
+    *   **左侧**：[弹幕列表(背景透明)] + [聊天输入框]。
+    *   **右侧**：功能阵列 [美颜] [音效] [连线] [PK]。
+*   **观众模式 (Audience Live)**：
+    *   **左侧**：[弹幕列表] + [聊天输入框]。
+    *   **右侧**：[礼物] [申请连麦]。
+
+### 4. 首页布局与交互 (Home Interaction)
+
+#### A. 首页参考布局
+```
+┌─────────────────────────────┐
+│       AtomicXCore 直播       │
+│                             │
+│  直播间 ID                   │
+│  ┌─────────────────────────┐│
+│  │ live_000001             ││  ← 输入框 (带左侧 Padding, 半透明背景)
+│  └─────────────────────────┘│
+│                             │
+│  主播开播                    │
+│  (点击即以 anchor001 登录)    │
+│                             │
+│  观众观看                    │
+│  (点击即以 user001 登录)      │
+│                             │
+│       [ 📋 直播列表 ]        │
+└─────────────────────────────┘
+```
+
+#### B. 隐式登录流程
+**首页不需要单独的登录按钮**，登录在点击功能按钮时自动完成：
+*   点击「主播开播」→ 使用 `anchor001` 登录 → 跳转主播页。
+*   点击「观众观看」→ 使用 `user001` 登录 → 跳转观众页。
+*   点击「直播列表」→ 使用 `user001` 登录 → 跳转列表页。
+
+---
+
+## 🎯 功能实现细节
+
+### 1. 主播开播 (`host_streaming`)
+*   **核心**：`LiveCoreView(viewType: .pushView)`
+*   **流程**：`LiveListStore.shared.createLive()`
+*   **销毁**：`deinit` 或退出页面时必须调用 `endLive()`。
+
+### 2. 观众观看 (`audience_streaming`)
+*   **核心**：`LiveCoreView(viewType: .playView)`
+*   **流程**：`LiveListStore.shared.joinLive()`
+*   **销毁**：`deinit` 或退出页面时必须调用 `leaveLive()`。
+
+### 3. 直播列表 (`live_list`)
+*   **核心**：`LiveListStore.shared.fetchLiveList()` + `UITableView/UICollectionView`
+*   **数据**：订阅 `liveState.liveList`。
+*   **跳转**：点击列表项跳转观众页，传递 `liveID`。
+
+### 4. 连麦与连线交互规范 (`co_guest` & `co_host`)
+
+#### A. 观众连麦（主播被动接收）
+*   **主播端 UI**：❌ **严禁**在底部工具栏或任何位置显示「连麦申请」列表按钮。
+*   **交互逻辑**：当收到观众连麦申请回调时，直接在屏幕中心弹出对话框（`UIAlertController`）：
+    *   **标题**：连麦申请
+    *   **内容**：收到观众 [昵称] 的连麦申请，是否接受？
+    *   **操作**：[拒绝] [接受]
+
+#### B. 主播连线面板（点击底部【连线】按钮弹出）
+*   **展现形式**：使用底部浮层面板（`UIView` 动画升起），禁止使用 `UIAlertController`。
+*   **UI 布局（严格对照图示）**：
+```
+┌─────────────────────────────────────┐
+│                                     │
+│  发起连线              [🚪 结束连线]  │  ← 红色文字
+│                                     │
+│  连线中 (2 人)                       │
+│  ┌─────────────────────────────────┐│
+│  │ [👤] 李子明 [💎20]        PK中... ││  ← 已连线用户
+│  │ [👤] 菲林娜 [💎32]        PK中... ││
+│  └─────────────────────────────────┘│
+├─────────────────────────────────────┤
+│  其他连线用户                        │
+│  ┌─────────────────────────────────┐│
+│  │ [👤] 李子明 [💎20]      [取消邀请] ││  ← 灰黑背景按钮
+│  │ [👤] 菲林娜 [💎32]      [邀请连线] ││  ← 蓝色背景按钮
+│  │ [👤] 铁柱   [💗99]      [邀请连线] ││
+│  └─────────────────────────────────┘│
+└─────────────────────────────────────┘
+```
+
+#### C. PK 按钮交互约束
+*   **前置检查**：点击底部【PK】按钮时，必须检查当前连线状态（`CoHostStore.shared.connectedUsers.isEmpty`）。
+*   **状态处理**：
+    *   **未连线**：❌ 禁止跳转，使用 Toast 提示：`"请先发起连线"`。
+    *   **已连线**：✅ 弹出 PK 邀请面板。
+
+---
+
+## 📋 Agent 最终检查清单
+
+### 🚨 必做项（缺一不可）
+- [ ] **🔴 编译验证**：已执行以下命令且输出包含 **BUILD SUCCEEDED**（此项必须在 TODO 任务中明确列出）
+  ```bash
+  xcodebuild build -scheme <项目名> -workspace <项目名>.xcworkspace -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO 2>&1 | grep -E "(error:|warning:.*\.swift|BUILD SUCCEEDED|BUILD FAILED)" | head -30
+  ```
+- [ ] **凭证注入**：已调用 `get_usersig` 生成测试凭证
+- [ ] **依赖完整**：已检查 `Podfile` 和 Info.plist 权限
+```
+
+### 代码质量检查
+- [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `LiveInfo` 字段名。
+- [ ] **超时合规**：连麦超时 5-1800s，连线超时 ≤30s。
+- [ ] **扩展合规**：音效枚举正确，美颜范围 0-9，弹幕布局覆盖且键盘适配。
+- [ ] **礼物合规**：主播和观众端均实现了全屏礼物动画显示。
+
+---
+
+## 🚨 安全提醒（代码注释模板）
+
+```swift
+/**
+ * ⚠️ 测试凭证说明
+ * - 当前 userSig 由开发工具自动生成，有效期 7 天
+ * - ❌ 生产环境严禁在客户端生成 userSig
+ * - ✅ 正式上线前必须在后端服务生成
+ * - 参考: https://cloud.tencent.com/document/product/647/17275
+ */
+```

package/resource/doc/rtcengine/faq/web/web.md

@@ -1,4 +1,4 @@
-# 最佳实践: 自动播放受限处理建议
+# 自动播放受限处理建议
 
 ## 简介
 
@@ -83,7 +83,7 @@ function showCustomDialog(event) {
 - Android Webview 关闭自动播放限制：调用 [setMediaPlaybackRequiresUserGesture(false)](https://developer.android.com/reference/android/webkit/WebSettings#setMediaPlaybackRequiresUserGesture(boolean)) 关闭自动播放限制。
 - iOS Webview 关闭自动播放限制：[设置 mediaTypesRequiringUserActionForPlayback 为 WKAudiovisualMediaTypeNone](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1851524-mediatypesrequiringuseractionfor)
 
-# 最佳实践: 应对防火墙受限
+# 应对防火墙受限
 
 ## 功能描述
 

package/resource/doc/rtcengine/web/how_to_integrated_web_sdk.md

@@ -1,4 +1,4 @@
-# 开始集成音视频通话
+# 集成音视频通话
 ## 说明
 RTC Engine Web SDK 也称为 TRTC Web SDK，是腾讯云实时音视频 Web SDK。提供 npm package name “trtc-sdk-v5”。
 
@@ -166,7 +166,7 @@ trtc.on(TRTC.EVENT.KICKED_OUT, error => {
 });
 ```
 
-# 实现互动直播连麦
+# 互动直播连麦
 
 ## 主播端
 

package/resource/doc/rtcengine/web/plugin/20-advanced-customized-capture-rendering.md

@@ -0,0 +1,84 @@
+## 功能描述
+本文主要介绍自定义采集和自定义播放渲染的高阶用法。
+
+## 自定义采集
+
+默认情况下，{@link TRTC#startLocalVideo trtc.startLocalVideo()}，{@link TRTC#startLocalAudio trtc.startLocalAudio()} 是采集并发布摄像头、麦克风，{@link TRTC#startScreenShare trtc.startScreenShare()} 是采集并发布屏幕分享。
+
+您可以通过如下参数传入自定义采集的 MediaStreamTrack：
+
+- `trtc.startLocalAudio({ option: { audioTrack }})`
+  - 传入该参数后，SDK 不会采集麦克风，使用自定义 audioTrack 推流。
+  - 若同时设置 microphoneId，audioTrack，则按优先级（microphoneId>audioTrack）进行采集，但不建议混用。
+- `trtc.startLocalVideo({ option: { videoTrack }})`
+  - 传入该参数后，SDK 不会采集摄像头，自定义采集的 videoTrack 将会以主流的形式推流。
+  - 若同时设置 cameraId，useFrontCamera，videoTrack，则按优先级（cameraId>useFrontCamera>videoTrack）进行采集，但不建议混用。
+- `trtc.startScreenShare({ option: { videoTrack }})`
+  - 传入该参数后，SDK 不会采集屏幕分享，自定义采集的 videoTrack 将会以辅流的形式推流。
+
+获取 audioTrack，videoTrack 通常有以下几种方式：
+
+- 通过 [getUserMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) 采集摄像头和麦克风。
+- 通过 [getDisplayMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia) 采集屏幕分享。
+- 通过 [videoElement.captureStream](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/captureStream) 采集 video 标签中正在播放的音视频。
+- 通过 [canvas.captureStream](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/captureStream) 采集 canvas 画布中的动画。
+
+### 采集 video 标签中正在播放的视频
+
+```javascript
+// 检测您当前的浏览器是否支持从 video 元素采集
+if (!HTMLVideoElement.prototype.captureStream) {
+  console.log('your browser does not support capturing stream from video element');
+  return
+}
+// 获取您页面在播放视频的 video 标签 
+const video = document.getElementByID('your-video-element-ID');
+// 从播放的视频采集视频流
+const stream = video.captureStream();
+const audioTrack = stream.getAudioTracks()[0];
+const videoTrack = stream.getVideoTracks()[0];
+
+trtc.startLocalVideo({ option:{ videoTrack } });
+trtc.startLocalAudio({ option:{ audioTrack } });
+```
+
+### 采集 canvas 中的画面
+
+```javascript
+// 检测您当前的浏览器是否支持从 canvas 元素采集
+if (!HTMLCanvasElement.prototype.captureStream) {
+  console.log('your browser does not support capturing stream from canvas element');
+  return
+}
+// 获取您的 canvas 标签 
+const canvas = document.getElementByID('your-canvas-element-ID');
+
+// 从 canvas 采集 15 fps 的视频流
+const fps = 15;
+const stream = canvas.captureStream(fps);
+const videoTrack = stream.getVideoTracks()[0];
+
+trtc.startLocalVideo({ option:{ videoTrack } });
+```
+
+## 自定义播放渲染
+
+正常情况下，在  {@link TRTC#startLocalVideo startLocalVideo()}  {@link TRTC#startRemoteVideo startRemoteVideo()} 时，传入 view 参数，SDK 会在指定的 element 标签下，创建 `video` 标签播放视频画面。
+
+如果您需要自定义播放渲染，不需要 SDK 播放视频，可参考如下步骤实现：
+
+- 在 startLocalVideo 或 startRemoteVideo 方法调用时不填 view 参数或 view 参数传入 null
+- 监听 TRTC.EVENT.TRACK 事件，每当有新的 MediaStreamTrack 时，SDK 会通过该事件通知。
+- 在上述事件触发时，拿到最新的 MediaStreamTrack，此时您可以使用自己的播放器进行视频的播放渲染。
+- 使用这种自定义播放渲染方式后，{@link module:EVENT.VIDEO_PLAY_STATE_CHANGED VIDEO_PLAY_STATE_CHANGED} 事件将不会被触发，您需要自行监听视频轨道 [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack) 的 `mute/unmute/ended` 等事件来判断当前视频数据流的状态。
+
+### 自定义渲染本地视频
+
+```javascript
+trtc.on(TRTC.EVENT.TRACK, event => {
+  const isLocal = event.userId === ''; // userId === '' means event.track is a local track, otherwise it's a remote track
+  const isSubStream = event.streamType === TRTC.TYPE.STREAM_TYPE_SUB; // Usually the sub stream is a screen-sharing video stream.
+  const mediaStreamTrack = event.track; 
+  const kind = event.track.kind; // audio or video
+})
+```

package/resource/doc/rtcengine/web/plugin/21-advanced-auto-play-policy.md

@@ -0,0 +1,86 @@
+## 简介
+
+浏览器为了防止网页自动播放音视频对用户造成干扰，对音视频的自动播放功能做了限制：**在用户与网页产生交互（例如点击、触摸页面等）之前，网页将被禁止播放带有声音的媒体。在 iOS 10+ 中，如果开启了省电模式，[无声音的媒体也会被禁止播放](https://discussions.apple.com/thread/254541299?sortBy=best)。**
+
+受上述浏览器自动播放策略影响，在使用 TRTC Web SDK 时，可能会出现播放无声的问题。最常见的场景是：您的产品设计中，支持用户刷新页面后，无需用户点击，可自动进房拉流播放。
+
+本文主要介绍**如何解决因自动播放策略限制，导致播放失败**的问题。
+
+## 方案一：使用 SDK 提供的自动播放弹窗
+
+默认情况下，当出现自动播放失败时，SDK 会弹窗引导用户与页面产生交互。当产生交互后，SDK 会主动调用接口恢复播放。
+
+- 优点：业务侧无需做任何处理，简单高效。
+
+- 缺点：SDK 提供的弹窗不一定符合业务产品设计要求，此时可考虑使用方案二。
+
+SDK 提供的弹窗适配桌面端和移动端浏览器，样式如下：
+
+<div style="display:flex;align-items:center;">
+  <img src="./assets/autoplay-dialog-pc-cn.png" style="width:40%;max-width:450px;margin-right:16px;" />
+  <img src="./assets/autoplay-dialog-cn.png" style="width:30%;max-width:300px;" />
+</div>
+
+- SDK 会根据 [navigator.language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) 的值来切换中英文弹窗提示。
+
+- 当用户点击"确认"时，SDK 自动调用相关接口来恢复播放。
+
+- 为尽可能保证弹窗处于最上层展示，其 z-index 值为 1500。
+
+## 方案二：自定义处理自动播放限制
+
+如果您希望完全控制自动播放失败时的用户体验，可以按照以下步骤来实现：
+
+### 步骤 1：关闭 SDK 默认弹窗
+
+在调用 [trtc.enterRoom](./TRTC.html#enterRoom) 接口时，将 `enableAutoPlayDialog` 参数设置为 `false`：
+
+```javascript
+await trtc.enterRoom({
+  // ... 其他参数
+  enableAutoPlayDialog: false
+});
+```
+
+### 步骤 2：监听自动播放失败事件（必做）
+
+监听 [AUTOPLAY_FAILED](./module-EVENT.html#.AUTOPLAY_FAILED) 事件来处理自动播放失败的情况。SDK 会自动监听用户的点击行为，在用户点击后自动恢复播放。
+
+```javascript
+trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, event => {
+  // 在此处添加您的自定义处理逻辑
+  // 例如：显示自定义提示框，引导用户点击页面
+});
+```
+
+### 步骤 3：主动恢复播放（可选）
+
+> 从版本 5.9.0 开始支持
+
+在某些特殊场景下（如在 iframe 中或使用特定前端框架时），您可能需要主动调用恢复播放方法。此时可以使用事件中提供的 `resume` 方法：
+
+```javascript
+trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, (event) => {
+  showCustomDialog(event);
+});
+function showCustomDialog(event) {
+  const { userId, resume } = event;
+  // 受限的用户 id 为 userId，resume 是恢复这个用户播放的函数
+  // 需要显示一个自定义按钮，提示 userId 播放受限，在按钮点击回调里调用 'resume()'
+}
+```
+
+### 重要提示
+
+1. 某些浏览器可能在每次播放前都会检查用户交互状态，因此可能多次触发自动播放失败事件。
+
+2. 在 iOS 微信浏览器和小程序 webview 中有特殊要求：
+   - 首次播放远端流时，必须在用户点击事件的回调函数中直接调用播放接口
+   - 不能使用 setTimeout 等异步方式调用播放接口，否则会导致播放失败
+
+## Webview 中关闭自动播放策略限制
+
+在 Android 和 iOS Webview 中的默认自动播放策略可能和浏览器中的不一致，您可以参考如下文档，在您的 App 中关闭自动播放限制。
+
+- Android Webview 关闭自动播放限制：调用 [setMediaPlaybackRequiresUserGesture(false)](https://developer.android.com/reference/android/webkit/WebSettings#setMediaPlaybackRequiresUserGesture(boolean)) 关闭自动播放限制。
+- iOS Webview 关闭自动播放限制：[设置 mediaTypesRequiringUserActionForPlayback 为 WKAudiovisualMediaTypeNone](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1851524-mediatypesrequiringuseractionfor)