腾讯云云点播Flutter 接入指引

SDK 下载

腾讯云视立方 Flutter 播放器 SDK 的地址是 Player Flutter。

阅读对象

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

通过本文您可以学会

如何集成腾讯云视立方 Flutter 播放器 SDK。如何使用播放器组件进行点播播放。

播放器组件简介

Flutter 播放器组件是基于 Flutter 播放器 SDK 的扩展，播放器组件对于点播播放器，集成了更多的功能，包括全屏切换、清晰度切换、
进度条、播放控制、封面标题展示等常用功能，并且相对于点播播放器使用起来更加方便，如果想更加方便快捷的集成 Flutter 视频播放能力，可以选择 Flutter 播放器组件使用。支持功能列表：全屏播放播放过程中屏幕旋转自适应自定义视频封面清晰度切换声音和亮度调节倍速播放硬件加速开启\关闭画中画（PIP）（支持 Android 和 iOS 平台）雪碧图和关键帧打点信息更多功能正在逐步开发中。

集成指引

1. 将项目中 superplayer_widget 目录复制到自己的 flutter 工程下。2. 在自己项目的配置文件 pubspec.yaml 下添加依赖。

superplayer_widget:      # 该路径根据superplayer_widget存放路径改变      path: ../superplayer_widgetsuper_player:  git:    url: https://github.com/LiteAVSDK/Player_Flutter    path: Flutter    ref: main

ref 可以根据自身项目需要，替换为对应的版本或分支。3. 修改 superplayer_widget 的superPlayer依赖。
进入修改 superplayer_widget 的pubspec.yaml。将如下配置进行替换：

super_player:  path: ../

替换为：

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

ref 可以根据自身项目需要，替换为对应的版本或分支。4. 在需要使用到的页面，导入superplayer_widget的依赖包，如下所示：

import 'package:superplayer_widget/demo_superplayer_lib.dart';

SDK 集成

步骤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 onWillPop() async {  return !_controller.onBackPress();}

步骤7：启动播放

通过 url 方式通过 fileId 方式

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"_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} 设置 Licence 后方可成功播放， 否则将播放失败（黑屏），全局仅设置一次即可。直播 Licence、短视频 Licence 和播放器 Licence 均可使用，若您暂未获取上述 Licence ，可 快速免费申请测试版 Licence 以正常播放，正式版 License 需 购买。说明开始播放视频。接口

_controller.playWithModelNeedLicence(model);

参数说明SuperPlayerModel

SuperPlayerVideoId

playAction

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 来获取，前者为清晰度列表，后者为默认清晰度。清晰度切换能力在播放器组件中已经集成，切换到全屏之后可点击右下角清晰度进行切换。

9、调整进度(seek)

说明调整当前视频的播放进度。接口

_controller.seek(progress);

参数说明

10、配置播放器组件

说明配置播放器组件。接口

_controller.setPlayConfig(config);

参数说明

11、开关硬解

说明开启或关闭硬解播放能力。接口

_controller.enableHardwareDecode(enable);

12、获得播放状态

说明获得当前播放器的播放状态。接口

SuperPlayerState superPlayerState = _controller.getPlayerState();

参数说明

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 平台。

事件通知

1、播放状态监听

说明监听视频播放的状态，封装后的状态变化。代码

_playController.onPlayStateBroadcast.listen((event) {  SuperPlayerState state = event['event'];});

事件说明事件通过枚举类 SuperPlayerState 来传递事件。

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

事件说明

高级功能

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

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设置画中画控制跳转，跳转的页面为用于进入画中画的播放器页面。
可根据自身项目情况设置不同的界面，代码实例如下：

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

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

TXPipController.instance.setPipPlayerPage(this);

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

3、视频下载

下载视频

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

停止下载视频

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

DownloadHelper.instance.stopDownload(mediaInfo);

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

删除下载视频

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

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

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

下载状态

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 来判断下载状态。

播放下载的视频

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

controller.startVodPlay(mediaInfo.playPath);

4、横竖屏的使用

横竖屏切换配置

播放器组件横竖屏的切换，iOS 需要使用 Xcode 打开，打开项目配置，General 分页下的 Deployment 标签下，勾选上Landscape left和Landscaoe right。确保 iOS 设备能够支持横屏。如果希望自己的 App 其他页面稳定保持竖屏，不受横竖屏自动旋转影响，需要在自己项目下的入口处，配置竖屏。代码如下：

SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]);

根据 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    }  });

Demo 体验

更多功能和调试 Demo 体验，请 单击这里。
云点播官网1折活动，限时活动，即将结束，速速收藏
同尘科技为腾讯云授权服务中心。
购买腾讯云产品享受折上折，更有现金返利。同意关联立享优惠