MediaPlayer

adjustPlayoutVolume

Adjusts the local playback volume.

Future<void> adjustPlayoutVolume(int volume);

Parameters

volume

The local playback volume, which ranges from 0 to 100:

0: Mute.
100: (Default) The original volume.

Exceptions

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

adjustPublishSignalVolume

Adjusts the volume of the media file for publishing.

Future<void> adjustPublishSignalVolume(int volume);

Details

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

Parameters

volume

The volume, which ranges from 0 to 400:

0: Mute.
100: (Default) The original volume.
400: Four times the original volume (amplifying the audio signals by four times).

Exceptions

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

getDuration

Gets the duration of the media resource.

Future<int> getDuration();

Returns

The total duration (ms) of the media file.

getMediaPlayerId

Gets the ID of the media player.

int getMediaPlayerId();

Returns

Success. The ID of the media player.
< 0: Failure.

getMute

Reports whether the media resource is muted.

Future<bool> getMute();

Returns

true: Reports whether the media resource is muted.
false: Reports whether the media resource is muted.

getPlayoutVolume

Gets the local playback volume.

Future<int> getPlayoutVolume();

Returns

The local playback volume, which ranges from 0 to 100.

0: Mute.
100: (Default) The original volume.

getPlayPosition

Gets current local playback progress.

Future<int> getPlayPosition();

Returns

Returns the current playback progress (ms) if the call succeeds.
< 0: Failure. See MediaPlayerReason.

getPublishSignalVolume

Gets the volume of the media file for publishing.

Future<int> getPublishSignalVolume();

Returns

≥ 0: The remote playback volume.
< 0: Failure.

getState

Gets current playback state.

Future<MediaPlayerState> getState();

Returns

The current playback state. See MediaPlayerState.

getStreamCount

Gets the number of the media streams in the media resource.

Future<int> getStreamCount();

Details

Attention: Call this method after you call open and receive the onPlayerSourceStateChanged callback reporting the state playerStateOpenCompleted.

Returns

The number of the media streams in the media resource if the method call succeeds.
< 0: Failure. See MediaPlayerReason.

getStreamInfo

Gets the detailed information of the media stream.

Future<PlayerStreamInfo> getStreamInfo(int index);

Details

Attention: Call this method after calling getStreamCount.

Parameters

index: The index of the media stream. This parameter must be less than the return value of getStreamCount.

Returns

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

mute

Sets whether to mute the media file.

Future<void> mute(bool muted);

Parameters

muted

Whether to mute the media file:

true: Mute the media file.
false: (Default) Unmute the media file.

Exceptions

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

open

Opens the media resource.

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

Details

Attention:

This method is called asynchronously.

If you need to play a media file, make sure you receive the onPlayerSourceStateChanged callback reporting playerStateOpenCompleted before calling the play method to play the file.

Parameters

url: The path of the media file. Both local path and online path are supported.
startPos: The starting position (ms) for playback. Default value is 0.

Exceptions

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

openWithMediaSource

Opens a media file and configures the playback scenarios.

Future<void> openWithMediaSource(MediaSource source);

Details

This method supports opening media files of different sources, including a custom media source, and allows you to configure the playback scenarios.

Parameters

source: Media resources. See MediaSource.

Exceptions

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

< 0: Failure.

pause

Pauses the playback.

Future<void> pause();

Exceptions

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

play

Plays the media file.

Future<void> play();

Details

After calling open or seek, you can call this method to play the media file.

Exceptions

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

playPreloadedSrc

Plays preloaded media resources.

Future<void> playPreloadedSrc(String src);

Details

After calling the preloadSrc method to preload the 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 which reports the playerStatePlaying state, the playback is successful.

If you want to change the preloaded media resource to be played, you can call this method again and specify the URL of the new media resource that you want to preload. If you want to replay the media resource, you need to call preloadSrc to preload the media resource to the playlist again before playing. If you want to clear the playlist, call the stop method.

Note:

If you call this method when playback is paused, this method does not take effect until playback is resumed.

Parameters

