666mille/MyJBxHeadsetControl

# 我的JBxHeadsetControl 一款专为 **JBL Quantum 950 Wireless** 耳机设计的 Stream Deck 插件。  直接通过 Elgato Stream Deck 控制你的 JBL Quantum 950 Wireless 耳机 - 无需 JBL QuantumENGINE。该插件通过逆向工程的 HID 协议与耳机的 USB dongle 进行通信， 并在你的按键和旋钮上显示实时状态。 ## 功能 | 操作 | 类型 | 作用 | |---|---|---| | **Mute** | 按键 | 切换麦克风静音。显示麦克风图标：开启时为白色，静音时为红色并带有叉号。离线 / 无 Dongle 状态会显示可自定义的标题和颜色。 | | **ANC / Ambient** | 按键 | 循环切换 Off → Noise Cancelling → Ambient Aware，颜色可自定义 | | **Spatial Sound** | 按键 | 循环切换 Off → Fixed → Head Tracking，颜色可自定义 | | **Battery** | 按键 | 将实时电量显示为会根据电量填充的电池，具备可自定义的阈值和颜色 | | **Game-Chat Balance** | 旋钮 | 自定义显示：JBL 标题、实时电量读数、耳机图标和双色平衡条。旋转以调节，按下可重置为 50/50。最后使用的值将被持久化保存。 | 每个按键都可以在左上角显示可自定义的标题文本（默认为 `JBL`）- 可以在 Property Inspector 中针对每个操作开启/关闭该功能并修改文本。 所有操作都会对其他地方的更改（耳机按钮、耳罩上的滚轮或 QuantumENGINE）做出即时反应， 并在耳机关机时显示 **OFFLINE**，在拔出 USB dongle 时显示 **NO DONGLE**，包括自动重连。离线和无 Dongle 的颜色支持针对每个操作单独自定义。 ## 环境要求 - JBL Quantum 950 Wireless 及其 2.4 GHz USB dongle - Elgato Stream Deck 软件 7.1+（SDK v3，Node.js 20 插件 runtime） - Windows 10/11（在 Windows 上开发并测试；macOS 未经测试） ## 安装说明 ### 通过发布版本安装（推荐） 1. 从 [Releases 页面](https://github.com/666mille/MyJBxHeadsetControl/releases) 下载最新的 `com.holgermilz.myjbxheadsetcontrol.streamDeckPlugin`。 2. 双击该文件 - Stream Deck 应用会自动安装此插件。 ### 从源码安装 ``` git clone https://github.com/666mille/MyJBxHeadsetControl.git cd MyJBxHeadsetControl npm install npm run build streamdeck link com.holgermilz.myjbxheadsetcontrol.sdPlugin ``` `streamdeck` 是 [Elgato CLI](https://docs.elgato.com/sdk/plugins/cli) （`npm i -g @elgato/cli`）。在开发时，请使用 `npm run watch`，它会在每次更改后重新构建并 重启插件。注意：`watch` 仅会重新加载插件代码 - 在更改 manifest、layouts 或 Property Inspector HTML 后，请完全退出 Stream Deck 应用并重新启动它。 ## 使用说明 - 如果在使用插件时发现冲突，请**关闭 JBL QuantumENGINE** - 因为两者 会与同一个 HID 接口进行通信。 - 旋钮会显示当前的游戏/聊天音量分配；彩色数字和进度条使用的是 可自定义的 **chat** 和 **game** 颜色。 ## 故障排除 **耳机已开启，但显示 OFFLINE** dongle 只有在收到真实的状态更新后才会报告耳机信息。如果你 在电脑（或 Stream Deck）启动*之后*才打开耳机，插件可能尚未 接收到状态数据包。要强制发送一次，请执行以下操作： - **转动一下音量滚轮**，或者 - **切换一次 ANC / 静音**，或者 - **将耳机关闭后再重新打开**。 以上任何操作都会使耳机发送状态数据包，随后显示会立即 切换为在线。提示：在电脑已开机的情况下打开耳机，通常可以 完全避免这种情况。 **没有任何更新 / 数值卡住** 确保 JBL QuantumENGINE 已关闭，然后退出并重新启动 Stream Deck 应用。 **日志** `%appdata%\Elgato\StreamDeck\Plugins\com.holgermilz.myjbxheadsetcontrol.sdPlugin\logs` ## 工作原理 Quantum 950 dongle 在 USB 接口 5 上公开了多个 HID collection。该插件 使用一个共享句柄打开 vendor collection： - **Events in：** dongle 会推送关于电量、静音、 ANC、ambient aware、spatial mode、game-chat balance 和耳机电源的状态数据包（`86 00 dd ...`）。此外，watchdog 会轮询设备列表以检测 dongle 的拔出/重新插入。 - **Commands out：** 设置将以 64 字节的 feature report 写入 （`88 00 dd 02 00 01 00 05 00 01 00 `）。 连接状态会先以悲观策略设置为 *offline*，只有在收到来自耳机的第一个真实状态数据包时（已知状态码或 head-tracking 数据），才会转为 *online*。 普通的 dongle 后台通信会被刻意忽略，因此未开机的耳机会被 正确显示为 OFFLINE。该状态会保持为 online，直到收到明确的关机事件 或 dongle 被移除。 状态保存在内存中，并通过 pub/sub 机制进行同步（通过去抖动的 批量写入镜像到磁盘），这样只要发生任何变化，每个按键和旋钮都会立即更新。 ## 致谢 协议的逆向工程借助于 USB 分析仪和极大的耐心。 使用 [Elgato Stream Deck SDK](https://docs.elgato.com/sdk) 和 [node-hid](https://github.com/node-hid/node-hid) 构建。 ## 许可证 [MIT](LICENSE) (c) 2026 Holger Milz

标签：GNU通用公共许可证, HID 协议, JBL Quantum, MITM代理, Node.js, Stream Deck 插件, 外设管理, 数据可视化, 硬件控制, 自动化攻击