Skip to main content

kinetic_player 3.0.0 copy "kinetic_player: ^3.0.0" to clipboard
kinetic_player: ^3.0.0 copied to clipboard

Multi-core Flutter video player: GSYVideoPlayer (Android) + SGPlayer (iOS/macOS) + Artplayer.js (Web) + libmpv (Windows/Linux).

Kinetic Player

kinetic_player #

English version: README_EN.md

最强大的跨平台 Flutter 视频播放器插件:Android 使用 GSYVideoPlayer 14.0.0,iOS / macOS 使用 wanwenfeng4798/SGPlayer(v2.0.0),Web 使用 Artplayer.js 5.4.0,Windows / Linux 使用 libmpv。

仓库:github.com/wanwenfeng4798/kinetic_player

需要 Dart 3.13 / Flutter 3.47+,并依赖 material_ui: ^1.8.0。

平台预览 #

以下截图为迁移前版本;3.0 的 iOS/macOS 使用 SGPlayer 2 原生控制栏。

Android iOS
Android iOS
macOS Web
macOS Web

特性 #

  • 统一的 CommonVideoController API(播放 / 暂停 / 跳转 / 缩放 / 倍速 / 音量 / 音轨 / 循环 / 截图等)
  • 平台自动选型:Android → GSY,iOS / macOS → SGPlayer,Web → Artplayer,Windows / Linux → libmpv
  • Android 使用 GSY 原生控制栏;iOS/macOS 使用 SGPlayer 2 原生控制栏;桌面与 Web 保留独立 UI
  • Android / iOS 支持滑动手势调进度 / 音量 / 亮度(enableNativeControls);macOS / Windows / Linux 无滑动手势,用进度条 + 喇叭/齿轮按钮
  • Android 画中画(PiP)默认开启(API 26+;播放中切后台自动进入,含 GSY 自动播放场景)
  • Web:Video / Document PiP、HLS/DASH、官方 Artplayer 插件(弹幕 / 字幕 / Chromecast 等)
  • Android GSY:弹幕/水印/广告/滤镜等高级能力见 doc/GSY_FEATURES.md(内嵌与窗口全屏一致)
  • 独有功能通过显式向下转型调用(不污染公共接口)
  • iOS / macOS 经 sharedDarwinSource(darwin/)同时支持 CocoaPods 与 Swift Package Manager (SPM)
  • 预编译 SGPlayer.xcframework 可通过 GitHub Release 下载,避免本地编译

文档 #

文档 说明
doc/USAGE.md 集成步骤、公共 API、原生 UI、平台差异、PiP 配置
doc/GSY_FEATURES.md Android GSY 高级能力对照表
doc/DARWIN_SGPLAYER.md iOS / macOS SGPlayer:二进制、脚本、SPM、Release
doc/WEB_ARTPLAYER.md Web Artplayer:插件、HLS/DASH、Web 独有 API、打包
doc/DESKTOP_MPV.md Windows / Linux libmpv:依赖、DLL、Wayland、hwdec
doc/EXAMPLE.md Example 应用说明

快速开始 #

1. 添加依赖 #

dependencies:
  kinetic_player:
    path: ../kinetic_player   # 或 pub.dev / git 引用

2. 启用 Apple SPM(推荐,iOS / macOS) #

在应用与插件 pubspec.yaml 中:

flutter:
  config:
    enable-swift-package-manager: true

3. iOS / macOS(通常无需额外步骤) #

详见 doc/DARWIN_SGPLAYER.md。

SPM: 首次解析前执行 bash darwin/scripts/sgplayer/spm_prebuild_hook.sh ios,准备官方 v2.0.0 的 iOS/macOS 本地二进制目标。最低 iOS 15 / macOS 12。CocoaPods 会自动下载。原生控制栏和配置限制见 Darwin 文档。

4. 最小示例 #

import 'package:kinetic_player/kinetic_player.dart';

CommonVideoPlayerViewBuilder(
  url: 'https://example.com/video.mp4',
  creationParams: {
    ...const KineticUiConfig(
      showVolumeToolbar: true,
      showSettingsButton: true,
      pictureInPictureEnabled: true, // Android only
      locale: 'zh',
    ).toCreationParams(),
  },
  builder: (controller) {
    // controller 为 CommonVideoController,可按平台向下转型
  },
);

完整示例见 doc/EXAMPLE.md 与 example/ 目录。

HDR 测试链接 #

为避免重复维护,HDR 测试流统一维护在独立文档:

内核选型 #

按目标平台选内核即可;Windows / Linux 已内建 libmpv,不必再引入 GstPlayer。

目标平台 选用内核 说明
Android GSYVideoPlayer 默认自动选型
iOS / macOS SGPlayer 默认自动选型
Web Artplayer.js 默认自动选型
Windows / Linux libmpv 默认自动选型;详见 doc/DESKTOP_MPV.md

若你更需要 GStreamer 管线,仍可选用独立包 GstPlayer。

平台支持 #

平台 内核 真机 / 桌面 模拟器 / 浏览器 画中画
Android GSYVideoPlayer 14.0.0 ✅ ✅ ✅ 默认开启
iOS SGPlayer 2.0.0 ✅ ❌(FFmpeg 预编译仅 arm64 真机) ✅ SGPlayer 2
macOS SGPlayer 2.0.0 ✅ ✅(macosx xcframework) ✅ SGPlayer 2
Web Artplayer.js 5.4.0 — ✅ Chrome / Safari / 移动 Web ✅ Video PiP;Document PiP 可选
Windows libmpv(打包 DLL) ✅ x64 — ❌
Linux libmpv(系统库) ✅ — ❌

许可证 #

本插件代码采用 MIT License。

SGPlayer 为独立第三方项目,其许可证以 wanwenfeng4798/SGPlayer 仓库为准(fork 自 libobjc/SGPlayer)。

Windows 预编译 libmpv 为 LGPLv2.1+ 动态链接(见 doc/DESKTOP_MPV.md)。

支持 #

如果你觉得这个项目对你有帮助请支持我

支持

2
likes
160
points
688
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Multi-core Flutter video player: GSYVideoPlayer (Android) + SGPlayer (iOS/macOS) + Artplayer.js (Web) + libmpv (Windows/Linux).

Repository (GitHub)
View/report issues

License

MIT (license)

Dependencies

flutter, flutter_web_plugins, material_ui, web

More

Packages that depend on kinetic_player

Packages that implement kinetic_player