@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

package/resource/doc/livekit/{live → core-sdk/live}/ios/live-live-list.md

@@ -1,8 +1,5 @@
 `LiveListStore` 是 `AtomicXCore` 中负责管理直播房间列表、创建、加入以及维护房间状态的核心模块。通过`LiveListStore`，您可以为您的应用构建完整的直播生命周期管理。
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/6fd3c4f2ab6011f0b5345254005ef0f7.png)
-
-
 ## 核心功能
 - **直播列表拉取**：获取当前所有公开的直播间列表，支持分页加载。
 
@@ -14,58 +11,21 @@
 
 - **自定义业务数据**：强大的自定义元数据（`MetaData`）能力，允许您在房间内存储和同步任何业务相关的信息，例如直播状态、音乐信息、自定义角色等 。
 
-
 ## 核心概念
 
 在开始集成之前，我们先通过下表了解一下 `LiveListStore` 相关的几个核心概念：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**核心概念**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**核心职责与描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`LiveInfo`</td>
-
-<td rowspan="1" colSpan="1" >`struct`</td>
-
-<td rowspan="1" colSpan="1" >代表一个直播间的所有信息模型。包含了直播ID (`liveID`)、名称 (`liveName`)、房主信息 (`liveOwner`) 以及自定义元数据 (`metaData`) 等。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`LiveListState`</td>
-
-<td rowspan="1" colSpan="1" >`struct`</td>
-
-<td rowspan="1" colSpan="1" >代表直播列表模块的当前状态。其核心属性 liveList 是一个 `[LiveInfo] `数组，存储了拉取到的直播列表；`currentLive` 则代表用户当前所在的直播间信息。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`LiveListEvent`</td>
-
-<td rowspan="1" colSpan="1" >`enum`</td>
-
-<td rowspan="1" colSpan="1" >代表直播房间的全局事件。分为 `.onLiveEnded` (直播结束) 和 `.onKickedOutOfLive` (被踢出直播) 两种，用于处理关键的房间状态变更。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`LiveListStore`</td>
-
-<td rowspan="1" colSpan="1" >`class`</td>
-
-<td rowspan="1" colSpan="1" >这是与直播列表和房间生命周期交互的核心管理类。它是一个全局单例 (shared)，负责所有直播房间的创建、加入、信息更新等操作。</td>
-</tr>
-</table>
-
+| **核心概念** | **类型** | **核心职责与描述** |
+| --- | --- | --- |
+| `LiveInfo` | `struct` | 代表一个直播间的所有信息模型。包含了直播ID (`liveID`)、名称 (`liveName`)、房主信息 (`liveOwner`) 以及自定义元数据 (`metaData`) 等。 |
+| `LiveListState` | `struct` | 代表直播列表模块的当前状态。其核心属性 liveList 是一个 `[LiveInfo] `数组，存储了拉取到的直播列表；`currentLive` 则代表用户当前所在的直播间信息。 |
+| `LiveListEvent` | `enum` | 代表直播房间的全局事件。分为 `.onLiveEnded` (直播结束) 和 `.onKickedOutOfLive` (被踢出直播) 两种，用于处理关键的房间状态变更。 |
+| `LiveListStore` | `class` | 这是与直播列表和房间生命周期交互的核心管理类。它是一个全局单例 (shared)，负责所有直播房间的创建、加入、信息更新等操作。 |
 
 ## 实现步骤
 
 ### 步骤1：组件集成
 
-请参考 [开始直播](https://write.woa.com/document/191126382767431680) 集成 **AtomicXCore**，并完成 [主播开播](https://write.woa.com/document/191126382767431680) 和 [观众观看](https://write.woa.com/document/191126382767431680) 的功能实现。
+请参考 开始直播 集成 **AtomicXCore**，并完成 主播开播 和 观众观看 的功能实现。
 
 ### 步骤2：实现观众从直播列表进入直播间
 
@@ -81,7 +41,7 @@ class LiveListViewController: UIViewController, UICollectionViewDataSource, UICo
     private let liveListStore = LiveListStore.shared
     private var cancellables = Set<AnyCancellable>()
     private var liveList: [LiveInfo] = []
-    
+
     private var collectionView: UICollectionView!
 
     override func viewDidLoad() {
@@ -90,7 +50,7 @@ class LiveListViewController: UIViewController, UICollectionViewDataSource, UICo
         bindStore()
         fetchLiveList()
     }
-    
+
     private func bindStore() {
         // 订阅 state，自动接收列表更新
         liveListStore.state
@@ -110,17 +70,17 @@ class LiveListViewController: UIViewController, UICollectionViewDataSource, UICo
             }
         }
     }
