docs: complete HarmonyOS phase 0 research

DOCS/BUILD_STRATEGY.md

@@ -0,0 +1,126 @@
+# First Build Strategy
+
+## 1. 目标与非目标
+
+Phase 1 第一目标仅为：以 HarmonyOS API 24 arm64 工具链构建尽可能原始的 upstream MPV，产出 `libmpv` 及必需 Native libraries。不是播放视频、UI、硬解、HDR 或性能优化。
+
+## 2. 已确认工具链
+
+```text
+SDK root   /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony
+version    6.1.1.125 / API 24
+sysroot    <SDK root>/native/sysroot
+CC         <SDK root>/native/llvm/bin/clang
+CXX        <SDK root>/native/llvm/bin/clang++
+AR         <SDK root>/native/llvm/bin/llvm-ar
+RANLIB     <SDK root>/native/llvm/bin/llvm-ranlib
+STRIP      <SDK root>/native/llvm/bin/llvm-strip
+LD         <SDK root>/native/llvm/bin/ld.lld
+target     aarch64-linux-ohos
+compiler   OHOS Clang 15.0.4
+```
+
+本机当前没有 `meson`、`ninja`、`pkg-config` 命令。Phase 1 必须先安装并记录版本；不能把 DevEco CMake 当作 MPV 的 Meson 替代品。
+
+## 3. Meson cross file
+
+建议新增仓库内 `toolchains/ohos-api24-arm64.ini`，路径允许通过环境生成而非硬编码提交个人目录。预计内容：
+
+```ini
+[binaries]
+c = '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/llvm/bin/clang'
+cpp = '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/llvm/bin/clang++'
+ar = '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/llvm/bin/llvm-ar'
+strip = '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/llvm/bin/llvm-strip'
+pkg-config = 'pkg-config'
+
+[built-in options]
+c_args = ['--target=aarch64-linux-ohos', '--sysroot=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/sysroot', '-DOHOS_PLATFORM']
+cpp_args = ['--target=aarch64-linux-ohos', '--sysroot=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/sysroot', '-DOHOS_PLATFORM']
+c_link_args = ['--target=aarch64-linux-ohos', '--sysroot=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/sysroot']
+cpp_link_args = ['--target=aarch64-linux-ohos', '--sysroot=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/sysroot']
+
+[host_machine]
+system = 'ohos'
+cpu_family = 'aarch64'
+cpu = 'armv8-a'
+endian = 'little'
+
+[properties]
+needs_exe_wrapper = true
+```
+
+`OHOS_PLATFORM` 是本机 EGL header 选择 `OHNativeWindow *` 的条件；编译器只自动定义 `__OHOS__`。`PKG_CONFIG_LIBDIR` 必须只包含 OHOS staging prefix 的 pkgconfig 路径，禁止找到 macOS 宿主库。
+
+## 4. 依赖顺序
+
+1. 建立独立 staging prefix，例如 `build/ohos-arm64/prefix`。
+2. zlib：优先使用 SDK `libz.so`；验证 Meson/pkg-config 可见性。
+3. TLS：交叉构建锁版 OpenSSL，确认 CA 策略和许可证。
+4. FFmpeg：先 software decode/network 版本；再受控开启 `--enable-ohcodec`。
+5. FreeType → HarfBuzz/FriBidi → libass。
+6. libplacebo：首版只开启 MPV 所需最小能力；Vulkan 可暂关，保留 GLES/OpenGL 方向。
+7. MPV：只构建 libmpv，关闭不适用桌面平台 backend。
+
+每个依赖必须安装 `.pc` 到 staging prefix；静态依赖需要 `Libs.private` 完整。
+
+## 5. MPV 最小 Patch 前的预计配置
+
+以下命令是 Phase 1 设计，不是编译成功声明：
+
+```sh
+PKG_CONFIG_LIBDIR="$OHOS_PREFIX/lib/pkgconfig:$OHOS_PREFIX/share/pkgconfig" \
+meson setup build/ohos-arm64/mpv \
+  --cross-file toolchains/ohos-api24-arm64.ini \
+  --prefix "$OHOS_PREFIX" \
+  --default-library shared \
+  -Dcplayer=false \
+  -Dlibmpv=true \
+  -Dtests=false \
+  -Dfuzzers=false \
+  -Dplain-gl=enabled \
+  -Degl=enabled \
+  -Dvulkan=disabled \
+  -Dx11=disabled \
+  -Dwayland=disabled \
+  -Ddrm=disabled \
+  -Dgbm=disabled \
+  -Dalsa=disabled \
+  -Dpipewire=disabled \
+  -Dpulse=disabled \
+  -Djack=disabled \
+  -Doss-audio=disabled \
+  -Dsndio=disabled \
+  -Daaudio=disabled \
+  -Daudiotrack=disabled \
+  -Dopensles=disabled \
+  -Dcocoa=disabled \
+  -Dd3d11=disabled \
+  -Ddirect3d=disabled \
+  -Dwasapi=disabled \
+  -Dcuda-hwaccel=disabled \
+  -Dvaapi=disabled \
+  -Dvdpau=disabled \
+  -Dandroid-media-ndk=disabled \
+  -Dlibcurl=disabled \
+  -Djavascript=disabled \
+  -Dlua=disabled \
+  -Dmanpage-build=disabled
+
+meson compile -C build/ohos-arm64/mpv -v
+```
+
+首次 configure 前需要先增加最小 `ohos` OS detection，否则 MPV 会把它归为泛 POSIX并选择 Linux timer；应一次修一个 blocker并记入 `DOCS/BUILD_ISSUES.md`。
+
+## 6. 预计 Native 链接库
+
+基础：libc/libm、pthread、dl、z。渲染集成阶段：EGL、GLESv3 或 GLESv2、native_window、ace_ndk。音频阶段：ohaudio。硬解阶段：native_media_vdec、native_media_codecbase、native_media_core、native_window。日志可选 hilog_ndk。
+
+不得在 Phase 1 把尚未使用的全部 SDK 库一次性链接进去。
+
+## 7. Blocker 处理与验收
+
+- 创建 `DOCS/BUILD_ISSUES.md`，每个原始错误独立编号；一个 patch 对应一个根因。
+- 禁止批量 `#ifdef` 掉 core、fake success 或空 backend。
+- 产物验收：架构为 AArch64；动态依赖无 macOS/Android 库；导出 libmpv public symbols；记录尺寸、warnings、耗时、enabled/disabled features。
+- 完成后生成 `DOCS/MPV_BUILD_REPORT.md`；当前 Phase 0 不提前创建伪报告。

