agora::rtc::IMediaPlayer Class Reference

Public Member Functions
virtual int	initialize (const MediaPlayerContext &context)=0
virtual int	open (const char *src, int64_t startPos)=0
virtual int	play ()=0
virtual int	pause ()=0
virtual int	stop ()=0
virtual int	seek (int64_t pos)=0
virtual int	mute (bool mute)=0
virtual int	getMute (bool &mute)=0
virtual int	adjustPlayoutVolume (int volume)=0
virtual int	getPlayoutVolume (int &volume)=0
virtual int	getDuration (int64_t &duration)=0
virtual int	getPlayPosition (int64_t &pos)=0
virtual int	getStreamCount (int64_t &count)=0
virtual int	getStreamInfo (int64_t index, media::base::MediaStreamInfo *info)=0
virtual media::base::MEDIA_PLAYER_STATE	getState ()=0
virtual int	setView (media::base::view_t view)=0
virtual int	setRenderMode (media::base::RENDER_MODE_TYPE renderMode)=0
virtual int	registerPlayerObserver (IMediaPlayerObserver *observer)=0
virtual int	unregisterPlayerObserver (IMediaPlayerObserver *observer)=0
virtual int	registerVideoFrameObserver (media::base::IVideoFrameObserver *observer)=0
virtual int	unregisterVideoFrameObserver (agora::media::base::IVideoFrameObserver *observer)=0
virtual int	registerAudioFrameObserver (media::base::IAudioFrameObserver *observer)=0
virtual int	unregisterAudioFrameObserver (agora::media::base::IAudioFrameObserver *observer)=0
virtual int	setLogFile (const char *filePath)=0
virtual int	setLogFilter (unsigned int filter)=0
virtual int	changePlaybackSpeed (media::base::MEDIA_PLAYER_PLAYBACK_SPEED speed)=0
virtual int	selectAudioTrack (int index)=0
virtual int	setPlayerOption (const char *key, int value)=0
virtual int	setPlayerOption (const char *key, const char *value)=0
virtual int	setExternalSubtitle (const char *url)=0
virtual int	setPlayerOption (const char *key, const char *value)=0
virtual int	setLoopCount (int loopCount)=0
virtual const char *	getPlayerSdkVersion ()=0
virtual int	switchSrc (const char *src, bool syncPts=true)=0
virtual int	addPreloadSrc (const char *src, int64_t startPos)=0
virtual int	playPreload (const char *src)=0
virtual void	release (bool sync=true)=0

Protected Member Functions
virtual	~IMediaPlayer ()=default

Detailed Description

The IMediaPlayer class.

Constructor & Destructor Documentation

~IMediaPlayer()

virtual agora::rtc::IMediaPlayer::~IMediaPlayer ( )

protectedvirtualdefault

Member Function Documentation

initialize()

virtual int agora::rtc::IMediaPlayer::initialize ( const MediaPlayerContext &  context )

pure virtual

Initializes the MediaPlayer Kit service.

Parameters

context

The MediaPlayer Kit context. See MediaPlayerContext for details.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

open()

virtual int agora::rtc::IMediaPlayer::open ( const char *  src, int64_t  startPos  )

pure virtual

Opens the media resource.

Parameters

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

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

play()

virtual int agora::rtc::IMediaPlayer::play ( )

pure virtual

Plays the media resource.

After open() or pause() or seek(), you can call this method to play the media resource.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

pause()

virtual int agora::rtc::IMediaPlayer::pause ( )

pure virtual

Pauses the playback.

To resume the playback, call the play() method.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

stop()

virtual int agora::rtc::IMediaPlayer::stop ( )

pure virtual

Stops the playback.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

seek()

virtual int agora::rtc::IMediaPlayer::seek ( int64_t  pos )

pure virtual

Seeks to a new playback position.

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

Parameters

pos	The new playback position (ms).

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

mute()

virtual int agora::rtc::IMediaPlayer::mute ( bool  mute )

