本文介绍了Flutter播放器含UI集成方案。通过接入AliPlayerWidget您可以快速使用Flutter播放器。
概述
AliPlayerWidget 是一款专为 Flutter 应用程序打造的高性能视频播放组件,基于阿里云播放器 SDK flutter_aliplayer
构建。它不仅支持点播(VOD)、直播、列表播放以及短剧场景等,还提供了丰富的功能集和高度灵活的 UI 定制能力,能够满足教育、娱乐、电商以及短剧应用等多个领域对视频播放的需求。
环境要求
类别 | 说明 |
类别 | 说明 |
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 和 iOS 中启用网络权限,以便播放器能够加载在线视频资源。
License 配置
您已获取音视频终端 SDK 的播放器的 License 授权证书和 License Key,获取的详细步骤请参见管理License。
注意:如未正确配置 License,播放器将无法正常工作,并可能抛出License授权异常。
更多初始化配置,请参考 aliplayer_widget_example
示例工程。
示例 Demo
为了帮助开发者快速体验 AliPlayerWidget 的功能,我们基于 aliplayer_widget_example
示例工程构建了一个演示包。该演示包可以直接安装到设备上运行,无需额外配置开发环境。
获取方式
使用手机扫描以下二维码,即可快速下载并安装演示包:
注意:二维码链接指向最新版本的演示包,请确保您的设备已开启允许安装第三方应用的权限。
SDK 集成与下载
aliplayer_widget 已经开源并提供多种下载方式。如果您需要对组件进行自定义修改,您可以使用源码依赖的方式,直接获取并修改源码。完整源码可通过以下方式获取:
下载说明 | 下载地址 |
下载说明 | 下载地址 |
Pub 源 |
aliplayer_widget 推荐开发者通过包管理工具集成 |
GitHub | |
源码包 |
下载包的内容包括:
核心组件:
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
就已成功集成到您的项目中,您可以开始使用它了!
快速开始
实现视频播放
以下是一个完整的示例,展示如何在页面中嵌入视频播放器。只需几行代码即可完成视频播放功能。
步骤解析
初始化
AliPlayerWidgetController
在
initState
方法中创建_controller
实例。调用
configure
接口使用
AliPlayerWidgetData
配置视频地址、封面图、标题等信息。调用
_controller.configure(data)
将数据传递给播放器组件。
释放资源
在
dispose
方法中调用_controller.destroy()
,避免内存泄漏。
更多场景支持
上述示例展示了点播场景的基本用法。如需了解更复杂的场景(如直播、列表播放等),请参考 aliplayer_widget_example
示例工程,其中包含了详细的代码和使用说明。
示例工程
项目说明
aliplayer_widget_example
是基于 aliplayer_widget
Flutter 库的示例工程,旨在帮助开发者快速上手并深入理解如何在实际项目中集成和使用 AliPlayerWidget
。
通过本示例工程,您可以详细了解以下内容:
如何嵌入视频播放器组件。
如何配置不同场景下的播放功能(如点播、直播、列表播放)。
如何利用自定义选项实现个性化的用户体验。
编译与运行
克隆仓库
首先,克隆
aliplayer_widget_example
仓库到本地:cd aliplayer_widget_example
安装依赖
执行以下命令以安装项目所需的依赖:
flutter pub get
编译工程
编译Android工程编译iOS工程如果您需要编译 Android 工程,请按照以下步骤操作:
确保已安装 Android SDK 和 Gradle。
执行以下命令生成 APK 文件:
flutter build apk
编译完成后,APK 文件将位于
build/app/outputs/flutter-apk/app-release.apk
。
如果您需要编译 iOS 工程,请按照以下步骤操作:
确保已安装 Xcode 和 CocoaPods。
初始化 CocoaPods 依赖:
cd ios && pod install && cd ..
执行以下命令生成 iOS 应用包(IPA 文件):
flutter build ipa
编译完成后,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
打开项目:
启动Android Studio。选择
Open an Existing Project
,然后导航到克隆的aliplayer_widget_example
目录并打开。安装依赖:
在 Android Studio 中,点击
pubspec.yaml
文件,然后点击右上角的Pub Get
按钮以安装依赖。配置设备:
确保已连接 Android 真机设备。
运行应用:
点击工具栏中的绿色运行按钮(
Run
),选择目标设备后即可启动应用。
使用 VS Code
打开项目:
启动 VS Code。选择
File -> Open Folder
,然后导航到克隆的aliplayer_widget_example
目录并打开。安装依赖:
打开终端(
Ctrl + ~
),运行以下命令以安装依赖:flutter pub get
配置设备:
确保已连接 Android 或 iOS 真机设备。使用 VS Code 的设备选择器(左下角)选择目标设备。
运行应用:
按下
F5
或点击左侧活动栏中的Run and Debug
图标,选择Flutter
配置并启动调试会话。
使用 Xcode(仅限 iOS)
打开项目:
导航到
ios
目录,双击Runner.xcworkspace
文件以在 Xcode 中打开项目。安装 CocoaPods 依赖:
如果尚未安装 CocoaPods 依赖,请在终端中运行以下命令:
cd ios && pod install && cd ..
配置签名:
在 Xcode 中,选择
Runner
项目,进入Signing & Capabilities
标签页,配置有效的开发者账号和签名证书。运行应用:
点击 Xcode 工具栏中的运行按钮(
▶️
),选择目标设备后即可启动应用。
示例说明
aliplayer_widget_example
工程涵盖了多个典型场景,展示了 AliPlayerWidget
的核心功能及其在不同场景中的实际应用。无论是基础的点播播放页面,还是复杂的直播播放页面和短视频列表播放页面,开发者都可以通过本示例工程快速掌握集成和使用方法,并根据需求进行定制化开发。
功能描述
当前页面展示如何使用 AliPlayerWidget
实现基础的点播视频播放功能。
运行效果
页面加载后自动播放指定的点播视频,并显示封面图和标题。用户可以通过控制栏进行暂停、快进、调整音量等操作。示例如下:
@override
void initState() {
super.initState();
_controller = AliPlayerWidgetController(context);
final data = AliPlayerWidgetData(
videoUrl: "https://example.com/sample-video.mp4",
coverUrl: "https://example.com/sample-cover.jpg",
videoTitle: "Sample Video Title",
);
_controller.configure(data);
}
@override
Widget build(BuildContext context) {
return Scaffold(
body: AliPlayerWidget(_controller),
);
}
功能描述
当前页面展示如何配置 AliPlayerWidget
以支持实时直播流媒体播放。
运行效果
页面加载后实时播放直播流,支持低延迟播放。用户可以在聊天窗口中查看消息并发送自己的评论。示例如下:
@override
void initState() {
super.initState();
_controller = AliPlayerWidgetController(context);
final data = AliPlayerWidgetData(
videoUrl: "https://example.com/live-stream.m3u8",
sceneType: SceneType.live,
);
_controller.configure(data);
}
@override
Widget build(BuildContext context) {
return Scaffold(
body: Column(
children: [
Expanded(child: AliPlayerWidget(_controller)),
_buildChatArea(),
_buildMessageInput(),
],
),
);
}
短视频列表操作用法请参见集成微短剧方案—Flutter。
核心组件
AliPlayerWidget
AliPlayerWidget
是核心的播放器组件,用于嵌入到 Flutter 应用中并播放视频。
构造函数
AliPlayerWidget(
AliPlayerWidgetController controller, {
Key? key,
List<Widget> overlays = const [],
});
名称 | 说明 |
名称 | 说明 |
controller | 播放器控制器,用于管理播放逻辑。 |
overlays | 可选的浮层组件列表,用于在播放器组件上叠加自定义 UI。 |
示例如下
AliPlayerWidgetController
AliPlayerWidgetController
是播放器组件的核心控制器,用于管理播放器组件的初始化、播放、销毁等逻辑。
方法说明
名称 | 说明 |
名称 | 说明 |
configure(AliPlayerWidgetData data) | 配置数据源。 |
play() | 开始播放视频。 |
pause() | 暂停播放。 |
seek(Duration position) | 跳转到指定播放位置。 |
setUrl(String url) | 设置视频播放地址。 |
destroy() | 销毁播放器实例,释放资源。 |
示例如下
// 初始化播放器组件控制器
final controller = AliPlayerWidgetController(context);
// 设置播放器组件数据
AliPlayerWidgetData data = AliPlayerWidgetData(
videoUrl: "https://example.com/video.mp4",
);
controller.configure(data);
// 销毁播放器
controller.destroy();
AliPlayerWidgetData
AliPlayerWidgetData
是播放器组件所需的数据模型,包含视频地址、封面图、标题等信息。
属性说明
名称 | 说明 |
名称 | 说明 |
videoUrl | 视频播放地址(必填)。 |
coverUrl | 封面图地址(可选)。 |
videoTitle | 视频标题(可选)。 |
thumbnailUrl | 缩略图地址(可选)。 |
sceneType | 播放场景类型,默认为点播( |
示例如下
AliPlayerWidgetData(
videoUrl: "https://example.com/video.mp4",
coverUrl: "https://example.com/cover.jpg",
videoTitle: "Sample Video",
sceneType: SceneType.vod,
);
自定义功能
浮层组件
通过 overlays
参数,您可以轻松地在播放器上叠加自定义 UI 组件。例如,添加点赞、评论、分享按钮等。
AliPlayerWidget(
_controller,
overlays: [
Positioned(
right: 16,
bottom: 80,
child: Column(
children: [
IconButton(icon: Icon(Icons.favorite), onPressed: () {}),
IconButton(icon: Icon(Icons.comment), onPressed: () {}),
IconButton(icon: Icon(Icons.share), onPressed: () {}),
],
),
),
],
);
常用接口
AliPlayerWidget
提供了一系列对外接口,方便开发者直接控制播放器的行为。这些接口通过 AliPlayerWidgetController
暴露,支持播放控制、状态查询、数据更新等功能。以下是一些常用的对外接口及其使用场景:
配置与初始化
名称 | 功能描述 |
名称 | 功能描述 |
configure | 配置播放器数据源并初始化播放器。 |
prepare | 准备播放器(手动调用准备流程)。 |
播放控制
名称 | 功能描述 |
名称 | 功能描述 |
play | 开始播放视频。 |
pause | 暂停播放。 |
stop | 停止播放并重置播放器。 |
seek | 跳转到指定的播放位置。 |
togglePlayState | 切换播放状态(播放/暂停)。 |
replay | 重新播放视频(通常用于播放完成后重新开始)。 |
播放属性设置
名称 | 功能描述 |
名称 | 功能描述 |
setSpeed | 设置播放速度。 |
setVolume | 设置音量。 |
setVolumeWithDelta | 根据增量调整音量。 |
setBrightness | 设置屏幕亮度。 |
setBrightnessWithDelta | 根据增量调整屏幕亮度。 |
setLoop | 设置是否循环播放。 |
setMute | 设置是否静音。 |
setMirrorMode | 设置镜像模式(如水平镜像、垂直镜像等)。 |
setRotateMode | 设置旋转角度(如 90°、180° 等)。 |
setScaleMode | 设置渲染填充模式(如拉伸、裁剪等)。 |
selectTrack | 切换播放清晰度。 |
其它设置
名称 | 功能描述 |
名称 | 功能描述 |
requestThumbnailBitmap | 请求指定时间点的缩略图。 |
clearCaches | 清除播放器缓存(包括视频缓存和图片缓存)。 |
getWidgetVersion | 获取当前 Flutter Widget 的版本号。 |
事件通知
AliPlayerWidgetController
提供了一系列 ValueNotifier
,用于实时通知播放器的状态变化和用户操作。以下是一些常用的 notifier
及其用途:
常用 Notifier 概览
播放状态管理
名称 | 功能描述 |
名称 | 功能描述 |
playStateNotifier | 用于监听播放状态的变化(如播放、暂停、停止等)。 |
playErrorNotifier | 监听播放过程中发生的错误信息,提供错误码和错误描述。 |
播放进度管理
名称 | 功能描述 |
名称 | 功能描述 |
currentPositionNotifier | 实时更新当前播放进度(单位:毫秒)。 |
bufferedPositionNotifier | 跟踪视频的缓冲进度,帮助用户了解已缓存的内容范围。 |
totalDurationNotifier | 提供视频的总时长信息,便于计算播放进度百分比或显示总时长。 |
音量与亮度控制
Notifier | 功能描述 |
Notifier | 功能描述 |
volumeNotifier | 监听音量变化,支持动态调整音量大小(范围通常为 0.0 到 1.0)。 |
brightnessNotifier | 监听屏幕亮度变化,允许用户根据环境光线调整亮度(范围通常为 0.0 到 1.0)。 |
清晰度与缩略图
Notifier | 功能描述 |
Notifier | 功能描述 |
currentTrackInfoNotifier | 跟踪当前视频清晰度信息的变化(如标清、高清、超清等),并提供切换后的清晰度详情。 |
thumbnailNotifier | 监听缩略图加载状态,确保在拖动进度条时能够实时显示对应的缩略图预览。 |
使用方法
通过 ValueListenableBuilder
监听 notifier
的变化,可以实时更新 UI 或执行逻辑。示例如下:
// 监听播放错误
ValueListenableBuilder<Map<int?, String?>?>(
valueListenable: _controller.playErrorNotifier,
builder: (context, error, _) {
if (error != null) {
final errorCode = error.keys.firstOrNull;
final errorMsg = error.values.firstOrNull;
return Text("播放错误: [$errorCode] $errorMsg");
}
return SizedBox.shrink();
},
);
功能特性
多场景适配
支持点播、直播、列表播放及全屏播放等多种场景。
丰富的功能集
基础功能:提供播放控制、设置面板、封面图显示、清晰度切换等核心功能,满足常规视频播放需求。
手势控制:支持亮度、音量和播放进度的手势调节,操作直观便捷,提升用户体验。
灵活的 UI 定制
浮层支持:支持自定义浮层组件,扩展性强,允许开发者实现如广告、弹幕等复杂功能。
模块化设计:内置顶部栏、底部栏、设置面板等可复用的 UI 组件,方便开发者按需定制。
全屏适配:自动适配横竖屏切换,确保在不同设备上的最佳显示效果。
事件与状态管理
实时状态监控:提供播放状态、视频尺寸、缓冲进度等实时数据更新,便于开发者实现动态交互。
事件回调机制:提供全面的播放器事件监听,包括播放开始、暂停、完成等状态管理,方便开发者处理各种播放场景。
日志与调试支持:内置详细的日志系统,便于问题排查和性能优化。
核心优势
通过简单的 API 调用,开发者可以快速集成高质量的视频播放功能,显著降低开发成本。无论是基础的播放控制,还是复杂的交互场景(如手势调节、浮层叠加),AliPlayerWidget 都能轻松应对,帮助开发者构建流畅且高效的用户体验。
简单易用
通过简单的 API 调用即可实现复杂的视频播放功能,快速集成到 Flutter 项目中。
灵活可扩展
模块化设计,支持多种自定义选项,方便开发者根据需求进行定制。
自动适配不同屏幕尺寸和分辨率,确保一致的用户体验。
高性能与稳定性
基于阿里云播放器 SDK,提供低延迟、高稳定性的视频播放体验。
优化的架构设计,通过轻量化组件、异步加载和事件驱动模型,确保高效运行与流畅用户体验。
跨平台支持
充分利用 Flutter 的跨平台特性,支持 Android 和 iOS 平台,一次开发即可实现双端运行。
注意事项
资源释放
在页面销毁时,请务必调用 AliPlayerWidgetController.destroy()
方法以释放播放器资源。
网络权限
确保应用已配置必要的网络权限,以便加载在线视频。
缩略图支持
如果需要使用缩略图功能,请确保提供了有效的缩略图地址。
调试与优化
建议在开发过程中开启日志功能,便于排查问题。同时,注意优化浮层组件的性能,避免影响播放流畅性。
常见问题
更多关于使用阿里云播放器 SDK 的常见问题及修复建议,请参见播放器常见问题。
- 本页导读 (1)
- 概述
- 环境要求
- 权限配置
- 示例 Demo
- 获取方式
- SDK 集成与下载
- 集成方式
- 快速开始
- 示例工程
- 项目说明
- 编译与运行
- 示例说明
- 核心组件
- AliPlayerWidget
- AliPlayerWidgetController
- AliPlayerWidgetData
- 自定义功能
- 浮层组件
- 常用接口
- 事件通知
- 常用 Notifier 概览
- 使用方法
- 功能特性
- 多场景适配
- 丰富的功能集
- 灵活的 UI 定制
- 事件与状态管理
- 核心优势
- 简单易用
- 灵活可扩展
- 高性能与稳定性
- 跨平台支持
- 注意事项
- 常见问题