DOCS/FFMPEG_STRATEGY.md

@@ -0,0 +1,81 @@
+# 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。

DOCS/HARMONY_AUDIO_RESEARCH.md

@@ -0,0 +1,57 @@
+# HarmonyOS Audio Research
+
+## 1. 推荐方案
+
+新增 MPV 音频输出 `ao_harmony`，直接接 HarmonyOS OHAudio：
+
+```text
+MPV audio pipeline -> native PCM ring/buffer -> OHAudio write callback -> AudioRenderer
+```
+
+禁止 PCM 逐块跨 N-API/ArkTS。ArkTS 只发送播放器级控制和生命周期事件。
+
+## 2. SDK 依据
+
+- headers：`ohaudio/native_audiostreambuilder.h`、`native_audiorenderer.h`、`native_audiostream_base.h`、`multimedia/native_audio_channel_layout.h`
+- library：`libohaudio.so`
+- baseline：API 10
+- builder：采样率、声道数、sample format、encoding、latency mode、channel layout、usage、write callback、callback frame size
+- renderer：Start、Pause、Stop、Flush、Release、timestamp、frames written、volume、speed、underflow count、latency
+
+API 24 还提供 advanced callback 等新接口，但首版使用最低且稳定的 callback API，避免无必要抬高最低版本。
+
+## 3. 与 MPV AO 的映射
+
+| MPV / 播放需求 | OHAudio 映射 | 设计 |
+|---|---|---|
+| PCM 格式协商 | `SetSamplingRate`、`SetChannelCount/Layout`、`SetSampleFormat` | `init()` 将 MPV `ao->format` 映射为 OHAudio；不支持时返回 unsupported，让 MPV 重采样 |
+| 数据输出 | renderer write callback | 回调只读取 MPV AO buffer，禁止阻塞、分配大对象或调用 ArkTS |
+| Pause/Resume | `OH_AudioRenderer_Pause/Start` | 与 MPV `control()` 状态串行化 |
+| Stop/Seek | `Stop/Flush/Start` | Seek 时丢弃旧 PCM，并重建 MPV A/V sync 基准 |
+| Volume | `OH_AudioRenderer_SetVolume` | 首版支持 0..1；MPV 软件音量仍可用，避免重复增益 |
+| Speed | MPV 音频滤镜为主 | 不直接用 Renderer speed 改变 MPV 时钟；系统 speed 仅后续专项验证 |
+| A/V Sync | `GetTimestamp` / `GetFramesWritten` | 驱动 delay 由已提交帧与硬件播放位置计算，必须做单调性/路由切换测试 |
+| 低延迟 | `SetLatencyMode` | 视频播放默认 normal；fast 仅在设备支持和稳定性测试后启用 |
+| 多声道 | channel layout + capability | 先 stereo；5.1/7.1 按设备能力协商，失败回退重混音，不 fake success |
+
+## 4. MPV 接入位置
+
+- 新文件建议：`audio/out/ao_harmony.c`。
+- 注册位置：`meson.build` 的 audio outputs 区域和 `audio/out/ao.c` driver list。
+- 参考结构：`ao_aaudio.c` 的 callback/pull 模式及状态控制；不能复制其 Android API。
+- OHAudio callback 与 MPV AO buffer 的线程安全遵循 `audio/out/buffer.c` 现有模型；回调只消费系统请求的 frame 数。
+
+## 5. 格式策略
+
+首版候选优先级：float32（若稳定支持）→ signed 16-bit。采样率优先内容原始值，设备拒绝则让 MPV/libswresample 转为 48 kHz。声道首版 2.0，随后验证 5.1/7.1。所有实际支持值通过 builder 创建结果与设备行为确认，不从枚举存在推断硬件支持。
+
+## 6. 风险与验证
+
+1. write callback 的实时线程约束和最大执行时间。
+2. `GetTimestamp` 在暂停、Flush、蓝牙/有线切换后的连续性。
+3. underrun、首包预填充与首音频时间。
+4. Surface 暂停但音频继续、应用后台、音频焦点中断。
+5. 播放速度与 MPV 时钟双重调整风险。
+6. 多声道 layout 枚举和实际设备 route 不一致。
+
+首版验收：PCM 正常播放；pause/resume/seek 无旧音频泄漏；1 小时无死锁；统计 underrun；A/V sync 偏差有真实测量。未完成这些测试前不宣称低延迟或多声道完成。

