MediaPlayer

adjustPlayoutVolume

Adjusts the local playback volume.

Future<void> adjustPlayoutVolume(int volume);

Timing

Can be called before or after joining a channel.

Parameters

volume

Local playback volume, ranging from 0 to 100:

0: Mute.
100: (Default) Original playback volume of the media file.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

adjustPublishSignalVolume

Adjusts the volume heard by remote users.

Future<void> adjustPublishSignalVolume(int volume);

After connecting to the Agora server, you can call this method to adjust the volume of the media file heard by remote users.

Timing

Can be called before or after joining a channel.

Parameters

volume

Signal volume, ranging from 0 to 400:

0: Mute.
100: (Default) Original volume of the media file.
400: Four times the original volume (with built-in overflow protection).

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

getAudioBufferDelay

Gets the audio buffer delay when playing a media file.

Future<int> getAudioBufferDelay();

Parameters

delayMs: Output parameter that indicates the audio buffer delay when playing a media file, in milliseconds.

Return Values

0: Success.
< 0: Failure.

getDuration

Gets the total duration of the media file.

Future<int> getDuration();

Return Values

Total duration of the media file (in milliseconds).

getMediaPlayerId

Gets the player ID.

int getMediaPlayerId();

Return Values

If the method call succeeds, returns the player ID.
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getMute

Gets whether the currently playing media file is muted.

Future<bool> getMute();

Return Values

true: The currently playing media file is muted.
false: The currently playing media file is not muted.

getPlayPosition

Gets the current playback position.

Future<int> getPlayPosition();

Return Values

If the method call succeeds, returns the current playback position (milliseconds).
< 0: The method call fails. See MediaPlayerReason.

getPlaySrc

Gets the path of the media resource being played.

Future<String> getPlaySrc();

Return Values

The path of the media resource being played.

getPlayoutVolume

Gets the current local playback volume.

Future<int> getPlayoutVolume();

Return Values

Returns the current local playback volume, ranging from 0 to 100:

0: Silent.
100: (Default) Original playback volume of the media file.

getPublishSignalVolume

Gets the volume heard by remote users.

Future<int> getPublishSignalVolume();

Return Values

≥ 0: Remote playback volume of the media file.
< 0: The method call fails. See Error Codes for details and resolution suggestions.

getState

Gets the current state of the player.

Future<MediaPlayerState> getState();

Return Values

The current state of the player. See MediaPlayerState.

getStreamCount

Gets the number of media streams in the current media file.

Future<int> getStreamCount();

Note: Call this method after open and after receiving the onPlayerSourceStateChanged callback reporting the playback state as playerStateOpenCompleted.

Return Values

If the method call succeeds, returns the number of media streams in the media file.
< 0: The method call fails. See MediaPlayerReason.

getStreamInfo

Gets media stream information by stream index.

Future<PlayerStreamInfo> getStreamInfo(int index);

Timing

You need to call this method after getStreamCount.

Parameters

index: Media stream index. The value must be less than the return value of getStreamCount.

Return Values

If the method call succeeds, returns the media stream information. See PlayerStreamInfo.
If the method call fails, returns NULL.

mute

Sets whether to mute.

Future<void> mute(bool muted);

Timing

This method can be called before or after joining a channel.

Parameters

muted

Mute option.

true: Mute.
false: (Default) Do not mute.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

open

Opens a media resource.

Future<void> open({required String url, required int startPos});

Note: This method is asynchronous.

Timing

Can be called before or after joining a channel.

Related Callbacks

After calling this method, the onPlayerSourceStateChanged callback is triggered. When the playback state is reported as playerStateOpenCompleted, you can call the play method to play the media file.

Parameters

url: Sets the path of the media file. Supports both local and online files.
startPos: Sets the start playback position in milliseconds. Default is 0.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

openWithMediaSource

Opens a media resource and sets playback options.

Future<void> openWithMediaSource(MediaSource source);

This method allows you to open different types of media resources, including custom media files, and configure playback settings.

Note: This method is asynchronous. To play the media file, call the play method after receiving the onPlayerSourceStateChanged callback reporting the state playerStateOpenCompleted.

Timing

This method can be called before or after joining a channel.

Parameters

source: Media resource. See MediaSource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

< 0: Failure. See Error Codes for details and resolution suggestions.

pause

Pauses playback.

Future<void> pause();

Timing

This method can be called before or after joining a channel.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

play

Plays the media file.

Future<void> play();

Timing

Call this method after calling open or openWithMediaSource to open the media file and receiving the onPlayerSourceStateChanged callback reporting the state as playerStateOpenCompleted.
Call this method after calling seek.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

playPreloadedSrc

Plays a preloaded media resource.

Future<void> playPreloadedSrc(String src);

After calling the preloadSrc method to preload a media resource into the playlist, you can call this method to play the preloaded media resource. After calling this method, if you receive the onPlayerSourceStateChanged callback reporting the state as playerStatePlaying, the playback is successful. If you want to change the preloaded media resource being played, you can call this method again and specify a new media resource path. If you want to replay the media resource, you need to call preloadSrc again to preload the media resource into the playlist before playing. To clear the playlist, call stop.

