@tencent-rtc/mcp 1.3.9 → 1.4.0

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

@@ -1,72 +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/281d42a3c9fd11f09e745254007c27c5.png)
-
 ## Core Concepts
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Key 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" >`class`</td>
-
-<td rowspan="1" colSpan="1" >Manages the lifecycle of co-hosting between streamers, providing APIs for co-hosting (requestHostConnection, acceptHostConnection).</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**BattleStore**</td>
-
-<td rowspan="1" colSpan="1" >`class`</td>
-
-<td rowspan="1" colSpan="1" >Handles signaling and state management for cross-room PK battles, including PK status.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**LiveListStore**</td>
-
-<td rowspan="1" colSpan="1" >`class`</td>
-
-<td rowspan="1" colSpan="1" >Fetches the list of live rooms (`fetchLiveList`), enabling discovery of other rooms available for co-hosting.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**LiveSeatStore**</td>
-
-<td rowspan="1" colSpan="1" >`class`</td>
-
-<td rowspan="1" colSpan="1" >Manages the status of all seats in a room (including cross-room seats during co-hosting), tracks users joining/leaving seats 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 co-hosting, such as `.hostStaticVoice6v6`.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**BattleConfig**</td>
-
-<td rowspan="1" colSpan="1" >`struct`</td>
-
-<td rowspan="1" colSpan="1" >Configures PK details, including PK duration (`duration`) and whether a response (`needResponse`) is required.</td>
-</tr>
-</table>
-
+| **Key Concept** | **Type** | **Core Responsibilities & Description** |
+| --- | --- | --- |
+| **CoHostStore** | `class` | Manages the lifecycle of co-hosting between streamers, providing APIs for co-hosting (requestHostConnection, acceptHostConnection). |
+| **BattleStore** | `class` | Handles signaling and state management for cross-room PK battles, including PK status. |
+| **LiveListStore** | `class` | Fetches the list of live rooms (`fetchLiveList`), enabling discovery of other rooms available for co-hosting. |
+| **LiveSeatStore** | `class` | Manages the status of all seats in a room (including cross-room seats during co-hosting), tracks users joining/leaving seats and microphone status. |
+| **CoHostLayoutTemplate** | `enum` | Defines seat layout templates for co-hosting, such as `.hostStaticVoice6v6`. |
+| **BattleConfig** | `struct` | Configures PK details, including PK duration (`duration`) and whether a response (`needResponse`) is required. |
 
 ## Prerequisites
 
-Integrate the [Quick Start](https://write.woa.com/document/194571595685527552) and ensure you have implemented both **streamer start live** and **audience watch** features.
+Integrate the Quick Start and ensure you have implemented both **streamer start live** and **audience watch** features.
 
 ## Streamer Initiates a Co-hosting Session
 
@@ -77,7 +23,7 @@ To initiate co-hosting or PK, fetch the current list of live rooms and select a
 **Implementation:** Call `LiveListStore.shared.fetchLiveList`.
 
 > **Note：**
-> 
+>
 > - If the desired live room is missing from the list, verify that the isPublicVisible field in TUILiveInfo was set to true when starting the stream.
 > - This API supports pagination. Use the cursor from the `Result` is `.success` callback for subsequent requests. If the returned cursor is empty, all rooms have been fetched.
 > - For optimal performance, set count to 20.
@@ -109,7 +55,7 @@ func fetchLiveListForCoHost() {
 After selecting a target streamer, use `CoHostStore.requestHostConnection` to send a co-hosting invitation.
 
 > **Note：**
-> 
+>
 > - AtomicXCore supports up to 9 rooms for cross-room co-hosting, with 50 users per room.
 > - The API supports batch invitations. To check if an invitation to a single room was successful, you need to check if the` Result` is `.success` in the completion callback.
 > - The API accepts extension fields. After the invitation is sent, this field is delivered to the target streamer via the `onCoHostRequestReceived` callback. Use it to pass custom business data, such as "start PK immediately".
@@ -277,35 +223,11 @@ func 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 co-hosting**</td>
-
-<td rowspan="1" colSpan="1" >Both sides **already co-hosting**</td>
-
-<td rowspan="1" colSpan="1" >Return to co-hosting state</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**Scenario 2: Co-hosting with PK mode**</td>
-
-<td rowspan="1" colSpan="1" >Both sides **not co-hosting**</td>
-
-<td rowspan="1" colSpan="1" >Return to co-hosting state</td>
-</tr>
-</table>
-
+| **PK Mode** | **Room State (Before PK)** | **Room State (After PK)** |
+| --- | --- | --- |
+| **Scenario 1: PK after co-hosting** | Both sides **already co-hosting** | Return to co-hosting state |
+| **Scenario 2: Co-hosting with PK mode** | Both sides **not co-hosting** | Return to co-hosting state |
 
 ### Scenario 1: PK After Co-hosting
 
@@ -322,19 +244,12 @@ PK Streamer Initiates a PK BattleStreamers can start PK battles using two main f
 
 6. After PK, the session returns to co-hosting.
 
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/27f2a816c9fd11f0a7775254005ef0f7.png)
-
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/27feada9c9fd11f0a93d52540044a08e.png)
-
-
 #### Step 1: Initiate PK Invitation
 
 While co-hosting, call `BattleStore.requestBattle` to send a PK invitation. Configure PK duration, whether acceptance is required, and any extension info.
 
 > **Note：**
-> 
+>
 > - If duration is not set, PK defaults to 5 minutes.
 > - To skip target acceptance, set needResponse to false in BattleConfig. PK starts immediately.
 > - If needResponse is false, set timeout to 0.
