播放器 SDK Harmony Flutter

二、通过这篇你可以学会

·如何在鸿蒙工程中集成腾讯云视立方 Flutter 播放器 SDK。

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

·如何使用播放器 SDK 底层能力实现更多功能。

三、基础知识

这里说明视频云 SDK 的点播播放功能，在使用前，建议你先了解如下：

云点播（VOD）的视频源是云端的一个视频文件，只要未被从云端移除，视频就可以随时播放，播放中你可以通过进度条控制播放位置，腾讯视频等视频网站上的视频观看就是典型的点播场景。

四、特别说明

视频云 SDK 不会对播放地址的来源做限制，即你可以用它来播放腾讯云或非腾讯云的地址。视频云 SDK 中的播放器支持 MP4、HLS（m3u8）和 FLV 格式的点播地址。

五、使用前提

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

八、1.1 下载 SDK

请 单击此处下载最新版 Flutter 鸿蒙端点播 SDK。

下载并解压后，会得到 Flutter 插件根目录（其中包含 pubspec.yaml、ohos/ 等子目录），后续 1.2 中提到的 <path-to-this-plugin> 即为该解压目录的本地路径（绝对/相对均可）。

九、1.2 添加 Flutter 依赖

在你的 Flutter 工程根目录的 pubspec.yaml 中添加 super_player 依赖：

dependencies: super_player: path: <path-to-this-plugin> # 指向插件根目录的本地相对/绝对路径

执行：

flutter pub get

十、1.3 配置鸿蒙工程的 ohpm 依赖

在 <your-ohos-project>/oh-package.json5 中添加 overrides：

{ "overrides": { "super_player": "file:./har/super_player.har" }}

在 <your-ohos-project>/entry/oh-package.json5 中添加 dependencies：

{ "dependencies": { "super_player": "file:../har/super_player.har" }}

注意：说明：

注意：har/super_player.har 由 flutter build hap（或 flutter run 在 ohos 设备上）自动构建并拷贝到该路径，无需手动放置。

十一、1.4 配置 License

在调用任何播放器 API 前，必须先设置 License。建议在 main() 或 MyApp.initState() 早期阶段调用：

