欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目: https://atomgit.com/OpenHarmonyPCDeveloper


摘要

chiaki-ng 是 PS Remote Play(PS5 串流)的开源客户端:GUI 是 Qt6/QML(几万行 QML + C++ 会话/手柄逻辑),底层是 C 写的 chiaki-lib(ffmpeg 解码 + 自定义协议栈)。把它移植到鸿蒙 PC,最大的难点不是"能不能编译",而是**“一个 Qt 应用怎么变成一个鸿蒙应用”**——鸿蒙应用必须打包成 HAP(ArkUI),而把上游 QML 全部重写成 ArkTS 等于重写整个应用。

本文记录我们选的混合架构路线,以及过程中四类"平台敏感"问题的解法:

  1. 架构:Qt 窗口装进 ArkUI,而不是重写。 ArkUI XComponent 承载 Qt 的 HarmonyOS 平台插件 qohos,Qt 在原生窗口里用 Vulkan 渲染,上游 QML UI 一行不改全部复用;ArkUI 层只做系统壳 + 剪贴板/状态叠加按钮,两层之间用文件桥通信(免权限)。
  2. 构建:CMake 不认 HarmonyOS、Qt 6.12 要打 30+ 文件补丁、ffmpeg NEON 静态链接、.so 还要签名——而 hvigor 打包时会把签名剥掉。 每一步都是一个坑,每一条都只有踩过才知道。
  3. 系统能力:SDL 音频在 OHOS 上必然初始化失败(SDK 的 SDL 没有 OHOS 后端)→ 改用系统 Audio Kit(OHAudio OH_AudioRenderer);视频走 OH_AVCodec 硬解;手柄盲区键(R1/PS)靠系统键码桥合成 SDL 事件。
  4. 最花时间的其实是"看起来和代码无关"的网络问题。 串流每 ~18 秒顿挫一次:用 hilog + 内核 kmsg + 逐包 ping 三方对齐,定位到 PC 侧 Wi-Fi 子系统(Wifi2/MultiSta 增强)每 18.0 秒重连一次主接口,产生 100–305 ms 纯时延尖峰而 ICMP 0% 丢包;另一次"声音卡顿"用 PS5 切有线的对照实验(音频欠载率 100% → 0.07%)证明根源在 PS5 侧 Wi-Fi 链路。

项目地址:

在这里插入图片描述


目录


1. 项目概览

项目信息
目标平台HarmonyOS PC(OpenHarmony-7.0.0.105,API 26,aarch64,2in1)
编译器OHOS SDK llvm clang(ohos.toolchain.cmake)
语言/构建C(chiaki-lib)+ C++/QML(Qt 6.12)+ ArkTS(HAP 壳);CMake + hvigor
上游版本chiaki-ng(持续跟随上游 main)
核心依赖Qt 6.12(qtbase / qtdeclarative / qtshadertools)、ffmpeg 7.1.1、SDL2 2.30、glslang、libplacebo;OHOS NDK(libohaudio / OH_AVCodec / GCK)
链接方式libchiaki.so 动态库;ffmpeg 静态链接(NEON,-Wl,-Bsymbolic)
产物HAP(约 17MB,含签名后的 libchiaki.so)
构建状态✅ 可连接 PS5 串流并运行游戏(视频硬解 60fps / 音频 OHAudio / DS5 手柄全键位)
移植周期2026-09 起持续迭代

2. 为什么是"Qt 装进 ArkUI",而不是重写?

2.1 不能重写的理由

chiaki-ng 的 UI 不是"一个界面",而是一整套完整的 Qt6/QML 应用:串流会话管理、手柄按键映射、设置页、自动发现 PS5、延迟/丢包监控面板……全部在 QML + C++ 里,总代码量以万行计。纯 ArkTS 重写 = 重写整个应用,而且上游还在持续更新,重写版本永远追不上。

2.2 混合架构:ArkUI 当壳,Qt 当内核

鸿蒙 PC 应用必须是 HAP(ArkUI 页面 + 可选 native 组件)。于是反过来想:ArkUI 只提供一页 XComponent,把整个 Qt 应用嵌进去。

┌─────────────────────────────────────────┐
│ ArkUI 页面(MainWindowNativeNode.ets)    │
│  ┌───────────────────────────────────┐  │
│  │ XComponent(libraryname='qohos')   │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │ Qt native 窗口(Vulkan)      │  │  │
│  │  │  QML 全部 UI(上游原样复用)    │  │  │
│  │  └─────────────────────────────┘  │  │
│  │  ┌─ 叠加按钮(Paste / 状态条)───┐  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
  • qohos 是 Qt 的 HarmonyOS 平台插件(类似 Qt 的 linuxfb/xcb 后端),在 XComponent 里创建 native 窗口;
  • Qt 渲染走 Vulkan:nativeResourceForWindow("vkSurface", window) 拿到 VkSurfaceKHR,配合 setVulkanInstance 起渲染;
  • 音视频/手柄全部走系统 NDK(OHAudio / OH_AVCodec / GCK),不进 ArkUI;
  • 两层 UI 的协作用"文件桥":Qt 侧把会话状态、剪贴板内容写到 $HOME/chiaki_*.txt,ArkUI 侧 300ms 轮询 + 叠加按钮回写——全程零权限申请(见 §4.4)。

