[feat] enable Android MediaCodec decoding and simplify tests

apps/android/README.md

@@ -5,11 +5,11 @@
 ## 当前功能
 
 - 官方或自托管 WSS 信令服务器；授权后进入前台即自动注册或登录本机身份，首页实时显示连接、重连及失败状态。发起桌面连接时复用该身份；切换服务器会重新登录，撤回授权或进入后台会关闭连接。
-- H.264（OpenH264）和 AV1（dav1d）软件解码，独立显示线程将 NV12 转 RGBA 后提交 Android 原生 Surface；只保留最新待显示帧，避免 Surface 等待阻塞解码。压缩视频帧使用 MiniRTC 原有的通用解码队列，暂未限制排队长度或等待时间。
+- 优先使用 MediaCodec 硬件解码 H.264 / AV1，硬件缓冲区直接提交 Surface；设备无对应硬件、分辨率超限或运行失败时，按原编码格式回退到 OpenH264 / dav1d。软件输出由独立显示线程将 NV12 转 RGBA；只保留最新待显示帧。MiniRTC 原有的通用压缩帧解码队列保持不变。
 - 48 kHz 单声道 PCM 播放，支持静音，音频队列有容量限制。
 - 相对鼠标（触控板）和绝对位置模式；单指点击、绝对模式按住拖动、长按右键、双指滚轮，以及外接键盘、鼠标。
 - 横竖屏等比例显示、远端多显示器切换。与 iOS 一致的画面质量（低/中/高）、采集帧率（30/60 fps）、画面偏好；支持能力检测、电脑端确认、失败/5 秒超时回退及连续操作的应答排序。
-- 根据 Android 软件解码和屏幕尺寸设置起始参数：显示长边不超过 1280 像素时默认低画质（最高 720p）/30 fps，其余默认中画质（最高 1080p）/30 fps。用户保存的画面偏好不变，仍可手动选择高画质或 60 fps。
+- 根据常见移动设备解码能力和屏幕尺寸设置起始参数：显示长边不超过 1280 像素时默认低画质（最高 720p）/30 fps，其余默认中画质（最高 1080p）/30 fps。用户保存的画面偏好不变，仍可手动选择高画质或 60 fps。
 - 网络状态按视频、音频、数据、合计展示收发速率和丢包率，并显示实际提交帧率、分辨率、画面延时、平滑 RTT、P2P/TURN 和实际 SRTP 状态。每秒刷新，过期或无效测量显示“—”。
 - 可拖动的悬浮控制球、三列控制菜单和浮动 ASCII / 电脑键盘、常用快捷键；通过剪贴板发送中文等文本，再手动执行远端粘贴。
 - 设备身份与选择保存的连接密码使用 Android Keystore / AES-GCM 加密；首次联网需同意，后台切换会结束会话。
@@ -21,7 +21,7 @@
 - 可选保存远程画面预览：默认关闭，经确认开启后，从下一次连接起保存一张 640×360 预览，用于最近连接卡片。支持清除预览，关闭选项或撤回授权会清除已有图片。
 - “关于 CrossDesk”对齐 iOS 的版本、软件许可、开源组件及源码与构建说明页面，包含 OpenFEC 告知、组件详情和可离线选择复制的完整许可；版本号读取当前 APK，构建时记录应用与 MiniRTC 的基础版本。
 
-当前不包含安卓被控端、文件传输、隐私屏、Ctrl+Alt+Del 服务命令、捏合缩放或 iOS 全部附加功能。相关入口保留 iOS 的布局并明确标注不可用。H.264 / AV1 尚未使用 MediaCodec 硬件解码，高分辨率或高帧率可能增加功耗；可通过悬浮菜单的画面设置降低画质或采集帧率。暂只构建 `arm64-v8a`，不支持 x86 模拟器或 32 位设备。
+当前不包含安卓被控端、文件传输、隐私屏、Ctrl+Alt+Del 服务命令、捏合缩放或 iOS 全部附加功能。相关入口保留 iOS 的布局并明确标注不可用。硬件能力取决于设备和编码格式，软件回退时高分辨率或高帧率可能增加功耗；可通过悬浮菜单的画面设置降低画质或采集帧率。暂只构建 `arm64-v8a`，不支持 x86 模拟器或 32 位设备。
 
 ## 构建
 
