docs: record Phase 4 OHCodec validation

MEMORY.md

@@ -1,13 +1,14 @@
 # Velix-MPV-Core Memory
 
 - 项目：独立 HarmonyOS MPV 播放内核，禁止混入 Velix 主应用源码。
-- 当前阶段：Phase 3 OHAudio AO 代码完成；模拟器音频 smoke 已验证；实体设备验收待做。
+- 当前阶段：Phase 4 CODE COMPLETE / GPU INTEROP BLOCKED / DEVICE VALIDATION PENDING；OHCodec 适配与软件回退已完成，模拟器启动/EGL smoke 已验证。
 - 基线：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 路线。
 - Phase 1 产物：`build/ohos-arm64/prefix/lib/libmpv.so.2.5.0`，AArch64 ELF，OpenGL Render API symbols 完整。
 - 远程：`origin` 为私有 Gitea 仓库，默认分支 `harmony-port`；`upstream` 为 MPV 官方仓库。
 - Phase 2：`playback_lab/` 独立 HAP，XComponent/OHNativeWindow/EGL/libmpv/软件解码已通；实体设备待验。
-- Phase 3：`audio/out/ao_harmony.c` + OHAudio pull callback、pause/flush/clock/metrics 已通；保持 `hwdec=no`，未接 OHCodec。
-- 待办：实体机 H.264/AAC、真实 A/V sync/路由/多声道、压力与 30 分钟稳定性；完成后再评估 Phase 4。
+- Phase 3：`audio/out/ao_harmony.c` + OHAudio pull callback、pause/flush/clock/metrics 已通；实体机路由/A-V sync/压力待验。
+- Phase 4：`IMGFMT_OHCODEC`、`hwdec=ohcodec`、API24 capability adapter、direct-surface experimental driver、软件构建矩阵、Playback Lab 诊断已提交；FFmpeg 保持 upstream。
+- Phase 4 边界：官方 OHCodec hwcontext/decoder 仅提供 surface 输出，NativeBuffer→EGL 仅做禁用默认 API probe，未宣称零拷贝/HDR/真实硬件帧；详见 `DOCS/OHCODEC_GPU_INTEROP_DESIGN.md`。
 - 索引：`memory/projects.md`、`memory/infra.md`、`memory/lessons.md`、`memory/2026-08-28.md`。

memory/2026-08-29.md