pure virtual

Sets whether to mute the media resource.

Parameters

mute	Sets whether to mute the media resource: true: Mute the media resource. false: (default) Unmute the media resource.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

getMute()

virtual int agora::rtc::IMediaPlayer::getMute ( bool &  mute )

pure virtual

Checks whether the media resource is muted.

Parameters

[out]

mute

Whether the media resource is muted: true: The media resource is muted. false: (default) The media resource is not muted.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

adjustPlayoutVolume()

virtual int agora::rtc::IMediaPlayer::adjustPlayoutVolume ( int  volume )

pure virtual

Adjusts the local playback volume.

Parameters

volume

The local playback volume, which ranges from 0 to 100: 0: Mute. 100: (default) The original volume.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

getPlayoutVolume()

virtual int agora::rtc::IMediaPlayer::getPlayoutVolume ( int &  volume )

pure virtual

Gets current local playback volume.

Parameters

[out]

volume

The local playback volume, which ranges from 0 to 100: 0: Mute. 100: (default) The original volume.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

getDuration()

virtual int agora::rtc::IMediaPlayer::getDuration ( int64_t &  duration )

pure virtual

Gets the duration of the media resource.

Parameters

[out]

duration

The total duration (ms) of the media resource.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

getPlayPosition()

virtual int agora::rtc::IMediaPlayer::getPlayPosition ( int64_t &  pos )

pure virtual

Gets current playback progress.

Parameters

[out]

pos

The playback progress (ms).

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

getStreamCount()

virtual int agora::rtc::IMediaPlayer::getStreamCount ( int64_t &  count )

pure virtual

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

Parameters

[out]

count

The number of the media streams in the media resource.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

getStreamInfo()

virtual int agora::rtc::IMediaPlayer::getStreamInfo ( int64_t  index, media::base::MediaStreamInfo *  info  )

pure virtual

Gets the detailed information of the media stream.

Parameters

	index	The index of the media stream.
[out]	info	The detailed information of the media stream. See MediaStreamInfo for details.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

getState()

virtual media::base::MEDIA_PLAYER_STATE agora::rtc::IMediaPlayer::getState ( )

pure virtual

Gets current playback state.

Returns

The current playback state.

• 0: Success.See MEDIA_PLAYER_STATE for details.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setView()

virtual int agora::rtc::IMediaPlayer::setView ( media::base::view_t  view )

pure virtual

Sets the player's render view.

Parameters

view	The player's render view (HWND).

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setRenderMode()

virtual int agora::rtc::IMediaPlayer::setRenderMode ( media::base::RENDER_MODE_TYPE  renderMode )

pure virtual

Sets the player's render mode.

Parameters

renderMode

The player's render mode RENDER_MODE_HIDDEN (1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. RENDER_MODE_FIT (2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to disparity in the aspect ratio are filled with black.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

registerPlayerObserver()

virtual int agora::rtc::IMediaPlayer::registerPlayerObserver ( IMediaPlayerObserver *  observer )

pure virtual

Registers a player observer.

Parameters

observer

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

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

unregisterPlayerObserver()

virtual int agora::rtc::IMediaPlayer::unregisterPlayerObserver ( IMediaPlayerObserver *  observer )

pure virtual

Unregisters a player observer.

Parameters

observer

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

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

registerVideoFrameObserver()

virtual int agora::rtc::IMediaPlayer::registerVideoFrameObserver ( media::base::IVideoFrameObserver *  observer )

pure virtual

Registers a video observer.

Parameters

observer

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

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

unregisterVideoFrameObserver()

virtual int agora::rtc::IMediaPlayer::unregisterVideoFrameObserver ( agora::media::base::IVideoFrameObserver *  observer )

pure virtual

Unregisters a video observer.

Parameters

observer

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

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

registerAudioFrameObserver()

virtual int agora::rtc::IMediaPlayer::registerAudioFrameObserver ( media::base::IAudioFrameObserver *  observer )