Note: If you call this method while playback is paused, it will take effect only after playback resumes.

Parameters

src: The URL of the media resource in the playlist. It must match the src set in the preloadSrc method; otherwise, playback will fail.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

preloadSrc

Preloads a media resource.

Future<void> preloadSrc({required String src, required int startPos});

You can call this method to preload a media resource into the playlist. To preload multiple media resources, call this method multiple times. After preloading succeeds, call playPreloadedSrc to play the media resource, or call stop to clear the playlist.

Note:

Before calling this method, make sure you have successfully called open or openWithMediaSource to open the media resource.
The SDK does not support preloading duplicate media resources into the playlist, but supports preloading the currently playing media resource again into the playlist.

Parameters

src: Network path of the media resource.
startPos: Start position (in milliseconds) when playback begins after preloading into the playlist. Set to 0 when preloading a live stream.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

registerAudioFrameObserver

Registers an audio frame observer.

void registerAudioFrameObserver(
      {required AudioPcmFrameSink observer,
      RawAudioFrameOpModeType mode =
          RawAudioFrameOpModeType.rawAudioFrameOpModeReadOnly});

Parameters

observer: Audio frame observer that monitors the reception of each audio frame. See AudioPcmFrameSink.
mode: Usage mode of the audio frame. See RawAudioFrameOpModeType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

registerPlayerSourceObserver

Registers a playback observer.

void registerPlayerSourceObserver(MediaPlayerSourceObserver observer);

Timing

Can be called before or after joining a channel.

Parameters

observer: Playback observer that reports events during playback. See MediaPlayerSourceObserver.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

registerVideoFrameObserver

Registers a video frame observer.

void registerVideoFrameObserver(MediaPlayerVideoFrameObserver observer);

You need to implement a MediaPlayerVideoFrameObserver class in this method and register its callbacks as needed based on your scenario. Once the video frame observer is successfully registered, the SDK triggers the registered callbacks upon capturing each video frame.

Parameters

observer: Video frame observer that monitors the reception of each video frame. See MediaPlayerVideoFrameObserver.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

resume

Resumes playback after pausing.

Future<void> resume();

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

seek

Seeks to the specified playback position in the media file.

Future<void> seek(int newPos);

If you call seek after playback has completed (i.e., you received the onPlayerSourceStateChanged callback reporting the playback state as playerStatePlaybackCompleted or playerStatePlaybackAllLoopsCompleted), the SDK will automatically start playback from the specified position upon success. You will receive the onPlayerSourceStateChanged callback reporting the state as playerStatePlaying.
If you call seek while playback is paused, the SDK will seek to the specified position upon success. To start playback, call resume or play.

Timing

This method can be called before or after joining a channel.

Related Callbacks

After successfully calling this method, you will receive the onPlayerEvent callback reporting events such as seek start, seek success, or seek failure.

Parameters

newPos: The specified position (in milliseconds).

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

selectAudioTrack

Specifies the audio track for the current audio file.

Future<void> selectAudioTrack(int index);

After obtaining the audio track index of the audio file, you can call this method to select any track for playback. If different tracks in a multi-track file contain songs in different languages, you can call this method to set the playback language.

Note: You need to call this method after calling getStreamInfo to get the audio stream index.

Parameters

index: Index of the audio track.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

selectMultiAudioTrack

Selects the audio tracks for local playback and remote publishing.

Future<void> selectMultiAudioTrack(
    {required int playoutTrackIndex, required int publishTrackIndex});

You can call this method to separately set the audio tracks for local playback and for publishing to the remote end. Before calling this method, you must open the media file using openWithMediaSource and set enableMultiAudioTrack to true via MediaSource.

Scenario

In karaoke scenarios, the host can choose to play one track locally (e.g., instrumental) and send another track (e.g., vocals) to the remote audience to enhance their experience.

Parameters

playoutTrackIndex: The index of the audio track used for local playback. You can get the index via getStreamInfo.
publishTrackIndex: The index of the audio track used for publishing to the remote end. You can get the index via getStreamInfo.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly.

< 0: Failure.

setAudioDualMonoMode

Sets the channel mode of the current audio file.

Future<void> setAudioDualMonoMode(AudioDualMonoMode mode);

In stereo audio files, the left and right channels can store different audio data. Depending on your needs, you can set the channel mode to original, left channel, right channel, or mixed mode. For example, in a KTV scenario, the left channel of an audio file stores the accompaniment, and the right channel stores the original vocal. If you only want to hear the accompaniment, call this method to set the channel mode to left channel; if you want to hear both the accompaniment and the original vocal, set the channel mode to mixed mode.

Note:

You need to call this method after calling open.
This method applies to stereo audio files only.

Parameters

mode: Channel mode. See AudioDualMonoMode.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setAudioPitch

Adjusts the pitch of the currently playing media resource.

Future<void> setAudioPitch(int pitch);

Note: You need to call this method after calling open.

Parameters

