tencent cloud

Mobile Live Video Broadcasting

ドキュメントMobile Live Video BroadcastingClient APIsFlutterMusicStore

MusicStore

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-11-02 17:31:48
AI翻訳

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
ValueListenable<String?>
Currently playing music URL. null means no music is playing.
playStatus
ValueListenable<MusicPlayStatus>
Current playback status.
playProgress
ValueListenable<int>
Current playback progress (unit: milliseconds).
totalDuration
ValueListenable<int>
Total duration of current music (unit: milliseconds). 0 means unknown.
musicVolume
ValueListenable<int>
BGM volume, range 0 - 100, default 60.

API List

Function
Description
Create music playback management instance.
Music playback event callbacks.
Music playback event callbacks.
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

MusicStore.create

Create music playback management instance.

Observing State and Events

addMusicListener

Music playback event callbacks.

removeMusicListener

Music playback event callbacks.

Playback Control

startPlay

Start playing music.
Future<CompletionHandler> startPlay(AudioMusicParam param);
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.

pausePlay

Pause music playback.
void pausePlay();
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.
void resumePlay();
Resumes playback from the paused position. The playback status will change to PLAYING.
Version
Supported since version 3.5.

stopPlay

Stop music playback.
void stopPlay();
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.
void seek(int ms);
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.
void setMusicVolume(int volume);
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.
void setPitch(double pitch);
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
ValueListenable<String?>
Currently playing music URL. null means no music is playing.
playStatus
ValueListenable<MusicPlayStatus>
Current playback status.
playProgress
ValueListenable<int>
Current playback progress (unit: milliseconds).
totalDuration
ValueListenable<int>
Total duration of current music (unit: milliseconds). 0 means unknown.
musicVolume
ValueListenable<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.
void onPlayCompleted(String playURL) {}
Parameter
Type
Description
playURL
String
The music URL that finished playing.
onPlayError: Event callback when music playback encounters an error.
void onPlayError(String playURL, int code) {}
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).
前の記事へ: AtomicLiveView次の記事へ: ScreenShareStore

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック

キーワードで検索
    Enter keywords to search documentation