headphone-mute

Mute audio device on Linux when wired headphones are unplugged.

Usage

cargo install headphone-mute # Install CLI
sudo usermod -aG input "$USER" # Add user to the input group
# log out and log back in so the new group membership is applied
headphone-mute # Test CLI

After installing, log out and log back in so the new group membership is applied.

If you want a temporary workaround without logging out, run:

newgrp input
headphone-mute

Verify that the current session has the required group:

id -nG | tr ' ' '\n' | grep '^input$'

If this prints nothing, start a new login session by logging out and back in. For a temporary shell-only workaround, run newgrp input and then start the program from that shell.

Run at startup

Desktop autostart

On many Linux desktops, add a .desktop file to ~/.config/autostart/:

mkdir -p ~/.config/autostart
cat > ~/.config/autostart/headphone-mute.desktop <<'EOF'
[Desktop Entry]
Type=Application
Name=headphone-mute
Exec=/home/YOUR_USERNAME/.cargo/bin/headphone-mute
Terminal=false
X-GNOME-Autostart-enabled=true
EOF

Replace YOUR_USERNAME with your Linux username.

Use pgrep to check whether it is running:

pgrep -af headphone-mute

If it started successfully, the command prints the process ID and command line. If it prints nothing, inspect your desktop environment's autostart logs or run the command manually to see the error:

/home/YOUR_USERNAME/.cargo/bin/headphone-mute

systemd (user service)

Create a user service file:

mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/headphone-mute.service

Add:

[Unit]
Description=Headphone mute monitor

[Service]
Type=simple
ExecStart=%h/.cargo/bin/headphone-mute
Restart=on-failure

[Install]
WantedBy=default.target

Then enable it:

systemctl --user daemon-reload
systemctl --user enable --now headphone-mute.service

Check its status and recent logs with:

systemctl --user status headphone-mute.service
journalctl --user -u headphone-mute.service

The service should show active (running). The log should include Starting headphone monitor... and, after a device is found, Found headphone switch device.

This makes the tool start automatically after login.

Use-Case

I developed it to use a package that will mute sound when I unplug my wired headphones.

You might use it for that reason too...

^_^

Details

It tries to mute using wpctl, first. If it fails, it tries with pactl.

Note

It was tested on Ubuntu 24.04.4 LTS (x86_64)

Development

1. Build using cargo: cargo build
2. Run executable with sudo: sudo ./target/debug/headphone-mute

Test Permission Denied

Just run cargo run with user that does not have sudo privilege.

It should show: Permission denied error in terminal, since /dev/input files require sudo privilege.

Troubleshooting

Permission denied when starting the app

If you see a message about /dev/input permissions, add your user to the input group:

sudo usermod -aG input "$USER"

Then log out and back in, or reboot.

Audio does not mute

Make sure one of these is installed and available in your session:

• wpctl (WirePlumber)
• pactl (PulseAudio)

You can usually install them via your distro package manager.

License

MIT OR Apache-2.0

Contributing

If you have idea, feel free to open PR.