src: The URL of the media resource in the playlist must be consistent with the src set by the preloadSrc method; otherwise, the media resource cannot be played.

Exceptions

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

preloadSrc

Preloads a media resource.

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

Details

You can call this method to preload a media resource into the playlist. If you need to preload multiple media resources, you can call this method multiple times.

If the preload is successful and you want to play the media resource, call playPreloadedSrc; if you want to clear the playlist, call stop.

Note:

Agora does not support preloading duplicate media resources to the playlist. However, you can preload the media resources that are being played to the playlist again.

Parameters

src: The URL of the media resource.
startPos: The starting position (ms) for playing after the media resource is preloaded to the playlist. When preloading a live stream, set this parameter to 0.

Exceptions

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

registerPlayerSourceObserver

Registers a media player observer.

void registerPlayerSourceObserver(MediaPlayerSourceObserver observer);

Parameters

observer: The player observer, listening for events during the playback. See MediaPlayerSourceObserver.

Exceptions

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

registerVideoFrameObserver

Registers a video frame observer object.

void registerVideoFrameObserver(MediaPlayerVideoFrameObserver observer);

Details

You need to implement the MediaPlayerVideoFrameObserver class in this method and register callbacks according to your scenarios. After you successfully register the video frame observer, the SDK triggers the registered callbacks each time a video frame is received.

Parameters

observer: The video observer, reporting the reception of each video frame. See MediaPlayerVideoFrameObserver.

Exceptions

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

resume

Resumes playing the media file.

Future<void> resume();

Exceptions

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

seek

Seeks to a new playback position.

Future<void> seek(int newPos);

Details

After successfully calling this method, you will receive the onPlayerEvent callback, reporting the result of the seek operation to the new playback position.

To play the media file from a specific position, do the following:

Call this method to seek to the position you want to begin playback.
Call the play method to play the media file.

Parameters

newPos: The new playback position (ms).

Exceptions

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

selectAudioTrack

Selects the audio track used during playback.

Future<void> selectAudioTrack(int index);

Details

After getting the track index of the audio file, you can call this method to specify any track to play. For example, if different tracks of a multi-track file store songs in different languages, you can call this method to set the playback language.

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

Parameters

index: The index of the audio track.

Exceptions

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

setAudioPitch

Sets the pitch of the current media resource.

Future<void> setAudioPitch(int pitch);

Details

Note: Call this method after calling open.

Parameters

pitch: Sets the pitch of the local music file by the chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.

Exceptions

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

setAudioDualMonoMode

Sets the channel mode of the current audio file.

Future<void> setAudioDualMonoMode(AudioDualMonoMode mode);

Details

In a stereo music file, the left and right channels can store different audio data. According to your needs, you can set the channel mode to original mode, left channel mode, right channel mode, or mixed channel mode. For example, in the KTV scenario, the left channel of the music file stores the musical accompaniment, and the right channel stores the singing voice. If you only need to listen to the accompaniment, call this method to set the channel mode of the music file to left channel mode; if you need to listen to the accompaniment and the singing voice at the same time, call this method to set the channel mode to mixed channel mode.

Attention:

Call this method after calling open.
This method only applies to stereo audio files.

Parameters

mode: The channel mode. See AudioDualMonoMode.

Exceptions

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

setLoopCount

Sets the loop playback.

Future<void> setLoopCount(int loopCount);

Details

If you want to loop, call this method and set the number of the loops.

When the loop finishes, the SDK triggers onPlayerSourceStateChanged and reports the playback state as playerStatePlaybackAllLoopsCompleted.

Parameters

loopCount: The number of times the audio effect loops:

Exceptions

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

setPlaybackSpeed

Sets the channel mode of the current audio file.

Future<void> setPlaybackSpeed(int speed);

Details

Call this method after calling open.

Parameters

speed

The playback speed. Agora recommends that you limit this value to a range between 50 and 400, which is defined as follows:

50: Half the original speed.
100: The original speed.
400: 4 times the original speed.

Exceptions

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

