A GNOME Shell extension that caps media volume when headphones (wired or Bluetooth) are the active audio output — the same hearing-safety feature found on many phones, now on your Gnome desktop.
| Feature | Description |
|---|---|
| Volume cap | Set a maximum volume percentage (1–100%). When headphones exceed it, the extension acts immediately. |
| Three action modes | warn-prompt — clamp + notification with "Allow anyway" buttonwarn-allow — notification only, no clampingblock — silently clamp, no notification |
| Device targeting | Apply the limit to all headphones, or pick one specific Bluetooth device by MAC address. |
| Quick Settings toggle | Enable/disable the limiter instantly from the system menu. |
| Session override | Click "Allow anyway" on a notification to bypass the limit until you disconnect the device. |
| Virtual sink passthrough | Works correctly with EasyEffects and other DSP pipelines that insert virtual sinks between apps and hardware. |
Visit extensions.gnome.org and search for "Headphone Volume Limiter".
- Download the latest
headphone-volume-limiter@brian.local-v*.zipfrom the Releases page. - Install it:
gnome-extensions install headphone-volume-limiter@brian.local-v*.zipRestart GNOME Shell (Alt+F2, type r, Enter on X11; log out/in on Wayland). Enable: gnome-extensions enable headphone-volume-limiter@brian.local
# Clone git clone https://github.com/imnotndesh/headphone-volume-limiter.git cd headphone-volume-limiter # Symlink into extensions directory ln -s "$(pwd)/headphone-volume-limiter@brian.local" \ ~/.local/share/gnome-shell/extensions/headphone-volume-limiter@brian.local # Compile schemas glib-compile-schemas \ ~/.local/share/gnome-shell/extensions/headphone-volume-limiter@brian.local/schemas/ # Reload Shell (Alt+F2 → r → Enter) then enable gnome-extensions enable headphone-volume-limiter@brian.local
Open preferences from GNOME Extensions app, or:
gnome-extensions prefs headphone-volume-limiter@brian.local
- Limit percentage — slider from 1% to 100% (default: 70%)
- Action mode — warn-prompt, warn-allow, or block
- Device targeting — all headphones, or one specific Bluetooth device
- The Quick Settings toggle in the system menu mirrors the enabled setting
To Watch extension logs in real time
journalctl -f -o cat /usr/bin/gnome-shell | grep headphone-limiter