@@ -9,3 +9,9 @@
 文件变更: audio/out/ao_harmony.c, audio/out/ao_harmony.h, audio/out/ao.c, meson.build, meson.options, scripts/*, playback_lab/*, DOCS/HARMONY_AUDIO_*.md, memory/*
 教训: MPV 音频开关使用 `aid=auto/no`；OHAudio reset 必须 Stop→等待 callback→Flush；模拟器可验证输出但不能代替实体机路由/A-V sync/压力验收。
 标签: #phase3 #ohaudio #audio #emulator-smoke #pending-device
+
+[PROJECT:Velix-MPV-Core] 完成 Phase 4 OHCodec 适配与验证闭环
+结论: 提交 `3f6132637b`、`37df87fc56`、`1f1a6e5962` 已推送 `origin/harmony-port`；实现 `IMGFMT_OHCODEC`、`hwdec=ohcodec`、API24 capability/direct-surface 实验驱动、软件回退与 Playback Lab 诊断，完整 AArch64/软件/GL probe/HAP 构建通过，模拟器启动与 EGL smoke 通过；GPU 互操作受官方 surface-only 上游路径阻塞，实体设备验证待做。
+文件变更: video/*ohcodec*, video/fmt-conversion.c, video/img_format.h, meson.build, meson.options, playback_lab/*, scripts/*, DOCS/OHCODEC_*.md, DOCS/HDR_PIPELINE_NOTES.md, LICENSE_AUDIT.md, memory/*
+教训: `OH_AVBuffer_GetNativeBuffer` 和 EGL 扩展只能证明 API 可探测，不能证明上游 decoder 已提供可导入非 surface 帧；HAP 未签名可装模拟器但不能作为发布包。
+标签: #phase4 #ohcodec #hwdec #gpu-interop-blocked #emulator-smoke #pending-device

memory/infra.md

@@ -15,5 +15,8 @@
 - hdc：`/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc`
 - 模拟器目标：`127.0.0.1:5555`，HarmonyOS 6.1.0.126 / API 24
 - Playback Lab 构建：在 `playback_lab/` 执行 `scripts/stage-mpv.sh` 后用 hvigor `--no-daemon assembleHap --mode module -p product=default`
+- HAP 构建 Java：`/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home`；未配置签名时产物为 `entry-default-unsigned.hap`。
 - OHAudio：API 24 headers `ohaudio/native_audiostreambuilder.h` / `native_audiorenderer.h` / `native_audiostream_base.h`，动态库 `libohaudio.so`；Meson 使用 `-Dharmony-audio=enabled`。
 - Phase 3 HAP：`playback_lab/entry/build/default/outputs/default/entry-default-unsigned.hap`；模拟器 H.264/AAC smoke target `127.0.0.1:5555`。
+- Phase 4 构建入口：`scripts/build-mpv-ohos.sh`（OHCodec enabled）、`scripts/build-mpv-ohos-software.sh`（OHCodec disabled）、`scripts/build-all-ohos.sh`（全量矩阵）；GL API probe 通过单独 Meson `harmony-ohcodec-gl=enabled` 构建验证。
+- Phase 4 产物：`build/ohos-arm64/prefix/lib/libmpv.so.2.5.0`；软件构建位于 `build/ohos-arm64/build/mpv-software/libmpv.so.2.5.0`；HAP 位于 `playback_lab/entry/build/default/outputs/default/entry-default-unsigned.hap`。

memory/lessons.md

@@ -21,3 +21,5 @@
 - OHAudio seek/reset 先 `Stop` 再 `Flush`，并等待 inflight callback；只 Flush 后重新 Start 在模拟器返回 `AUDIOSTREAM_ERROR_ILLEGAL_STATE`。
 - OHAudio timestamp 在 Flush 后可能保留旧 epoch；统计需保存 raw frame origin，否则会出现 `playedFrames > submittedFrames`。
 - `setup-ohos-env.sh` 在 zsh 中的循环变量 `path` 会覆盖特殊 PATH 数组；运行脚本应使用 `/bin/sh` 或避免 source 到交互 zsh。
+- FFmpeg upstream OHCodec API24 路径是 surface-first：`AV_PIX_FMT_OHCODEC` 的 hwcontext 只保存 `OHNativeWindow*`，decoder 硬件帧通过 surface 输出；NativeBuffer/EGL API 存在不等于 MPV 可合法导入的非 surface 帧。
+- OHCodec capability 必须通过 `OH_AVCodec_GetCapabilityByCategory` 及 `OH_AVCapability_*` 查询；不能把 SDK 头文件存在误写成设备能力或硬件帧已产出。

memory/projects.md

@@ -2,9 +2,11 @@
 
 ## Velix-MPV-Core
 
-- 状态：Phase 3 CODE COMPLETE / DEVICE VALIDATION PENDING；OHAudio 模拟器 smoke 完成，最终实体机验收未完成。
+- 状态：Phase 4 CODE COMPLETE / GPU INTEROP BLOCKED / DEVICE VALIDATION PENDING；OHCodec 代码闭环、模拟器启动/EGL smoke 完成，实体机硬解验收未完成。
 - 已完成：远程闭环、固定依赖、隔离工具链、C/C++ 探针、FFmpeg/OpenSSL/字体栈/libplacebo、AArch64 `libmpv.so.2.5.0`、ABI/符号/污染/许可证审计。
 - 产物：`build/ohos-arm64/prefix/lib/libmpv.so.2.5.0`，34,308,568 bytes；DT_NEEDED 含 `libohaudio.so`。
 - 已完成：独立 HAP、XComponent/OHNativeWindow、EGL ES3、libmpv OpenGL Render、软件解码本地 MP4 首帧、播放控制与释放重入。
 - 已完成：`ao_harmony` PCM float32→S16 fallback、采样率/mono-stereo 协商、pause/resume/stop/flush/release、timestamp epoch、starvation/flush metrics；`build-all-ohos.sh`、video-only/audio-enabled 构建和 Playback Lab HAP 均通过。
-- 待办：实体机输出路由、真实延迟/A-V sync、蓝牙/耳机、多声道、30 分钟压力；报告见 `DOCS/HARMONY_AUDIO_IMPLEMENTATION.md` 与 `DOCS/PHASE2_PLAYBACK_REPORT.md`。
+- 已完成：OHCodec H.264/HEVC capability 查询、`hwdec=ohcodec` direct-surface 实验驱动、显式软件回退、Playback Lab requested/actual/metrics 诊断、软件/硬解/GL probe 构建矩阵；FFmpeg 未修改。
+- 边界：官方 OHCodec 上游没有非 surface 的可导入硬件帧路径，EGL/NativeBuffer 仅保留禁用默认探针；无零拷贝、HDR 或硬件帧产出声明。
+- 待办：实体机 H.264/HEVC capability、surface 生命周期/stride/crop/fence、真实 GPU 互操作与 A/V sync；报告见 `DOCS/OHCODEC_*.md`、`DOCS/HDR_PIPELINE_NOTES.md`。