集成微短剧方案—Flutter_音视频终端 SDK(Apsara Video SDK)-阿里云帮助中心

微短剧方案Flutter端是基于Flutter含UI集成方案AliPlayerWidget实现的。

概述

AliPlayerWidget 是一款专为 Flutter 应用程序设计的高性能视频播放组件，基于阿里云播放器 SDK（flutter_aliplayer）构建。它支持多种播放场景，包括视频点播（VOD）、直播、列表播放和短剧场景等。该组件提供了丰富的功能集，并具有高度灵活的 UI 定制能力，能够满足各类应用的需求，如教育、娱乐、电商和短剧等。有关更多信息，请参阅Flutter播放器含UI集成方案。

aliplayer_widget_example 是基于 aliplayer_widget Flutter 库搭建的示例工程，旨在帮助开发者快速上手并深入理解如何在实际项目中集成和使用 AliPlayerWidget；通过此工程，您可以学习如何搭建并使用短视频列表播放。

环境要求

类别	说明

类别	说明
Flutter 版本	不低于2.10.0，推荐使用3.22.2。
JDK 版本	推荐使用JDK 11。说明 JDK 11设置方法：Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Gradle JDK -> 选择 11（如果没有11，请升级你的Android Studio版本）
Android 版本	支持Android 6.0以上版本，Gradle 版本不低于 7.0。
iOS 版本	支持iOS 10.0及以上版本。
手机芯片	架构要求：armeabi-v7a、arm64-v8a。
开发工具	推荐使用Android Studio或Visual Studio Code。

前提条件

您已经获取播放器SDK License专业版的授权及License Key，应用的绑定步骤请参见绑定License。

Demo体验

下载Demo

aliplayer_widget 已经开源并提供多种下载方式。如果您需要对组件进行自定义修改，您可以使用源码依赖的方式，直接获取并修改源码。完整源码可通过以下方式获取：

下载说明	下载地址

下载说明	下载地址
Pub 源	Pub 官方源：pub.dev 中国镜像源：pub.flutter-io.cn 说明 aliplayer_widget 推荐开发者通过包管理工具集成
Pub 源
GitHub	Github地址
源码包	aliplayer_widget.zip

下载包的内容包括：

核心组件：AliPlayerWidget 和 AliPlayerWidgetController 的完整实现。
示例工程：aliplayer_widget_example 提供点播、直播、列表播放等场景的代码示例，帮助开发者快速集成和使用。
文档与注释：源码包含详细注释和开发指南，便于二次开发与定制。

集成方式

手动添加依赖

在您的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  aliplayer_widget: ^x.y.z

说明

注意：x.y.z 表示 aliplayer_widget 的版本号。您可以在 Pub.dev 官方页面中查看最新稳定版本号，并将其替换为实际值（例如 ^7.0.0）。

使用命令行工具

如果您更倾向于使用命令行，可以直接运行以下命令来添加依赖：

flutter pub add aliplayer_widget

该命令会自动更新您的 pubspec.yaml 文件。

无论您选择哪种方式，完成依赖添加后，请在终端中运行以下命令以安装依赖：

flutter pub get

通过上述步骤，AliPlayerWidget 就已成功集成到您的项目中，您可以开始使用它了！

编译与运行

命令行方式运行

IDE 方式运行

克隆仓库
首先，克隆 aliplayer_widget_example 仓库到本地：
```
cd aliplayer_widget_example
```
安装依赖
执行以下命令以安装项目所需的依赖：
```
flutter pub get
```
编译工程
编译Android工程
编译iOS工程
如果您需要编译 Android 工程，请按照以下步骤操作：
1. 确保已安装 Android SDK 和 Gradle。
2. 执行以下命令生成 APK 文件：
  flutter build apk
3. 编译完成后，APK 文件将位于build/app/outputs/flutter-apk/app-release.apk。
如果您需要编译 iOS 工程，请按照以下步骤操作：
1. 确保已安装 Xcode 和 CocoaPods。
2. 初始化 CocoaPods 依赖：
  cd ios && pod install && cd ..
3. 执行以下命令生成 iOS 应用包（IPA 文件）：
  flutter build ipa
4. 编译完成后，IPA 文件将位于build/ios/ipa/Runner.ipa。

运行示例

运行Android示例
```
flutter run lib/main.dart
```

运行iOS示例

cd ios && pod install && cd ..//运行前先pod install

flutter run lib/main.dart

使用Android Studio
1. 打开项目：
  启动Android Studio。选择 Open an Existing Project，然后导航到克隆的 aliplayer_widget_example 目录并打开。
2. 安装依赖：
  在 Android Studio 中，点击 pubspec.yaml 文件，然后点击右上角的 Pub Get 按钮以安装依赖。
3. 配置设备：
  确保已连接 Android 真机设备。
4. 运行应用：
  点击工具栏中的绿色运行按钮（Run），选择目标设备后即可启动应用。
