播放器 SDK Flutter（播放器组件）

二、阅读对象

这篇档部分内容为腾讯云专属能力，使用前请开通 腾讯云 相关服务，未注册用户可注册账号 免费试用。

三、通过这篇你可以学会

·如何集成腾讯云视立方 Flutter 播放器 SDK。

·如何使用播放器组件进行点播播放。

四、播放器组件简介

Flutter 播放器组件是基于 Flutter 播放器 SDK 的扩展，播放器组件对于点播播放器，集成了更多的功能，包括全屏切换、清晰度切换、
进度条、播放控制、封面标题展示等常用功能，并且相对于点播播放器使用起来更加方便，如果想更加方便快捷的集成 Flutter 视频播放能力，可以选择 Flutter 播放器组件使用。

支持功能列表：

·全屏播放

·播放过程中屏幕旋转自适应

·自定义视频封面

·清晰度切换

·声音和亮度调节

·倍速播放

·硬件加速开启\\关闭

·画中画（PIP）（支持 Android 和 iOS 平台）

·雪碧图和关键帧打点信息

更多功能正在逐步开发中。

五、集成指引

1. 将项目中 superplayer_widget 目录复制到自己的 flutter 工程下。

2. 在自己项目的配置文件 pubspec.yaml 下添加依赖。

分支集成pub 集成superplayer_widget: # 该路径根据superplayer_widget存放路径改变 path: ../superplayer_widget## 13.0 之后集成方式，不加则默认使用 professional 版本：super_player: sub_spec: 'professional' # 可根据自身需要，切换如下版本 # player: 播放器基础版本，支持点播（VOD）与基础直播功能. # professional: 完整功能版本，通常用于同时集成多个腾讯插件. # premium: 播放器高级版本，包含高级播放器功能. # professional_premium: 完整功能版与高级播放器版本的结合，在兼容完整功能版的同时支持使用高级播放器能力.dependencies: super_player: git: url: https://github.com/LiteAVSDK/Player_Flutter path: Flutter ## 13.0 之前集成方式：super_player: git: url: https://github.com/LiteAVSDK/Player_Flutter path: Flutter ref: main# ref 可以根据自身项目需要，替换为对应的版本或分支。superplayer_widget: # 该路径根据superplayer_widget存放路径改变 path: ../superplayer_widget ## 13.0 之后集成方式，不加则默认使用 professional 版本：super_player: sub_spec: 'professional' # 可根据自身需要，切换如下版本 # player: 播放器基础版本，支持点播（VOD）与基础直播功能. # professional: 完整功能版本，通常用于同时集成多个腾讯插件. # premium: 播放器高级版本，包含高级播放器功能. # professional_premium: 完整功能版与高级播放器版本的结合，在兼容完整功能版的同时支持使用高级播放器能力.dependencies: # 13.0 之前，pub集成默认为 professional 版本，13.0 之后可以通过以上 sub_spec 方式来指定版本 super_player: ^13.0.0

3. 修改 superplayer_widget 的 superPlayer 依赖。

4. 进入修改 superplayer_widget 的 pubspec.yaml。

将如下配置进行替换：

super_player: path: ../

替换为：

super_player: git: url: https://github.com/LiteAVSDK/Player_Flutter path: Flutter ref: main

ref 可以根据自身项目需要，替换为对应的版本或分支。

5. 由于目前播放器组件接入了国际化，需要在入口函数中添加国际化组件，如下示例：

@override
Widget build(BuildContext context) {
return MaterialApp(
localizationsDelegates: [
SuperPlayerWidgetLocals.delegate, // …… your app other delegate
],
supportedLocales: [
Locale.fromSubtags(languageCode: 'en'),
Locale.fromSubtags(languageCode: 'zh'), // ……. other language
], // …… your app other code
);
}

6. 在需要使用到的页面，导入 superplayer_widget 的依赖包，如下所示：

import 'package:superplayer_widget/demo_superplayer_lib.dart';

7. 其余原生相关配置，可以参考 集成指引。

七、步骤1：申请播放器 License 和集成

集成播放器前，需要 注册腾讯云账户，注册成功后申请播放器 License， 然后通过下面方式集成，建议在应用启动时进行。

如果没有集成 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：启动播放

通过 url 方式通过 fileId 方式SuperPlayerModel model = SuperPlayerModel();model.videoURL = "http://1400329073.vod2.example.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";_controller.playWithModelNeedLicence(model);在 媒资管理 找到对应的视频文件。在文件名下方可以看到 FileId。通过 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} 设置 License 后方可成功播放， 否则将播放失败（黑屏），全局仅设置一次即可。直播 License、短视频 License 和播放器 License 均可使用，若你暂未获取上述 License ，可 免费申请测试版 License 以正常播放，正式版 License 需 购买。

说明

开始播放视频。

接口

_controller.playWithModelNeedLicence(model);

参数说明

·SuperPlayerModel

·SuperPlayerVideoId

·playAction

