Open Voice Bridge · 开放语音桥

Open Voice Bridge 是一个面向无线麦克风、语音遥控器和其他语音/按键外设的跨设备、跨传输、跨平台桥接框架。

它把问题拆成六层：设备身份与能力、传输、设备协议、音频图、动作映射和平台后端。一个设备可以组合 BLE GATT、Bluetooth HID、USB 数字音频或系统音频输入；macOS、Windows、Linux 分别实现自己的权限与 I/O 后端。

当前已完成实现和真机验收的组合是：Xiaomi Bluetooth Remote 2 Pro / RC003 + macOS，以及小米蓝牙语音遥控器普通款 / ARN9 + macOS（单设备）。RC003 Windows 是源码/构建候选：已经在真实 Windows GitHub Actions runner 上通过完整测试与打包流程（未真机验收，见 apps/windows/rc003/），不应理解为已经支持。DJI Mic 2 的双平台系统输入识别正在开发和真机验收中；Linux 仍为 planned/research。

当前支持矩阵

DJI 官方说明 Mic 2 接收器可以通过 USB-C 连接电脑；其发射器直接蓝牙兼容列表主要包含指定 DJI 设备与手机。因此本项目不会因为设备“支持蓝牙”就把它假设为桌面通用蓝牙麦克风。相关资料见 DJI Mic 2 Specs 和 DJI Mic 2 FAQ。

macOS 会读取蓝牙 Device Information Service 的 Model Number（0x2A24）：RC003 对应 2 Pro，ARN9 对应普通款。设置窗口只展示当前实际识别到的设备；完整适配范围单独放在“支持设备”页。2 Pro 与 ARN9 因名称和协议相同而复用同一个小米适配器，但各自使用真实外观和按键集合：

• 选 RC003：显示 BLE/HID/ATVV 桥接、BlackHole 语音输出、双击开关、Mac Fn 兼容和 13 键映射。
• 选 ARN9 普通款：显示相同的 BLE/HID/ATVV 语音链路，以及没有 TV 键的普通款实物图和 12 个实体功能区（包括语音键在内均可映射）。
• 选 DJI Mic 2：只显示 macOS 系统录音输入检测、声音输入设置入口和 DJI 实体控制边界；不启动 RC003 桥接，不显示 BlackHole 和 13 键映射。

框架入口

• 总体架构
• 添加新设备适配器
• 设备 profile Schema
• 已实现的 Xiaomi RC003 profile
• Xiaomi RC003 Windows 源码/构建候选（未真机验收）
• DJI Mic 2 开发中 profile

Profile 只记录可核对的事实与状态，不是驱动。只有代码、自动验证和目标平台真机门都通过后，某个设备/平台组合才会标为 implemented。

第一个适配器：Xiaomi RC003 for macOS

现有 XiaomiRemoteBridgeMac target、应用显示名和 Bundle ID 暂时保留，避免总项目改名导致已安装用户重新授予蓝牙、输入监控和辅助功能权限。当前版本为 v0.4.0，包含 Mac 物理 Fn 麦克风兼容、真正鼠标右键、语音键双击暂停/恢复、所有实体键的自定义快捷键录制、Developer ID 正式签名与 Apple 公证发行链，以及基于 Sparkle 2 的应用内更新。更新包同时使用 EdDSA 与 Developer ID 校验；发现新版本后由用户确认安装，不静默安装，也不发送系统画像。

当前功能：

