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 不是首版必需。