{
  "added_at": "2026-11-02",
  "additional_evidence_urls": [
    "https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/Headtracking.py",
    "https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/SpatialSensorManager.py",
    "https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/BluetoothService.py",
    "https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/Crc16.py",
    "https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/buds_to_unity.py",
    "https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/getBudsUDP.cs",
    "https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/LICENSE"
  ],
  "category": "reconstruction-cases",
  "description_en": "Reimplements the Samsung Galaxy Buds Pro’s proprietary spatial-audio messages in a small Python script so that a PC can stream the earbuds’ head-tracking data in real time. It connects to the earbuds’ GEARMANAGER (or FACTORY) RFCOMM serial service, frames packets with start and end markers and a CRC16-CCITT checksum, enables the sensor stream with attach and two-second keep-alive messages, and decodes the rotation quaternion from the data events. A contributed script converts the quaternion to Euler angles and forwards it over local UDP to a Unity receiver; results are shown only as author-provided sample output.",
  "description_zh": "用一个小型 Python 脚本重新实现 Samsung Galaxy Buds Pro 专有的空间音频消息，使电脑能实时获取耳机的头部追踪数据。脚本连接耳机的 GEARMANAGER（或 FACTORY）RFCOMM 串口服务，以起止标记和 CRC16-CCITT 校验封装数据包，通过 attach 消息和每两秒一次的保活消息开启传感器数据流，并从数据事件中解码旋转四元数。另有贡献者编写的脚本把四元数转换为欧拉角，经本机 UDP 转发给 Unity 接收端；效果仅以作者给出的示例输出展示。",
  "entry_url": "https://awesomerea.org/resources/budspro-headtracking-case/",
  "entry_url_zh": "https://awesomerea.org/zh/resources/budspro-headtracking-case/",
  "evidence_url": "https://github.com/timschneeb/BudsPro-Headtracking/blob/63b321aa0536fd28233eaaf3a05c4f3b3f8201fe/README.md",
  "group": "cases",
  "id": "budspro-headtracking-case",
  "json_url": "https://awesomerea.org/resources/budspro-headtracking-case/record.json",
  "kind": "case-study",
  "markdown_url": "https://awesomerea.org/resources/budspro-headtracking-case/index.md",
  "markdown_url_zh": "https://awesomerea.org/zh/resources/budspro-headtracking-case/index.md",
  "name": "BudsPro-Headtracking: streaming Galaxy Buds Pro head tracking over Samsung’s serial protocol",
  "name_zh": "BudsPro-Headtracking：通过 Samsung 串口协议获取 Galaxy Buds Pro 头部追踪数据",
  "record_type": "resource",
  "relationship": "independent-reconstruction",
  "requirements": [
    "The reviewed master commit 63b321a (2024-12-30) merges a contributor change that also accepts the FACTORY service name reported for Galaxy Buds2; the README covers only the Galaxy Buds Pro, and the project has no releases, tests or list of tested earbud firmware. Headtracking.py prints the raw x, y, z, w quaternion (four signed 16-bit values divided by 10,000) or, with -b, frame-timing statistics, and reports gyro-bias and stuck-sensor events only in verbose mode.",
    "It needs the user’s own paired Galaxy Buds Pro, addressed by its Bluetooth MAC address; no Samsung app or firmware is used at runtime or included in the repository. The repository does not document how the message IDs and framing were derived; code comments point to the author’s separate Galaxy Buds desktop client for the full parser and quaternion conversion.",
    "Python 3 with PyBluez on Windows or Linux; the README requires PyBluez 0.22 on Windows because 0.23 fails to enumerate Bluetooth devices. buds_to_unity.py also needs NumPy, hardcodes a device address and sends to 127.0.0.1:12562, and getBudsUDP.cs is a Unity MonoBehaviour adapted from a receiver credited to KAIST UVR Lab.",
    "The README shows sample quaternion output, and benchmark mode reports the average, minimum and maximum time between motion frames, but no captures, tests or recorded benchmark results are published. In the reviewed SpatialSensorManager.py the command payloads are built with Python’s bytes(n), which yields n zero bytes rather than the value n, so the bytes sent may differ from what the constant names suggest.",
    "LICENSE grants MIT (2021, Tim Schneeberger); the Unity script carries an attribution to its original author but no separate license. Galaxy Buds and its services belong to Samsung."
  ],
  "requirements_zh": [
    "所审阅的 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 所有。"
  ],
  "targets": [
    "protocol"
  ],
  "url": "https://github.com/timschneeb/BudsPro-Headtracking",
  "verification": "source-reviewed",
  "verified_at": "2026-10-20"
}