tencent cloud

Mobile Live Video Broadcasting

DocumentaçãoMobile Live Video BroadcastingClient APIsiOSMusicStore

MusicStore

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-11-02 17:31:51
Traduzido por IA

Introduction

MusicStore provides a complete set of music playback management APIs, including starting/pausing/resuming/stopping playback and volume control. Through this class, BGM playback functionality can be implemented in live rooms.
Notice:
Use the create(liveID:)factory method to create a MusicStore instance, passing a valid live room ID.
Note:
Playback state updates are delivered through the state publisher. Subscribe to it to receive real-time updates of playback data in the room.

Features

Playback Control: Support starting, pausing, resuming, stopping, and seeking BGM playback.
Volume Control: Adjustable BGM volume (0-100).
Pitch Adjustment: Support pitch shifting (-12 ~ 12).
State Management: Real-time playback state updates via reactive state publisher.
Event Listening: Listen to playback completion and error events.

Subscribable Data

MusicState fields are described below:
Property
Type
Description
playURL
String?
Currently playing music URL. nil/null means no music is playing.
playStatus
Current playback status.
playProgress
Int
Current playback progress (unit: milliseconds).
totalDuration
Int
Total duration of current music (unit: milliseconds). 0 means unknown.
musicVolume
Int
BGM volume, range 0 - 100, default 60.

API List

Function
Description
create
Create music playback management instance.
Music playback event publisher.
startPlay
Start playing music.
pausePlay
Pause playback.
Resume playback.
stopPlay
Stop playback.
seek
Seek to specified position.
Set BGM volume.
setPitch
Set pitch adjustment.

Creating Instance

create

Create music playback management instance.
public static func create(liveID: String) -> MusicStore {
    let store: MusicStoreImpl = StoreFactory.shared.getStore(roomID: liveID)
    return store
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
liveID
String
Live room ID.

Observing State and Events

musicEventPublisher

Music playback event publisher.

Playback Control

startPlay

Start playing music.
public func startPlay(param: AudioMusicParam, completion: CompletionClosure?) {
    fatalError("\\(#function) must be overridden by subclass")
}
Starts playing the music described by param. If a network URL is provided in AudioMusicParam/path, the SDK will handle downloading internally. The playback status will transition to LOADING first, then to PLAYING when playback actually starts. Error Codes: On failure, the completion callback will return TRTC SDK error codes. See the error code table in onPlayError for details.
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
param
Music playback parameters. See AudioMusicParam.
completion
Completion callback (success/failure status). Returns TRTC error code on failure.

pausePlay

Pause music playback.
public func pausePlay() {
    fatalError("\\(#function) must be overridden by subclass")
}
Pauses the currently playing music. The playback status will change to PAUSED. Call resumePlay to resume playback from the paused position.
Version
Supported since version 3.5.

resumePlay

Resume music playback.
public func resumePlay() {
    fatalError("\\(#function) must be overridden by subclass")
}
Resumes playback from the paused position. The playback status will change to PLAYING.
Version
Supported since version 3.5.

stopPlay

Stop music playback.
public func stopPlay() {
    fatalError("\\(#function) must be overridden by subclass")
}
Stops the current music playback completely. The playback status will change to IDLE. Unlike pause, stop will reset the playback position.
Version
Supported since version 3.5.

seek

Seek to specified playback position.
public func seek(to ms: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
Jumps to the specified time position in the currently playing music.
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
ms
Int
Target playback position in milliseconds.

Playback Parameters

setMusicVolume

Set BGM volume.
public func setMusicVolume(_ volume: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
Sets both the local playback volume and the remote publishing volume simultaneously.
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
volume
Int
BGM volume, range 0 - 100.

setPitch

Set pitch adjustment.
public func setPitch(_ pitch: Double) {
    fatalError("\\(#function) must be overridden by subclass")
}
Adjusts the pitch of the currently playing music.
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
pitch
Double
Pitch adjustment value, range -12 ~ 12. Positive values raise the pitch, negative values lower it.

Data Structures

MusicPlayStatus

Music playback status.
Enum Value
Value
Description
idle
0
Idle, not playing.
playing
1
Playing.
paused
2
Paused.
loading
3
Loading (e.g. buffering network resource).

MusicState

Music playback state, managing the playback data state of the current room.
Property
Type
Description
playURL
String?
Currently playing music URL. nil/null means no music is playing.
playStatus
Current playback status.
playProgress
Int
Current playback progress (unit: milliseconds).
totalDuration
Int
Total duration of current music (unit: milliseconds). 0 means unknown.
musicVolume
Int
BGM volume, range 0 - 100, default 60.

AudioMusicParam

Music playback parameters.
Property
Type
Description
id
Int
Music ID. Since the SDK allows playing multiple tracks at the same time, this ID is used to mark a track for start/stop/volume control, etc. When 0, an ID will be generated internally based on path.
path
String?
Full path or URL of the audio file. Supported formats: MP3, AAC, M4A, WAV.
loopCount
Int
Number of times to loop the track. 0 means play once without looping.

MusicListener

Music playback event listener, used to receive playback dynamics in live rooms/voice chat rooms.
Methods
onPlayCompleted: Event callback when music playback completes normally.
case playCompleted(playURL: String)
Parameter
Type
Description
playURL
String
The music URL that finished playing.
onPlayError: Event callback when music playback encounters an error.
case playError(playURL: String, code: Int)
Parameter
Type
Description
playURL
String
The music URL that encountered error.
code
Int
Error code, passed through from TRTC SDK. Common error codes are as follows:
0 (Success): Operation succeeded
-4001 (ERR_BGM_OPEN_FAILED): Failed to open file, invalid audio data or FFMPEG protocol not found
-4002 (ERR_BGM_DECODE_FAILED): Audio file decoding failed, file may be corrupted or encoding format unrecognized
-4003 (ERR_BGM_OVER_LIMIT): Number of preloaded music exceeded the limit
-4004 (ERR_BGM_INVALID_OPERATION): Invalid operation, e.g., calling preload during playback
-4005 (ERR_BGM_INVALID_PATH): Invalid path, please check if the file path points to a valid music file
-4006 (ERR_BGM_INVALID_URL): Invalid URL, please ensure the URL is accessible (iOS/Mac requires HTTPS)
-4007 (ERR_BGM_NO_AUDIO_STREAM): No audio stream, please confirm the file is a valid audio file and not corrupted
-4008 (ERR_BGM_FORMAT_NOT_SUPPORTED): Format not supported.
Mobile supports: mp3, aac, m4a, wav, ogg, mp4, mkv.
Desktop supports: mp3, aac, m4a, wav, mp4, mkv.
-4009 (ERR_CONCURRENT_BGM_OVER_LIMIT): Number of concurrent BGM playback exceeded the limit (max 10).
Anterior: AtomicLiveViewPróximo: AITranscriberStore

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation