Documentation
Interactive Live Streaming Premium (Legacy)
Console 官网 Community Technical support
English
search-icon

MediaPlayer Kit C++ API Reference

Overview IMediaPlayer IMediaPlayerObserver Error Codes

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
contextThe MediaPlayer Kit context. See MediaPlayerContext for details.
Returns

◆ open()

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

Opens the media resource.

Parameters
srcThe path of the media resource. Both local path and online path are supported.
startPosThe starting position (ms) for playback. Default value is 0.
Returns

◆ 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

◆ pause()

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

Pauses the playback.

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

Returns

◆ stop()

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

Stops the playback.

Returns

◆ 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
posThe new playback position (ms).
Returns

◆ mute()

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

Sets whether to mute the media resource.

Parameters
muteSets whether to mute the media resource:
  • true: Mute the media resource.
  • false: (default) Unmute the media resource.
Returns

◆ getMute()

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

Checks whether the media resource is muted.

Parameters
[out]muteWhether the media resource is muted:
  • true: The media resource is muted.
  • false: (default) The media resource is not muted.
Returns

◆ adjustPlayoutVolume()

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

Adjusts the local playback volume.

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

◆ getPlayoutVolume()

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

Gets current local playback volume.

Parameters
[out]volumeThe local playback volume, which ranges from 0 to 100:
  • 0: Mute.
  • 100: (default) The original volume.
Returns

◆ getDuration()

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

Gets the duration of the media resource.

Parameters
[out]durationThe total duration (ms) of the media resource.
Returns

◆ getPlayPosition()

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

Gets current playback progress.

Parameters
[out]posThe playback progress (ms).
Returns

◆ 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]countThe number of the media streams in the media resource.
Returns

◆ 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
indexThe index of the media stream.
[out]infoThe 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.

◆ setView()

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

Sets the player's render view.

Parameters
viewThe player's render view (HWND).
Returns

◆ setRenderMode()

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

Sets the player's render mode.

Parameters
renderModeThe 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

◆ registerPlayerObserver()

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

Registers a player observer.

Parameters
observerThe player observer, listening for events during the playback. See IMediaPlayerObserver for details.
Returns

◆ unregisterPlayerObserver()

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

Unregisters a player observer.

Parameters
observerThe player observer, listening for events during the playback. See IMediaPlayerObserver for details.
Returns

◆ registerVideoFrameObserver()

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

Registers a video observer.

Parameters
observerThe video observer, reporting the reception of each video frame. See IVideoFrameObserver for details.
Returns

◆ unregisterVideoFrameObserver()

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

Unregisters a video observer.

Parameters
observerThe video observer, reporting the reception of each video frame. See IVideoFrameObserver for details.
Returns

◆ registerAudioFrameObserver()

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

Registers an audio observer.

Parameters
observerThe audio observer, reporting the reception of each audio frame. See IAudioFrameObserver for details.
Returns

◆ unregisterAudioFrameObserver()

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

Unregisters an audio observer.

Parameters
observerThe audio observer, reporting the reception of each audio frame. See IAudioFrameObserver for details.
Returns

◆ 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
filePathAbsolute path of the log file, which is UTF-8 encoded.
Returns

◆ 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
filterThe 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

◆ 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
speedThe playback speed. See MEDIA_PLAYER_PLAYBACK_SPEED for details
Returns

◆ 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
indexThe index of the audio track.
Returns

◆ 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
keykey.
valuevalue.
Returns

◆ 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
keykey.
valuevalue.
Returns

◆ 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
urlThe URL address of the external subtitle. Both SRT subtitle and ASS subtitle, local address and online address are supported.
Returns

◆ 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
keykey.
valuevalue.
Returns

◆ 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
loopCountThe number of the loops.
Returns

◆ 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
srcThe URL address of the media resource to be switched. HTTP, RTMP, and RTSP protocols are supported for local and online media streams.
syncPtsWhether 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

◆ 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
srcThe URL address of the preloaded media resource. HTTP, RTMP, and RTSP protocols are supported for local and online media streams.
startPosThe starting position (milliseconds) when starting to play after preloading to the playlist. When preloading a live stream, set startPos to 0.
Returns

◆ 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
srcThe 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

◆ release()

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

Releases the IMediaPlayer resource.