sm-emby-share/plugins/media3_engine/README.md

# media3_engine

`smplayer` 项目本地 Flutter plugin。**仅 Android**，包名 `com.smplayer.media3_engine`，
不发布到 pub.dev。Dart 侧通过约定好的 MethodChannel / EventChannel 与 native 通讯。

引擎实现位于主项目：
- Dart：`lib/core/infra/player_engine/media3_player_engine.dart`
- Kotlin：`plugins/media3_engine/android/src/main/kotlin/com/smplayer/media3_engine/`

## 版本锁定

| 组件 | 版本 |
|------|------|
| androidx.media | `1.10.1` |
| FFmpeg | `release/6.0` |
| Android NDK | `r27d` LTS (27.3.13750724) |
| Android `minSdk` | 24 |
| Android `compileSdk` | 36 |
| AGP / Kotlin / JDK | 8.11.1 / 2.2.20 / 17 |
| ABI | **arm64-v8a only**（包体最小化） |
| License | LGPL（不开 `--enable-gpl` / `--enable-nonfree`） |

升 Media3 / FFmpeg 版本前，先核对 `androidx/media @ <tag>/libraries/decoder_ffmpeg/README.md`
推荐的 NDK 与 FFmpeg branch，再调整 `scripts/build_media3_ffmpeg.sh` 默认值。

## 通道协议

### MethodChannel `smplayer/media3_engine`

| 方法 | 参数 | 返回 |
|------|------|------|
| `create` | – | `{playerId:int, textureId:int, ffmpegAvailable:bool, ffmpegVersion:string}` |
| `open` | `playerId, url, headers, startMs, play, generation` | 首次 `STATE_READY` 或 `PlaybackException` 后 complete |
| `play` / `pause` | `playerId` | – |
| `stop` | `playerId, generation` | – |
| `seek` | `playerId, positionMs` | – |
| `setRate` | `playerId, rate` (float) | – |
| `setVolume` | `playerId, volume` (0..200) | – |
| `setAudioTrack` | `playerId, id` (`audio:<g>:<t>` / `auto` / `no`) | – |
| `setSubtitleTrack` | `playerId, id` (`text:<g>:<t>` / `auto` / `no`) | – |
| `setSubtitleStyle` | `playerId, fontSize, bgOpacity, position` | – （首版 no-op，cue 由 Dart 渲染） |
| `getProperty` | `playerId, name` | `string`（`ffmpegAvailable` / `ffmpegVersion` / `audioRenderer` / `playbackState`） |
| `dispose` | `playerId` | – |

### EventChannel `smplayer/media3_engine/events`

所有事件载荷形如 `{playerId, generation, type, ...}`，Dart 侧按 `playerId` 过滤、
按 `generation` 丢弃过期事件。

| `type` | payload |
|--------|---------|
| `position` | `{positionMs, bufferMs}` |
| `duration` | `{durationMs}` |
| `playing` | `{playing}` |
| `completed` | `{}` |
| `videoSize` | `{width, height}` |
| `tracks` | `{audio:[{id,index,title,language}], subtitle:[…]}` |
| `subtitle` | `{lines:[string]}` |
| `volume` | `{volume}`（保留，目前 native 不主动 emit） |
| `error` | `{code, message}` |

Generation token 语义：Dart 端每次 `open / stop / dispose` ++ generation，native
回调先比对此值，过期事件丢弃。这保证了 cancel / reopen 时不会有迟到的 STATE_READY
污染新 session 的状态。

## FFmpeg 软解 codec 列表

`scripts/build_media3_ffmpeg.sh` 的 `ENABLED_DECODERS` 默认：

| 解码器名（FFmpeg） | 实际格式 |
|-------------------|----------|
| `dca` | DTS / DTS-HD / DTS-HD MA |
| `ac3` | AC3 |
| `eac3` | E-AC3 (Dolby Digital Plus) |
| `truehd` | Dolby TrueHD（含 Atmos 元数据，但 Atmos 渲染依赖宿主 audio sink） |
| `opus` | Opus |
| `vorbis` | Vorbis |
| `flac` | FLAC |

视频解码不在范围——交给平台 MediaCodec 硬解。容器解析与音频帧 parser 由 ExoPlayer
自身处理，FFmpeg 扩展只补 decoder（无需 `--enable-parser` / `--enable-demuxer`）。

## 编译 AAR

