# FFmpegKit (full-gpl) 归档与放置说明

本项目用 ffmpeg-kit 在 Android 端做 H.264/裸流 → MP4 转码(libx264 重编码),
以修复各设备(如 OPPO/MTK)解码器对坏 PPS 流播放卡死的问题。

## 依赖来源

- Maven: `dev.ffmpegkit-maintained:ffmpeg-kit-full-gpl:6.0.3`
  (原 `com.arthenica:ffmpeg-kit-full` 已于 2025-04 从 Maven Central 下架;`full` 不含 x264,必须用 `full-gpl`)
- FFmpeg 内部版本: **n6.1.6**
- 含 libx264(重编码用)
- 仅 arm64-v8a(项目只发布 arm64)

本目录 `ffmpeg-kit-full-gpl-6.0.3.aar` 即下载的原始包(36.6MB),作为来源/备份。

## 运行时文件位置(勿乱动!)

Unity Android 对 native 库与 jar 的打包位置有强约束,放错地方会导致 APK 缺少
native 库或类,运行时 `UnsatisfiedLinkError`/`ClassNotFoundException`。请**保持现状**:

- `.so` → `Assets/Plugins/Android/jniLibs/arm64-v8a/`
  - libavcodec / libavdevice / libavfilter / libavformat / libavutil
  - libswresample / libswscale
  - libffmpegkit / libffmpegkit_abidetect
  - **libc++_shared.so(必带,full 构建的 C++ 运行时依赖)**
- 类包 → `Assets/Plugins/Android/libs/ffmpeg-kit-classes.jar`
  (由 `Assets/Plugins/Android/mainTemplate.gradle` 的
  `implementation files('libs/ffmpeg-kit-classes.jar')` 引用)

## 调用链

- C# 桥接: `Assets/Scripts/Video/FFmpegKitBridge.cs`
  - `#if UNITY_ANDROID && !UNITY_EDITOR`(Android 专用)
  - JNI 必须在 Unity 主线程执行:经由 `MainThreadDispatcher.cs` 派发
  - 转码参数: `-c:v libx264 -preset ultrafast -crf 23 -pix_fmt yuv420p -movflags +faststart -fflags +genpts`
- 视频页: `Assets/Scripts/UI/Pages/VideoPage/VideoPageCtrl.cs`
- 下载/播放服务: `Assets/Scripts/Video/VideoDownloadPlayService.cs`

## 升级方法

1. 重新下载目标版本 aar。
2. 解压,用 `jni/arm64-v8a/*.so` 整体覆盖上面 jniLibs 目录(含 libc++_shared.so)。
3. 用 aar 内 `classes.jar` 覆盖 libs/ 下的 jar。
4. clean 重建 release(不要增量)。

## 备注

- x264 为 GPL,与服务端已用的 libx264 转码策略一致,License 口径以项目自身为准。
- 播放验证关键日志:
  - `[VideoDownloadPlayService]` -> `[FFmpegKitBridge] args`(确认含 `libx264`)
  - `rc=` `isSuccess=True`、`[ProbeMp4Info]` mp4 正常尺寸
  - `[vf-3]` VideoPrepared 的 frameCount / length 正常
  - 播放过程不应再出现长时间卡帧。