@tencent-rtc/mcp 1.3.3 → 1.3.5

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

@@ -49,7 +49,7 @@ Provides the Agent with a **code generation blueprint** for implementing core fe
 
 **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_interaction`) must be called **after** basic features are completed.
+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.
 
 ---
@@ -135,12 +135,106 @@ Execute `./gradlew assembleDebug` and deliver once verified.
     * ❌ NOT 0-1 (Float), and NOT 0-100 (Int).
 * **UI Mapping Formula**: `progress / 100.0f * 9.0f`.
 
-#### C. Barrage, Gift & Layout
+#### C. Barrage, Gift & Layout (Barrage, Gift & UI)
 * **Layering Requirements**: Barrage list and full-screen gift animations MUST overlay **on top** of the video layer using `FrameLayout` or `RelativeLayout`.
 * **Split Screen Prohibited**: Strictly prohibited to split the screen (e.g., video on top, barrage at bottom); MUST use overlay mode.
-* **Keyboard Adaptation**: Set `android:windowSoftInputMode="adjustNothing"` or `adjustPan` in the Manifest to **prevent video distortion or shifting when the keyboard appears**.
+* **Keyboard Adaptation**: Must set `android:windowSoftInputMode="adjustNothing"` or `adjustPan` in the Manifest to **prevent video distortion or shifting when the keyboard appears**.
+
+##### 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` layout must be fixed to `match_parent`, prohibiting distortion or upward shifting.
+    * **MUST** set `android:windowSoftInputMode="adjustNothing"` in the Manifest.
+
+##### 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.create(liveId).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 (`recyclerView.scrollToPosition(adapter.itemCount - 1)`).
+* **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**: **If the user needs full-screen gift integration**, upon receiving the gift callback, the full-screen animation MUST be played on the top-level video view on **both host and audience sides**. Hosts MUST also see the special effects of gifts sent by viewers.
+
+##### 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 `FrameLayout` container.
+* **Layout**: Constrained to `match_parent`, covering the entire screen.
+* **Dual-side Sync**: Upon receiving the `GiftStore.onReceiveGift` callback, the full-screen animation MUST be played on **both host and audience sides**. Playing only on the audience side is strictly prohibited.
+
+### 🎨 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 `Color.BLACK`, and the video layer (`LiveCoreView`) must **fill the entire screen** (`match_parent`) and be at the bottom layer.
+* **Safe Area**: All floating UIs must consider status and navigation bars, and are strictly prohibited from being blocked by notches or bottom navigation bars.
+* **Text Readability**: White text above the video (e.g., barrage, ID) must have a **black shadow** (`setShadowLayer`).
+* **Error Prompts**: Use **Toast** uniformly; prohibit the use of modal AlertDialogs that interrupt the user.
+
+### 2. Component Standards
+* **Glass Capsule (Top)**:
+    * **Style**: **Semi-transparent black background** + **full rounded corners** (`cornerRadius = height / 2`).
+    * **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 semi-transparent background icon.
+* **Floating Panels**:
+    * **Style**: Only top rounded corners (`topLeftRadius, topRightRadius`).
+    * **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 **semi-transparent 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.
 
 ---
 
@@ -161,13 +255,50 @@ Execute `./gradlew assembleDebug` and deliver once verified.
 * **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 (`AlertDialog`) 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 (`BottomSheetDialog` or custom `View` animated up); prohibit `AlertDialog`.
