kinetic_player 2.0.2

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

kinetic_player

English version: README_EN.md

最强大的跨平台 Flutter 视频播放器插件：Android 使用 GSYVideoPlayer 13.1.0，iOS / macOS 使用 wanwenfeng4798/SGPlayer（master），Web 使用 Artplayer.js 5.4.0；需要 Linux / Windows 时使用 GstPlayer（pub.dev，GStreamer）。

仓库：github.com/wanwenfeng4798/kinetic_player

平台预览

Android	iOS

macOS	Web

特性

• 统一的 CommonVideoController API（播放 / 暂停 / 跳转 / 缩放 / 倍速 / 音量 / 音轨 / 循环 / 截图等）
• 平台自动选型：Android → GSY，iOS / macOS → SGPlayer，Web → Artplayer；Linux / Windows → GstPlayer
• B 站风格原生控制栏：竖向音量弹窗（拖动显示百分比）、设置面板选音轨、统一进度条与底栏图标尺寸
• Android / iOS 支持滑动手势调进度 / 音量 / 亮度（enableNativeControls）；macOS 无滑动手势，用进度条 + 喇叭/齿轮按钮
• 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/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（推荐）： 插件已随包发布 Package.swift + 源码；Xcode 解析时按远程 binaryTarget 自动下载 SGPlayer.xcframework。macOS 请将 MACOSX_DEPLOYMENT_TARGET 设为 11.0+。若 Xcode 直编报包装包版本冲突，见 DARWIN_SGPLAYER.md 手动修改 FlutterGeneratedPluginSwiftPackage。

CocoaPods： pod install 经 prepare_command 调用 ensure_sgplayer.sh（下载预编译；失败再本地编译）。

维护者更新 Release / manifest 后重生成 Package.swift，或强制本地编译，见 Darwin 文档。

4. 最小示例

import 'package:kinetic_player/kinetic_player.dart';

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

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

HDR 测试链接

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

• 中文： doc/HDR_TEST_LINKS.md
• English: doc/HDR_TEST_LINKS_EN.md

内核选型

按目标平台选内核即可；需要支持 Linux 或 Windows 时，使用 GstPlayer（pub.dev/packages/gstplayer）。

目标平台	选用内核	说明
Android	GSYVideoPlayer	默认自动选型
iOS / macOS	SGPlayer	默认自动选型
Web	Artplayer.js	默认自动选型
Linux / Windows	GstPlayer	仅在需要 Linux 或 Windows 时选用（GStreamer；pub.dev）

仅做移动端 + Web 时用默认内核；一旦产品要覆盖 Linux / Windows 桌面，应走 GstPlayer，而不是 GSY / SGPlayer。

dependencies:
  gstplayer: ^0.0.1   # https://pub.dev/packages/gstplayer

平台支持

平台	内核	真机 / 桌面	模拟器 / 浏览器	画中画
Android	GSYVideoPlayer 13.1.0	✅	✅	✅ 默认开启
iOS	SGPlayer master	✅	❌（FFmpeg 预编译仅 arm64 真机）	❌
macOS	SGPlayer master	✅	✅（macosx xcframework）	❌
Web	Artplayer.js 5.4.0	—	✅ Chrome / Safari / 移动 Web	✅ Video PiP；Document PiP 可选
Linux / Windows	GstPlayer	✅（需系统 GStreamer）	—	视实现而定

许可证

本插件代码采用 MIT License。

SGPlayer 为独立第三方项目，其许可证以 wanwenfeng4798/SGPlayer 仓库为准（fork 自 libobjc/SGPlayer）。

支持

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