@@ -391,10 +306,6 @@ When you receive the `onBattleStarted` event, render the PK progress bar in the
 
 - When PK begins, all participants receive `onBattleStarted`.
 
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/27ff4d76c9fd11f0b011525400bf7822.png)
-
-
 #### Step 4: End PK State
 
 PK can end in two ways:
@@ -419,14 +330,12 @@ PK can end in two ways:
    ```
 
    After PK ends (`onBattleEnded`), display results and identify the winner/loser (see Winner Determination section).
-   
 
    > **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.
@@ -440,19 +349,11 @@ PK can end in two ways:
 
 5. After PK ends, the winner is determined by points.
 
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/280714c7c9fd11f0aedb525400454e06.png)
-
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/280558e0c9fd11f08942525400e889b2.png)
-   
-
    > **Note：**
-   > 
+   >
 
    > This flow requires both CoHostStore and BattleStore, with `BattleConfig.needResponse` set to `false`.
-   > 
-
+   >
 
 #### Step 1: Send Co-hosting Request
 
@@ -465,12 +366,12 @@ For example:
 
    ``` swift
    import AtomicXCore
-   
+
    let targetHostLiveID = "target_host_room_id"
    let layoutTemplate = .hostStaticVoice6v6
    let timeout: TimeInterval = 10
    let extraInfo: String = "" // e.g., {"withPK:true"}
-   
+
    coHostStore.requestHostConnection(
        targetHost: targetHostLiveID,
        layoutTemplate: layoutTemplate,
@@ -554,7 +455,7 @@ coHostStore.coHostEventPublisher
 
 #### Step 4: Enter PK State
 
-This step is same as [Enter PK State](https://write.woa.com/#41199d6f-8352-47bb-ada3-c2202d58391e).
+This step is same as Enter PK State.
 
 ## PK Score Update and Winner Determination
 
@@ -563,125 +464,45 @@ This step is same as [Enter PK State](https://write.woa.com/#41199d6f-8352-47bb-
 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/34d084f8ca0011f08942525400e889b2.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, streamer scores are tied to gifts received. The PK module in RoomEngine supports score updates and broadcasting. Link gift events to PK scoring for real-time progress bar updates.
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/cb8a5a37cc3d11f091ab5254007c27c5.png)
-
-
-When your billing system detects a successful gift transaction, call the [Modify PK Score REST API](https://write.woa.com/document/170220034100383744) to update the streamer's PK score. All users in the PK rooms will see the updated `battleScore` in `BattleState`. Use this to update the PK progress bar.
+When your billing system detects a successful gift transaction, call the Modify PK Score REST API to update the streamer's PK score. All users in the PK rooms will see the updated `battleScore` in `BattleState`. Use this to update the PK progress bar.
 ``` swift
 battleStore.state.subscribe(StatePublisherSelector(keyPath: \BattleState.battleScore))
     .receive(on: RunLoop.main)
@@ -695,48 +516,12 @@ battleStore.state.subscribe(StatePublisherSelector(keyPath: \BattleState.battleS
 ## API Documentation
 
 For complete API details, refer to 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" >Core component for live stream display and interaction: handles video rendering, widget management, streamer live, audience mic-link, streamer co-hosting, and more.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cohoststore)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**BattleStore**</td>
-
-<td rowspan="1" colSpan="1" >Manages the full lifecycle of live rooms: create, join, leave, destroy, query room list, modify live info, listen for live status changes.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/battlestore)</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_iOS/documentation/atomicxcore/liveliststore)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >**LiveSeatStore**</td>
-
-<td rowspan="1" colSpan="1" >Manages seat status: tracks all seats in the room (including cross-room seats during co-hosting), check user join/leave, microphone, seat status, etc.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveseatstore)</td>
-</tr>
-</table>
-
+| **Store/Component** | **Function Description** | **API Documentation** |
+| --- | --- | --- |
+| **CoHostStore** | Core component for live stream display and interaction: handles video rendering, widget management, streamer live, audience mic-link, streamer co-hosting, and more. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cohoststore) |
+| **BattleStore** | Manages the full lifecycle of live rooms: create, join, leave, destroy, query room list, modify live info, listen for live status changes. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/battlestore) |
+| **LiveListStore** | Manages live room lifecycle: query room list, modify live info, etc. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveliststore) |
+| **LiveSeatStore** | Manages seat status: tracks all seats in the room (including cross-room seats during co-hosting), check user join/leave, microphone, seat status, etc. | [API Documentation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveseatstore) |
 
 ## FAQs
 
@@ -753,7 +538,6 @@ After receiving the `onBattleEnded` callback from `battleEventPublisher`, use `b
 
 - Check network connectivity; invitation signaling times out after 30 seconds.
 
-
 #### What happens if a streamer disconnects or the app crashes during co-hosting or PK?
 
 **CoHostStore** and **BattleStore** include heartbeat and timeout detection. If a participant exits by accident, the other party receives events such as **onCoHostUserLeft** or **onUserExitBattle**. Use these events to update the UI (e.g., "The other party has disconnected") and end the interaction.
@@ -766,5 +550,3 @@ After receiving the `onBattleEnded` callback from `battleEventPublisher`, use `b
 - **Real-time multi-end sync**: Standardized formats (e.g., JSON) enable rapid integration with gift, PK, and display systems, keeping scores consistent and real-time across streamer, audience, and backend.
 
 - **Flexible rule adaptation**: Backend configuration changes (e.g., gift-to-score mapping, bonus points) can be made without frontend updates, reducing iteration costs.
-
-