Flutter 接入指引

SDK 下载

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

阅读对象

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

通过本文你可以学会

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

播放器组件简介

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

支持功能列表：

• 全屏播放

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

• 自定义视频封面

• 清晰度切换

• 声音和亮度调节

• 倍速播放

• 硬件加速开启\关闭

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

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

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

集成指引

1. 将项目中 example 下的 superplayer 目录复制到自己的 Flutter 工程下
2. 在需要使用到的页面，导入superplayer的依赖包，如下所示：
   

   import 'superplayer/demo_superplayer_lib.dart';

SDK 集成

步骤1：申请视频播放能力 License 和集成

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

如果没有集成 License，播放过程中可能会出现异常。

String licenceURL = ""; // 获取到的 licence url
String licenceKey = ""; // 获取到的 licence key
SuperPlayerPlugin.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：添加返回事件监听

添加返回事件监听，确保用户在触发返回事件的时候，如果播放器处于全屏等状态，可以优先退出全屏，再次触发才会退出页面。
如果全屏播放状态下需要直接退出页面，可以不实现该监听

  @override
Widget 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/42436
model.videoId.pSign = "psignXXX"
_controller.playWithModelNeedLicence(model);

步骤8：结束播放

结束播放时记得调用 controller 的销毁方法，尤其是在下次 startVodPlay 之前，否则可能会产生大量的内存泄露以及闪屏问题。也确保在退出页面的时候，能够结束视频播放。

  @override
void 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);

参数说明

1. SuperPlayerModel

2. SuperPlayerVideoId

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

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、Android 平台配置

1.1 在自己项目的android包下，找到 AndroidManifest.xml ，在项目入口activity节点下，增加如下配置

android:supportsPictureInPicture="true"
android:resizeableActivity="true"
android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation"

// 在自己项目android包下，找到build.gralde，确认 compileSdkVersion 和 targetSdkVersion 的版本为31或以上

1.2 继承 pip activity

将 github 项目中example/android 中的 FTXFlutterPipActivity.java 复制到自己入口 Activity 的同目录下，并将自己 Activity 的父类修改为该类。

2、iOS 平台配置

2.1 在自己项目的target下选择Signing & Capabilities 添加 Background Modes，勾选 Audio,AirPlay,and Picture in Picture。

3、复制 superPlayer 示例代码

将 github 项目中 example/lib 中的 superplayer 包复制到自己的 lib 目录下，仿照示例代码中的 demo_superplayer.dart 集成好超级播放器。
然后就可以在超级播放器的播放界面右边中间看到画中画模式按钮，单击即可进入画中画模式。

4、监听画中画模式生命周期

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

5、画中画模式进入错误码

进入画中画模式失败的时候，除了有 log 提示以外，还会有 toast 提示，可在 superplayer_widget.dart 的 _onEnterPipMode 方法内修改错误情况处理。错误码含义如下：

6、判断当前设备是否支持画中画

使用 SuperPlayerPlugin 中的 isDeviceSupportPip 可判断当前是否能够开启画中画，代码示例如下

int result = await SuperPlayerPlugin.isDeviceSupportPip();
if(result == TXVodPlayEvent.NO_ERROR) {
  // pip support
}

result 的返回结果的含义和画中画模式错误码一致。