DOCS/HARMONY_CAPABILITY_RESEARCH.md

@@ -0,0 +1,65 @@
+# 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 依赖验证。

DOCS/HARMONY_HWDEC_RESEARCH.md

@@ -0,0 +1,64 @@
+# HarmonyOS Hardware Decode Research
+
+## 1. 关键发现
+
+截至 FFmpeg 官方 master `3acec0a1af2dda0a0838689b8b8649e7deb080a0`（2026-08-28），upstream 已包含 OpenHarmony Codec：
+
+- configure：`--enable-ohcodec`
+- hw device：`AV_HWDEVICE_TYPE_OHCODEC`
+- pixel format：`AV_PIX_FMT_OHCODEC`
+- public device context：`AVOHCodecDeviceContext.native_window`
+- decoder/encoder：`h264_oh`、`hevc_oh`
+- SDK linkage：`native_media_vdec`、`native_media_venc`、`native_media_codecbase`、`native_media_core`、`native_window`
+
+其 surface 路径把 `OHNativeWindow *` 放入 hw device，FFmpeg 配置 `AV_PIXEL_FORMAT_SURFACE_FORMAT`，并在 AVFrame release 时调用 `OH_VideoDecoder_RenderOutputBuffer()`。因此“不存在 FFmpeg Harmony hwcontext”已不是事实；当前缺口主要转移到 MPV 对 OHCODEC 的识别、Surface 所有权和呈现同步。
+
+## 2. Codec 矩阵
+
+| Codec | Harmony Native Support | FFmpeg Support | MPV Support | Surface Decode | Pixel Format | Copy | Zero Copy Feasibility | 10-bit / HDR | Known Limitation | Complexity |
+|---|---|---|---|---|---|---|---|---|---|---|
+| H.264 | Native decoder API 存在；具体 profile/4K 由设备 capability 查询 | `h264_oh` 已在 upstream master | 无 OHCODEC 映射/backend | 已实现 | `AV_PIX_FMT_OHCODEC` / surface format | 解码器到 Surface 可避免 CPU frame；是否经过系统内部 copy 不可见 | 高，但直出播放 Surface 与 MPV shader/字幕合成冲突 | 设备查询；H.264 10-bit 通常不作为首要目标，不能猜 | FFmpeg 实现新、MPV 未接入、字幕/OSD 合成路径未解决 | 高 |
+| HEVC | Native decoder API 存在；profile/level/10-bit 待设备查询 | `hevc_oh` 已在 upstream master | 无 OHCODEC 映射/backend | 已实现 | 同上 | 同上 | 高 | Main10/HDR 必须按真机 capability + 实际流验证 | HDR metadata 传递和 Surface colorspace 未证明 | 高 |
+| AV1 | SDK API 可按 MIME 查询，不代表设备必有硬件 | 当前 OHCodec backend 未声明 `av1_oh` | 无 | FFmpeg OH 路径无 | 无 | 未定 | 未定 | 未定 | upstream FFmpeg 尚未接 OH AV1 | 很高 |
+| VP9 | SDK API可查询，不代表设备必有硬件 | 当前 OHCodec backend 未声明 `vp9_oh` | 无 | FFmpeg OH 路径无 | 无 | 未定 | 未定 | 未定 | upstream FFmpeg 尚未接 OH VP9 | 很高 |
+
+## 3. MPV 缺口
+
+1. `video/fmt-conversion.c` 没有 `IMGFMT_OHCODEC <-> AV_PIX_FMT_OHCODEC`。
+2. `video/decode/vd_lavc.c` 尚无 OHCODEC device/backend 选择。
+3. GPU interop driver 列表没有 Harmony/OHNativeBuffer 路径。
+4. libmpv OpenGL Render API的目标 Surface与 OHCodec 直接输出 Surface存在所有权冲突：同一个播放画面若让 decoder 直接呈现，MPV 的 shader、OSD、ASS 字幕、色彩管理无法自然叠加。
+5. FFmpeg 当前 OHCodec surface frame 在 AVFrame release 时触发呈现，呈现时钟、drop/late frame 与 MPV VO 调度需要逐帧语义验证。
+
+## 4. 推荐路线
+
+### Stage 1：软件解码基线
+
+先以 FFmpeg software decode + libmpv GLES Render API 跑通首帧、Seek、字幕、网络和稳定性。该基线用于证明其后优化收益。
+
+### Stage 2：FFmpeg OHCodec 可用性验证
+
+独立验证官方 `h264_oh` / `hevc_oh`：创建 decoder、Flush/Seek、Surface destroy/recreate、4K、高码率、Main10；记录设备 capability。此阶段不修改 MPV 大量代码。
+
+### Stage 3：选择合成架构
+
+- 路线 3A，直接 Surface decode：最快接通、copy 少，但 MPV GPU shader/ASS/OSD 不能直接叠加。只适合验证硬解吞吐，不直接定为正式架构。
+- 路线 3B，OHNativeBuffer/GPU import：decoder 输出可导入 GLES/Vulkan，再由 MPV/libplacebo 合成。最符合最终产品，但 FFmpeg 当前 OHCodec API是否暴露可导入 buffer 尚需源码和真机证明。
+- 路线 3C，双 Surface/system overlay：视频与字幕分层，由系统合成。同步、HDR、截图和滤镜语义复杂，仅作备选。
+
+正式路线优先研究 3B；在其不可行证据充分前，不宣称零拷贝。
+
+## 5. Patch 边界
+
+如进入实现，优先局限在：
+
+- `video/fmt-conversion.c` / image format 定义
+- `video/decode/vd_lavc.c` 的 hw device 选择
+- `video/out/hwdec/hwdec_ohcodec.c` 或明确命名的 Harmony interop driver
+- `meson.build` Harmony feature gate
+
+任何不支持格式明确返回 unsupported；不得以 CPU 黑帧、fake success 或注释掉检查伪装完成。
+
+## 6. 当前判定
+
+**不创建 Velix-FFmpeg-Harmony。** 官方 FFmpeg 已有关键 OHCodec 基础，Phase 1 应固定官方 commit 并先编译；只有真实 blocker 证明需要 patch 且无法快速 upstream 后，才建立独立 FFmpeg fork。AV1、VP9、buffer import、HDR metadata 仍为 `NEED VERIFY`。

