Flutter播放器含UI集成方案

更新时间:2025-03-24 07:46:20

本文介绍了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 StudioVisual Studio Code

权限配置

网络权限

  • 在 Android 和 iOS 中启用网络权限,以便播放器能够加载在线视频资源。

License 配置

  • 您已获取音视频终端 SDK 的播放器的 License 授权证书和 License Key,获取的详细步骤请参见管理License

说明

注意:如未正确配置 License,播放器将无法正常工作,并可能抛出License授权异常。

更多初始化配置,请参考 aliplayer_widget_example 示例工程。

示例 Demo

为了帮助开发者快速体验 AliPlayerWidget 的功能,我们基于 aliplayer_widget_example 示例工程构建了一个演示包。该演示包可以直接安装到设备上运行,无需额外配置开发环境。

获取方式

使用手机扫描以下二维码,即可快速下载并安装演示包:

demo-qr-code

说明

注意:二维码链接指向最新版本的演示包,请确保您的设备已开启允许安装第三方应用的权限。

SDK 集成与下载

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

下载说明

下载地址

下载说明

下载地址

Pub 源

说明

aliplayer_widget 推荐开发者通过包管理工具集成

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 就已成功集成到您的项目中,您可以开始使用它了!

快速开始

实现视频播放

以下是一个完整的示例,展示如何在页面中嵌入视频播放器。只需几行代码即可完成视频播放功能。

展开查看示例代码

import 'package:flutter/material.dart';
import 'package:aliplayer_widget/aliplayer_widget_lib.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: VideoPlayerPage(),
    );
  }
}

class VideoPlayerPage extends StatefulWidget {
  @override
  _VideoPlayerPageState createState() => _VideoPlayerPageState();
}

class _VideoPlayerPageState extends State<VideoPlayerPage> {
  late AliPlayerWidgetController _controller;

  @override
  void initState() {
    super.initState();
    // 初始化播放器组件控制器
    _controller = AliPlayerWidgetController(context);
    // 配置播放器组件数据
    final data = AliPlayerWidgetData(
      videoUrl: "https://example.com/video.mp4", // 替换为实际视频地址
      coverUrl: "https://example.com/cover.jpg", // 替换为实际封面图地址
      videoTitle: "Sample Video",
    );
    _controller.configure(data); // 设置自动播放
  }

  @override
  void dispose() {
    // 销毁播放器实例,释放资源
    _controller.destroy();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: AliPlayerWidget(
          _controller,
        ),
      ),
    );
  }
}

步骤解析

  1. 初始化AliPlayerWidgetController

    在 initState 方法中创建 _controller 实例。

  2. 调用 configure 接口

    • 使用 AliPlayerWidgetData 配置视频地址、封面图、标题等信息。

    • 调用 _controller.configure(data) 将数据传递给播放器组件。

  3. 释放资源

    在 dispose 方法中调用 _controller.destroy(),避免内存泄漏。

更多场景支持

上述示例展示了点播场景的基本用法。如需了解更复杂的场景(如直播、列表播放等),请参考 aliplayer_widget_example 示例工程,其中包含了详细的代码和使用说明。

示例工程

项目说明

aliplayer_widget_example 是基于 aliplayer_widget Flutter 库的示例工程,旨在帮助开发者快速上手并深入理解如何在实际项目中集成和使用 AliPlayerWidget

通过本示例工程,您可以详细了解以下内容:

  • 如何嵌入视频播放器组件。

  • 如何配置不同场景下的播放功能(如点播、直播、列表播放)。

  • 如何利用自定义选项实现个性化的用户体验。

编译与运行

命令行方式运行
IDE 方式运行
  1. 克隆仓库

    首先,克隆 aliplayer_widget_example 仓库到本地:

    cd aliplayer_widget_example
  2. 安装依赖

    执行以下命令以安装项目所需的依赖:

    flutter pub get
  3. 编译工程

    编译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

  4. 运行示例

    • 运行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 工具栏中的运行按钮(▶️),选择目标设备后即可启动应用。

示例说明

aliplayer_widget_example 工程涵盖了多个典型场景,展示了 AliPlayerWidget 的核心功能及其在不同场景中的实际应用。无论是基础的点播播放页面,还是复杂的直播播放页面和短视频列表播放页面,开发者都可以通过本示例工程快速掌握集成和使用方法,并根据需求进行定制化开发。

点播播放页面(LongVideoPage)
直播播放页面(LivePage)

功能描述

当前页面展示如何使用 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。

示例如下

展开查看示例代码

AliPlayerWidget(
  _controller,
  overlays: [
    Positioned(
      right: 16,
      bottom: 80,
      child: Column(
        children: [
          IconButton(icon: Icon(Icons.favorite), onPressed: () {}),
          IconButton(icon: Icon(Icons.share), onPressed: () {}),
        ],
      ),
    ),
  ],
);

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

播放场景类型,默认为点播(SceneType.vod)。

示例如下

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 定制
  • 事件与状态管理
  • 核心优势
  • 简单易用
  • 灵活可扩展
  • 高性能与稳定性
  • 跨平台支持
  • 注意事项
  • 常见问题
AI助理

点击开启售前

在线咨询服务

你好,我是AI助理

可以解答问题、推荐解决方案等