pitch: Adjusts the pitch of the locally played music file in semitone steps. The default value is 0, meaning no pitch adjustment. The valid range is [-12, 12], where each adjacent value differs by a semitone. The greater the absolute value, the more the pitch is increased or decreased.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setLoopCount

Sets loop playback.

Future<void> setLoopCount(int loopCount);

If you want to enable loop playback, call this method and set the number of loops. When loop playback ends, the SDK triggers the onPlayerSourceStateChanged callback to report the playback state as playerStatePlaybackAllLoopsCompleted.

Parameters

loopCount

Number of playback loops.

≥0: Number of loops. For example, 0 means no loop, play once in total; 1 means loop once, play twice in total.
-1: Infinite loop.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setPlaybackSpeed

Sets the playback speed of the current audio file.

Future<void> setPlaybackSpeed(int speed);

You need to call this method after open.

Parameters

speed

Playback speed. Recommended range is [30, 400], where:

30: 0.3x speed.
100: original speed.
400: 4x speed.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setPlayerOptionInInt

Sets media player options.

Future<void> setPlayerOptionInInt({required String key, required int value});

The media player supports setting options using key and value. The difference between this method and setPlayerOptionInString is that this method uses an Int type for value, while setPlayerOptionInString uses a String type. The two cannot be mixed.

Scenario

Scenarios that require technical preview or special customization features. In general, you do not need to call this method; use the default media player option settings.

Timing

This method must be called before open or openWithMediaSource.

Parameters

key: Key value.
value: Value.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setPlayerOptionInString

Sets media player options.

Future<void> setPlayerOptionInString(
    {required String key, required String value});

The media player supports setting options using key and value. The difference between this method and setPlayerOptionInInt is that this method uses a String type for value, while setPlayerOptionInInt uses an Int type. The two cannot be mixed.

Scenario

Scenarios where technical preview or customized features are needed. In general, you don't need to call this method; the default media player option settings are sufficient.

Timing

This method must be called before open or openWithMediaSource.

Parameters

key: Key value.
value: Value.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setRenderMode

Sets the rendering mode of the player view.

Future<void> setRenderMode(RenderModeType renderMode);

Parameters

renderMode: Rendering mode of the player view. See RenderModeType.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setSpatialAudioParams

Enables or disables spatial audio for the media player.

Future<void> setSpatialAudioParams(SpatialAudioParams params);

After successfully setting the spatial audio parameters of the media player, the SDK enables spatial audio for the media player, allowing the local user to perceive spatial sound from media resources. To disable spatial audio for the media player, you need to set the params parameter to null.

Parameters

params: Spatial audio parameters for the media player. See SpatialAudioParams.

Return Values

When the method call succeeds, there is no return value; when it fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

setView

Sets the player rendering view.

Future<void> setView(int view);

Note: In Flutter, you do not need to call this method manually. Use AgoraVideoView to render local and remote views.

Timing

This method can be called before or after joining a channel.

Parameters

view: Rendering view. On Windows, this is a window handle (HWND).

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

stop

Stops playback.

Future<void> stop();

After calling this method to stop playback, you need to call open or openWithMediaSource to open the media resource again if you want to replay.

Timing

This method must be called after play.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

switchSrc

Switches the media resource.

Future<void> switchSrc({required String src, bool syncPts = true});

You can call this method to switch the bitrate of the media resource being played based on the current network conditions. For example:

When the network is poor, switch to a lower bitrate media resource.
When the network is good, switch to a higher bitrate media resource.

After calling this method, if you receive the onPlayerEvent callback reporting the playerEventSwitchComplete event, the media resource has been switched successfully. If the switch fails, the SDK retries 3 times. If it still fails, you receive the onPlayerEvent callback reporting the playerEventSwitchError event, indicating an error occurred during the switch.

Note:

Make sure to call this method after open.
To ensure normal playback, note the following when calling this method:
- Do not call this method while playback is paused.
- Do not call seek during bitrate switching.
- Ensure the playback position before switching does not exceed the total duration of the media resource to be switched.

Parameters

src

Network path of the media resource.

syncPts

Whether to synchronize the start playback position before and after switching:

true: Synchronize.
false: (Default) Do not synchronize.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unloadSrc

Releases the preloaded media resource.

Future<void> unloadSrc(String src);

Parameters

src: Network path of the media resource.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unregisterAudioFrameObserver

Unregisters the audio frame observer.

void unregisterAudioFrameObserver(AudioPcmFrameSink observer);

Parameters

observer: Audio frame observer. See AudioPcmFrameSink.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unregisterPlayerSourceObserver

Unregisters the playback observer.

void unregisterPlayerSourceObserver(MediaPlayerSourceObserver observer);

Parameters

observer: Playback observer that reports events during playback. See MediaPlayerSourceObserver.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.

unregisterVideoFrameObserver

Unregisters the video frame observer.

void unregisterVideoFrameObserver(MediaPlayerVideoFrameObserver observer);

Parameters

observer: Video frame observer that monitors the reception of each video frame. See MediaPlayerVideoFrameObserver.

Return Values

When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.