• 精确发现、连接和重连 RC003；
• Android TV Voice-over-BLE（ATVV）能力协商与 16 kHz IMA/DVI ADPCM 解码；
• 把语音写入用户选择的 CoreAudio 输出，配合 BlackHole 等回环设备作为虚拟麦克风；
• 在“设置 → 连接 → 语音链路诊断”中显示遥控器 PCM、应用向所选输出设备的排队电平，以及播放器回执状态；三项只描述本应用可观察的边界，不会伪装成“输入法已收到”或“文字已提交”；
• 仅对 RC003 把真实 F5 硬件按下/松开映射为 Mac Fn/🌐︎，退出时恢复原映射；
• IOHID 原始按键读取，以及方向、确定、返回、主页、菜单、TV、音量等动作映射；
• 可选“兼容 Mac 键盘 Fn”：按住 Mac 内置键盘物理 Fn 时把本机麦克风转发到同一语音输出，RC003 语音始终优先；新安装默认开启，仍然只在按住时采集、松手即停；
• 快速双击 RC003 语音键即可停用/恢复整个桥接（停用后遥控器不再向 Mac 注入按键、Fn/🌐︎、语音或音频），也可在设置或菜单栏用显式按钮切换；长按语音不受影响、无额外延迟，运行时状态不持久化，重开应用自动恢复为“已启用”；
• 保持原比例的 RC003 实物图与图形化映射设置。

日常使用速查

双击麦克风键只是暂停/恢复本应用桥接，不会关闭遥控器实体电源、不会断开蓝牙，也不会取消配对。单击、正常长按和慢速双击不会切换状态。若误触暂停，可再次双击、使用显式“启用桥接”按钮，或退出并重开应用。

应用同时提供菜单栏和 Dock 入口。菜单栏可用空间不足时，macOS 可能暂时不显示部分第三方图标，应用无法改变系统排序；点击 Dock 中的 Open Voice Bridge 图标即可重新显示设置窗口。

“登录时自动启动”默认开启，可在“设置 → 连接 → 应用”中关闭。macOS 13 及以上若显示“需在系统登录项中允许”，点击界面里的按钮后，在“系统设置 → 通用 → 登录项与扩展”中允许本应用。

图形化按键映射界面

_{完整“按键”设置界面：点击左侧实物按键，右侧会定位到对应动作。截图中的权限状态以当前 Mac 实际授权结果为准。}

打开菜单栏中的应用图标，选择“打开设置… → 按键”，即可使用图形化映射：

1. 打开“启用 RC003 自定义按键映射”；
2. 点击左侧实物图上的按键，右侧会自动定位到对应映射；
3. 从动作菜单中选择新动作，修改后自动保存；
4. 需要撤销所有自定义设置时，点击“恢复默认”。

每个真实实体键都可以选择内置动作、禁用，或点击“录制自定义快捷键…”直接录入单键/组合键。麦克风键默认仍用于 RC003 语音 + Mac Fn/🌐︎ 长按；也可改成自定义的按住型宿主快捷键，应用会恢复设备 F5→Fn 映射并从原始 HID 按下/松开边沿注入该组合键，避免双发。遥控器没有独立静音实体键；“系统静音”只是可分配给其他实体键的可选动作，不是默认映射。

ARN9 普通款使用同一语音/Fn 行为和同一套默认动作，但映射页会切换为黑色普通款实物图并隐藏不存在的 TV 键。它的真实单设备测试已确认两次完整的“按下 → ATVV 流启动 → 松开 → ATVV 流停止”。由于 2 Pro 与 ARN9 向 macOS 暴露相同名称、VID/PID 和固件号，当前不要同时连接两只同名小米遥控器；现版本还不能可靠保证 HID 与 BLE 选中同一个物理实例，双设备选择将在后续实例身份切片处理。

默认映射如下：

动作菜单里三个容易混淆的选项区别如下：

• 上下文菜单（Shift-F10）：发送键盘 Shift-F10，请求当前聚焦控件在其自身位置弹出上下文菜单，不移动也不使用鼠标；部分应用不响应该快捷键。
• 切换应用（Command-Tab）：发送 Command-Tab，打开系统的应用切换器，用于在已打开的应用之间切换，与右键无关。
• 鼠标右键（当前位置）：在鼠标指针当前所在位置触发一次真正的系统右键单击（右键按下 + 松开），等同于用鼠标右击，可在任意位置调出右键菜单。

若希望菜单键直接充当鼠标右键，打开“打开设置… → 按键”，点击左侧实物图的“菜单”键，在右侧动作下拉框中选择“鼠标右键（当前位置）”即可（修改后自动保存）。默认值仍为“上下文菜单（Shift-F10）”，升级不会自动改变已有习惯。

