@tencent-rtc/mcp 1.3.4 → 1.3.6

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

@@ -0,0 +1,454 @@
+# Native Live AtomicXCore Code Generation Workflow Instructions (iOS)
+
+## 🚨 Core Principles (Highest Priority)
+
+**The Agent MUST ensure that the generated code compiles and runs successfully. Delivering uncompilable code to the user is strictly prohibited!**
+
+### ⚠️ Mandatory Compilation Verification (Must be executed, cannot be omitted)
+
+**🚫 Prohibited Actions**:
+- ❌ DO NOT assume code is correct based only on `read_lints` checks.
+- ❌ DO NOT use `grep` to filter compilation output (this will cause commands to be skipped).
+- ❌ DO NOT deliver code without compilation verification.
+
+**✅ The Only Correct Way to Verify**:
+
+```bash
+# Step 1: Install dependencies (if needed)
+cd <ProjectDir> && pod install
+
+# Step 2: Compile verification (use tail to limit output)
+cd <ProjectDir> && xcodebuild build \
+  -scheme <SchemeName> \
+  -workspace <WorkspaceName>.xcworkspace \
+  -destination 'generic/platform=iOS' \
+  CODE_SIGNING_ALLOWED=NO 2>&1 | tail -150
+```
+
+**Judging Criteria**:
+- ✅ Output contains `BUILD SUCCEEDED` → Compilation passed, ready for delivery.
+- ❌ Output contains `BUILD FAILED` or `error:` → Must fix and recompile.
+
+**Common Errors & Fixes**:
+| Error Keyword | Reason | Fix |
+|---------------|--------|-----|
+| `No such module 'xxx'` | Missing Pod dependency | Add to Podfile and run `pod install`. |
+| `Cannot find 'xxx' in scope` | Missing import | Add `import xxx`. |
+| `Use of unresolved identifier` | Incorrect API name | Consult documentation for correct API. |
+| `NSCameraUsageDescription` | Missing Info.plist permission | Add permission description. |
+
+**Verification Loop (Must Follow)**:
+```
+Execute Compilation → Failure → Analyze Error → Fix Code → Re-execute Compilation → ... → BUILD SUCCEEDED → Deliver
+```
+
+---
+
+## 📋 Instruction Purpose & Architecture
+
+Provides the Agent with a **code generation blueprint** for implementing core features of Native (iOS) Live AtomicXCore.
+
+**Core Architecture**:
+* **Container**: `LiveCoreView` (View layer)
+* **State**: `Store` (Data-driven)
+* **Events**: `Publisher` (Combine subscription)
+
+**Feature Dependency Logic (Important)**:
+1. **Base First**: Basic live streaming (Broadcasting/Viewing/List) must be completed first using the base tool (`get_native_live_uikit_integration`).
+2. **Interaction Overlay**: If requirements include "Co-guesting", "PK", or "Audience List", the interaction tool (`get_native_live_uikit_interaction`) must be called **after** basic features are completed.
+3. **Empty Project Handling**: If the user requests interaction features in an empty project, the Agent **MUST implement basic features first**, then add interaction capabilities.
+
+---
+
+## ⚙️ Automated Workflow Steps (Must be created as TODO tasks)
+
+**🚨 The Agent MUST create the following steps as a TODO task list, complete them one by one, and check them off:**
+
+### Step 1: Preparation
+1. **Generate Credentials**: Call the `get_usersig` tool to generate test credentials.
+    * Host: `anchor001`, `anchor002`, `anchor003`
+    * Audience: `user001`, `user002`, `user003`
+2. **Environment Check**: Check `Podfile` and add the following dependency if missing:
+    ```ruby
+    pod 'AtomicXCore'
+    ```
+3. **Permission Injection**: Add Camera and Microphone permission descriptions in `Info.plist`:
+    ```xml
+    <key>NSCameraUsageDescription</key>
+    <string>Needs camera access to record video.</string>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>Needs microphone access to record audio.</string>
+    ```
+
+### Step 2: Code Generation
+**PRIORITIZE and EXCLUSIVELY** use the **real-time documentation content** returned by this tool for code generation.
+* **Host Only**: Generate `AnchorViewController`.
+* **Audience Only**: Generate `AudienceViewController`.
+* **Host + Audience**: Generate `MainViewController` (Entry selection) + `AnchorViewController` + `AudienceViewController`.
+
+### Step 3: 🚨 Compilation Verification (Mandatory, cannot be skipped)
+**This step MUST be executed as a standalone TODO task, cannot be omitted or merged!**
+
+**Execution Command**:
+```bash
+cd <ProjectDir>/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
+```
+
+**Judgment & Handling**:
+* Output contains **BUILD SUCCEEDED** → Proceed to Step 4.
+* Output contains **BUILD FAILED** or **error:** → Analyze error → Fix code → **Re-execute this command**, loop until success.
+
+### Step 4: Deliver Results
+Deliver the code after confirming compilation passes.
+
+---
+
+## 🚫 Code Generation Constraints (Strictly Follow)
+
+### 1. General Code Constraints
+* **Strictly Prohibited to Modify Imports**: Import paths in the documentation are verified; DO NOT modify them.
+* **Strictly Prohibited to Fabricate APIs**: If an API is not in the documentation, DO NOT invent method or parameter names.
+* **MUST Consult API Docs**: For data model fields (e.g., `LiveInfo`), visit the documentation to confirm field names (e.g., confirm it's `liveOwner.userName` and not `name`).
+
+### 2. 🧩 Store & Publisher Management Constraints (Lifecycle Safety)
+**Core Reason**: SDK uses Combine's `Publisher` for state subscription. Incorrect lifecycle management leads to listener failure or memory leaks.
+
+* **Subscription Management Principle**: All `AnyCancellable` **MUST be declared as member variables** of the ViewController in `cancellableSet`.
+* **No Ignoring Return Values**: Prohibited to not store the `AnyCancellable` returned by `.sink {}`.
+* **Pairing Principle**: Setup subscriptions in `viewDidLoad`; they will be automatically released when the `cancellableSet` is deinitialized.
+
+### 3. ⏱️ Timeout Limits (Critical)
+**Strictly adhere to the following parameter limits, prioritizing values from documentation examples:**
+
+#### A. Co-guesting (`CoGuestStore`)
+* **Rules**:
+    * Optional parameter; if not filled, timeout is not checked.
+    * If filled, the range MUST be between **5 - 1800 seconds**.
+* **Correct Examples**:
+    ```swift
+    // ✅ Recommended: Follow doc examples (e.g., 30s)
+    CoGuestStore.shared.applyForSeat(seatIndex: -1, timeout: 30) { ... }
+    // ✅ Valid: No timeout check
+    CoGuestStore.shared.applyForSeat(seatIndex: -1, timeout: 0) { ... }
+    ```
+* **Incorrect Examples**: ❌ `timeout: 3` (too short), ❌ `timeout: 2000` (too long).
+
+#### B. Co-hosting/PK (`CoHostStore`)
+* **Rules**:
+    * **Maximum 30 seconds** (Hard limit).
+* **Correct Examples**:
+    ```swift
+    // ✅ Recommended: Use maximum value
+    CoHostStore.shared.requestHostConnection(..., timeout: 30) { ... }
+    ```
+* **Incorrect Examples**: ❌ `timeout: 60` (will cause request failure).
+
+### 4. 🎨 Extra Feature Constraints (Beauty/Audio/UI)
+
+#### A. Audio Effects
+* **Voice Changer Enum (`AudioChangerType`)**:
+    * ✅ **Allowed**: `.child, .littleGirl, .man, .ethereal`, etc.
+    * ❌ **Prohibited**: `.uncle, .loli, .girl, .boy` (deprecated or incorrect).
+* **Reverb Enum (`AudioReverbType`)**:
+    * ✅ **Allowed**: `.ktv, .smallRoom, .metallic`, etc.
+    * ❌ **Prohibited**: `.room, .hall, .low`.
+
+#### B. Beauty
+* **Parameter Range**: **0.0 - 9.0** (Float).
+    * ❌ NOT 0-1 (Float), and NOT 0-100 (Int).
+* **UI Mapping Formula**: `sliderValue / 100.0 * 9.0`.
+
+#### C. Barrage, Gift & Layout (Barrage, Gift & UI)
+* **Layering Requirements**: Barrage list and full-screen gift animations MUST overlay **on top** of the video layer `LiveCoreView` using a `UIView`.
+* **Split Screen Prohibited**: Strictly prohibited to split the screen (e.g., video on top, barrage at bottom); MUST use overlay mode.
+
+##### Barrage Input
+* **Position**: Fixed at the bottom left of the screen, in the same row as function buttons (Gift, Co-guest, etc.).
+* **Style**: Semi-transparent rounded background + placeholder text "Say something...".
+* **Keyboard Adaptation**:
+    * When the keyboard is raised, the input box **must remain in its original position** and is prohibited from moving up with the keyboard.
+    * The `LiveCoreView` constraint must be fixed to `edges.equalToSuperview()`, prohibiting distortion or upward shifting.
+    * **Strictly Prohibited** to use `UIScrollView.contentInsetAdjustmentBehavior` or automatic constraint adjustments.
+
+##### Barrage Display Flow
+```
+Sending Barrage:
+User input → Click Send/Enter → BarrageStore.sendTextMessage(text) → Insert into local barrage list immediately
+
+Receiving Barrage:
+Subscribe to BarrageStore.barrageState.$barrageList → New message received → Insert into barrage list → Scroll to bottom
+```
+* **Data Source**: Subscribe to `BarrageStore.shared.barrageState.$barrageList`.
+* **Local Echo**: Insert into the local barrage list **immediately** after successful sending, without waiting for server callback.
+* **Scrolling Behavior**: Automatically scroll to the bottom when a new message arrives (`scrollToRow(at: lastIndex, animated: true)`).
+* **Message Format**: `[Nickname]: [Message Content]`, nickname uses theme color, content uses white.
+
+* **Gift Barrage**: **If the user needs gift barrage integration**, when `onReceiveGift` is triggered, a gift message MUST be inserted into the barrage list on **both host and audience sides**. DO NOT display only on the audience side.
+
+##### Full-screen Gift Animation
+**⚠️ MANDATORY**: Full-screen gift animation is a **mandatory requirement** when integrating gift features and cannot be omitted.
+
+* **Layering**: The full-screen gift animation view MUST overlay **on top** of the `LiveCoreView` using a separate `UIView` container.
+* **Layout**: Constrained to `edges.equalToSuperview()`, covering the entire screen.
+* **Dual-side Sync**: Upon receiving the `.onReceiveGift` event, the full-screen animation MUST be played on **both host and audience sides**. Playing only on the audience side is strictly prohibited.
+
+##### ⚠️ SVGA Animation Playback (Mandatory use of SVGAPlayer, Strictly Prohibited to use UIImageView)
+**Strictly Prohibited to use UIImageView/Kingfisher to load .svga files**. SVGA is a vector animation format, not a normal image; UIImageView cannot play it.
+
+* **Dependency Configuration** (Podfile):
+```ruby
+pod 'SVGAPlayer'
+```
+
+* **Core Playback Logic (MUST use SVGAParser + SVGAPlayer)**:
+```swift
+import SVGAPlayer
+
+// ❌ Incorrect: Using UIImageView to load SVGA (cannot play animation)
+// imageView.kf.setImage(with: URL(string: gift.resourceURL))
+
+// ✅ Correct: Using SVGAParser to parse + SVGAPlayer to play
+svgaParser.parse(with: url) { [weak self] videoItem in
+    guard let videoItem = videoItem else { return }
+    self?.svgaPlayer.videoItem = videoItem
+    self?.svgaPlayer.startAnimation()  // Start playing animation
+}
+```
+
+* **Full Implementation Example (Within ViewController)**:
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+import SVGAPlayer
+
+class LiveRoomViewController: UIViewController, SVGAPlayerDelegate {
+    private var cancellables = Set<AnyCancellable>()
+    
+    // SVGA Player Components
+    private let svgaPlayer = SVGAPlayer()
+    private let svgaParser = SVGAParser()
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        setupSVGAPlayer()
+        subscribeGiftEvents()
+    }
+    
+    // 1. Initialize SVGAPlayer
+    private func setupSVGAPlayer() {
+        svgaPlayer.delegate = self
+        svgaPlayer.loops = 1              // Play once
+        svgaPlayer.clearsAfterStop = true // Clear automatically after stopping
+        svgaPlayer.frame = view.bounds    // Full screen
+        svgaPlayer.isHidden = true
+        view.addSubview(svgaPlayer)
+        // Ensure svgaPlayer is at the top level
+        view.bringSubviewToFront(svgaPlayer)
+    }
+    
+    // 2. Subscribe to Gift Events
+    private func subscribeGiftEvents() {
+        let giftStore = GiftStore.create(liveID: liveId)
+        giftStore.giftEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                guard case .onReceiveGift(_, let gift, let count, let sender) = event else { return }
+                
+                // Play full-screen gift animation
+                if !gift.resourceURL.isEmpty, let url = URL(string: gift.resourceURL) {
+                    self?.playGiftAnimation(from: url)
+                }
+                
+                // (Optional) Insert gift message into barrage list
+                // let tipText = "\(sender.userName) sent \(gift.name) x \(count)"
+                // barrageStore.appendLocalTip(message: tipText)
+            }
+            .store(in: &cancellables)
+    }
+    
+    // 3. Use SVGAParser to parse and play animation
+    private func playGiftAnimation(from url: URL) {
+        svgaParser.parse(with: url, completionBlock: { [weak self] videoItem in
+            guard let self = self, let videoItem = videoItem else { return }
+            DispatchQueue.main.async {
+                self.svgaPlayer.videoItem = videoItem
+                self.svgaPlayer.isHidden = false
+                self.svgaPlayer.startAnimation()
+            }
+        }, failureBlock: { error in
+            print("SVGA Parse Failed: \(error?.localizedDescription ?? "")")
+        })
+    }
+    
+    // 4. SVGAPlayerDelegate - Playback Finished Callback
+    func svgaPlayerDidFinishedAnimation(_ player: SVGAPlayer!) {
+        svgaPlayer.isHidden = true
+    }
+}
+```
+
+* **Key Checkpoints**:
+    1. ✅ Import `import SVGAPlayer`
+    2. ✅ Use `SVGAParser().parse(with: url)` to parse animation URL
+    3. ✅ Use `SVGAPlayer().startAnimation()` to play animation
+    4. ✅ Implement `SVGAPlayerDelegate` to handle playback end
+    5. ❌ PROHIBITED to use `UIImageView`/`Kingfisher`/`SDWebImage` to load .svga files
+
+### 🎨 Default UI/UX Design & Interaction Specifications (Only applies if user doesn't specify)
+
+**⚠️ Note: The following specifications are only executed as default standards when the user does not provide specific UI design or requirements.**
+
+### 1. Global Aesthetics
+* **Immersive Dark**: The background of the live page must be `.black`, and the video layer (`LiveCoreView`) must **fill the entire screen** (`edges.equalToSuperview()`) and be at the bottom layer.
+* **Safe Area**: All floating UIs must be constrained within the `safeAreaLayoutGuide`, strictly prohibiting being blocked by notches or the bottom Home bar.
+* **Text Readability**: White text above the video (e.g., barrage, ID) must have a **black shadow** (`shadowColor = .black, offset = 0x1`).
+* **Error Prompts**: Use **Toast** uniformly; prohibit the use of modal Alerts that interrupt the user.
+
+### 2. Component Standards
+* **Glass Capsule (Top)**:
+    * **Style**: **Frosted glass background** (`UIBlurEffect.dark`) + **full rounded corners**.
+    * **Application**: Only used at the top left to display "Host Avatar + ID + Popularity".
+* **Flat Buttons**:
+    * **Style**: **"Text + Rounded Rectangle Background"**. Minimalist flat design, background color is semi-transparent black or theme color.
+    * **Close Button**: Special case, use a circular frosted glass icon.
+* **Floating Panels**:
+    * **Style**: Only top rounded corners (`maskedCorners = [.layerMinXMinYCorner, .layerMaxXMinYCorner]`).
+    * **Taboo**: Solid color backgrounds at the bottom are prohibited; floating feeling must be maintained.
+
+### 3. Live Room Layout Blueprint
+**⚠️ Dynamic Layout Principle: Only render function buttons that the user has actually integrated. If a user did not request a feature (e.g., PK/Beauty), DO NOT add corresponding empty buttons.**
+
+#### A. Top Bar
+* **Left [Room Info]**: Wrapped in a **frosted capsule** [Host Avatar | Host Nickname].
+* **Right [Control Area]**: Horizontally arranged [Online Audience Count] + [Close Icon (X)].
+
+#### B. Bottom Bar - Dynamically switches based on state
+* **Preview Mode**:
+    * Content **aligned to the right**: [Beauty] [Audio Effects] [Start Live (Main Button)].
+* **Anchor Live Mode**:
+    * **Left**: [Barrage List (Transparent Background)] + [Chat Input Box].
+    * **Right**: Function array [Beauty] [Audio Effects] [Co-hosting] [PK].
+* **Audience Live Mode**:
+    * **Left**: [Barrage List] + [Chat Input Box].
+    * **Right**: [Gift] [Apply for Co-guesting].
+
+### 4. Home Layout & Interaction
+
+#### A. Home Reference Layout
+```
+┌─────────────────────────────┐
+│       AtomicXCore Live       │
+│                             │
+│  Live Room ID                │
+│  ┌─────────────────────────┐│
+│  │ live_000001             ││  ← Input Box (with left padding, semi-transparent background)
+│  └─────────────────────────┘│
+│                             │
+│  Host Broadcasting           │
+│  (Click to login as anchor001)│
+│                             │
+│  Audience Viewing            │
+│  (Click to login as user001)  │
+│                             │
+│       [ 📋 Live List ]       │
+└─────────────────────────────┘
+```
+
+#### B. Implicit Login Flow
+**No separate login button is required on the home page**; login is automatically completed when a function button is clicked:
+* Click "Host Broadcasting" → Login using `anchor001` → Jump to host page.
+* Click "Audience Viewing" → Login using `user001` → Jump to audience page.
+* Click "Live List" → Login using `user001` → Jump to list page.
+
+---
+
+## 🎯 Implementation Details
+
+### 1. Host Broadcasting (`host_streaming`)
+* **Core**: `LiveCoreView(viewType: .pushView)`
+* **Flow**: `LiveListStore.shared.createLive()`
+* **Cleanup**: `deinit` or when exiting the page, `endLive()` MUST be called.
+
+### 2. Audience Viewing (`audience_streaming`)
+* **Core**: `LiveCoreView(viewType: .playView)`
+* **Flow**: `LiveListStore.shared.joinLive()`
+* **Cleanup**: `deinit` or when exiting the page, `leaveLive()` MUST be called.
+
+### 3. Live List (`live_list`)
+* **Core**: `LiveListStore.shared.fetchLiveList()` + `UITableView/UICollectionView`
+* **Data**: Subscribe to `liveState.liveList`.
+* **Navigation**: Clicking a list item navigates to the audience page, passing the `liveID`.
+
+### 4. Co-guest & Co-host Interaction Specifications (`co_guest` & `co_host`)
+
+#### A. Audience Co-guesting (Host passively receives)
+* **Host UI**: ❌ **Strictly prohibited** to display a "Co-guest Application" list button in the bottom toolbar or anywhere else.
+* **Interaction Logic**: Upon receiving a co-guest application callback, pop up a dialog (`UIAlertController`) directly in the center of the screen:
+    * **Title**: Co-guest Application
+    * **Content**: Received a co-guest application from audience [Nickname], accept?
+    * **Operations**: [Decline] [Accept]
+
+#### B. Host Co-hosting Panel (Pops up when clicking bottom [Co-host] button)
+* **Presentation**: Use a bottom floating panel (`UIView` animated up); prohibit `UIAlertController`.
+* **UI Layout (Strictly follow illustration)**:
+```
+┌─────────────────────────────────────┐
+│                                     │
+│  Initiate Connection   [🚪 End Co-host]  │  ← Red text
+│                                     │
+│  Connected (2 persons)               │
+│  ┌─────────────────────────────────┐│
+│  │ [👤] Li Ziming [💎20]      PK...   ││  ← Connected users
+│  │ [👤] Filinna  [💎32]      PK...   ││
+│  └─────────────────────────────────┘│
+├─────────────────────────────────────┤
+│  Other Live Users                   │
+│  ┌─────────────────────────────────┐│
+│  │ [👤] Li Ziming [💎20]  [Cancel Inv] ││  ← Gray-black background button
+│  │ [👤] Filinna  [💎32]  [Invite]      ││  ← Blue background button
+│  │ [👤] Tie Zhu   [💗99]  [Invite]      ││
+│  └─────────────────────────────────┘│
+└─────────────────────────────────────┘
+```
+
+#### C. PK Button Interaction Constraints
+* **Pre-check**: When clicking the bottom [PK] button, current connection status must be checked (`CoHostStore.shared.connectedUsers.isEmpty`).
+* **Status Handling**:
+    * **Not connected**: ❌ Prohibit jump, show Toast: `"Please initiate co-hosting first"`.
+    * **Connected**: ✅ Pop up PK invitation panel.
+
+---
+
+## 📋 Agent Final Checklist
+
+### 🚨 Must-do Items (None can be omitted)
+- [ ] **🔴 Compilation Verification**: Executed the following command and output contains **BUILD SUCCEEDED** (This item must be explicitly listed in the TODO task)
+  ```bash
+  xcodebuild build -scheme <ProjectName> -workspace <ProjectName>.xcworkspace -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO 2>&1 | grep -E "(error:|warning:.*\.swift|BUILD SUCCEEDED|BUILD FAILED)" | head -30
+  ```
+- [ ] **Credential Injection**: Called `get_usersig` to generate test credentials.
+- [ ] **Dependencies Complete**: Checked `Podfile` and Info.plist permissions.
+
+### Code Quality Check
+- [ ] **API Accuracy**: Imports not modified, APIs not fabricated, `LiveInfo` field names verified.
+- [ ] **Timeout Compliance**: Co-guesting 5-1800s, Co-hosting ≤30s.
+- [ ] **Extra Feature Compliance**: Audio enums correct, beauty range 0-9, barrage layout overlays, and keyboard adaptation.
+- [ ] **Gift Compliance**: Full-screen gift animations implemented on both host and audience sides.
+
+---
+
+## 🚨 Security Reminder (Code Comment Template)
+
+```swift
+/**
+ * ⚠️ Test Credential Warning
+ * - Current userSig is automatically generated by development tools and is valid for 7 days.
+ * - ❌ PROHIBITED from generating userSig on the client side in production.
+ * - ✅ userSig MUST be generated on a backend service before official launch.
+ * - Reference: https://trtc.io/document/35166?product=live&menulabel=uikit&platform=ios
+ */
+```

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

@@ -0,0 +1,87 @@
+
+## Function Description
+This article mainly introduces the advanced usage of custom capture and custom rendering.
+
+## Custom Capture
+
+By default, {@link TRTC#startLocalVideo startLocalVideo()} and {@link TRTC#startLocalAudio startLocalAudio()} will start camera and microphone, {@link TRTC#startScreenShare trtc.startScreenShare()} will start screen sharing.
+
+If you need to customize the capture:
+
+- `trtc.startLocalAudio({ option: { audioTrack }})`
+  - After passing this parameter, the SDK will not capture the microphone and use the custom audioTrack to publish the stream.
+  - If microphoneId and audioTrack are set at the same time, the capture priority is microphoneId > audioTrack, but it is not recommended to mix them.
+- `trtc.startLocalVideo({ option: { videoTrack }})`
+  - After passing this parameter, the SDK will not capture the camera, the custom captured videoTrack will be published as main stream.
+  - If you set cameraId, useFrontCamera, videoTrack at the same time, the capture priority is cameraId > useFrontCamera > videoTrack, but it is not recommended to mix them.
+- `trtc.startScreenShare({ option: { videoTrack }})`
+  - After passing this parameter, the SDK will not capture screen share, the custom captured videoTrack will be published as sub stream.
+
+There are usually several ways to obtain audioTrack and videoTrack:
+
+- Use [getUserMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) to capture the camera and microphone.
+- Use [getDisplayMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia) to capture screen sharing.
+- Use [videoElement.captureStream](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/captureStream) to capture the audio and video being played in the video tag.
+- Use [canvas.captureStream](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/captureStream) to capture the animation in the canvas.
+
+### Capture the video being played in the video tag
+
+```javascript
+// Check if your current browser supports capturing streams from video elements
+if (!HTMLVideoElement.prototype.captureStream) {
+  console.log('your browser does not support capturing stream from video element');
+  return
+}
+// Get the video tag that is playing video on your page
+const video = document.getElementByID('your-video-element-ID');
+// Capture the video stream from the playing video
+const stream = video.captureStream();
+const audioTrack = stream.getAudioTracks()[0];
+const videoTrack = stream.getVideoTracks()[0];
+
+trtc.startLocalVideo({ option:{ videoTrack } });
+trtc.startLocalAudio({ option:{ audioTrack } });
+```
+
+### Capture the animation in the canvas
+
+```javascript
+// Check if your current browser supports capturing streams from canvas elements
+if (!HTMLCanvasElement.prototype.captureStream) {
+  console.log('your browser does not support capturing stream from canvas element');
+  return
+}
+// Get your canvas tag
+const canvas = document.getElementByID('your-canvas-element-ID');
+
+// Capture a 15 fps video stream from the canvas
+const fps = 15;
+const stream = canvas.captureStream(fps);
+const videoTrack = stream.getVideoTracks()[0];
+
+trtc.startLocalVideo({ option:{ videoTrack } });
+```
+
+
+## Custom Rendering
+
+By default, when calling {@link TRTC#startLocalVideo startLocalVideo()} or {@link TRTC#startRemoteVideo startRemoteVideo()}, you need to pass in the view parameter. The SDK will create a `video` tag under the specified element tag to play the video.
+
+If you need to customize the rendering, and do not need the SDK to play the video, you can refer to the following steps:
+
+- Do not fill in the view parameter or pass in null when calling the startLocalVideo or startRemoteVideo method.
+- Listen the TRTC.EVENT.TRACK, SDK will fires this event when there has a new MediaStreamTrack, then you can get the MediaStreamTrack for custom rendering.
+- Use your own player for video rendering.
+- If you using the custom rendering, the {@link module:EVENT.VIDEO_PLAY_STATE_CHANGED VIDEO_PLAY_STATE_CHANGED} event will not be fired. You need to listen to the `mute/unmute/ended` events of the video track [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack) to determine the status of the current video data stream.
+- For remote video, you also need to listen to the {@link module:EVENT.REMOTE_VIDEO_AVAILABLE REMOTE_VIDEO_AVAILABLE} and {@link module:EVENT.REMOTE_VIDEO_UNAVAILABLE REMOTE_VIDEO_UNAVAILABLE} events to handle the lifecycle of remote video.
+
+### Custom rendering by TRTC.EVENT.TRACK
+
+```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,87 @@
+## Introduction
+
+In order to prevent web pages from automatically playing audio and video and causing interference to users, browsers have restricted the automatic playback function of audio and video: **before the user interacts with the web page (such as clicking, touching the page, etc.), the web page will be prohibited from playing media with sound. In iOS 10+, if low power mode is enabled, media without sound will also be prohibited from playing.**
+
+Affected by the above browser autoplay policy, when using the TRTC Web SDK, there may be problems with playing silently. The most common scenario is: in your product design, support users to automatically enter the room and pull the stream for playback without the need for users to click after refreshing the page.
+
+This article mainly introduces **how to solve the problem of playback failure caused by the restriction of autoplay policy**.
+
+## Solution 1: Use the SDK's autoplay popup window
+
+By default, when autoplay fails, the SDK will pop up to guide the user to interact with the page. After the interaction occurs, the SDK will actively call the interface to resume playback.
+
+- Advantages: The business side does not need to do anything, simple and efficient.
+
+- Disadvantages: The popup window provided by the SDK may not meet the design requirements of the business product. At this time, you can consider using Solution 2.
+
+The popup window provided by the SDK is adapted to desktop and mobile browser, and the style is as follows:
+
+<div style="display:flex;align-items:center;">
+  <img src="./assets/autoplay-dialog-pc-en.png" style="width:40%;max-width:450px;margin-right:16px;" />
+  <img src="./assets/autoplay-dialog-en.png" style="width:30%;max-width:300px;" />
+</div>
+
+
+- The SDK will switch the Chinese and English popup prompts according to the value of [navigator.language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language).
+
+- When the user clicks "OK", the SDK automatically calls the relevant interface to resume playback.
+
+- In order to ensure that the popup window is displayed on the top layer as much as possible, its z-index value is 1500.
+
+## Solution 2: Custom handling of autoplay restrictions
+
+If you want to have complete control over the user experience when autoplay fails, you can follow these steps:
+
+### Step 1: Disable SDK default popup
+
+Set the `enableAutoPlayDialog` parameter to `false` when calling the [TRTC.enterRoom](./TRTC.html#enterRoom) interface:
+
+```javascript
+await trtc.enterRoom({
+  // ... other parameters
+  enableAutoPlayDialog: false
+});
+```
+
+### Step 2: Listen for autoplay failure events (Required)
+
+Listen to the [AUTOPLAY_FAILED](./module-EVENT.html#.AUTOPLAY_FAILED) event to handle autoplay failures. The SDK will automatically monitor user click events and resume playback after the user clicks.
+
+```javascript
+trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, event => {
+  // Add your custom handling logic here
+  // For example: display a custom prompt to guide users to click on the page
+});
+```
+
+### Step 3: Actively resume playback (Optional)
+
+> Supported from version 5.9.0
+
+In some special scenarios (such as in iframes or when using specific frontend frameworks), you may need to actively call the resume playback method. In this case, you can use the `resume` method provided in the event:
+
+```javascript
+trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, (event) => {
+  showCustomDialog(event);
+});
+function showCustomDialog(event) {
+  const { userId, resume } = event;
+  // The restricted user id is userId, resume is the function to resume playback for this user
+  // Need to display a custom button, prompt that userId playback is restricted, and call 'resume()' in the button click callback
+}
+```
+
+### Important Notes
+
+1. Some browsers may check user interaction status before each playback, so autoplay failure events may be triggered multiple times.
+
+2. Special requirements in iOS WeChat browser and mini-program webview:
+   - When playing remote streams for the first time, you must call the playback interface directly in the user click event callback
+   - You cannot use asynchronous methods like setTimeout to call the playback interface, otherwise playback will fail
+
+## Disable Autoplay Policy in Webview
+
+The default autoplay policy in Android and iOS Webview may be different to the browser. You can refer to the following document to turn off autoplay restrictions in your App.
+
+- Android Webview: Call [setMediaPlaybackRequiresUserGesture(false)](https://developer.android.com/reference/android/webkit/WebSettings#setMediaPlaybackRequiresUserGesture(boolean)).
+- iOS Webview: Set [mediaTypesRequiringUserActionForPlayback](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1851524-mediatypesrequiringuseractionfor) to WKAudiovisualMediaTypeNone.