+* **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.connectedUsers.isEmpty()`).
+* **Status Handling**:
+    * **Not connected**: ❌ Prohibit jump, show Toast: `"Please initiate co-hosting first"`.
+    * **Connected**: ✅ Pop up PK invitation panel.
+
 ---
 
 ## 📋 Agent Final Checklist
 
 - [ ] **Build Verification**: Full `./gradlew assembleDebug` executed and result is SUCCESS.
 - [ ] **API Accuracy**: Imports not modified, APIs not fabricated, `LiveInfo` field names verified.
-- [ ] **Store & Listener Compliance**: Listeners are member variables, properly added and removed.
 - [ ] **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.
@@ -186,4 +317,4 @@ Execute `./gradlew assembleDebug` and deliver once verified.
  * - ✅ UserSig MUST be generated on a backend service before official launch.
  * - Reference: https://trtc.io/document/35166?product=live&menulabel=uikit&platform=android
  */
-```
+```

package/resource/doc/livekit/live/ios/live-audience-list.md

@@ -0,0 +1,339 @@
+`LiveAudienceStore` is a module in `AtomicXCore` designed for managing audience information in live streaming rooms. With `LiveAudienceStore`, you can implement a comprehensive audience list and management system for your live streaming application.
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/9013fb14c6b611f087ad52540099c741.png)
+
+
+## Core Features
+- **Real-Time Audience List**: Fetch and display the list of users currently in the room.
+
+- **Audience Statistics**: Get the real-time total viewer count.
+
+- **Event Monitoring**: Listen for events when viewers join or leave the room.
+
+- **Role Management**: The host can grant or revoke administrator privileges for viewers.
+
+- **Room Management**: The host or administrator can remove specific viewers from the live room.
+
+
+## Core Concepts
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Core Concept**</td>
+
+<td rowspan="1" colSpan="1" >**Type**</td>
+
+<td rowspan="1" colSpan="1" >**Core Responsibilities & Description**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`LiveUserInfo`</td>
+
+<td rowspan="1" colSpan="1" >`class`</td>
+
+<td rowspan="1" colSpan="1" >- Data model representing a viewer.<br>- Contains basic profile information such as userID, userName, and avatarURL.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`LiveAudienceState`</td>
+
+<td rowspan="1" colSpan="1" >`struct`</td>
+
+<td rowspan="1" colSpan="1" >- State container for the audience module.<br>- Exposes `audienceList` (StateFlow) for the real-time user list and `audienceCount` for the total viewer count.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`LiveAudienceEvent`</td>
+
+<td rowspan="1" colSpan="1" >`enum`</td>
+
+<td rowspan="1" colSpan="1" >- Event listener for audience changes.<br>- Provides callbacks like `.onAudienceJoined` and` .onAudienceLeft` to handle incremental list updates.</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`LiveAudienceStore`</td>
+
+<td rowspan="1" colSpan="1" >`class`</td>
+
+<td rowspan="1" colSpan="1" >- Primary interface for audience management.<br>- Used to fetch list snapshots, perform admin operations (e.g., kicking users), and subscribe to real-time events.</td>
+</tr>
+</table>
+
+
+## Implementation
+
+### Step 1: Component Integration
+- **Video Live Streaming**: Please refer to [Quick Start](https://write.woa.com/document/194571606121816064) to integrate AtomicXCore.
+
+- **Voice Chat Room**: Please refer to [Quick Start](https://write.woa.com/document/194571595685527552) to integrate AtomicXCore.
+
+
+### Step 2: Initialize and Retrieve the Audience List
+
+Get a `LiveAudienceStore` instance linked to the `liveId` and fetch the initial audience snapshot. 
+``` swift
+import Foundation
+import AtomicXCore 
+import Combine     
+
+class AudienceManager {
+    private let liveId: String
+    private let audienceStore: LiveAudienceStore
+    private var cancellables = Set<AnyCancellable>()
+    
+    // Expose the [full] audience list publisher for UI layer subscription
+    let audienceListPublisher = CurrentValueSubject<[LiveUserInfo], Never>([])
+    // Expose the audience count publisher
+    let audienceCountPublisher = PassthroughSubject<UInt, Never>()
+
+    init(liveId: String) {
+        self.liveId = liveId
+        // 1. Get the LiveAudienceStore instance by liveId
+        self.audienceStore = LiveAudienceStore.create(liveID: liveId)
+        
+        // 2. Subscribe to state and events
+        subscribeToAudienceState()
+        subscribeToAudienceEvents()
+        
+        // 3. Proactively fetch initial data for the first screen
+        fetchInitialAudienceList()
+    }
+
+    /// Proactively fetch a snapshot of the audience list
+    func fetchInitialAudienceList() {
+        audienceStore.fetchAudienceList { [weak self] result in
+            switch result {
+            case .success:
+                print("Successfully fetched the audience list for the first time")
+                // On success, data will be automatically updated via the state subscription channel below
+            case .failure(let error):
+                print("Failed to fetch the audience list for the first time: \(error.localizedDescription)")
+            }
+        }
+    }
+    
+    // ... subsequent code
+}
+```
+
+### Step 3: Subscribe to State and Events
+
+Observe the `audienceStore` state and listen for events to receive list snapshots and real-time join/leave updates
+``` swift
+extension AudienceManager {
+    /// Subscribe to state to get audience count and list snapshot
+    private func subscribeToAudienceState() {
+        audienceStore.state
+            .subscribe()
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] state in
+                // state.audienceList is a full snapshot
+                self?.audienceListPublisher.send(state.audienceList)
+                // state.audienceCount is the real-time total
+                self?.audienceCountPublisher.send(state.audienceCount)
+            }
+            .store(in: &cancellables)
+    }
+
+    /// Subscribe to events to handle real-time audience join/leave
+    private func subscribeToAudienceEvents() {
+        audienceStore.liveAudienceEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                guard let self = self else { return }
+                
+                var currentList = self.audienceListPublisher.value
+                
+                switch event {
+                case .onAudienceJoined(let newAudience):
+                    print("Audience \(newAudience.userName) joined the live room")
+                    // Incremental update: add the new audience member to the end of the current list
+                    if !currentList.contains(where: { $0.userID == newAudience.userID }) {
+                        currentList.append(newAudience)
+                        self.audienceListPublisher.send(currentList)
+                    }
+                    
+                case .onAudienceLeft(let departedAudience):
+                    print("Audience \(departedAudience.userName) left the live room")
+                    // Incremental update: remove the departed audience member from the current list
+                    currentList.removeAll { $0.userID == departedAudience.userID }
+                    self.audienceListPublisher.send(currentList)
+                }
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+
+### Step 4: Manage Audience
+
+As a host or administrator, you can manage viewers in the live room.
+
+#### 4.1 Kick a Viewer Out of the Live Room
+
+Call the `kickUserOutOfRoom` API to remove a specified user from the live room.
+``` swift
+extension AudienceManager {
+    func kick(userId: String) {
+        audienceStore.kickUserOutOfRoom(userID: userId) { result in
+            switch result {
+            case .success:
+                print("Successfully kicked user \(userId) out of the room")
+                // After a successful kick, you will receive an onAudienceLeft event
+            case .failure(let error):
+                print("Failed to kick user \(userId) out: \(error.localizedDescription)")
+            }
+        }
+    }
+}
+```
+
+#### 4.2 Manage Admin Roles
+
+Use the `setAdministrator` and `revokeAdministrator` APIs to grant or revoke administrator privileges for a user.
+``` swift
+extension AudienceManager {
+    /// Promote user to administrator
+    func promoteToAdmin(userId: String) {
+        audienceStore.setAdministrator(userID: userId) { result in
+            if case .success = result {
+                print("Successfully promoted user \(userId) to administrator")
+            }
+        }
+    }
+
+    /// Revoke user's administrator status
+    func revokeAdmin(userId: String) {
+        audienceStore.revokeAdministrator(userID: userId) { result in
+            if case .success = result {
+                print("Successfully revoked administrator status for user \(userId)")
+            }
+        }
+    }
+}
+```
+
+## Advanced Features
+
+### Display Welcome Message on Entry
+
+When a new audience member enters the live room, a welcome message is automatically displayed locally in the barrage/chat area, such as: `"Welcome [User Nickname] to the live room"`.
+
+#### Implementation
+1. Listen for Join Events: Observe the `LiveAudienceEvent.onAudienceJoined` callback in `LiveAudienceStore` to receive real-time notifications when a new user enters.
+
+2. Insert Local Message: Upon triggering the event, extract the user's nickname and immediately call the `appendLocalTip` API in BarrageStore to insert the system message locally.
+
+   ``` swift
+   import Foundation
+   import AtomicXCore 
+   import Combine
+   
+   class LiveRoomManager {
+       private let liveId: String
+       private let audienceManager: AudienceManager
+       private let barrageManager: BarrageManager // Assume you have implemented BarrageManager as described in the barrage documentation
+       private var cancellables = Set<AnyCancellable>()
+   
+       init(liveId: String) {
+           self.liveId = liveId
+           // Initialize two core managers
+           self.audienceManager = AudienceManager(liveId: liveId)
+           self.barrageManager = BarrageManager(liveId: liveId)
+   
+           // Set up linkage
+           setupWelcomeMessageFlow()
+       }
+   
+       private func setupWelcomeMessageFlow() {
+           // 1. Get the LiveAudienceStore instance
+           let audienceStore = LiveAudienceStore.create(liveID: self.liveId)
+   
+           // 2. Get the BarrageStore instance (thanks to internal mechanisms, this will be the same instance)
+           let barrageStore = BarrageStore.create(liveID: self.liveId)
+   
+           // 3. Subscribe to audience events
+           audienceStore.liveAudienceEventPublisher
+               .receive(on: DispatchQueue.main)
+               .sink { event in
+                   // 4. Only handle audience join events
+                   guard case .onAudienceJoined(let newAudience) = event else {
+                       return
+                   }
+   
+                   // 5. Create a local tip message
+                   var welcomeTip = Barrage()
+                   welcomeTip.messageType = .text 
+                   welcomeTip.textContent = "Welcome \(newAudience.userName) to the live room!"
+   
+                   // 6. Call BarrageStore's API to insert it into the barrage list
+                   barrageStore.appendLocalTip(message: welcomeTip)
+               }
+               .store(in: &cancellables)
+       }
+   }
+   ```
+
+## API Documentation
+
+For detailed information on all public interfaces, properties, and methods of [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore) and its related classes, refer to the official API documentation included with the [AtomicX Core](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) framework. The relevant Stores used in this document are as follows:
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**Store/Component**</td>
+
+<td rowspan="1" colSpan="1" >**Feature Description**</td>
+
+<td rowspan="1" colSpan="1" >**API Documentation**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >LiveCoreView</td>
+
+<td rowspan="1" colSpan="1" >Core view component for live video stream display and interaction: responsible for video stream rendering and view widget handling, supporting scenarios such as host streaming, audience co-hosting, and host-to-host connection.</td>
+
+<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/livecoreview)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >LiveAudienceStore</td>
+
+<td rowspan="1" colSpan="1" >Audience management: obtain real-time audience list (ID / name / avatar), count audience numbers, and listen for audience join/leave events.</td>
+
+<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >BarrageStore</td>
+
+<td rowspan="1" colSpan="1" >Barrage feature: send text/custom barrage, maintain barrage list, and listen to barrage status in real time.</td>
+
+<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestore)</td>
+</tr>
+</table>
+
+
+## FAQs
+
+### How is the online audience count (audienceCount) in LiveAudienceState updated? What are the timing and frequency?
+
+The `audienceCount` is a high-precision estimate. Updates occur based on specific triggers and are subject to system frequency controls:
+- **Active Entry/Exit (Immediate)**:When a user explicitly joins or leaves the room, the count updates immediately in `LiveAudienceState`.
+
+- **Unexpected Disconnection (Delayed)**:If a user disconnects abnormally (e.g., app crash, network loss), the system uses a heartbeat mechanism to verify status. The user is marked offline only after 90 seconds of inactivity, triggering a delayed count update.
+
+- **Frequency Control & Rate Limiting**: Audience count updates are broadcast as room messages. The system enforces a limit of 40 messages per second per room.
+   
+
+   > **Note：**
+   > 
+
+   > During high-traffic spikes (e.g., chat floods or rapid gifting), if the message rate exceeds this threshold, the system prioritizes core messages (like chat/barrage). Consequently, audience count update messages may be dropped to maintain stability.
+   > 
+
+- **What does this mean for developers?**
+
+
+   Treat `audienceCount` as a metric for UI display purposes only. Do not rely on it for billing, critical statistics, or scenarios requiring 100% accuracy, as brief delays or data loss may occur during high-concurrency events.
+
+
+
+