# FFmpeg Strategy

## 决策

Phase 1 使用独立构建的 **官方 FFmpeg upstream**，不把源码揉进 MPV，也暂不建立 `Velix-FFmpeg-Harmony`。

研究基线：FFmpeg master `3acec0a1af2dda0a0838689b8b8649e7deb080a0`（2026-08-28）。该 commit 已提供 OpenHarmony `ohcodec` hwcontext/pixel format 以及 H.264/HEVC decoder/encoder，显著降低自行 fork 的必要性。

## MPV 依赖约束

MPV 当前 Meson 最低要求：

| Library | 最低版本 |
|---|---:|
| libavcodec | 60.31.102 |
| libavfilter | 9.12.100 |
| libavformat | 60.16.100 |
| libavutil | 58.29.100 |
| libswresample | 4.12.100 |
| libswscale | 7.5.100 |

必须同时生成 pkg-config 文件供 MPV cross build 使用。

## 两种方案评估

### A. 官方 FFmpeg 独立构建（采用）

- 独立源码目录与安装前缀。
- arm64 OHOS toolchain 交叉编译。
- Phase 1 首先保留 software decode、demux、HTTP/HLS、字幕相关基础；OHCodec 可编译但不要求首次 MPV 构建即启用硬解。
- TLS 使用 FFmpeg 已支持并经过许可审核的第三方 backend（优先 OpenSSL）；Harmony `libnet_ssl.so` 不能直接替代。
- 优点：上游同步清晰、已有 OHCodec、MPV 仓库 patch 最小。

### B. Velix-FFmpeg-Harmony fork（暂不采用）

只有满足以下任一条件才触发：

1. 官方 OHCodec 在 API 24 上存在阻断编译/运行问题，且修复无法及时 upstream。
2. 需要 OHNativeBuffer/GPU import 或 HDR metadata 等实质性 FFmpeg API 扩展。
3. 网络/TLS 或 Harmony 生命周期需要不可在外部构建脚本解决的源码 patch。

建立后必须同样保留完整历史、配置 `upstream`、小 patch 分支，并单独维护许可证审计。

## Phase 1 建议配置轮廓

实际参数必须先由交叉编译探针和 FFmpeg `configure --help` 固化；以下是预计命令，不是已成功结果：

```sh
./configure \
  --prefix="$FFMPEG_PREFIX" \
  --target-os=linux \
  --arch=aarch64 \
  --cc="$OHOS_CLANG --target=aarch64-linux-ohos --sysroot=$OHOS_SYSROOT" \
  --cxx="$OHOS_CLANGXX --target=aarch64-linux-ohos --sysroot=$OHOS_SYSROOT" \
  --ar="$OHOS_LLVM_AR" \
  --strip="$OHOS_LLVM_STRIP" \
  --enable-cross-compile \
  --enable-pic \
  --enable-shared \
  --disable-programs \
  --disable-doc \
  --enable-network \
  --enable-openssl
```

注意：FFmpeg 当前 configure 未发现独立 `target-os=ohos` 结论，是否应使用 `linux` 必须由真实配置日志决定；编译器会同时定义 `__OHOS__` 与 `__linux__`。`--enable-ohcodec` 在首次软件解码 build 可暂缓，第二个受控构建再开启并验证其五个 Native media 库。

## 网络与 TLS

- HTTP/HLS 主要由 libavformat protocol/demuxer 提供，不新增 MPV 自定义网络栈。
- socket/DNS 可直接使用 OHOS libc。
- HTTPS 需要 FFmpeg 支持的 TLS backend。首选独立交叉构建 OpenSSL，并固定 CA bundle/系统证书策略；证书路径、SNI、代理、IPv6、重定向、Range 请求必须真机验证。
- 禁止将“SDK 有 `libnet_ssl.so`”写成“FFmpeg HTTPS 已支持”。

## 验收与 fork 决策点

1. `configure` 识别 arm64 OHOS、pthreads、network、dlopen。
2. 所需 FFmpeg libraries 完整生成，pkg-config 不泄漏宿主机路径。
3. software decode + HTTP/HLS 单测通过。
4. `--enable-ohcodec` 能链接 API 24 SDK，并枚举 `h264_oh` / `hevc_oh`。
5. 任何源码 patch 先形成最小 diff、根因、upstream 可接受性评估，再决定是否 fork。