@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

package/resource/doc/livekit/core-sdk/live/android/api-reference/AudioEffectStore.md

@@ -0,0 +1,283 @@
+## 简介
+
+**AudioEffectStore** 提供了一套完整的音效管理 API，包括变声效果、混响效果和耳返功能。
+通过该类，主播可以在直播过程中实时调整自己的声音效果，提升直播体验。
+
+> **重要：**
+>
+
+> 使用 **AudioEffectStore.shared** 单例获取 **AudioEffectStore** 实例。设置的音效在退出房间后会自动失效，下次进房需要重新设置。
+>
+
+> **说明：**
+>
+
+> 音效状态更新通过 **audioEffectState** 发布者传递。订阅它以接收有关变声、混响和耳返状态的实时更新。
+>
+
+> **警告：**
+>
+
+> 由于蓝牙耳机的硬件延迟非常高，在主播佩戴蓝牙耳机时无法开启耳返功能。请在用户界面上提示主播佩戴有线耳机。
+>
+
+## 功能特性
+- **变声效果**：支持多种变声特效，如熊孩子、小女孩、大叔等。
+
+- **混响效果**：支持多种混响特效，如KTV、小房间、大会堂等。
+
+- **耳返功能**：主播可在耳机中听到自己的声音，适用于唱歌场景。
+
+- **音量控制**：支持耳返音量的精细调节。
+
+## 可订阅数据
+
+**AudioEffectState** 的字段描述如下：
+| **属性名** | **类型** | **描述** |
+| --- | --- | --- |
+| audioChangerType | StateFlow<AudioChangerType> | 变声状态。 |
+| audioReverbType | StateFlow<AudioReverbType> | 混响状态。 |
+| isEarMonitorOpened | StateFlow<Boolean> | 耳返开启。 |
+| earMonitorVolume | StateFlow<Int> | 耳返音量，取值范围 0 - 100。<br>如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。 |
+
+## API 列表
+| **函数名** | **描述** |
+| --- | --- |
+| AudioEffectStore.shared | 获取单例实例。 |
+| setAudioChangerType | 设置变声效果。 |
+| setAudioReverbType | 设置混响效果。 |
+| setVoiceEarMonitorEnable | 开启/关闭耳返。 |
+| setVoiceEarMonitorVolume | 设置耳返音量。 |
+| reset | 重置为默认状态。 |
+
+### 获取实例
+
+#### AudioEffectStore.shared
+
+获取单例实例。
+
+### 变声设置
+
+#### setAudioChangerType
+
+设置变声效果
+``` kotlin
+abstract fun setAudioChangerType(type: AudioChangerType)
+```
+
+通过该接口您可以设置人声的变声特效。
+
+变声特效可以作用于人声之上，通过声学算法对人声进行二次处理，以获得与原始声音所不同的音色。
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**调用时机**
+
+进入房间后，且需要使用变声效果时调用。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
+>
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| type | AudioChangerType | 必填 | 变声效果类型。 |
+
+### 混响设置
+
+#### setAudioReverbType
+
+设置混响效果
+``` kotlin
+abstract fun setAudioReverbType(type: AudioReverbType)
+```
+
+通过该接口您可以设置人声的混响效果。
+
+混响特效可以作用于人声之上，通过声学算法对声音进行叠加处理，模拟出各种不同环境下的临场感受。
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**调用时机**
+
+进入房间后，且需要使用混响效果时调用。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
+>
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| type | AudioReverbType | 必填 | 混响效果类型。 |
+
+### 耳返设置
+
+#### setVoiceEarMonitorEnable
+
+开启/关闭耳返
+``` kotlin
+abstract fun setVoiceEarMonitorEnable(enable: Boolean)
+```
+
+主播开启耳返后，可以在耳机里听到麦克风采集到的自己发出的声音，该特效适用于主播唱歌的应用场景中。
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**适用场景**
+
+适用于主播唱歌场景，让主播能够实时听到自己的声音以便调整演唱效果。
+
+**调用时机**
+
+进入房间后，且主播佩戴有线耳机时调用。
+
+**注意事项**
+
+> **警告：**
+>
+
+> 由于蓝牙耳机的硬件延迟非常高，所以在主播佩戴蓝牙耳机时无法开启此特效，请尽量在用户界面上提示主播佩戴有线耳机。
+>
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| enable | Boolean | 必填 | 是否开启耳返。 |
+
+#### setVoiceEarMonitorVolume
+
+设置耳返音量
+``` kotlin
+abstract fun setVoiceEarMonitorVolume(volume: Int)
+```
+
+通过该接口您可以设置耳返特效中声音的音量大小。
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**调用时机**
+
+开启耳返功能后调用。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。
+>
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| volume | Int | 必填 | 耳返音量。（取值范围：0 - 100（超过 100 可能导致爆音））（默认值：100）。 |
+
+### 重置
+
+#### reset
+
+重置为默认状态
+``` kotlin
+abstract fun reset()
+```
+
+将所有音效设置重置为默认值，包括关闭变声效果、关闭混响效果、关闭耳返并重置耳返音量。
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**调用时机**
+
+需要恢复默认音效设置时调用，例如退出直播间前。
+
+## 数据结构
+
+### AudioChangerType
+
+变声效果类型。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| NONE | 0 | 关闭特效。 |
+| CHILD | 1 | 熊孩子。 |
+| LITTLE_GIRL | 2 | 小女孩。 |
+| MAN | 3 | 大叔。 |
+| HEAVY_METAL | 4 | 重金属。 |
+| COLD | 5 | 感冒。 |
+| FOREIGNER | 6 | 外语腔。 |
+| TRAPPED_BEAST | 7 | 困兽。 |
+| FATSO | 8 | 肥宅。 |
+| STRONG_CURRENT | 9 | 强电流。 |
+| HEAVY_MACHINERY | 10 | 重机械。 |
+| ETHEREAL | 11 | 空灵。 |
+
+### AudioReverbType
+
+混响效果类型。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| NONE | 0 | 关闭特效。 |
+| KTV | 1 | KTV。 |
+| SMALL_ROOM | 2 | 小房间。 |
+| AUDITORIUM | 3 | 大会堂。 |
+| DEEP | 4 | 低沉。 |
+| LOUD | 5 | 洪亮。 |
+| METALLIC | 6 | 金属声。 |
+| MAGNETIC | 7 | 磁性。 |
+
+### AudioEffectState
+
+AudioEffectStore 对外提供的音效相关状态数据。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| audioChangerType | StateFlow<AudioChangerType> | 变声状态。 |
+| audioReverbType | StateFlow<AudioReverbType> | 混响状态。 |
+| isEarMonitorOpened | StateFlow<Boolean> | 耳返开启。 |
+| earMonitorVolume | StateFlow<Int> | 耳返音量，取值范围 0 - 100。<br>如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。 |
+
+## 使用示例
+``` kotlin
+// 获取单例实例
+val store = AudioEffectStore.shared()
+
+// 订阅状态变化
+lifecycleScope.launch {
+    store.audioEffectState.audioChangerType.collect { type ->
+        println("当前变声效果: $type")
+    }
+}
+
+lifecycleScope.launch {
+    store.audioEffectState.audioReverbType.collect { type ->
+        println("当前混响效果: $type")
+    }
+}
+
+// 设置变声效果
+store.setAudioChangerType(AudioChangerType.LITTLE_GIRL)
+
+// 设置混响效果
+store.setAudioReverbType(AudioReverbType.KTV)
+
+// 开启耳返
+store.setVoiceEarMonitorEnable(true)
+store.setVoiceEarMonitorVolume(80)
+```

