jmScrcpy Audio Capture

鸿蒙（HarmonyOS NEXT）系统内录音频采集服务：基于华为官方 Media Kit（@ohos.multimedia.media，HarmonyOS 多媒体服务）的 OH_AVScreenCapture C API（innerCapInfo 内录音源）采集手机系统播放的音频（PCM），经 TCP 推流到电脑端。

本组件是「建木手机投屏」（jmScrcpy，鸿蒙远程真机投屏工具）的手机端配套组件。桌面端投屏时，通过 hdc 自动安装本服务到手机并拉起，实现"手机声音同步到电脑播放"。

特性

• 系统内录：OH_AVScreenCapture + innerCapInfo（OH_ALL_PLAYBACK），采集系统所有播放声音（不含麦克风）
• PCM 推流：TCP 客户端连 127.0.0.1:9960（设备端 rport 反向转发到电脑），16B 元数据 + 帧长 + PCM 帧协议
• 无感驻留：采集模式加载服务页后 moveAbilityToBackground() 退后台，AUDIO_RECORDING 长时任务保活
• 单 Ability 双模式：桌面图标 → 服务信息页；--pb start true → 采集模式；--pi restoreVolume n → 恢复音量后自杀
• 静音/恢复：授权后自动静音（系统音量 API），结束投屏自动恢复原音量
• 多语言：电脑端下发语言码（0=zh_CN 1=en_US 2=ja_JP 3=ko_KR），服务页文案跟随
• 断线重连：TCP 断开 500ms 自动重连

架构

电脑端（jmScrcpy）                    手机端（本 HAP）
┌──────────────────┐   hdc rport    ┌──────────────────────────┐
│ AudioSyncService │◄── 127.0.0.1:9960 │ libentry.so（C++）        │
│ 接收 PCM 播放     │   反向转发      │  OH_AVScreenCapture 内录   │
└──────────────────┘                │  → TCP 客户端推流          │
                                    │  EntryAbility（ArkTS）      │
                                    │  生命周期/静音/窗口管理     │
                                    └──────────────────────────┘

• entry/src/main/cpp/audio_capture.cpp：AVScreenCapture 采集 + TCP 推流（native 层）
• entry/src/main/ets/entryability/EntryAbility.ets：Ability 生命周期、窗口处理、静音/恢复、长时任务
• entry/src/main/ets/pages/Index.ets：服务信息页（四语言）

协议（9960）

1. 连接建立后，手机端先发 16 字节元数据（全部小端 u32）：
   • [0:4] 魔数校验
   • [4:8] 采样率 sampleRate
   • [8:12] 声道数 channelCount
   • [12:16] 位深 bitDepth
2. 之后按帧传输 PCM：每帧 = [长度 u32le][PCM 数据]
3. 电脑端收到元数据后，可选下发 1 字节语言码（0=zh_CN 1=en_US 2=ja_JP 3=ko_KR，供服务页文案跟随电脑端语言；旧版 HAP 忽略该字节，双向兼容）

构建

./build-hap.sh          # 需要 DevEco Studio 工具链（hvigor + SDK + Node）
./build-hap.sh clean    # 清理后重建

产物：entry/build/default/outputs/default/entry-default-unsigned.hap

签名：HAP 必须签名才能安装到消费者版设备。本仓库不包含任何签名材料：

• 需自备华为开发者/企业证书（.p12 + .cer + Profile .p7b）
• 在 build-profile.json5 的 signingConfigs 中配置（DevEco Studio 的 Signing Configs 可生成）
• 包名 com.hokit_jm.capture 已被原项目注册使用，自行发布时请更换 bundleName

已知限制（华为官方文档/真机实证，2026-08）

• 每次采集都会弹系统录屏授权窗（普通签名应用无豁免；EXEMPT_CAPTURE_SCREEN_AUTHORIZE 是 system 级特权权限）
• 状态栏录屏胶囊不可隐藏（系统管控）；来电自动停止；隐私场景（输密码）暂停
• 应用打开/关闭动画不可隐藏（手机上无华为官方 API）：moveWindowTo 对非自由窗口主窗口无效、moveWindowToGlobal 非 FLOATING 报 1300010、setWindowTransitionAnimation 手机报 801；透明启动窗口仅保证动画期间内容不泄漏

踩坑记录（真机验证）

• 窗口无感方案演进：白屏 → 透明页 → minimize（切走用户页面）→ terminateSelf（进程被杀音频断）→ 最终 moveAbilityToBackground()（退后台 + 长时任务保活）
• 任务快照：退后台瞬间系统拍快照，窗口未渲染内容则卡片为"白底+图标"占位、点开全白屏——须先 loadContent 服务页并延时 1.2s 等渲染完成再退后台
• 单 Ability 双模式：双 UIAbility 会产生两个任务卡片（excludeFromMissions 仅系统应用生效），合并为单 Ability 靠启动参数区分模式
• 恢复模式：电脑端 stop() 先 aa start --pi restoreVolume（实例存活走 onNewWant 复用窗口，无打开动画），恢复音量后自杀（removeMissionAfterTerminate 清理任务卡片）；不再先 force-stop（会迫使新开窗口播放动画）

许可

Business Source License 1.1（BSL 1.1），详见 LICENSE。

• ✅ 免费：研究、学习、教学、个人非商业使用、组织内部非商业测试
• 💰 商用付费：将本组件或其衍生作品集成到商业产品/服务、销售、收费分发——须事先获得书面商业许可
• ⏳ 转开源：每个发布版本从该版本首次公开发布之日起满 5 年，自动转为 Apache License 2.0（统一规则，适用于所有版本；）

商业许可请联系：choger@qq.com

本组件是「建木手机投屏」（jmScrcpy）的配套组件，完整投屏方案（视频流、反控、控件树、音频同步、授权）见官网 https://touping.obeiip.com。