DOCS/HARMONY_RENDER_RESEARCH.md

@@ -0,0 +1,74 @@
+# HarmonyOS Rendering Research
+
+## 1. 结论
+
+第一阶段推荐 **OpenGL ES + EGL + libmpv OpenGL Render API**：ArkUI XComponent 仅交付 `OHNativeWindow *`，Native 层创建 EGL window surface/context，并在 GL 线程调用 `mpv_render_context_render()` 渲染到默认 FBO，随后 `eglSwapBuffers()`。视频帧不经过 ArkTS/N-API。
+
+```text
+XComponent Surface
+  -> OHNativeWindow
+  -> EGLSurface + GLES context（Native 渲染线程）
+  -> libmpv OpenGL Render API
+  -> GPU render -> eglSwapBuffers -> Display
+```
+
+依据：本机 API 24 SDK 明确把 `EGLNativeWindowType` 定义为 `struct NativeWindow *`；MPV 公共 Render API 当前只公开 `MPV_RENDER_API_TYPE_OPENGL` 与软件渲染，未公开 Vulkan Render API。
+
+## 2. 方案 A：OpenGL ES / EGL
+
+### 调用边界
+
+1. `OH_NativeXComponent_RegisterCallback()` 接收 Surface 创建/变化/销毁。
+2. `OnSurfaceCreated` 的 `void *window` 按 SDK 契约转换为 `OHNativeWindow *`。
+3. Native GL 线程执行 `eglGetDisplay`、`eglInitialize`、`eglChooseConfig`、`eglCreateWindowSurface`、`eglCreateContext`。
+4. 用 `MPV_RENDER_PARAM_API_TYPE=MPV_RENDER_API_TYPE_OPENGL` 和 `mpv_opengl_init_params` 创建 render context。
+5. update callback 只唤醒渲染线程；该线程 make-current，调用 `mpv_render_context_render()`，目标为默认 FBO 0 和当前 Surface 尺寸，再 swap。
+6. Surface changed 更新 viewport/FBO 尺寸；Surface destroyed 先停止提交帧，再释放 render context 的 surface 相关状态和 EGLSurface。
+
+### 评估
+
+| 维度 | 结论 |
+|---|---|
+| 实现复杂度 | 中；MPV 已有完整 OpenGL Render API，Harmony 只负责 EGL/XComponent 生命周期 |
+| MPV 支持度 | 高；公共 API 稳定，`include/mpv/render.h`、`render_gl.h` 为直接依据 |
+| HarmonyOS 支持度 | 高；API 24 提供 EGL、GLES2/3、OHNativeWindow |
+| Surface 生命周期 | 必须单线程串行化 create/change/destroy，销毁后禁止 swap |
+| Copy 次数 | 软件解码时 FFmpeg frame 上传 GPU，至少一次 CPU→GPU；无逐帧 N-API copy |
+| 4K | 渲染路径可行，性能取决于上传、shader、带宽；需 Benchmark |
+| 10-bit | 软件帧可由 MPV shader 处理；Surface 色深/输出格式待设备 EGLConfig 验证 |
+| HDR | MPV 色彩处理可复用，但 Harmony Surface 色域、transfer、HDR metadata 通路尚未证明 |
+| 风险 | EGL context 线程归属、Surface 快速重建、默认 FBO 方向、vsync/帧节奏 |
+
+### MPV 修改范围
+
+- Phase 1 构建 `libmpv` 时启用 `plain-gl`，无需先新增完整 `vo_harmony`。
+- Playback Lab 的 Harmony glue 独立放在后续 `playback_lab/native/`，不把 ArkTS 业务代码放进 MPV core。
+- 只有确认必须让 MPV 自管 window/context 时，才新增 `video/out/opengl/context_harmony.c` 并在 Meson 中以 `features['harmony']` 注册。
+
+## 3. 方案 B：Vulkan
+
+### 可行基础
+
+API 24 提供 `VK_OHOS_surface`、`VkSurfaceCreateInfoOHOS`、`vkCreateSurfaceOHOS()` 与 `libvulkan.so`，可从 `OHNativeWindow *` 创建 `VkSurfaceKHR`。MPV 内部 `vo_gpu_next` / libplacebo 支持 Vulkan，但 libmpv 公共 Render API 没有 Vulkan 类型。
+
+| 维度 | 结论 |
+|---|---|
+| 实现复杂度 | 高；需要新增/扩展 MPV Vulkan context 或设计受支持的嵌入路径 |
+| MPV 支持度 | 内部高、公共嵌入 API 低 |
+| HarmonyOS 支持度 | API 10+ 有 surface 扩展，设备扩展需枚举 |
+| Surface 生命周期 | 需重建 swapchain，处理 out-of-date/suboptimal、旋转与尺寸变化 |
+| Copy 次数 | 软件解码仍需上传；未来 native buffer/Vulkan interop 有降 copy 潜力 |
+| 4K | 理论适合，未实测不能优于 GLES |
+| 10-bit/HDR | Vulkan format/colorspace 路径潜力更强，但 Harmony 设备与系统合成支持待证 |
+| 风险 | libplacebo/Vulkan 版本、OHOS surface 接入、swapchain、同步/fence、驱动差异 |
+
+## 4. 禁止路径
+
+`MPV -> CPU frame -> Native Buffer -> ArkTS -> ArkUI Image` 不进入正式架构。它会增加逐帧跨 N-API、CPU copy、GC/调度与背压风险，也无法作为 4K 主路径。
+
+## 5. Phase 门禁
+
+- Phase 1：只证明 `libmpv` arm64 编译，OpenGL Render API 符号存在。
+- Phase 2：Playback Lab 证明 XComponent→EGL→首帧；记录 Surface 重建和旋转。
+- Phase 3：软件解码基线后再接 OHCodec；分别测 CPU upload 与 surface decode。
+- Vulkan 只有在 GLES 基线与瓶颈证据齐备后启动，不以“理论更快”替代 Benchmark。

