239 lines
22 KiB
Markdown
239 lines
22 KiB
Markdown
# Harmony Connector 实时投屏性能：官方资料与协议
|
||
|
||
调研日期：2026-09-10。范围：macOS、用户已授权的 USB 调试/HDC、官方 UITest 扩展；不要求开发者账号、HAP 安装、root 或修改设备安全策略。本报告仅做官方资料及官方分发包的静态分析，没有启动设备代理或测量手机帧率。用户要求优先完成编码，因而不在本报告中承诺实测 60 fps。
|
||
|
||
## 结论
|
||
|
||
应把实时画面从逐帧 JPEG 改为官方 Hypium recorder 的 H.264 视频流，再由 macOS 的持久视频图层显示。Hypium **26.0.0.500** 官方包确实提供已带签名块的 Unix socket recorder，可通过 HDC 的 `localabstract` 转发实现设备端无 TCP 监听的连接。此前检查的 PyPI 6.1.0.210 包缺少这些 Unix recorder，不能据此判断鸿蒙没有这条路径。[官方 Hypium 下载页](https://developer.huawei.com/consumer/cn/download/deveco-testing-hypium)、[官方 26.0.0 发布说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/deveco-testing-releasenotes-2600)
|
||
|
||
**容易接错的 socket：实时 `-m 0` 使用 `scrcpy_grpc_socket`；文件录制 `-m 1` 使用 `screen_record_grpc_socket`。** 官方 Python 的 `record_agent.py` 是文件录制封装，照抄它的 socket 名并把 mode 改为 0，会连不到实时服务。此区别直接来自 26 包 `libscrcpy_server_unix_6.6-20260629.z.so` 的 `RpcServer::InitServer`，见下文精确位置。
|
||
|
||
## 官方分发包和本地证据
|
||
|
||
来源是官方下载页当前列出的 **DevEco Testing Hypium 26.0.0.500，118.7 MB，2026/08/29**。通过用户现有网页登录状态点击正常下载取得官方 CDN 文件，未要求新账号或签名授权。临时签名下载 URL 不写入仓库。
|
||
|
||
研究文件保存在忽略目录 `dist/harmony-screen-performance-research/`；不是产品运行时路径。
|
||
|
||
| 文件 | 本地计算的 SHA256 |
|
||
| --- | --- |
|
||
| `devecotesting-hypium-26.0.0.500.zip` | `1c66fb288a291e3cd1743a4bf82708752bcef58c230748088194182f304a097f` |
|
||
| `hypium26/python/xdevice_devicetest-26.0.0.500-py3-none-any.whl` | `810b2d33bb86a6fe91c5f24fe9bc33cc3937e3af84ce1d760e3257bb648f9c06` |
|
||
|
||
外层 zip 包含 `hypium-26.0.0.500.zip`、`hypium-driver-js-26.0.0500.zip` 和 PyCharm 插件 zip。Python zip 包含 hypium、xdevice、xdevice_ohos、xdevice_devicetest 四个 wheel、API 文档和安装脚本。只解压读取，没有运行安装脚本。以上是下载原件的本地校验摘要，不声称已经另行比对官网公布的 SHA256。
|
||
|
||
以下资源的完整本地目录为：
|
||
|
||
```text
|
||
dist/harmony-screen-performance-research/hypium26/python/
|
||
xdevice_devicetest/devicetest/res/recorder/
|
||
```
|
||
|
||
| Unix recorder 原件 | 字节 | SHA256 |
|
||
| --- | ---: | --- |
|
||
| `libscrcpy_server_unix_6.3.1-20260113.z.so` | 272567 | `3e29e3a1d23ea6dbd4e6fb3b8f094ca5d4b15b4c580f421fba3d0e1f5429e3fe` |
|
||
| `libscrcpy_server_unix_6.4-20260113.z.so` | 264374 | `b698b41ae1351337eeea3dcc87bf0160552196d669ba321b4963c342fa5a47f4` |
|
||
| `libscrcpy_server_unix_6.5-20260313.z.so` | 268469 | `2c8f1ef94d581281bf8e86d54f5939af9b205d5db5aa2cfb27f2562215c87b0a` |
|
||
| `libscrcpy_server_unix_6.6-20260418.z.so` | 268471 | `98bbc964fef1c4d17b446ec717102b855d09224b23fc1872bf70e1f928d010dd` |
|
||
| `libscrcpy_server_unix_6.6-20260629.z.so` | 260278 | `b24231188ab0fffa84c2bd71cab6948c8ffad9d661c80301f32eaf580177ce8e` |
|
||
|
||
各 Unix 原件均含 `elf sign block`；旧 recorder 也带该块及 Huawei 软件签名证书链字符串。这证明分发文件带有签名结构，不等于本报告独立完成签名密码学验证，也不保证每个系统版本均接受每个原件。必须完整保留原件字节，不能 strip、改监听地址或重签名再声称是官方原件。
|
||
|
||
同 wheel 还提供 `devicetest/res/prototype/native/uitest_agent_v1.2.3.so`，以及 1.1.3、1.1.5、1.1.12 和 x86_64 资源。wheel 的 `xdevice_devicetest-26.0.0.500.dist-info/licenses/LICENSE` 是 Apache License 2.0；相关 Python 文件带 Huawei Device Co., Ltd. 的 Apache 2.0 版权头。打包时保留对应许可和来源，不把另一个独立下载包的授权凭空套用到这些文件。
|
||
|
||
`uitest_agent_v1.2.3.so` 原件为 **600246 字节**，SHA256 为 `5dfbaca7e274a85bece8f225148ceb759b94d7319b956b9a7ea40d37944e4a9b`。该 wheel 的 METADATA 明列 `License-File: LICENSE`；解包中未发现另外的 NOTICE 或逐二进制许可文件。产品随两种原件保留这份 LICENSE，并在自己的第三方声明中记录 Huawei 官方分发包、版本、原件路径、摘要及未修改状态；不要将自己补写的来源说明说成上游附带 NOTICE。
|
||
|
||
## 官方代理选择规则
|
||
|
||
直接证据文件：
|
||
|
||
```text
|
||
hypium26/python/xdevice_devicetest/devicetest/controllers/tools/recorder/record_agent.py
|
||
hypium26/python/xdevice_ohos/ohos/environment/device.py
|
||
```
|
||
|
||
`RecordAgent._start_scrcpy_server` 首先读取 UITest 版本，要求至少 4.1.4.6，随后按 `device.check_if_unix_socket_mode()` 决定传输。后者实际代码判断为 UITest 版本元组大于 `6.0.2.1` 且架构不含 `x86_64`。旁边注释写的是“大于 6.0.2.2”，与代码不完全一致；客户端应使用实际能力和数值版本解析，不照抄字符串元组比较的问题。
|
||
|
||
Unix 分支只尝试文件名含 `unix` 的资源；非 Unix 分支只尝试不含 `unix` 的资源。官方按 `os.walk` 文件列表倒序逐个启动，**没有把文件名的 6.3.1 / 6.6 映射为 HarmonyOS 产品版本**。插件应固定已支持的原件，或采用明确的兼容性候选顺序；不能声称手机必须运行“鸿蒙 6.6”。
|
||
|
||
官方会覆盖 `/data/local/tmp/libscreen_recorder.z.so`，以进程命令和 `/proc/net/unix` 检查启动是否成功。产品应为自己的扩展文件与进程记录所有权，不复用或结束别的 UI 调试会话。Unix socket 名在原件中固定，因此冲突时应明确报告，而不是杀掉所有 `uitest` 进程。
|
||
|
||
## 实时 H.264 的最小连接流程
|
||
|
||
这是根据官方启动脚本和原件参数解析重建的编码接口，未在本研究中对手机执行。`HDC`、`SERIAL`、`LOCAL_PORT`、`AGENT` 为客户端已校验的值；远端扩展文件名使用本插件自己的固定名称。
|
||
|
||
```sh
|
||
"$HDC" -t "$SERIAL" file send "$AGENT" /data/local/tmp/libharmony_connector_screen.z.so
|
||
"$HDC" -t "$SERIAL" fport "tcp:$LOCAL_PORT" localabstract:scrcpy_grpc_socket
|
||
"$HDC" -t "$SERIAL" shell /system/bin/uitest start-daemon singleness \
|
||
--extension-name libharmony_connector_screen.z.so \
|
||
-m 0 -scale 2 -frameRate 60 -bitRate 8000000 -iFrameInterval 1000 -screenId 0
|
||
```
|
||
|
||
随后连接主机端 `127.0.0.1:LOCAL_PORT`，以 HTTP/2 gRPC 调用 `/ScrcpyService/onStart`，请求为 `Empty`，持续读取 server stream。无需创建 Driver、申请开发者证书、安装 HAP 或另发初始化 RPC。控制连接独立使用 UITest agent，避免视频读循环被输入 RPC 阻塞。
|
||
|
||
`RpcServer::InitServer` 在最新 Unix 原件中的入口是 `0x1a960`：
|
||
|
||
- `0x1aa40–0x1aa74` 默认初始化 `scrcpy_grpc_socket`，只在 mode 等于 1 时跳转。
|
||
- `0x1ada8–0x1adb8` 将 mode 1 的名字替换为 `screen_record_grpc_socket`。
|
||
- 字符串地址 `0xe001` 是 `scrcpy_grpc_socket`，`0xe014` 是 `screen_record_grpc_socket`，`0xeeca` 是 `unix-abstract:`。
|
||
- `0x1aaf0–0x1ab0c` 拼接 `unix-abstract:` 后调用 gRPC `AddListeningPort`。没有在这个路径构建 IP:port。
|
||
|
||
官方 Python 的 `-p 5001 -m 1` 是录文件场景。新版 Unix 参数日志将 port 标记为 `[deprecated]`；实时启动不必配置设备 TCP 端口。
|
||
|
||
设备端抽象 Unix socket 不在 WLAN IP 上监听；主机端仍需确保本地转发仅被期望的本机客户端访问。HDC 本身若被另行配置成网络调试，则不能仅因使用 `localabstract` 就宣称整个 HDC 会话来自 USB。
|
||
|
||
### 视频与控制同时运行
|
||
|
||
最简单的官方组合是 **两个独立 `singleness` daemon**，各加载一个扩展。`ExecuteExtension` 只读取第一个 `--extension-name` 并 `dlopen` 一个文件，没有一次加载两个代理的参数语义。[官方扩展加载源码](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/uitest/addon/extension_executor.cpp#L353)
|
||
|
||
`server_main.cpp::StartDaemon` 在 `token == "singleness"` 时直接执行扩展，该分支不调用普通 peer 连接的 `InitAndConnectPeer`，也没有以 singleness 命名的全局互斥锁。这里的字符串不是“设备只能有一个 UITest 进程”的代码证据。[官方 daemon 源码](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/uitest/server/server_main.cpp#L471)
|
||
|
||
官方 Hypium 26 的 `ohos/proxy/ui_proxy.py::start_uitest` 启动 `uitest start-daemon singleness`，默认加载 `/data/local/tmp/agent.so` 并转发 `uitest_socket`；`RecordAgent` 另外启动带 `--extension-name libscreen_recorder.z.so` 的 daemon。其 UI 进程查找还特意排除命令中带 `--extension-name` 的进程，以区分录屏。`devicetest/core/variables.py::_start_record_step_screen` 在测试步骤期间启动 recorder，说明官方设计就是 UI 自动化和录制并行，而不是两个功能择一。
|
||
|
||
因此插件应采用：
|
||
|
||
```text
|
||
控制：uitest start-daemon singleness --extension-name <本插件的控制原件文件名>
|
||
HDC localabstract:uitest_socket → 主机控制端口
|
||
视频：uitest start-daemon singleness --extension-name <本插件的视频原件文件名> -m 0 ...
|
||
HDC localabstract:scrcpy_grpc_socket → 主机视频端口
|
||
```
|
||
|
||
产品自己的会话检查必须识别这两个进程同属一个会话；不能看到任何其他 `uitest` 进程就拒绝。固定 socket 被其他应用占用时仍属于真实冲突，应保持现有不抢占策略。上述是官方源码和分发包的并行设计证据，不额外声称已对所有商业设备系统实现完成兼容测试。
|
||
|
||
### 参数
|
||
|
||
下表来自最新 Unix 原件 `RpcServer::parse_params` (`0x19c70`) 的静态分支，不是面向第三方的长期 API 稳定性承诺。
|
||
|
||
| 参数 | 已确认规则 |
|
||
| --- | --- |
|
||
| `-m` | 1 为 MP4 录制；其他值归为 0，实时回传编码 buffer |
|
||
| `-scale` | 整数 1–5；小于等于 0 回 1，大于 5 限为 5。不是 JPEG 接口的 0.5 浮点比例 |
|
||
| `-frameRate` | 最新 Unix 6.6-20260629 接受 15、30、60；内部计算 `120 / value` 的虚拟屏刷新间隔。120 会回默认 60，不能沿用旧 recorder4 接受 120 的结论 |
|
||
| `-bitRate` | 至少 1048576 bit/s，否则恢复默认 31457280；按负载选择码率，不要把最大值当低延迟默认 |
|
||
| `-iFrameInterval` | 非负整数；非法值回 2000；需与编码器间隔单位契约一致 |
|
||
| `-screenId` | 非负显示 ID，通常主屏为 0 |
|
||
| `-repeatInterval` | 新参数，接受 8、16、33，其他值恢复 0；引用 `OH_MD_KEY_VIDEO_ENCODER_REPEAT_PREVIOUS_FRAME_AFTER` 和 `...MAX_COUNT`。它用于重复之前的编码帧，不代表多采到了新画面 |
|
||
|
||
原件也存在 appPid、windowsId 和其他内部参数。当前需求不需要绕开安全窗口，不能把这些参数用作获取受保护内容的手段。
|
||
|
||
## gRPC 消息
|
||
|
||
官方文件位于 `.../controllers/tools/recorder/proto/scrcpy_pb2.py` 和 `scrcpy_pb2_grpc.py`。26.0.0.500 的 `scrcpy_pb2.py` 与下载到的 6.1.0.210 版本内容完全相同。
|
||
|
||
```proto
|
||
syntax = "proto3";
|
||
|
||
service ScrcpyService {
|
||
rpc onStart(Empty) returns (stream ReplyMessage);
|
||
rpc onEnd(Empty) returns (ReplyEndMessage);
|
||
rpc onRequestIDRFrame(Empty) returns (ReplyEndMessage);
|
||
}
|
||
message Empty {}
|
||
message ReplyEndMessage { int32 result = 1; }
|
||
message ReplyMessage {
|
||
string data = 1;
|
||
int32 reply_type = 2;
|
||
map<string, ParamValue> payload = 3;
|
||
}
|
||
message ParamValue {
|
||
oneof values {
|
||
int64 val_int = 1;
|
||
double val_double = 2;
|
||
string val_string = 3;
|
||
bool val_bool = 4;
|
||
bytes val_bytes = 5;
|
||
float val_float = 6;
|
||
}
|
||
}
|
||
```
|
||
|
||
没有 protobuf package 前缀。三个路径分别为 `/ScrcpyService/onStart`、`/ScrcpyService/onEnd`、`/ScrcpyService/onRequestIDRFrame`。
|
||
|
||
官方 recorder4 的 `ReplyVideoData` 和静态全局键初始化能确认：`payload["data"].val_bytes` 才是编码数据；`len`、`flags`、`pts` 使用 `val_int`。外层 string `data` 不是视频 bytes。最新 Unix 原件仍有同签名的 `ReplyVideoData` 和同一协议；客户端应验证字段类型、长度和包大小，不根据日志字符串找图像。
|
||
|
||
`reply_type` 在 proto 中是普通 int32，没有枚举定义。本研究不猜测完整枚举含义。`flags` 来自媒体输出 buffer 属性，应按编码配置、关键帧和 EOS 标志处理，而不是把所有 payload 都当普通视频帧。
|
||
|
||
旧 recorder4 的 `OnNeedOutputData` 在 mode 0 里取 `OH_AVMemory_GetAddr + offset`、长度和 flags，调用 `ReplyVideoData`；mode 1 才调用 `OH_AVMuxer_WriteSample`。它发送的 pts 来自输出时的 `system_clock.now()`，静态除数和 SDK chrono 单位指向毫秒，而不是直接复制编码器 `attr.pts`。**不要未经归一化将它当微秒或主机单调时钟；首版实时显示可采用立即显示，不等待设备绝对时间。** 最新原件实际时间语义仍应通过客户端观察校准，不在这里声称已测过。
|
||
|
||
停止时，保持 stream reader 存活，用同一 channel 发 `onEnd(Empty)`，然后释放流、关闭本插件通道并删除本插件 fport。官方 Python 将 `ReplyEndMessage.result` 用作录制帧数；不应把它一概当布尔成功码。`onRequestIDRFrame` 可以用于解码器重新同步；不要每帧请求 IDR。异常时只清理本插件拥有的进程。
|
||
|
||
官方 `rpc_manager.py` 建立 insecure gRPC channel，未设置应用层 token；其 5 秒 `onStart` 超时适合官方录制封装，不能直接复制为持续投屏生命周期。其最大消息大小 option 拼写为 `grpc_max_receive_message_length`，使用其他客户端时应按对应 gRPC 库的正确配置项设置大小上限。
|
||
|
||
## 为什么不采用旧 TCP recorder
|
||
|
||
已下载的官方 PyPI 6.1.0.210 资源只有 `libscrcpy_server1.z.so` 至 `4.z.so`。其中 recorder4 的 `InitServer` 使用固定 `0.0.0.0` 和 `grpc::InsecureServerCredentials()`；完整参数解析没有 host、listen address 或 Unix 参数。它不是仅绑定 USB 的服务，HDC 转发本身不会把设备上已经存在的 TCP listener 限制到 USB。
|
||
|
||
未找到说明该无鉴权 gRPC 端口必然被系统网络隔离的官方保证。不能依赖这种假设作为默认生产方案，也不能修改签名原件或安全策略。26 包的 Unix 版本已经给出更合适的连接机制。[官方 PyPI 分发原件](https://files.pythonhosted.org/packages/a2/b5/55bdfe4d669558331499848dbc68269506abb9b4a771e3524a65f9845127/xdevice_devicetest-6.1.0.210-py3-none-any.whl)
|
||
|
||
## 真正的按下、移动、抬起
|
||
|
||
在 26 官方包的 `uitest_agent_v1.2.3.so` 中，`OHOS::uitest::HandleGesture` (`0x28c34`) 直接确认了以下内层请求：
|
||
|
||
```json
|
||
{"api":"touchDown","args":{"x":120,"y":360}}
|
||
{"api":"touchMove","args":{"x":125,"y":370}}
|
||
{"api":"touchUp","args":{"x":125,"y":370}}
|
||
```
|
||
|
||
沿用现有 UITest RPC 外层 envelope 和 `method: "Gestures"`，不要把这些请求发往视频 gRPC 服务。
|
||
|
||
证据链：
|
||
|
||
- `0x28ca0` 取 `api`，确认是字符串；`0x28cc4` 取 `args`，确认是对象。
|
||
- `0x28fd4–0x29028` 的内联字节比较包含 `touchDown` 与 `touchMove`；`0x28e88–0x28ec0` 检查 `touchUp`。
|
||
- 三者汇入 `0x28ec4`，读取 `x` (`0xdee2`) 和 `y` (`0xdd4a`)；均要求整数类型，然后调用 `EasyJSON::GetInteger`。
|
||
- `0x29700–0x2977c` 将 down/move/up 分别映射为动作 1/2/3，经 `Modules::GetUiTestLowLevelFunctions()` 的触控函数注入。
|
||
- 成功路径调用结果 callback，结果对象保持 `SetNull()`，不是截图或坐标返回值。错误路径包括 `Illegal gesture api` 和 `Illegal touch point coordination`。
|
||
|
||
**没有发现 touchCancel 分支，也不能依赖断开连接自动抬起。** 同原件的 `GestureHandleSessionDeathBroadcast` 指向 `0x1d8f4`，该入口只有一条 `ret`。客户端应持有自己按下的触点状态，在 mouse up、窗口失焦、取消和停止时尽力发送最后坐标的 touchUp，再关闭控制连接。只合并尚未发送的 move，不丢 down/up 或跨越它们重排。使用显示内容区域的坐标映射，扣除黑边并处理旋转，避免将窗口坐标直接当设备坐标。
|
||
|
||
该证据针对 1.2.3 原件；不凭版本相近就声称所有旧 agent 的行为完全一致。研究输出 `.../res/prototype/native/gestures-key.disasm` 保留了相关汇编。
|
||
|
||
## JPEG 路径的性能上限来自哪里
|
||
|
||
OpenHarmony 官方 UITest `screen_copy.cpp` 的生产循环先调用 `DisplayManager::GetScreenshot` 取得全屏 PixelMap，再比较像素是否变化，再缩放并 JPEG 编码。缩放函数持有共享 frameLock；JPEG 质量设置为 75。缩小 scale 能减少缩放后编码和传输成本，但不省掉原始全屏截图读回。源码的 50 ms sleep 位于屏幕关闭处理，不是正常推流固定 20 fps 限制。[官方源码固定版本](https://github.com/openharmony/testfwk_arkxtest/blob/b04e30c40cf266c9abfbd52933e43a0456eb99a2/uitest/addon/screen_copy.cpp)
|
||
|
||
因此，仅改浏览器刷新周期、缩图或提高标称 fps 无法把逐帧截图机制变为 scrcpy 的编码视频链路。这里的开源实现解释了 UITest 公开截图机制，不声称商业 Hypium agent 每个内部细节都与该源码相同。
|
||
|
||
官方 recorder 则引用 `OH_VideoEncoder_CreateByMime`、H.264 MIME、`OH_VideoEncoder_GetSurface` 和虚拟显示 Surface，输出已经编码的媒体 buffer；这才是和 scrcpy 对应的性能方向。实际流畅度仍受设备编码器、虚拟屏刷新、USB/HDC、主机解码与呈现共同影响。
|
||
|
||
## 对照 scrcpy 的实现原则
|
||
|
||
Genymobile 官方文档和源码中，Surface 进入 MediaCodec，视频由独立连接传输，控制由独立线程处理；默认立即显示解码后的帧，额外视频缓冲是显式选项。帧率随画面变化，`max-fps` 是上限而不是静止画面也必须重复达到的最低值。[scrcpy 开发文档](https://github.com/Genymobile/scrcpy/blob/19c1261d2e2cbf2b5e6a71a8b64cc1dd3ede06ac/doc/develop.md)、[视频选项](https://github.com/Genymobile/scrcpy/blob/19c1261d2e2cbf2b5e6a71a8b64cc1dd3ede06ac/doc/video.md)
|
||
|
||
其 `frame_buffer.c` 用 pending/tmp 交换，允许新解码帧覆盖未消费帧；先取得新引用，失败时保留旧帧。这适合用于修复画面闪烁和积压：维持同一个显示 surface，在下一帧确实可呈现时替换，不能先清空旧画面。[scrcpy 帧缓冲源码](https://github.com/Genymobile/scrcpy/blob/19c1261d2e2cbf2b5e6a71a8b64cc1dd3ede06ac/app/src/frame_buffer.c)
|
||
|
||
可移植到插件的设计建议：
|
||
|
||
1. HDC + gRPC reader 独立运行，及时取出编码包，不在同一循环更新 UI 或等待触控。
|
||
2. H.264 按解码依赖顺序送解码器；不能像独立 JPEG 那样随意丢 P 帧。解码后只保留最新可显示帧；编码队列溢出时明确重同步并请求 IDR。
|
||
3. 持久 AppKit 视频视图，避免每帧重建窗口、WebView 图像节点、object URL 或黑底占位。
|
||
4. 配置变更/旋转后重建必要的格式描述，普通帧不重建渲染层。停止期间保留最后有效画面直到状态视图接管。
|
||
5. 分开统计收到编码帧、成功解码帧、实际显示帧、丢帧和队列长度。静止桌面的低更新数不等于卡顿；不能用接收包数冒充显示 fps。
|
||
|
||
这些是从官方机制推导的实现建议，不是本研究的真机性能结果。
|
||
|
||
## macOS 呈现接口
|
||
|
||
`AVSampleBufferDisplayLayer` 能呈现压缩或未压缩视频。H.264 buffer 应正确组成 `CMSampleBuffer`，维护 SPS/PPS 和格式描述，交由系统视频解码/呈现；若使用 VideoToolbox 解码，可设置实时属性并检查实际是否使用硬件解码。[Apple 图层文档](https://developer.apple.com/documentation/avfoundation/avsamplebufferdisplaylayer)、[VideoToolbox 解压属性](https://developer.apple.com/documentation/videotoolbox/decompression-properties)
|
||
|
||
`kCMSampleAttachmentKey_DisplayImmediately = true` 应设置在 **sample attachments array**，用于不按时间戳等待的实时显示。不是对样本调用普通 `CMSetAttachment` 就等价。新样本到达后立即呈现，有助于避免设备绝对时间与主机时间基不一致产生的积压。[Apple DisplayImmediately](https://developer.apple.com/documentation/coremedia/kcmsampleattachmentkey_displayimmediately)、[Apple enqueue](https://developer.apple.com/documentation/avfoundation/avsamplebufferdisplaylayer/enqueue(_:))
|
||
|
||
macOS 14 及以上可使用该层的 sampleBufferRenderer，保留项目要求的旧系统兼容路径。`requestMediaDataWhenReady` 必须与停止请求成对管理，窗口销毁后不能继续向已释放视图派发渲染工作。
|
||
|
||
## 证据边界
|
||
|
||
- 已完成：官方 26 包获取、静态解包、资源摘要、启动/选型脚本、proto 对比、Unix 绑定与触控参数的汇编核查。
|
||
- 未完成且未声称完成：最新 Unix 原件在用户手机的加载兼容性、连续视频解码结果、流畅度/耗电/延迟测量、旧 1.2.2 agent 的触控全量契约复核。
|
||
- 不需要为采用本路径继续下载完整 IDE、创建 HAP 或申请开发者签名；用户的实际前置条件是可用 HDC 与设备调试授权。原件与系统 ABI 的兼容性仍需清楚报告，不能失败后偷偷切回慢截图却继续显示“实时视频”。
|
||
|
||
|
||
## 0.5.1 启动流程修正
|
||
|
||
用户报告的 `Connection refused` 被 0.5.0 视频 TCP 连接处的通用 `std::io::Error → Fault` 包装成 Mac 文件错误。该代码路径可直接定位，但没有真机复现证据可以把底层拒绝进一步归因为某个代理 ABI。
|
||
|
||
实现补齐官方 `RecordAgent` 已做的进程/Unix socket 就绪判断，按上表最新至最旧顺序选择能够启动的官方 Unix 原件。视频连接失败时移除并重建自身记录的转发；不会借用未知转发或终止外部进程。HDC 转发包含本机监听与对端激活阶段，发出 `fport` 命令本身不能代替端到端连接。[HDC 官方转发源码](https://github.com/openharmony/developtools_hdc/blob/master/src/common/forward.cpp)
|
||
|
||
产品错误信息区分设备组件启动、HDC 转发及视频连接；首帧显示前保持“正在建立视频连接”。按用户要求，本轮未跑测试、真机实验或远程安装验证。
|