文档中心
互动直播 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

MediaPlayer Kit C++ API Reference

概览 IMediaPlayer IMediaPlayerObserver 错误码

Public 成员函数

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 takeScreenshot (const char *filename)=0
 
virtual int setExternalSubtitle (const char *url)=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 成员函数

virtual ~IMediaPlayer ()=default
 

详细描述

IMediaPlayer 类

构造及析构函数说明

◆ ~IMediaPlayer()

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

成员函数说明

◆ initialize()

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

初始化播放器

参数
context详见 MediaPlayerContext
返回

◆ open()

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

打开媒体文件

参数
src设置媒体文件的路径：本地路径或网络路径
startPos设置起始播放位置（毫秒），默认值为 0
返回

◆ play()

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

播放媒体文件

open() 或 或 seek() 后，你可以调用该方法播放媒体文件。

返回

◆ pause()

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

暂停播放

如果你想恢复播放，请调用 play() 方法。

返回

◆ stop()

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

停止播放

返回

◆ seek()

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

从指定的位置播放媒体文件

成功调用该方法后，你会收到 onPlayerEvent 回调，报告当前播放器发生的事件，如定位开始、定位成功或定位失败。

参数
pos指定的位置（毫秒）
返回

◆ mute()

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

设置是否静音

参数
mute静音选项：
  • true: 静音
  • false: （默认）不静音
返回

◆ getMute()

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

获取当前的静音状态

参数
[out]mute静音状态：
  • true: 静音
  • false: 不静音
返回

◆ adjustPlayoutVolume()

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

调节本地播放音量

参数
volume本地播放音量，取值范围从 0 到 100：
  • 0: 无声
  • 100: （默认）媒体文件的原始播放音量
返回

◆ getPlayoutVolume()

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

获取当前本地播放音量

参数
[out]volume本地播放音量，取值范围从 0 到 100：
  • 0: 无声
  • 100: （默认）媒体文件的原始播放音量
返回

◆ getDuration()

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

获取媒体文件总时长

参数
[out]duration媒体文件总时长（毫秒）
返回

◆ getPlayPosition()

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

获取当前播放进度

参数
[out]pos播放进度（毫秒）
返回

◆ getStreamCount()

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

获取该媒体文件中媒体流的数量

参数
[out]count该媒体文件中媒体流的数量
返回

◆ getStreamInfo()

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

通过此条媒体流的索引值获取媒体流信息

参数
index媒体流索引值
[out]info媒体流的所有信息，详见 MediaStreamInfo
返回

◆ getState()

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

获取播放器当前状态

返回
播放器当前状态，详见 MEDIA_PLAYER_STATE

◆ setView()

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

设置播放器渲染视图

参数
view渲染视图，Windows 平台为窗口句柄（HWND）
返回

◆ setRenderMode()

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

设置播放器视图的渲染模式

参数
renderMode播放器视图的渲染模式：
  • RENDER_MODE_HIDDEN (1): 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
  • RENDER_MODE_FIT (2): 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
返回

◆ registerPlayerObserver()

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

注册一个观测器

一旦注册了播放器源观测器，你可以使用观察器来监控播放器的状态变化。

参数
observer观测器，报告播放中的事件，详见 IMediaPlayerObserver
返回

◆ unregisterPlayerObserver()

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

取消注册该播放观测器

参数
observer观测器，报告播放中的事件，详见 IMediaPlayerObserver
返回

◆ registerVideoFrameObserver()

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

注册视频观测器

参数
observer视频观测观测器，观测每帧视频的接收，详见 IVideoFrameObserver
返回

◆ unregisterVideoFrameObserver()

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

取消注册视频观测器

参数
observer视频观测器，详见 IVideoFrameObserver
返回

◆ registerAudioFrameObserver()

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

注册音频观测器

参数
observer音频观测器，观测每帧音频的接收，详见 IAudioFrameObserver
返回

◆ unregisterAudioFrameObserver()

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

取消注册音频观测器

参数
observer观测器，详见 IAudioFrameObserver
返回

◆ setLogFile()

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

设置日志文件

MediaPlayer Kit 运行时产生的 log 都写入日志文件，调用该方法可以设置日志文件的存储路径。 请确保你指定的日志文件路径存在且可写。如果不调用该方法，日志文件会存储至默认路径： "C:\Users\{user_name}\AppData\Local\Agora\{project_name}"。

注解
请在调用 initialize() 后立即调用该方法，否则日志文件中的 log 可能不完整。
参数
filePath日志文件的完整路径。该日志文件为 UTF-8 编码。
返回

◆ setLogFilter()

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

设置输出日志的过滤等级

设置 MediaPlayer Kit 的输出日志的过滤等级。过滤等级从低到高分别为 OFF，DEBUG，INFO，WARN，ERROR， CRITICAL。选择一个过滤等级，你就可以看到在该等级之前的所有等级的日志信息，详见 filter 参数描述。

参数
filter设置日志过滤等级：
  • LOG_FILTER_OFF (0): 不输出任何日志。
  • LOG_FILTER_DEBUG (0x80f): 输出所有的日志。
  • LOG_FILTER_INFO (0x0f): （推荐取值）输出 INFO，WARN，ERROR，CRITICAL 等级的日志。
  • LOG_FILTER_WARN (0x0e): 输出 WARN，ERROR，CRITICAL 等级的日志。
  • LOG_FILTER_ERROR (0x0c): 输出 ERROR，CRITICAL 等级的日志。
  • LOG_FILTER_CRITICAL (0x08): 输出 CRITICAL 等级的日志。