DOCS/PORTING_PLAN.md

@@ -0,0 +1,70 @@
+# 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 不是首版必需。

DOCS/RISK_ASSESSMENT.md

@@ -0,0 +1,35 @@
+# Risk Assessment
+
+## Top 10
+
+| # | 风险 | 可能性 / 影响 | 证据 | 缓解与验收 |
+|---:|---|---|---|---|
+| 1 | MPV 无 OHOS 平台检测，OHOS 被泛 POSIX/Linux 逻辑误分类 | 高 / 高 | 当前 `meson.build` 无 harmony/ohos；编译器同时定义 `__linux__` | 显式 `features['harmony']`；每个 Linux feature 用 compile/link probe |
+| 2 | 交叉依赖链复杂且 pkg-config 污染宿主库 | 高 / 高 | 本机无 Meson/Ninja/pkg-config；MPV 强依赖 FFmpeg/libplacebo/libass | 单一 staging prefix、清空默认 `PKG_CONFIG_PATH`、产物 readelf 审计 |
+| 3 | HTTPS/TLS 无可直接复用的 FFmpeg Harmony backend | 高 / 高 | SDK有 `libnet_ssl.so`，FFmpeg不使用它 | 交叉构建 OpenSSL；真机证书/SNI/Range/HLS 测试 |
+| 4 | Surface 生命周期与 GL 线程竞态导致黑屏/崩溃 | 高 / 高 | XComponent异步 create/change/destroy，EGL context 有线程归属 | 单一 render thread 状态机；销毁屏障；旋转/后台压力测试 |
+| 5 | OHAudio callback 与 MPV buffer/clock 语义不匹配 | 中高 / 高 | MPV无 Harmony AO | realtime-safe callback；timestamp/delay 校准；seek/route switch 测试 |
+| 6 | FFmpeg OHCodec虽已 upstream，但 MPV完全不识别 OHCODEC | 高 / 高 | MPV无 `AV_PIX_FMT_OHCODEC` / `AV_HWDEVICE_TYPE_OHCODEC` | 软件基线后小步接入；先独立验证 FFmpeg backend |
+| 7 | Direct Surface decode 绕过 MPV shader/ASS/色彩管理 | 高 / 高 | FFmpeg OHCodec向 window直接 render | 优先研究 OHNativeBuffer GPU import；direct surface仅作验证路径 |
+| 8 | 4K/10-bit/HDR 能力因机型/驱动不同，SDK存在不等于设备支持 | 高 / 高 | capability API要求运行时查询 | 保存设备矩阵、profile/level/format/extension；不做泛化承诺 |
+| 9 | GPL/LGPL 与静态链接/FFmpeg选项污染商业发布 | 中高 / 极高 | MPV默认 GPLv2+；开关不自动产生 LGPL授权 | 默认 GPL 管理；保存完整 build manifest；发布前法务审计 |
+| 10 | arm64 OHOS ABI/符号/打包规则与普通 Linux不同 | 中 / 高 | target 是 `aarch64-linux-ohos`，系统库命名含 `.z.so` | 小探针→依赖→libmpv；检查 SONAME、NEEDED、符号可见性和 HAP 装载 |
+
+## 其他风险
+
+- 字体发现和字体包体积影响 ASS 首帧及中日韩字幕正确性。
+- 网络切换、代理、IPv6、慢速 Range、HLS discontinuity 对稳定性影响大。
+- MPV master 与 FFmpeg master 同时变化，需锁 commit 并记录组合。
+- API 24 SDK header含更低 API接口，但实际目标机系统版本仍要匹配。
+- Vulkan headers/loader存在不代表驱动质量和 HDR swapchain 可用。
+
+## 决策门禁
+
+| 决策 | 必需证据 |
+|---|---|
+| 进入 Phase 1 | Phase 0 文档完成；origin/upstream/branch明确；依赖与 license 策略确认 |
+| 开始 Playback Lab | libmpv arm64真实产物及 build report |
+| 启用 OHCodec | software decode 基线 + 官方 FFmpeg OHCodec 独立验证 |
+| 宣称 low-copy/zero-copy | 帧路径、buffer ownership、GPU import、同步与 copy 测量证据 |
+| 采用 Vulkan | GLES benchmark证明瓶颈且 Vulkan原型在目标机显著改善 |
+| 商业发布 | 实际链接清单、许可证正文、源码义务、法务审核全部完成 |

