IMediaPlayer
提供媒体播放器功能的类,支持多实例。
adjustPlayoutVolume
调节本地播放音量。
virtual int adjustPlayoutVolume(int volume) = 0;
参数
- volume
- 本地播放音量,取值范围从 0 到 100:
- 0: 无声。
- 100: (默认)媒体文件的原始播放音量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
adjustPublishSignalVolume
调节远端用户听到的音量。
virtual int adjustPublishSignalVolume(int volume) = 0;
连接到 Agora 服务器后,你可以调用该方法,调节远端用户听到的媒体文件的音量。
参数
- volume
- 信号音量,取值范围从 0 到 400:
- 0: 无声。
- 100: (默认)媒体文件的原始音量。
- 400: 原始音量的四倍(自带溢出保护)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAutoSwitchAgoraCDN
开启/关闭自动切换媒体资源的 CDN 线路。
virtual int enableAutoSwitchAgoraCDN(bool enable) = 0;
如果你想设置 SDK 根据网络情况自动切换媒体资源 CDN 线路,你可以调用该方法。
请在 openWithAgoraCDNSrc 前调用该方法。
参数
- enable
- 设置是否开启自动切换媒体资源的 CDN 线路:
true
:开启自动切换媒体资源的 CDN 线路。false
:(默认) 关闭自动切换媒体资源的 CDN 线路。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getAgoraCDNLineCount
获取媒体资源的 CDN 线路数量。
virtual int getAgoraCDNLineCount() = 0;
返回值
- > 0:方法调用成功,返回媒体资源的 CDN 线路数量。
- ≤ 0:方法调用失败。
getCurrentAgoraCDNIndex
获取当前使用的媒体资源的 CDN 线路索引。
virtual int getCurrentAgoraCDNIndex() = 0;
返回值
- ≥ 0: 方法调用成功,返回媒体资源的 CDN 线路索引。数值范围为 [0, getAgoraCDNLineCount
()
)。 - < 0: 方法调用失败。
getDuration
获取媒体文件总时长。
virtual int getDuration(int64_t& duration) = 0;
参数
- duration
- 输出参数。媒体文件总时长(毫秒)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getMediaPlayerCacheManager
获取 IMediaPlayerCacheManager 实例。
AGORA_API agora::rtc::IMediaPlayerCacheManager* AGORA_CALL getMediaPlayerCacheManager();
请在初始化 IRtcEngine 后调用该方法。
返回值
getMediaPlayerId
获取播放器 ID。
virtual int getMediaPlayerId() const = 0;
返回值
- 方法调用成功,返回播放器 ID。
- < 0: 方法调用失败。
getMute
获取当前播放的媒体文件是否静音。
virtual int getMute(bool& mute) = 0;
参数
- mute
- 输出参数。静音状态:
true
: 静音。false
: 不静音。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getPlayoutVolume
获取当前本地播放音量。
virtual int getPlayoutVolume(int& volume) = 0;
参数
- volume
- 输出参数。本地播放音量,取值范围从 0 到 100:
- 0: 无声。
- 100: (默认)媒体文件的原始播放音量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getPlayPosition
获取当前播放进度。
virtual int getPlayPosition(int64_t& pos) = 0;
参数
- pos
- 媒体资源文件当前的播放位置,单位为毫秒。
返回值
- 方法调用成功,返回当前播放进度(毫秒)。
- < 0: 方法调用失败,详见 MEDIA_PLAYER_ERROR。
getPublishSignalVolume
获取远端用户听到的音量。
virtual int getPublishSignalVolume(int& volume) = 0;
参数
- volume
- 输出参数。播放文件的远端播放音量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getState
获取播放器当前状态。
virtual media::base::MEDIA_PLAYER_STATE getState() = 0;
返回值
播放器当前状态,详见 MEDIA_PLAYER_STATE。
getStreamCount
获取当前媒体文件中媒体流的数量。
virtual int getStreamCount(int64_t& count) = 0;
参数
- count
- 输出参数。当前媒体文件中媒体流的数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败,详见 MEDIA_PLAYER_ERROR。
getStreamInfo
通过媒体流的索引值获取媒体流信息。
virtual int getStreamInfo(int64_t index, media::base::PlayerStreamInfo* info) = 0;
参数
- index
- 媒体流索引值。
- info
- 输出参数。媒体流的所有信息,详见 PlayerStreamInfo。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
mute
设置是否静音。
virtual int mute(bool mute) = 0;
参数
- mute
- 静音选项。
true
:静音。false
:(默认)不静音。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
open
打开媒体资源。
virtual int open(const char* url, int64_t startPos) = 0;
如果用户需要自定义播放线路,你可以调用 openWithAgoraCDNSrc。Agora 会通过自研调度中心支持调度线路,提升观看用户体验。如果用户不需要自定义播放线路,你可以调用 open。
该方法为异步调用。
如需播放媒体文件,请在收到 onPlayerSourceStateChanged 回调报告播放状态为 PLAYER_STATE_OPEN_COMPLETED 后再调用 play 方法播放媒体文件。
参数
- url
- 设置媒体文件的路径,支持本地和在线文件。
- startPos
- 设置起始播放位置(毫秒),默认值为 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
openWithAgoraCDNSrc
打开媒体资源,并通过自研调度中心请求媒体资源的所有 CDN 线路。
virtual int openWithAgoraCDNSrc(const char* src, int64_t startPos) = 0;
该方法为异步调用。
如需播放媒体文件,请在收到 onPlayerSourceStateChanged 回调报告播放状态为 PLAYER_STATE_OPEN_COMPLETED 后再调用 play 方法播放媒体文件。
调用该方法后,Agora 会打开媒体资源并通过自研调度中心请求媒体资源的所有 CDN 线路。Agora 默认使用第一个线路,你也可以通过 switchAgoraCDNLineByIndex 自行切换线路。
query parameter
以更新媒体资源的网路路径。例如:
- 媒体资源网络路径为
rtmp://$domain/$appName/$streamName
- 通过鉴权信息更新过的媒体资源网络路径为
rtmp://$domain/$appName/$streamName?ts=$ts&sign=$sign
- sign : 通过
authKey
+appName
+streamName
+ts
进行 md5 算法加密得出的鉴权字段。你需要联系技术支持咨询你的authKey
字段内容。 - ts : 鉴权过期时间。你可以指定再过多久鉴权过期。例如,
24h
或1h30m20s
。
参数
- src
- 媒体资源的网络路径。
- startPos
- 设置起始播放位置 (毫秒),默认值为 0。如果媒体资源为直播流,则无需赋值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
openWithCustomSource
打开自定义媒体资源文件。
virtual int openWithCustomSource(int64_t startPos, IMediaPlayerCustomDataProvider* provider) = 0;
- 弃用:
- 该方法已废弃,请改用 openWithMediaSource。
该方法支持你打开自定义的媒体资源文件。例如,你可以调用该方法打开已加密的媒体资源。
参数
- startPos
- 设置起始播放位置(毫秒),默认值为 0。
- provider
- 自定义媒体资源文件的回调。详见 IMediaPlayerCustomDataProvider。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
openWithMediaSource
打开媒体资源并进行播放设置。
virtual int openWithMediaSource(const media::base::MediaSource &source) = 0;
该方法支持你打开不同类型的媒体资源,包括自定义的媒体资源文件,并可进行播放设置。
参数
- source
- 媒体资源,详见 MediaSource。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pause
暂停播放。
virtual int pause() = 0;
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
play
playPreloadedSrc
播放预加载的媒体资源。
virtual int playPreloadedSrc(const char* src) = 0;
调用 preloadSrc 方法将媒体资源预加载到播放列表后,可以调用该方法播放已预加载的媒体资源。调用该方法后,如果你收到 onPlayerSourceStateChanged 回调报告状态 PLAYER_STATE_PLAYING,则表示播放成功。
如果你想更换播放的预加载媒体资源,你可以再次调用该方法并指定新的媒体资源路径。如果你想重新播放媒体资源,你需要在播放前调用 preloadSrc 重新将该媒体资源预加载到播放列表。如果你想清空播放列表,请调用 stop。
如果你在播放暂停时调用该方法,该方法会在恢复播放后才生效。
参数
- src
- 播放列表中的媒体资源 URL 地址,必须与 preloadSrc 方法设置的 src 一致,否则无法播放。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
preloadSrc
预加载媒体资源。
virtual int preloadSrc(const char* src, int64_t startPos) = 0;
你可以调用该方法将一个媒体资源预加载到播放列表中。如果需要预加载多个媒体资源,你可以多次调用该方法。
调用该方法后,如果收到 onPreloadEvent 回调报告事件 PLAYER_PRELOAD_EVENT_COMPLETE,则预加载成功;如果你收到 onPreloadEvent 回调报告事件 PLAYER_PRELOAD_EVENT_ERROR,则预加载失败。
预加载成功后,如果你想播放媒体资源,请调用 playPreloadedSrc;如果你想清空播放列表,请调用 stop。
Agora 不支持你预加载重复的媒体资源到播放列表,但支持你将正在播放的媒体资源再次预加载到播放列表。
参数
- src
- 媒体资源的网络路径。
- startPos
- 预加载到播放列表后,开始播放时的起始位置(毫秒)。预加载直播流时,将该参数设置为 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerAudioFrameObserver [1/2]
注册音频帧观测器。
virtual int registerAudioFrameObserver(media::base::IAudioFrameObserver* observer) = 0;
你需要在该方法中实现一个 IAudioFrameObserver 类,并根据场景需要,注册该类的回调。成功注册音频帧观测器后,SDK 会在捕捉到每个音频帧时,触发你所注册的回调。
参数
- observer
- 音频帧观测器,观测每帧音频的接收,详见 IAudioFrameObserver。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerAudioFrameObserver [2/2]
注册音频帧观测器。
virtual int registerAudioFrameObserver(media::base::IAudioFrameObserver observer, RAW_AUDIO_FRAME_OP_MODE_TYPE mode) = 0;
参数
- observer
-
音频帧观测器,观测每帧音频的接收,详见 IAudioFrameObserver。
- mode
-
音频帧的使用模式,详见 RAW_AUDIO_FRAME_OP_MODE_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerPlayerSourceObserver
注册一个播放观测器。
virtual int registerPlayerSourceObserver(IMediaPlayerSourceObserver* observer) = 0;
参数
- observer
- 播放观测器,报告播放中的事件,详见 IMediaPlayerSourceObserver。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerVideoFrameObserver
注册视频帧观测器。
virtual int registerVideoFrameObserver(media::base::IVideoFrameObserver* observer) = 0;
你需要在该方法中实现一个 IVideoFrameObserver 类,并根据场景需要,注册该类的回调。成功注册视频帧观测器后,SDK 会在捕捉到每个视频帧时,触发你所注册的回调。
参数
- observer
- 视频帧观测器,观测每帧视频的接收。详见 IVideoFrameObserver。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
renewAgoraCDNSrcToken
更新媒体资源网络路径的鉴权信息。
virtual int renewAgoraCDNSrcToken(const char* token, int64_t ts) = 0;
当鉴权信息过期(超出 ts 时间)时,你可以调用 openWithAgoraCDNSrc 或 switchAgoraCDNSrc 重新打开或切换媒体资源,并传入带新鉴权信息(如更新 ts 字段内容)的媒体资源网络路径。
如果你在切换媒体资源线路 (switchAgoraCDNLineByIndex) 时遇到鉴权信息过期,你需要调用该方法并传入新的鉴权信息,以更新该媒体资源网络路径的鉴权信息。更新鉴权信息后,你还需调用 switchAgoraCDNLineByIndex 才能完成线路切换。
为避免鉴权信息频繁过期,请务必根据场景需求设置合适的 ts 字段内容或联系技术支持。
参数
- token
- 鉴权字段。即鉴权信息中的 sign 字段。
- ts
- 鉴权过期时间。即鉴权信息中的 ts 字段。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
resume
暂停后恢复播放。
virtual int resume() = 0;
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
seek
定位到媒体文件的指定播放位置。
virtual int seek(int64_t newPos) = 0;
成功调用该方法后,你会收到 onPlayerEvent 回调,报告当前播放器发生的事件,如定位开始、定位成功或定位失败。
- 调用该方法定位。
- 定位完成后,调用 play 方法播放。
参数
- newPos
- 指定的位置(毫秒)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
selectAudioTrack
指定当前音频文件的播放音轨。
virtual int selectAudioTrack(int index) = 0;
获取音频文件的音轨索引后,你可以调用该方法指定任一音轨进行播放。例如,如果一个多音轨文件的不同音轨存放了不同语言的歌曲,则你可以调用该方法设置播放语言。
参数
- index
- 音轨的索引值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioPitch
调整当前播放的媒体资源的音调。
virtual int setAudioPitch(int pitch) = 0;
参数
- pitch
- 按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioDualMonoMode
设置当前音频文件的声道模式。
virtual int setAudioDualMonoMode(agora::media::base::AUDIO_DUAL_MONO_MODE mode) = 0;
在双声道音频文件中,左声道和右声道可以存储不同的音频数据。根据实际需要,你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如,在 KTV 场景中,音频文件的左声道存储了伴奏,右声道存储了原唱的歌声。如果你只需听伴奏,调用该方法设置音频文件的声道模式为左声道模式;如果你需要同时听伴奏和原唱,调用该方法设置声道模式为混合模式。
- 你需要在调用 open 后调用该方法。
- 该方法仅适用于双声道的音频文件。
参数
- mode
- 声道模式。详见 AUDIO_DUAL_MONO_MODE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLoopCount
设置循环播放。
virtual int setLoopCount(int loopCount) = 0;
如果你希望循环播放,请调用该方法并设置循环播放次数。
循环播放结束时,SDK 会触发 onPlayerSourceStateChanged 回调,向你报告播放状态为 PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED。
参数
- loopCount
- 循环播放的次数。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setPlaybackSpeed
设置当前音频文件的播放速度。
virtual int setPlaybackSpeed(int speed) = 0;
你需要在 open 后调用该方法。
参数
- speed
- 播放速度。推荐取值范围为 [50,400],其中:
- 50: 0.5 倍速。
- 100: 原始速度。
- 400: 4 倍速。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setPlayerOption
设置媒体播放器的私有选项。
virtual int setPlayerOption(const char* key, int value) = 0;
媒体播放器支持通过 key 和 value 来设置私有选项。 一般情况下,你无需知晓私有选项设置,使用媒体播放器默认的选项设置即可。
- 请确保在 open 之前调用该方法。
- 如果你使用客户端旁路推流功能,且在推流过程中发送 SEI 信息,你需要调用 setPlayerOption
("sei_data_with_uuid", 1)
方法,否则会导致 SEI 信息的丢失。
参数
- key
- key 值。
- value
- value 值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRenderMode
设置播放器视图的渲染模式。
virtual int setRenderMode(media::base::RENDER_MODE_TYPE renderMode) = 0;
参数
- renderMode
-
播放器视图的渲染模式。详见 RENDER_MODE_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setView
设置播放器渲染视图。
virtual int setView(media::base::view_t view) = 0;
参数
- view
- 渲染视图。Windows 平台为窗口句柄(HWND)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stop
停止播放。
virtual int stop() = 0;
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
switchAgoraCDNLineByIndex
切换媒体资源的 CDN 线路。
virtual int switchAgoraCDNLineByIndex(int index) = 0;
- 请在 openWithAgoraCDNSrc 后调用该方法。
- 该方法在 play 前后均可调用。如果你在 play 前调用该方法,切换不会立即生效。SDK 会等待播放完成后再切换媒体资源的 CDN 线路。
参数
- index
- CDN 线路索引。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
switchAgoraCDNSrc
切换媒体资源。
virtual int switchAgoraCDNSrc(const char* src, bool syncPts = false) = 0;
如果用户需要自定义播放线路,你可以调用该方法实现媒体资源切换。Agora 会通过自研调度中心支持调度线路,提升观看用户体验。如果用户不需要自定义播放线路,你可以调用 switchSrc 实现媒体资源切换。
- 请在 openWithAgoraCDNSrc 后调用该方法。
- 该方法在 play 前后均可调用。如果你在 play 前调用该方法,SDK 会等你调用 play 后再完成线路切换。
query parameter
以更新媒体资源的网路路径。例如:
- 媒体资源网络路径为
rtmp://$domain/$appName/$streamName
- 通过鉴权信息更新过的媒体资源网络路径为
rtmp://$domain/$appName/$streamName?ts=$ts&sign=$sign
- sign : 通过
authKey
+appName
+streamName
+ts
进行 md5 算法加密得出的鉴权字段。你需要联系技术支持咨询你的authKey
字段内容。 - ts : 鉴权过期时间。你可以指定再过多久鉴权过期。例如,
24h
或1h30m20s
。
参数
- src
- 媒体资源的网络路径。
- syncPts
- 是否同步切换前后的起始播放位置:
true
:同步。false
:(默认) 不同步。
如果媒体资源为直播流,你只能将该参数设置为
false
,否则 SDK 切换媒体资源会失败。如果媒体资源为点播流,你可以根据场景需求对该参数赋值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
switchSrc
切换媒体资源。
virtual int switchSrc(const char* src, bool syncPts) = 0;
- 在网络较差时,将播放的媒体资源切换为较低码率的媒体资源地址。
- 在网络较好时,将播放的媒体资源切换为较高码率的媒体资源地址。
调用该方法后,如果你收到 onPlayerEvent 回调报告事件 PLAYER_EVENT_SWITCH_COMPLETE,则媒体资源切换成功;如果你收到 onPlayerEvent 回调报告事件 PLAYER_EVENT_SWITCH_ERROR,则媒体资源切换失败。
如果用户需要自定义播放线路,你可以调用 switchAgoraCDNSrc 实现媒体资源切换。Agora 会通过自研调度中心支持调度线路,提升观看用户体验。如果用户不需要自定义播放线路,你可以调用 switchSrc 实现媒体资源切换。
参数
- src
- 媒体资源的网络路径。
- syncPts
- 是否同步切换前后的起始播放位置:
true
:同步。false
:(默认) 不同步。
如果媒体资源为直播流,你只能将该参数设置为
false
,否则 SDK 切换媒体资源会失败。如果媒体资源为点播流,你可以根据场景需求对该参数赋值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unloadSrc
释放预加载的媒体资源。
virtual int unloadSrc(const char* src) = 0;
该方法不支持释放当前播放的媒体资源。
参数
- src
- 媒体资源的网络路径。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unregisterAudioFrameObserver
取消注册音频帧观测器 。
virtual int unregisterAudioFrameObserver(media::base::IAudioFrameObserver* observer) = 0;
参数
- observer
- 音频帧观测器,详见 IAudioFrameObserver。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unregisterPlayerSourceObserver
取消注册播放观测器。
virtual int unregisterPlayerSourceObserver(IMediaPlayerSourceObserver* observer) = 0;
参数
- observer
- 播放观测器,报告播放中的事件,详见 IMediaPlayerSourceObserver。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unregisterVideoFrameObserver
取消注册视频帧观测器。
virtual int unregisterVideoFrameObserver(agora::media::base::IVideoFrameObserver* observer) = 0;
参数
- observer
- 视频帧观测器,观测每帧视频的接收,详见 IVideoFrameObserver。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。