sonyctl

Linux desktop monitor and Tier-A controller for Sony WH-1000XM-series headphones (and similar Bluetooth headsets that publish battery via BlueZ).

What you get

• sonyctl (CLI) — probe, watch, list, explain, connect, disconnect, set-profile.
• sonyctl-app (GTK4 desktop) — tray indicator with battery, popup window with status + Tier A controls.

See docs/ARCHITECTURE.md for the design.

Build

System dependencies (Pop!_OS 22.04 / Ubuntu 22.04+):

sudo apt install -y libgtk-4-dev libglib2.0-dev pkg-config build-essential

Then:

cargo build --release
./target/release/sonyctl probe --mac AA:BB:CC:DD:EE:FF
./target/release/sonyctl-app --mac AA:BB:CC:DD:EE:FF

Host prerequisites

• BlueZ 5.56+ running with --experimental (otherwise Battery1 is never exposed). See docs/ARCHITECTURE.md §"Known constraints".
• PipeWire + WirePlumber 0.5+ with the native HFP/HSP backend.
• The headset must be paired and trusted in BlueZ before first run.

Legal / trademark notice

sonyctl is an unofficial open-source project and is not affiliated with, endorsed by, sponsored by, or supported by Sony.

Sony, WH-1000XM, and related product names are trademarks of their respective owners. Product names are used only to describe compatibility.

This project does not contain Sony firmware, Sony application code, Sony assets, or proprietary Sony documentation.

Safety notice

This software is provided as-is. Some commands may change headset settings. Use it only with devices you own or are authorized to control. Firmware updates may change behavior. Use at your own risk.

License

MIT — see LICENSE.