LICENSES/GPL-2.0-or-later.txt

@@ -0,0 +1,338 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Moe Ghoul>, 1 April 1989
+  Moe Ghoul, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

LICENSES/LGPL-2.1-or-later.txt

@@ -0,0 +1,501 @@
+                  GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+ <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it.  You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+                  GNU LESSER GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Use a suitable shared library mechanism for linking with the
+    Library.  A suitable mechanism is one that (1) uses at run time a
+    copy of the library already present on the user's computer system,
+    rather than copying library functions into the executable, and (2)
+    will operate properly with a modified version of the library, if
+    the user installs one, as long as the modified version is
+    interface-compatible with the version that the work was made with.
+
+    c) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    d) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    e) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                            NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Moe Ghoul>, 1 April 1990
+  Moe Ghoul, President of Vice
+
+That's all there is to it!

LICENSES/README.md

@@ -0,0 +1,6 @@
+# License texts
+
+- `GPL-2.0-or-later.txt`：MPV 默认构建所适用的 GPL v2 文本。
+- `LGPL-2.1-or-later.txt`：MPV 合规 LGPL-only 构建及 FFmpeg 默认构建所涉及的 LGPL v2.1 文本。
+
+第三方源码未 vendoring 到本仓库，因此其许可证正文不在未锁版前复制。Phase 1 锁定每个依赖 commit 后，必须复制对应仓库的原始许可证正文并更新 `LICENSE_AUDIT.md`。

LICENSE_AUDIT.md

