docs(playback-lab): record emulator verification

2026-08-29 09:06:04 +08:00
1 parent d4c84601fa
commit c650a4214d
@@ -0,0 +1,67 @@
+# Phase 2 Playback Lab 报告
+
+日期：2026-08-29
+分支：`harmony-port`
+
+## 范围
+
+`playback_lab/` 是独立 HarmonyOS 验证工程，仅链接 Phase 1 生成的 arm64 `libmpv.so.2`，不复用 Velix 主应用的页面或业务逻辑。当前只验证 GLES/EGL、软件解码和本地 MP4 首帧，不接入音频或硬解。
+
+## 构建与产物
+
+环境：DevEco Studio SDK API 24，HarmonyOS emulator 6.1.0.126，`aarch64-linux-ohos`。构建命令：
+
+```sh
+./scripts/stage-mpv.sh
+DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
+JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home \
+PATH="$JAVA_HOME/bin:$PATH" \
+/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
+  --no-daemon assembleHap --mode module -p product=default
+```
+
+结果：`BUILD SUCCESSFUL`。HAP：`playback_lab/entry/build/default/outputs/default/entry-default-unsigned.hap`，约 31 MiB，SHA-256 `877568c34a02a4d61b8c4ed7721dd2e6486cb675cd1a58a8eaf44c9b00de05f5`。包内包含 `libentry.so`、`libmpv.so.2` 和 `libc++_shared.so`；未提交 34 MiB 的 staged native 库。
+
+构建仅保留两项预期警告：NAPI 动态模块在当前 SDK 尚未完成类型校验，以及调试 HAP 未配置正式签名；两者不影响本轮模拟器安装验证。
+
+## 模拟器验证
+
+目标：`127.0.0.1:5555`，虚拟设备进程配置为 Pura 90 Pro Max。
+
+| 项目 | 结果 | 证据 |
+| --- | --- | --- |
+| HAP 安装、启动 | 通过 | `hdc install -r`、`aa start` 成功 |
+| XComponent / OHNativeWindow | 通过 | 页面显示 `surface=READY`；Native 回调无崩溃 |
+| EGLDisplay / EGLConfig / EGLContext / WindowSurface / makeCurrent | 通过 | 页面显示 `egl=READY`；日志 `EGL vendor=Express ... renderer=Mali-G77` |
+| libmpv 初始化与 Render API | 通过 | 页面显示 `mpv=READY`；日志 `libmpv initialized` |
+| 本地 H.264 MP4 软件解码 | 通过 | 本地 `sample.mp4` 首帧及持续播放成功 |
+| Pause / Resume / Stop / Release | 通过 | UI 状态分别出现 `PAUSED`、`PLAYING`、`STOPPED`、`RELEASED` |
+| Seek | 通过 | 有效播放中 `-10s/+10s` 不报错；跳转按 duration 做边界裁剪 |
+| 释放后重新进入 | 通过 | `RELEASED` 后重新启动回到 `PLAYER_CREATED`，Surface/EGL/mpv 再次 READY |
+| BigInt 状态序列化 | 通过 | `renderCount` 改为 Number，Inspector 不再出现 BigInt 序列化错误 |
+
+一次本地播放快照：`position=2.00`、`duration=5.05`、`fps=29.97`、`dropped=0`、`firstFrameMs=622`、`renderCount=52`。另一轮快照首帧为 117 ms；`firstFrameMs` 从 `load()` 调用开始计时，并在第一次 `eglSwapBuffers` 后记录。
+
+## First Frame Timeline
+
+1. T0：XComponent 创建并取得回调传入的 `OHNativeWindow`，增加 NativeObject 引用。
+2. T1：专用渲染线程创建 EGLDisplay、RGBA8 EGLConfig、ES3 EGLContext 和 EGLWindowSurface，执行 `eglMakeCurrent`。
+3. T2：同一渲染线程创建 mpv OpenGL Render Context，注册 update callback。
+4. T3：`loadfile` 完成本地文件打开，MPV 软件解码产生可渲染帧。
+5. T4：渲染线程执行 `mpv_render_context_render`、`eglSwapBuffers`，记录 `firstFrameMs` 和 `renderCount`。
+
+## 尚未完成的真机验收
+
+本轮只有模拟器，没有接入 HarmonyOS 实体手机，因此 Phase 2 不能标记为最终 COMPLETE。以下项目保持待验证：实体机 HAP 安装、实体机本地 1080P H.264/AAC、HTTP MP4、HTTPS MP4、HLS、20 次 Surface recreate、20 次进出、50 次 Play/Pause、50 次 Seek、横竖屏 20 次、30 分钟稳定性、CPU/RAM 曲线。
+
+## 风险状态
+
+| 风险 | 当前状态 |
+| --- | --- |
+| RISK-01 POSIX / DNS / network runtime | 未验证，网络链路留待实体机 |
+| RISK-02 XComponent / OHNativeWindow lifecycle | 模拟器已验证；实体机压力测试待做 |
+| RISK-03 EGL context / Surface / plain-gl | 模拟器已验证；旋转与重建待做 |
+| RISK-04 OHCodec buffer lifecycle | 保持开放；Phase 2 明确禁用硬解 |
+| RISK-05 CA / HAP packaging | 未签名调试 HAP 安装通过；正式签名待接入 |
+
+新增 MPV upstream patch：0；未修改第三方源码。进入 Phase 3（`ao_harmony + OHAudio`）的前置条件是实体机首帧、控制和压力矩阵完成。
@@ -1,11 +1,12 @@
 # Velix-MPV-Core Memory

 - 项目：独立 HarmonyOS MPV 播放内核，禁止混入 Velix 主应用源码。