下载安装与首次配置

1. 准备条件

• macOS 11 Big Sur 或以上；
• Apple Silicon 或 Intel Mac；
• 小米蓝牙遥控器 2 Pro / RC003，或普通款 / ARN9；
• 使用遥控器语音时，安装 BlackHole 2ch 或等价的 CoreAudio 回环设备。

应用不会自动安装音频驱动，也不会修改系统默认输入/输出设备。

2. 下载并安装应用

1. 从项目 Releases 下载最新的 macOS DMG；
2. 打开 DMG，把“小米遥控器桥接.app”拖到旁边的 Applications；
3. 进入“应用程序”，按住 Control 单击“小米遥控器桥接”，选择“打开”；
4. 如果系统仍然拦截：
   • macOS 13 或以上：进入“系统设置 → 隐私与安全性”，在安全性提示处选择“仍要打开”；
   • macOS 11/12：进入“系统偏好设置 → 安全性与隐私 → 通用”，选择“仍要打开”。

v0.3.7 起的 macOS 正式包使用 Apple Developer ID Application 同时签署 App 本体和 DMG 容器，启用 hardened runtime、安全时间戳并装订 Apple 公证 ticket。v0.3.6 及更早公开测试包仍是 ad-hoc/未公证历史产物。只应从本项目 Release 或你信任的分享者处取安装包。维护者的本地开发构建仍可使用 Open Voice Bridge Local Code Signing 持久本机身份或 ad-hoc 回退；只有显式 --release-sign 构建并通过公证验证的 DMG 才是正式发行包。

v0.4.0 是首个带应用内更新的版本。由于 v0.3.9 及更早版本没有更新器，需要手动安装 v0.4.0 一次；以后可从菜单栏“检查更新…”或“设置 → 连接 → 应用”检查。默认每天最多自动检查一次，发现更新会显示版本和说明并等待确认，不会静默安装。可随时关闭“自动检查更新”；更新检查不上传语音、设备信息或系统画像。

3. 让遥控器进入配对状态

1. 打开 Mac 的蓝牙设置；
2. 同时长按遥控器的 主页键 + 菜单键，让遥控器进入配对广播状态；
3. 在 Mac 上连接并允许名称为“小米蓝牙语音遥控器”、“MI RC”或“Xiaomi Bluetooth Remote 2 Pro”的设备；
4. 打开应用菜单栏图标；如果没有自动连接，选择“立即重新连接”。

4. 授予按键映射权限

蓝牙权限用于连接 RC003 和读取语音；自定义按键还需要“输入监控”和“辅助功能”。在应用“打开设置… → 权限”中依次点击对应的“请求权限”：

• macOS 13 或以上：“系统设置 → 隐私与安全性 → 输入监控 / 辅助功能”；
• macOS 11/12：“系统偏好设置 → 安全性与隐私 → 隐私 → 输入监控 / 辅助功能”。

在两个列表中都打开“小米遥控器桥接”。如果列表里没有应用，先回到应用的“权限”页面重新点击“请求权限”，或使用列表下方的 + 手动加入 /Applications/小米遥控器桥接.app。完成后从菜单栏选择“退出”，再从“应用程序”重新打开一次。

首次从 ad-hoc/本机测试包升级到 Developer ID 正式包时，权限开关可能看似开启但新版本仍显示无权限。 这是 macOS 仍保留旧签名身份的 TCC 记录造成的。若关闭、删除再重新添加仍无效，请完全退出应用，在“终端”依次运行 tccutil reset ListenEvent com.kingwell.XiaomiRemoteBridgeMac、tccutil reset Accessibility com.kingwell.XiaomiRemoteBridgeMac 和 tccutil reset Microphone com.kingwell.XiaomiRemoteBridgeMac，再重新打开应用并按“权限”页提示逐项授权。这些命令只清除本应用对应权限，不会修改其他应用。v0.3.9 已修复正式签名包漏签音频输入能力的问题；从正式包开始，后续版本保持同一 Developer ID 身份，不再因 ad-hoc 哈希变化而每次换身份。