@@ -0,0 +1,39 @@
+# License Audit
+
+审计基线：MPV `182fa6ca49f455cadb884858f386e2f00540aeb7`。本文件是工程审计记录，不构成法律意见。
+
+## 当前结论
+
+仓库分离不改变链接后二进制的许可证。第一版按 MPV 默认 GPLv2+ 口径管理，除非后续对 MPV、FFmpeg 及全部链接依赖完成 LGPL-only 的逐文件、逐选项和链接方式审计。MPV 自身 `Copyright` 明确说明 `-Dgpl=false` 只是排除已知 GPL-only 文件的辅助开关，并不自动产生 LGPL 授权结论。
+
+Phase 0 尚未生成二进制，因此“最终实际链接库”尚不存在。下表区分计划必需与候选依赖；Phase 1 必须以 link map、`readelf -d` 和构建配置替换“预计”字段。
+
+| 组件 | 许可证 | 计划链接 | 必需 | GPL-only / 风险 | 依据与状态 |
+|---|---|---:|---:|---|---|
+| MPV | 默认 GPL-2.0-or-later；满足完整条件时可 LGPL-2.1-or-later | 动态 `libmpv` 优先 | 是 | 默认构建含 GPL-only 文件 | 本仓库 `Copyright`、`LICENSE.GPL`、`LICENSE.LGPL` |
+| FFmpeg | 默认 LGPL-2.1-or-later；`--enable-gpl` 后 GPL；`--enable-nonfree` 不可再分发 | 动态优先 | 是 | 外部库和 configure 选项可改变整体许可证 | FFmpeg `LICENSE.md`；Phase 1 锁 commit |
+| libplacebo | LGPL-2.1-or-later（待锁定版本复核原文） | 静态或动态待定 | 是（当前 MPV Meson 强依赖） | 静态链接影响 LGPL 重新链接义务 | MPV `meson.build` 要求 `>=7.360.1` |
+| libass | ISC（待锁定版本复核原文） | 动态优先 | 是 | 还会引入 FreeType、HarfBuzz、FriBidi | MPV `meson.build` 要求 `>=0.12.2` |
+| zlib | Zlib | SDK 动态 `libz.so` 优先 | 可选但建议启用 | 低 | 本机 API 24 SDK 提供头文件和库 |
+| TLS 实现 | OpenSSL 3.x 为首选候选，Apache-2.0 | 动态优先 | HTTPS 必需 | FFmpeg GPLv2 模式与 OpenSSL 组合需单独复核；不得同时启用 nonfree 后分发 | 尚未锁版；Harmony `libnet_ssl.so` 不能直接当作 FFmpeg TLS backend |
+| FreeType | FTL 或 GPL 双许可证 | 由 libass 引入 | 字幕必需 | 选择 FTL 口径并保存原文 | NEED VERIFY at pin |
+| HarfBuzz | MIT | 由 libass 引入 | 复杂文本必需 | 低 | NEED VERIFY at pin |
+| FriBidi | LGPL-2.1-or-later | 由 libass 引入 | 双向文本必需 | 动态链接优先 | NEED VERIFY at pin |
+| iconv | 系统 libc 或独立实现许可证 | 系统符号优先 | 字符集处理 | 若引入 GNU libiconv，需审核 LGPL | Phase 1 探测 |
+| libcurl | curl license | 默认关闭；网络交给 FFmpeg | 否 | 增加 TLS/HTTP 依赖面 | MPV `-Dlibcurl=disabled` |
+| uchardet | MPL-1.1 / GPL-2.0-or-later / LGPL-2.1-or-later 多许可证 | 默认关闭 | 否 | 需选择许可口径 | NEED VERIFY at pin |
+| MuJS | ISC | 默认关闭 | 否 | 低 | JS 功能首版不需要 |
+| HarmonyOS Native SDK stubs | SDK/EULA 与各头文件声明并存 | 系统动态库 | 是 | 发行许可由 HarmonyOS SDK 条款约束 | 需在发版前由法务核查 SDK redistributable 边界 |
+
+## MPV GPL-only 范围
+
+MPV `Copyright` 当前列出 JACK、OSS、DVB、CDDA、DVD、CACA、legacy Direct3D、VAAPI VO、VDPAU、X11/Xv 等 GPL-only 文件。HarmonyOS 首版均不需要，但这不等于整个产物自动成为 LGPL。
+
+## 发版门禁
+
+1. 固定全部源码 commit、构建选项、静态/动态链接方式。
+2. 保存 FFmpeg `configure` 输出与 `config.h`，确认未启用 `nonfree`，并列出 GPL/version3 状态。
+3. 保存 MPV `meson configure` 输出，逐项确认 GPL-only 文件是否进入产物。
+4. 用 `llvm-readelf -d`、link map 和 archive 成员清单核对所有实际链接库。
+5. 补齐许可证正文、版权声明、源码获取方式、修改说明及 LGPL 重新链接材料。
+6. 商业发布前完成法务复核；未完成前不得宣称“LGPL-only”或“闭源可安全链接”。

MEMORY.md

@@ -0,0 +1,9 @@
+# Velix-MPV-Core Memory
+
+- 项目：独立 HarmonyOS MPV 播放内核，禁止混入 Velix 主应用源码。
+- 当前阶段：Phase 0 研究已完成，等待确认后才能进入 Phase 1。
+- 基线：MPV `182fa6ca49f455cadb884858f386e2f00540aeb7`，分支 `harmony-port`。
+- SDK：OpenHarmony API 24 / 6.1.1.125 / `aarch64-linux-ohos` / Clang 15.0.4。
+- 关键结论：首版 GLES+EGL+libmpv Render API；OHAudio AO；官方 FFmpeg OHCodec 路线。
+- 待办：创建 GitHub fork并配置 `origin`；安装 Meson/Ninja/pkg-config；Phase 1 首编译。
+- 索引：`memory/projects.md`、`memory/infra.md`、`memory/lessons.md`、`memory/2026-08-28.md`。

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,7 @@
+# Third-Party Notices
+
+Velix-MPV-Core 基于 MPV，当前上游基线见 `UPSTREAM.md`。MPV 默认按 GNU GPL v2 or later 管理；其完整版权与许可证说明保留在 `Copyright`、`LICENSE.GPL`、`LICENSE.LGPL` 及 `LICENSES/`。
+
+计划构建将使用 FFmpeg、libplacebo、libass，并可能使用 zlib、OpenSSL、FreeType、HarfBuzz、FriBidi 等依赖。Phase 0 未产生可分发二进制，依赖版本与最终链接集合尚未锁定，因此本文件不是最终发行 notices。
+
+每次发布必须由构建产物自动生成第三方清单，至少包含：组件名称、版本/commit、主页、版权方、许可证、修改状态、静态/动态链接方式、许可证正文位置和源码获取方式。完整审计门禁见 `LICENSE_AUDIT.md`。

