@tencent-rtc/mcp 1.3.9 → 1.4.0

package/resource/doc/livekit/{voice → core-sdk/voice}/android/voice-host-interaction.md

@@ -1,70 +1,18 @@
 `AtomicXCore` provides two core modules: `CoHostStore` for **cross-room connections** and `BattleStore` for **PK battles**. This guide explains how to integrate these modules to enable connection and PK features in a voice chat room application.
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/4b488f1dc9fc11f087ad52540099c741.png)
-
 ## 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" >**CoHostStore**</td>
-
-<td rowspan="1" colSpan="1" >`abstract class`</td>
-
-<td rowspan="1" colSpan="1" >Manages the lifecycle of host-to-host connections. Provides connection APIs such as `requestHostConnection` and `acceptHostConnection`.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**BattleStore**</td>
-
-<td rowspan="1" colSpan="1" >`abstract class`</td>
-
-<td rowspan="1" colSpan="1" >Handles PK battle signaling and state management across rooms, including PK status tracking.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**LiveListStore**</td>
-
-<td rowspan="1" colSpan="1" >`abstract class`</td>
-
-<td rowspan="1" colSpan="1" >Fetches the list of active live rooms (`fetchLiveList`). Use this to discover rooms available for connection.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**LiveSeatStore**</td>
-
-<td rowspan="1" colSpan="1" >`abstract class`</td>
-
-<td rowspan="1" colSpan="1" >Manages seat states within a room, including cross-room seats during connection. Tracks user join/leave events and microphone status.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**CoHostLayoutTemplate**</td>
-
-<td rowspan="1" colSpan="1" >`enum`</td>
-
-<td rowspan="1" colSpan="1" >Defines seat layout templates for cross-room connections, e.g., `HOST_STATIC_VOICE_6V6`.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**BattleConfig**</td>
-
-<td rowspan="1" colSpan="1" >`data`</td>
-
-<td rowspan="1" colSpan="1" >Configures PK battle details such as duration (`duration`) and whether a secondary response is required (`needResponse`).</td>
-</tr>
-</table>
-
+| **Core Concept** | **Type** | **Core Responsibilities & Description** |
+| --- | --- | --- |
+| **CoHostStore** | `abstract class` | Manages the lifecycle of host-to-host connections. Provides connection APIs such as `requestHostConnection` and `acceptHostConnection`. |
+| **BattleStore** | `abstract class` | Handles PK battle signaling and state management across rooms, including PK status tracking. |
+| **LiveListStore** | `abstract class` | Fetches the list of active live rooms (`fetchLiveList`). Use this to discover rooms available for connection. |
+| **LiveSeatStore** | `abstract class` | Manages seat states within a room, including cross-room seats during connection. Tracks user join/leave events and microphone status. |
+| **CoHostLayoutTemplate** | `enum` | Defines seat layout templates for cross-room connections, e.g., `HOST_STATIC_VOICE_6V6`. |
+| **BattleConfig** | `data` | Configures PK battle details such as duration (`duration`) and whether a secondary response is required (`needResponse`). |
 
 ## Prerequisites
 
