# HeadsetControl

A cross-platform tool to control USB gaming headsets on **Linux**, **macOS**, and **Windows**. Manage sidetone, battery status, LED lights, equalizers, and more.

## Features

- **Sidetone** - Hear your own voice without latency (unlike software loopback)
- **Battery Status** - Monitor charge level, voltage, and time remaining
- **LED Control** - Toggle lights on/off
- **Equalizer** - Presets and custom EQ curves (including parametric EQ)
- **Inactive Time** - Auto power-off timer
- **Chat-Mix** - Game/chat audio balance
- **Microphone** - Volume, mute LED brightness, rotate-to-mute
- **Voice Prompts** - Enable/disable audio cues
- **Bluetooth** - Power-on behavior, call volume

Check the [Supported Devices](#supported-devices) table below to confirm your headset is covered.

## Installation

The quickest way to install is through your platform's package manager. Prefer a ready-made binary? Grab one from the [Releases](https://github.com/Sapd/HeadsetControl/releases) page — every release ships GPG-signed source, Linux (AppImage / `.deb` / `.rpm` / portable), macOS, and Windows (installer + portable) builds. The rolling [`continuous`](https://github.com/Sapd/HeadsetControl/releases/tag/continuous) pre-release tracks the latest `master`.

### Linux

**Ubuntu / Debian** — [PPA](https://launchpad.net/~sapd/+archive/ubuntu/headsetcontrol)
```bash
sudo add-apt-repository ppa:sapd/headsetcontrol
sudo apt update && sudo apt install headsetcontrol
```

**Fedora** — [COPR](https://copr.fedorainfracloud.org/coprs/thesapd/headsetcontrol/)
```bash
sudo dnf copr enable thesapd/headsetcontrol
sudo dnf install headsetcontrol
```

**RHEL / CentOS Stream / Rocky / AlmaLinux 10** — [COPR](https://copr.fedorainfracloud.org/coprs/thesapd/headsetcontrol/)

`hidapi` ships in EPEL on the RHEL family, so enable that first:
```bash
sudo dnf install epel-release
sudo dnf copr enable thesapd/headsetcontrol
sudo dnf install headsetcontrol
```

**Arch Linux** — available in the [AUR](https://aur.archlinux.org/packages?K=headsetcontrol)
```bash
yay -S headsetcontrol   # or the -git variant for the latest master
```

**NixOS**
```nix
# configuration.nix
environment.systemPackages = [ pkgs.headsetcontrol ];
services.udev.packages = [ pkgs.headsetcontrol ];  # for udev rules
```
Or run without installing: `nix run nixpkgs#headsetcontrol`

**Gentoo** — [nitratesky](https://github.com/VTimofeenko/nitratesky) overlay
```bash
eselect repository enable nitratesky
emerge -a app-misc/headsetcontrol
```

**FreeBSD**
```bash
pkg install headsetcontrol
```

### macOS

**Homebrew**
```bash
brew install sapd/headsetcontrol/headsetcontrol
```
Append `--HEAD` for the latest development version. A portable binary is also available on the [Releases](https://github.com/Sapd/HeadsetControl/releases) page — it is a self-contained universal build (Apple Silicon and Intel) that needs no Homebrew and runs on macOS 13.3 or newer.

### Windows

Download the installer or the portable `.exe` from the [Releases](https://github.com/Sapd/HeadsetControl/releases) page.

### Build from source

<details>
<summary>Click to expand build instructions</summary>

#### Requirements

- **C++20 compiler** (GCC 13+, Clang 16+, Apple Clang 15+, MSVC 2019 16.10+)
- **CMake** 3.12+
- **HIDAPI** library

#### Install dependencies

**Debian / Ubuntu**
```bash
apt-get install build-essential git cmake libhidapi-dev
```

**Fedora**
```bash
dnf install cmake hidapi-devel g++
```

**Arch Linux**
```bash
pacman -S git cmake hidapi
```

**RHEL / CentOS / Rocky / AlmaLinux**
```bash
dnf install epel-release
dnf groupinstall "Development Tools"
dnf install git cmake hidapi-devel
```

**openSUSE**
```bash
zypper in -t pattern devel_basis
zypper in cmake libhidapi-devel
```

**FreeBSD**
```bash
pkg install hidapi cmake
```

**macOS**
```bash
brew install hidapi cmake
```
Xcode (from the App Store) is required for the compilers.

**Windows** — for compilation using MSYS2/MinGW, see the [Development Guide](docs/DEVELOPMENT.md#windows-specific-notes).

#### Build and install

```bash
git clone https://github.com/Sapd/HeadsetControl && cd HeadsetControl
mkdir build && cd build
cmake ..
make
sudo make install
```

On **Linux**, `make install` also installs udev rules for non-root access. Reload them with:
```bash
sudo udevadm control --reload-rules && sudo udevadm trigger
```

</details>

## Supported Devices

| Device | Platform | sidetone | battery | notification sound | lights | inactive time | chatmix | voice prompts | rotate to mute | equalizer preset | equalizer | parametric equalizer | microphone mute led brightness | microphone volume | volume limiter | bluetooth when powered on | bluetooth call volume | microphone noise filter | sidetone status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Logitech ASTRO A50 Gen 4 | All | x | x |   |   |   | x |   |   | x | x | x |   | x |   |   |   | x | x |
| Logitech ASTRO A50 Gen 5 | All | x | x |   | x |   | x |   |   |   |   | x |   |   |   |   |   | x |   |
| Logitech G522 LIGHTSPEED | All | x | x |   | x | x |   | x |   | x | x | x | x |   |   |   |   |   | x |
| Logitech G533 | All | x | x |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Logitech G535 | All | x | x |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Logitech G633/G635/G733/G933/G935 | All | x | x |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Logitech G431/G432/G433 | All | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Logitech G930 | All | x | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Logitech G PRO X 2 LIGHTSPEED | All | x | x |   |   | x |   |   |   | x | x | x |   |   |   |   |   |   |   |
| Logitech G PRO Series | All | x | x |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Logitech Zone Wired/Zone 750 | All | x |   |   |   |   |   | x | x |   |   |   |   |   |   |   |   |   |   |
| Corsair Headset Device | All | x | x | x | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Corsair Wireless V2 Headset Device | All | x | x |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Corsair Virtuoso XT/SE | All |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| SteelSeries Arctis (1/7X/7P) Wireless | All | x | x |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| SteelSeries Arctis (7/Pro) | All | x | x |   | x | x | x |   |   |   |   |   |   |   |   |   |   |   |   |
| SteelSeries Arctis 9 | All | x | x |   |   | x | x |   |   |   |   |   |   |   |   |   |   |   |   |
| SteelSeries Arctis Pro Wireless | All | x | x |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| SteelSeries Arctis Nova 3 | All | x |   |   |   |   |   |   |   | x | x |   | x | x |   |   |   |   |   |
| SteelSeries Arctis Nova (5/5X) | All | x | x |   |   | x | x |   |   | x | x | x | x | x | x |   |   |   |   |
| SteelSeries Arctis Nova 7 | All | x | x |   |   | x | x |   |   | x | x |   | x | x | x | x | x |   | x* |
| SteelSeries Arctis Nova 7P | All |   | x |   |   | x |   |   |   | x | x |   | x | x | x | x | x |   |   |
| SteelSeries Arctis 7+ | All | x | x |   |   | x | x |   |   | x | x |   |   |   |   |   |   |   |   |
| SteelSeries Arctis Nova Pro Wireless | All | x | x |   | x | x |   |   |   | x | x |   |   |   |   |   |   |   |   |
| SteelSeries Arctis Nova 3P Wireless | All | x | x |   |   | x |   |   |   | x | x | x |   | x |   |   |   |   |   |
| SteelSeries Arctis GameBuds | All |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| HyperX Cloud Alpha Wireless | All | x | x |   |   | x |   | x |   |   |   |   |   |   |   |   |   |   |   |
| HyperX Cloud Flight Wireless | All |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| HyperX Cloud II Wireless | All |   | x |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| HyperX Cloud II Wireless (Kingston) | All | x | x |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| HyperX Cloud 3 | All | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| ROCCAT Elo 7.1 Air | All |   |   |   | x | x |   |   |   |   |   |   |   |   |   |   |   |   |   |
| ROCCAT Elo 7.1 USB | All |   |   |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Audeze Maxwell | All | x | x |   |   | x | x | x |   | x |   |   |   |   | x |   |   | x |   |
| Audeze Maxwell 2 | All | x | x |   |   | x | x | x |   | x |   |   |   |   |   |   |   | x |   |
| Lenovo Wireless VoIP Headset | All | x | x |   |   | x |   | x | x | x |   |   | x |   | x |   |   |   |   |
| Plantronics Voyager 8200 UC (BT600) | L/W | x | x |   | x |   |   | x |   |   |   |   |   |   | x |   |   |   |   |
| Jabra Link 390 (paired headset) | L/M | x | x |   | x | x |   | x |   |   |   |   |   |   | x |   |   |   | x |
| Jabra Evolve2 65 Flex (USB) | L/M | x | x |   | x | x |   | x |   |   |   |   |   |   | x |   |   |   | x |
| Sony INZONE Buds | All |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| Sony INZONE H5 | All | x | x |   |   |   | x |   |   |   |   |   |   | x |   |   |   |   |   |
| MCHOSE X9 Wireless | L/W |   | x |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
| HeadsetControl Test device | All | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x |

**Platform:** All = Linux, macOS, Windows | L/M = Linux and macOS only | L/W = Linux and Windows only

\* Only available on some product variants of that device. Sidetone status reading, for instance, is verified only for the SteelSeries Arctis Nova 7 Gen 2 (`1038:227e`).

> **Note:** Some Corsair headsets may need additional configuration - see [Adding a Corsair device](docs/ADDING_A_CORSAIR_DEVICE.md). Some headsets (HS80, HS70 wired, RGB Elite, Virtuoso) expose sidetone via ALSA mixer instead.

## Usage

```bash
# Show available options for your headset
headsetcontrol -h

# Show all options
headsetcontrol --help-all

# Get battery status
headsetcontrol -b

# Set sidetone level (0-128)
headsetcontrol -s 64

# Read the current sidetone level (when supported)
headsetcontrol -s

# Turn off LEDs
headsetcontrol -l 0

# Set auto-off timer (minutes, 0 = disabled)
headsetcontrol -i 30

# List device capabilities
headsetcontrol --capabilities
# or shorthand
headsetcontrol --caps
```

### Output Formats

For scripting and integration with other tools:

```bash
# JSON output
headsetcontrol -o json

# YAML output
headsetcontrol -o yaml

# Environment variables
headsetcontrol -o env
```

See [docs/LIBRARY_USAGE.md](docs/LIBRARY_USAGE.md) for building applications on top of HeadsetControl.

### Developer Mode

For debugging and reverse-engineering headset protocols:

```bash
# List all HID devices
headsetcontrol --dev -- --list

# Send raw HID data
headsetcontrol --dev -- --device 0x1b1c:0x1b27 --send "0xC9, 0x64" --receive
```

## Library API

HeadsetControl can be used as a library with C++ and C APIs. Build with shared library support:

```bash
cmake -DBUILD_SHARED_LIBRARY=ON ..
make
```

See [docs/LIBRARY_USAGE.md](docs/LIBRARY_USAGE.md) for complete documentation.

### Test Device

For development without hardware:
```bash
headsetcontrol --test-device -b
```

## GUI Applications

### Linux
- [gnome-shell-extension-HeadsetControl](https://github.com/ChrisLauinger77/gnome-shell-extension-HeadsetControl/) - GNOME shell extension (GNOME 42+)
- [headset-charge-indicator](https://github.com/centic9/headset-charge-indicator/) - System tray with controls (Python)
- [headset-battery-indicator](https://github.com/ruflas/headset-battery-indicator) - Tray icon with ChatMix, Sidetone controls (Python/Qt)
- [headsetcontrol-notificationd](https://github.com/Manawyrm/headsetcontrol-notificationd) - Battery notifications (PHP)
- [HeadsetControl-GUI](https://github.com/paradox-ng/HeadsetControl-GUI) - System tray and window with controls; x86-64 and ARM64 builds (Python/Qt6)

### macOS
- [HeadsetControl-MacOSTray](https://github.com/ChrisLauinger77/HeadsetControl-MacOSTray) - Menu bar app (macOS 14+)

### Windows
- [QontrolPanel](https://github.com/Odizinne/QontrolPanel) - Quick access / settings panel (Qt C++/QML, also works on Linux) - ARCHIVED
- [QontrolPanel](https://github.com/ChrisLauinger77/QontrolPanel) - Quick access / settings panel (Qt C++/QML, also works on Linux) - FORK from Odizinne
- [HeadsetControl-GUI](https://github.com/LeoKlaus/HeadsetControl-GUI) - Simple GUI (Qt C++)
- [HeadsetControl-SystemTray](https://github.com/zampierilucas/HeadsetControl-SystemTray) - System tray (Python)
- [headset-battery-indicator](https://github.com/aarol/headset-battery-indicator) - Native tray icon (Rust)

## Contributing

Want to add support for a new headset or improve the software? See the [Development Guide](docs/DEVELOPMENT.md).

Adding a new device requires capturing USB traffic between the headset and its Windows software using Wireshark or USBlyzer (a VM with USB passthrough works well).

## License

Released under [GPL v3](LICENSE).

HeadsetControl is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

---

If you find this useful, please star the repository!