Velix-MPV-Core/DOCS/PORTING_PLAN.md

# HarmonyOS Porting Plan

## 1. 源码扫描结论

MPV 核心播放、demux、filter、subtitle、A/V sync、command、client API 基本跨平台。平台耦合集中在 `meson.build`、`osdep/`、`audio/out/`、`video/out/`、`video/decode/` 与 hwdec interop。当前仓库搜索不到 Harmony/OHOS 代码。

MPV 当前检测逻辑 `posix = not win32`；非 Darwin POSIX 自动选择 `osdep/timer-linux.c`。OHOS 编译器同时定义 `__OHOS__` 与 `__linux__`，因此所有 Linux feature 必须由 Meson probe 或显式 Harmony gate 决定，不能只看 `__linux__`。

## 2. 文件级移植矩阵

| MPV source / file | 当前依赖 API / 行为 | HarmonyOS 替代或复用 | Patch | 风险 | 阶段 | 工作量 |
|---|---|---|---:|---|---|---|
| `meson.build` OS detection | win32/darwin/posix/android/linux 分支 | 增加 `ohos = host_machine.system() == 'ohos'`、`features['harmony']`、config `HAVE_HARMONY` | 是 | 高 | P1-01 | 1–2d |
| `meson.build` platform sources | 非 Darwin POSIX选 Linux timer；Android 单独 EGL/media | 为 OHOS 明确选择 POSIX可复用源、Harmony AO/可选 context；不进入 Android 分支 | 是 | 高 | P1-01 | 1d |
| `osdep/threads-posix.c` | pthread、cond、mutex、TLS | 直接使用 SDK `pthread.h`；线程名由 feature probe | 预计否/小 | 中 | P1-02 | 0.5–1d |
| `osdep/timer-linux.c` | `clock_gettime`、`nanosleep` | API均可用；可先明确选该实现，后续重命名/拆成 POSIX timer 以便 upstream | 小 | 低 | P1-02 | 0.5d |
| `osdep/path-unix.c` | POSIX paths、HOME/XDG 等桌面约定 | 文件 API复用；应用 data/cache 路径最终由宿主注入，不能依赖 HOME | 小/后续 | 中 | P1-03 | 1–2d |
| `osdep/language-posix.c` | locale/environment | 先复用；设备语言由宿主 API注入作为后续增强 | 预计否 | 低 | P1-03 | 0.5d |
| `osdep/subprocess-posix.c` | fork/exec/process | Harmony app 不需要 subprocess；若 probe失败明确选 `subprocess-dummy.c` 并返回 unsupported | 小 | 中 | P1-03 | 0.5d |
| `osdep/terminal-unix.c` | tty/terminal | libmpv build 不需要交互 terminal；cplayer关闭 | 配置 | 低 | P1-01 | 0.2d |
| `input/ipc-unix.c` | Unix domain socket | 首版 libmpv 可关闭/保留按 probe；产品 API不暴露 IPC | 小/配置 | 低 | P1-03 | 0.5d |
| `stream/` + FFmpeg AVIO | POSIX socket、DNS、FFmpeg HTTP/TLS | socket/DNS复用；HTTP/HLS由 FFmpeg；TLS 使用交叉构建 OpenSSL | MPV 否 | 高 | P1-04 | 3–5d |
| `demux/demux_lavf.c` | libavformat | 直接复用官方 FFmpeg OHOS build | 否 | 中 | P1-04 | 1d 验证 |
| `sub/`、`sub/osd_libass.c` | libass、字体栈 | 直接复用；字体发现/应用字体目录需配置验证 | 小/配置 | 中 | P1-05 | 2–3d |
| `include/mpv/client.h` | libmpv C API | 直接复用仅作内部依赖；最终 Velix API再封装 | 否 | 低 | P1 | 0.5d |
| `include/mpv/render*.h` | OpenGL / software public render API | 直接使用 OpenGL API；宿主提供 GLES proc resolver/FBO | 否 | 中 | P2-01 | 2–4d lab glue |
| `video/out/vo_libmpv.c` | libmpv render bridge | 直接复用 | 预计否 | 中 | P2-01 | 1d 验证 |
| `video/out/opengl/libmpv_gl.c` | OpenGL Render API | 直接复用 GLES/EGL context；验证所需 GL symbols | 小/预计否 | 中 | P2-01 | 2d |
| `video/out/opengl/context*.c` | Android/X11/Wayland/DRM/Windows context | 首版 libmpv plain-gl 不新增；如 MPV自管 context，再新增 `context_harmony.c` | 后续 | 中 | P2-02 | 3–5d |
| `video/out/vulkan/context.c` | libplacebo/Vulkan context registry | 若采用 Vulkan新增 `context_harmony.c`，调用 `vkCreateSurfaceOHOS` | 后续是 | 高 | P4 | 7–12d |
| `audio/out/ao.c` | AO driver registry | 注册 `audio_out_harmony` | 是 | 低 | P2-03 | 0.5d |
| `audio/out/ao_aaudio.c` | Android AAudio callback模型 | 仅作结构参考；实际新增 `ao_harmony.c` 使用 OHAudio | 新文件 | 高 | P2-03 | 5–8d |
| `audio/out/buffer.c` | MPV AO buffering | 直接复用，由 OHAudio callback消费 | 预计否 | 中 | P2-03 | 1–2d 验证 |
| `video/fmt-conversion.c` | FFmpeg pixfmt↔MPV imgfmt | 增加 `AV_PIX_FMT_OHCODEC` 映射前先确认 MPV image semantics | 后续是 | 高 | P3-02 | 1–2d |
| `video/decode/vd_lavc.c` | hw device选择、frames | 加入 `AV_HWDEVICE_TYPE_OHCODEC` 并传递 native window/device ctx | 后续是 | 高 | P3-02 | 3–6d |
| `video/out/gpu/hwdec.c` | GPU interop registry | 注册 Harmony interop driver，仅在真实 buffer import 方案明确后 | 后续是 | 极高 | P3-03 | 7–15d |
| `video/out/hwdec/` | VAAPI/DRM/VT/Android interop | 新增隔离的 `hwdec_ohcodec.c`，不散落 OHOS ifdef | 后续是 | 极高 | P3-03 | 10–20d |
| `video/out/opengl/egl_helpers.c` | 通用 EGL config/context helpers | 优先复用；验证 GLES profile、10-bit config、context loss | 可能小 | 中 | P2-01 | 2d |
| `misc/io_utils.c` / poll wrapper | poll/FD helper | POSIX poll 复用；epoll不作为无证据优化 | 预计否 | 低 | P1-02 | 0.5d |
| logging (`common/msg.c`) | stderr/terminal | 首编译复用；lab阶段加 HiLog adapter，不能替换核心 logger | 后续小 | 低 | P2 | 1–2d |

