Juanipis/motobuds
GitHub: Juanipis/motobuds
通过逆向工程实现的 Motorola Moto Buds macOS 原生伴侣应用，附带完整的蓝牙协议文档和设备发现工具。
Stars: 0 | Forks: 0
# MotoBuds for Mac
**Motorola Moto Buds** (XT2443-1 "guitar" 及相关型号) 的原生 macOS 伴侣应用。可切换 ANC 模式、读取电量、监测入耳/入仓状态，以及运行查找耳机——官方 Android 应用能做的所有事情，都能在你的 Mac 上完成。
## 功能特性
- **ANC 模式** — 关闭、通透、ANC (高)、自适应 (轻度 ANC)。通过与耳机自带触摸按键相同的线缆格式进行发送。
- **电池电量** — 左、右、充电仓，全部实时显示并提供通知。
- **入耳 / 入仓检测** — 在 UI 中实时可见。
- **查找耳机** — 让左或右耳机播放铃声。
- **双连接切换** — 允许耳机同时保持与两个主机的连接。
- **高解析度模式、游戏模式、音量增强开关** — 全部支持读取和写入。
- **菜单栏快捷控制** — 无需打开窗口即可查看电量并选择 ANC 模式。
## 安装说明
### Homebrew (推荐)
```
brew tap juanipis/tap
brew install --cask motobuds
```
### 手动安装
从 [Releases](https://github.com/Juanipis/motobuds/releases) 页面下载最新的 `MotoBuds-x.y.z.zip`，解压缩后，将 `MotoBuds.app` 拖入 `/Applications`。首次启动时会请求蓝牙权限 — 接受即可开始使用。
## 系统要求
- macOS 14+ (Sonoma)。
- Apple Silicon 或 Intel。
- 一副**已经配对**到你的 Mac 的 Moto Buds 耳机（通过标准蓝牙配对流程：设置 → 蓝牙 → 配对）。
## 工作原理
耳机通过其 `moto buds` 蓝牙经典连接公开三种传输通道：
1. 音频 (A2DP / HFP) — 由 macOS 自身处理。
2. **RFCOMM SPP `fc9d9fe0-…` 通道 16** — 与官方 Moto Buds Android 应用使用的相同供应商 SPP 路径。MotoBuds 会打开此通道，并通过它进行 BES (Bestechnic) 切换配置协议的通信。
3. OTA 通道 (`BESOTA`, `TOTA`) — 严格保持原样，不作处理。
线缆格式和完整的操作码表位于 [`docs/protocol.md`](docs/protocol.md)。通过逆向工程官方 APK 获取；交叉引用位于 `Tools/DiscoverBuds` 中。
## 开发
```
git clone https://github.com/Juanipis/motobuds.git
cd motobuds
swift test # unit tests
bash Bundle/build-app.sh debug # assemble MotoBuds.app
bash Bundle/install.sh debug # copy to /Applications + launch
# 查看实时日志
tail -f ~/Library/Logs/MotoBudsMac.log
```
使用真实的 RFCOMM 传输运行：
```
MOTOBUDS_REAL=1 open -a /Applications/MotoBuds.app
```
如果不加 `MOTOBUDS_REAL`，应用将运行于带有模拟状态的模拟传输环境中 — 这在没有硬件的情况下进行 UI 开发非常有用。
## 布局
```
.
├── Sources/MotoBudsApp/ # the SwiftUI app
│ ├── App/ # @main + ContentView
│ ├── BudsCore/ # transport, protocol, manager
│ ├── Features/ # ANC, battery, find buds, … views
│ └── UI/ # design system, menubar, hero
├── Tools/DiscoverBuds/ # SPM CLI for SDP/GATT discovery + SPP probe
├── Tests/MotoBudsAppTests/ # wire-format unit tests
├── Bundle/ # AppInfo.plist, build/package/install scripts, icon
├── scripts/ # bump-cask, update-appcast (release-time)
├── .github/workflows/ # CI + semantic-release
└── docs/protocol.md # reverse-engineered wire spec
```
## 发布说明
发布版本由 [semantic-release](https://semantic-release.gitbook.io/) 驱动：
- 向 `main` 分支推送包含 [约定式提交](https://www.conventionalcommits.org/) 信息 (`feat:`, `fix:`, …) 的代码。
- CI 会构建 `.app`，将其压缩，计算 SHA-256 哈希值，将两者附加到 GitHub release，更新 `CHANGELOG.md`，升级 [Homebrew cask](https://github.com/Juanipis/homebrew-tap)，并追加 Sparkle appcast 条目，以便已安装的应用自动更新。
有关完整的提交信息规范，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
## 状态
| 功能 | 状态 |
|---|---|
| ANC 模式 (关闭/通透/ANC/自适应) | ✅ 已通过听觉验证 |
| 电池电量 (左/右/充电仓) 实时 | ✅ |
| 入耳及入仓检测 | ✅ |
| 查找耳机 | ✅ |
| 双连接切换 | ✅ |
| 高解析度、游戏模式、音量增强 | ✅ |
| 低音增强 | ⚠️ 在此固件上静音 |
| 自定义 EQ | ❌ `guitar` 固件不支持 |
| OTA 固件更新 | ❌ 不会发布 — 在没有文档的情况下存在风险 |
## 致谢
灵感来源于 Android Moto Buds 应用 v01.0.129.12 — 线缆格式从其反编译代码中提取。与 Motorola Mobility LLC 无关联。"Moto Buds" 和 "Motorola" 是其各自所有者的商标。
## 许可证
[MIT](LICENSE) © 2026 Juan Pablo Díaz Correa.
标签：ANC主动降噪, Bestechnic, BES芯片, Homebrew, macOS应用, MIT协议, Moto Buds, Objective-C, SPP通信, Swift, TWS耳机控制, 云资产清单, 协议分析, 双设备连接, 开源, 摩托罗拉耳机, 权限提升, 查找耳机, 电量监控, 硬件控制, 菜单栏工具, 蓝牙RFCOMM, 蓝牙工具, 辅助 companion app, 逆向工程