内置媒体播放器
介绍内置媒体播放器相关的方法和回调。
你可以通过调用媒体播放器相关的 API 播放本地或在线媒体资源,或将媒体资源分享给频道内的远端用户观看或收听。
adjustPlayoutVolume
调节本地播放音量。
Future<void> adjustPlayoutVolume(int volume);
参数
- volume
- 本地播放音量,取值范围从 0 到 100:
- 0: 无声。
- 100: (默认)媒体文件的原始播放音量。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
adjustPublishSignalVolume
调节远端用户听到的音量。
Future<void> adjustPublishSignalVolume(int volume);
详情
连接到声网服务器后,你可以调用该方法,调节远端用户听到的媒体文件的音量。
参数
- volume
- 信号音量,取值范围从 0 到 400:
- 0: 无声。
- 100: (默认)媒体文件的原始音量。
- 400: 原始音量的四倍(自带溢出保护)。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
createMediaPlayer
destroyMediaPlayer
销毁媒体播放器。
Future<void> destroyMediaPlayer(MediaPlayer mediaPlayer);
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败
enableAutoRemoveCache
设置是否开启自动清除缓存文件功能。
Future<void> enableAutoRemoveCache(bool enable);
详情
开启自动清除缓存文件后,当播放器中缓存的媒体文件超过你设置的文件数量或总缓存大小的上限时,SDK 会自动清除近期最少使用的一个缓存文件。
参数
- enable
- 是否自动清除缓存文件:
true
:开启自动清除缓存文件功能。false
:(默认)关闭自动清除缓存文件功能。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0:方法调用失败,详见 MediaPlayerError。
getCacheDir
获取缓存文件的储存路径。
Future<String> getCacheDir(int length);
详情
如果你在调用该方法前未曾调用 setCacheDir 方法自定义缓存文件的储存路径,该方法返回的为 SDK 默认的缓存文件储存路径。
参数
- length
- 输入参数,缓存文件储存路径字符串的最大长度。
返回值
- 方法调用成功时,返回缓存文件的储存路径。
- < 0:方法调用失败,详见 MediaPlayerError。
getCacheFileCount
获取当前已缓存的媒体文件的总数量。
Future<int> getCacheFileCount();
返回值
- ≥ 0:方法调用成功,返回当前已缓存的媒体文件的总数量。
- < 0:方法调用失败,详见 MediaPlayerError。
getDuration
获取媒体文件总时长。
Future<int> getDuration();
返回值
媒体文件总时长(毫秒)。
getMaxCacheFileCount
获取所设置的缓存文件数量上限。
Future<int> getMaxCacheFileCount();
详情
SDK 默认的缓存文件数量上限为 1000。
返回值
- > 0:方法调用成功,返回缓存文件数量的上限。
- < 0:方法调用失败,详见 MediaPlayerError。
getMaxCacheFileSize
获取所设置的缓存文件总缓存的上限。
Future<int> getMaxCacheFileSize();
详情
SDK 默认的缓存文件总缓存上限为 1GB。你可以调用 setMaxCacheFileSize 方法自定义总缓存大小的上限。
返回值
- > 0:方法调用成功,返回缓存文件的总缓存上限,单位为字节。
- < 0:方法调用失败,详见 MediaPlayerError。
getMediaPlayerCacheManager
获取 MediaPlayerCacheManager 实例。
MediaPlayerCacheManager getMediaPlayerCacheManager()
详情
当你调用该方法后,SDK 会返回一个媒体播放器缓存管理器的实例。由于媒体播放器缓存管理器对象是单例模式,因此多次调用该方法将返回同一个实例。
请在初始化 RtcEngine 后调用该方法。
返回值
getMediaPlayerId
获取播放器 ID。
int getMediaPlayerId();
返回值
- 方法调用成功,返回播放器 ID。
- < 0: 方法调用失败。
getMute
获取当前播放的媒体文件是否静音。
Future<bool> getMute();
返回值
true
:当前播放的媒体文件为静音。false
:当前播放的媒体文件没有静音。
getPlayoutVolume
获取当前本地播放音量。
Future<int> getPlayoutVolume();
返回值
- 0: 无声。
- 100: (默认)媒体文件的原始播放音量。
getPlayPosition
getPlaySrc
获取播放的媒体资源的路径。
Future<String> getPlaySrc();
返回值
播放的媒体资源的路径。
getPublishSignalVolume
获取远端用户听到的音量。
Future<int> getPublishSignalVolume();
返回值
- ≥ 0: 播放文件的远端播放音量。
- < 0: 方法调用失败。
getState
getStreamCount
获取当前媒体文件中媒体流的数量。
Future<int> getStreamCount();
详情
返回值
- 方法调用成功,返回该媒体文件中媒体流的数量。
- < 0: 方法调用失败,详见 MediaPlayerError。
getStreamInfo
通过媒体流的索引值获取媒体流信息。
Future<PlayerStreamInfo> getStreamInfo(int index);
详情
参数
- index
- 媒体流索引值。
返回值
- 方法调用成功,返回媒体流信息,详见 PlayerStreamInfo。
- 方法调用失败,返回
NULL
。
initialize
创建一个 MediaPlayerController。
Future<void> initialize();
详情
- 该方法需要在初始化 RtcEngine 对象后调用。
- 请确保在调用其他 MediaPlayer 中的 API 前先调用该方法。
mute
设置是否静音。
Future<void> mute(bool muted);
参数
- muted
- 静音选项。
true
:静音。false
:(默认)不静音。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
open
打开媒体资源。
Future<void> open({required String url, required int startPos});
详情
该方法为异步调用。
如需播放媒体文件,请在收到 onPlayerSourceStateChanged 回调报告播放状态为 playerStateOpenCompleted 后再调用 play 方法播放媒体文件。
参数
- url
- 设置媒体文件的路径,支持本地和在线文件。
- startPos
- 设置起始播放位置(毫秒),默认值为 0。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
openWithMediaSource
打开媒体资源并进行播放设置。
Future<void> openWithMediaSource(MediaSource source);
详情
该方法支持你打开不同类型的媒体资源,包括自定义的媒体资源文件,并可进行播放设置。
参数
- source
- 媒体资源,详见 MediaSource。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0:方法调用失败。
pause
暂停播放。
Future<void> pause();
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
play
播放媒体文件。
Future<void> play();
详情
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
playPreloadedSrc
播放预加载的媒体资源。
Future<void> playPreloadedSrc(String src);
详情
调用 preloadSrc 方法将媒体资源预加载到播放列表后,可以调用该方法播放已预加载的媒体资源。调用该方法后,如果你收到 onPlayerSourceStateChanged 回调报告状态 playerStatePlaying,则表示播放成功。
如果你想更换播放的预加载媒体资源,你可以再次调用该方法并指定新的媒体资源路径。如果你想重新播放媒体资源,你需要在播放前调用 preloadSrc 重新将该媒体资源预加载到播放列表。如果你想清空播放列表,请调用 stop。
如果你在播放暂停时调用该方法,该方法会在恢复播放后才生效。
参数
- src
- 播放列表中的媒体资源 URL 地址,必须与 preloadSrc 方法设置的 src 一致,否则无法播放。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
preloadSrc
预加载媒体资源。
Future<void> preloadSrc({required String src, required int startPos});
详情
你可以调用该方法将一个媒体资源预加载到播放列表中。如果需要预加载多个媒体资源,你可以多次调用该方法。
预加载成功后,如果你想播放媒体资源,请调用 playPreloadedSrc;如果你想清空播放列表,请调用 stop。
SDK 不支持你预加载重复的媒体资源到播放列表,但支持你将正在播放的媒体资源再次预加载到播放列表。
参数
- src
- 媒体资源的网络路径。
- startPos
- 预加载到播放列表后,开始播放时的起始位置(毫秒)。预加载直播流时,将该参数设置为 0。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
registerAudioFrameObserver
注册音频帧观测器。
void registerAudioFrameObserver( {required AudioPcmFrameSink observer, RawAudioFrameOpModeType mode = RawAudioFrameOpModeType.rawAudioFrameOpModeReadOnly});
参数
- observer
-
音频帧观测器,观测每帧音频的接收,详见 AudioPcmFrameSink。
- mode
-
音频帧的使用模式,详见 RawAudioFrameOpModeType。
返回值
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
registerPlayerSourceObserver
注册一个播放观测器。
void registerPlayerSourceObserver(MediaPlayerSourceObserver observer);
参数
- observer
- 播放观测器,报告播放中的事件,详见 MediaPlayerSourceObserver。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
registerVideoFrameObserver
注册视频帧观测器。
void registerVideoFrameObserver(MediaPlayerVideoFrameObserver observer);
详情
你需要在该方法中实现一个 MediaPlayerVideoFrameObserver 类,并根据场景需要,注册该类的回调。成功注册视频帧观测器后,SDK 会在捕捉到每个视频帧时,触发你所注册的回调。
参数
- observer
- 视频帧观测器,观测每帧视频的接收。详见 MediaPlayerVideoFrameObserver。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
removeAllCaches
删除媒体播放器中所有已缓存的媒体文件。
Future<void> removeAllCaches();
详情
该方法不会删除正在播放中的已缓存媒体文件。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0:方法调用失败,详见 MediaPlayerError。
removeCacheByUri
删除指定的已缓存媒体文件。
uture<void> removeCacheByUri(String uri);
详情
该方法不会删除正在播放中的已缓存媒体文件。
参数
- uri
- 待删除的缓存文件的 URI(Uniform Resource Identifier),可用于标识媒体文件。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0:方法调用失败,详见 MediaPlayerError。
removeOldCache
删除媒体播放器中近期最少使用的一个缓存媒体文件。
Future<void> removeOldCache();
详情
缓存媒体文件占用过多空间时,你可以调用该方法清理缓存文件。调用该方法后,SDK 会删除最少使用的一个缓存媒体文件。
当你调用此方法删除缓存媒体文件时,当前正在播放的已缓存媒体文件不会被删除。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0:方法调用失败,详见 MediaPlayerError。
resume
暂停后恢复播放。
Future<void> resume();
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
seek
定位到媒体文件的指定播放位置。
Future<void> seek(int newPos);
详情
成功调用该方法后,你会收到 onPlayerEvent 回调,报告当前播放器发生的事件,如定位开始、定位成功或定位失败。
- 调用该方法定位。
- 定位完成后,调用 play 方法播放。
参数
- newPos
- 指定的位置(毫秒)。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
selectAudioTrack
指定当前音频文件的播放音轨。
Future<void> selectAudioTrack(int index);
详情
获取音频文件的音轨索引后,你可以调用该方法指定任一音轨进行播放。例如,如果一个多音轨文件的不同音轨存放了不同语言的歌曲,则你可以调用该方法设置播放语言。
参数
- index
- 音轨的索引值。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
setAudioDualMonoMode
设置当前音频文件的声道模式。
Future<void> setAudioDualMonoMode(AudioDualMonoMode mode);
详情
在双声道音频文件中,左声道和右声道可以存储不同的音频数据。根据实际需要,你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如,在 KTV 场景中,音频文件的左声道存储了伴奏,右声道存储了原唱的歌声。如果你只需听伴奏,调用该方法设置音频文件的声道模式为左声道模式;如果你需要同时听伴奏和原唱,调用该方法设置声道模式为混合模式。
- 你需要在调用 open 后调用该方法。
- 该方法仅适用于双声道的音频文件。
参数
- mode
- 声道模式。详见 AudioDualMonoMode。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败
setAudioPitch
调整当前播放的媒体资源的音调。
Future<void> setAudioPitch(int pitch);
详情
参数
- pitch
- 按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败
setCacheDir
设置待缓存的媒体文件的储存路径。
Future<void> setCacheDir(String path);
详情
该方法需在初始化 RtcEngine 之后调用。
参数
- path
- 缓存文件储存的绝对路径。请确保指定的目录存在且可写。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0:方法调用失败,详见 MediaPlayerError。
setLoopCount
设置循环播放。
Future<void> setLoopCount(int loopCount);
详情
如果你希望循环播放,请调用该方法并设置循环播放次数。
循环播放结束时,SDK 会触发 onPlayerSourceStateChanged 回调,向你报告播放状态为 playerStatePlaybackAllLoopsCompleted。
参数
- loopCount
- 循环播放的次数。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
setMaxCacheFileCount
设置缓存媒体文件数量的上限。
Future<void> setMaxCacheFileCount(int count);
参数
- count
- 可缓存的媒体文件数量的上限,默认值为 1000。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0:方法调用失败,详见 MediaPlayerError。
setMaxCacheFileSize
设置缓存媒体文件的总缓存大小的上限。
Future<void> setMaxCacheFileSize(int cacheSize);
参数
- cacheSize
- 缓存媒体文件的总缓存上限,单位为字节。默认为 1 GB。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0:方法调用失败,详见 MediaPlayerError。
setPlaybackSpeed
设置当前音频文件的播放速度。
Future<void> setPlaybackSpeed(int speed);
详情
你需要在 open 后调用该方法。
参数
- speed
- 播放速度。推荐取值范围为 [50,400],其中:
- 50: 0.5 倍速。
- 100: 原始速度。
- 400: 4 倍速。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
setRenderMode
设置播放器视图的渲染模式。
Future<void> setRenderMode(RenderModeType renderMode);
参数
- renderMode
-
播放器视图的渲染模式。详见 RenderModeType。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
setSpatialAudioParams
开启或关闭媒体播放器的空间音效。
Future<void> setSpatialAudioParams(SpatialAudioParams params);
详情
成功设置媒体播放器的空间音效参数后,SDK 会开启媒体播放器的空间音效,即本地用户听媒体资源会有空间感。
如果需关闭媒体播放器的空间音效,你需要将 params 参数设为空。
参数
- params
- 媒体播放器的空间音效参数。详见 SpatialAudioParams。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
setView
设置播放器渲染视图。
Future<void> setView(int view);
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
stop
停止播放。
Future<void> stop();
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
switchSrc
切换媒体资源。
Future<void> switchSrc({required String src, bool syncPts = true});
详情
- 在网络较差时,将播放的媒体资源切换为较低码率的媒体资源地址。
- 在网络较好时,将播放的媒体资源切换为较高码率的媒体资源地址。
调用该方法后,如果你收到 onPlayerEvent 回调报告事件 playerEventSwitchComplete,则媒体资源切换成功;如果你收到 onPlayerEvent 回调报告事件 playerEventSwitchError,则媒体资源切换失败。
参数
- src
- 媒体资源的网络路径。
- syncPts
- 是否同步切换前后的起始播放位置:
true
:同步。false
:(默认) 不同步。
如果媒体资源为直播流,你只能将该参数设置为
false
,否则 SDK 切换媒体资源会失败。如果媒体资源为点播流,你可以根据场景需求对该参数赋值。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
unloadSrc
释放预加载的媒体资源。
Future<void> unloadSrc(String src);
详情
该方法不支持释放当前播放的媒体资源。
参数
- src
- 媒体资源的网络路径。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
unregisterAudioFrameObserver [2/2]
取消注册音频帧观测器。
void unregisterAudioFrameObserver(AudioPcmFrameSink observer);
参数
- observer
- 音频帧观测器,详见 AudioPcmFrameSink。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
unregisterPlayerSourceObserver
取消注册播放观测器。
void unregisterPlayerSourceObserver(MediaPlayerSourceObserver observer);
参数
- observer
- 播放观测器,报告播放中的事件,详见 MediaPlayerSourceObserver。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
unregisterVideoFrameObserver [2/2]
取消注册视频帧观测器。
void unregisterVideoFrameObserver(MediaPlayerVideoFrameObserver observer);
参数
- observer
- 视频帧观测器,观测每帧视频的接收,详见 MediaPlayerVideoFrameObserver。
异常
方法成功调用时,无返回值;方法调用失败时,会抛出 AgoraRtcException 异常,你需要捕获异常并进行处理。
- < 0: 方法调用失败。
onAudioVolumeIndication
媒体播放器音量提示回调。
final void Function(int volume)? onAudioVolumeIndication;
SDK 每 200 毫秒触发一次该回调,报告媒体播放器当前的音量。
参数
- volume
- 播放器的当前音量,取值范围为 [0,255]。
onMetaData
报告已获取媒体附属信息。
final void Function(Uint8List data, int length)? onMetaData;
解析媒体附属信息后时,SDK 会触发该回调,报告媒体附属信息的数据类型和具体数据。
参数
- data
- 具体数据,用户自定义格式的数据。
- length
- 数据长度,单位为 byte。
onPlayBufferUpdated
报告当前缓冲数据能播放的时间。
final void Function(int playCachedBuffer)? onPlayBufferUpdated;
- 当缓冲数据支持的播放时间小于阈值(默认为 0)时,返回 playerEventBufferLow。
- 当缓冲数据支持的播放时间大于阈值(默认为 0)时,返回 playerEventBufferRecover。
参数
- playCachedBuffer
- 当前缓冲的数据能支持的播放时间 (毫秒)。
onPlayerEvent
报告播放器的事件。
final void Function( MediaPlayerEvent eventCode, int elapsedTime, String message)? onPlayerEvent;
- 调用 seek 定位播放后,SDK 会触发该回调,报告定位播放的结果。
参数
- eventCode
- 播放器事件,详见 MediaPlayerEvent。
- elapsedTime
- 发生事件的时间 (毫秒)。
- message
- 事件的信息。
onPlayerInfoUpdated
媒体播放器相关信息发生改变回调。
final void Function(PlayerUpdatedInfo info)? onPlayerInfoUpdated;
当媒体播放器相关信息发生改变时,SDK 会触发该回调。你可用其进行问题定位和排查。
参数
- info
- 媒体播放器相关信息。详见 PlayerUpdatedInfo。
onPlayerSourceStateChanged
报告播放器状态改变。
final void Function(MediaPlayerState state, MediaPlayerError ec)? onPlayerSourceStateChanged;
当播放器状态改变时,SDK 会触发该回调,报告新的播放状态。
参数
- state
- 新的播放状态,详见 MediaPlayerState。
- ec
- 播放器错误码,详见 MediaPlayerError。
onPlayerSrcInfoChanged
onPositionChanged
报告当前播放进度。
final void Function(int position)? onPositionChanged;
播放媒体文件时,SDK 每隔 1 秒会自动触发该回调,报告当前播放进度。
参数
- position
- 当前播放进度,单位为 ms。
onPreloadEvent
报告预加载媒体资源的事件。
final void Function(String src, PlayerPreloadEvent event)? onPreloadEvent;
参数
- src
- 媒体资源的路径。
- event
- 预加载媒体资源时发生的事件。详见 PlayerPreloadEvent。