setPlayerOptionInInt

Set media player options for providing technical previews or special customization features.

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

Details

The media player supports setting options through key and value. In general, you don't need to know about the option settings. You can use the default option settings of the media player.

The difference between this method and setPlayerOptionInString is that the value parameter of this method is of type Int, while the value of setPlayerOptionInString is of type String. These two methods cannot be used together.

Attention: Ensure that you call this method before open or openWithMediaSource.

Parameters

key: The key of the option.
value: The value of the key.

Exceptions

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

setPlayerOptionInString

Set media player options for providing technical previews or special customization features.

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

Details

The media player supports setting options through key and value. In general, you don't need to know about the option settings. You can use the default option settings of the media player.

The difference between this method and setPlayerOptionInInt is that the value parameter of this method is of type String, while the value of setPlayerOptionInInt is of type String. These two methods cannot be used together.

Attention: Ensure that you call this method before open or openWithMediaSource.

Parameters

key: The key of the option.
value: The value of the key.

Exceptions

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

setRenderMode

Sets the render mode of the media player.

Future<void> setRenderMode(RenderModeType renderMode);

Parameters

renderMode: Sets the render mode of the view. See RenderModeType.

Exceptions

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

setSpatialAudioParams

Enables or disables the spatial audio effect for the media player.

Future<void> setSpatialAudioParams(SpatialAudioParams params);

Details

After successfully setting the spatial audio effect parameters of the media player, the SDK enables the spatial audio effect for the media player, and the local user can hear the media resources with a sense of space.

If you need to disable the spatial audio effect for the media player, set the params parameter to null.

Parameters

params: The spatial audio effect parameters of the media player. See SpatialAudioParams.

Exceptions

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

setView

Sets the view.

Future<void> setView(int view);

Exceptions

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

stop

Stops playing the media track.

Future<void> stop();

Exceptions

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

switchSrc

Switches the media resource being played.

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

Details

You can call this method to switch the media resource to be played according to the current network status. For example:

When the network is poor, the media resource to be played is switched to a media resource address with a lower bitrate.
When the network is good, the media resource to be played is switched to a media resource address with a higher bitrate.

After calling this method, if you receive the playerEventSwitchComplete event in the onPlayerEvent callback, the switch is successful; If you receive the playerEventSwitchError event in the onPlayerEvent callback, the switch fails.

Attention:

Ensure that you call this method after open.
To ensure normal playback, pay attention to the following when calling this method:
- Do not call this method when playback is paused.
- Do not call the seek method during switching.
- Before switching the media resource, make sure that the playback position does not exceed the total duration of the media resource to be switched.

Parameters

src

The URL of the media resource.

syncPts

Whether to synchronize the playback position (ms) before and after the switch:

true: Synchronize the playback position before and after the switch.
false: (Default) Do not synchronize the playback position before and after the switch.

Make sure to set this parameter as false if you need to play live streams, or the switch fails. If you need to play on-demand streams, you can set the value of this parameter according to your scenarios.

Exceptions

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

unloadSrc

Unloads media resources that are preloaded.

Future<void> unloadSrc(String src);

Details

Attention:

This method cannot release the media resource being played.

Parameters

src: The URL of the media resource.

Exceptions

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

unregisterAudioFrameObserver [2/2]

Unregisters an audio frame observer.

void unregisterAudioFrameObserver(AudioPcmFrameSink observer);

Parameters

observer: The audio observer. See AudioPcmFrameSink.

Exceptions

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

unregisterPlayerSourceObserver

Releases a media player observer.

void unregisterPlayerSourceObserver(MediaPlayerSourceObserver observer);

Parameters

observer: The player observer, listening for events during the playback. See MediaPlayerSourceObserver.

Exceptions

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

unregisterVideoFrameObserver [2/2]

Unregisters the video frame observer.

void unregisterVideoFrameObserver(MediaPlayerVideoFrameObserver observer);

Parameters

observer: The video observer, reporting the reception of each video frame. See MediaPlayerVideoFrameObserver.

Exceptions

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