cunningorb/windows-headset-control
GitHub: cunningorb/windows-headset-control
通过逆向 HID 协议在 Windows 系统托盘中控制 Razer BlackShark V3 Pro 无线耳机的各项设置，无需运行 Synapse。
Stars: 0 | Forks: 0
# windows-headset-control
在 Windows 系统托盘中控制您的 Razer BlackShark V3 Pro 头戴式耳机，无需运行 Synapse。
电量、麦克风静音、侧听、游戏/聊天平衡以及降噪 —— 所有功能集中在一个面板中
该面板可从通知区域打开，点击其他位置即可关闭。它占用约 30 MB
内存，并且在您允许的情况下可以随 Windows 开机自启。
- 以普通用户身份运行。无需管理员权限。
- 不安装任何驱动程序或服务。
- 绝不触碰固件。
- 没有任何网络访问和遥测，绝对没有。
## 它适用于我的耳机吗？
**仅支持一款，且唯一一款型号：**
| | |
| --- | --- |
| 产品 | Razer BlackShark V3 Pro（无线，通过其 USB dongle） |
| USB vendor id | `0x1532` |
| USB product id | `0x101B` |
其他产品**不受支持**，包括其他 BlackShark 型号。本程序与耳机交互所使用的“语言”是通过监听它得出的，而非来自官方文档，因此只要 product id 不同，在有人重新破解之前，它就被视为完全不同的设备。
不确定您的设备型号？安装后运行 `headsetctl list --vendor-id 0x1532`。如果没有任何输出，则说明本程序无法与您的耳机进行通信。
## 安装
**[下载最新版本](https://github.com/cunningorb/windows-headset-control/releases/latest)**
并运行安装程序。它仅为您当前的用户安装，会添加一个“开始”菜单项，并提供
随 Windows 开机自启的选项。
**Windows 会向您发出警告。** 该安装程序未进行代码签名，因此 SmartScreen 会显示“Windows
已保护你的电脑”。请选择**“更多信息”**，然后选择**“仍要运行”**。
卸载方法：设置 → 已安装的应用 → Headset Tray → 卸载。
## 使用说明
单击托盘图标即可打开面板。
**电量**和**麦克风**状态显示在顶部。如果*耳机自身的开关*或 *Windows* 将您静音，麦克风状态都会显示为 `MUTED`，因为任何一种方式都会让您无法发声——点击该状态可切换 Windows 端的设置，因为没有任何软件能够代替您拨动物理开关。
**侧听**（0–15）控制您能听到多少自己的声音。**游戏/聊天平衡**（0–20）
用于混合耳机输出的两个音频通道。该按钮用于切换滑动条当前控制的是哪一个通道；拖动滑动条并松开后，更改将被一次性发送。
**降噪控制**支持关闭、ANC 或环境音模式。
ANC 有四个等级。环境音模式则没有等级——因此在该模式下，等级轨道会变暗（静默），
但依然会显示当您切换回 ANC 时的目标等级，因为耳机会记住设置。
**屏幕上没有任何猜测值。** 如果耳机拒绝提供某个数值，将显示为 `--`，而不会显示为
数字。失去无线连接会清除读数，而不是留下过时的数据。此外，在每次更改后，托盘程序都会询问耳机当前的实际状态——因此，如果耳机的反馈与您的设定不符，您看到的将是实际情况。
右键单击图标可进行刷新或退出。齿轮图标可打开设置：包括开机自启，以及当 Synapse 正在运行时是否向您发出警告（因为它会与本应用争夺相同的设置项）。
## 需了解的信息
该程序目前处于 **Alpha** 阶段。它已在开发者的硬件上正常运行，并有数百项测试作为保障，但其使用的是逆向得出的协议，并且目前仅在确切的一款耳机上实际使用过。
它向硬件发送厂商特定的指令。它不执行任何类型的固件访问，
且其能够发送的每一条指令都是通过观察 Razer 自家软件的操作得出的——但我们不提供任何
担保。运行此程序可能会使您的硬件保修失效。
有些您可能预期的功能**并未**包含在内，因为它们并非由耳机控制：音量和软件麦克风静音由 Windows 处理，而 Synapse 的音频增强功能（如低音增强、语音清晰度等）是由 PC 端的 THX 处理的，而非耳机端。因此本应用无需发送相关指令。
## 命令行
`headsetctl` 与托盘程序配套提供。每个命令都支持 `--json` 参数，以及
用于显示设备路径的 `--include-sensitive` 参数（默认隐藏）。
```
> headsetctl get battery
battery: 49
> headsetctl set sidetone 7
sidetone: 7
> headsetctl noise
noise-cancellation: anc level 4
> headsetctl noise --level 2 # keeps the current mode
noise-cancellation: anc level 2
> headsetctl noise --mode ambient # ambient has no level; the ANC level is retained
noise-cancellation: ambient (anc level 2)
```
| 命令 | 是否写入设备 |
| --- | --- |
| `list`、`inspect`、`probe`、`watch` | 否 |
| `get ` | 发送读取请求 |
| `set ` | 是 |
| `noise` | 读取；仅在指定 `--mode` 或 `--level` 时写入 |
| `param get/set ` | 是，仅限允许的标识符 |
`get` 在耳机拒绝读取时会报告 `unavailable` 而非数字——当耳机处于关闭状态时即会如此。`set` 在写入后会重新读取，并告诉您设备实际保存的值，因为写入被确认并不代表它已生效。
`list` 会枚举计算机上的所有 HID collection，并标出最佳的控制候选对象。`inspect` 在无 I/O 权限的情况下打开一个设备并打印其 report descriptor。`probe` 会在不发送任何指令的情况下监听主动上报（unsolicited report）；无输出是正常结果，因为设备仅在状态发生改变时才会通信。
```
> headsetctl param get 0x2c # observed but unidentified; no meaning is claimed
0x2c: 0f
```
## 工作原理
该耳机使用专有的 HID 协议，无任何公开文档。本项目是通过
抓取 Razer 自家软件驱动硬件时的数据包来逆向解析该协议的，并且
[`docs/device-research.md`](docs/device-research.md) 记录了每一个字节的证据：
发送了什么，返回了什么，在什么条件下。
**本项目仅能发送它在线路上实际捕获过的标识符。** 这些标识符存在于 `headset-protocol` 的允许列表（allowlist）中，除此之外它无法编码任何内容——因此，从代码库的任何角落，被猜测或暴力破解的命令都找不到通往您设备的路径。对于十个虽然被观察到但始终未能确定含义的参数，本项目特意不予命名，而不是为它们贴上听起来貌似合理的标签。
本项目未从任何其他项目中提取代码、注释或命令表。
[`docs/clean-room-notes.md`](docs/clean-room-notes.md) 记录了参考过的资料及参考条件，
其中包括一个后来被证明是错误的假设。
延伸阅读：[`docs/architecture.md`](docs/architecture.md) 介绍各个 crate 如何协同工作，
[`docs/threat-model.md`](docs/threat-model.md) 介绍安全态势，以及
[`docs/history/`](docs/history/) 了解设计记录。
## 从源码构建
仅支持 Windows，且对工具链的要求比平时更具体——开始前请查阅
[`CONTRIBUTING.md`](CONTRIBUTING.md)。
```
.\build-installer.ps1 # produces dist\HeadsetTray--setup.exe
```
或者，直接构建而不进行打包：
```
cargo build --release
.\target\release\headset-tray.exe --install
```
欢迎贡献代码；[`CONTRIBUTING.md`](CONTRIBUTING.md) 解释了确保协议研究真实可靠的相关规则，
并且这类规则还有不少。
## 非附属声明
这是一个非官方的社区互操作性实用工具。它不附属于 Razer Inc. 或任何其他制造商，也未获得其授权、认可或赞助。产品名称仅用于描述硬件兼容性。
Razer、BlackShark、Synapse 和 THX 是其各自所有者的商标。此处使用它们仅仅是为了标识本工具进行互操作的硬件。本项目的许可证不授予任何商标使用权。
## 许可证
根据以下任一许可证获得授权：
- Apache License, Version 2.0 ([`LICENSE-APACHE`](LICENSE-APACHE) 或
)
- MIT 许可证 ([`LICENSE-MIT`](LICENSE-MIT) 或 )
由您任选其一。
除非您明确声明，否则根据 Apache-2.0 许可证的规定，您为包含在本作品中而故意提交的任何贡献，均应按上述方式进行双许可授权，无需任何附加的条款或条件。
电量、麦克风静音、侧听、游戏/聊天平衡以及降噪 —— 所有功能集中在一个面板中
该面板可从通知区域打开，点击其他位置即可关闭。它占用约 30 MB
内存，并且在您允许的情况下可以随 Windows 开机自启。
- 以普通用户身份运行。无需管理员权限。
- 不安装任何驱动程序或服务。
- 绝不触碰固件。
- 没有任何网络访问和遥测，绝对没有。
## 它适用于我的耳机吗？
**仅支持一款，且唯一一款型号：**
| | |
| --- | --- |
| 产品 | Razer BlackShark V3 Pro（无线，通过其 USB dongle） |
| USB vendor id | `0x1532` |
| USB product id | `0x101B` |
其他产品**不受支持**，包括其他 BlackShark 型号。本程序与耳机交互所使用的“语言”是通过监听它得出的，而非来自官方文档，因此只要 product id 不同，在有人重新破解之前，它就被视为完全不同的设备。
不确定您的设备型号？安装后运行 `headsetctl list --vendor-id 0x1532`。如果没有任何输出，则说明本程序无法与您的耳机进行通信。
## 安装
**[下载最新版本](https://github.com/cunningorb/windows-headset-control/releases/latest)**
并运行安装程序。它仅为您当前的用户安装，会添加一个“开始”菜单项，并提供
随 Windows 开机自启的选项。
**Windows 会向您发出警告。** 该安装程序未进行代码签名，因此 SmartScreen 会显示“Windows
已保护你的电脑”。请选择**“更多信息”**，然后选择**“仍要运行”**。
卸载方法：设置 → 已安装的应用 → Headset Tray → 卸载。
## 使用说明
单击托盘图标即可打开面板。
**电量**和**麦克风**状态显示在顶部。如果*耳机自身的开关*或 *Windows* 将您静音，麦克风状态都会显示为 `MUTED`，因为任何一种方式都会让您无法发声——点击该状态可切换 Windows 端的设置，因为没有任何软件能够代替您拨动物理开关。
**侧听**（0–15）控制您能听到多少自己的声音。**游戏/聊天平衡**（0–20）
用于混合耳机输出的两个音频通道。该按钮用于切换滑动条当前控制的是哪一个通道；拖动滑动条并松开后，更改将被一次性发送。
**降噪控制**支持关闭、ANC 或环境音模式。
ANC 有四个等级。环境音模式则没有等级——因此在该模式下，等级轨道会变暗（静默），
但依然会显示当您切换回 ANC 时的目标等级，因为耳机会记住设置。
**屏幕上没有任何猜测值。** 如果耳机拒绝提供某个数值，将显示为 `--`，而不会显示为
数字。失去无线连接会清除读数，而不是留下过时的数据。此外，在每次更改后，托盘程序都会询问耳机当前的实际状态——因此，如果耳机的反馈与您的设定不符，您看到的将是实际情况。
右键单击图标可进行刷新或退出。齿轮图标可打开设置：包括开机自启，以及当 Synapse 正在运行时是否向您发出警告（因为它会与本应用争夺相同的设置项）。
## 需了解的信息
该程序目前处于 **Alpha** 阶段。它已在开发者的硬件上正常运行，并有数百项测试作为保障，但其使用的是逆向得出的协议，并且目前仅在确切的一款耳机上实际使用过。
它向硬件发送厂商特定的指令。它不执行任何类型的固件访问，
且其能够发送的每一条指令都是通过观察 Razer 自家软件的操作得出的——但我们不提供任何
担保。运行此程序可能会使您的硬件保修失效。
有些您可能预期的功能**并未**包含在内，因为它们并非由耳机控制：音量和软件麦克风静音由 Windows 处理，而 Synapse 的音频增强功能（如低音增强、语音清晰度等）是由 PC 端的 THX 处理的，而非耳机端。因此本应用无需发送相关指令。
## 命令行
`headsetctl` 与托盘程序配套提供。每个命令都支持 `--json` 参数，以及
用于显示设备路径的 `--include-sensitive` 参数（默认隐藏）。
```
> headsetctl get battery
battery: 49
> headsetctl set sidetone 7
sidetone: 7
> headsetctl noise
noise-cancellation: anc level 4
> headsetctl noise --level 2 # keeps the current mode
noise-cancellation: anc level 2
> headsetctl noise --mode ambient # ambient has no level; the ANC level is retained
noise-cancellation: ambient (anc level 2)
```
| 命令 | 是否写入设备 |
| --- | --- |
| `list`、`inspect`、`probe`、`watch` | 否 |
| `get 标签：HID, Linux, Razer, 动态分析, 可视化界面, 外设管理, 桌面应用, 硬件控制, 系统工具, 通知系统