十七、2、暂停播放

说明

暂停播放视频。

接口

_controller.pause();

十八、3、继续播放

说明

继续播放视频。

接口

_controller.resume();

十九、4、重新开始播放

说明

重新开始播放视频。

接口

_controller.reStart();

20、5、重置播放器

说明

重置播放器状态，并停止播放视频。

接口

_controller.resetPlayer();

21、6、释放播放器

说明

释放播放器资源，并停止播放，调用该方法之后，controller 将不可再复用。

接口

_controller.releasePlayer();

22、7、播放器返回事件

说明

触发播放器返回事件，该方法主要用于全屏播放模式下的返回判断和处理。

返回 true：执行了退出全屏等操作，消耗了返回事件；返回 false：未消耗事件。

接口

_controller.onBackPress();

23、8、切换清晰度

说明

实时切换当前正在播放的视频的清晰度。

接口

_controller.switchStream(videoQuality);

参数说明

videoQuality 在开始播放之后，一般可通过 _controller.currentQualityList 和 _controller.currentQuality 来获取，前者为清晰度列表，后者为默认清晰度。清晰度切换能力在播放器组件中已经集成，切换到全屏之后可点击右下角清晰度进行切换。

24、9、调整进度(seek)

说明

调整当前视频的播放进度。

接口

_controller.seek(progress);

参数说明

25、10、配置播放器组件

说明

配置播放器组件。

接口

_controller.setPlayConfig(config);

参数说明

26、11、开关硬解

说明

开启或关闭硬解播放能力。

接口

_controller.enableHardwareDecode(enable);

27、12、获得播放状态

说明

获得当前播放器的播放状态。

接口

SuperPlayerState superPlayerState = _controller.getPlayerState();

参数说明

28、13、进入画中画模式

说明

调用该方法之后，视频将会进入画中画模式，该模式只支持 Android 7.0 以上，并且支持画中画模式的机型。其中 iOS 直播画中画需要使用 premium 权限，并使用 12.1 以上版本的 SDK。

接口

_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 平台，iOS 平台使用默认图片。

29、14、设置平铺模式

目前播放器组件提供了两种平铺模式，适应视频分辨率模式 SuperPlayerRenderMode.ADJUST_RESOLUTION 和 铺满播放器模式 SuperPlayerRenderMode.FILL_VIEW ，默认 SuperPlayerRenderMode.ADJUST_RESOLUTION 模式，其中使用 FILL_VIEW 模式，必须要给播放器设置一个确定的高度，否则播放器的高度可能会撑开到全屏，该模式由组件构造方法传入，示例如下：

Widget _getPlayArea() {
return Container(
decoration: BoxDecoration(color: Colors.black),
height: playerHeight,
child: SuperPlayerView(_controller, SuperPlayerRenderMode.ADJUST_RESOLUTION),
);
}

31、播放事件监听

说明

监听播放器的操作事件。

代码

_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); }});

事件说明

33、1、通过 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);});

34、2、画中画模式的使用

1. 平台配置

AndroidiOS在自己项目 android 包下，找到 build.gradle，确保 compileSdkVersion 和 targetSdkVersion 的版本为31或以上。在自己项目的 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 方法内修改错误情况处理。错误码含义如下：

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 设置画中画控制跳转，跳转的页面为用于进入画中画的播放器页面。

6.2 可根据自身项目情况设置不同的界面，代码实例如下：

TXPipController.instance.setNavigatorHandle((params) { navigatorKey.currentState?.push(MaterialPageRoute(builder: (_) => DemoSuperPlayer(initParams: params)));});

6.3 设置画中画的播放页面监听，需要实现 TXPipPlayerRestorePage 方法，设置之后，当即将进入画中画时，控制器会回调 void onNeedSavePipPageState(Map<String, dynamic> params)方法，此时可以在 params 中存入当前页面需要的参数。

TXPipController.instance.setPipPlayerPage(this);

随后，当用户点击 SuperPlayerView 上的进入画中画按钮的时候，会调用 SuperPlayerView 的 _onEnterPipMode 内部方法进入画中画，也可以自行调用 SuperPlayerController 的 enterPictureInPictureMode 方法进入。

36、下载视频

1. 使用播放器组件的视频下载，首先需要把 SuperPlayerModel 中的 isEnableDownload 打开，该字段默认关闭。

SuperPlayerModel model = SuperPlayerModel();// 打开视频下载能力model.isEnableDownload = true;

播放器组件目前只会在点播播放模式下启用下载。

2. 使用 SuperPlayerController 的 startDownload 方法，可以直接下载当前播放器正在播放的视频，对应的是当前播放视频的清晰度。也可以使用 DownloadHelper 下载指定视频，如下：

DownloadHelper.instance.startDownloadBySize(videoModel, videoWidth, videoHeight);

使用 DownloadHelper 的 startDownloadBySize，可下载指定分辨率的视频，如果没有该分辨率，会下载相近分辨率的视频。

