@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

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

@@ -0,0 +1,365 @@
+`LiveListStore` 是 `AtomicXCore` 中负责管理直播房间列表、创建、加入以及维护房间状态的核心模块。通过`LiveListStore`，您可以为您的应用构建完整的直播生命周期管理。
+
+## 核心功能
+- **直播列表拉取**：获取当前所有公开的直播间列表，支持分页加载。
+
+- **直播生命周期管理**：提供从创建、开播、加入、离开到结束直播的全套流程接口。
+
+- **直播信息更新**：主播可以随时更新直播间的公开信息，例如封面、公告等。
+
+- **实时事件监听**：监听直播结束、用户被踢出等关键事件。
+
+- **自定义业务数据**：强大的自定义元数据（`MetaData`）能力，允许您在房间内存储和同步任何业务相关的信息，例如直播状态、音乐信息、自定义角色等 。
+
+## 核心概念
+
+在开始集成之前，我们先通过下表了解一下 `LiveListStore` 相关的几个核心概念：
+| **核心概念** | **类型** | **核心职责与描述** |
+| --- | --- | --- |
+| `LiveInfo` | `data class` | 代表一个直播间的所有信息模型。包含了直播ID (`liveID`)、名称 (`liveName`)、房主信息 (`liveOwner`) 以及自定义元数据 (`metaData`) 等。 |
+| `LiveListState` | `data class` | 代表直播列表模块的当前状态。其核心属性 liveList 是一个 `StateFlow`，存储了拉取到的直播列表；`currentLive` 则代表用户当前所在的直播间信息。 |
+| `LiveListListener` | `abstract class` | 代表直播房间的全局事件。分为 `onLiveEnded` (直播结束) 和 `onKickedOutOfLive` (被踢出直播) 两种，用于处理关键的房间状态变更。 |
+| `LiveListStore` | `abstract class` | 代表直播房间的全局事件。分为 `.onLiveEnded` (直播结束) 和 `.onKickedOutOfLive` (被踢出直播) 两种，用于处理关键的房间状态变更。 |
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 开始直播 集成 **AtomicXCore**，并完成 主播开播 和 观众观看 的功能实现。
+
+### 步骤2：实现观众从直播列表进入直播间
+
+创建一个展示直播列表的页面，该页面使用 `RecyclerView` 来布局直播间卡片。当用户点击某个卡片时，获取该直播间的 `liveId`，并跳转到观众观看页面。
+``` kotlin
+import android.content.Intent
+import android.os.Bundle
+import android.view.LayoutInflater
+import android.view.View
+import android.view.ViewGroup
+import androidx.appcompat.app.AppCompatActivity
+import androidx.recyclerview.widget.GridLayoutManager
+import androidx.recyclerview.widget.RecyclerView
+import io.trtc.tuikit.atomicxcore.api.*
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+class LiveListActivity : AppCompatActivity() {
+    private val liveListStore = LiveListStore.shared()
+    private var liveList: List<LiveInfo> = emptyList()
+    private val coroutineScope = CoroutineScope(Dispatchers.Main)
+
+    private lateinit var recyclerView: RecyclerView
+    private lateinit var adapter: LiveListAdapter
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_live_list)
+        setupUI()
+        bindStore()
+        fetchLiveList()
+    }
+
+    private fun bindStore() {
+        // 订阅 state，自动接收列表更新
+        coroutineScope.launch {
+            liveListStore.liveState.liveList.collect { fetchedList ->
+                liveList = fetchedList
+                adapter.notifyDataSetChanged()
+            }
+        }
+    }
+
+    private fun fetchLiveList() {
+        liveListStore.fetchLiveList(
+            cursor = "",
+            count = 20,
+            completion = object : CompletionHandler {
+                override fun onSuccess() {
+                    println("直播列表拉取成功")
+                }
+
+                override fun onFailure(code: Int, desc: String) {
+                    println("直播列表拉取失败: $desc")
+                }
+            }
+        )
+    }
+
+    // 当用户点击列表中的某个Item时
+    private fun onLiveItemClick(liveInfo: LiveInfo) {
+        // 创建观众观看页面，并将 liveId 传入
+        val intent = Intent(this, YourAudienceActivity::class.java)
+        intent.putExtra("liveId", liveInfo.liveID)
+        startActivity(intent)
+    }
+
+    // --- RecyclerView 相关方法 ---
+    private fun setupUI() {
+        recyclerView = findViewById(R.id.recyclerView)
+        adapter = LiveListAdapter(liveList) { liveInfo ->
+            onLiveItemClick(liveInfo)
+        }
+        recyclerView.layoutManager = GridLayoutManager(this, 2)
+        recyclerView.adapter = adapter
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        coroutineScope.cancel()
+    }
+}
+
+// RecyclerView Adapter
+class LiveListAdapter(
+    private var liveList: List<LiveInfo>,
+    private val onItemClick: (LiveInfo) -> Unit
+) : RecyclerView.Adapter<LiveListAdapter.LiveViewHolder>() {
+
+    class LiveViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) {
+        // 定义您的ViewHolder视图组件
+        // val titleTextView: TextView = itemView.findViewById(R.id.titleTextView)
+        // val coverImageView: ImageView = itemView.findViewById(R.id.coverImageView)
+    }
+
+    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): LiveViewHolder {
+        val view = LayoutInflater.from(parent.context)
+            .inflate(R.layout.item_live_card, parent, false)
+        return LiveViewHolder(view)
+    }
+
+    override fun onBindViewHolder(holder: LiveViewHolder, position: Int) {
+        val liveInfo = liveList[position]
+        // 设置数据到ViewHolder
+        // holder.titleTextView.text = liveInfo.liveName
+        // 加载封面图片等
+
+        holder.itemView.setOnClickListener {
+            onItemClick(liveInfo)
+        }
+    }
+
+    override fun getItemCount(): Int = liveList.size
+}
+
+```
+
+**LiveInfo 参数说明**
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `liveID` | `String` | 直播间的唯一标识符 |
+| `liveName` | `String` | 直播间的标题 |
+| `coverURL` | `String` | 直播间的封面图片地址 |
+| `liveOwner` | [LiveUserInfo](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-live-user-info/index.html) | 房主的个人信息 |
+| `totalViewerCount` | `Int` | 直播间的总观看人数 |
+| `categoryList` | `List<Int>` | 直播间的分类标签列表 |
+| `notice` | `String` | 直播间的公告信息 |
+| `metaData` | `Map<String: String>` | 开发者自定义的元数据，用于实现复杂的业务场景 |
+
+## 功能进阶
+
+### 场景一：实现直播列表的分类展示
+
+在 App 的直播广场页，顶部设有"热门"、"音乐"、"游戏"等分类标签。用户点击不同的标签后，下方的直播列表会动态筛选，只展示对应分类的直播间，从而帮助用户快速发现感兴趣的内容。
+
+#### 实现方式
+
+核心是利用 `LiveInfo` 模型中的 `categoryList` 属性。当主播开播设置分类后，`fetchLiveList` 返回的 `LiveInfo` 对象中就会包含这些分类信息。您的 App 在获取到完整的直播列表后，只需在客户端根据用户选择的分类，对这个列表进行一次简单的筛选，然后刷新 UI 即可。
+
+#### 代码示例
+
+以下示例展示了如何在 `LiveListActivity` 中扩展一个 `LiveListManager` 来处理数据和筛选逻辑。
+``` kotlin
+import android.os.Bundle
+import androidx.appcompat.app.AppCompatActivity
+import androidx.recyclerview.widget.RecyclerView
+import io.trtc.tuikit.atomicxcore.api.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+// 1. 创建一个数据管理器来封装数据获取和筛选逻辑
+class LiveListManager {
+    private val liveListStore = LiveListStore.shared()
+    private var fullLiveList: List<LiveInfo> = emptyList()
+
+    // 对外暴露最终的直播列表
+    private val _filteredLiveList = MutableStateFlow<List<LiveInfo>>(emptyList())
+    val filteredLiveList: StateFlow<List<LiveInfo>> = _filteredLiveList
+
+    init {
+        // 监听完整列表变化
+        CoroutineScope(Dispatchers.Main).launch {
+            liveListStore.liveState.liveList.collect { fetchedList ->
+                fullLiveList = fetchedList
+                // 默认将完整列表发布出去
+                _filteredLiveList.value = fetchedList
+            }
+        }
+    }
+
+    fun fetchFirstPage() {
+        liveListStore.fetchLiveList(cursor = "", count = 20, completion = null)
+    }
+
+    /// 根据分类筛选直播列表
+    fun filterLiveList(categoryId: Int?) {
+        if (categoryId == null) {
+            // 如果 categoryId 为 null，则显示完整列表
+            _filteredLiveList.value = fullLiveList
+            return
+        }
+
+        val filteredList = fullLiveList.filter { liveInfo ->
+            liveInfo.categoryList.contains(categoryId)
+        }
+        _filteredLiveList.value = filteredList
+    }
+}
+
+// 2. 在您的 LiveListActivity 中使用 Manager
+class LiveListActivity : AppCompatActivity() {
+    private val manager = LiveListManager()
+    private lateinit var recyclerView: RecyclerView
+    private lateinit var adapter: LiveListAdapter
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_live_list)
+        // setupUI()
+
+        // 绑定数据
+        CoroutineScope(Dispatchers.Main).launch {
+            manager.filteredLiveList.collect { filteredList ->
+                // 刷新UI
+               // adapter.updateList(filteredList)
+            }
+        }
+
+        // 首次拉取
+        manager.fetchFirstPage()
+    }
+
+    // 当用户点击顶部分类标签时
+    fun onCategorySelected(categoryId: Int) {
+        manager.filterLiveList(categoryId)
+    }
+
+    // ... (RecyclerView 相关代码)
+}
+```
+
+### 场景二：实现语聊房内的自定义状态同步
+
+在语聊房中，主播可能需要向所有观众同步一些自定义信息，例如“当前房间话题”、“背景音乐信息”等。`LiveListStore` 的 `MetaData` 功能可以实现这一点。
+
+#### 实现方式：
+
+主播端将自定义信息通过 `updateLiveMetaData` 接口设置到一个或多个 `key` 中。`AtomicXCore` 会将这个变更实时同步给所有观众。观众端只需订阅` LiveListState.currentLive`，监听 `metaData` 的变化，一旦发现关心的 `key` 更新，就解析其 `value` 并刷新业务状态。
+
+#### 示例代码：
+``` java
+import io.trtc.tuikit.atomicxcore.api.LiveListStore
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import com.google.gson.Gson
+import io.trtc.tuikit.atomicxcore.api.MetaDataCompletionHandler
+
+// 1. 定义一个背景音乐模型 (使用 data class)
+data class MusicModel(
+    val musicId: String,
+    val musicName: String
+)
+
+// 2. 主播端：在您的主播业务逻辑中，添加推送背景音乐的方法
+fun updateBackgroundMusic(music: MusicModel) {
+    val gson = Gson()
+    val jsonString = gson.toJson(music) ?: ""
+
+    // 将要更新的 metaData
+    val metaData = hashMapOf("music_info" to jsonString)
+
+    // 更新 metaData
+    LiveListStore.shared()
+        .updateLiveMetaData(
+            metaData,
+            object : CompletionHandler {
+                override fun onSuccess() {
+                    print("背景音乐 ${music.musicName} 推送成功")
+                }
+
+                override fun onFailure(code: Int, desc: String) {
+                    print("背景音乐推送失败: $desc")
+                }
+            }
+        )
+}
+
+// 3. 观众端：在您的观众业务逻辑中 ，添加监听背景音乐变化的方法
+private fun subscribeToDataUpdates() {
+    CoroutineScope(Dispatchers.Main).launch {
+        LiveListStore.shared()
+            .liveState
+            .currentLive
+            .map { it.metaData }
+            .collect {
+                val musicInfo = it["music_info"]
+                // 刷新业务状态，例如播放新的背景音乐
+            }
+    }
+}
+
+```
+
+## API 文档
+
+关于 [LiveListStore](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) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Android/index.html) 框架的官方 API 文档。本文档使用到的相关 `Store` 如下：
+| **Store/Component** | **功能描述** | **API 文档** |
+| --- | --- | --- |
+| **LiveListStore** | 直播间全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改直播信息（名称、公告等），监听直播状态（例如被踢出、结束）。 | [API 文档](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) |
+
+## 常见问题
+
+### 语聊房的列表和视频直播的列表数据是同一份吗？
+
+它们的数据是同一份，您不需要分开拉取。`LiveListStore` 是一个全局单例，它负责统一管理应用中所有“直播”房间的生命周期，无论是视频直播还是语聊房。
+
+### **直播列表中如何区分语聊房和视频直播**
+
+`LiveListStore` 本身不区分房间的业务类型。您需要在获取列表后，在客户端的应用层（业务逻辑或 `UI` 层）进行筛选和分类。
+
+我们推荐采用以下两种方式进行区分：
+
+**方式一（推荐）**：**使用 seatLayoutTemplateID 区分**。这是一个用于定义房间布局的模板 `ID`，关于目前已支持的模板 `ID` 和效果，请参阅文档 开始直播 > 运行效果。您要在创建房间时指定 `ID`，然后在获取列表时根据 `ID` 范围来识别业务场景。
+- **步骤1**：**创建房间时指定 ID **调用 `LiveListStore.shared.createLive` 时，您需要根据业务场景为 `LiveInfo` 的 `seatLayoutTemplateID` 属性传入指定范围的 `ID`：
+
+  - 语聊房场景：传入 1 - 199 范围内的模板 `ID`。
+
+  - 视频直播场景：传入 200 - 999 范围内的模板 `ID`。
+
+- **步骤2**：**获取列表时筛选 **客户端在 `LiveListStore.state.liveList` 中收到列表数据后，通过判断这个 `ID` 值所属的范围判断，从而在进入直播间的时候区分两种业务场景。
+
+   > **重要提示：**
+   >
+
+   > 创建房间时，如果传入的 `seatLayoutTemplateID` 范围与您的业务场景（语聊房、视频直播）不匹配，可能会导致麦位布局出现功能异常。
+   >
+
+   **方式二**：**为 **`liveID`** 添加业务前缀。**这是一种可选的、纯粹的应用层约定，用于辅助您在客户端快速筛选。
+
+  - 步**骤1：创建房间时添加前缀 **在您生成 `liveID` 并调用 `createLive` 时，为不同业务类型的 `liveID` 赋予不同的前缀。例如：视频直播的 `ID` 以 “`Live_`” 开头 (例如：`Live_12345`)，语聊房的 `ID` 以 “`voice_`” 开头 (例如：`voice_67890`)。
+
+  - **步骤2：获取列表时检查前缀 **客户端在拉取到列表后，通过检查 `liveID` 字符串的前缀来进行区分。
+
+### 使用 `updateLiveMetaData` 时有哪些需要注意的限制和规则？
+
+为了保证系统的稳定和高效，`metaData` 的使用遵循以下规则：
+- **权限**: 只有房主和管理员可以调用 `updateLiveMetaData`。普通观众没有权限。
+
+- **数量与大小限制**：
+
+  - 单个房间最多支持 **10** 个 `key`。
+
+  - 每个 `key` 的长度不超过 **50 字节**，每个 `value` 的长度不超过 **2KB**。
+
+  - 单个房间所有 `value` 的总大小不超过 **16KB**。
+
+- **冲突解决**： `metaData` 的更新机制是“后来者覆盖”。如果多个管理员在短时间内修改同一个 `key`，最后一次的修改会生效。建议在业务设计上避免多人同时修改同一个关键信息。

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