pure virtual

Registers an audio observer.

Parameters

observer

The audio observer, reporting the reception of each audio frame. See IAudioFrameObserver for details.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

unregisterAudioFrameObserver()

virtual int agora::rtc::IMediaPlayer::unregisterAudioFrameObserver ( agora::media::base::IAudioFrameObserver *  observer )

pure virtual

Unregisters an audio observer.

Parameters

observer

The audio observer, reporting the reception of each audio frame. See IAudioFrameObserver for details.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setLogFile()

virtual int agora::rtc::IMediaPlayer::setLogFile ( const char *  filePath )

pure virtual

Sets the output path of the log file.

The log generated during the mediaplayer kit runtime records in the log file. To set the storage path of the log file, call this method. Ensure that the path you specified exists and is writable. If you don't call this method, the log file records in the log file to the default path: "C:\Users\{user_name}\AppData\Local\Agora\{project_name}".

Note

Call this method immediately after initialize(), otherwise the log file may not be complete.

Parameters

filePath

Absolute path of the log file, which is UTF-8 encoded.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setLogFilter()

virtual int agora::rtc::IMediaPlayer::setLogFilter ( unsigned int  filter )

pure virtual

Sets the output level of the log file.

Sets the filter level of the output log for the MediaPlayer Kit. The filter levels from low to high are OFF, DEBUG, INFO, WARN, ERROR, and CRITICAL respectively. Sets a filter level and you can get the log for all levels prior to that level. See filter for details.

Parameters

filter

The filter level of the output log file. LOG_FILTER_OFF (0): Do not output any log. LOG_FILTER_DEBUG (0x80f): Output all the log. LOG_FILTER_INFO (0x0f): (Recommended) Output the log of the INFO, WARN, ERROR, and CRITICAL levels. LOG_FILTER_WARN (0x0e): Output the log of the WARN, ERROR, and CRITICAL levels. LOG_FILTER_ERROR (0x0c): Output the log of the ERROR and CRITICAL levels. LOG_FILTER_CRITICAL (0x08): Output the log of the CRITICAL level.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

changePlaybackSpeed()

virtual int agora::rtc::IMediaPlayer::changePlaybackSpeed ( media::base::MEDIA_PLAYER_PLAYBACK_SPEED  speed )

pure virtual

Adjusts the playback speed.

Call this method after the play() method.

Parameters

speed

The playback speed. See MEDIA_PLAYER_PLAYBACK_SPEED for details

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

selectAudioTrack()

virtual int agora::rtc::IMediaPlayer::selectAudioTrack ( int  index )

pure virtual

Selects the audio track.

When the media resource contains more than one audio track, you can call this method to select which audio track to use.

Parameters

index

The index of the audio track.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setPlayerOption() [1/3]

virtual int agora::rtc::IMediaPlayer::setPlayerOption ( const char *  key, int  value  )

pure virtual

Sets the private options for the MediaPlayer Kit.

The MediaPlayer Kit supports setting private options by providing key and value. Under normal circumstances, you do not need to know the private option settings, and just use the default option settings.

Note

Calling this method before the open method.

Parameters

key	key.
value	value.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setPlayerOption() [2/3]

virtual int agora::rtc::IMediaPlayer::setPlayerOption ( const char *  key, const char *  value  )

pure virtual

Sets the private options for the MediaPlayer Kit.

The MediaPlayer Kit supports setting private options by providing key and value. Under normal circumstances, you do not need to know the private option settings, and just use the default option settings.

Note

Calling this method before the open method.

Parameters

key	key.
value	value.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setExternalSubtitle()

virtual int agora::rtc::IMediaPlayer::setExternalSubtitle ( const char *  url )

pure virtual

Sets the external subtitle.

After opening the media file, you can call this method set the mediaplayer kit to display the external subtitle.

Parameters

url	The URL address of the external subtitle. Both SRT subtitle and ASS subtitle, local address and online address are supported.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setPlayerOption() [3/3]