-Integrate the [Quick Start](https://write.woa.com/document/194571595678187521) and ensure you have implemented both **Host Start Live** and **Audience Watch** features.
+Integrate the Quick Start and ensure you have implemented both **Host Start Live** and **Audience Watch** features.
 
 ## Host Initiates a Connection
 
@@ -75,7 +23,7 @@ To initiate a connection or PK, the host must retrieve the current list of live
 **Implementation:** Call `LiveListStore.shared().fetchLiveList`.
 
 > **Note：**
-> 
+>
 > - If the target room is missing from the returned list, verify that isPublicVisible in TUILiveInfo is set to true when starting the stream.
 > - This API supports pagination. Use the cursor from the onSuccess callback for subsequent fetches. An empty cursor indicates all rooms have been fetched.
 > - For optimal performance, set pageCount to 20.
@@ -106,7 +54,7 @@ fun fetchLiveListForCoHost() {
 When a host selects another host, use `CoHostStore.requestHostConnection` to send a connection invitation.
 
 > **Note：**
-> 
+>
 > 1. AtomicXCore supports up to **9** interconnected rooms, each with up to **50** users.
 > 2. This interface supports batch invitations, which you can use continuously; to check if an invitation to a single live room was successful, you need to listen for the `onSuccess` callback.
 > 3. The API supports extension fields. These are delivered to the target host via `onCoHostRequestReceived` in `CoHostListener`. Use this to pass business logic such as "start PK immediately".
@@ -239,32 +187,10 @@ public void onExitButtonClicked() {
 ## PK Streamer Initiates a PK
 
  BattleStreamers can start PK battles using two main flows, depending on the room state before PK begins:
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**PK Mode**</td>
-
-<td rowspan="1" colSpan="1" >**Room State (Before PK)**</td>
-
-<td rowspan="1" colSpan="1" >**Room State (After PK)**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Scenario 1: PK after connection</td>
-
-<td rowspan="1" colSpan="1" >Both sides connected</td>
-
-<td rowspan="1" colSpan="1" >Returns to connection state</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Scenario 2: Connection with PK mode</td>
-
-<td rowspan="1" colSpan="1" >Both sides not connected</td>
-
-<td rowspan="1" colSpan="1" >Returns to connection state</td>
-</tr>
-</table>
-
+| **PK Mode** | **Room State (Before PK)** | **Room State (After PK)** |
+| --- | --- | --- |
+| Scenario 1: PK after connection | Both sides connected | Returns to connection state |
+| Scenario 2: Connection with PK mode | Both sides not connected | Returns to connection state |
 
 ### Scenario 1: PK After Connection
 
@@ -281,19 +207,12 @@ AtomicXCore enables hosts to start a timed PK battle once connected. Typical UI
 
 6. After PK, state returns to connection mode.
 
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/4b475a6ec9fc11f087ad52540099c741.png)
-
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/4ad26a5ec9fc11f0aedb525400454e06.png)
-
-
 #### Step 1: Initiate PK Invitation
 
 To start a PK battle among connected hosts, use `BattleStore.requestBattle`. Configure PK duration, whether a response is required, and any extension info.
 
 > **Note：**
-> 
+>
 > 1. Default PK duration is 5 minutes if not set in `BattleConfig`.
 > 2. To start PK immediately, set `needResponse` to `false`.
 > 3. If `needResponse` is `false`, set `timeout` to 0.
@@ -350,10 +269,6 @@ When `onBattleStarted` is triggered in `BattleListener`, render the PK progress
 
 - All PK participants receive `onBattleStarted`.
 
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/4b859b66c9fc11f09e745254007c27c5.png)
-
-
 #### Step 4: End PK State
 
 PK ends either when the duration expires or when all hosts leave.
@@ -368,14 +283,12 @@ PK ends either when the duration expires or when all hosts leave.
    ```
 
    After PK ends, use `onBattleEnded` to display results and determine winner/loser.
-   
 
    > **Note：**
-   > 
+   >
 >   - After PK ends, the session returns to cross-room co-hosting.
 >   - To end co-hosting after PK, call `exitHostConnection`.
 
-
 ### Scenario 2: Co-hosting with PK Mode
 
 **AtomicXCore** supports direct PK initiation during a live session, without prior co-hosting. After PK ends, the session returns to the live room state.
@@ -389,21 +302,11 @@ PK ends either when the duration expires or when all hosts leave.
 
 5. After PK ends, the winner is determined by points.
 
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/4b47decec9fc11f0a4a55254001c06ec.png)
-
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/4ad25df0c9fc11f087ad52540099c741.png)
-
-
-
-
 > **Note：**
-> 
+>
 
 > This workflow requires both CoHostStore and BattleStore, with `needResponse` in BattleConfig set to `false`.
-> 
-
+>
 
 #### Step 1: Send Co-hosting Request
 
@@ -415,12 +318,12 @@ This step is similar to Steps 1 and 2 in "Host Initiates a Connection". Use the
    ``` java
    import io.trtc.tuikit.atomicxcore.api.live.CoHostLayoutTemplate
    import io.trtc.tuikit.atomicxcore.api.CompletionHandler
-   
+
    val targetHostLiveID = "target_host_room_id"
    val layoutTemplate = CoHostLayoutTemplate.HOST_STATIC_VOICE_6V6
    val timeout = 10
    val extraInfo = "withPK:true"
