Velix-MPV-Core/memory/lessons.md

Lessons

High

• OHOS 同时定义 __OHOS__ 和 __linux__；必须显式平台检测，不能把全部 Linux API视为可用。
• 最新 FFmpeg upstream 已有 OHCodec H.264/HEVC；研究当前源码后再决定 fork，避免重复维护。
• libnet_ssl.so 主要提供证书验证接口，不是 FFmpeg TLS transport backend。
• Clang 仅设置 sysroot 不会切换 target；macOS arm64 交叉编译必须在编译和链接两侧显式传 --target=aarch64-linux-ohos。

Medium

• MPV upstream 使用 DOCS/；大小写不敏感文件系统不能可靠并存 docs/，沿用 upstream 目录。
• 私有 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。
• MPV audio 是 aid 别名（音轨选择），不能传布尔 yes/no；Playback Lab 音频开关必须使用 aid=auto/no。
• 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。