-    
+
     // 当用户点击列表中的某个Cell时
     func collectionView(_ collectionView: UICollectionView, didSelectItemAt indexPath: IndexPath) {
         let selectedLiveInfo = liveList[indexPath.item]
-        
+
         // 创建观众观看页面，并将 liveId 传入
         let audienceVC = YourAudienceViewController(liveId: selectedLiveInfo.liveID)
         audienceVC.modalPresentationStyle = .fullScreen
         present(audienceVC, animated: true)
     }
-    
+
     // --- UICollectionViewDataSource, Delegate, and UI setup methods ---
     private func setupUI() {
         let layout = UICollectionViewFlowLayout()
@@ -135,7 +95,7 @@ class LiveListViewController: UIViewController, UICollectionViewDataSource, UICo
     func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
         return liveList.count
     }
-    
+
     func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
         let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "LiveCell", for: indexPath)
         cell.backgroundColor = .lightGray // 自定义您的Cell样式
@@ -143,7 +103,7 @@ class LiveListViewController: UIViewController, UICollectionViewDataSource, UICo
         // ... (例如: cell.titleLabel.text = liveInfo.liveName)
         return cell
     }
-    
+
     func collectionView(_ collectionView: UICollectionView, layout collectionViewLayout: UICollectionViewLayout, sizeForItemAt indexPath: IndexPath) -> CGSize {
         // 单列、双列布局可通过自定义您的Cell大小来实现
         let width = (view.bounds.width - 30) / 2
@@ -153,80 +113,16 @@ class LiveListViewController: UIViewController, UICollectionViewDataSource, UICo
 ```
 
 **LiveInfo 参数说明**
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**参数名**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`liveID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >直播间的唯一标识符</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`liveName`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >直播间的标题</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`coverURL`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >直播间的封面图片地址</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`liveOwner`</td>
-
-<td rowspan="1" colSpan="1" >[LiveUserInfo](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveuserinfo)</td>
-
-<td rowspan="1" colSpan="1" >房主的个人信息</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`totalViewerCount`</td>
-
-<td rowspan="1" colSpan="1" >`Int`</td>
-
-<td rowspan="1" colSpan="1" >直播间的总观看人数</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`categoryList`</td>
-
-<td rowspan="1" colSpan="1" >`[NSNumber]`</td>
-
-<td rowspan="1" colSpan="1" >直播间的分类标签列表</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`notice`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >直播间的公告信息</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`metaData`</td>
-
-<td rowspan="1" colSpan="1" >`[String: String]`</td>
-
-<td rowspan="1" colSpan="1" >开发者自定义的元数据，用于实现复杂的业务场景</td>
-</tr>
-</table>
-
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `liveID` | `String` | 直播间的唯一标识符 |
+| `liveName` | `String` | 直播间的标题 |
+| `coverURL` | `String` | 直播间的封面图片地址 |
+| `liveOwner` | [LiveUserInfo](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveuserinfo) | 房主的个人信息 |
+| `totalViewerCount` | `Int` | 直播间的总观看人数 |
+| `categoryList` | `[NSNumber]` | 直播间的分类标签列表 |
+| `notice` | `String` | 直播间的公告信息 |
+| `metaData` | `[String: String]` | 开发者自定义的元数据，用于实现复杂的业务场景 |
 
 ## 功能进阶
 
@@ -234,9 +130,6 @@ class LiveListViewController: UIViewController, UICollectionViewDataSource, UICo
 
 在 App 的直播广场页，顶部设有“热门”、“音乐”、“游戏”等分类标签。用户点击不同的标签后，下方的直播列表会动态筛选，只展示对应分类的直播间，从而帮助用户快速发现感兴趣的内容。
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/7dcde616ab4b11f0a68e5254001c06ec.png)
-
-
 #### 实现方式
 
 核心是利用 `LiveInfo` 模型中的 `categoryList` 属性。当主播开播设置分类后，`fetchLiveList` 返回的 `LiveInfo` 对象中就会包含这些分类信息。您的 App 在获取到完整的直播列表后，只需在客户端根据用户选择的分类，对这个列表进行一次简单的筛选，然后刷新 UI 即可。