使用 VS Code
1. 打开项目：
  启动 VS Code。选择 File -> Open Folder，然后导航到克隆的 aliplayer_widget_example 目录并打开。
2. 安装依赖：
  打开终端（Ctrl + ~），运行以下命令以安装依赖：
```
flutter pub get
```
3. 配置设备：
  确保已连接 Android 或 iOS 真机设备。使用 VS Code 的设备选择器（左下角）选择目标设备。
4. 运行应用：
  按下 F5 或点击左侧活动栏中的 Run and Debug 图标，选择 Flutter 配置并启动调试会话。
使用 Xcode（仅限 iOS）
1. 打开项目：
  导航到 ios 目录，双击 Runner.xcworkspace 文件以在 Xcode 中打开项目。
2. 安装 CocoaPods 依赖：
  如果尚未安装 CocoaPods 依赖，请在终端中运行以下命令：
```
cd ios && pod install && cd ..
```
3. 配置签名：
  在 Xcode 中，选择 Runner 项目，进入 Signing & Capabilities 标签页，配置有效的开发者账号和签名证书。
4. 运行应用：
  点击 Xcode 工具栏中的运行按钮（▶️），选择目标设备后即可启动应用。

使用方法

短视频列表播放页面（ShortVideoPage）

短视频播放的核心在于展示如何在列表中嵌入多个 AliPlayerWidget 实例，以实现多个视频的列表播放功能。示例如下：

@override
void initState() {
  super.initState();
  _pageController = PageController();
  _loadVideoInfoList();
  _pageController.addListener(_onPageChanged);
}

Widget build(BuildContext context) {
  return Scaffold(
    body: PageView.builder(
      controller: _pageController,
      itemCount: videoInfoList.length,
      itemBuilder: (context, index) {
        final videoInfo = videoInfoList[index];
        return ShortVideoItem(videoInfo: videoInfo);
      },
    ),
  );
}

运行效果：当前页面展示了一个视频列表，每个列表项包含一个独立的播放器实例。用户可以通过滑动操作切换视频，同时支持手势滑动进行视频切换。

说明

更多针对微短剧场景的优化方案，请参考aliplayer_widget_example 示例工程中的具体实现。

核心功能介绍

本组件功能使用阿里云播放器SDK，通过多个播放器实例（AliPlayer）+ 预加载（MediaLoader）+ 预渲染的方式进行实现，使用了预加载、预渲染、HTTPDNS、加密播放等核心能力，在播放延迟、播放稳定性及安全性方面大幅提升观看体验。

预加载

通过滑动窗口策略，动态启停视频的预加载任务。SDK底层基于网络状态智能调节任务优先级，以确保正播放视频和即将播放视频可以获得更多的网络资源，显著提升视频秒开率，减少播放卡顿。即使在快速滑动视频时，仍然可以获得流畅的播放体验。更多信息，请参见预加载。

预渲染

使用预渲染的方式，在后台提前渲染后续视频的首帧，减少黑屏的出现，让播放更加丝滑。音视频终端 SDK和播放器SDK从6.16.0版本开始增添了对强制预渲染功能的支持。更多信息，请参见预渲染。

HTTPDNS

HTTPDNS可以提供更快速和稳定的DNS解析服务，通过替换传统DNS解析，可以减少DNS解析时间，提高视频播放的加载速度和稳定性，从而提升用户的观看体验。音视频终端SDK和播放器SDK从6.12.0版本开始无需手动开启HTTPDNS。更多信息，请参见HTTPDNS。

视频加密

微短剧场景的视频通常为1~3分钟的MP4格式视频，音视频终端SDK和播放器SDK从6.8.0版本开始支持MP4私有加密播放能力，为微短剧场景的视频提供安全保障支撑。更多信息，请参见阿里云视频加密（私有加密）。

经私有加密的MP4格式视频，需满足以下条件，才可正常播放：

经私有加密的MP4视频传给播放器播放时，业务侧（App侧）需要为视频URL追加etavirp_nuyila=1，例如：原视频URL为https://example.aliyundoc.com/test.mp4，则需要传给播放器播放的视频URL为https://example.aliyundoc.com/test.mp4?etavirp_nuyila=1。
App的License对应的uid与产生私有加密MP4的uid是一致的。

如何校验私有加密视频是否正确，以私有加密的视频URL为例说明如下：

meta信息里面应带有AliyunPrivateKeyUri的tag。
ffplay不能直接播放。

H265自适应播放

当播放H265流硬解失败且已设置H264备流时，实现自动降级播放H264备流；若未设置H264备流，则自动降级为H265软解播放。更多信息，请参见H265自适应播放。

自适应ABR

播放器SDK支持多码率自适应HLS、DASH视频流，通过调用播放器的selectTrack方法切换播放的码流，可以实现网络自适应切换视频清晰度的功能。更多信息，详情请参见网络自适应切换。

常见问题

更多关于使用阿里云播放器 SDK 的常见问题及修复建议，请参见播放器常见问题。