@@ -0,0 +1,259 @@
+`LiveAudienceStore` 是 `AtomicXCore` 中专门负责管理直播间观众信息的模块。通过 `LiveAudienceStore`，您可以为您的直播应用构建一套完整的观众列表及管理系统。
+
+## 核心功能
+- **实时观众列表**：获取并展示当前在直播间内的所有观众信息。
+
+- **观众人数统计**：实时获取当前直播间的准确观众总数。
+
+- **观众动态监听**：通过事件订阅，实时感知观众的加入和离开。
+
+- **管理员权限**：主播可以将普通观众设为管理员，或撤销其管理员身份。
+
+- **房间管理**：主播或管理员可以将任意普通观众请出（踢出）直播间。
+
+## 核心概念
+
+下表介绍了 `LiveAudienceStore` 的核心概念：
+| **核心概念** | **类型** | **核心职责与描述** |
+| --- | --- | --- |
+| [LiveUserInfo](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveUserInfo-class.html) | `class` | 代表一个观众（用户）的基础信息模型。它包含了用户的唯一标识 (`userID`)、昵称 (`userName`) 和头像地址 (`avatarURL`)。 |
+| [LiveAudienceState](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceState-class.html) | `class` | 代表观众模块的当前状态。其核心属性 `audienceList` 是一个 `ValueListenable<List<LiveUserInfo>>`，存储了观众列表的快照；`audienceCount` 则代表当前观众总数。 |
+| [LiveAudienceListener](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceListener-class.html) | `class` | 代表观众动态的实时事件监听器。包含 `onAudienceJoined`（观众加入）和 `onAudienceLeft`（观众离开）两个回调，用于实现对观众列表的增量更新。 |
+| [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html) | `class` | 这是与观众列表功能交互的核心管理类。通过它，您可以获取观众列表快照、执行管理操作，并通过 `addLiveAudienceListener` 来接收实时动态。 |
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 快速接入 集成 **AtomicXCore**，完成接入。
+
+### 步骤2：初始化并获取观众列表
+
+获取一个与当前直播间 liveId 绑定的 `LiveAudienceStore` 实例，并主动拉取一次当前的观众列表，用于首次展示。
+
+在退出直播间时可通过调用 `AudienceManager` 的 `dispose` 方法回收资源。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+class AudienceManager {
+    final String liveId;
+    late final LiveAudienceStore audienceStore;
+    late LiveAudienceListener _audienceListener;
+    late final VoidCallback _audienceListChangedListener = _onAudienceListChanged;
+    late final VoidCallback _audienceCountChangedListener = _onAudienceCountChanged;
+
+    // 对外暴露【全量】观众列表
+    List<LiveUserInfo> audienceList = [];
+    // 对外暴露观众总数
+    int audienceCount = 0;
+
+    // 状态变更回调
+    Function()? onStateChanged;
+
+    AudienceManager({required this.liveId}) {
+        // 1. 通过 liveId 获取 LiveAudienceStore 的实例
+        audienceStore = LiveAudienceStore.create(liveId);
+
+        // 2. 订阅状态和事件
+        _subscribeToAudienceState();
+        _subscribeToAudienceEvents();
+
+        // 3. 主动拉取首屏数据
+        fetchInitialAudienceList();
+    }
+
+    /// 主动获取一次观众列表快照
+    Future<void> fetchInitialAudienceList() async {
+        final result = await audienceStore.fetchAudienceList();
+        if (result.isSuccess) {
+            print("首次拉取观众列表成功");
+            // 成功后，数据会通过下面的 state 订阅通道自动更新
+        } else {
+            print("首次拉取观众列表失败: ${result.errorMessage}");
+        }
+    }
+
+    void dispose() {
+        audienceStore.liveAudienceState.audienceList.removeListener(_audienceListChangedListener);
+        audienceStore.liveAudienceState.audienceCount.removeListener(_audienceCountChangedListener);
+        audienceStore.removeLiveAudienceListener(_audienceListener);
+    }
+}
+```
+
+观众列表等 `state` 订阅将在下一步骤详细讲解。
+
+### 步骤3：监听观众列表状态与实时动态
+
+订阅 `audienceStore` 的 `liveAudienceState` 和 `LiveAudienceListener`，以接收全量列表快照和实时的观众进出事件，从而驱动 UI 更新。
+``` java
+extension AudienceManagerSubscription on AudienceManager {
+    /// 订阅 state，用于获取观众总数和列表快照
+    void _subscribeToAudienceState() {
+        // 监听观众列表变化
+        audienceStore.liveAudienceState.audienceList.addListener(_audienceListChangedListener);
+        // 监听观众人数变化
+        audienceStore.liveAudienceState.audienceCount.addListener(_audienceCountChangedListener);
+    }
+
+    void _onAudienceListChanged() {
+        // audienceList 是一个全量快照
+        audienceList = audienceStore.liveAudienceState.audienceList.value;
+        onStateChanged?.call();
+    }
+
+    void _onAudienceCountChanged() {
+        // audienceCount 是实时总数
+        audienceCount = audienceStore.liveAudienceState.audienceCount.value;
+        onStateChanged?.call();
+    }
+
+    /// 订阅 event，用于处理观众的实时进出
+    void _subscribeToAudienceEvents() {
+        _audienceListener = LiveAudienceListener(
+            onAudienceJoined: (audience) {
+                print("观众 ${audience.userName} 加入了直播间");
+                // 增量更新：在当前列表末尾添加新观众
+                if (!audienceList.any((a) => a.userID == audience.userID)) {
+                    audienceList.add(audience);
+                    onStateChanged?.call();
+                }
+            },
+            onAudienceLeft: (audience) {
+                print("观众 ${audience.userName} 离开了直播间");
+                // 增量更新：从当前列表中移除离开的观众
+                audienceList.removeWhere((a) => a.userID == audience.userID);
+                onStateChanged?.call();
+            },
+        );
+        audienceStore.addLiveAudienceListener(_audienceListener);
+    }
+}
+```
+
+### 步骤4：管理观众（踢人与设置管理员）
+
+作为主播或管理员，对直播间内的观众进行管理操作。
+
+#### 4.1 将观众踢出直播间
+
+调用 `kickUserOutOfRoom` 接口可以将指定用户请出直播间。
+``` java
+extension AudienceManagerActions on AudienceManager {
+    Future<void> kick(String userId) async {
+        final result = await audienceStore.kickUserOutOfRoom(userId);
+        if (result.isSuccess) {
+            print("成功将用户 $userId 踢出房间");
+            // 踢出成功后，您会收到 onAudienceLeft 事件
+        } else {
+            print("踢出用户 $userId 失败: ${result.errorMessage}");
+        }
+    }
+}
+```
+
+#### 4.2 设置/撤销管理员
+
+通过 `setAdministrator` 和 `revokeAdministrator` 接口可以管理用户的管理员身份。
+``` java
+extension AudienceManagerAdmin on AudienceManager {
+    /// 将用户设为管理员
+    Future<void> promoteToAdmin(String userId) async {
+        final result = await audienceStore.setAdministrator(userId);
+        if (result.isSuccess) {
+            print("成功将用户 $userId 设为管理员");
+        }
+    }
+
+    /// 撤销用户的管理员身份
+    Future<void> revokeAdmin(String userId) async {
+        final result = await audienceStore.revokeAdministrator(userId);
+        if (result.isSuccess) {
+            print("成功撤销用户 $userId 的管理员身份");
+        }
+    }
+}
+```
+
+## 功能进阶
+
+### 在弹幕区展示观众入场欢迎语
+
+当有新观众进入直播间时，弹幕/聊天区域会在本地自动显示一条欢迎消息，例如："欢迎 [用户昵称] 进入直播间"。
+
+#### 实现方式
+
+我们通过订阅 `LiveAudienceStore` 的观众加入事件（`onAudienceJoined`）来获取新观众加入的实时通知。一旦事件触发，我们便提取出新观众的昵称信息，然后立即调用 `BarrageStore` 的本地插入接口 `appendLocalTip`。
+
+在退出直播间时可通过调用 `LiveRoomManager` 的 `dispose` 方法回收资源。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+class LiveRoomManager {
+    final String liveId;
+    late LiveAudienceListener _welcomeListener;
+
+    LiveRoomManager({required this.liveId}) {
+        _setupWelcomeMessageFlow();
+    }
+
+    void _setupWelcomeMessageFlow() {
+        // 1. 获取 LiveAudienceStore 的实例
+        final audienceStore = LiveAudienceStore.create(liveId);
+
+        // 2. 获取 BarrageStore 的实例 (得益于内部机制，这会是同一个实例)
+        final barrageStore = BarrageStore.create(liveId);
+
+        // 3. 订阅观众事件
+        _welcomeListener = LiveAudienceListener(
+            onAudienceJoined: (audience) {
+                // 4. 创建一条本地提示消息
+                final welcomeTip = Barrage(
+                    messageType: BarrageType.text,
+                    textContent: "欢迎 ${audience.userName} 进入直播间！",
+                );
+
+                // 5. 调用 BarrageStore 的接口将其插入弹幕列表
+                barrageStore.appendLocalTip(welcomeTip);
+            },
+        );
+        audienceStore.addLiveAudienceListener(_welcomeListener);
+    }
+
+    void dispose() {
+        final audienceStore = LiveAudienceStore.create(liveId);
+        audienceStore.removeLiveAudienceListener(_welcomeListener);
+    }
+}
+```
+
+## API 文档
+
+关于 [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html) 及其相关类的所有公开接口、属性和方法的详细信息，请参考 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Flutter/index.html) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
+| **Store/Component** | **功能描述** | **API 文档** |
+| --- | --- | --- |
+| **LiveCoreWidget** | 直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreWidget-class.html) |
+| **LiveCoreController** | LiveCoreWidget 的控制器：用于设置直播 ID、控制预览等操作。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreController-class.html) |
+| **LiveAudienceStore** | 观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html) |
+| **BarrageStore** | 弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。 | [API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_barrage_barrage_store/api_barrage_barrage_store-library.html) |
+
+## 常见问题
+
+### `LiveAudienceState` 中的在线人数（`audienceCount`）是如何更新的？时机和频率是怎样的？
+
+`audienceCount` 的更新并非总是实时的，其机制如下：
+- **主动进出房间**：当用户主动加入或正常退出直播间时，在线人数的变更通知会即时触发。您会很快在 `LiveAudienceState` 中观察到 `audienceCount` 的变化。
+
+- **异常掉线**：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。
+
+- **更新机制与频率控制：**
+
+  - 无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。
+
+  - 房间内每秒的消息总量有上限，单房间消息频控是**每秒 40 条消息**。
+
+  - **关键点：**在"弹幕风暴"或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，**人数变更的消息可能会被频控策略丢弃**。
+
+      **这对开发者意味着什么？**
+
+      `audienceCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 **UI 展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。