返回

◆ changePlaybackSpeed()

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

调节播放速度

请在 play() 后调用该方法。

参数
speed播放媒体资源的速度，详见 MEDIA_PLAYER_PLAYBACK_SPEED
返回

◆ selectAudioTrack()

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

设置使用的音轨

如果媒体资源含有多个音轨，你可以调用该方法设置你想使用的音轨。

参数
index音轨的索引值
返回

◆ setPlayerOption() [1/2]

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

设置 MediaPlayer Kit 私有选项

MediaPlayer Kit 支持通过 key 和 value 来设置私有选项。一般情况下，你无需知晓私有选项设置，使用 Player 默认的选项设置即可。

注解
请确保在 open 之后调用该方法。
参数
keykey 值
valuevalue 值
返回

◆ setPlayerOption() [2/2]

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

设置 MediaPlayer Kit 私有选项

MediaPlayer Kit 支持通过 key 和 value 来设置私有选项。一般情况下，你无需知晓私有选项设置，使用 Player 默认的选项设置即可。

注解
请确保在 open 之后调用该方法。
参数
keykey 值
value值
返回

◆ takeScreenshot()

virtual int agora::rtc::IMediaPlayer::takeScreenshot ( const char *  filename)
pure virtual

播放视频时屏幕截图

参数
filename屏幕截图文件的文件名
返回

◆ setExternalSubtitle()

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

设置外挂字幕

调用 open 方法成功打开媒体文件后，你可以调用本方法设置播放器显示外挂字幕。支持 SRT 和 ASS 类型的字幕。

参数
url外挂字幕的 URL 地址。支持本地地址和在线地址。
返回

◆ setLoopCount()

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

设置循环播放

如果你希望循环播放，请调用该方法并设置循环播放次数。

循环播放结束时，MediaPlayer Kit 会返回 PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED

参数
loopCount循环播放的次数
返回

◆ getPlayerSdkVersion()

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

获取 MediaPlayer Kit 版本号

返回
当前使用的 Player 的版本号，如 "1.2.1"

◆ switchSrc()

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

切换正在播放的媒体资源。

你可以根据当前网络状态调用该方法切换播放的媒体资源。例如，在网络较差时，将播放的媒体资源切换为较低码率的媒体资源地址；在网络较好时，将播放的媒体资源切换为较高码率的媒体资源地址。

调用 switchSrc 后，如果你收到 onPlayerEvent 回调报告事件 PLAYER_EVENT_SWITCH_COMPLETE，则切换成功；如果你收到 onPlayerEvent 回调报告事件 PLAYER_EVENT_SWITCH_ERROR，则切换失败。

注解
  • 请确保在 open 之后调用该方法。
  • 为保证播放正常，请在调用 switchSrc(src, true) 时注意如下：
    • 不要在播放暂停时调用该方法。
    • 不要在切换过程中调用 seek。
    • 确保切换前的播放位置不大于待切换的媒体资源总时长。
参数
src待切换的媒体资源 URL 地址，支持本地和 HTTP、RTMP 和 RTSP 协议的在线媒体流。
syncPts是否同步切换前后的播放位置（毫秒）：

  • true:（默认）同步切换前后的播放位置。MediaPlayer Kit 会在切换后，从切换时的播放位置开始播放媒体资源。

    Note: Agora 仅支持在播放点播流时，将 syncPts 设为 true。

  • false: 不同步切换前后的播放位置：
    • 如果媒体资源是点播流，MediaPlayer Kit 会在切换后，从头开始播放媒体资源。
    • 如果媒体资源是直播流，MediaPlayer Kit 会在切换后，从切换时的播放位置开始播放媒体资源。
返回

◆ addPreloadSrc()

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

预加载媒体资源。

你可以调用该方法将一个媒体资源预加载到播放列表中。如果需要预加载多个媒体资源，你可以多次调用该方法。

调用 addPreloadSrc 后，如果收到 onPreloadEvent 回调报告事件 PLAYER_PRELOAD_EVENT_COMPLETE，则预加载成功；如果你收到 onPreloadEvent 回调报告事件 PLAYER_PRELOAD_EVENT_ERROR，预加载失败。

预加载成功后，如果你想播放媒体资源，请调用 playPreload；如果你想清空播放列表，请调用 stop。

注解
Agora 不支持你预加载重复的媒体资源到播放列表，但支持你将正在播放的媒体资源再次预加载到播放列表。
参数
src预加载的媒体资源 URL 地址，支持本地和 HTTP、RTMP 和 RTSP 协议的在线媒体流。
startPos预加载到播放列表后，开始播放时的起始位置（毫秒）。预加载直播流时，将 startPos 设为 0。
返回

◆ playPreload()

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

播放预加载的媒体资源。

该方法仅支持播放已预加载到播放列表中的媒体资源。调用该方法后，如果你收到 onPlayerStateChanged 回调报告状态 PLAYER_STATE_PLAYING，播放成功。

如果你想更换播放的预加载媒体资源，你可以再次调用该方法并指定新的媒体资源路径。 如果你想重新播放媒体资源，你需要在播放前调用 addPreloadSrc 重新将该媒体资源预加载到播放列表。 如果你想清空播放列表，请调用 stop。

注解
如果你在播放暂停时调用该方法，该方法会在恢复播放后才生效。
参数
src播放列表中的媒体资源 URL 地址，必须与 addPreloadSrc 方法设置的 src 一致，否则无法播放。
返回

◆ release()

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

释放 IMediaPlayer 对象