IMediaPlayer

This class provides media player functions and supports multiple instances.

adjustPlayoutVolume

Adjusts the local playback volume.

virtual int adjustPlayoutVolume(int volume) = 0;

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.

virtual int adjustPublishSignalVolume(int volume) = 0;

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.

getDuration

Gets the duration of the media resource.

virtual int getDuration(int64_t& duration) = 0;

Parameters

duration
An output parameter. The total duration (ms) of the media file.

Returns

  • 0: Success.
  • < 0: Failure.

getMediaPlayerCacheManager

Gets one IMediaPlayerCacheManager instance.

AGORA_API agora::rtc::IMediaPlayerCacheManager* AGORA_CALL getMediaPlayerCacheManager();

Before calling any APIs in the IMediaPlayerCacheManager class, you need to call this method to get a cache manager instance of a media player.

Call timing

Make sure the IRtcEngine is initialized before you call this method.

Restrictions

The cache manager is a singleton pattern. Therefore, multiple calls to this method returns the same instance.

Returns

The IMediaPlayerCacheManager instance.

getMediaPlayerId

Gets the ID of the media player.

virtual int getMediaPlayerId() const = 0;

Returns

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

getMute

Reports whether the media resource is muted.

virtual int getMute(bool& mute) = 0;

Parameters

mute
An output parameter. Whether the media file is muted:
  • true: The media file is muted.
  • false: The media file is not muted.

Returns

  • 0: Success.
  • < 0: Failure.

getPlayoutVolume

Gets the local playback volume.

virtual int getPlayoutVolume(int& volume) = 0;

Parameters

volume
An output parameter. The local playback volume, which ranges from 0 to 100:
  • 0: Mute.
  • 100: (Default) The original volume.

Returns

  • 0: Success.
  • < 0: Failure.

getPlayPosition

Gets current local playback progress.

virtual int getPlayPosition(int64_t& pos) = 0;

Parameters

pos
The playback position (ms) of the audio effect file.

Returns

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

getPlaySrc

Gets the path of the media resource being played.

virtual const char* getPlaySrc() = 0;

Returns

The path of the media resource being played.

getPublishSignalVolume

Gets the volume of the media file for publishing.

virtual int getPublishSignalVolume(int& volume) = 0;

Parameters

volume
An output parameter. The remote playback volume.

Returns

  • 0: Success.
  • < 0: Failure.

getState

Gets current playback state.

virtual media::base::MEDIA_PLAYER_STATE getState() = 0;

Returns

The current playback state. See MEDIA_PLAYER_STATE.

getStreamCount

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

virtual int getStreamCount(int64_t& count) = 0;

Details

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

Parameters

count
An output parameter. The number of the media streams in the media resource.

Returns

getStreamInfo

Gets the detailed information of the media stream.

virtual int getStreamInfo(int64_t index, media::base::PlayerStreamInfo* info) = 0;

Call timing

Call this method after calling getStreamCount.

Restrictions

None.

Parameters

index
The index of the media stream. This parameter needs to be less than the count parameter of getStreamCount.
info
An output parameter. The detailed information of the media stream. See PlayerStreamInfo.

Returns

  • 0: Success.
  • < 0: Failure.

mute

Sets whether to mute the media file.

virtual int mute(bool muted) = 0;

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

Opens the media resource.

virtual int open(const char* url, int64_t startPos) = 0;

Attention:

This method is called asynchronously.

Call timing

This method can be called either before or after joining the channel.

Restrictions

None.

Related callbacks

After calling this method, the SDK triggers the onPlayerSourceStateChanged callback. After receiving the report of the playback status as PLAYER_STATE_OPEN_COMPLETED, you can call the play method to play the media 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.

Returns

  • 0: Success.
  • < 0: Failure.

openWithMediaSource

Opens a media file and configures the playback scenarios.

virtual int openWithMediaSource(const media::base::MediaSource &source) = 0;

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

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 onPlayerSourceStateChanged callback reporting PLAYER_STATE_OPEN_COMPLETED before calling the play method to play the file.

Parameters

source
Media resources. See MediaSource.

Returns

  • 0: Success.
  • < 0: Failure.

pause

Pauses the playback.

virtual int pause() = 0;

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.

virtual int play() = 0;

Call timing

Restrictions

None.

Returns

  • 0: Success.
  • < 0: Failure.

playPreloadedSrc

Plays preloaded media resources.

virtual int playPreloadedSrc(const char* src) = 0;

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 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.

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.

Returns

  • 0: Success.
  • < 0: Failure.

preloadSrc

Preloads a media resource.

virtual int preloadSrc(const char* src, int64_t startPos) = 0;

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.

Note:
  • Before calling this method, ensure that you have called open or openWithMediaSource to open the media resource successfully.
  • 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 [1/2]

Registers a PCM audio frame observer object.

virtual int registerAudioFrameObserver(media::IAudioPcmFrameSink* observer) = 0;

Details

You need to implement the IAudioPcmFrameSink 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 audio frame observer, reporting the reception of each audio frame. See IAudioPcmFrameSink.

Returns

  • 0: Success.
  • < 0: Failure.

registerAudioFrameObserver [2/2]

Registers an audio frame observer object.

virtual int registerAudioFrameObserver(media::IAudioPcmFrameSink* observer,
                                         RAW_AUDIO_FRAME_OP_MODE_TYPE mode) = 0;

