# BudsPro-Headtracking：通过 Samsung 串口协议获取 Galaxy Buds Pro 头部追踪数据

> 用一个小型 Python 脚本重新实现 Samsung Galaxy Buds Pro 专有的空间音频消息，使电脑能实时获取耳机的头部追踪数据。脚本连接耳机的 GEARMANAGER（或 FACTORY）RFCOMM 串口服务，以起止标记和 CRC16-CCITT 校验封装数据包，通过 attach 消息和每两秒一次的保活消息开启传感器数据流，并从数据事件中解码旋转四元数。另有贡献者编写的脚本把四元数转换为欧拉角，经本机 UDP 转发给 Unity 接收端；效果仅以作者给出的示例输出展示。

- 类型：案例
- 目标：协议
- 类别：独立重建案例
- 关联：独立重建项目
- 来源复核于：2026-10-20
- 收录于：2026-11-02
- 原始资源：<https://github.com/timschneeb/BudsPro-Headtracking>
- 一手来源：<https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/README.md>
- 目录页面：<https://awesomerea.org/zh/resources/budspro-headtracking-case/>
- 记录 JSON：<https://awesomerea.org/resources/budspro-headtracking-case/record.json>
- 英文版：[English](https://awesomerea.org/resources/budspro-headtracking-case/index.md)

## 使用条件与局限

- 所审阅的 master 分支提交 63b321a（2024-12-30）合并了一位贡献者的修改，使脚本也能识别据报告用于 Galaxy Buds2 的 FACTORY 服务名；README 只涉及 Galaxy Buds Pro，项目没有发布版本、测试，也没有列出测试过的耳机固件版本。Headtracking.py 输出原始的 x、y、z、w 四元数（四个有符号 16 位数值除以 10000），使用 -b 时则输出帧间隔统计，陀螺仪偏差和传感器卡滞事件只在详细模式下提示。
- 需要使用者自己已配对的 Galaxy Buds Pro，并通过其蓝牙 MAC 地址指定设备；运行时不使用任何 Samsung 应用或固件，仓库中也不包含这些文件。仓库未说明消息 ID 和帧格式是如何推断出来的；代码注释指向作者另一个 Galaxy Buds 桌面客户端项目中的完整解析器和四元数转换代码。
- 需要 Python 3 与 PyBluez，可在 Windows 或 Linux 上运行；README 要求在 Windows 上使用 PyBluez 0.22，因为 0.23 无法枚举蓝牙设备。buds_to_unity.py 还需要 NumPy，脚本内写死了设备地址并发送到 127.0.0.1:12562；getBudsUDP.cs 是一个 Unity MonoBehaviour，改编自注明出自 KAIST UVR Lab 的接收端代码。
- README 展示了四元数示例输出，基准模式可报告运动帧之间的平均、最短和最长间隔，但项目没有公开抓包记录、测试或基准结果。在所审阅的 SpatialSensorManager.py 中，命令负载用 Python 的 bytes(n) 构造，得到的是 n 个零字节而非数值 n，因此实际发送的字节可能与常量名称所示含义不同。
- LICENSE 声明采用 MIT 许可（2021，Tim Schneeberger）；Unity 脚本保留了原作者署名，但没有单独的许可证。Galaxy Buds 及其服务归 Samsung 所有。

## 一手来源

1. <https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/README.md>
2. <https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/Headtracking.py>
3. <https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/SpatialSensorManager.py>
4. <https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/BluetoothService.py>
5. <https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/Crc16.py>
6. <https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/buds_to_unity.py>
7. <https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/getBudsUDP.cs>
8. <https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/LICENSE>

## 同分区更多条目：协议

- [Even G2 协议：逆向分析 Even Realities G2 智能眼镜的 BLE 通信](https://awesomerea.org/zh/resources/even-g2-ble-protocol-case/index.md) · 案例
- [fuji-cam-wifi-tool：重建 Fujifilm X 系列相机 Wi-Fi 遥控协议](https://awesomerea.org/zh/resources/fuji-cam-wifi-tool-protocol-case/index.md) · 案例
- [Gymnasticon：将专有健身单车数据转为标准骑行传感器信号](https://awesomerea.org/zh/resources/gymnasticon-exercise-bike-bridge-case/index.md) · 案例
- [garmin-ble：Garmin 手表 GFDI 协议的 Python 客户端](https://awesomerea.org/zh/resources/garmin-ble-gfdi-protocol-case/index.md) · 案例
- [bosectl：重建 Bose BMAP 耳机协议](https://awesomerea.org/zh/resources/bosectl-bose-bmap-protocol-case/index.md) · 案例
- [lib-osmo-ble：DJI Osmo Pocket 3 低功耗蓝牙协议库](https://awesomerea.org/zh/resources/osmo-pocket-3-ble-protocol-case/index.md) · 案例

## 关于此条目

说明已依据一手来源复核。
原创说明采用 MIT 许可；外部项目、论文与素材保留各自的权利和许可。