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

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 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Logitech G533 | All | x | x | | | x | | | | | | | | | | | | | Logitech G535 | All | x | x | | | x | | | | | | | | | | | | | Logitech G633/G635/G733/G933/G935 | All | x | x | | x | | | | | | | | | | | | | | Logitech G432/G433 | All | x | | | | | | | | | | | | | | | | | Logitech G930 | All | 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 | All | 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 | | | | | 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 | | | | | | | | | | | | | | | | | 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 | | | | Lenovo Wireless VoIP Headset | All | x | x | | | x | | x | x | x | | | | | x | | | | HeadsetControl Test device | All | 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

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.

Installation

Package Managers

macOS (Homebrew)

brew install sapd/headsetcontrol/headsetcontrol --HEAD

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

Building from Source

Requirements

• C++20 compiler (GCC 10+, Clang 10+, MSVC 2019+)
• CMake 3.12+
• HIDAPI library

Install Dependencies

<details> <summary><b>Linux</b></summary>

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

CentOS / RHEL

yum install epel-release
yum groupinstall "Development tools"
yum install git cmake hidapi-devel

openSUSE

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

FreeBSD

pkg install hidapi cmake

</details> <details> <summary><b>macOS</b></summary>

brew install hidapi cmake

Note: Xcode (from App Store) is required for compilers.

</details> <details> <summary><b>Windows</b></summary>

Pre-built binaries are available on the releases page.

For compilation using MSYS2/MinGW, see the Development Guide.

</details>

Build

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

Install

sudo make install

On Linux, this also installs udev rules for non-root access. Reload them with:

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

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)

macOS

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

Windows

• QontrolPanel - Quick access / settings panel (Qt C++/QML, also works on Linux)
• 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!