Parameters

observer

The audio frame observer, reporting the reception of each audio frame. See IAudioPcmFrameSink.

mode

The use mode of the audio frame. See RAW_AUDIO_FRAME_OP_MODE_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

registerPlayerSourceObserver

Registers a media player observer.

virtual int registerPlayerSourceObserver(IMediaPlayerSourceObserver* observer) = 0;

Call timing

This method can be called either before or after joining the channel.

Restrictions

None.

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

registerVideoFrameObserver

Registers a video frame observer object.

virtual int registerVideoFrameObserver(media::base::IVideoFrameObserver* observer) = 0;

Details

You need to implement the IVideoFrameObserver 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 IVideoFrameObserver.

Returns

  • 0: Success.
  • < 0: Failure.

resume

Resumes playing the media file.

virtual int resume() = 0;

Returns

  • 0: Success.
  • < 0: Failure.

seek

Seeks to a new playback position.

virtual int seek(int64_t newPos) = 0;
  • If you call seek after the playback has completed (upon receiving callback onPlayerSourceStateChanged 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 onPlayerSourceStateChanged 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.

Related callbacks

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

Parameters

newPos
The new playback position (ms).

Returns

  • 0: Success.
  • < 0: Failure.

selectAudioTrack [2/2]

Selects the audio track used during playback.

virtual int selectAudioTrack(int index) = 0;

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.

Returns

  • 0: Success.
  • < 0: Failure.

setAudioPitch

Sets the pitch of the current media resource.

virtual int setAudioPitch(int pitch) = 0;

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.

Returns

  • 0: Success.
  • < 0: Failure.

setAudioDualMonoMode

Sets the channel mode of the current audio file.

virtual int setAudioDualMonoMode(agora::media::base::AUDIO_DUAL_MONO_MODE mode) = 0;

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 AUDIO_DUAL_MONO_MODE.

Returns

  • 0: Success.
  • < 0: Failure.

setLoopCount

Sets the loop playback.

virtual int setLoopCount(int loopCount) = 0;

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 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.

virtual int setPlaybackSpeed(int speed) = 0;

Details

Call this method after calling open.

Parameters

speed
The playback speed. Agora recommends that you set this to a value between 30 and 400, defined as follows:
  • 30: 0.3 times the original speed.
  • 100: The original speed.
  • 400: 4 times the original speed.

Returns

  • 0: Success.
  • < 0: Failure.

setPlayerOption [1/2]

Sets media player options.

virtual int setPlayerOption(const char* key, int64_t value) = 0;

The media player supports setting options through key and value.

The difference between this method and setPlayerOption [2/2] is that the value parameter of this method is of type Int, while the value of setPlayerOption [2/2] 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 or openWithMediaSource method.

Restrictions

None.

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

setPlayerOption [2/2]

Sets media player options.

virtual int setPlayerOption(const char* key, const char* value) = 0;

The media player supports setting options through key and value.

The difference between this method and setPlayerOption [1/2] is that the value parameter of this method is of type String, while the value of setPlayerOption [1/2] 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 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.

virtual int setRenderMode(media::base::RENDER_MODE_TYPE renderMode) = 0;

Parameters

renderMode

Sets the render mode of the view. See RENDER_MODE_TYPE.

Returns

  • 0: Success.
  • < 0: Failure.

setSpatialAudioParams

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

virtual int setSpatialAudioParams(const SpatialAudioParams& params) = 0;

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.

virtual int setView(media::base::view_t view) = 0;

Call timing

You can call this method either before or after joining a channel.

Restrictions

None.

Parameters

view
The render view. On Windows, this parameter sets the window handle (HWND).

Returns

  • 0: Success.
  • < 0: Failure.

stop

Stops playing the media track.

virtual int stop() = 0;

After calling this method to stop playback, if you want to play again, you need to call open 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.

virtual int switchSrc(const char* src, bool syncPts) = 0;

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 onPlayerEvent callback report the PLAYER_EVENT_SWITCH_COMPLETE event, the switching is successful. If the switching fails, the SDK will automatically retry 3 times. If it still fails, you will receive the onPlayerEvent callback reporting the PLAYER_EVENT_SWITCH_ERROR event indicating an error occurred during media resource switching.

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.

Returns

  • 0: Success.
  • < 0: Failure.

unloadSrc

Unloads media resources that are preloaded.

virtual int unloadSrc(const char* src) = 0;

Details

Attention:

This method cannot release the media resource being played.

Parameters

src
The URL of the media resource.

Returns

  • 0: Success.
  • < 0: Failure.

unregisterAudioFrameObserver

Unregisters an audio frame observer.

virtual int unregisterAudioFrameObserver(media::IAudioPcmFrameSink* observer) = 0;

Parameters

observer
The audio observer. See IAudioPcmFrameSink.

Returns

  • 0: Success.
  • < 0: Failure.

unregisterPlayerSourceObserver

Releases a media player observer.

virtual int unregisterPlayerSourceObserver(IMediaPlayerSourceObserver* observer) = 0;

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.

unregisterVideoFrameObserver

Unregisters the video frame observer.

virtual int unregisterVideoFrameObserver(agora::media::base::IVideoFrameObserver* observer) = 0;

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.