这条路绕不开的三个难点:

难点坑
qohos 平台插件Qt 官方没有 OHOS 后端,qohos 是移植时自补的插件:EGL/Vulkan surface 创建、键码映射、剪贴板告警降噪都要单独处理
QML ↔ C++ 可见性Q_INVOKABLE 声明在 private: 段 QML 调用会静默 TypeError,必须放 public:;且 Qt 报错走 Qt category 而非 chiaki 自己的 tag,hilog -T chiakiohos 过滤会把它藏掉——排查时要按 domain 过滤
聚焦/叠加层协作ArkUI 的按钮叠在 Qt 窗口上,串流中要自动隐藏(!Chiaki.session 判定),否则挡视线/误触

3. 构建系统:四个连环坑

3.1 CMake 不认 HarmonyOS

CMAKE_SYSTEM_NAME 没有 HarmonyOS 这个值,只能用 ohos.toolchain.cmake + 一个平台补丁模块目录(CMAKE_MODULE_PATH)让 cmake 认识 OHOS——否则 FindXxx.cmake、库路径检测全会给出错误结果。这条与 Neovim 移植(同系列上一篇)踩的是同一个坑。

3.2 Qt 6.12 三件套补丁(30+ 文件)

组件补丁内容
qtbase27 个文件:CMake/configure 的 OHOS 平台判定、各模块 CMakeLists、qhash.cpp 的 ARM AES 内建守卫、3 个 qohos 插件文件(键码告警降噪/剪贴板降噪/EGL 句柄 nullptr→0)、src/corelib/private/ 下 8 个软链
qtdeclarativeqv4compilationunitmapper_unix.cpp + qv4functiontable_noop.cpp(无 JIT)+ OSAllocatorPosix.cpp
qtshadertools内置 glslang 的 OSDEPENDENT 路径归到 Unix

3.3 ffmpeg 静态链接 + 签名

  • ffmpeg 以静态库方式链进 libchiaki.so(含 NEON 汇编),必须 -Wl,-Bsymbolic,否则符号冲突;
  • 鸿蒙要求所有 ELF/.so 合法签名才能加载:llvm-objcopy --remove-section=.codesign 剥掉旧段 → binary-sign-tool sign -selfSign 1(注意 outFile 必须预先存在);
  • hvigor 打包 HAP 时会剥掉 .so 的签名且不重新签名——所以签名必须在进 HAP 之前独立完成,这个坑不写下来没人知道。

3.4 部署

devecocli run --module entry@default --device "HUAWEI MateBook Pro" --build-mode debug
hdc shell "aa force-stop org.streetpea.chiaking; aa start -a QAbility -b org.streetpea.chiaking"

4. 系统能力接入

4.1 音频:SDL 无 OHOS 后端 → OHAudio(系统 Audio Kit)

  • 现象:SDL_Init(SDL_INIT_AUDIO) / SDL_OpenAudioDevice 在 OHOS 上必然失败——SDK 的 SDL 2.30 没有 OHOS 音频后端,沙箱里也没有 ALSA/dsp 节点;
  • 修复:gui/src/ohosaudioout.cpp 用 OH_AudioRenderer(libohaudio.so)实现 SDL 队列式音频 API 的输出半边(Open/Close/Pause/Queue/QueuedBytes/ClearQueue/GetStats),在 streamsession.cpp 用宏把 SDL_OpenAudioDevice/QueueAudio/... 重定向过去;AUDIOSTREAM_USAGE_GAME、S16LE、48kHz;
  • 低延迟快路径:默认走 fast mode(OH_AudioRenderer_GetFastStatus 判定),回调粒度 5ms、设备延迟 25ms;CHIAKI_OHOS_AUDIO_LATENCY=normal 可切回普通路径(回调 93ms、延迟 45–93ms);
  • 实测稳态 [ohos-audio] under 计数平(无欠载),总延迟 ≈ 2×设置里的 Audio Buffer Size + 25ms。

4.2 视频:OH_AVCodec 硬件解码

  • 软件解码 CPU 86.6%、端到端延迟 60–280ms → lib/src/ffmpegdecoder.c 增加 OHOS 硬解路径(NV12 拷贝/队列/墙钟 pts/统计日志):CPU 降到 50%、稳定 60fps、延迟 20–80ms。

4.3 手柄:系统键码桥 + GCK + 右摇杆条件器

  • R1/PS 盲区键:系统 key event 经 qohos 转成 QKeyEvent(nativeVirtualKey() 保留原始键码)到达 Qt 层,C++ 侧拦截后合成 SDL 事件——不必重编 qohos 也能补全键位;
  • GCK 桥:OhosGamepadBridge 对接系统手柄服务;顺手修了 ControllerManager::IsConnected()(OHOS 上无手柄对象时误判断开→游戏内无输入);
  • 右摇杆手感:内置条件器(死区 + 双指数平滑 + 中心校准,参数可热调),逐秒 [ohos-rstick] 日志量化:原始事件 1–16ms 间隔、rest≈0.488(不是 0.5)、修复前冷启动满杆放大 vs 修复后 slow-sweep max_step 0.005–0.03。

