SDK 下载
阅读对象
通过本文您可以学会
如何集成腾讯云视立方 Flutter播放器SDK。
如何使用播放器组件进行点播播放。
播放器组件简介
Flutter 播放器组件是基于 flutter 播放器 SDK 的扩展,播放器组件对于点播播放器,集成了更多的功能,包括全屏切换、清晰度切换、
进度条、播放控制、封面标题展示等常用功能,并且相对于点播播放器使用起来更加方便,如果想更加方便快捷的集成 flutter 视频播放能力,可以选择 flutter 播放器组件使用。
支持功能列表:
全屏播放
播放过程中屏幕旋转自适应
自定义视频封面
清晰度切换
声音和亮度调节
倍速播放
硬件加速开启\\关闭
画中画(PIP)(支持 Android 和 iOS 平台)
雪碧图和关键帧打点信息
更多功能正在逐步开发中......
集成指引
1. 将项目中
superplayer_widget
目录复制到自己的 flutter 工程下2. 在自己项目的配置文件
pubspec.yaml
下添加依赖superplayer_widget:# 该路径根据superplayer_widget存放路径改变path: ../superplayer_widget
3. 在需要使用到的页面,导入
superplayer_widget
的依赖包,如下所示:import 'package:superplayer_widget/demo_superplayer_lib.dart';
SDK 集成
步骤1:申请视频播放能力 License 和集成
String licenceURL = ""; // 获取到的 licence URLString licenceKey = ""; // 获取到的 licence keySuperPlayerPlugin.setGlobalLicense(licenceURL, licenceKey);
步骤2:创建 controller
SuperPlayerController _controller = SuperPlayerController(context);
步骤3:配置播放器
FTXVodPlayConfig config = FTXVodPlayConfig();// 如果不配置preferredResolution,则在播放多码率视频的时候优先播放720 * 1280分辨率的码率config.preferredResolution = 720 * 1280;_controller.setPlayConfig(config);
FTXVodPlayConfig 中的详细配置可参考 flutter 点播播放器的配置播放器接口。
步骤4:设置监听事件
_controller.onSimplePlayerEventBroadcast.listen((event) {String evtName = event["event"];if (evtName == SuperPlayerViewEvent.onStartFullScreenPlay) {setState(() {_isFullScreen = true;});} else if (evtName == SuperPlayerViewEvent.onStopFullScreenPlay) {setState(() {_isFullScreen = false;});} else {print(evtName);}});
步骤5:添加布局
Widget _getPlayArea() {return Container(height: 220,child: SuperPlayerView(_controller),);}
步骤6:添加返回事件监听
添加返回事件监听,确保用户在触发返回事件的时候,如果播放器处于全屏等状态,可以优先退出全屏,再次触发才会退出页面。
如果全屏播放状态下需要直接退出页面,可以不实现该监听。
@overrideWidget build(BuildContext context) {return WillPopScope(child: Container(decoration: BoxDecoration(image: DecorationImage(image: AssetImage("images/ic_new_vod_bg.png"),fit: BoxFit.cover,)),child: Scaffold(backgroundColor: Colors.transparent,appBar: _isFullScreen? null: AppBar(backgroundColor: Colors.transparent,title: const Text('SuperPlayer'),),body: SafeArea(child: Builder(builder: (context) => getBody(),),),),),onWillPop: onWillPop);}Future<bool> onWillPop() async {return !_controller.onBackPress();}
步骤7:启动播放
SuperPlayerModel model = SuperPlayerModel();model.videoURL = "http://1400329073.vod2.myqcloud.com/d62d88a7vodtranscq1400329073/59c68fe75285890800381567412/adp.10.m3u8";_controller.playWithModelNeedLicence(model);
SuperPlayerModel model = SuperPlayerModel();model.appId = 1500005830;model.videoId = new SuperPlayerVideoId();model.videoId.fileId = "8602268011437356984";// psign 即播放器组件签名,签名介绍和生成方式参见链接:https://cloud.tencent.com/document/product/266/42436model.videoId.pSign = "psignXXX" // 通过fileId播放必须填写_controller.playWithModelNeedLicence(model);
通过 FileId 方式播放,播放器会向后台请求真实的播放地址。如果此时网络异常或 FileId 不存在,则会收到 SuperPlayerViewEvent.onSuperPlayerError 事件。
步骤8:结束播放
结束播放时记得调用 controller 的销毁方法,尤其是在下次 startVodPlay 之前,否则可能会产生大量的内存泄露以及闪屏问题。也确保在退出页面的时候,能够结束视频播放。
@overridevoid dispose() {// must invoke when page exit._controller.releasePlayer();super.dispose();}
播放器组件接口列表
1、视频播放
注意:
10.7版本开始,startPlay 变更为 startVodPlay,需要通过 {@link SuperPlayerPlugin#setGlobalLicense} 设置 Licence 后方可成功播放, 否则将播放失败(黑屏),全局仅设置一次即可。直播 Licence、短视频 Licence 和视频播放 Licence 均可使用,若您暂未获取上述 Licence ,可 快速免费申请测试版 Licence 以正常播放,正式版 License 需 购买。
说明:开始播放视频.
接口
_controller.playWithModelNeedLicence(model);
参数说明:
SuperPlayerModel
参数名 | 类型 | 描述 |
appId | int | 应用 appId。FileId播放必填。 |
videoURL | String | 视频 URL,URL 播放必填。 |
multiVideoURLs | List<String> | 多码率 URL,多码率 URL 播放必填。 |
defaultPlayIndex | int | 默认播放码率序号,配合 multiVideoURLs 使用。 |
videoId | SuperPlayerVideoId | fileId 存储对象,以下会有详细介绍。 |
title | String | 视频标题,用户可设置该字段来自定义标题,从而覆盖播放器内部从服务器请求的标题。 |
coverUrl | String | 从腾讯服务器拉取的封面图片,该值会在 SuperVodDataLoader 中被自动赋值。 |
customeCoverUrl | String | 自定义视频封面,该字段会被优先判断,可以通过定义该参数来实现自定义封面。 |
duration | int | 视频时长,单位 秒。 |
videoDescription | String | 视频描述。 |
videoMoreDescription | String | 视频详细描述。 |
playAction | int | action 包括 PLAY_ACTION_AUTO_PLAY、PLAY_ACTION_MANUAL_PLAY 和 PLAY_ACTION_PRELOAD,以下对参数含义会有详细介绍。 |
SuperPlayerVideoId
参数名 | 类型 | 描述 |
fileId | String | 文件id。必填。 |
psign | String | v4 开启防盗链必填。 |
playAction
PLAY_ACTION_AUTO_PLAY:调用 playWithModel 之后,会自动开始播放视频。
PLAY_ACTION_MANUAL_PLAY:调用 playWithModel 之后,需要手动播放,并且播放器实质上并未加载视频,只会显示封面图,相对于 PLAY_ACTION_PRELOAD 没有任何视频播放资源消耗。
PLAY_ACTION_PRELOAD:调用 playWithModel 之后,会显示封面图,不会开始播放视频,不过播放器实质上已经加载了视频,相对于 PLAY_ACTION_MANUAL_PLAY,起播速度会更快。
2、暂停播放
说明:暂停播放视频
接口
_controller.pause();
3、继续播放
说明:继续播放视频
接口
_controller.resume();
4、重新开始播放
说明:重新开始播放视频
接口
_controller.reStart();
5、重置播放器
说明:重置播放器状态,并停止播放视频
接口
_controller.resetPlayer();
6、释放播放器
说明:释放播放器资源,并停止播放,调用该方法之后,controller 将不可再复用
接口
_controller.releasePlayer();
7、播放器返回事件
说明:触发播放器返回事件,该方法主要用于全屏播放模式下的返回判断和处理,返回 true:执行了退出全屏等操作,消耗了返回事件,false:未消耗事件。
接口
_controller.onBackPress();
8、切换清晰度
说明:实时切换当前正在播放的视频的清晰度
接口
_controller.switchStream(videoQuality);
参数说明
videoQuality 在开始播放之后,一般可通过 _controller.currentQualiyList 和 _controller.currentQuality 来获取,前者为清晰度列表,后者为默认清晰度。清晰度切换能力在播放器组件中已经集成,切换到全屏之后可点击右下角清晰度进行切换。
参数名 | 类型 | 描述 |
index | int | 清晰度序号。 |
bitrate | int | 清晰度码率。 |
width | int | 该清晰度下视频的宽度。 |
height | int | 该清晰度下视频的高度。 |
name | String | 清晰度简称。 |
title | String | 用于显示的清晰度名称。 |
URL | String | 非必填,清晰度 URL,用于多码率下的清晰度 URL。 |
9、调整进度(seek)
说明:调整当前视频的播放进度
接口
_controller.seek(progress);
参数说明
参数名 | 类型 | 描述 |
progress | double | 需要调整到的时间,单位 秒。 |
10、配置播放器组件
说明:配置播放器组件
接口
_controller.setPlayConfig(config);
参数说明
参数名 | 类型 | 描述 |
connectRetryCount | int | 播放器重连次数,当 SDK 与服务器异常断开连接时,SDK 会尝试与服务器重连,通过该值设置 SDK 重连次数。 |
connectRetryInterval | int | 播放器重连间隔,当 SDK 与服务器异常断开连接时,SDK 会尝试与服务器重连,通过该值设置两次重连间隔时间。 |
timeout | int | 播放器连接超时时间。 |
playerType | int | 播放器类型 : 0 点播 1 直播 2 直播回看 |
headers | Map | 自定义 http headers。 |
enableAccurateSeek | bool | 是否精确 seek,默认 true。 |
autoRotate | bool | 播放 MP4 文件时,若设为 true 则根据文件中的旋转角度自动旋转。旋转角度可在 PLAY_EVT_CHANGE_ROTATION 事件中获得。默认 true。 |
smoothSwitchBitrate | bool | 平滑切换多码率 HLS,默认 false。 设为 false 时,可提高多码率地址打开速度。 设为 true,在 IDR 对齐时可平滑切换码率。 |
cacheMp4ExtName | String | 缓存 MP4 文件扩展名,默认 MP4。 |
progressInterval | int | 设置进度回调间隔,若不设置,SDK 默认间隔0.5秒回调一次,单位毫秒。 |
maxBufferSize | int | 最大播放缓冲大小,单位:MB。此设置会影响 playableDuration,设置越大,提前缓存的越多。 |
maxPreloadSize | int | 预加载最大缓冲大小,单位:MB。 |
firstStartPlayBufferTime | int | 首缓需要加载的数据时长,单位:ms,默认值为100ms。 |
nextStartPlayBufferTime | int | 缓冲时(缓冲数据不够引起的二次缓冲,或者 seek 引起的拖动缓冲)最少要缓存多长的数据才能结束缓冲,单位:ms,默认值为250ms。 |
overlayKey | String | HLS 安全加固加解密 key。 |
overlayIv | String | HLS 安全加固加解密 Iv。 |
extInfoMap | Map | 一些不必周知的特殊配置。 |
enableRenderProcess | bool | 是否允许加载后渲染后处理服务,默认开启,开启后超分插件如果存在,默认加载。 |
preferredResolution | int | 优先播放的分辨率,preferredResolution = width * height。 |
11、开关硬解
说明:开启或关闭硬解播放能力
接口
_controller.enableHardwareDecode(enable);
12、获得播放状态
说明:获得当前播放器的播放状态
接口
SuperPlayerState superPlayerState = _controller.getPlayerState();
参数说明
参数名 | 类型 | 描述 |
INIT | SuperPlayerState | 初始状态 |
PLAYING | SuperPlayerState | 播放中 |
PAUSE | SuperPlayerState | 暂停中 |
LOADING | SuperPlayerState | 缓冲中 |
END | SuperPlayerState | 播放结束 |
13、进入画中画模式
说明:调动该方法之后,视频将会进入画中画模式,该模式只支持 Android 7.0以上,并且支持画中画模式的机型。
接口
_controller.enterPictureInPictureMode(backIcon: "images/ic_pip_play_replay.png",playIcon: "images/ic_pip_play_normal.png",pauseIcon: "images/ic_pip_play_pause.png",forwardIcon: "images/ic_pip_play_forward.png");
参数说明
该参数只适用于 Android 平台。
参数名 | 类型 | 描述 |
backIcon | String | 回退按钮图标,由于 Android 平台限制,图标大小不得超过1M,可不传,不传则使用系统自带图标。 |
playIcon | String | 播放按钮图标,由于 Android 平台限制,图标大小不得超过1M,可不传,不传则使用系统自带图标。 |
pauseIcon | String | 暂停按钮图标,由于 Android 平台限制,图标大小不得超过1M,可不传,不传则使用系统自带图标。 |
forwardIcon | String | 快进按钮图标,由于 Android 平台限制,图标大小不得超过1M,可不传,不传则使用系统自带图标。 |
事件通知
1、播放状态监听
说明:监听视频播放的状态,封装后的状态变化。
代码
_playController.onPlayStateBroadcast.listen((event) {SuperPlayerState state = event['event'];});
事件说明
事件通过枚举类 SuperPlayerState 来传递事件。
状态 | 含义 |
INIT | 初始状态 |
PLAYING | 播放中 |
PAUSE | 暂停中 |
LOADING | 缓冲中 |
END | 播放结束 |
2、播放事件监听
说明:监听播放器的操作事件。
代码
_controller.onSimplePlayerEventBroadcast.listen((event) {String evtName = event["event"];if (evtName == SuperPlayerViewEvent.onStartFullScreenPlay) {setState(() {_ isFullScreen = true;});} else if (evtName == SuperPlayerViewEvent.onStopFullScreenPlay) {setState(() {_isFullScreen = false;});} else {print(evtName);}});
事件说明
状态 | 含义 |
onStartFullScreenPlay | 进入全屏播放 |
onStopFullScreenPlay | 退出全屏播放 |
onSuperPlayerDidStart | 播放开始通知 |
onSuperPlayerDidEnd | 播放结束通知 |
onSuperPlayerError | 播放错误通知 |
onSuperPlayerBackAction | 返回事件 |
高级功能
通过 fileId 提前请求视频数据
可通过 SuperVodDataLoader 提前将视频数据请求下来,提高起播速度。
代码示例
SuperPlayerModel model = SuperPlayerModel();model.appId = 1500005830;model.videoId = new SuperPlayerVideoId();model.videoId.fileId = "8602268011437356984";model.title = "云点播";SuperVodDataLoader loader = SuperVodDataLoader();// model中的必要参数会在SuperVodDataLoader中直接赋值loader.getVideoData(model, (resultModel) {_controller.playWithModelNeedLicence(resultModel);})
画中画模式的使用
1. 平台配置
Android 平台配置:在自己项目 android 包下,找到 build.gradle,确保 compileSdkVersion 和 targetSdkVersion 的版本为31或以上
iOS 平台配置:在自己项目的 target 下选择 Signing & Capabilities 添加 Background Modes,勾选 Audio、AirPlay、and Picture in Picture。
2. 复制 superPlayer 示例代码
将 Github 项目中 superplayer_widget 导入到自己的 lib 目录下,仿照示例代码中的 demo_superplayer.dart 集成播放器组件。
然后就可以在播放器组件的播放界面右边中间看到画中画模式按钮,单击即可进入画中画模式。
3. 监听画中画模式生命周期
使用 SuperPlayerPlugin 中的 onExtraEventBroadcast 可监听到画中画模式的生命周期,示例代码如下:
SuperPlayerPlugin.instance.onExtraEventBroadcast.listen((event) {int eventCode = event["event"];if (eventCode == TXVodPlayEvent.EVENT_PIP_MODE_ALREADY_EXIT) {// exit pip mode} else if (eventCode == TXVodPlayEvent.EVENT_PIP_MODE_REQUEST_START) {// enter pip mode} else if (eventCode == TXVodPlayEvent.EVENT_PIP_MODE_ALREADY_ENTER) {// already enter pip mode} else if (eventCode == TXVodPlayEvent.EVENT_IOS_PIP_MODE_WILL_EXIT) {// will exit pip mode} else if (eventCode == TXVodPlayEvent.EVENT_IOS_PIP_MODE_RESTORE_UI) {// restore UI only support iOS}});
4. 画中画模式进入错误码
进入画中画模式失败的时候,除了有 log 提示以外,还会有 toast 提示,可在 superplayer_widget.dart 的 _onEnterPipMode 方法内修改错误情况处理。错误码含义如下:
参数名 | 值 | 描述 |
NO_ERROR | 0 | 启动成功,没有错误。 |
ERROR_PIP_LOWER_VERSION | -101 | android 版本过低,不支持画中画模式。 |
ERROR_PIP_DENIED_PERMISSION | -102 | 画中画模式权限未打开,或者当前设备不支持画中画。 |
ERROR_PIP_ACTIVITY_DESTROYED | -103 | 当前界面已经销毁。 |
ERROR_IOS_PIP_DEVICE_NOT_SUPPORT | -104 | 设备或系统版本不支持(iPad iOS9+ 才支持 PIP)。 |
ERROR_IOS_PIP_PLAYER_NOT_SUPPORT | -105 | 播放器不支持。 |
ERROR_IOS_PIP_VIDEO_NOT_SUPPORT | -106 | 视频不支持。 |
ERROR_IOS_PIP_IS_NOT_POSSIBLE | -107 | PIP 控制器不可用。 |
ERROR_IOS_PIP_FROM_SYSTEM | -108 | PIP 控制器报错。 |
ERROR_IOS_PIP_PLAYER_NOT_EXIST | -109 | 播放器对象不存在。 |
ERROR_IOS_PIP_IS_RUNNING | -110 | PIP 功能已经运行。 |
ERROR_IOS_PIP_NOT_RUNNING | -111 | PIP 功能没有启动。 |
5. 判断当前设备是否支持画中画
使用 SuperPlayerPlugin 中的 isDeviceSupportPip 可判断当前是否能够开启画中画,代码示例如下:
int result = await SuperPlayerPlugin.isDeviceSupportPip();if(result == TXVodPlayEvent.NO_ERROR) {// pip support}
result 的返回结果的含义和画中画模式错误码一致。
6. 使用画中画控制器管理画中画
画中画控制器 TXPipController 为 superplayer_widget 中封装的画中画工具,必须与 SuperPlayerView 搭配起来使用,进入画中画会自动关闭当前界面,并回调提前设置的监听方法,在回调的方法中可以保存播放器当前界面的必要参数。画中画还原之后,会重新将之前的界面 push 回来,并传递之前保存的参数。
使用该控制器的时候,画中画和播放器只能存在一个实例,当重新进入播放器界面的时候,画中画会自动关闭。
6.1 在自己的项目的入口处,如 main.dart,调用 TXPipController 设置画中画控制跳转,跳转的页面为用于进入画中画的播放器页面,
可根据自身项目情况设置不同的界面,代码实例如下:
TXPipController.instance.setNavigatorHandle((params) {navigatorKey.currentState?.push(MaterialPageRoute(builder: (_) => DemoSuperPlayer(initParams: params)));});
6.2 设置画中画的播放页面监听,需要实现
TXPipPlayerRestorePage
方法,设置之后,当即将进入画中画时,控制器会回调void onNeedSavePipPageState(Map<String, dynamic> params)
方法,此时可以在 params 中存入当前页面需要的参数。TXPipController.instance.setPipPlayerPage(this);
6.3 随后,当用户单击 SuperPlayerView 上的进入画中画按钮的时候,会调用
SuperPlayerView
的_onEnterPipMode
内部方法进入画中画,也可以自行调用SuperPlayerController
的enterPictureInPictureMode
方法进入。