Kinetic Player

kinetic_player

English version: README_EN.md

最强大的移动端 Android / iOS / macOS Flutter 视频播放器插件：Android 使用 GSYVideoPlayer 13.1.0，iOS / macOS 使用 wanwenfeng4798/SGPlayer（master）。

仓库：github.com/wanwenfeng4798/kinetic_player

特性

  • 统一的 CommonVideoController API（播放 / 暂停 / 跳转 / 缩放 / 倍速 / 音量 / 音轨 / 循环 / 截图等）
  • 平台自动选型：Android → GSY，iOS / macOS → SGPlayer
  • B 站风格原生控制栏：竖向音量弹窗（拖动显示百分比）、设置面板选音轨、统一进度条与底栏图标尺寸
  • iOS / macOS 支持滑动手势调进度 / 音量 / 亮度（与 Android 共用 enableNativeControls）
  • Android 画中画（PiP）默认开启（API 26+；播放中切后台自动进入，含 GSY 自动播放场景）
  • 独有功能通过显式向下转型调用（不污染公共接口）
  • iOS / macOS 支持 CocoaPods 与 Swift Package Manager (SPM)；脚本与产物统一在 darwin/
  • 预编译 SGPlayer.xcframework 可通过 GitHub Release 下载，避免本地编译

文档

文档 说明
doc/USAGE.md 集成步骤、公共 API、原生 UI、平台差异、PiP 配置
doc/GSY_FEATURES.md Android GSY 高级能力对照表
doc/EXAMPLE.md Example 应用说明
doc/DARWIN_SGPLAYER.md iOS / macOS SGPlayer：二进制、脚本、SPM、Release

快速开始

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. 准备 SGPlayer 二进制（iOS / macOS）

详见 doc/DARWIN_SGPLAYER.md。

SPM（推荐）： Package.swift 远程 binaryTarget 由 Xcode 解析时下载；Example Scheme Pre-action 再跑钩子（同步 checksum + ensure 本地产物）。

手动 / CI：

bash kinetic_player/darwin/scripts/sgplayer/spm_prebuild_hook.sh ios
bash kinetic_player/darwin/scripts/sgplayer/spm_prebuild_hook.sh macos

或 CocoaPods：pod install 经 prepare_command 调用 ensure_sgplayer.sh。

备选： 本地源码编译（约 30–60 分钟，仅首次）

bash kinetic_player/darwin/scripts/sgplayer/build_sgplayer.sh ios
bash kinetic_player/darwin/scripts/sgplayer/build_sgplayer.sh macos

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 测试流统一维护在独立文档：

平台支持

平台 内核 真机 模拟器 画中画
Android GSYVideoPlayer 13.1.0 ✅ ✅ ✅ 默认开启
iOS SGPlayer master ✅ ❌（FFmpeg 预编译仅 arm64 真机） ❌
macOS SGPlayer master ✅ ✅（macosx xcframework） ❌

许可证

本插件代码采用 MIT License。

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

Libraries

kinetic_player