feat(harmony): stream screens over HDC without a companion app
Replace per-frame file capture with the unchanged official Hypium agent, bounded JPEG decoding, independent control RPC and scoped session cleanup. Remove the HAP build and account-signing experiment. All 85 automated checks pass; moving-screen performance and integrated phone input remain unverified because the USB device went offline. Keep published 0.3.2 artifacts unchanged.
This commit is contained in:
@@ -1,78 +1,40 @@
|
||||
# Harmony Connector 连续视频开发验证
|
||||
# Harmony Connector 持续投屏开发验证
|
||||
|
||||
当前为待真机验证的开发组件，尚未接入插件播放器，也未发布新插件版本。已发布的 0.3.2 仍使用逐帧截图。不要将本篇的编码配置或本机生成视频测试结果描述成手机实测性能。
|
||||
运行路径为：已授权的 HDC USB 连接 → 官方 Hypium 设备代理 → 持续 JPEG 推送 → 插件显示。用户无需开发者账号、AppGallery Connect、HAP 安装、编译或签名。代理由插件自动部署到本次会话的临时文件，停止时删除。
|
||||
|
||||
## 已完成与待验证
|
||||
## 当前状态
|
||||
|
||||
2026-09-10 的原链路真机采集耗时为 696、803、802 ms，约 1.3 fps。截图命令、PNG 文件回传和图像转换是逐帧执行的；调整界面定时器不足以实现实时视频。
|
||||
2026-09-10：已发布的 0.3.2 仍使用逐张截图，真机原链路为 696、803、802 ms，约 1.3 fps。当前源代码已替换该路径，尚未发布新版本。
|
||||
|
||||
新增源码：
|
||||
官方 `xdevice-devicetest` 6.1.0.210 的 `uitest_agent_v1.2.2.so` 已在 HUAWEI Pura 70 Ultra 的商业系统上成功加载。独立探针收到真实 JPEG、屏幕尺寸 1260 × 2844，并成功调用尺寸、旋转和唤醒接口。设备端文件为 600245 字节，未改动签名原件。没有安装 HAP，也没有账号或系统共享确认步骤。
|
||||
|
||||
- `curios/harmony-connector/companion`：官方 Empty Ability 模板上的普通手机应用。用户点击共享后，经系统授权，将 AVScreenCapture Surface 接到 H.264 编码器。初始配置最长边 1280、30 fps、4 Mbps CBR、Baseline、1 秒关键帧间隔，不采集音频。
|
||||
- `tools/harmony-stream.py`：独立 Mac 开发验证程序，建立本会话 HDC 转发、启动组件、接收与解码视频，输出接收帧率、解码帧数和码率。默认不保存画面文件、不发送输入。`--view` 用于人工观看。
|
||||
- `tools/harmony-stream.test.py`：协议尺寸与长度限制、断流、超时、非 H.264 数据，以及真正经过 FFmpeg 编码与解码的 20 帧生成视频测试。
|
||||
探测期间手机主要处于锁屏或静止状态。黑色首帧、短暂变化及收包时间不能证明动态帧率或端到端延迟达标。接入生产后端时手机变为 Offline，后端的完整真机连通、持续动态画面、输入及重连仍待验收。自动化替身测试不替代这项验收。完整自动化检查通过 85 项：47 项原生、32 项 UI/格式/坐标、6 项 USB 桥接与底座协议检查。
|
||||
|
||||
已使用官方 Command Line Tools 26.0.0.821 编译出 arm64-v8a 未签名 HAP，包含 ArkTS 和本地 C++ 动态库；编译兼容级别 API 17，使用的采集接口最低 API 14。编译成功不代表商业设备运行授权与编码能力已经验证。
|
||||
之前的 HAP 实验源码和签名流程已移除。本机签名材料不属于插件或发行包。原方案的研究过程保留在[历史记录](research/harmony-realtime-stream.md)，当前方案及来源见[HDC 持续投屏调研](research/harmony-hdc-only-screen.md)。
|
||||
|
||||
签名工具已登录，但调用 `signature generate` 返回账号尚未完成开发者实名认证。尚未安装伴随应用、取得真机 H.264 视频、测量呈现帧率或端到端延迟。
|
||||
|
||||
## 构建与签名
|
||||
|
||||
需要完整官方 Command Line Tools、Node.js 22+、官方 `@deveco/deveco-cli@1.3.0-stable`。`DEVECO_CLI_CLT_PATH` 指向包含 `sdk`、`tool`、`hvigor` 的 `command-line-tools` 根目录，不是单独的 HDC 所在目录。
|
||||
## 构建和验证
|
||||
|
||||
```sh
|
||||
cd curios/harmony-connector/companion
|
||||
# 首次准备；已有配置时保留本机签名。
|
||||
test -f build-profile.json5 || cp build-profile.template.json5 build-profile.json5
|
||||
node curios/harmony-connector/build.mjs
|
||||
node tools/test-harmony.mjs
|
||||
|
||||
# 预先按本机实际路径设置 DEVECO_CLI_CLT_PATH。
|
||||
npx --yes @deveco/deveco-cli@1.3.0-stable build --modules entry --build-mode debug
|
||||
# 手机开启 USB 调试并授权 Mac；多设备时在末尾加目标 ID。
|
||||
curios/harmony-connector/backend/harmony-connector --check-screen /absolute/path/to/hdc
|
||||
|
||||
# 连续 20 秒，通过与 UI 相同的后端接口接收并实际解码 JPEG。
|
||||
curios/harmony-connector/backend/harmony-connector --check-screen-stream /absolute/path/to/hdc
|
||||
```
|
||||
|
||||
得到 `entry/build/default/outputs/default/entry-default-unsigned.hap`。真实手机安装必须有合法签名；需要已实名认证的华为开发者账号，按官方流程配置可调试设备。认证入口是 [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)，见[官方开发准备](https://developer.huawei.com/consumer/cn/appgallery/devstart/)。
|
||||
动态测量时保持手机解锁，并连续滑动桌面或滚动页面。`receivedFps` 与 `mbps` 是最近一秒收到的帧数和码率；`consumerFps` 是此验证程序在完整观察期解码的不同帧数除以时长，不是 WebView 呈现帧率。`frameAgeMs` 是收到画面后经过的时间，不是端到端延迟。静止画面不重复计帧。
|
||||
|
||||
```sh
|
||||
npx --yes @deveco/deveco-cli@1.3.0-stable auth login
|
||||
npx --yes @deveco/deveco-cli@1.3.0-stable signature generate --product default
|
||||
npx --yes @deveco/deveco-cli@1.3.0-stable build --modules entry --build-mode debug
|
||||
```
|
||||
上述命令默认不保存画面、不启用控制，也不发送输入。基础连通命令的第三个参数可以是用户指定的保存目录。真实交互仍需在插件中检验：启用控制、点击、拖动、返回/主页、文字输入、停止后重新开始，以及拔线后旧画面清空。
|
||||
|
||||
`build-profile.json5`、签名证书、profile 和密码材料均属于本机文件，不提交到仓库。模板 `build-profile.template.json5` 不包含签名配置。不要将绑定调试设备的 HAP 当作所有用户均可安装的发行包；正式手机组件需要发布者签名和正式分发流程。
|
||||
## 会话与协议
|
||||
|
||||
## 真机验证
|
||||
- 插件只保留最新一张 JPEG，不积压视频队列。UI 用上一帧序号等待变化；静止时返回状态，不重复发送图片。
|
||||
- 图像与控制使用两个独立 socket，共用本会话的 HDC 转发。按键和手势通过持久 RPC 发送，文字使用已验证的 `uitest uiInput text`。
|
||||
- 代理回包包括 JSON 行与 JPEG；解析 JPEG 段长度，避免把 EXIF 数据中的字节误认作图像结尾。单帧上限 2 MiB，JSON 上限 64 KiB。
|
||||
- 静止画面不视为断线；独立控制连接查询尺寸检查存活。UI 停止请求超过 15 秒会结束会话。屏幕几何变化会关闭输入控制。
|
||||
- 每次部署使用唯一文件名，只结束加载该文件的进程，只删除本次转发和文件。发现其他 UITest 会话时提示占用，不接管或结束其他调试工具。
|
||||
|
||||
先确认 `hdc list targets -v` 显示目标为 `Connected`。安装刚构建的 **signed** HAP，包名为 `ink.render.trove.harmonyconnector`。安装应选择明确目标，不自动安装到其他设备。
|
||||
|
||||
在仓库根目录执行以下命令，将 HDC 路径替换为本机工具路径；连接多台设备时另加 `--target`：
|
||||
|
||||
```sh
|
||||
python3 tools/harmony-stream.py --hdc /absolute/path/to/hdc --seconds 20
|
||||
# 人工观看连续画面；需 ffplay。
|
||||
python3 tools/harmony-stream.py --hdc /absolute/path/to/hdc --seconds 20 --view
|
||||
```
|
||||
|
||||
运行时在手机点击「共享屏幕」，同意系统请求，滚动页面或移动窗口产生持续变化。默认验证需要 FFmpeg；它只用于开发测量，未引入生产插件依赖。
|
||||
|
||||
接收帧率目标至少 20 fps，默认解码模式同时要求解码帧数达到收到视频帧数的 95%。这些只是开发验收门槛，不能代替端到端延迟测量。`--view` 的 FFplay 不提供解码帧计数，需另外运行默认模式；人工确认的流畅程度应单独记录。静态画面可能由系统抑制重复帧，性能测试必须保持画面变化。
|
||||
|
||||
停止共享、系统拒绝、拔线、关闭验证程序都必须终止手机采集并清理仅本会话的转发。当前原型在屏幕尺寸变化时停止共享，提示重新开始；自动旋转重建、插件播放器集成及流式会话中的输入验证仍待完成。
|
||||
|
||||
## 传输与资源边界
|
||||
|
||||
手机仅监听 IPv4 loopback，由启动端提供随机远端端口和 32 字节会话随机值。连接后首先发送 64 个小写十六进制字符进行会话校验，不通过则断开。正常用户操作仍需手机点击共享以及系统录屏授权。
|
||||
|
||||
验证成功后，手机发送固定 24 字节头：`HCS1` + 5 个大端 u32，依次为编码宽、高、屏幕宽、高、配置帧率。随后每包为大端 `u32 payloadLength + u32 flags + i64 ptsUs + Annex B H.264 payload`，沿用公共编码器的 buffer flags。SPS/PPS 配置数据与编码帧均按输出顺序保留。
|
||||
|
||||
单包上限 2 MiB；采集回调复制数据后归还编码器 buffer。发送队列上限 6 包和 4 MiB，超过就结束会话，不积压旧帧，也不任意丢弃参考帧。Socket 发送超时 500 ms。主机发送一个零字节或断开连接可停止采集。系统停止与错误统一由资源所属线程收尾，释放 capture、encoder、surface、socket。
|
||||
|
||||
这仍是开发协议，尚未替代正式产品的配对、版本协商和播放器生命周期设计。普通录屏授权也不会赋予任意输入注入权限；后续控制需复用已授权的 UITest 能力并验证响应。
|
||||
|
||||
## 自动化验证
|
||||
|
||||
```sh
|
||||
python3 tools/harmony-stream.test.py -v
|
||||
```
|
||||
|
||||
测试不连接手机；使用本地 socket pair 验证接收行为，使用生成图案验证实际 H.264 解码。当前 8 项通过，20 帧均成功解码。它们不证明手机端授权、编码吞吐、后台保活或 USB 实时性。
|
||||
|
||||
API、权限和被拒绝的无安装路线见[连续视频调研](research/harmony-realtime-stream.md)。
|
||||
运行 HDC 不需要完整 SDK：本机独立验证了 `hdc` 与同目录 `libusb_shared.dylib` 的版本命令，总计约 6.4 MiB。完整工具包用于开发构建，不应成为普通投屏用户的依赖。本次尚未新增精简 HDC 发行包；插件继续使用已配置或自动发现的官方工具。
|
||||
|
||||
Reference in New Issue
Block a user