A lightweight, modern tray indicator that shows your wireless headset's battery level and charging status, with controls for LEDs, sidetone, ChatMix, and more — powered by HeadsetControl and built with PySide6 (Qt).

Works on KDE Plasma, GNOME, XFCE, Cinnamon, and other Linux desktop environments.

• Features
• Requirements
• Installation
  • Option 1: AppImage (Recommended)
  • Option 2: Fedora COPR
  • Option 3: Arch Linux (AUR)
  • Option 4: From Source
• Usage
• Command-Line Options
• Autostart
• Troubleshooting

• Dynamic Tray Icon — Live battery percentage and charging state rendered in real time.
• Low-Battery Notifications — Desktop alerts with optional headset sound when battery drops below your threshold.
• Preferences Dialog — Customize icon colors, orientation, scale, text overlay, poll interval, notification threshold, disconnected icon style, and language.
• Device Control — Toggle LEDs, adjust sidetone, set ChatMix level, and configure auto power-off time.
• Persistent Configuration — All preferences are saved between sessions automatically.
• Non-Blocking Polling — Hardware queries run in a background thread; the UI never freezes.
• Internationalization — UI is fully translatable; Spanish included. Language selectable in Preferences.
• Version Menu Item — Current version shown in the tray menu; click to open the GitHub releases page and check for updates.
• Debug Mode — Interactive console with live log output for troubleshooting.

⚠️ This app depends entirely on HeadsetControl for hardware communication.
Make sure headsetcontrol is installed and working before running the indicator.

No need to install Python or PySide6 — just headsetcontrol.

Download the latest AppImage (Linux) or EXE (Windows) from the Releases page.

1. Download the latest AppImage from the Releases page.

2. Make it executable:

   chmod +x Headset_Battery_Indicator-*.AppImage

3. Run it:

   ./Headset_Battery_Indicator-*.AppImage

You can move it to ~/.local/bin and add it to your desktop's autostart list.

sudo dnf copr enable ruflas/headset-battery-indicator
sudo dnf install headset-battery-indicator

Install using your AUR helper of choice:

yay -S headset-battery-indicator-git
# or
paru -S headset-battery-indicator-git

Community-maintained AUR package by @segarra99.

1. Install system dependencies:

   # Fedora:
   sudo dnf install headsetcontrol python3-pyside6
   
   # Debian/Ubuntu:
   sudo apt install headsetcontrol python3-pyside6

2. Clone and install:

   git clone https://github.com/ruflas/headset-battery-indicator.git
   cd headset-battery-indicator
   pip install .

3. Run:

   headset-battery-indicator
   # or
   python -m headset_battery_indicator

Once launched, the indicator appears in your system tray.

Right-clicking the tray icon gives you:

• Device name and current status (read-only info)
• Preferences — opens the configuration dialog
• Notify on low battery — toggle low-battery alerts
• LED, Sidetone, ChatMix, Auto-Off — direct device controls

Open via the tray menu → Preferences. From here you can configure:

• Icon fill and border colors (color picker or #RRGGBB hex input)
• Battery icon orientation (horizontal / vertical)
• Icon zoom/scale
• Percentage text overlay
• Notification threshold (5–95%)
• Poll interval (10–300 seconds)
• When disconnected — choose between empty battery (default), error/X icon, or hiding the tray icon
• Language — select UI language; Spanish and English included (restart required)

All settings take effect immediately and are saved automatically.

Example:

./Headset_Battery_Indicator-*.AppImage -debug

In debug mode, available commands include setIcon 75, setIcon 100 charging, notification, update, mockon, mockoff, resume, and exit.

To run the indicator automatically on login:

1. Open System Settings.
2. Go to Startup and Shutdown → Autostart (KDE) or Startup Applications (GNOME/XFCE).
3. Add a new entry:
   • AppImage: /full/path/to/Headset_Battery_Indicator-*.AppImage
   • Source install: headset-battery-indicator

Install headsetcontrol and verify it works before launching the indicator:

headsetcontrol -b

Installation by distro:

• Fedora / RHEL: sudo dnf install headsetcontrol
• Debian / Ubuntu: sudo apt install headsetcontrol
• Manual: see the HeadsetControl releases page

Also make sure QT_QPA_PLATFORM is not set to offscreen.

headsetcontrol needs USB device access. Install the udev rules:

sudo curl -o /etc/udev/rules.d/70-headsetcontrol.rules \
  https://raw.githubusercontent.com/Sapd/HeadsetControl/master/udev/70-headsetcontrol.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

Then re-plug the headset.

Launch with -debug for live log output and an interactive console:

# AppImage:
./Headset_Battery_Indicator-*.AppImage -debug

# Source install:
python -m headset_battery_indicator -debug

The rotating log file is always written to:

~/.local/share/HeadsetBatteryIndicator/logs/app.log