@@ -125,27 +125,33 @@ CI 构建 Debug、Release 和设备测试 APK，执行 Debug / Release Lint、
 "$ANDROID_HOME/platform-tools/adb" install -r app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk
 "$ANDROID_HOME/platform-tools/adb" shell am instrument -w -r cn.crossdesk.mobile.test/androidx.test.runner.AndroidJUnitRunner
 "$ANDROID_HOME/platform-tools/adb" uninstall cn.crossdesk.mobile.test
-python3 scripts/verify_apk.py app/build/outputs/apk/debug/app-debug.apk
-python3 scripts/test_protocol.py
+python3 test/verify_apk.py app/build/outputs/apk/debug/app-debug.apk
+python3 test/run_native.py
 ```
 
 以上流程覆盖安装应用并只卸载测试包，保留已有应用数据；多台设备同时连接时，在每个 `adb` 命令中加上 `-s <设备序列号>`。`connectedDebugAndroidTest` 可能卸载被测应用及其数据，不用于已有连接记录或密码的设备。
 
-自动化测试覆盖键盘映射、身份加密及服务器隔离、原生 Peer 的重复启动/取消，以及未授权时不启动信令、授权后自动连接、后台断开/前台重连、服务器切换及首页状态更新。布局测试验证密码弹层、设置导航、密码与连接记录的隔离、已保存密码直接重连及页面重启后的读取、损坏凭据回退输入、密码错误后修改并在成功时保存、悬浮菜单/键盘的横竖屏边界，以及断开确认流程；会话 UI 使用本地测试对象和连接状态回调驱动，不代表真实电脑互通验证。TLS 回归测试在真实 Android 应用进程内使用本机环回 TLS 服务，覆盖受信证书成功、未知 CA 拒绝以及主机名不匹配拒绝；测试证书和私钥仅打包进测试 APK。`verify_apk.py` 检查 APK 必须带有 arm64 原生库、许可证，以及 ELF 和 ZIP 的 16 KB 对齐。
+测试源码、资源和检查入口统一位于 `test/`：
 
-画面设置与网络统计测试覆盖能力检测、请求/确认/拒绝/超时、快速修改与乱序响应、无效数据、请求编号回绕、码率单位、RTT 平滑、实际提交帧计数、空闲/过期数据和切屏重置；UI 测试检查设置回退及统计更新时面板不重建、不跳动。JNI 测试验证发送失败的反馈与网络/画面采样回调。`test_protocol.py` 在本机编译 Android 实际使用的消息编码函数，并用桌面端共享解析器验证画面设置报文，同时检查 MiniRTC 分项统计的字段映射。
+- `test/native/`：本机 C++ 协议、帧队列与画面延时回归，由 `test/run_native.py` 编译运行。
+- `test/android/java/`：20 项非 UI 的 Android 功能回归，覆盖需要 Android API 或 JNI 的逻辑。Gradle 的 `androidTest` 源集显式引用此目录。
+- `test/android/assets/tls/`：本机环回 TLS 测试证书，仅进入测试 APK。
+- `test/verify_apk.py`：发布 APK 的 arm64 ABI、16 KB ELF / ZIP 对齐、许可证完整性和源码资料检查。
 
-2026-10-01 初始本地验证：NDK r28c 原生编译、Gradle Debug APK、Lint 零错误、Android 15 arm64 的 4 KB / 16 KB 模拟器各 4 项测试，以及共享 wire / keyboard-state 协议测试。iOS 布局适配后，Android 15 / 16 KB 模拟器的 7 项测试通过，完成首页、密码、设置、悬浮控制栏和横屏键盘截图检查。修复 TLS 根证书加载后，新增的 3 项环回 TLS 测试与原有测试合计 10 项通过；修复前可稳定复现受信证书握手失败。当时尚未连接真实电脑。
+设备回归仅保留 TLS 证书校验、凭据加密及服务器隔离、原生连接生命周期、键盘映射、画面设置状态、网络采样、公告与预览数据持久化、版本兼容判断。预览存储测试使用生成的纯色位图，不采集屏幕或视频画面。
 
-此前使用 Retroid Pocket 2S（Android 11）通过 P2P 连接 Mac 的延时测试包含 Android 专用解码队列保护。该策略现已撤销，历史延时数据不能代表当前版本；后续统一进行跨平台解码队列优化与性能验证。4K / 60 fps 超过该设备的软件解码能力时仍可能产生积压。声音、触控、屏幕切换、剪贴板完整互通及其他 Android 版本真机仍需进一步验证。
+UI 验证统一由人工完成，不维护页面导航、布局、动画、悬浮窗和截图采集的自动化用例。许可证和构建资料的完整性由 `test/verify_apk.py` 检查。
 
-公告功能新增 12 项测试，覆盖摘要/正文分页、全量未读计数、读取和删除的持久保存、版本更新、服务器及身份隔离、乱序/重复/畸形回复、超时、磁盘写入失败、安全链接和原生信令回调；UI 测试验证角标、详情、下拉刷新、左滑删除、空态和重试。2026-10-01 在 Android 15 arm64 / 16 KB 模拟器上，包含连接、密码、悬浮菜单、画面设置和网络统计的 47 项回归测试通过；APK 对齐检查、原生协议测试及 Lint（零错误）通过。模拟器连接实际默认服务器后，成功加载 1 条公告并显示正确的未读数量；详情及删除操作使用独立测试数据验证。
+## MediaCodec 编解码
 
-远程预览功能新增 11 项测试：默认关闭与授权约束、保存与跨实例读取、服务器隔离、重复连接、清除及删除与未完成截图的竞争、清除失败后重试、损坏图片、居中裁剪，以及开关/清除/撤回授权的页面流程。实际 Surface 截图测试验证 640×360 输出、排除本地覆盖控件、每次连接仅保存一次、首页展示及重启后读取。2026-10-01 在 Android 15 arm64 / 16 KB 模拟器上，58 项预览、公告、连接、密码、布局、画面设置与网络统计回归测试通过。模拟器连接本机 Mac 实测生成 640×360 JPEG 预览，关闭开关后预览目录已清除，原有连接记录和已保存密码保留。
+实现参照 MiniRTC 的 NVCodec 分层：`src/media/mediacodec/` 负责硬件后端、能力查询和 JNI/Surface 资源；`src/media/video/encode/mediacodec/` 与 `src/media/video/decode/mediacodec/` 分别接入编码器、解码器接口，并负责同编码格式的软件回退。Android 工程直接编译这些源码。通用 API 仅需启用 `hardware_acceleration` 和 `native_video_output`。JavaVM 由 Android JNI 适配层在 `JNI_OnLoad` 中设置到后端私有实现；该桥接不安装为 SDK 头文件，也不导出为动态库符号。当前能力查询和 SurfaceTexture 创建依赖 JNI，缺少 JavaVM 时仍可使用软件编解码。独立输出线程在画面停止更新后仍会取出最后一帧，空闲时休眠。
 
-页面转场新增 7 项测试，覆盖进入/返回的首帧及中间帧位置、正常播放结束、连续导航与系统返回、同页刷新、后台及尺寸变化中断、转场中的输入拦截，以及关闭系统动画后直接切换。会话测试确保视频 Surface 所在页面保持不透明、不建立硬件缓存层，只对其上方的普通页面做淡入淡出，避免视频 Surface 的透明度兼容问题。2026-10-01 在 Android 15 arm64 / 16 KB 模拟器上，包含已有功能的 65 项回归测试通过；转场中间帧截图、Lint（零错误）和 APK 对齐检查通过。
+- H.264 / AV1 由系统能力查询选择硬件组件，支持编码码率调整、请求关键帧和分辨率变化。编码输入为 8 位 NV12，硬件需支持 NV12 / I420 ByteBuffer 输入；不满足时回退 OpenH264 / SVT-AV1。当前应用仍是控制端，库的编码能力不代表已实现安卓被控端。
+- 解码原生输出为可保留/释放的 MediaCodec 缓冲区，显示线程直接提交 Surface。切换显示器、销毁 Surface 和切回软件输出时解除旧 Surface 绑定。缓冲区在解码器重建或销毁后不可再次显示；未显示的缓冲区自动归还。
+- 关闭原生输出时，支持将硬件 NV12 / I420 输出按行距、填充高度和裁剪范围转换为紧凑 NV12；未知布局回退软件。
+- Retroid Pocket 2S 的 `OMX.sprd.av1.decoder` 实际加载软件 dav1d，虽被系统标成硬件组件，仍明确排除；AV1 使用软件回退。H.264 可使用 `OMX.sprd.h264.encoder` / `OMX.sprd.h264.decoder`。
 
-分段选项动画接入后，页面转场、布局与画面设置的 30 项相关回归测试通过，覆盖设置保存、能力变化、应答排序、拒绝及超时回退。模拟器录屏检查确认鼠标控制、画面偏好的选中底块连续滑动，悬浮控制栏布局保持稳定；Lint 零错误，APK 对齐检查通过。
+AV1 硬件路径尚无对应实机验证；Retroid 上使用 dav1d 软件解码。
 
 ## 开源资料