Velix-MPV-Core/DOCS/HARMONY_CAPABILITY_RESEARCH.md

HarmonyOS Native Capability Research

1. 取证基线

• SDK：/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony
• Native / Toolchains：6.1.1.125，API 24
• 目标：aarch64-linux-ohos
• 编译器：OHOS Clang 15.0.4
• 最小头文件探针已通过：pthread、dlopen、mmap、epoll、poll、socket、DNS、EGL、GLES3、Vulkan、XComponent、OHAudio、Native AVCodec 可被同一 C translation unit 包含。
• 编译器预定义：__OHOS__、__linux__、__unix__、__aarch64__、__LP64__。EGL 平台头使用 OHOS_PLATFORM 选择 OHNativeWindow *，构建时必须显式定义该宏。

以下“最低 API”来自本机 API 24 SDK 头文件的 @since / availability；运行行为仍需 Phase 1/2 真机验证。

2. 能力矩阵

能力	C/C++ API / header	library	最低 API	生命周期与限制	结论
ArkUI Surface	OH_NativeXComponent_RegisterCallback；OnSurfaceCreated/Changed/Destroyed；ace/xcomponent/native_interface_xcomponent.h	libace_ndk.z.so	8	window 只在组件 Surface 生命周期内有效；销毁前停止渲染并释放 EGL/Vulkan surface	可用
Native Window	OHNativeWindow；native_window/external_window.h	libnative_window.so	8 起，部分新 buffer API 23	XComponent 回调交付 window；不得替换成 Android ANativeWindow	可用
Native Buffer	OH_NativeBuffer_*；native_buffer/native_buffer.h	libnative_buffer.so	11 起，具体函数不同	用于后续互操作；格式、usage、fence 必须真机查询	可用，Phase 0 不承诺零拷贝
OpenGL ES	<GLES2/gl2.h>、<GLES3/gl3.h>	libGLESv2.so / libGLESv3.so	SDK 基础能力	实际 GLES 版本、扩展、10-bit/HDR 格式按设备查询	可用
EGL	eglGetDisplay、eglCreateWindowSurface、eglSwapBuffers；<EGL/egl.h>	libEGL.so	SDK 基础能力	EGLNativeWindowType 在 OHOS_PLATFORM 下是 OHNativeWindow *；上下文线程归属必须固定	可用，首选渲染入口
Vulkan	VK_OHOS_surface、vkCreateSurfaceOHOS；<vulkan/vulkan.h> / vulkan_ohos.h	libvulkan.so	10	Surface 绑定 OHNativeWindow；扩展和 format 支持需设备枚举	可用，但不是 libmpv 公共 Render API
VSync	OH_NativeVSync_*；native_vsync/native_vsync.h	libnative_vsync.so	9	回调与 Surface 生命周期协调	可用，首版可先由 EGL swap/MPV 调度
Native Audio	OH_AudioStreamBuilder_*、OH_AudioRenderer_*；ohaudio/*.h	libohaudio.so	10	builder 生成 renderer 后销毁；renderer 使用写回调拉取 PCM；Start/Pause/Stop/Flush/Release 有明确状态机	可用，需新增 AO
Native Video Decoder	OH_VideoDecoder_*；multimedia/player_framework/native_avcodec_videodecoder.h	libnative_media_vdec.so、libnative_media_codecbase.so、libnative_media_core.so、libnative_window.so	9；buffer 新接口 11	Create→Configure→SetSurface→Prepare→Start；Seek 需要 Flush 后重启；输出可直接 RenderOutputBuffer 到 Surface	可用
Codec Capability	OH_AVCodec_GetCapability*、OH_AVCapability_*；native_avcapability.h	Native media libs	10	必须在目标设备查询硬件/软件、尺寸、帧率、profile/level；SDK 头不能证明某机型支持 4K/10-bit/HDR	可用，能力值待真机
POSIX file	open/read/write/stat；fcntl.h、unistd.h、sys/stat.h	libc	基础	受应用沙箱与授权 URI 限制；ArkUI picker URI/FD 需桥接到 native	可用但路径权限需集成层处理
Packaged rawfile	OH_ResourceManager_* / rawfile/*.h	librawfile.z.so	8 起	只适合包内资源，不是通用媒体文件系统	可用，不替代 POSIX file
pthread	pthread_create、mutex/cond；pthread.h	libc	基础	MPV threads-posix.c 可优先复用；线程名函数需 Meson 实测	可复用
socket	BSD sockets；sys/socket.h、netinet/in.h	libc	基础	需要网络权限；移动网络切换、IPv6、代理需真机测试	可复用
DNS	getaddrinfo/freeaddrinfo；netdb.h	libc	基础	DNS/网络切换错误传播由 FFmpeg 网络层处理	可复用
Native HTTP	OH_Http_*；network/netstack/net_http.h	libnet_http.so	20	与 FFmpeg AVIO 不直接兼容；不作为首版 MPV 网络栈	API 24 可用但不采用
TLS certificate verification	OH_NetStack_CertVerification 等；network/netstack/net_ssl/net_ssl_c.h	libnet_ssl.so	11	这是证书链验证接口，不是 FFmpeg TLS transport backend；首版需交叉构建 FFmpeg 支持的 TLS 库	系统验证能力可用，MPV 路径需第三方 TLS
Shared library	dlopen/dlsym/dlclose；dlfcn.h	libdl.a / libc	基础	插件路径和符号可见性受沙箱约束	编译可用，运行待测
Timer	clock_gettime、nanosleep；time.h	libc	基础	MPV timer-linux.c 实际只依赖这两个 POSIX API；源码应改名/条件化以免平台语义错误	可复用实现，需整理检测
Memory mapping	mmap/munmap；sys/mman.h	libc	基础	文件映射权限及大文件压力需真机测试	编译可用
poll / epoll	poll、epoll_*；poll.h、sys/epoll.h	libc	基础	头文件存在且探针通过；运行语义、FD 类型兼容性仍需测	可用，优先 POSIX poll
System information	uname、sysconf、getauxval；sys/utsname.h、unistd.h、sys/auxv.h；OH_GetDeviceType (deviceinfo.h)	libc / libdeviceinfo_ndk.z.so	API 10 起（DeviceInfo）	只用于诊断与保守能力探测，不按设备名硬编码功能	可用
CPU detection	AArch64 编译宏、getauxval；FFmpeg CPU detection	libc	基础	arm64 基线已有 NEON；不得未经实测强开额外 ISA	可复用
Lifecycle	XComponent Surface callbacks + N-API/ArkTS 页面生命周期桥接	libace_ndk.z.so / libace_napi.z.so	8	MPV Core 仅接受 surface attach/detach、pause/resume 等播放器级事件；业务生命周期留在宿主	需薄桥接
Power	系统 running lock / 后台任务 API主要由应用层管理	系统服务	版本依 API	Core 不自行申请长期后台权限；向宿主暴露播放状态，由宿主管理屏幕常亮/后台播放	不建 MPV backend

3. 直接可复用的 MPV/POSIX 区域

• osdep/threads-posix.c：pthread 基础满足。
• osdep/path-unix.c、osdep/language-posix.c：大部分 POSIX 路径/locale 逻辑可编译，沙箱路径语义需测试。
• osdep/timer-linux.c 的实现仅用 clock_gettime/nanosleep，能力可复用，但构建选择需改为 ohos 明确分支或重命名为 POSIX timer。
• socket、DNS、poll、mmap、dlopen 头文件均存在，先通过 feature detection，不因 __linux__ 自动宣称全部 Linux 特性可用。
• demux、字幕、滤镜、同步、命令和 libmpv client API 与平台无关，可直接复用。

4. 必须新增或调整的边界

1. Meson 增加 host_machine.system() == 'ohos' / features['harmony']，生成 HAVE_HARMONY，防止把 OHOS 的 __linux__ 等同桌面 Linux。
2. 新增 OHAudio AO，不能复用 Android AAudio/OpenSL ES。
3. 若构建 MPV 自管 VO，新增 Harmony EGL/Vulkan context；首版 Playback Lab 可由宿主持有 EGL context，使用 libmpv OpenGL Render API，减少 upstream patch。
4. 硬解需要 MPV 识别 FFmpeg 的 AV_PIX_FMT_OHCODEC 与 AV_HWDEVICE_TYPE_OHCODEC；该工作晚于软件解码首帧。
5. 日志可先复用 stderr；实验室集成阶段增加 HiLog sink，不能让日志 backend 阻塞首次构建。

5. 未验证项

• 各目标设备具体 Vulkan/GLES 扩展、HDR/10-bit swapchain、codec profile/level、最大分辨率/码率。
• epoll、dlopen、mmap 大文件在应用沙箱内的运行行为。
• 后台播放、音频焦点、路由切换、蓝牙延迟和 Surface 重建行为。
• Native HTTP/TLS 与系统代理/证书策略；首版按 FFmpeg + 独立 TLS 依赖验证。