帮你快速理解、总结文档立即下载
文档中心>实时音视频>直播与语聊 SDK>客户端 API>iOS>MusicStore

MusicStore

最近更新时间：2026-10-23 17:00:00
我的收藏

本页目录：

简介

MusicStore 提供了一套完整的音乐播放管理 API，包括播放/暂停/恢复/停止和音量控制。 通过该类，可以在直播间内实现 BGM 播放功能。
重要：
使用 create(liveID:)工厂方法创建 MusicStore 实例，需要传入有效的直播间 ID。
说明：
播放状态更新通过 state 发布者传递。订阅它以接收房间内播放数据的实时更新。

功能特性

播放控制：支持 BGM 的播放、暂停、恢复、停止和跳转。
音量控制：可调节 BGM 音量（0-100）。
升降调：支持升降调调节（-12 ~ 12）。
状态管理：通过响应式状态发布者实时更新播放状态。
事件监听：监听播放完成和播放错误事件。

可订阅数据

MusicState 的字段描述如下：
属性名
类型
描述
playURL
String?
当前播放的音乐 URL。nil/null 表示没有音乐在播放。
playStatus
当前播放状态。
playProgress
Int
当前播放进度（单位：毫秒）。
totalDuration
Int
当前音乐总时长（单位：毫秒）。0 表示未知。
musicVolume
Int
BGM 音量，取值范围 0 - 100，默认 60。

API 列表

函数名
描述
create
创建音乐播放管理实例。
音乐播放事件发布者。
startPlay
开始播放音乐。
pausePlay
暂停播放。
恢复播放。
stopPlay
停止播放。
seek
跳转到指定位置。
设置 BGM 音量。
setPitch
设置升降调。

创建实例

create

创建音乐播放管理实例。
public static func create(liveID: String) -> MusicStore {
    let store: MusicStoreImpl = StoreFactory.shared.getStore(roomID: liveID)
    return store
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
liveID
String
直播间 ID。

观察状态和事件

musicEventPublisher

音乐播放事件发布者。

播放控制

startPlay

开始播放音乐。
public func startPlay(param: AudioMusicParam, completion: CompletionClosure?) {
    fatalError("\\(#function) must be overridden by subclass")
}
播放 param 描述的音乐。若在 AudioMusicParam/path 中提供网络 URL，SDK 会在内部处理下载。 播放状态会先转为 LOADING，在实际开始播放时转为 PLAYING。 错误码说明：失败时 completion 回调会返回 TRTC SDK 的错误码，详见 onPlayError 中的错误码表。
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
param
音乐播放参数。参见 AudioMusicParam。
completion
完成回调（成功/失败状态）。失败时会返回 TRTC 错误码。

pausePlay

暂停音乐播放。
public func pausePlay() {
    fatalError("\\(#function) must be overridden by subclass")
}
暂停当前正在播放的音乐。播放状态会变为 PAUSED。 调用 resumePlay 可以从暂停位置恢复播放。
版本信息
从3.5版本开始支持。

resumePlay

恢复音乐播放。
public func resumePlay() {
    fatalError("\\(#function) must be overridden by subclass")
}
从暂停位置恢复播放。播放状态会变为 PLAYING。
版本信息
从3.5版本开始支持。

stopPlay

停止音乐播放。
public func stopPlay() {
    fatalError("\\(#function) must be overridden by subclass")
}
完全停止当前音乐播放。播放状态会变为 IDLE。 与暂停不同，停止会重置播放位置。
版本信息
从3.5版本开始支持。

seek

跳转到指定播放位置。
public func seek(to ms: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
跳转到当前播放音乐的指定时间位置。
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
ms
Int
目标播放位置，单位毫秒。

播放参数

setMusicVolume

设置 BGM 音量。
public func setMusicVolume(_ volume: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
同时设置本地播放音量和远端推流音量。
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
volume
Int
BGM 音量，取值范围 0 - 100。

setPitch

设置升降调。
public func setPitch(_ pitch: Double) {
    fatalError("\\(#function) must be overridden by subclass")
}
调节当前播放音乐的音调。
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
pitch
Double
升降调值，取值范围 -12 ~ 12。正值升调，负值降调。

数据结构

MusicPlayStatus

音乐播放状态。
枚举值
值
说明
idle
0
空闲，未播放。
playing
1
播放中。
paused
2
已暂停。
loading
3
加载中（如缓冲网络资源）。

MusicState

音乐播放状态，管理当前房间的播放数据状态。
属性
类型
说明
playURL
String?
当前播放的音乐 URL。nil/null 表示没有音乐在播放。
playStatus
当前播放状态。
playProgress
Int
当前播放进度（单位：毫秒）。
totalDuration
Int
当前音乐总时长（单位：毫秒）。0 表示未知。
musicVolume
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: 音乐正常播放完成时的事件回调。
case playCompleted(playURL: String)
参数名
类型
说明
playURL
String
播放完成的音乐 URL。
onPlayError: 音乐播放出错时的事件回调。
case playError(playURL: String, code: Int)
参数名
类型
说明
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 个）。
中国站