5. 配置 BlackHole 语音链路

1. 安装 BlackHole 2ch；
2. 打开“设置 → 连接”，在“虚拟麦克风 → 语音输出”中选择 BlackHole 2ch；
3. 可先点击“发送 1 秒测试音”，确认本应用播放器能够完成向所选输出设备的播放；
4. 在豆包输入法、微信输入法或其他目标语音应用中，把麦克风也选择为同一个 BlackHole 2ch；
5. 先单击目标输入框，确认文字光标已经出现；
6. 按住遥控器麦克风键说话，松开后应用会释放 Fn 并结束语音流。

6. 验证按键与语音

• 方向、OK、返回、主页、菜单、TV、音量 +/− 应按上表执行；
• 打开“设置 → 按键”可以点击实物图并逐键修改；
• 长按麦克风键时开始语音，松开后应立即结束；
• 按键无映射反应时，先确认“输入监控”和“辅助功能”均已打开，并完全退出后重新启动应用。

7. 让 Mac 物理 Fn 也能用本机麦克风（新安装默认开启）

RC003 的语音是通过 ATVV 把遥控器麦克风写入 BlackHole 的；而 Mac 内置键盘的物理 Fn 只负责触发输入法的语音界面，本机麦克风的声音走的是系统默认输入，并不会进入 BlackHole。因此当豆包等输入法把麦克风固定为 BlackHole 2ch 时，只按物理 Fn 会出现语音界面却收不到文字——这与桥接是否在线无关。

如果你希望按住 Mac 物理 Fn 时也用本机麦克风说话，可以打开这个可选开关：

1. 打开“设置 → 权限”，在“麦克风（本机 Fn 兼容）”处点击“请求权限”，并在系统弹窗中允许麦克风访问；
2. 打开“设置 → 连接 → 兼容 Mac 键盘 Fn”，开启“按住物理 Fn 时使用本机麦克风”；
3. “本机输入源”保持“系统默认输入”（通常就是 MacBook 内置麦克风），也可以指定其他输入设备；不要选择与上方“语音输出”相同的设备，否则会形成回声环并被自动停用；
4. 现在按住 Mac 内置键盘的物理 Fn 说话，应用会把本机麦克风转发到所选的语音输出（如 BlackHole 2ch）；松开 Fn 立即停止。

行为与边界：

• 新安装默认勾选，已明确关闭的用户在升级后仍保持关闭。勾选本身不会开始采集，只有系统已授权且用户按住物理 Fn 时才会打开麦克风，松手即停。
• RC003 语音始终优先：遥控器一旦开始说话，本机麦克风立即停止，并保持停止直到你松开物理 Fn；遥控器结束后不会因为你还按着 Fn 就重新打开本机麦克风。
• 只在“已开启 + 已授权 + 按住物理 Fn + RC003 未说话”时采集；松手、遥控器开始、退出应用、设备消失或撤销权限都会立即停止。
• 监听物理 Fn 复用与 RC003 按键映射相同的“输入监控”授权。缺少麦克风或输入监控权限、未选择输出设备、输入与输出为同一设备时都会失败关闭，不影响遥控器语音和普通按键。
• 不录音、不落盘、不上传；不修改系统默认输入/输出，也不会安装或改动 BlackHole。

8. 用双击语音键停用 / 恢复桥接（默认开启）

有时你希望暂时让 RC003 完全“安静”——不再向 Mac 注入任何按键、Fn/🌐︎、语音或音频，但又不想拔电池、取消蓝牙配对或退出应用。为此可以快速双击遥控器的语音（麦克风）键在“桥接已启用 / 桥接已停用”之间切换。