- 当前阶段：Phase 1 已完成并验证；等待用户确认后才能进入 Phase 2。
+- 当前阶段：Phase 2 Playback Lab 模拟器首帧与控制链路已验证；实体机验收待做。
 - 基线：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 XComponent + EGL 真机首帧验证。
+- Phase 2：`playback_lab/` 独立 HAP，XComponent/OHNativeWindow/EGL/libmpv/软件解码已通；未接音频、硬解、网络。
+- 待办：实体机 H.264/AAC、HTTP/HTTPS/HLS、压力与 30 分钟稳定性；完成后再进入 Phase 3 音频。
 - 索引：`memory/projects.md`、`memory/infra.md`、`memory/lessons.md`、`memory/2026-08-28.md`。
@@ -0,0 +1,5 @@
+[PROJECT:Velix-MPV-Core] 完成 Phase 2 Playback Lab 模拟器首帧验证
+结论: 独立 HAP 在 HarmonyOS emulator API 24 上完成 XComponent/OHNativeWindow、EGL ES3、libmpv OpenGL Render、本地 H.264 软件解码首帧及播放控制验证；实体机验收仍待完成。
+文件变更: playback_lab/*, DOCS/PHASE2_PLAYBACK_REPORT.md, MEMORY.md, memory/*
+教训: Surface 回调直接取得 OHNativeWindow；事件线程改为 20ms；ArkTS 状态计数使用 Number；hdc 文件需发送到应用沙箱。
+标签: #phase2 #playback-lab #harmonyos #egl #libmpv #first-frame
@@ -12,3 +12,6 @@
 - libmpv：`build/ohos-arm64/prefix/lib/libmpv.so.2.5.0`
 - Git origin：`https://git.leee.xin/leeexin/Velix-MPV-Core.git`，默认分支 `harmony-port`
 - MPV upstream：`https://github.com/mpv-player/mpv.git`
+- 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`
@@ -13,3 +13,7 @@
 - 私有 Gitea 反向代理限制单次 HTTPS pack 时，可先推送历史基线 commit，再推增量分支；不得以浅克隆或裁剪历史规避限制。
 - Meson Cross File 的 `@GLOBAL_SOURCE_ROOT@` 随被构建项目变化；共享工具路径应以 `@DIRNAME@` 相对 Cross File 定位。
 - FreeType `zlib=external` 表示 fallback subproject；使用 SDK zlib 必须选择 `zlib=system` 并隔离 pkg-config。
+- XComponent Surface 回调的 `surface` 已是 `OHNativeWindow*`，应直接转换并 `NativeObjectReference`；再次调用 `CreateNativeWindow` 会在模拟器触发 SIGSEGV。
+- `hdc file send` 语法为 `file send -b <bundle> <local> <remote>`；应用沙箱媒体必须发送到 `/data/storage/el2/base/haps/entry/files/`。
+- libmpv 诊断计数返回 ArkTS Number；返回 BigInt 会导致 Inspector 无法序列化组件状态。
+- MPV 事件线程需高频轮询；200ms 轮询会使属性/命令事件堆积，seek 报 `MPV_ERROR_EVENT_QUEUE_FULL`。
@@ -2,7 +2,8 @@

 ## Velix-MPV-Core

- 状态：Phase 1 HarmonyOS arm64 首次 Native Build 已完成并核验；未进入 Phase 2。
+- 状态：Phase 2 Playback Lab 模拟器验证完成；最终实体机验收未完成。
 - 已完成：远程闭环、固定依赖、隔离工具链、C/C++ 探针、FFmpeg/OpenSSL/字体栈/libplacebo、AArch64 `libmpv.so.2.5.0`、ABI/符号/污染/许可证审计。
 - 产物：`build/ohos-arm64/prefix/lib/libmpv.so.2.5.0`，34,297,376 bytes。
- 待办：用户确认后进入 Phase 2 XComponent + OHNativeWindow + EGL 真机首帧。
+- 已完成：独立 HAP、XComponent/OHNativeWindow、EGL ES3、libmpv OpenGL Render、软件解码本地 MP4 首帧、播放控制与释放重入。
+- 待办：实体机与网络/音频/压力矩阵；报告见 `DOCS/PHASE2_PLAYBACK_REPORT.md`。