本文提供Flutter播放器SDK常用功能的使用示例。
基础功能
创建播放器
本节介绍如何用更简单的方式让Flutter播放器SDK播放视频,按照播放方式的不同可以分为手动播放和自动播放。
如需播放ARTC流,除了需要在集成时引入RTS相关依赖,Android端还需在创建播放器前调用FlutterAliPlayerFactory.loadRtsLibrary();
加载RtsSDK动态库。
创建播放器。
创建单实例播放器。
FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer();
创建多实例播放器。
需要在Flutter层管理playerId,在播放器的回调中会返回对应的playerId,用来通知Flutter层。
FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer(playerId: playerId);
设置监听器。
播放器支持设置多个监听器。
创建手动播放时,
OnPrepard
必须设置,因为手动播放需要在OnPrepard
回调中调用play
开始播放。OnTrackReady
、OnError
较为重要,建议您设置。
以下示例仅展示部分接口,如下所示:
// 准备成功 fAliplayer.setOnPrepard((playerId) {}); // 首帧显示 fAliplayer.setOnRenderingStart((playerId) {}); // 视频宽高变化 fAliplayer.setOnVideoSizeChanged((width, height,playerId) {}); // 播放器状态变化 fAliplayer.setOnStateChanged((newState,playerId) {}); // 加载状态 fAliplayer.setOnLoadingStatusListener( loadingBegin: (playerId) {}, loadingProgress: (percent, netSpeed,playerId) {}, loadingEnd: (playerId) {}); // 拖动完成 fAliplayer.setOnSeekComplete((playerId) {}); // 播放器事件信息回调,包括buffer、当前播放进度等等信息,根据infoCode来判断,对应FlutterAvpdef.infoCode fAliplayer.setOnInfo((infoCode, extraValue, extraMsg,playerId) {}); // 播放完成 fAliplayer.setOnCompletion((playerId) {}); // 设置流准备完成 fAliplayer.setOnTrackReady((playerId) {}); // 截图结果 fAliplayer.setOnSnapShot((path,playerId) {}); // 错误结果 fAliplayer.setOnError((errorCode, errorExtra, errorMsg,playerId) {}); // 切换流变化 fAliplayer.setOnTrackChanged((value,playerId) {});
创建播放源。
Flutter播放器SDK支持4种点播播放方式,包括:UrlSource播放、VidAuth播放(视频点播用户推荐使用)、VidSts播放、加密播放。
Flutter播放器SDK仅支持1种直播播放方式,为UrlSource播放。
点播视频播放
点播UrlSource播放
使用点播UrlSource播放方式播放点播视频,需要将播放器的setUrl属性设置为播放地址。播放地址可以是第三方点播地址或阿里云点播服务中的播放地址。
阿里云播放地址可以调用GetPlayInfo接口获取。建议您通过SDK方式来获取音视频播放地址,免去自签名的麻烦。调用接口获取音视频播放地址的示例请参见开发者门户。
void onViewPlayerCreated(viewId) async { // 将渲染的View设置给播放器 fAliplayer.setPlayerView(viewId); // 设置播放源 switch (_playMode) { // UrlSource播放方式 case ModeType.URL: this.fAliplayer.setUrl("播放地址"); // 必选参数,播放地址,可以是第三方点播地址,或阿里云点播服务中的播放地址。 break; default: } }
点播VidAuth播放(推荐)
使用VidAuth播放方式播放点播视频,需要将播放器的vid属性设置为音视频ID,将playauth属性设置为音视频播放凭证。
音视频ID可以在音视频上传完成后通过控制台(路径:媒资库>音/视频。)或服务端接口(SearchMedia)获取。
音视频播放凭证可以调用GetVideoPlayAuth接口获取。建议您通过SDK方式来获取音视频播放凭证,免去自签名的麻烦。调用接口获取音视频播放凭证的示例请参见开发者门户。
推荐视频点播用户采用此播放方式。相比STS播放方式,PlayAuth播放方式在易用性和安全性上更有优势,对比详情请参见凭证方式与STS方式对比。
void onViewPlayerCreated(viewId) async { // 将渲染的View设置给播放器 fAliplayer.setPlayerView(viewId); // 设置播放源 switch (_playMode) { // VidAuth播放方式 case ModeType.AUTH: FlutterAliplayer.generatePlayerConfig().then((value) { this.fAliplayer.setVidAuth( vid: "Vid信息",// 必选参数,视频ID(VideoId)。 region: "接入地域",// 必选参数,点播服务的接入地域,默认为cn-shanghai。 playAuth: "<yourPlayAuth>",// 必选参数,播放凭证,需要调用点播服务的GetVideoPlayAuth接口生成。 playConfig: value); }); break; default: } }
点播VidSts播放
使用点播VidSts播放方式播放点播视频是指用STS临时凭证而非点播音视频播放凭证播放。STS安全令牌和STS临时AK对(AccessKeyId和AccessKeySecret)需要提前获取,获取方式请参见创建RAM角色并进行STS临时授权。
void onViewPlayerCreated(viewId) async { // 将渲染的View设置给播放器 fAliplayer.setPlayerView(viewId); // 设置播放源 switch (_playMode) { // VidSts播放方式 case ModeType.STS: FlutterAliplayer.generatePlayerConfig().then((value) { this.fAliplayer.setVidSts( vid: "Vid信息",// 必选参数,视频ID(VideoId)。 region: "接入地域",// 必选参数,点播服务的接入地域,默认为cn-shanghai。 accessKeyId: "<yourAccessKeyId>",// 必选参数,STS临时AK对的访问密钥ID,需要调用STS服务的AssumeRole接口生成。 accessKeySecret: "<yourAccessKeySecret>",// 必选参数,STS临时AK对的访问密钥,需要调用STS服务的AssumeRole接口生成。 securityToken: "<yourSecurityToken>",// 必选参数,STS安全令牌,需要调用STS服务的AssumeRole接口生成。 playConfig: value); }); break; default: } }
点播加密播放
点播视频支持HLS标准加密、阿里云私有加密和DRM加密。加密播放请参见播放加密视频。
直播视频UrlSource播放
使用UrlSource播放方式播放直播视频,需要将播放器的setUrl属性设置为直播拉流地址。播放地址可以是第三方直播地址或阿里云直播服务中的拉流地址。
阿里云直播拉流地址可以通过直播控制台的地址生成器生成。详情请参见阿里云直播地址生成器 。
void onViewPlayerCreated(viewId) async { // 将渲染的View设置给播放器 fAliplayer.setPlayerView(viewId); // 设置播放源 switch (_playMode) { // UrlSource播放方式 case ModeType.URL: this.fAliplayer.setUrl("填写资源的播放地址"); // 播放地址可以是第三方直播地址,或阿里云直播服务中的拉流地址。 break; default: } }
设置显示View。
如果播放源有画面,那么需要设置显示的view到播放器中,用来显示画面。示例如下:
@override Widget build(BuildContext context) { var x = 0.0; var y = 0.0; Orientation orientation = MediaQuery.of(context).orientation; var width = MediaQuery.of(context).size.width; var height; if (orientation == Orientation.portrait) { height = width * 9.0 / 16.0; } else { height = MediaQuery.of(context).size.height; } AliPlayerView aliPlayerView = AliPlayerView( onCreated: onViewPlayerCreated, x: x, y: y, width: width, height: height); return OrientationBuilder( builder: (BuildContext context, Orientation orientation) { return Scaffold( body: Column( children: [ Container( color: Colors.black, child: aliPlayerView, width: width, height: height), ], ), ); }, );
可选:开启自动播放,默认为关闭状态。
fAliplayer.setAutoPlay(true);
准备播放。
调用
prepare()
方法准备播放。fAliplayer.prepare();
开始播放。
如果未开启自动播放,需要在
OnPrepard
回调中调用fAliplayer.play();
开始播放视频。如果开启了自动播放,则不需要调用
fAliplayer.play();
,数据解析完成后将开始自动播放视频。
fAliplayer.play();
控制播放
Flutter播放器SDK支持开始、暂停、从指定时间点播放等主流操作。
开始播放
开始播放视频,由play
接口实现。示例如下:
fAliplayer.play();
从指定时间开始播放
跳转到某个时刻进行播放,由seek
接口实现。适用于用户拖拽进度条,或续播等需要从指定时间点开始播放的场景。示例如下:
// posotion为指定的时间,单位:毫秒。seekMode取值:FlutterAvpdef.ACCURATE(精准seek)和FlutterAvpdef.INACCURATE(非精准seek)
fAliplayer.seek(position,seekMode);
暂停播放
暂停播放视频,由pause
接口实现。示例如下:
fAliplayer.pause();
停止播放
停止播放视频,由stop
接口实现。示例如下:
fAliplayer.stop();
设置显示模式
Flutter播放器SDK支持填充、旋转、镜像等显示设置。
填充
支持设置宽高比适应、宽高比填充和拉伸填充这3种画面填充模式,由setScalingMode
接口实现。示例如下:
// 设置宽高比适应(将按照视频宽高比等比缩小到view内部,不会有画面变形)
fAliplayer.setScalingMode(FlutterAvpdef.AVP_SCALINGMODE_SCALEASPECTFIT);
// 设置宽高比填充(将按照视频宽高比等比放大,充满view,不会有画面变形)
fAliplayer.setScalingMode(FlutterAvpdef.AVP_SCALINGMODE_SCALEASPECTFILL);
// 设置拉伸填充(如果视频宽高比例与view比例不一致,会导致画面变形)
fAliplayer.setScalingMode(FlutterAvpdef.AVP_SCALINGMODE_SCALETOFILL);
旋转
画面按指定角度旋转,由setRotateMode
接口实现。设置后还可查询旋转角度。示例如下:
// 设置画面顺时针旋转0度
fAliplayer.setRotateMode(FlutterAvpdef.AVP_ROTATE_0);
// 设置画面顺时针旋转90度
fAliplayer.setRotateMode(FlutterAvpdef.AVP_ROTATE_90);
// 设置画面顺时针旋转180度
fAliplayer.setRotateMode(FlutterAvpdef.AVP_ROTATE_180);
// 设置画面顺时针旋转270度
fAliplayer.setRotateMode(FlutterAvpdef.AVP_ROTATE_270);
// 获取旋转角度
fAliplayer.getRotateMode();
镜像
支持水平镜像、垂直镜像和无镜像,由setMirrorMode
接口实现。示例如下:
// 设置无镜像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_NONE);
// 设置水平镜像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_HORIZONTAL);
// 设置垂直镜像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_VERTICAL);
获取播放信息
Flutter播放器SDK支持获取当前的播放进度和播放时长。
获取当前播放进度
获取当前的播放时刻,在onInfo回调中获取,单位毫秒。示例如下:
fAliplayer.setOnInfo((infoCode,extraValue,extraMsg,playerId){
if(infoCode==FlutterAvpdef.CURRENTPOSITION){
// extraValue为当前播放进度
}
});
获取播放时长
获取视频总时长。需要在视频加载完成以后才可以获取到,可以在AVPEventPrepareDone事件后获取duration。示例如下:
fAliplayer.getMediaInfo().then((value){
_videoDuration=value['duration'];
});
监听播放状态
监听播放器的状态,onStateChanged 回调参数为当前播放器状态。示例如下:
fAliplayer.setOnStateChanged((newState,playerId){
//newState为播放状态
switch(newState){
caseFlutterAvpdef.AVPStatus_AVPStatusIdle: // 空转、闲时、静态
break;
caseFlutterAvpdef.AVPStatus_AVPStatusInitialzed: // 初始化完成
break;
caseFlutterAvpdef.AVPStatus_AVPStatusPrepared: // 准备完成
break;
caseFlutterAvpdef.AVPStatus_AVPStatusStarted: // 正在播放
break;
caseFlutterAvpdef.AVPStatus_AVPStatusPaused: // 播放暂停
break;
caseFlutterAvpdef.AVPStatus_AVPStatusStopped: // 播放停止
break;
caseFlutterAvpdef.AVPStatus_AVPStatusCompletion: // 播放完成
break;
caseFlutterAvpdef.AVPStatus_AVPStatusError: // 播放错误
break;
default:
}
});
设置音量
设置音量包括音量调节和静音设置。
音量调节
调节音量大小,支持0~2倍,当音量大于1时,可能出现噪音,不推荐使用。由setVolume
接口实现。设置后还可获取音量信息。示例如下:
// volume的值为0~2之间的实数。
fAliPlayer.setVolume(1);
// 获取音量信息。
fAliPlayer.getVolume();
静音设置
将播放中的视频设置为静音状态,由setMute
接口实现。示例如下:
fAliplayer.setMute(true);
倍速播放
Flutter播放器SDK提供了倍速播放视频的功能,通过设置setRate
方法,能够以0.5倍~5倍速去播放视频。同时保持变声不变调。示例如下:
// 设置倍速播放:支持0.5~5倍速的播放,通常按0.5的倍数来设置,例如0.5倍、1倍、1.5倍等
fAliplayer.setRate(1.0);
多清晰度设置
如果使用VID方式(VidAuth(推荐)及VidSts)播放,无需额外设置。Flutter播放器SDK会从点播服务获取清晰度列表。Flutter播放器SDK支持获取和切换清晰度,UrlSource播放方式暂不支持此设置。
获取清晰度
当视频加载完成后,可以获取视频的清晰度。
fAliplayer.getMediaInfo().then((value){
AVPMediaInfoinfo=AVPMediaInfo.fromJson(value);
info.tracks.forEach((element){
if(element.trackType==3){
// 清晰度
Stringdefinition=element.trackDefinition;
// 流索引
intindex=element.trackIndex;
}
}
});
切换清晰度
通过selectTrack
方法切换清晰度,传递对应TrackInfo的index即可。
fAliplayer.selectTrack(trackIdx);
清晰度切换通知
清晰度切换成功回调。
fAliplayer.setOnTrackChanged((value,playerId){
// 有回调表示切换成功,切换失败接口暂未提供
});
循环播放
Flutter播放器SDK提供了循环播放视频的功能。调用setLoop
开启循环播放,播放完成后,将会自动从头开始播放视频。示例如下:
fAliplayer.setLoop(true);
同时循环开始的回调将会使用onInfo
通知。示例如下:
fAliplayer.setOnInfo((infoCode, extraValue, extraMsg, playerId) {
if(infoCode == FlutterAvpdef.LOOPINGSTART){
// 循环播放开始通知
}
});
进阶功能
短视频列表播放
创建列表播放器。
FlutterAliListPlayer fAliListPlayer = FlutterAliPlayerFactory.createAliListPlayer();
添加资源、移除资源。
列表播放器目前只支持两种播放方式:UrlSource播放和VidSts播放。
// uid是视频的唯一标志。用于区分视频是否一样。如果uid一样,则认为是一样的 fAliListPlayer.addUrlSource(url,uid); fAliListPlayer.addVidSource(vid,uid); fAliListPlayer.removeSource(uid);
设置预加载个数。
合理设置预加载个数,能够有效的提高起播的速度。示例如下:
// 设置预加载个数。总共加载的个数为: 1 + count*2。 fAliListPlayer.setPreloadCount(count);
播放视频源。
// uid为必填项,如果是URL播放方式,只需要uid即可,如果是STS方式,则需要填写STS信息 fAliListPlayer.moveTo();
软硬解切换
Flutter播放器SDK提供了H.264、H.265的硬解码能力,同时提供了setEnableHardwareDecoder
开关。默认开,并且在硬解初始化失败时,自动切换为软解,保证视频的正常播放。示例如下:
// 开启硬解,默认开启
fAliplayer.setEnableHardwareDecoder(enable);
网络自适应切换视频清晰度
Flutter播放器SDK支持多码率自适应HLS、DASH视频流。在prepare
成功之后,通过getMediaInfo
可以获取到各个码流的信息,即TrackInfo
。示例如下:
fAliplayer.getMediaInfo().then((value) {
// value为map,value['tracks']可以获取对应的TrackInfos 列表信息,可以参考Demo中AVPMediaInfo info = AVPMediaInfo.fromJson(value); 了解如何解析TrackInfo
});
在播放过程中,可以通过调用播放器的selectTrack
方法切换播放的码流,参数为TrackInfo
中的trackIndex
,切换的结果会在OnTrackChangedListener
监听之后会回调。
// 多码率切换
fAliplayer.selectTrack(index);
// 多码率切换并自适应
fAliplayer.selectTrack(-1);
截图
Flutter播放器SDK提供了对当前视频截图的功能,由setOnSnapShot
接口实现。
// 截图成功监听
fAliplayer.setOnSnapShot((path,playerId) {
});
// 截图,path为图片保存路径
fAliplayer.snapshot(path);
试看
Flutter播放器SDK通过配合点播服务配置,可以实现试看功能,VidAuth播放(推荐)和VidSts播放方式支持试看功能。如何配置和使用试看功能,请参见点播试看。
配置试看功能之后,通过setVidAuth
接口的previewTime
方法设置播放器的试看时长。示例如下:
// previewTime为试看时间,单位:秒
// VidAuth播放方式
fAliplayer.setVidAuth(
vid: "填写资源的vid",
region: "填写资源的region",
playAuth: "填写资源的region",
previewTime: "填写试看时间,单位:秒");
// VidSts播放方式
fAliplayer.setVidSts(
vid: "填写资源的vid",
region: "填写资源的region",
accessKeyId: "填写资源的鉴权id",
accessKeySecret: "填写资源的鉴权密钥",
securityToken: "填写资源的安全Token",
previewTime: "填写试看时间,单位:秒");
其他配置
Flutter播放器SDK的其他播放配置。需要在prepare()
方法之前设置给播放器。
var configMap = {
'mStartBufferDuration':_mStartBufferDurationController.text,// 起播缓冲区时长,单位:毫秒
'mHighBufferDuration':_mHighBufferDurationController.text,// 高缓冲时长,单位:毫秒
'mMaxBufferDuration':_mMaxBufferDurationController.text,// 最大缓冲区时长,单位:毫秒
'mMaxDelayTime': _mMaxDelayTimeController.text,// 直播最大延迟,单位:毫秒。注意:仅直播有效
'mNetworkTimeout': _mNetworkTimeoutController.text,// 网络超时时间,单位:毫秒
'mNetworkRetryCount':_mNetworkRetryCountController.text,// 网络超时重试次数,单位:毫秒
'mMaxProbeSize': _mMaxProbeSizeController.text,// 最大probe大小
'mReferrer': _mReferrerController.text,// 设置referrer
'mHttpProxy': _mHttpProxyController.text,// http代理
'mEnableSEI': mEnableSEI,// 是否启用SEI
'mClearFrameWhenStop': !mShowFrameWhenStop,// 停止后是否清空画面
'mDisableVideo': mDisableVideo,// 禁用Video
'mDisableAudio': mDisableAudio,// 禁用Audio
'mUserAgent':mUserAgent,// 设置UserAgent
};
// 应用配置
fAliplayer.setConfig(configMap);
性能
本地缓存
Flutter播放器SDK提供了本地缓存(边播边缓存)的功能,能够让用户重复播放视频时,达到省流量的目的。需要在prepare
之前给播放器配置setCacheConfig
即可实现此功能。示例如下:
var map = {
"mMaxSizeMB": _mMaxSizeMBController.text,// 缓存目录的最大占用空间
"mMaxDurationS": _mMaxDurationSController.text,// 设置能够缓存的单个文件的最大时长
"mDir": _mDirController.text,// 缓存目录
"mEnable": mEnableCacheConfig,// 是否开启缓存功能
};
fAliplayer.setCacheConfig(map);
视频下载
Flutter播放器SDK提供了点播服务视频的下载功能,允许用户通过阿里云播放器将视频缓存至本地观看。同时,提供了普通下载和安全下载两种下载方式。
普通下载
下载后的视频数据未经过阿里云加密,用户可以用第三方播放器播放。
安全下载
下载后的视频数据经过阿里云加密。第三方播放器无法播放,仅支持使用阿里云的播放器SDK进行播放。
使用说明
仅VidSts和VidAuth方式支持视频下载功能。
使用播放器的视频下载功能,需要在点播控制台开启并配置下载模式,详细操作请参见下载设置。
视频下载支持断点续传。
操作步骤
可选:配置安全下载的加密校验文件。仅安全下载需要配置,普通下载无需配置。
说明请确保配置的加密校验文件与App信息一致,否则会导致视频下载失败。
如果设置为安全下载方式,则需要将在点播控制台生成的密钥文件配置到播放器SDK中,用于视频下载和播放的解密验证,密钥文件的生成请参见安全下载。
配置一次即可,示例如下:
FlutterAliPlayerFactory.initService(byteData);
创建并设置下载器。
示例如下:
FlutterAliDownloader downloader = FlutterAliDownloader.init(); // 设置保存路径 downloader.setSaveDir(path)
开始下载。
调用了开始下载后,会自动设置监听,并将回调信息返回。示例如下:
// 1.prepare // 参数说明:type可选值为FlutterAvpdef.DOWNLOADTYPE_STS / FlutterAvpdef.DOWNLOADTYPE_AUTH 。当type为DOWNLOADTYPE_STS时候,必填参数为:{vid,accessKeyId,accessKeySecret,securityToken},当 type 为 DOWNLOADTYPE_AUTH 时,必须填参数为 {vid,playAuth} downloader.prepare(type, vid).then((value) { // value为map,对应Demo中的DownloadModel自定义下载类 DownloadModel downloadModel = DownloadModel.fromJson(value); // 2.selectItem,根据不同的trackInfo来确定需要下载哪个清晰度 List<TrackInfoModel> trackInfos = downloadModel.trackInfos; downloader.selectItem(vid,trackInfos[0].index); //3.start downloader.start(vid, trackInfos[0].index).listen((event) { // 说明:event可能会有多种信息,可参考FlutterAvpdef.EventChanneldef中的信息,以下为具体说明: if (event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_PROGRESS){ // 下载进度百分比信息,获取下载进度百分比:event[EventChanneldef.DOWNLOAD_PROGRESS] }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_PROCESS){ // 处理进度百分比信息,获取处理进度百分比:event[EventChanneldef.DOWNLOAD_PROCESS] }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_COMPLETION){ // 下载完成,可以通过 event['vid']、event['index'] 获取对应的vid和index用于判断是哪个视频下载完成,event['savePath'] 用于获取下载完成视频的本地路径 }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_ERROR){ // 下载失败,可以通过 event['vid']、event['index'] 获取对应的vid和index用于判断是哪个视频下载失败,event['errorCode']、event['errorMsg'] 可以获取对应的错误码,和错误信息 } }); });
停止下载。
示例如下:
downloader.stop(vid, index)
删除下载。
删除下载选项,如果删除成功,则下载的本地文件也会随之删除。示例如下:
downloader.delete(vid, index)
释放下载对象。
当某个下载对象不再使用时,使用
release
方法将其释放,防止内存泄漏。示例如下:downloader.release(vid, index)
视频加密播放
点播视频支持HLS标准加密、阿里云私有加密和DRM加密。加密播放请参见播放加密视频。
- 本页导读 (1)