@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

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

@@ -0,0 +1,262 @@
+`LiveAudienceStore` 是 `AtomicXCore` 中专门负责管理直播间观众信息的模块。通过 `LiveAudienceStore`，您可以为您的直播应用构建一套完整的观众列表及管理系统。
+
+## 核心功能
+- **实时观众列表**：获取并展示当前在直播间内的所有观众信息。
+
+- **观众人数统计**：实时获取当前直播间的准确观众总数。
+
+- **观众动态监听**：通过事件订阅，实时感知观众的加入和离开。
+
+- **管理员权限**：主播可以将普通观众设为管理员，或撤销其管理员身份。
+
+- **房间管理**：主播或管理员可以将任意普通观众请出（踢出）直播间。
+
+## 核心概念
+
+在开始集成之前，我们先通过下表了解一下 LiveAudienceStore 相关的几个核心概念：
+| **核心概念** | **类型** | **核心职责与描述** |
+| --- | --- | --- |
+| `LiveUserInfo` | struct | 代表一个观众（用户）的基础信息模型。它包含了用户的唯一标识 (`userID`)、昵称 (`userName`) 和头像地址 (`avatarURL`)。 |
+| `LiveAudienceState` | struct | 代表观众模块的当前状态。其核心属性 `audienceList` 是一个 `[LiveUserInfo] `数组，存储了观众列表的快照；`audienceCount` 则代表当前观众总数。 |
+| `LiveAudienceEvent` | enum | 代表观众动态的实时事件。分为 `.onAudienceJoined`（观众加入） 和 `.onAudienceLeft`（观众离开）两种，用于实现对观众列表的增量更新。 |
+| `LiveAudienceStore` | class | 这是与观众列表功能交互的核心管理类。通过它，您可以获取观众列表快照、执行管理操作，并通过订阅其 `liveAudienceEventPublisher` 来接收实时动态。 |
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 开始直播 集成 **AtomicXCore**，完成接入。
+
+### 步骤2：初始化并获取观众列表
+
+获取一个与当前直播间 liveId 绑定的 `LiveAudienceStore` 实例，并主动拉取一次当前的观众列表，用于首次展示。
+``` swift
+import Foundation
+import AtomicXCore
+import Combine
+
+class AudienceManager {
+    private let liveId: String
+    private let audienceStore: LiveAudienceStore
+    private var cancellables = Set<AnyCancellable>()
+
+    // 对外暴露【全量】观众列表的发布者，方便UI层订阅
+    let audienceListPublisher = CurrentValueSubject<[LiveUserInfo], Never>([])
+    // 对外暴露观众总数的发布者
+    let audienceCountPublisher = PassthroughSubject<UInt, Never>()
+
+    init(liveId: String) {
+        self.liveId = liveId
+        // 1. 通过 liveId 获取 LiveAudienceStore 的实例
+        self.audienceStore = LiveAudienceStore.create(liveID: liveId)
+
+        // 2. 订阅状态和事件
+        subscribeToAudienceState()
+        subscribeToAudienceEvents()
+
+        // 3. 主动拉取首屏数据
+        fetchInitialAudienceList()
+    }
+
+    /// 主动获取一次观众列表快照
+    func fetchInitialAudienceList() {
+        audienceStore.fetchAudienceList { [weak self] result in
+            switch result {
+            case .success:
+                print("首次拉取观众列表成功")
+                // 成功后，数据会通过下面的 state 订阅通道自动更新
+            case .failure(let error):
+                print("首次拉取观众列表失败: \(error.localizedDescription)")
+            }
+        }
+    }
+
+    // ... 后续代码
+}
+```
+
+### 步骤3：监听观众列表状态与实时动态
+
+订阅 `audienceStore` 的 `state` 和 `event`，以接收全量列表快照和实时的观众进出事件，从而驱动 UI 更新。
+``` swift
+extension AudienceManager {
+    /// 订阅 state，用于获取观众总数和列表快照
+    private func subscribeToAudienceState() {
+        audienceStore.state
+            .subscribe()
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] state in
+                // state.audienceList 是一个全量快照
+                self?.audienceListPublisher.send(state.audienceList)
+                // state.audienceCount 是实时总数
+                self?.audienceCountPublisher.send(state.audienceCount)
+            }
+            .store(in: &cancellables)
+    }
+
+    /// 订阅 event，用于处理观众的实时进出
+    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("观众 \(newAudience.userName) 加入了直播间")
+                    // 增量更新：在当前列表末尾添加新观众
+                    if !currentList.contains(where: { $0.userID == newAudience.userID }) {
+                        currentList.append(newAudience)
+                        self.audienceListPublisher.send(currentList)
+                    }
+
+                case .onAudienceLeft(let departedAudience):
+                    print("观众 \(departedAudience.userName) 离开了直播间")
+                    // 增量更新：从当前列表中移除离开的观众
+                    currentList.removeAll { $0.userID == departedAudience.userID }
+                    self.audienceListPublisher.send(currentList)
+                }
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+
+### 步骤4：管理观众（踢人与设置管理员）
+
+作为主播或管理员，对直播间内的观众进行管理操作。
+
+#### 4.1 将观众踢出直播间
+
+调用 `kickUserOutOfRoom` 接口可以将指定用户请出直播间。
+``` swift
+extension AudienceManager {
+    func kick(userId: String) {
+        audienceStore.kickUserOutOfRoom(userId: userId) { result in
+            switch result {
+            case .success:
+                print("成功将用户 \(userId) 踢出房间")
+                // 踢出成功后，您会收到 onAudienceLeft 事件
+            case .failure(let error):
+                print("踢出用户 \(userId) 失败: \(error.localizedDescription)")
+            }
+        }
+    }
+}
+```
+
+#### 4.2 设置/撤销管理员
+
+通过 `setAdministrator` 和 `revokeAdministrator` 接口可以管理用户的管理员身份。
+``` swift
+extension AudienceManager {
+    /// 将用户设为管理员
+    func promoteToAdmin(userId: String) {
+        audienceStore.setAdministrator(userId: userId) { result in
+            if case .success = result {
+                print("成功将用户 \(userId) 设为管理员")
+            }
+        }
+    }
+
+    /// 撤销用户的管理员身份
+    func revokeAdmin(userId: String) {
+        audienceStore.revokeAdministrator(userId: userId) { result in
+            if case .success = result {
+                print("成功撤销用户 \(userId) 的管理员身份")
+            }
+        }
+    }
+}
+```
+
+## 功能进阶
+
+### 在弹幕区展示观众入场欢迎语
+
+当有新观众进入直播间时，弹幕/聊天区域会在本地自动显示一条欢迎消息，例如：“欢迎 [用户昵称] 进入直播间”。
+
+#### 实现方式
+
+我们通过订阅 `LiveAudienceStore` 的观众加入事件（`LiveAudienceEvent.onAudienceJoined`）来获取新观众加入的实时通知。一旦事件触发，我们便提取出新观众的昵称信息，然后立即调用 `BarrageStore` 的本地插入接口 `appendLocalTip`。
+``` swift
+import Foundation
+import AtomicXCore
+import Combine
+
+class LiveRoomManager {
+    private let liveId: String
+    private let audienceManager: AudienceManager
+    private let barrageManager: BarrageManager // 假设您已实现了弹幕文档中的BarrageManager
+    private var cancellables = Set<AnyCancellable>()
+
+    init(liveId: String) {
+        self.liveId = liveId
+        // 初始化两个核心管理器
+        self.audienceManager = AudienceManager(liveId: liveId)
+        self.barrageManager = BarrageManager(liveId: liveId)
+
+        // 设置联动
+        setupWelcomeMessageFlow()
+    }
+
+    private func setupWelcomeMessageFlow() {
+        // 1. 获取 LiveAudienceStore 的实例
+        let audienceStore = LiveAudienceStore.create(liveID: self.liveId)
+
+        // 2. 获取 BarrageStore 的实例 (得益于内部机制，这会是同一个实例)
+        let barrageStore = BarrageStore.create(liveID: self.liveId)
+
+        // 3. 订阅观众事件
+        audienceStore.liveAudienceEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { event in
+                // 4. 只处理观众加入事件
+                guard case .onAudienceJoined(let newAudience) = event else {
+                    return
+                }
+
+                // 5. 创建一条本地提示消息
+                var welcomeTip = Barrage()
+                welcomeTip.messageType = .text
+                welcomeTip.textContent = "欢迎 \(newAudience.userName) 进入直播间！"
+
+                // 6. 调用 BarrageStore 的接口将其插入弹幕列表
+                barrageStore.appendLocalTip(message: welcomeTip)
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+
+## API 文档
+
+关于 [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
+| Store/Component | 功能描述 | API 文档 |
+| --- | --- | --- |
+| LiveCoreView | 直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/livecoreview) |
+| LiveAudienceStore | 观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore) |
+| BarrageStore | 弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestore) |
+
+## 常见问题
+
+### `LiveAudienceState` 中的在线人数（`audienceCount`）是如何更新的？时机和频率是怎样的？
+
+`audienceCount` 的更新并非总是实时的，其机制如下：
+- **主动进出房间**：当用户主动加入或正常退出直播间时，在线人数的变更通知会即时触发。您会很快在 `LiveAudienceState` 中观察到 `audienceCount` 的变化。
+
+- **异常掉线**：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。
+
+- **更新机制与频率控制：**
+
+  - 无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。
+
+  - 房间内每秒的消息总量有上限，单房间消息频控是**每秒 40 条消息**。
+
+  - **关键点：**在“弹幕风暴”或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（如弹幕）的送达，**人数变更的消息可能会被频控策略丢弃**。
+
+      **这对开发者意味着什么？**
+
+      `audienceCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 **UI 展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。

package/resource/doc/livekit/core-sdk/voice/ios/voice-audio-effect.md

@@ -0,0 +1,211 @@
+本篇文档旨在指导您如何使用 `AtomicXCore` 框架中的  `AudioEffectStore` 和 `DeviceStore` 模块，为您的直播应用快速集成音效控制功能，包括麦克风音量、耳返监听，并添加多种趣味变声效果和混响效果。
+
+## 核心功能
+
+通过组合 `AudioEffectStore` 和 `DeviceStore`，您将能实现以下核心功能：
+- **人声音量调节**：控制本地音频上行的采集音量大小，即观众听到的您的声音大小。
+
+- **耳返功能**：允许主播或连麦用户通过耳机实时听到自己的声音，用于监听和矫正发音。
+
+- **变声效果**：提供多种趣味变声选项，例如萝莉、大叔、熊孩子等。
+
+- **混响效果**：模拟不同环境的声场效果，例如 KTV、金属声、低沉、洪亮等。
+
+## 概念说明
+| **核心概念** | **类型** | **核心职责与描述** |
+| --- | --- | --- |
+| `AudioChangerType` | `enum` | 变声效果枚举，例如，“小孩”，“男人”等。 |
+| `AudioReverbType` | `enum` | 混响效果枚举，例如，“ktv”，“礼堂”等。 |
+| `AudioEffectState` | `struct` | 代表音效模块的当前状态，通常用于 UI 渲染。包括变声状态、混响状态、耳返开启状态、耳返音量。 |
+| `AudioEffectStore` | `class` | 代表音效模块**单例数据管理类**。通过它您可以调用修改音效接口，当您调用接口后，相应的`state`属性会自动更新，可以通过订阅这个 state 响应式数据来接收和监听状态更新。 |
+| `DeviceState` | `struct` | 代表设备模块的当前状态，通常用于 UI 渲染。核心属性包括摄像头、麦克风的设备状态。 |
+| `DeviceStore` | `class` | 代表设备模块**单例数据管理类**。通过它您可以调用操作摄像头、麦克风接口，当您调用接口后，相应的`state`属性会自动更新，可以通过订阅这个 state 响应式数据来接收和监听状态更新。 |
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 快速接入 集成 **AtomicXCore。**
+
+### 步骤2：获取 Store 实例
+
+`AudioEffectStore` 和 `DeviceStore`是单例对象，您可以直接通过 shared 属性在项目的任何位置获取实例。您也可以参考 TUILiveKit 开源 UI Demo 项目中的 [AudioEffectView.swift](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/live/Sources/Component/AudioEffect/AudioEffectView.swift) 文件来了解完整的实现逻辑。
+``` swift
+import UIKit
+import AtomicXCore
+import Combine
+
+let audioEffectStore = AudioEffectStore.shared
+let deviceStore = DeviceStore.shared
+```
+
+### 步骤3：实现耳返功能
+
+耳返功能允许用户实时监听自己的麦克风声音，可以通过调用本节介绍的接口管理耳返功能。
+
+> **注意：**
+>
+
+> 耳返功能通常需要连接耳机才能正常工作。
+>
+
+#### 实现方式:
+1. **开关耳返**：您可以使用`UISwitch`控件实现开关耳返功能。
+
+2. **设置耳返音量值**：您可以使用 `UISlider` 控件实现左右拖动滑块来调节音量的功能，并将 `UISlider` 的值映射成音量值，调用`setOutputVolume(_ volume:)。`请注意，该接口接收的参数范围是 `[0, 150]`，所以您需要将 UI 控件的值（例如 UISlider 的 `0 - 1.0`）映射到 `0 - 150` 的范围。
+
+3. **监听状态更新UI**：您可以订阅实时的耳返状态值更新UI。
+
+#### 代码示例:
+``` swift
+// 1. 开启耳返
+audioEffectStore.setVoiceEarMonitorEnable(enable: true)
+
+// 2. 调节耳返音量
+audioEffectStore.setVoiceEarMonitorVolume(volume: 80)
+
+// 3. 关闭耳返
+audioEffectStore.setVoiceEarMonitorEnable(enable: false)
+
+// 4. 监听状态
+audioEffectStore.state
+    .subscribe(StatePublisherSelector(keyPath: \AudioEffectState.earMonitorVolume))
+    .removeDuplicates()
+    .sink { currentVolume in
+        print("耳返音量: \(currentVolume)")
+        valueLabel.text = "\(currentVolume)" //更新UILabel显示数值
+    }
+    .store(in: &cancellables)
+```
+
+#### setVoiceEarMonitorEnable 接口参数
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `enable` | `Bool` | 是否开启耳返。<br>- true：开启<br>- false：关闭 |
+
+#### setVoiceEarMonitorVolume 接口参数
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `volume` | `Int` | 耳返音量大小。<br>- 取值范围： [0, 150]<br>- 默认值：100 |
+
+### 步骤4：实现人声音量调节
+
+当主播希望调节自己的上行采集音量大小时，调用`DeviceStore`的`setCaptureVolume(volume: )`方法传入音量值即可。
+
+#### 实现方式:
+1. **设置采集音量值**：您可以使用 `UISlider` 控件实现左右拖动滑块来调节音量的功能，并将 `UISlider` 的值映射成音量值后调用`setCaptureVolume(volume: 80)。`请注意，该接口接收的参数范围是 `[0, 150]`，所以您需要将 UI 控件的值（例如 UISlider 的 `0 - 1.0`）映射到 `0 - 150` 的范围。
+
+2. **监听状态更新 UI**：您可以订阅实时的音量状态值更新 UI。
+
+#### 示例代码：
+``` swift
+// 1. 调节音量
+deviceStore.setCaptureVolume(volume: 80)
+
+// 2. 监听状态
+deviceStore.state
+    .subscribe(StatePublisherSelector(keyPath: \DeviceState.captureVolume))
+    .removeDuplicates()
+    .sink { captureVolume in
+        print("采集音量: \(captureVolume)")
+        valueLabel.text = "\(captureVolume)" //更新UILabel显示数值
+    }
+    .store(in: &cancellables)
+```
+
+#### setCaptureVolume 接口参数
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `volume` | `Int` | 采集音量大小。<br>- 取值范围： [0, 150]<br>- 默认值：100 |
+
+### 步骤5：实现变声效果
+
+当主播希望改变自己的声音时，您可以调用 `setAudioChangerType(type:)`方法，传入相应的Type 枚举值即可切换效果。
+
+#### 示例代码：
+``` swift
+// 示例：将变声效果设置为“小孩”
+audioEffectStore.setAudioChangerType(type: .child)
+// 示例：关闭变声效果
+audioEffectStore.setAudioChangerType(type: .none)
+```
+
+#### setAudioChangerType 接口参数
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `type` | `AudioChangerType` | 变声效果枚举。 |
+
+### 步骤6：实现混响效果
+
+当主播希望给自己的声音添加混响效果时，您可以调用`setAudioReverbType(type:)` 方法，传入相应的Type 枚举值即可切换效果。
+``` swift
+// 示例：设置为“KTV”混响效果
+audioEffectStore.setAudioReverbType(type: .ktv)
+// 示例：关闭混响效果
+audioEffectStore.setAudioReverbType(type: .none)
+```
+
+#### setAudioReverbType 接口参数
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `type` | `AudioReverbType` | 混响效果枚举。 |
+
+### 步骤7：重置音效设置
+
+> **重要：**
+>
+
+> AudioEffectStore和DeviceStore是单例，这意味着音效和设备设置是全局生效的，如果您在当前直播间的设置不想影响到您创建的其他直播间，就需要在当前直播间结束的时候重置音效和设备设置。
+>
+
+以下两种情况您可能需要重置音效设置：
+1. 当前直播间结束时，需要重置音效设置。
+
+2. 您需要提供“一键恢复”的功能，可以通过调用 store的`reset()` 方法实现。
+
+   ``` swift
+   class YourMainViewController: UIViewController {
+       func reset() {
+           AudioEffectStore.shared.reset()
+           DeviceStore.shared.reset()
+       }
+   }
+   ```
+
+## API 文档
+
+关于 [AudioEffectStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/audioeffectstore) 和 [DeviceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore) 及其相关类的所有公开接口、属性的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) 框架的官方 API 文档。
+| **Store/Component** | **功能描述** | **API 文档** |
+| --- | --- | --- |
+| AudioEffectStore | 音效管理：进行音效设置，并获取实时音效状态。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/audioeffectstore/) |
+| DeviceStore | 设备管理：进行摄像头、麦克风操作，并获取实时设备状态。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore) |
+
+## 常见问题
+
+### 音效和设备接口的调用时机有没有要求？
+
+没有限制。`AudioEffectStore`和`DeviceStore` 的设置是全局生效的，您可以在进入直播间之前或之后随时调用相关接口（例如设置变声、混响或耳返），设置会立即生效并被保留。
+
+### **“人声音量” 和“耳返音量” 有什么区别？**
+
+这是一个非常重要且易混淆的概念，区别如下：
+- **人声音量 (CaptureVolume)：**通过 `DeviceStore.setCaptureVolume()` 设置**。它决定了观众**能听到的您的声音大小。
+
+- **耳返音量 (EarMonitorVolume)：**通过 `AudioEffectStore.setVoiceEarMonitorVolume()`** 设置。它只**决定了**您自己**在耳机里听到的监听声音大小，**不会**影响观众。
+
+### **新创建的直播间为什么直接就有音效、或者出现音量很大、很小等问题？**
+
+`AudioEffectStore`和`DeviceStore`是单例，这意味着音效和设备设置是全局生效的，出现这种情况很可能是因为您之前设置过音效但是没有重置，需要在合适的地方调用`reset()`方法重置。
+
+### **为什么我开启了“耳返”，但是听不到自己的声音？**
+
+请您按照以下步骤检查：
+1. **是否插入耳机**：耳返功能绝大多数情况下依赖耳机才能生效，请确保已连接有线或蓝牙耳机。
+
+2. **音量是否为0**：检查“耳返音量”是否被设置为了 0。
+
+3. **麦克风是否开启**：确认 `DeviceStore` 中的麦克风是开启状态（即已调用 `openLocalMicrophone`）。
+
+### **变声效果 和混响效果 可以同时生效吗？**
+
+可以。`AudioChangerType` 和 `AudioReverbType` 是可以叠加生效的。例如，您可以同时设置 `.littleGirl` 变声和 `.ktv` 混响。