@@ -329,9 +222,6 @@ class LiveListViewController: UIViewController, UICollectionViewDataSource, UICo
 
 #### 交互流程图
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/904c1b1dab5c11f08bcc5254007c27c5.webp)
-
-
 #### 实现方式
 
 `LiveCoreView` 支持多实例使用，我们为每一个 `UICollectionViewCell` 都创建一个独立的 `LiveCoreView` 实例。通过监听 `UICollectionView` 的滚动代理方法，我们可以精确地控制即将出现和已经离开屏幕的 Cell 中的 `LiveCoreView` 何时开始和停止拉流，从而实现“即滑即播、即走即停”的效果。
@@ -411,9 +301,6 @@ class LiveFeedViewController: UIViewController, UICollectionViewDataSource, UICo
 
 在电商直播中，主播正在讲解一款商品。此时，所有观众的直播画面下方都会弹出一张商品卡片，实时展示该商品的图片、名称和价格。当主播切换讲解下一件商品时，所有观众端的卡片都会自动、同步更新。
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/2ba67778ac9611f0a0a052540099c741.png)
-
-
 #### 实现方式
 
 主播端将当前商品的结构化信息（建议使用 **JSON **格式）通过 `updateLiveMetaData` 接口设置到一个自定义的 key（例如 "`product_info`"）中。**AtomicXCore** 会将这个变更实时同步给所有观众。观众端只需订阅 `LiveListStore.state`，监听 `metaData` 的变化，一旦发现 `product_info` 的值更新，就解析其中的 JSON 数据并刷新商品卡片 UI。
@@ -490,32 +377,10 @@ class YourAudienceViewController: UIViewController {
 ## API 文档
 
 关于 [LiveListStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveliststore) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >Store/Component</td>
-
-<td rowspan="1" colSpan="1" >功能描述</td>
-
-<td rowspan="1" colSpan="1" >API 文档</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveCoreView</td>
-
-<td rowspan="1" colSpan="1" >直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。</td>
-
-<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/livecoreview)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveListStore</td>
-
-<td rowspan="1" colSpan="1" >直播间全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改直播信息（名称、公告等），监听直播状态（例如被踢出、结束）。</td>
-
-<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveliststore)</td>
-</tr>
-</table>
-
+| Store/Component | 功能描述 | API 文档 |
+| --- | --- | --- |
+| LiveCoreView | 直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/livecoreview) |
+| LiveListStore | 直播间全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改直播信息（名称、公告等），监听直播状态（例如被踢出、结束）。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveliststore) |
 
 ## 常见问题
 

package/resource/doc/livekit/core-sdk/voice/android/voice-audience-list.md

