IMediaPlayer
This class provides media player functions and supports multiple instances.
adjustPlayoutVolume
Adjusts the local playback volume.
int adjustPlayoutVolume(int volume);
Call timing
This method can be called either before or after joining the channel.
Restrictions
None.
Parameters
- volume
- The local playback volume, which ranges from 0 to 100:
- 0: Mute.
- 100: (Default) The original volume.
Returns
- 0: Success.
- < 0: Failure.
adjustPublishSignalVolume
Adjusts the volume of the media file for publishing.
int adjustPublishSignalVolume(int volume);
After connected to the Agora server, you can call this method to adjust the volume of the media file heard by the remote user.
Call timing
This method can be called either before or after joining the channel.
Restrictions
None.
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).
Returns
- 0: Success.
- < 0: Failure.
destroy
Destroys the media player instance.
int destroy();
Returns
- ≥ 0: Success. Returns the ID of media player instance.
- < 0: Failure.
getDuration
Gets the duration of the media resource.
long getDuration();
Returns
- If the method call succeeds, the SDK returns the total duration(ms) of the media file.
- < 0: Failure.
getMediaPlayerId
Gets the ID of the media player.
int getMediaPlayerId();
Returns
- Success. The ID of the media player.
- < 0: Failure.
getPlayoutVolume
Gets the local playback volume.
int getPlayoutVolume();
Returns
- 0: Mute.
- 100: (Default) The original volume.
getPlayPosition
Gets current local playback progress.
long getPlayPosition();
Returns
- Returns the current playback progress (ms) if the call succeeds.
- < 0: Failure. See MediaPlayerReason.
getPlaySrc [1/2]
Gets the path of the media resource being played.
String getPlaySrc();
Returns
The path of the media resource being played.
getPublishSignalVolume
Gets the volume of the media file for publishing.
int getPublishSignalVolume();
Returns
- ≥ 0: The remote playback volume.
- < 0: Failure.
getState
Gets current playback state.
Constants.MediaPlayerState getState();
Returns
The current playback state. See MediaPlayerState.
getStreamCount
Gets the number of the media streams in the media resource.
int getStreamCount();
Details
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.
MediaStreamInfo getStreamInfo(int index);
Call timing
Call this method after calling getStreamCount.
Restrictions
None.
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 MediaStreamInfo.
- If the call fails, returns
NULL
.
getMute
Reports whether the media resource is muted.
boolean getMute();
Returns
true
: Reports whether the media resource is muted.false
: Reports whether the media resource is muted.
mute
Sets whether to mute the media file.
int mute(boolean muted);
Call timing
You can call this method either before or after joining a channel.
Restrictions
None.
Parameters
- muted
- Whether to mute the media file:
true
: Mute the media file.false
: (Default) Unmute the media file.
Returns
- 0: Success.
- < 0: Failure.
open [1/2]
Opens the media resource.
int open(String url, long startPos);
This method supports playing URI files starting with content://
.
This method is called asynchronously.
Call timing
This method can be called either before or after joining the channel.
Restrictions
None.
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.
Returns
- 0: Success.
- < 0: Failure.
open [2/2]
Opens a media file through a URI address.
int open(Uri uri, long startPos);
Details
This method is called asynchronously.
Parameters
- uri
- The URI (Uniform Resource Identifier) of the media file.
- startPos
- The starting position (ms) for playback. The default value is 0.
Returns
- 0: Success.
- < 0: Failure.
openWithMediaSource
Opens a media file and configures the playback scenarios.
int openWithMediaSource(MediaPlayerSource source);
This method supports opening different types of media files, including URI files starting with content://
, media files in the assets
folder, and setting the playback options.
Call timing
You can call this method either before or after joining a channel.
Restrictions
This method is called asynchronously. If you need to play a media file, make sure you receive the onPlayerStateChanged callback reporting PLAYER_STATE_OPEN_COMPLETED before calling the play method to play the file.
Parameters
- source
- Media resources. See MediaPlayerSource.
Returns
- 0: Success.
- < 0: Failure.
pause
Pauses the playback.
int pause();
Call timing
You can call this method either before or after joining a channel.
Restrictions
None.
Returns
- 0: Success.
- < 0: Failure.
play
Plays the media file.
int play();
Call timing
- Call this method after calling open [1/2] or openWithMediaSource opening a media file and receiving a onPlayerStateChanged callback reporting the status as PLAYER_STATE_OPEN_COMPLETED.
- Call the method after calling seek.
Restrictions
None.
Returns
- 0: Success.
- < 0: Failure.
playPreloadedSrc
Plays preloaded media resources.
int 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 onPlayerStateChanged callback which reports the PLAYER_STATE_PLAYING 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.
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.
Returns
- 0: Success.
- < 0: Failure.
preloadSrc
Preloads a media resource.
int preloadSrc(String src, long 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.
After calling this method, if you receive the PLAYER_PRELOAD_EVENT_COMPLETE event in the onPreloadEvent callback, the preload is successful; If you receive the PLAYER_PRELOAD_EVENT_ERROR event in the onPreloadEvent callback, the preload fails.
If the preload is successful and you want to play the media resource, call playPreloadedSrc; if you want to clear the playlist, call stop.
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.
Returns
- 0: Success.
- < 0: Failure.
registerAudioFrameObserver
Registers an audio frame observer object.
int registerAudioFrameObserver(IMediaPlayerAudioFrameObserver audioFrameObserver, int mode);
Parameters
- audioFrameObserver
-
The audio frame observer, reporting the reception of each audio frame. See IMediaPlayerAudioFrameObserver.
- mode
-
The use mode of the audio frame:
- RAW_AUDIO_FRAME_OP_MODE_READ_ONLY(0): (Default) Read only mode. For example, when users acquire the data with the Agora SDK, then push the RTMP or RTMPS streams.
- RAW_AUDIO_FRAME_OP_MODE_READ_WRITE(2): Read and write mode: Users read the data from AudioFrame, modify it, and then play it. For example, when users have their own audio-effect processing module and perform some voice pre-processing, such as a voice change.
Returns
- 0: Success.
- < 0: Failure.
registerVideoFrameObserver
Registers a video frame observer object.
int registerVideoFrameObserver(IMediaPlayerVideoFrameObserver videoFrameObserver);
Details
You need to implement the IMediaPlayerVideoFrameObserver 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
- videoFrameObserver
- The video observer, reporting the reception of each video frame. See IMediaPlayerVideoFrameObserver.
Returns
- 0: Success.
- < 0: Failure.
registerPlayerObserver
Registers a media player observer.
int registerPlayerObserver(IMediaPlayerObserver playerObserver);
Call timing
This method can be called either before or after joining the channel.
Restrictions
None.
Parameters
- playerObserver
- The player observer, listening for events during the playback. See IMediaPlayerObserver.
Returns
- 0: Success.
- < 0: Failure.
resume
Resumes playing the media file.
int resume();
Returns
- 0: Success.
- < 0: Failure.
seek
Seeks to a new playback position.
int seek(long newPos);
- If you call seek after the playback has completed (upon receiving callback onPlayerStateChanged reporting playback status as PLAYER_STATE_PLAYBACK_COMPLETED or PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED), the SDK will play the media file from the specified position. At this point, you will receive callback onPlayerStateChanged reporting playback status as PLAYER_STATE_PLAYING.
- If you call seek while the playback is paused, upon successful call of this method, the SDK will seek to the specified position. To resume playback, call resume orplay .
Call timing
You can call this method either before or after joining a channel.
Restrictions
None.
Parameters
- newPos
- The new playback position (ms).
Returns
- 0: Success.
- < 0: Failure.
selectAudioTrack
Selects the audio track used during playback.
int 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.
Parameters
- index
- The index of the audio track.
Returns
- 0: Success.
- < 0: Failure.
setAudioPitch
Sets the pitch of the current media resource.
int setAudioPitch(int pitch);
Details
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.
Returns
- 0: Success.
- < 0: Failure.
setAudioDualMonoMode
Sets the channel mode of the current audio file.
int setAudioDualMonoMode(int 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.
- Call this method after calling open [1/2].
- This method only applies to stereo audio files.
Parameters
- mode
- The channel mode.
- AUDIO_DUAL_MONO_STEREO(0): Original mode.
- AUDIO_DUAL_MONO_L(1): Left channel mode. This mode replaces the audio of the right channel with the audio of the left channel, which means the user can only hear the audio of the left channel.
- AUDIO_DUAL_MONO_R(2): Right channel mode. This mode replaces the audio of the left channel with the audio of the right channel, which means the user can only hear the audio of the right channel.
- AUDIO_DUAL_MONO_MIX(3): Mixed channel mode. This mode mixes the audio of the left channel and the right channel, which means the user can hear the audio of the left channel and the right channel at the same time.
Returns
- 0: Success.
- < 0: Failure.
setLoopCount
Sets the loop playback.
int 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 onPlayerStateChanged and reports the playback state as PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED.
Parameters
- loopCount
- The number of times the audio effect loops:
- ≥0: Number of times for playing. For example, setting it to 0 means no loop playback, playing only once; setting it to 1 means loop playback once, playing a total of twice.
- -1: Play the audio file in an infinite loop.
Returns
- 0: Success.
- < 0: Failure.
setPlaybackSpeed
Sets the channel mode of the current audio file.
int setPlaybackSpeed(int speed);
Details
Call this method after calling open [1/2].
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.
Returns
- 0: Success.
- < 0: Failure.
setPlayerOption
Sets media player options.
int setPlayerOption(String key, int value);
The media player supports setting options through key and value.
The difference between this method and setPlayerOptionString is that the value parameter of this method is of type Int, while the value of setPlayerOptionString is of type String. These two methods cannot be used together.
Applicable scenarios
Scenarios that require technical previews or special customization features. In general, you do not need to call this method; you can simply use the default options provided by the media player.
Call timing
Call this method before the open [1/2] or openWithMediaSource method.
Restrictions
None.
Parameters
- key
- The key of the option.
- value
- The value of the key.
Returns
- 0: Success.
- < 0: Failure.
setPlayerOptionString
Sets media player options.
int setPlayerOptionString(String key, String value);
The media player supports setting options through key and value.
The difference between this method and setPlayerOption is that the value parameter of this method is of type String, while the value of setPlayerOption is of type String. These two methods cannot be used together.
Applicable scenarios
Scenarios that require technical previews or special customization features. In general, you do not need to call this method; you can simply use the default options provided by the media player.
Call timing
Call this method before the open [1/2] or openWithMediaSource method.
Restrictions
None.
Parameters
- key
- The key of the option.
- value
- The value of the key.
Returns
- 0: Success.
- < 0: Failure.
setRenderMode
Sets the render mode of the media player.
int setRenderMode(int mode);
Parameters
- mode
-
Sets the render mode of the view:
- RENDER_MODE_HIDDEN(1): Hidden mode. Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.
- RENDER_MODE_FIT(2): Fit mode. Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black.
- RENDER_MODE_ADAPTIVE(3): Adaptive mode.
- Deprecated:
- This enumerator is deprecated and not recommended for use.
Returns
- 0: Success.
- < 0: Failure.
setSpatialAudioParams
Enables or disables the spatial audio effect for the media player.
int 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.
Returns
- 0: Success.
- < 0: Failure.
setView
Sets the view.
int setView(View videoView);
Call timing
You can call this method either before or after joining a channel.
Restrictions
None.
Parameters
- videoView
- The render view.
Returns
- 0: Success.
- < 0: Failure.
stop
Stops playing the media track.
int stop();
After calling this method to stop playback, if you want to play again, you need to call open [1/2] or openWithMediaSource to open the media resource.
Call timing
Call this method after play.
Restrictions
None.
Returns
- 0: Success.
- < 0: Failure.
switchSrc
Switches the media resource being played.
int switchSrc(String src, boolean syncPts);
Details
- 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 PLAYER_EVENT_SWITCH_COMPLETE event in the onPlayerEvent callback, the switch is successful; If you receive the PLAYER_EVENT_SWITCH_ERROR event in the onPlayerEvent callback, the switch fails.
- Ensure that you call this method after open [1/2].
- 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.
Returns
- 0: Success.
- < 0: Failure.
unloadSrc
Unloads media resources that are preloaded.
int unloadSrc(String src);
Details
This method cannot release the media resource being played.
Parameters
- src
- The URL of the media resource.
Returns
- 0: Success.
- < 0: Failure.
unRegisterPlayerObserver
Releases a media player observer.
int unRegisterPlayerObserver(IMediaPlayerObserver playerObserver);
Parameters
- playerObserver
- The player observer, listening for events during the playback. See IMediaPlayerObserver.
Returns
- 0: Success.
- < 0: Failure.