virtual int agora::rtc::IMediaPlayer::setPlayerOption ( const char *  key, const char *  value  )

pure virtual

Sets the private options for the MediaPlayer Kit.

The MediaPlayer Kit supports setting private options by providing key and value. Under normal circumstances, you do not need to know the private option settings, and just use the default option settings.

Note

Calling this method before the open method.

Parameters

key	key.
value	value.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

setLoopCount()

virtual int agora::rtc::IMediaPlayer::setLoopCount ( int  loopCount )

pure virtual

Sets the loop playback.

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

When the loop playback ends, MediaPlayer Kit returns PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED.

Parameters

loopCount

The number of the loops.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

getPlayerSdkVersion()

virtual const char* agora::rtc::IMediaPlayer::getPlayerSdkVersion ( )

pure virtual

Gets the version number of the MediaPlayer Kit.

Returns

The version number of the MediaPlayer Kit, such as "1.2.1".

switchSrc()

virtual int agora::rtc::IMediaPlayer::switchSrc ( const char *  src, bool  syncPts = true  )

pure virtual

Switches the media resource being played.

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 switchSrc, if you receive the onPlayerEvent callback event PLAYER_EVENT_SWITCH_COMPLETE, the switch is successful; if you receive the onPlayerEvent callback event PLAYER_EVENT_SWITCH_ERROR, the switch fails.

Note

• Make sure to call this method after open.
• To ensure normal playback, pay attention to the following when calling switchSrc(src, true):
  • Do not call this method when playback is paused.
  • Do not call seek during switching.
  • Before switching the media resource, ensure that the playback position does not exceed the total duration of the media resource to be switched.

Parameters

src

The URL address of the media resource to be switched. HTTP, RTMP, and RTSP protocols are supported for local and online media streams.

syncPts

Whether to synchronize the playback position(millionseconds) before and after the switch: true: (Default) Synchronize the playback position before and after the switch. After the MediaPlayer Kit switches the media resource, it starts playing the media resource from the playback position at the time of the switch. Note: Agora only supports setting syncPts to true when playing on-demand streams. false: The playback position before and after the media resource switch is not synchronized. Instead, the playback position after the media resource is switched is determined as follows: If the media resource is an on-demand stream, the MediaPlayer Kit starts playing the media resource from the beginning. If the media resource is a live stream, the MediaPlayer Kit starts playing the media resource from the playback position when the code rate is switched.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

addPreloadSrc()

virtual int agora::rtc::IMediaPlayer::addPreloadSrc ( const char *  src, int64_t  startPos  )

pure virtual

Preloads media resources.

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 addPreloadSrc, if you receive the onPreloadEvent callback event PLAYER_PRELOAD_EVENT_COMPLETE, the preload is successful; if you receive the onPreloadEvent callback event PLAYER_PRELOAD_EVENT_ERROR, the preload fails.

After the preload is successful, if you want to play the media resource, call playPreload; 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 address of the preloaded media resource. HTTP, RTMP, and RTSP protocols are supported for local and online media streams.
startPos	The starting position (milliseconds) when starting to play after preloading to the playlist. When preloading a live stream, set startPos to 0.

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

playPreload()

virtual int agora::rtc::IMediaPlayer::playPreload ( const char *  src )

pure virtual

Plays preloaded media resources.

This method only supports playing media resources that have been preloaded into the playlist. After calling this method, if you receive the onPlayerStateChanged callback to report the state PLAYER_STATE_PLAYING, the playback is successful.

If you want to change the preloaded media resource to be 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 addPreloadSrc to preload the media resource to the playlist again before playing.. If you want to clear the playlist, call stop.

Note

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

Parameters

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

Returns

• 0: Success.
• < 0: Failure. See MEDIA_PLAYER_ERROR for details.

release()

virtual void agora::rtc::IMediaPlayer::release ( bool  sync = true )

pure virtual

Releases the IMediaPlayer resource.