MusicStore 提供了一套完整的音乐播放管理 API，包括播放/暂停/恢复/停止和音量控制。 通过该类，可以在直播间内实现 BGM 播放功能。MusicStore 实例，需要传入有效的直播间 ID。属性名 | 类型 | 描述 |
playURL | ValueListenable<String?> | 当前播放的音乐 URL。null 表示没有音乐在播放。 |
playStatus | 当前播放状态。 | |
playProgress | ValueListenable<int> | 当前播放进度（单位：毫秒）。 |
totalDuration | ValueListenable<int> | 当前音乐总时长（单位：毫秒）。0 表示未知。 |
musicVolume | ValueListenable<int> | BGM 音量，取值范围 0 - 100，默认 60。 |
函数名 | 描述 |
创建音乐播放管理实例。 | |
音乐播放事件回调。 | |
音乐播放事件回调。 | |
开始播放音乐。 | |
暂停播放。 | |
恢复播放。 | |
停止播放。 | |
跳转到指定位置。 | |
设置 BGM 音量。 | |
设置升降调。 |
Future<CompletionHandler> startPlay(AudioMusicParam param);
onPlayError 中的错误码表。参数名 | 类型 | 描述 |
param |
void pausePlay();
void resumePlay();
void stopPlay();
void seek(int ms);
参数名 | 类型 | 描述 |
ms | Int | 目标播放位置，单位毫秒。 |
void setMusicVolume(int volume);
参数名 | 类型 | 描述 |
volume | Int | BGM 音量，取值范围 0 - 100。 |
void setPitch(double pitch);
参数名 | 类型 | 描述 |
pitch | Double | 升降调值，取值范围 -12 ~ 12。正值升调，负值降调。 |
枚举值 | 值 | 说明 |
idle | 0 | 空闲，未播放。 |
playing | 1 | 播放中。 |
paused | 2 | 已暂停。 |
loading | 3 | 加载中（如缓冲网络资源）。 |
属性 | 类型 | 说明 |
playURL | ValueListenable<String?> | 当前播放的音乐 URL。null 表示没有音乐在播放。 |
playStatus | 当前播放状态。 | |
playProgress | ValueListenable<int> | 当前播放进度（单位：毫秒）。 |
totalDuration | ValueListenable<int> | 当前音乐总时长（单位：毫秒）。0 表示未知。 |
musicVolume | ValueListenable<int> | BGM 音量，取值范围 0 - 100，默认 60。 |
属性 | 类型 | 说明 |
id | int | 音乐 ID。由于 SDK 允许同时播放多个音轨，此 ID 用于标记某个音轨以进行开始/停止/音量控制等。
为 0 时，SDK 会基于 path 在内部生成 ID。 |
path | String? | 音频文件的完整路径或 URL。支持格式：MP3、AAC、M4A、WAV。 |
loopCount | int | 音轨循环播放的次数。0 表示只播放一次，不循环。 |
void onPlayCompleted(String playURL) {}
参数名 | 类型 | 说明 |
playURL | String | 播放完成的音乐 URL。 |
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 个）。 |
文档反馈