@@ -0,0 +1,264 @@
+`LiveAudienceStore` 是 `AtomicXCore` 中专门负责管理直播间观众信息的模块。通过`LiveAudienceStore`，您可以为您的直播应用构建一套完整的观众列表及管理系统。
+
+## 核心功能
+- **实时观众列表**：获取并展示当前在直播间内的所有观众信息。
+
+- **观众人数统计**：实时获取当前直播间的准确观众总数。
+
+- **观众动态监听**：通过事件订阅，实时感知观众的加入和离开。
+
+- **管理员权限**：主播可以将普通观众设为管理员，或撤销其管理员身份。
+
+- **房间管理**：主播或管理员可以将任意普通观众请出（踢出）直播间。
+
+## 核心概念
+
+在开始集成之前，我们先通过下表了解一下 LiveAudienceStore 相关的几个核心概念：
+| **核心概念** | **类型** | **核心职责与描述** |
+| --- | --- | --- |
+| `LiveUserInfo` | data class | 代表一个观众（用户）的基础信息模型。它包含了用户的唯一标识 (`userID`)、昵称 (`userName`) 和头像地址 (`avatarURL`)。 |
+| `LiveAudienceState` | data class | 代表观众模块的当前状态。其核心属性 `audienceList` 是一个 StateFlow，存储了观众列表的实时状态；`audienceCount` 则代表当前观众总数的实时状态。 |
+| `LiveAudienceListener` | abstract class | 代表观众动态的实时事件。分为 `onAudienceJoined` (观众加入) 和 `onAudienceLeft` (观众离开) 两种，用于实现对观众列表的增量更新。 |
+| `LiveAudienceStore` | abstract class | 这是与观众列表功能交互的核心管理类。通过它，您可以获取观众列表快照、执行管理操作，并通过订阅其 `LiveAudienceListener` 来接收实时动态。 |
+
+## 实现指南
+
+### 步骤1：组件集成
+
+请参考 开始直播 集成 **AtomicXCore**，完成接入。
+
+### 步骤2：初始化并获取观众列表
+
+获取一个与当前直播间 liveID 绑定的 `LiveAudienceStore` 实例，并主动拉取一次当前的观众列表，用于首次展示。
+``` kotlin
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import io.trtc.tuikit.atomicxcore.api.live.LiveAudienceStore
+import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
+
+class AudienceManager(
+    private val liveId: String
+) {
+    private val audienceStore: LiveAudienceStore = LiveAudienceStore.create(liveId)
+    private val scope = CoroutineScope(Dispatchers.Main)
+
+    // 对外暴露【全量】观众列表的状态流，方便UI层订阅
+    private val _audienceList = MutableStateFlow<List<LiveUserInfo>>(emptyList())
+    val audienceList: StateFlow<List<LiveUserInfo>> = _audienceList.asStateFlow()
+
+    // 对外暴露观众总数的状态流
+    private val _audienceCount = MutableStateFlow(0)
+    val audienceCount: StateFlow<Int> = _audienceCount.asStateFlow()
+
+    init {
+        // 1. 订阅状态和事件，实现见下一节
+        subscribeToAudienceState()
+        subscribeToAudienceEvents()
+
+        // 2. 主动拉取首屏数据
+        fetchInitialAudienceList()
+    }
+
+    /// 主动获取一次观众列表快照
+    private fun fetchInitialAudienceList() {
+        audienceStore.fetchAudienceList(object : CompletionHandler {
+            override fun onSuccess() {
+                println("首次拉取观众列表成功")
+                // 成功后，数据会通过下面的 state 订阅通道自动更新
+            }
+
+            override fun onFailure(code: Int, desc: String) {
+                println("首次拉取观众列表失败: $desc")
+            }
+        })
+    }
+
+    // ... 后续代码
+}
+```
+
+### 步骤3：监听观众列表状态与实时动态
+
+订阅 `audienceStore` 的 `liveAudienceState` 和添加 `LiveAudienceListener`，以接收全量列表快照和实时的观众进出事件，从而驱动UI更新。
+``` kotlin
+class AudienceManager {
+    /// 订阅 state，用于获取观众总数和列表快照
+    private fun subscribeToAudienceState() {
+        scope.launch {
+            // audienceList 是一个全量快照
+            audienceStore.liveAudienceState.audienceList.collect { audienceList ->
+                _audienceList.value = audienceList
+            }
+        }
+
+        scope.launch {
+            // audienceCount 是实时总数
+            audienceStore.liveAudienceState.audienceCount.collect { count ->
+                _audienceCount.value = count
+            }
+        }
+    }
+
+    /// 订阅 event，用于处理观众的实时进出事件
+    private fun subscribeToAudienceEvents() {
+        audienceStore.addLiveAudienceListener(object : LiveAudienceListener() {
+            override fun onAudienceJoined(newAudience: LiveUserInfo) {
+                println("观众 ${newAudience.userName} 加入了直播间")
+                // 增量更新：在当前列表末尾添加新观众
+                val currentList = _audienceList.value.toMutableList()
+                if (!currentList.any { it.userID == newAudience.userID }) {
+                    currentList.add(newAudience)
+                    _audienceList.value = currentList
+                }
+            }
+
+            override fun onAudienceLeft(departedAudience: LiveUserInfo) {
+                println("观众 ${departedAudience.userName} 离开了直播间")
+                // 增量更新：从当前列表中移除离开的观众
+                val currentList = _audienceList.value.toMutableList()
+                currentList.removeAll { it.userID == departedAudience.userID }
+                _audienceList.value = currentList
+            }
+        })
+    }
+}
+```
+
+### 步骤4：管理观众（踢人与设置管理员）
+
+作为主播或管理员，对直播间内的观众进行管理操作。
+
+#### 4.1 将观众踢出直播间
+
+调用 `kickUserOutOfRoom` 接口可以将指定用户请出直播间。
+``` kotlin
+class AudienceManager {
+    fun kick(userId: String) {
+        audienceStore.kickUserOutOfRoom(userId, object : CompletionHandler {
+            override fun onSuccess() {
+                println("成功将用户 $userId 踢出房间")
+                // 踢出成功后，您会收到 onAudienceLeft 事件
+            }
+
+            override fun onFailure(code: Int, desc: String) {
+                println("踢出用户 $userId 失败: $desc")
+            }
+        })
+    }
+}
+```
+
+#### 4.2 设置/撤销管理员
+
+通过 `setAdministrator` 和 `revokeAdministrator` 接口可以管理用户的管理员身份。
+``` kotlin
+class AudienceManager {
+    /// 将用户设为管理员
+    fun promoteToAdmin(userId: String) {
+        audienceStore.setAdministrator(userId, object : CompletionHandler {
+            override fun onSuccess() {
+                println("成功将用户 $userId 设为管理员")
+            }
+
+            override fun onFailure(code: Int, desc: String) {
+                println("设置管理员失败: $desc")
+            }
+        })
+    }
+
+    /// 撤销用户的管理员身份
+    fun revokeAdmin(userId: String) {
+        audienceStore.revokeAdministrator(userId, object : CompletionHandler {
+            override fun onSuccess() {
+                println("成功撤销用户 $userId 的管理员身份")
+            }
+
+            override fun onFailure(code: Int, desc: String) {
+                println("撤销管理员失败: $desc")
+            }
+        })
+    }
+}
+```
+
+## 功能进阶
+
+### 在弹幕区展示观众入场欢迎语
+
+当有新观众进入直播间时，弹幕/聊天区域会在本地自动显示一条欢迎消息，例如："欢迎 [用户昵称] 进入直播间"。
+
+#### 实现方式
+
+我们通过添加 `LiveAudienceStore` 的观众加入事件监听器（`LiveAudienceListener.onAudienceJoined`）来获取新观众加入的实时通知。一旦事件触发，我们便提取出新观众的昵称信息，然后立即调用 `BarrageStore` 的本地插入接口 `appendLocalTip`。
+``` kotlin
+import io.trtc.tuikit.atomicxcore.api.live.LiveAudienceListener
+import io.trtc.tuikit.atomicxcore.api.live.LiveAudienceStore
+import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
+import io.trtc.tuikit.atomicxcore.api.barrage.Barrage
+import io.trtc.tuikit.atomicxcore.api.barrage.BarrageStore
+import io.trtc.tuikit.atomicxcore.api.barrage.BarrageType
+
+class LiveRoomManager(
+    private val liveId: String
+) {
+
+    init {
+        // 初始化两个核心管理器
+        setupWelcomeMessageFlow()
+    }
+
+    private fun setupWelcomeMessageFlow() {
+        // 1. 获取 LiveAudienceStore 的实例
+        val audienceStore = LiveAudienceStore.create(liveId)
+
+        // 2. 获取 BarrageStore 的实例 (得益于内部机制，这会是同一个实例)
+        val barrageStore = BarrageStore.create(liveId)
+
+        // 3. 订阅观众事件
+        audienceStore.addLiveAudienceListener(object : LiveAudienceListener() {
+            override fun onAudienceJoined(audience: LiveUserInfo) {
+                // 4. 创建一条本地提示消息
+                val welcomeTip = Barrage().apply {
+                    liveID = liveId
+                    messageType = BarrageType.TEXT
+                    textContent = "欢迎 ${audience.userName} 进入直播间！"
+                }
+
+                // 5. 调用 BarrageStore 的接口将其插入弹幕列表
+                barrageStore.appendLocalTip(welcomeTip)
+            }
+        })
+    }
+}
+```
+
+## API 文档
+
+关于 [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-audience-store/index.html) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicX Core](https://tencent-rtc.github.io/TUIKit_Android/index.html) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
+| Store/Component | 功能描述 | API 文档 |
+| --- | --- | --- |
+| LiveCoreView | 直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-live-core-view/index.html) |
+| LiveAudienceStore | 观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-live-core-view/index.html) |
+| BarrageStore | 弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.barrage/-barrage-store/index.html) |
+
+## 常见问题
+
+### `LiveAudienceState` 中的在线人数（`audienceCount`）是如何更新的？时机和频率是怎样的？
+
+`audienceCount` 的更新并非总是实时的，其机制如下：
+- **主动进出房间**: 当用户主动加入或正常退出直播间时，在线人数的变更通知会即时触发。您会很快在 `LiveAudienceState` 中观察到 `audienceCount` 的变化。
+
+- **异常掉线**: 当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。
+
+- **更新机制与频率控制:**
+
+  - 无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。
+
+  - 房间内每秒的消息总量有上限，单房间消息频控是**每秒 40 条消息**。
+
+  - **关键点: 在"弹幕风暴"或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，人数变更的消息可能会被频控策略丢弃**。
+
+      **这对开发者意味着什么？**
+
+      `audienceCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于**UI展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。