UPSTREAM.md

@@ -0,0 +1,27 @@
+# Upstream 基线
+
+| 项目 | 值 |
+|---|---|
+| MPV Repository | `https://github.com/mpv-player/mpv.git` |
+| MPV Current Commit | `182fa6ca49f455cadb884858f386e2f00540aeb7` |
+| Commit Date | 2026-08-26 |
+| MPV Version / Tag | `MPV_VERSION=0.41.0-UNKNOWN`；`git describe=git-release-292-g182fa6ca49`；HEAD 无 tag |
+| Fork Date | 2026-08-28 |
+| Development Branch | `harmony-port` |
+| HarmonyOS Target | HarmonyOS NEXT / OpenHarmony Native API 24 |
+| HarmonyOS SDK | DevEco Studio 内置 OpenHarmony SDK `6.1.1.125`，API 24 |
+| Target Architecture | `arm64-v8a` / `aarch64-linux-ohos` |
+| Compiler | OHOS Clang `15.0.4` (`99548401bd80576251755b185ab95945e5fe7884`) |
+| Build System | MPV Meson `>=1.3.0` + Ninja；依赖使用各自原生构建系统 |
+
+## 远程状态
+
+- `upstream` 已指向 MPV 官方仓库。
+- `origin` 尚未配置：GitHub 账号 `BoatingCloud` 已通过 SSH 验证，但 `BoatingCloud/Velix-MPV-Core` 尚不存在。禁止用占位 URL 冒充 origin；创建真实 fork 后执行：
+
+```sh
+git remote add origin git@github.com:BoatingCloud/Velix-MPV-Core.git
+git push -u origin harmony-port
+```
+
+基线更新必须先 `git fetch upstream`，评估后再合并或变基到 `harmony-port`，并同步更新本文件。

memory/2026-08-28.md

@@ -0,0 +1,5 @@
+[PROJECT:Velix-MPV-Core] 完成 Phase 0 移植研究
+结论: 基于 MPV 182fa6ca49 和 OpenHarmony API 24 完成全部研究文档，首版采用 GLES/EGL、OHAudio、官方 FFmpeg OHCodec 路线。
+文件变更: UPSTREAM.md, LICENSE_AUDIT.md, THIRD_PARTY_NOTICES.md, LICENSES/, DOCS/*_RESEARCH.md, DOCS/PORTING_PLAN.md, DOCS/FFMPEG_STRATEGY.md, DOCS/BUILD_STRATEGY.md, DOCS/RISK_ASSESSMENT.md
+教训: OHOS 会定义 __linux__；FFmpeg master 已有 OHCodec；Native TLS验证接口不能替代 FFmpeg TLS backend。
+标签: #mpv #harmonyos #phase0 #ffmpeg #ohcodec #license

memory/infra.md

@@ -0,0 +1,11 @@
+# Infrastructure
+
+- DevEco Studio：`/Applications/DevEco-Studio.app`
+- OpenHarmony SDK：`/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony`
+- SDK：API 24，版本 6.1.1.125
+- Native sysroot：`<SDK>/native/sysroot`
+- Toolchain：`<SDK>/native/llvm/bin`
+- Target：`aarch64-linux-ohos`
+- Compiler：OHOS Clang 15.0.4
+- GitHub SSH：账号 `BoatingCloud` 已认证
+- MPV upstream：`https://github.com/mpv-player/mpv.git`

memory/lessons.md

@@ -0,0 +1,11 @@
+# Lessons
+
+## High
+
+- OHOS 同时定义 `__OHOS__` 和 `__linux__`；必须显式平台检测，不能把全部 Linux API视为可用。
+- 最新 FFmpeg upstream 已有 OHCodec H.264/HEVC；研究当前源码后再决定 fork，避免重复维护。
+- `libnet_ssl.so` 主要提供证书验证接口，不是 FFmpeg TLS transport backend。
+
+## Medium
+
+- MPV upstream 使用 `DOCS/`；大小写不敏感文件系统不能可靠并存 `docs/`，沿用 upstream 目录。

memory/projects.md

@@ -0,0 +1,8 @@
+# Projects
+
+## Velix-MPV-Core
+
+- 状态：Phase 0 研究文档已完成并核验；尚未进入首次编译。
+- 已完成：完整 MPV 历史、`upstream`、`harmony-port`、SDK/API/源码/依赖/许可证/渲染/音频/硬解研究。
+- 待办：创建 `BoatingCloud/Velix-MPV-Core` fork并设置 `origin`；用户确认后进入 Phase 1。
+- Phase 1 前置：安装 Meson、Ninja、pkg-config，锁定 FFmpeg与依赖 commit。