package/resource/doc/livekit/core-sdk/live/android/api-reference/BarrageStore.md

@@ -0,0 +1,148 @@
+## 简介
+
+**BarrageStore** 提供了一套完整的弹幕管理 API，包括发送文本弹幕、发送自定义弹幕和添加本地提示消息。
+通过该类，可以在直播间内实现弹幕互动功能。
+
+> **重要：**
+>
+
+> 使用 **BarrageStore.create** 工厂方法创建 **BarrageStore** 实例，需要传入有效的直播间 ID。
+>
+
+> **说明：**
+>
+
+> 弹幕状态更新通过 **barrageState** 发布者传递。订阅它以接收房间内弹幕数据的实时更新。
+>
+
+## 功能特性
+- **文本弹幕**：支持发送纯文本弹幕消息。
+
+- **自定义弹幕**：支持发送自定义格式的弹幕（如带特效的弹幕）。
+
+- **本地提示**：支持添加仅本地可见的提示消息。
+
+## 可订阅数据
+
+**BarrageState** 的字段描述如下：
+| **属性名** | **类型** | **描述** |
+| --- | --- | --- |
+| messageList | StateFlow<List<Barrage>> | 当前房间的弹幕消息列表，支持实时更新并可被订阅监听。 |
+
+## API 列表
+| **函数名** | **描述** |
+| --- | --- |
+| BarrageStore.create | 创建弹幕管理实例。 |
+| sendTextMessage | 发送文本弹幕。 |
+| sendCustomMessage | 发送自定义弹幕。 |
+| appendLocalTip | 添加本地提示消息。 |
+
+### 创建实例
+
+#### BarrageStore.create
+
+创建弹幕管理实例。
+
+### 发送弹幕
+
+#### sendTextMessage
+
+发送文本类型弹幕。
+``` kotlin
+abstract fun sendTextMessage(
+        text: String?,
+        extensionInfo: Map<String, String>?,
+        completion: CompletionHandler?
+    )
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| text | String? | 必填 | 文本弹幕内容。 |
+| extensionInfo | Map<String,String>? | 必填 | 扩展信息，可包含自定义字段（如指定弹幕颜色、字体大小等）。 |
+| completion | CompletionHandler? | 必填 | 完成回调（成功/失败状态）。 |
+
+#### sendCustomMessage
+
+发送自定义类型弹幕。
+``` kotlin
+abstract fun sendCustomMessage(
+        businessID: String?,
+        data: String?,
+        completion: CompletionHandler?
+    )
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| businessID | String? | 必填 | 业务标识ID，用于区分不同业务场景的自定义弹幕。 |
+| data | String? | 必填 | 自定义数据内容，通常为JSON格式字符串，用于传递业务自定义的数据。 |
+| completion | CompletionHandler? | 必填 | 完成回调（成功/失败状态）。 |
+
+### 本地消息
+
+#### appendLocalTip
+
+添加本地提示消息（在本地添加提示或操作反馈消息，仅当前客户端可见）。
+``` kotlin
+abstract fun appendLocalTip(message: Barrage)
+```
+
+**版本信息**
+
+从 3.5 版本开始支持。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 该消息仅在本地显示，不会通过网络发送给其他用户。
+>
+
+**参数说明**
+| **参数名** | **类型** | **是否必填** | **描述** |
+| --- | --- | --- | --- |
+| message | Barrage | 必填 | 本地弹幕消息（如系统提示、操作反馈等，仅当前用户可见）。 |
+
+## 数据结构
+
+### BarrageType
+
+弹幕类型枚举，用于区分不同的弹幕消息种类。
+| **枚举值** | **值** | **说明** |
+| --- | --- | --- |
+| TEXT | 0 | 文本类型弹幕，包含纯文字内容。 |
+| CUSTOM | 1 | 自定义类型弹幕，支持业务自定义数据格式（如带特效的弹幕、互动消息等）。 |
+
+### Barrage
+
+弹幕数据模型，包含单条弹幕的完整属性信息。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| liveID | String | 弹幕所属直播间/语音聊天房的唯一标识ID。 |
+| sender | LiveUserInfo | 弹幕发送者的用户信息（如用户ID、昵称、头像等）。 |
+| sequence | Long | 弹幕消息的唯一序列ID，用于消息排序和去重。 |
+| timestampInSecond | Long | 弹幕发送时间戳（单位：秒），用于展示发送时间顺序。 |
+| messageType | BarrageType | 弹幕消息类型（文本或自定义）。 |
+| textContent | String | 文本类型弹幕的消息内容，即弹幕的文本内容。 |
+| extensionInfo | Map<String,String> | 弹幕扩展信息，可自定义字段（如显示样式、优先级等）。当 messageType 为 TEXT 时有效。 |
+| businessID | String | 自定义类型弹幕的业务标识ID，用于区分不同业务场景的自定义弹幕。 |
+| data | String | 自定义类型弹幕的具体数据内容（通常为JSON格式字符串），当 messageType 为 CUSTOM 时有效。 |
+
+### BarrageState
+
+弹幕状态，管理当前房间的弹幕数据状态。
+| **属性** | **类型** | **说明** |
+| --- | --- | --- |
+| messageList | StateFlow<List<Barrage>> | 当前房间的弹幕消息列表，支持实时更新并可被订阅监听。 |