• 手势：两次完整的短按（每次 按下 → 松开）。默认双击窗口 350ms（两次“按下”之间），单次短按最长 250ms。第二次松开的瞬间切换一次。
• 不会误触：单击、长按（按住说话）、慢速双击、重复按下、缺失松开都不会切换；长按语音仍然“按住即说、松手即停”，不会因为要等待第二次点击而增加任何延迟。
• 停用后：RC003 不再向 Mac 注入普通按键、连发、Fn/🌐︎、语音打开或音频；已在进行的语音、硬件 Fn、远端仲裁与音频队列会立即清理，并恢复 F5 的系统按键映射。蓝牙连接保持在线，方便随时恢复。
• 恢复：再次快速双击，或在“设置 → 连接 → 桥接开关”或菜单栏点“启用桥接”。显式按钮不依赖双击，便于无障碍或权限异常时恢复。
• 运行时、不持久化：停用状态只在本次运行有效。退出并重新打开应用会自动恢复为“桥接已启用”，避免忘记关过而误以为设备坏了。
• 原生按键降级边界（如实提示）：只有在开启“自定义按键映射”且系统允许独占读取 RC003 时，停用才能完整拦截遥控器的普通按键。如果你关闭了自定义映射，或系统不允许独占，遥控器的普通按键会走 macOS 原生行为；此时状态会明确显示“应用桥接已关闭，但 macOS 原生按键行为可能仍存在”，不会谎称完整拦截。语音键部分（F5→Fn 与 ATVV 语音）在任一情况下都会被完整停用。
• 不触碰实体电源与配对：“停用桥接”只表示本应用停止桥接 RC003，不会关闭遥控器电源，也不会取消蓝牙配对。
• 双击开关默认开启，可在“设置 → 连接 → 桥接开关”关闭（关闭后仍可用显式按钮切换）。它也不影响上面的“兼容 Mac 键盘 Fn”能力——物理 Fn 的行为不随这个遥控器开关改变。

常见问题

• 应用打不开：使用 Control 单击“打开”；仍被拦截时，到对应系统版本的“安全性”页面选择“仍要打开”。
• 权限列表里没有应用：先在应用“权限”页面点击“请求权限”；仍未出现时，用权限列表下方的 + 加入 /Applications/小米遥控器桥接.app，然后完全退出并重新打开。
• 权限开关已经打开，应用仍提示未授权：先确认已覆盖安装 v0.3.9 或更高版本并完全退出应用。然后在“终端”仅重置本应用的三项旧签名记录：tccutil reset ListenEvent com.kingwell.XiaomiRemoteBridgeMac、tccutil reset Accessibility com.kingwell.XiaomiRemoteBridgeMac、tccutil reset Microphone com.kingwell.XiaomiRemoteBridgeMac。重新打开后到应用“权限”页逐项点击请求；麦克风重置后会暂时从系统列表消失，应用重新发起请求并获准后才会再次出现。
• 遥控器按键有效但语音没有声音：确认应用“语音输出”和目标输入法“麦克风”都选择了同一个 BlackHole 2ch，不要只选择 MacBook 自带麦克风。
• 诊断里的 PCM 与输出电平均跳动，但仍没有文字：这说明遥控器音频已到本应用，且应用已向所选设备提交；“播放节点已完成到输出节点”也只说明本应用播放器完成。虚拟声卡的录音端是否被豆包、微信等第三方输入法选中、读取和提交文字，macOS 没有提供回执，界面会明确显示“状态未知”。
• 豆包只显示绿色文字预览、只能复制：先确认输入法已经取得当前可编辑输入框——松开按键、重新单击输入框确认光标已出现后再试。
• 只按 Mac 物理 Fn 时豆包出现语音界面却没有文字：当豆包把麦克风固定为 BlackHole 2ch 时，物理 Fn 只负责打开豆包的语音界面，而 Mac 本机麦克风的声音走的是系统默认输入，并没有进入 BlackHole，所以 BlackHole 上没有音频。这并不代表遥控器或桥接断线，也不是“实体 Fn 只能复制”。需要在这种场景下用本机麦克风说话时，打开可选的“兼容 Mac 键盘 Fn”（见下方第 7 步）。
• 重复触发或完全没有自定义动作：确认两项按键权限均已授权；应用会优先独占 RC003，不能独占时才使用兼容监听，不需要安装 Karabiner。
• 不小心把遥控器“关掉了”：你可能快速双击了语音键触发了“桥接已停用”。再次快速双击，或在“设置 → 连接 → 桥接开关 / 菜单栏”点“启用桥接”即可恢复；退出并重开应用也会自动恢复为“已启用”。识别双击需要“输入监控”权限；若尚未授权，请用显式按钮切换。

