MusicStore
简介
MusicStore 提供了一套完整的音乐播放管理 API，包括播放/暂停/恢复/停止和音量控制。 通过该类，可以在直播间内实现 BGM 播放功能。重要：
使用 create(liveID:)工厂方法创建
MusicStore 实例，需要传入有效的直播间 ID。说明：
播放状态更新通过 state 发布者传递。订阅它以接收房间内播放数据的实时更新。
功能特性
播放控制：支持 BGM 的播放、暂停、恢复、停止和跳转。
音量控制：可调节 BGM 音量（0-100）。
升降调：支持升降调调节（-12 ~ 12）。
状态管理：通过响应式状态发布者实时更新播放状态。
事件监听：监听播放完成和播放错误事件。
可订阅数据
MusicState 的字段描述如下：
属性名 | 类型 | 描述 |
playURL | ValueListenable<String?> | 当前播放的音乐 URL。null 表示没有音乐在播放。 |
playStatus | 当前播放状态。 | |
playProgress | ValueListenable<int> | 当前播放进度（单位：毫秒）。 |
totalDuration | ValueListenable<int> | 当前音乐总时长（单位：毫秒）。0 表示未知。 |
musicVolume | ValueListenable<int> | BGM 音量，取值范围 0 - 100，默认 60。 |
API 列表
函数名 | 描述 |
创建音乐播放管理实例。 | |
音乐播放事件回调。 | |
音乐播放事件回调。 | |
开始播放音乐。 | |
暂停播放。 | |
恢复播放。 | |
停止播放。 | |
跳转到指定位置。 | |
设置 BGM 音量。 | |
设置升降调。 |
创建实例
MusicStore.create
创建音乐播放管理实例。
观察状态和事件
addMusicListener
音乐播放事件回调。
removeMusicListener
音乐播放事件回调。
播放控制
startPlay
开始播放音乐。
Future<CompletionHandler> startPlay(AudioMusicParam param);
播放 param 描述的音乐。若在 AudioMusicParam.path 中提供网络 URL，SDK 会在内部处理下载。
播放状态会先转为 LOADING，在实际开始播放时转为 PLAYING。
错误码说明：失败时 completion 回调会返回 TRTC SDK 的错误码，详见
onPlayError 中的错误码表。版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
param | 音乐播放参数。参见 AudioMusicParam。 |
pausePlay
暂停音乐播放。
void pausePlay();
暂停当前正在播放的音乐。播放状态会变为 PAUSED。
调用 resumePlay 可以从暂停位置恢复播放。
版本信息
从3.5版本开始支持。
resumePlay
恢复音乐播放。
void resumePlay();
从暂停位置恢复播放。播放状态会变为 PLAYING。
版本信息
从3.5版本开始支持。
stopPlay
停止音乐播放。
void stopPlay();
完全停止当前音乐播放。播放状态会变为 IDLE。
与暂停不同，停止会重置播放位置。
版本信息
从3.5版本开始支持。
seek
跳转到指定播放位置。
void seek(int ms);
跳转到当前播放音乐的指定时间位置。
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
ms | Int | 目标播放位置，单位毫秒。 |
播放参数
setMusicVolume
设置 BGM 音量。
void setMusicVolume(int volume);
同时设置本地播放音量和远端推流音量。
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
volume | Int | BGM 音量，取值范围 0 - 100。 |
setPitch
设置升降调。
void setPitch(double pitch);
调节当前播放音乐的音调。
版本信息
从3.5版本开始支持。
参数说明
参数名 | 类型 | 描述 |
pitch | Double | 升降调值，取值范围 -12 ~ 12。正值升调，负值降调。 |
数据结构
MusicPlayStatus
音乐播放状态。
枚举值 | 值 | 说明 |
idle | 0 | 空闲，未播放。 |
playing | 1 | 播放中。 |
paused | 2 | 已暂停。 |
loading | 3 | 加载中（如缓冲网络资源）。 |
MusicState
音乐播放状态，管理当前房间的播放数据状态。
属性 | 类型 | 说明 |
playURL | ValueListenable<String?> | 当前播放的音乐 URL。null 表示没有音乐在播放。 |
playStatus | 当前播放状态。 | |
playProgress | ValueListenable<int> | 当前播放进度（单位：毫秒）。 |
totalDuration | ValueListenable<int> | 当前音乐总时长（单位：毫秒）。0 表示未知。 |
musicVolume | ValueListenable<int> | BGM 音量，取值范围 0 - 100，默认 60。 |
AudioMusicParam
音乐播放参数。
属性 | 类型 | 说明 |
id | int | 音乐 ID。由于 SDK 允许同时播放多个音轨，此 ID 用于标记某个音轨以进行开始/停止/音量控制等。
为 0 时，SDK 会基于 path 在内部生成 ID。 |
path | String? | 音频文件的完整路径或 URL。支持格式：MP3、AAC、M4A、WAV。 |
loopCount | int | 音轨循环播放的次数。0 表示只播放一次，不循环。 |
MusicListener
音乐播放事件监听器，用于接收直播间/语音聊天房内的播放动态。
方法
onPlayCompleted: 音乐正常播放完成时的事件回调。
void onPlayCompleted(String playURL) {}
参数名 | 类型 | 说明 |
playURL | String | 播放完成的音乐 URL。 |
onPlayError: 音乐播放出错时的事件回调。
void onPlayError(String playURL, int code) {}
参数名 | 类型 | 说明 |
playURL | String | 播放出错的音乐 URL。 |
code | Int | 错误码，透传自 TRTC SDK。常见错误码如下： 0（成功）：操作成功。 4001（ERR_BGM_OPEN_FAILED）：打开文件失败，音频数据无效或 FFMPEG 协议未找到。 4002（ERR_BGM_DECODE_FAILED）：音频文件解码失败，文件可能损坏或编码格式无法识别。 4003（ERR_BGM_OVER_LIMIT）：预加载音乐数量超过限定值。 4004（ERR_BGM_INVALID_OPERATION）：无效操作，如在播放中调用预加载。 4005（ERR_BGM_INVALID_PATH）：非法路径，请检查文件路径是否指向合法的音乐文件。 4006（ERR_BGM_INVALID_URL）：非法 URL，请确保 URL 可访问（iOS/Mac 需使用 HTTPS）。 4007（ERR_BGM_NO_AUDIO_STREAM）：无音频流，请确认文件是合法的音频文件且未损坏。 4008（ERR_BGM_FORMAT_NOT_SUPPORTED）：格式不支持。 移动端支持：mp3, aac, m4a, wav, ogg, mp4, mkv； 桌面端支持：mp3, aac, m4a, wav, mp4, mkv。 4009（ERR_CONCURRENT_BGM_OVER_LIMIT）：同时播放 BGM 数量超过限定值（最大 10 个）。 |