4.4 剪贴板:免权限文件桥 + ArkUI 叠加按钮

  • ohos.permission.READ_PASTEBOARD 是受限权限,自签名安装会失败 → 不做原生读剪贴板;
  • 改为:Qt 侧写 $HOME/chiaki_clipboard.txt,ArkUI 页面叠一个「Paste」按钮读取回填输入框;按钮只在非主屏页面显示、串流中自动隐藏(setPasteOverlayWanted + 300ms 轮询),位置避开返回键。

5. 平台深度适配

项做法
分层图标make-icon.py 从仓库素材派生 foreground.png(透明)+ background.png(不透明)+ layered_image.json;AppScope 资源与模块资源同名时 AppScope 生效
启动动画API 19+ startWindow 增强配置:startWindowIllustration(白字 logo,宽 26.6% 居中)+ startWindowBackgroundImage(Cover)+ 背景色;注意 AppIcon 与 Illustration 互斥(图标优先),startWindowBrandingImage 渲染尺寸只有窗口 12.2% 宽(太小,弃用)
串流监控面板[ohos-net](逐秒丢包/丢帧)、[ohos-fps](presented/dropped/队列年龄)、[ohos-render](每帧各阶段耗时)、[ohos-dec](解码帧率/漂移)——所有延迟问题都能从日志直接读数

6. 网络问题的工程排查(最花时间、也最值得讲)

6.1 现象与手法

串流时画面/声音周期性顿挫,但应用自报 packet_loss=0。我们把三条证据线对齐到同一时钟:

  1. hilog(app/core):Wi-Fi 子系统每 18.0 秒出现一次固定序列;
  2. 内核 kmsg(hilog -w start -t kmsg 开):驱动层同一时刻的动作;
  3. 逐包 ping(ping -i 0.2 网关)+ 应用自报的逐秒丢帧统计。

6.2 根因:Wifi2 增强反复重连主接口

T+0.0s  WifiEnhanceInfoRequestor: RequestWifi2Network wifi2 is not active, SetWifi2Enable
T+0.1s  HalDeviceManager: CreateStaIface wlan1   ← 建第二条链路
T+1.8s  [kmsg] vap:0 wal_cfg80211_connect::start a new connect   ← 主口被重连!
T+2.0s  ping 尖峰 115–305ms(ICMP 0% 丢包)
T+7.5s  WifiServiceScheduler: AutoStopWifi2Service 1 success!
T+18.0s 下一轮
  • 触发链是华为"Wifi2/MultiSta 增强"(MultiStaStateMachine → GetChbaGroupInfo freq=5220 bw=3 clientNum=1),每次尝试都会顺手把主 Wi-Fi 接口(wlan0/vap:0)重连一次;
  • 驱动层 25 次主口重连中 23 次(92%)在 ±3s 内命中 ping 尖峰,尖峰簇间隔中位数 18.0s;
  • 现象是间歇性的:活动期 3.5–7 分钟(每 18.0s 一轮)↔ 静默期 22–27 分钟——这正是"有时卡有时不卡"的原因。

6.3 另一个坑:声音卡顿 ≠ 网络丢包

一次"声音卡顿"投诉,用对照实验定位:同 PC、同 Wi-Fi,唯一变量是 PS5 的接入方式——

PS5 接入音频欠载率
Wi-Fi100%(callbacks=4961 underruns=4961,每回调必欠载;视频却 60fps/0 丢包)
切有线瞬间会话短暂断开(arkui stream state -> 0),ping 单次 146ms 尖峰
有线0.07%(under=17 后 5 分钟不再增长)

结论:这次声音卡顿的根源在 PS5 与路由器的 Wi-Fi 链路,和 PC 的 Wifi2 churn 是两个独立问题。方法论上的收获:排查串流卡顿要抓"时延尖峰"而不是只抓丢包——ICMP 0% 丢包 + 100–300ms 排队尖峰就足以让 60fps 串流可见顿挫。


7. 已知问题与后续

问题症状方案/状态
PC 侧 18s Wi-Fi 顿挫每 ~18s 一次时延尖峰(主口被 Wifi2 增强重连)已按华为要求提供全量 hilog + kmsg 取证包(含 hilog_dict);临时缓解:PC/PS5 尽量有线、关闭多设备协同/智能选网
声音卡顿音频 100% 欠载PS5 改有线(实测 100%→0.07%)
HAP 内 .so 失效hvigor 剥签名binary-sign-tool 独立签名后再进 HAP
第三方依赖补丁不在 git换机器即丢已全部收集到依赖目录 patches/(qtbase/qtdeclarative/qtshadertools/glslang/sdl2/libplacebo),README 记录逐文件说明

后续方向:向上游提 PR(qohos 平台插件、OHAudio 输出、OH_AVCodec 硬解均条件编译隔离,不影响其它平台)、继续压低端到端延迟、适配更多鸿蒙 PC 机型。


本文首发于【鸿蒙PC】系列专栏
最后更新:2026-09-25
文章版本:v1.0

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