开发者构建与验证

维护约定：每个新的 macOS 版本候选在完成自动测试和独立代码审查后，必须先把同一份正式签名、公证产物覆盖安装到维护者本机，完成版本、权限、空闲 CPU、真实遥控器按键与语音验收；本机验收通过并完成发布物独立复审后，才允许推送 GitHub Release。中途的排障或问答不会跳过或中止这条发布链。

./scripts/test.sh
./scripts/build-app.sh --universal
./scripts/verify-app.sh --universal

生成带应用、安装说明、许可证和对应源码的测试 DMG：

./scripts/build-dmg.sh
./scripts/verify-dmg.sh

维护者的正式签名与公证流程：

./scripts/store-notary-credentials.sh "OpenVoiceBridge Notary"
OVB_CODESIGN_IDENTITY='Developer ID Application: <name> (<team-id>)' \
  ./scripts/build-app.sh --universal --release-sign
./scripts/notarize-update-app.sh \
  --keychain-profile "OpenVoiceBridge Notary"
OVB_CODESIGN_IDENTITY='Developer ID Application: <name> (<team-id>)' \
  ./scripts/build-dmg.sh --release-sign --use-existing-app
./scripts/notarize-dmg.sh \
  --keychain-profile "OpenVoiceBridge Notary" \
  "dist/小米遥控器桥接-<version>.dmg"

store-notary-credentials.sh 会交互式请求 Apple Account、Team ID 和 App 专用密码；密码只进入 macOS 钥匙串，不应写进脚本、环境变量、命令历史或仓库。

Sparkle 的私有 EdDSA 更新密钥同样只保存在维护者登录钥匙串中，仓库只保存公开验证密钥。prepare-sparkle-tools.sh 只下载官方 2.9.2 工具包并验证固定 SHA-256；notarize-update-app.sh 在应用公证后生成更新 ZIP 和签名 appcast。修改已签名的 ZIP、发布说明或 appcast 后必须重新生成，不能手工补签。

当前 macOS 11 部署目标已完成双架构编译与打包校验，但尚未在真实 macOS 11 机器上运行验收。

安全与隐私

• 不上传语音，不保存语音文件；PCM 只在内存与用户选定的音频设备之间流动。
• 语音链路诊断只保留电平、帧/段计数和回执时间等内存元数据，不保存任何 PCM、语音内容或输入法内容。
• “兼容 Mac 键盘 Fn”在新安装中默认开启；仅在系统已授权、按住物理 Fn 且 RC003 未说话时采集本机麦克风，松手即停，不录音、不上传，并在输入与输出为同一设备时失败关闭以避免回声环。
• 不自动修改系统默认输入/输出。
• 双击停用/恢复桥接只切换本应用的运行时状态，不关闭遥控器电源、不取消蓝牙配对；运行时状态不落盘。日志不记录音频内容、设备 UID、输入内容或用户路径；会记录连接/状态/失败类别，以及已匹配蓝牙设备提供的显示名，便于本机排障。
• 不保存真实蓝牙地址；日志不记录语音内容或外设 UUID。
• 权限不足、身份不匹配或协议不满足时失败关闭。
• 新设备和新平台必须分别通过自己的权限、断线、音频和真机验收。

来源与许可

第一个 Xiaomi RC003 适配器的 ATVV UUID、握手、HID usage 与 IMA/DVI ADPCM 行为参考 GPL-3.0 项目 xxb26553663-star/remote-bridge-hub，参考 revision 8a93f321ac71a602300c6cd77f7256fa4b63068e。

本项目代码统一按 GPL-3.0-only 发布。参考项目的品牌与商业资产不包含在本项目中；RC003 图片和 Xiaomi 商标也不因代码许可证获得额外授权。修改与归属说明见 COPYRIGHT 和 THIRD_PARTY_NOTICES.md。