> **前置硬约束**：`android/app/libs/media3-decoder-ffmpeg-1.10.1-arm64.aar` 是
> Android 构建的硬依赖。仓库默认不提交该 AAR 二进制；缺文件时 plugin 的
> `preBuild` 任务 `verifyMedia3FfmpegAar` 会 fail-fast 抛错并给出本节的恢复
> 指令。CI / Clean checkout 都必须先编出 AAR 才能 `flutter build apk`。

### 前置

- macOS / Linux host（Apple Silicon 建议通过 Docker `linux-x86_64` 容器编译以规避
  Media3 README 未文档化的 darwin-arm64 行为）
- Android NDK r27d (LTS)：从 https://developer.android.com/ndk/downloads 安装；Media3 1.10.1 README 实测版本是 r26b，r27 ABI 兼容、社区已验证可编
- `perl`, `make`, `yasm`, `git`, `python3`, `shasum`（macOS 自带；Linux 需手装 yasm）
- JDK 17 + Android SDK（命令行工具足够，Android Studio 非必需）

### 步骤

```sh
# 1. 设置 NDK 路径（或用 --ndk-path 参数）
export ANDROID_NDK_HOME=/path/to/android-ndk-r27d

# 2. 跑脚本（首次约 30-60 分钟，取决于 host CPU / IO）
./scripts/build_media3_ffmpeg.sh

# 3. 产物
#    android/app/libs/media3-decoder-ffmpeg-1.10.1-arm64.aar
#    android/app/libs/CHECKSUMS.txt 自动追加 / 替换该 AAR 的 SHA-256
#
# 4. 核对 SHA-256 → git add 上述两个文件 → flutter build apk --debug 验证加载
```

### 重新编译 / 升级版本

```sh
# 完全清空工作区重新拉取（覆盖 androidx/media + FFmpeg 缓存）
./scripts/build_media3_ffmpeg.sh --clean

# 升 Media3 tag
./scripts/build_media3_ffmpeg.sh --clean --media3-tag 1.11.0

# 升 FFmpeg branch
./scripts/build_media3_ffmpeg.sh --clean --ffmpeg-branch release/6.1
```

脚本会在 `libraries/decoder_ffmpeg/src/main/jni/build_ffmpeg.sh` 上幂等地打一次
sed patch，把上游默认的 4 ABI 限制到 arm64-v8a only。`--clean` 会清空 patch 与缓存。

### Docker 复现编译（推荐 Apple Silicon）

```sh
docker run --rm -it \
  -v "$(pwd)":/work \
  -e ANDROID_NDK_HOME=/opt/android-ndk-r27d \
  -w /work \
  cimg/android:2024.05.1-ndk \
  scripts/build_media3_ffmpeg.sh
```

镜像版本以 r27d NDK 实际可用性为准；上面只是一个起点示意。

## 已知限制

| 限制 | 说明 / 解决路径 |
|------|----------------|
| **位图字幕**（PGS / VobSub） | onCues 检出后 emit 空文本 + `error: 'subtitle_bitmap_unsupported'`；建议改外挂 SRT/ASS 或切回 fvp |
| **音量 boost**（100 < volume ≤ 200） | ExoPlayer `volume` 上限为 1.0；本插件把 100..200 段静默截断到 1.0。Dart 端 `state.volume` 保留原值（UI 一致），但物理音量不会更大 |
| **HDR / DV** | 路由层显式排除（`resolvePlayerEngineKind` 在 DV/ProRes 下回退 fvp）；media3 视频走 MediaCodec，DV 元数据未被特殊处理 |
| **iOS / 桌面** | plugin 仅声明 Android 平台，构造层 `Platform.isAndroid` 守卫；UI 层桌面隐藏 media3 选项 |
| **PiP / MediaSession / Cast** | 不实现（范围外）；播放在前台 Activity 内完成 |
| **DRM / Widevine** | 不实现（范围外） |
| **FFmpeg AAR 体积** | 约 12-15 MB / arm64-v8a；release APK 增量约 ≤ 30 MB |

## 平台守卫四层

1. **枚举层**：`PlayerEngineOverride.media3` / `PlayerEngineKind.media3` 在所有平台编译通过（inert）
2. **路由层**：`resolvePlayerEngineKind` 在 desktop 把 media3 降级为 mpv
3. **构造层**：`Media3PlayerEngine` 构造函数 `assert(Platform.isAndroid)`，否则抛 `UnsupportedError`
4. **UI 层**：`PlayerEngineRow.visibleOptions` 过滤 + `coerceValue` 持久化值降级

任一层失守，其它层仍能阻止 native crash。