## 3. 分阶段执行

### P1：First Build

1. P1-01：Meson 识别 OHOS，构建只产 libmpv。
2. P1-02：逐项编译 POSIX 基础层；每个 blocker 单独记录。
3. P1-03：明确 subprocess/IPC/path 不支持或可复用边界。
4. P1-04：构建 FFmpeg software decode + network + TLS。
5. P1-05：构建 libass/font stack、libplacebo，链接 libmpv。

门禁：AArch64 libmpv 真实产物、导出符号、依赖清单、无 Android API、无宿主机库。

### P2：Playback Lab 基线

XComponent + EGL + libmpv OpenGL Render API；新增 OHAudio AO；URL/local file、play/pause/seek/stop/release、日志和基础 metrics。无正式产品 UI。

### P3：硬件解码

先验证 FFmpeg `h264_oh` / `hevc_oh`，再决定 direct surface 或 GPU import。所有优化必须对比软件解码基线。

### P4：定点性能与 Vulkan

只有 Benchmark 证明 GLES/上传或合成是瓶颈时，研究 Vulkan/HDR/zero-copy；每个 patch 必须有前后数据。

## 4. 可直接复用与必须新增

可直接复用：libmpv client/render API、player core、demux、software decode glue、filters、A/V sync、subtitle/libass、playlist/property/command、POSIX threads/timer/socket/DNS/poll/mmap 的已验证子集、OpenGL renderer。

必须新增：Harmony Meson detection、OHAudio AO、Playback Lab 的 XComponent/EGL native glue。硬解阶段预计新增 OHCodec image/device/interoperability backend。Vulkan context 不是首版必需。