除了以上接口以外，也可选择传入画质 ID 或者 mediaInfo 直接下载。

// QUALITY_240P 240p// QUALITY_360P 360P// QUALITY_480P 480p// QUALITY_540P 540p// QUALITY_720P 720p// QUALITY_1080P 1080p// QUALITY_2K 2k// QUALITY_4K 4k// quality参数可以自定义，取分辨率宽高最小值(如分辨率为1280*720, 期望下载此分辨率的流，quality传入 QUALITY_720P)// 播放器 SDK 会选择小于或等于传入分辨率的流进行下载// 使用画质ID下载DownloadHelper.instance.startDownload(videoModel, qualityId);// 使用mediaInfo下载DownloadHelper.instance.startDownloadOrg(mediaInfo);

3. 画质 ID 转换

点播的 CommonUtils 提供了 getDownloadQualityBySize 方法，用于将分辨率转为对应的画质 ID。

CommonUtils.getDownloadQualityBySize(width, height);

37、停止下载视频

使用 DownloadHelper 的 stopDownload 方法可以停止对应的视频下载，示例如下：

DownloadHelper.instance.stopDownload(mediaInfo);

mediaInfo 可通过 DownloadHelper 的 getMediaInfoByCurrent 方法获取，或者使用 TXVodDownloadController 的 getDownloadList 获得下载信息。

38、删除下载视频

使用 DownloadHelper 的 deleteDownload 方法，可以删除对应的视频。

bool deleteResult = await DownloadHelper.instance.deleteDownload(downloadModel.mediaInfo);

deleteDownload 会返回删除的结果，来判断是否删除成功。

39、下载状态

DownloadHelper 提供了基本的 isDownloaded 方法判断视频是否已经下载。也可以注册监听来实时判断下载状态。

DownloadHelper 对下载事件进行了分发，可通过如下代码进行事件注册。

// 注册下载事件监听DownloadHelper.instance.addDownloadListener(FTXDownloadListener((event, info) { // 下载状态变化 }, (errorCode, errorMsg, info) { // 下载错误回调 }));// 移除下载事件监听DownloadHelper.instance.removeDownloadListener(listener);

此外，还可以通过 TXVodDownloadController.instance.getDownloadInfo(mediaInfo)方法或者 TXVodDownloadController.instance.getDownloadList()方法直接查询 mediaInfo 中的 downloadState 来判断下载状态。

40、播放下载的视频

TXVodDownloadController.instance.getDownloadInfo(mediaInfo)和 TXVodDownloadController.instance.getDownloadList()获得到的视频信息中有个 playPath 字段，使用 TXVodPlayerController 直接播放即可。

controller.startVodPlay(mediaInfo.playPath);

42、横竖屏切换配置

播放器组件横竖屏的切换，iOS 需要使用 Xcode 打开，打开项目配置，General 分页下的 Deployment 标签下，勾选上 Landscape left 和 Landscaoe right。确保 iOS 设备能够支持横屏。

如果希望自己的 App 其他页面稳定保持竖屏，不受横竖屏自动旋转影响，需要在自己项目下的入口处，配置竖屏。代码如下：

SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]);

43、根据 sensor 配置自动全屏

Android 端需要调用如下方法，来开启对 sensor 的监听。

SuperPlayerPlugin.startVideoOrientationService();

调用之后，在 Android 设备上，将会对 Android sensor 进行监听，会通过 SuperPlayerPlugin.instance.onEventBroadcast 对 Flutter 侧发送旋转事件。播放器组件内部也会自动根据该事件旋转播放器。监听使用范例如下：

SuperPlayerPlugin.instance.onExtraEventBroadcast.listen((event) { int eventCode = event["event"]; if (eventCode == TXVodPlayEvent.EVENT_ORIENTATION_CHANGED ) { int orientation = event[TXVodPlayEvent.EXTRA_NAME_ORIENTATION]; // do orientation } });

44、常见问题

1. 集成后，播放经常出现有声音，却没有画面的现象，怎么处理？

由于含 UI 组件和 Flutter 播放器插件会随着版本迭代而更新调用方式，需要保持两者版本一致。播放器组件版本可以使用 PlayerConstants.PLAYER_WIDGET_VERSION 来确认，Flutter 播放器插件版本，除了集成时候的版本以外，也可以使用 FPlayerPckInfo.PLAYER_VERSION 确认，确保两者的版本一致。

2. 需要去掉屏幕自动旋转的能力，怎么处理？

播放器组件采用的开源方式，为了满足不同客户的业务定制化需求，建议客户采用直接修改组件代码的方式来完成业务定制化需求。如果需要跟进组件版本，可以建立私有仓库，fork 组件代码，有更新之后可以 pick 变动。

45、Demo 体验

更多功能和调试 Demo 体验，请 单击这里，运行该 Demo 的时候，需要在 demo_config 中设置自己的播放器 license，并在 Android 和 iOS 配置中，将包名和 bundleId 修改为自己签名的包名和 bundleId。