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 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 page — every release ships GPG-signed source, Linux (AppImage / .deb / .rpm / portable), macOS, and Windows (installer + portable) builds. The rolling continuous pre-release tracks the latest master.

Linux

Ubuntu / Debian — PPA

sudo add-apt-repository ppa:sapd/headsetcontrol
sudo apt update && sudo apt install headsetcontrol

Fedora — COPR

sudo dnf copr enable thesapd/headsetcontrol
sudo dnf install headsetcontrol

RHEL / CentOS Stream / Rocky / AlmaLinux 10 — COPR

hidapi ships in EPEL on the RHEL family, so enable that first:

sudo dnf install epel-release
sudo dnf copr enable thesapd/headsetcontrol
sudo dnf install headsetcontrol

Arch Linux — available in the AUR

yay -S headsetcontrol   # or the -git variant for the latest master

NixOS

# configuration.nix
environment.systemPackages = [ pkgs.headsetcontrol ];
services.udev.packages = [ pkgs.headsetcontrol ];  # for udev rules

Or run without installing: nix run nixpkgs#headsetcontrol

Gentoo — nitratesky overlay

eselect repository enable nitratesky
emerge -a app-misc/headsetcontrol

FreeBSD

pkg install headsetcontrol

macOS

Homebrew

brew install sapd/headsetcontrol/headsetcontrol

Append --HEAD for the latest development version. A portable binary is also available on the Releases page.

Windows

Download the installer or the portable .exe from the Releases page.

Build from source

Click to expand build instructions

Requirements

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

Install dependencies

Debian / Ubuntu

apt-get install build-essential git cmake libhidapi-dev

Fedora

dnf install cmake hidapi-devel g++

Arch Linux

pacman -S git cmake hidapi

RHEL / CentOS / Rocky / AlmaLinux

dnf install epel-release
dnf groupinstall "Development Tools"
dnf install git cmake hidapi-devel

openSUSE

zypper in -t pattern devel_basis
zypper in cmake libhidapi-devel

FreeBSD

pkg install hidapi cmake

macOS

brew install hidapi cmake

Xcode (from the App Store) is required for the compilers.

Windows — for compilation using MSYS2/MinGW, see the Development Guide.

Build and install

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:

sudo udevadm control --reload-rules && sudo udevadm trigger

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
Logitech G522 LIGHTSPEED	All	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
Logitech ASTRO A50 Gen 5	All	x	x		x		x					x						x
Corsair Headset Device	All	x	x	x	x
Corsair Wireless V2 Headset Device	All	x	x			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
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	L/M	x	x			x				x	x	x		x
SteelSeries Arctis Buds	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 3	All	x
HyperX Cloud II Wireless (Kingston)	All	x	x			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
Sony INZONE Buds	All		x
Sony INZONE H5	All	x	x				x							x
HeadsetControl Test device	All	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

Note: Some Corsair headsets may need additional configuration - see Adding a Corsair device. Some headsets (HS80, HS70 wired, RGB Elite, Virtuoso) expose sidetone via ALSA mixer instead.

Usage

# 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

# 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:

# JSON output
headsetcontrol -o json

# YAML output
headsetcontrol -o yaml

# Environment variables
headsetcontrol -o env

See docs/LIBRARY_USAGE.md for building applications on top of HeadsetControl.

Developer Mode

For debugging and reverse-engineering headset protocols:

# 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:

cmake -DBUILD_SHARED_LIBRARY=ON ..
make

See docs/LIBRARY_USAGE.md for complete documentation.

Test Device

For development without hardware:

headsetcontrol --test-device -b

GUI Applications

Linux

• gnome-shell-extension-HeadsetControl - GNOME shell extension (GNOME 42+)
• headset-charge-indicator - System tray with controls (Python)
• headset-battery-indicator - Tray icon with ChatMix, Sidetone controls (Python/Qt)
• headsetcontrol-notificationd - Battery notifications (PHP)
• HeadsetControl-GUI - System tray and window with controls; x86-64 and ARM64 builds (Python/Qt6)

macOS

• HeadsetControl-MacOSTray - Menu bar app (macOS 14+)

Windows

• QontrolPanel - Quick access / settings panel (Qt C++/QML, also works on Linux) - ARCHIVED
• QontrolPanel - Quick access / settings panel (Qt C++/QML, also works on Linux) - FORK from Odizinne
• HeadsetControl-GUI - Simple GUI (Qt C++)
• HeadsetControl-SystemTray - System tray (Python)
• headset-battery-indicator - Native tray icon (Rust)

Contributing

Want to add support for a new headset or improve the software? See the Development Guide.

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.

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!