-   
+
    coHostStore.requestHostConnection(
        targetHostLiveID,
        layoutTemplate,
@@ -472,23 +375,23 @@ When the target streamer accepts, immediately call `BattleStore.requestBattle` w
 override fun onCoHostRequestAccepted(invitee: SeatUserInfo) {
         coHostStore.acceptHostConnection(invitee.liveID, null)
         val directPKConfig = BattleConfig(
-            duration = 30, 
-            needResponse = false, 
+            duration = 30,
+            needResponse = false,
             extensionInfo = ""
         )
         battleStore.requestBattle(
             directPKConfig,
-            listOf(invitee.userID), 
+            listOf(invitee.userID),
             timeout = 0,
-            completion = null 
+            completion = null
         )
-    
+
 }
 ```
 
 #### Step 4: Enter PK State
 
-This step is the same as [Enter PK State](https://write.woa.com/#166c6a33-f068-4501-898a-6ef07c9b9b21).
+This step is the same as Enter PK State.
 
 ## PK Score Update and Win/Loss Determination
 
@@ -497,125 +400,45 @@ This step is the same as [Enter PK State](https://write.woa.com/#166c6a33-f068-4
 In typical** live host PK scenarios,** the value of gifts received by the host is linked to the PK score (for example, when a viewer sends a "Rocket" gift, the host's PK score increases by 500 points). You can implement real-time PK score updates using our REST API.
 
 > **Note：**
-> 
+>
 
 > The PK score system in the LiveKit backend uses pure numeric calculation and accumulation. You must calculate the PK score according to your own business logic before calling the update API. See the following PK score calculation examples:
-> 
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >Gift Type</td>
-
-<td rowspan="1" colSpan="1" >Score Calculation Rule</td>
-
-<td rowspan="1" colSpan="1" >Example</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Basic Gift</td>
-
-<td rowspan="1" colSpan="1" >Gift value × 5</td>
-
-<td rowspan="1" colSpan="1" >10 RMB gift → 50 points</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Intermediate Gift</td>
-
-<td rowspan="1" colSpan="1" >Gift value × 8</td>
-
-<td rowspan="1" colSpan="1" >50 RMB gift → 400 points</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Advanced Gift</td>
-
-<td rowspan="1" colSpan="1" >Gift value × 12</td>
-
-<td rowspan="1" colSpan="1" >100 RMB gift → 1200 points</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Special Effect Gift</td>
-
-<td rowspan="1" colSpan="1" >Fixed high score</td>
-
-<td rowspan="1" colSpan="1" >520 RMB gift → 1314 points</td>
-</tr>
-</table>
-
-
+>
+| Gift Type | Score Calculation Rule | Example |
+| --- | --- | --- |
+| Basic Gift | Gift value × 5 | 10 RMB gift → 50 points |
+| Intermediate Gift | Gift value × 8 | 50 RMB gift → 400 points |
+| Advanced Gift | Gift value × 12 | 100 RMB gift → 1200 points |
+| Special Effect Gift | Fixed high score | 520 RMB gift → 1314 points |
 
 #### REST API Call Flow
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/1cd5aeb2c9fd11f0a7775254005ef0f7.png)
-
-
 #### Key Process Description
 1. **Obtain PK Status:**
 
-  - **Callback Configuration**: Configure [PK Status Callback](https://write.woa.com/document/170203265552953344) to have the LiveKit backend actively notify your system when PK starts or ends.
+  - **Callback Configuration**: Configure PK Status Callback to have the LiveKit backend actively notify your system when PK starts or ends.
 
-  - **Active Query**: Your backend can call the [PK Status Query](https://write.woa.com/document/170220847572692992) API at any time to check the current PK status.
+  - **Active Query**: Your backend can call the PK Status Query API at any time to check the current PK status.
 
 2. **PK Score Calculation**: Your backend calculates the PK score increment based on your business rules.
 
-3. **PK Score Update**: Your backend calls the [Update PK Score](https://write.woa.com/document/170220034100383744) API to update the PK score in the LiveKit backend.
+3. **PK Score Update**: Your backend calls the Update PK Score API to update the PK score in the LiveKit backend.
 
 4. **LiveKit Backend Syncs to Client**: The backend automatically synchronizes the updated PK score to all clients.
 
-
 #### Involved REST API Endpoints
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**API**</td>
-
-<td rowspan="1" colSpan="1" >**Function Description**</td>
-
-<td rowspan="1" colSpan="1" >**Request Example**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Active API - Query PK Status</td>
-
-<td rowspan="1" colSpan="1" >Check whether the current room is in PK</td>
-
-<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/170220847572692992)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Active API - Update PK Score</td>
-
-<td rowspan="1" colSpan="1" >Update the calculated PK score</td>
-
-<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/170220034100383744)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Callback Configuration - PK Start Callback</td>
-
-<td rowspan="1" colSpan="1" >Receive real-time notification when PK starts</td>
-
-<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/170203265552953344)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >Callback Configuration - PK End Callback</td>
-
-<td rowspan="1" colSpan="1" >Receive real-time notification when PK ends</td>
-
-<td rowspan="1" colSpan="1" >[Example](https://write.woa.com/document/170221608179601408)</td>
-</tr>
-</table>
-
+| **API** | **Function Description** | **Request Example** |
+| --- | --- | --- |
+| Active API - Query PK Status | Check whether the current room is in PK | Example |
+| Active API - Update PK Score | Update the calculated PK score | Example |
+| Callback Configuration - PK Start Callback | Receive real-time notification when PK starts | Example |
+| Callback Configuration - PK End Callback | Receive real-time notification when PK ends | Example |
 
 ### Winner Determination
 
 In PK scenarios, scores are typically based on gifts received, driving competition and engagement. The PK module in RoomEngine supports score updates and broadcasts. Link your gift logic to this system.
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/d50c20c9cc3d11f0afdc52540044a08e.png)
-
-
-When your billing system confirms a gift transaction, call the [Modify PK Score](https://write.woa.com/document/170220034100383744) to update the host's PK score. All users in PK rooms see the updated `battleScore` in `BattleState`. Update your PK progress bar whenever `battleScore` changes.
+When your billing system confirms a gift transaction, call the Modify PK Score to update the host's PK score. All users in PK rooms see the updated `battleScore` in `BattleState`. Update your PK progress bar whenever `battleScore` changes.
 ``` java
 private fun observeBattleScore() {
     val job = lifecycleScope.launch {
@@ -630,48 +453,12 @@ private fun observeBattleScore() {
 ## API Documentation
 
 For details on all public interfaces, properties, and methods for CoHostStore, BattleStore, LiveListStore, LiveSeatStore, and related classes, see the [AtomicXCore API documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore).
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Store/Component**</td>
-
-<td rowspan="1" colSpan="1" >**Function Description**</td>
-
-<td rowspan="1" colSpan="1" >**API Documentation**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >CoHostStore</td>
-
-<td rowspan="1" colSpan="1" >Host Connection Lifecycle Management: Responsible for managing and coordinating the lifecycle of anchor connections, including initiating connection invitations, handling acceptance/rejection, switching connection status, managing video streams during connections, and disconnecting connections.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-host-store/index.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >BattleStore</td>
-
-<td rowspan="1" colSpan="1" >Streamer PK Battle Lifecycle Management: Responsible for managing the entire lifecycle of timed PK battles between streamers, including initiating PK invitations, starting the battle, updating PK scores in real time, settling the winner at the end of the PK, and penalty time.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-battle-store/index.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveListStore</td>
-
-<td rowspan="1" colSpan="1" >Manages live room lifecycle: query room list, modify live info, etc.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-list-store/index.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveSeatStore</td>
-
-<td rowspan="1" colSpan="1" >Manages seat states within a room (including cross-room seats), tracks user seat changes, microphone status, and more.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-seat-store/index.html)</td>
-</tr>
-</table>
-
+| **Store/Component** | **Function Description** | **API Documentation** |
+| --- | --- | --- |
+| CoHostStore | Host Connection Lifecycle Management: Responsible for managing and coordinating the lifecycle of anchor connections, including initiating connection invitations, handling acceptance/rejection, switching connection status, managing video streams during connections, and disconnecting connections. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-host-store/index.html) |
+| BattleStore | Streamer PK Battle Lifecycle Management: Responsible for managing the entire lifecycle of timed PK battles between streamers, including initiating PK invitations, starting the battle, updating PK scores in real time, settling the winner at the end of the PK, and penalty time. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-battle-store/index.html) |
+| LiveListStore | Manages live room lifecycle: query room list, modify live info, etc. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-list-store/index.html) |
+| LiveSeatStore | Manages seat states within a room (including cross-room seats), tracks user seat changes, microphone status, and more. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-seat-store/index.html) |
 
 ## FAQs
 
@@ -688,7 +475,6 @@ After receiving the `onBattleEnded` callback, determine the winner using `battle
 
 - Check network connectivity; invitation signaling has a default 30-second timeout.
 
-
 #### What happens if a host disconnects or the app crashes during connection or PK?
 
 CoHostStore and BattleStore have built-in heartbeat and timeout detection. If a participant exits unexpectedly, the other party is notified via events such as `onCoHostUserLeft` or `onUserExitBattle`. Use these events to update the UI (e.g., "The other party has disconnected") and end the interaction.