diff --git a/DOCS/PHASE2_PLAYBACK_REPORT.md b/DOCS/PHASE2_PLAYBACK_REPORT.md new file mode 100644 index 0000000000..4f43ebc758 --- /dev/null +++ b/DOCS/PHASE2_PLAYBACK_REPORT.md @@ -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`)的前置条件是实体机首帧、控制和压力矩阵完成。 diff --git a/MEMORY.md b/MEMORY.md index 2818b6db4e..b9d9822cc0 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -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`。 diff --git a/memory/2026-08-29.md b/memory/2026-08-29.md new file mode 100644 index 0000000000..7bd221bc6c --- /dev/null +++ b/memory/2026-08-29.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 diff --git a/memory/infra.md b/memory/infra.md index bdb9cc2f83..f990147a87 100644 --- a/memory/infra.md +++ b/memory/infra.md @@ -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` diff --git a/memory/lessons.md b/memory/lessons.md index c3320195d4..9aab4c3f2c 100644 --- a/memory/lessons.md +++ b/memory/lessons.md @@ -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 `;应用沙箱媒体必须发送到 `/data/storage/el2/base/haps/entry/files/`。 +- libmpv 诊断计数返回 ArkTS Number;返回 BigInt 会导致 Inspector 无法序列化组件状态。 +- MPV 事件线程需高频轮询;200ms 轮询会使属性/命令事件堆积,seek 报 `MPV_ERROR_EVENT_QUEUE_FULL`。 diff --git a/memory/projects.md b/memory/projects.md index 9ec68d44bb..1cc3fd07cf 100644 --- a/memory/projects.md +++ b/memory/projects.md @@ -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`。