import 'package:super_player/super_player.dart';const LICENSE_URL = "<License URL from 腾讯云控制台>";const LICENSE_KEY = "<License Key from 腾讯云控制台>";Future<void> _initPlayerLicense() async { // 注册 License 加载结果监听 SuperPlayerPlugin.instance.setSDKListener(licenceLoadedListener: (code, result) { debugPrint('[License] onLicenceLoaded code=$code result=$result'); }); await SuperPlayerPlugin.setGlobalLicense(LICENSE_URL, LICENSE_KEY);}

注意：腾讯云播放器 License 严格按 bundle name 绑定。请到 腾讯云控制台 为你的 OHOS 应用 bundle 关联 License。

十二、步骤2：创建 controller

TXVodPlayerController _controller = TXVodPlayerController();

十三、步骤3：设置监听事件

// 监听视频宽高变化，设置合适的宽高比例,也可自行设置宽高比例，视频纹理也会根据比例进行相应拉伸playEventSubscription = _controller.onPlayerEventBroadcast.listen((event) async { // Subscribe to event distribution final int code = event["event"]; if (code == TXVodPlayEvent.PLAY_EVT_CHANGE_RESOLUTION) { int? videoWidth = event[TXVodPlayEvent.EVT_PARAM1]; int? videoHeight = event[TXVodPlayEvent.EVT_PARAM2]; }});

十四、步骤4：添加布局

@overrideWidget build(BuildContext context) { return Container( decoration: BoxDecoration( image: DecorationImage( image: AssetImage("images/ic_new_vod_bg.png"), fit: BoxFit.cover, ), ), child: Scaffold( backgroundColor: Colors.transparent, appBar: AppBar( backgroundColor: Colors.transparent, title: const Text('点播'), ), body: SafeArea( child: Container( height: 150, color: Colors.black, child: Center( child: _aspectRatio > 0 ? AspectRatio( aspectRatio: _aspectRatio, child: TXPlayerVideo( androidRenderType: _renderType, onRenderViewCreatedListener: (viewId) { _controller.setPlayerView(viewId); }, ), ) : Container(), ), ), ), ), );}

十五、步骤5：启动播放

通过 url 方式通过 fileId 方式TXVodPlayerController 内部会自动识别播放协议，你只需要将你的播放 URL 传给 startVodPlay 函数即可。// 播放视频资源String _url = "http://1400329073.vod2.example.com/d62d88a7vodtranscq1400329073/59c68fe75285890800381567412/adp.10.m3u8";await _controller.startVodPlay(_url);// psign 即播放器签名TXPlayInfoParams params = TXPlayInfoParams( appId: 1252463788, fileId: "4564972819220421305", psign: "psignxxxxxxx",);await _controller.startVodPlayWithParams(params);签名介绍和生成方式可参见 播放器签名。在 云点播控制台 的智能媒资管理找到对应的视频文件，在文件名下方可以看到 FileId。通过 FileId 方式播放，播放器会向后台请求真实的播放地址。如果此时网络异常或 FileId 不存在，则会收到 PLAY_ERR_GET_PLAYINFO_FAIL 事件，反之收到 PLAY_EVT_GET_PLAYINFO_SUCC 表示请求成功。

十六、步骤6：结束播放

结束播放时记得调用 controller 的销毁方法，尤其是在下次 startVodPlay 之前，否则可能会产生大量的内存泄漏以及闪屏问题。

@overridevoid dispose() { _controller.dispose(); super.dispose();}

十八、1、播放控制

·开始播放

// 开始播放_controller.startVodPlay(url);

·暂停播放

// 暂停播放_controller.pause();

·恢复播放

// 恢复播放_controller.resume();

·结束播放

// 结束播放_controller.stopPlay(true);

·结束播放器

// 释放controller_controller.dispose();

·调整进度（Seek）：当用户拖拽进度条时，可调用 seek 从指定位置开始播放，播放器 SDK 支持精准 seek。

double time = 600; // double，单位为 秒// 调整进度_controller.seek(time);

·从指定时间开始播放：首次调用 startVodPlay 之前，支持从指定时间开始播放。

double startTimeInSecond = 60; // 单位：秒_controller.setStartTime(startTimeInSecond); // 设置开始播放时间_controller.startVodPlay(url);

十九、2、变速播放

点播播放器支持变速播放，通过接口 setRate 设置点播播放速率来完成，支持快速与慢速播放，如 0.5X、1.0X、1.2X、2X 等。

// 设置1.2倍速播放_controller.setRate(1.2);

20、3、循环播放

// 设置循环播放_controller.setLoop(true);// 获取当前循环播放状态_controller.isLoop();

21、4、静音设置

// 设置静音，true 表示开启静音， false 表示关闭静音_controller.setMute(true);

22、5、贴片广告

播放器 SDK 支持在界面添加图片贴片，用于广告宣传等。实现方式如下：

·将 autoPlay 设为 false，此时播放器会正常加载，但视频不会立刻开始播放。

·在播放器加载出来后、视频尚未开始时，即可在播放器界面查看图片贴片广告。

·待达到广告展示结束条件时，使用 resume 接口启动视频播放。

_controller.setAutoPlay(false); // 设置为非自动播放_controller.startVodPlay(url); // startVodPlay 后会加载视频，加载成功后不会自动播放// ……// 在播放器界面上展示广告// ……_controller.resume(); // 广告展示完调用 resume 开始播放视频

23、6、清晰度设置

SDK 支持 HLS 的多码率格式，方便用户切换不同码率的播放流，从而达到播放不同清晰度的目标。可以通过下面方法进行清晰度设置。

// 在收到播放器 PLAY_EVT_VOD_PLAY_PREPARED 事件调用 getSupportedBitrates 才会有值返回List _supportedBitrates = (await _controller.getSupportedBitrates())!; // 获取多码率数组int index = _supportedBitrates[i]; // 指定要播的码率下标_controller.setBitrateIndex(index); // 切换码率到想要的清晰度

在播放过程中，可以随时通过 _controller.setBitrateIndex(int) 切换码率。切换过程中，会重新拉取另一条流的数据，SDK 针对腾讯云的多码率文件做过优化，可以做到切换无卡顿。

如果你提前知道视频流的分辨率信息，可以在启播前优先指定播放的视频分辨率，从而避免播放后切换码流。详细方法参见 播放器配置#启播前指定分辨率。

24、7、码流自适应

SDK 支持 HLS 的多码流自适应，开启相关能力后播放器能够根据当前带宽，动态选择最合适的码率播放。可以通过下面方法开启码流自适应。

_controller.setBitrateIndex(-1); // index 参数传入-1

在播放过程中，可以随时通过 _controller.setBitrateIndex(int) 切换其它码率，切换后码流自适应也随之关闭。

25、8、开启平滑切换码率

在启动播放前，通过开启平滑切换码率，在播放过程中切换码率，可以达到无缝平滑切换不同清晰度。对比关闭平滑切换码率，切换过程比较耗时、体验更好，可以根据需求进行设置。

FTXVodPlayConfig playConfig = FTXVodPlayConfig();/// 设为true，可平滑切换码率, 设为false时，可提高多码率地址打开速度playConfig.smoothSwitchBitrate = true;_controller.setConfig(playConfig);

26、9、播放进度监听

点播播放中的进度信息分：加载进度和播放进度，SDK 目前是以事件通知的方式将这两个进度实时通知出来的。

通过 onPlayerEventBroadcast 接口监听播放器事件，进度通知会通过 PLAY_EVT_PLAY_PROGRESS 事件回调到你的应用程序。

_controller.onPlayerEventBroadcast.listen((event) async { if (event["event"] == TXVodPlayEvent.PLAY_EVT_PLAY_PROGRESS) { // 可播放时长，即加载进度, 单位是毫秒 double playableDuration = event[TXVodPlayEvent.EVT_PLAYABLE_DURATION_MS].toDouble(); // 播放进度, 单位是秒 int progress = event[TXVodPlayEvent.EVT_PLAY_PROGRESS].toInt(); // 视频总长, 单位是秒 int duration = event[TXVodPlayEvent.EVT_PLAY_DURATION].toInt(); }});

27、10、播放网速监听

通过 onPlayerNetStatusBroadcast 接口监听播放器的网络状态，如：NET_STATUS_NET_SPEED。

_controller.onPlayerNetStatusBroadcast.listen((event) { (event[TXVodNetEvent.NET_STATUS_NET_SPEED]).toDouble();});

28、11、获取视频分辨率

播放器 SDK 通过 URL 字符串播放视频，URL 中本身不包含视频信息。为获取相关信息，需要通过访问云端服务器加载到相关视频信息，因此 SDK 只能以事件通知的方式将视频信息发送到你的应用程序中。可以通过下面两种方法获取分辨率信息：

·方法1：通过 onPlayerNetStatusBroadcast 的 NET_STATUS_VIDEO_WIDTH 和 NET_STATUS_VIDEO_HEIGHT 获取视频的宽和高。

·方法2：在收到播放器的 PLAY_EVT_VOD_PLAY_PREPARED 事件回调后，直接调用 getWidth() 和 getHeight() 获取当前宽高。

_controller.onPlayerNetStatusBroadcast.listen((event) { double w = (event[TXVodNetEvent.NET_STATUS_VIDEO_WIDTH]).toDouble(); double h = (event[TXVodNetEvent.NET_STATUS_VIDEO_HEIGHT]).toDouble();});// 获取视频宽高，需要在收到播放器的 PLAY_EVT_VOD_PLAY_PREPARED 事件回调后才返回值_controller.getWidth();_controller.getHeight();

29、12、播放缓冲大小

在视频正常播放时，控制提前从网络缓冲的最大数据大小。如果不配置，则走播放器默认缓冲策略，保证流畅播放。

FTXVodPlayConfig playConfig = FTXVodPlayConfig();playConfig.maxBufferSize = 10; // 播放时最大缓冲大小。单位：MB_controller.setConfig(playConfig);

30、13、视频本地缓存

在短视频播放场景中，视频文件的本地缓存是很刚需的一个特性，对于普通用户而言，一个已经看过的视频再次观看时，不应该再消耗一次流量。

·格式支持：SDK 支持 HLS(m3u8) 和 MP4 两种常见点播格式的缓存功能。

·开启时机：SDK 并不默认开启缓存功能，对于用户回看率不高的场景，也并不推荐你开启此功能。

·开启方式：全局生效，在使用播放器开启。开启此功能需要配置两个参数：本地缓存目录及缓存大小。

// 设置播放引擎的全局缓存目录和缓存大小，单位 MBSuperPlayerPlugin.setGlobalMaxCacheSize(200);// 设置播放引擎的全局缓存目录// 鸿蒙端：缓存到沙盒的 cacheDir 下SuperPlayerPlugin.setGlobalCacheFolderPath("postfixPath");

31、14、外挂字幕

播放器 SDK 支持添加和切换外挂字幕，现已支持 SRT 和 VTT 这两种格式的字幕。

实践说明：建议在 startVodPlay 之前添加字幕和配置字幕样式，在收到 VOD_PLAY_EVT_VOD_PLAY_PREPARED 事件后，调用 selectTrack 选择字幕。添加字幕后，并不会主动加载字幕，调用 selectTrack 后，才会加载字幕，字幕选择成功会有 VOD_PLAY_EVT_SELECT_TRACK_COMPLETE 事件回调。选择字幕后，字幕文本内容会通过 TXVodPlayEvent.EVENT_SUBTITLE_DATA 事件回调，字幕的显示需要业务方自行处理。

32、步骤 1：添加外挂字幕

// 添加外挂字幕，传入 字幕url， 字幕名称， 字幕类型， 建议在启动播放器前添加_controller "https://mediacloud-76607.gzc.vod.tencent-cloud.com/DemoResource/subtitleVTT.vtt", "subtitleName", TXVodPlayEvent.VOD_PLAY_MIMETYPE_TEXT_SRT,);// 开始播放视频后，监听字幕文本内容回调_controller.onPlayerEventBroadcast.listen((event) async { if (event["event"] == TXVodPlayEvent.EVENT_SUBTITLE_DATA) { // 字幕文本内容，可用于显示 String subtitleDataStr = event[TXVodPlayEvent.EXTRA_SUBTITLE_DATA] ?? ""; }});

33、步骤 2：播放后切换字幕

// 开始播放视频后，选中添加的外挂字幕， 在收到 VOD_PLAY_EVT_VOD_PLAY_PREPARED 事件后调用_controller.onPlayerEventBroadcast.listen((event) async { if (event["event"] == TXVodPlayEvent.PLAY_EVT_VOD_PLAY_PREPARED) { List<TXTrackInfo> trackInfoList = await _vodPlayerController.getSubtitleTrackInfo(); for (TXTrackInfo tempInfo in trackInfoList) { if (tempInfo.name == "subtitleName") { // 选中字幕 _vodPlayerController.selectTrack(tempInfo.trackIndex); } else { // 其它字幕不需要的话， 进行 deselectTrack _vodPlayerController.deselectTrack(tempInfo.trackIndex); } } }});// 如果需要，可以监听轨道切换消息_controller.onPlayerEventBroadcast.listen((event) async { if (event["event"] == TXVodPlayEvent.VOD_PLAY_EVT_SELECT_TRACK_COMPLETE) { int trackIndex = event[TXVodPlayEvent.EVT_KEY_SELECT_TRACK_INDEX]; int errorCode = event[TXVodPlayEvent.EVT_KEY_SELECT_TRACK_ERROR_CODE]; }});

34、步骤 3：监听字幕文本内容

// 开始播放视频后，监听字幕文本内容回调_controller.onPlayerEventBroadcast.listen((event) async { if (event["event"] == TXVodPlayEvent.EVENT_SUBTITLE_DATA) { // 字幕文本内容，可用于显示 String subtitleDataStr = event[TXVodPlayEvent.EXTRA_SUBTITLE_DATA] ?? ""; }});

35、15、多音轨切换

// 返回音频轨道信息列表List<TXTrackInfo> trackInfoList = await _vodPlayerController.getAudioTrackInfo();for (TXTrackInfo tempInfo in trackInfoList) { if (tempInfo.trackIndex == 0) { // 通过判断 trackIndex 或者 name 切换到需要的音轨 _vodPlayerController.selectTrack(tempInfo.trackIndex); } else { // 不需要的音轨进行 deselectTrack _vodPlayerController.deselectTrack(tempInfo.trackIndex); }}

36、16、绑定纹理

build 中布局了 TXPlayerVideo 后，需要与播放器绑定才能将画面显示在 TXPlayerVideo 中，示例如下：

_controller.setPlayerView(viewId);

37、17、设置平铺模式

controller 提供了两种平铺模式，一种是按照视频比例优先展示完整画面 FTXPlayerRenderMode.ADJUST_RESOLUTION，另外一种是按照视频比例，铺满容器 FTXPlayerRenderMode.FULL_FILL_CONTAINER。示例如下：

_controller.setRenderMode(FTXPlayerRenderMode.ADJUST_RESOLUTION);

40、步骤 1：视频预播放使用

在短视频播放场景中，视频预播放功能对于流畅的观看体验很有帮助：在观看当前视频的同时，在后台加载即将要播放的下一个视频，这样当用户真正切换到下一个视频时，已经不需要从头开始加载了，而是可以做到立刻播放。

预播放视频会有很好的秒开效果，但有一定的性能开销，会占用下载带宽和线程资源。建议视频预播放并发个数控制在 3 个以内。

这就是视频播放中无缝切换的背后技术支撑，你可以使用 TXVodPlayerController 中的 setAutoPlay 开关来实现这个功能，具体做法如下：

// 播放视频 A: 如果将 autoPlay 设置为 true， 那么 startVodPlay 调用会立刻开始视频的加载和播放String urlA = "http://1252463788.vod2.example.com/xxxxx/v.f10.mp4";_controllercontroller.startVodPlay(urlA);// 在播放视频 A 的同时，预加载视频 B，做法是将 setAutoPlay 设置为 falseString urlB = "http://1252463788.vod2.example.com/xxxxx/v.f20.mp4";controller.setAutoPlay(isAutoPlay: false);controller.startVodPlay(urlB); // 不会立刻开始播放，而只会开始加载视频

等到视频 A 播放结束，自动（或者用户手动切换到）视频 B 时，调用 resume 函数即可实现立刻播放。

注意：设置了 autoPlay 为 false 之后，调用 resume 之前需要保证视频 B 已准备完成，即需要在监听到视频 B 的 PLAY_EVT_VOD_PLAY_PREPARED（2013，播放器已准备完成，可以播放）事件后调用。

controller.onPlayerEventBroadcast.listen((event) async { if (event["event"] == TXVodPlayEvent.PLAY_EVT_PLAY_END) { await _controller_A.stop(); await _controller_B.resume(); }});

41、步骤 2：视频预播放缓冲配置

设置较大的缓冲可以更好的应对网络的波动，达到流畅播放的目的。设置较小的缓冲可以帮助节省流量消耗。

预播放缓冲大小

此接口针对预加载场景（即在视频启播前，且设置 player 的 AutoPlay 为 false），用于控制启播前阶段的最大缓冲大小。

FTXVodPlayConfig config = FTXVodPlayConfig();config.maxPreloadSize = 2; // 预播放最大缓冲大小。单位：MB, 根据业务情况设置去节省流量_controller.setConfig(config);

播放缓冲大小

FTXVodPlayConfig config = FTXVodPlayConfig();config.maxBufferSize = 10; // 播放时最大缓冲大小。单位：MB_controller.setConfig(config);

42、2、播放器配置

在调用 startPlay 之前可以通过 setConfig 对播放器进行参数配置，例如：设置播放器连接超时时间、设置进度回调间隔、设置缓存文件个数等配置，TXVodPlayConfig 支持配置的详细参数请单击 基础配置接口 了解。使用示例：

FTXVodPlayConfig config = FTXVodPlayConfig();// 如果不配置 preferredResolution，则在播放多码率视频的时候优先播放 720*1280 分辨率的码率config.preferredResolution = 720 * 1280;config.enableAccurateSeek = true; // 设置是否精确 seek，默认 trueconfig.progressInterval = 200; // 设置进度回调间隔，单位毫秒config.maxBufferSize = 50; // 最大预加载大小，单位 MB_controller.setConfig(config);

启播前指定分辨率

播放 HLS 的多码率视频源，如果你提前知道视频流的分辨率信息，可以在启播前优先指定播放的视频分辨率。播放器会查找小于或等于偏好分辨率的流进行启播，启播后没有必要再通过 setBitrateIndex 切换到需要的码流。

FTXVodPlayConfig config = FTXVodPlayConfig();// 传入参数为视频宽和高的乘积(宽 * 高），可以自定义值传入，默认 720 * 1280config.preferredResolution = 720 * 1280;_controller.setConfig(config);

启播前指定媒资类型

当提前知道播放的媒资类型时，可以通过配置 FTXVodPlayConfig.mediaType 减少播放器 SDK 内部播放类型探测，提升启播速度。

FTXVodPlayConfig config = FTXVodPlayConfig();config.mediaType = TXVodPlayEvent.MEDIA_TYPE_FILE_VOD; // 用于提升 MP4 启播速度config.mediaType = TXVodPlayEvent.MEDIA_TYPE_HLS_VOD; // 用于提升 HLS 启播速度_controller.setConfig(config);

设置播放进度回调时间间隔

FTXVodPlayConfig config = FTXVodPlayConfig();config.progressInterval = 200; // 设置进度回调间隔，单位毫秒_controller.setConfig(config);

43、播放器事件监听

你可以通过 TXVodPlayerController 的 onPlayerEventBroadcast 来监听播放器的播放事件，来向你的应用程序同步信息。

44、播放事件通知（onPlayerEventBroadcast）

45、结束事件

46、警告事件

如下的这些事件你可以不用关心，它只是用来告知你 SDK 内部的一些事件。

47、连接事件

连接服务器的事件，主要用于测定和统计服务器连接时间：

48、画面事件

以下事件用于获取画面变化信息：

49、视频信息事件

如果通过 fileId 方式播放且请求成功，SDK 会将一些请求信息通知到上层。你可以在收到 PLAY_EVT_GET_PLAYINFO_SUCC 事件后，解析 param 获取视频信息。

通过 onPlayerEventBroadcast 获取视频播放过程信息示例：

_controller.onPlayerEventBroadcast.listen((event) async { if (event["event"] == TXVodPlayEvent.PLAY_EVT_PLAY_BEGIN || event["event"] == TXVodPlayEvent.PLAY_EVT_RCV_FIRST_I_FRAME) { // code … } else if (event["event"] == TXVodPlayEvent.PLAY_EVT_PLAY_PROGRESS) { // code … }});

50、播放状态反馈（onPlayerNetStatusBroadcast）

状态反馈每 0.5 秒都会被触发一次，目的是实时反馈当前的播放器状态，它就像汽车的仪表盘，可以告知你目前 SDK 内部的一些具体情况，以便你能对当前视频播放状态等有所了解。

通过 onPlayerNetStatusBroadcast 获取视频播放过程信息示例：

_controller.onPlayerNetStatusBroadcast.listen((event) async { int videoWidth = event[TXVodNetEvent.NET_STATUS_VIDEO_WIDTH];});

51、视频播放状态反馈

视频播放状态会在每一次播放状态切换的时候进行通知。

事件通过枚举类 TXPlayerState 来传递事件：

通过 onPlayerState 获取视频播放状态示例：

_controller.onPlayerState.listen((val) {});