pttkey

Push-to-talk mic toggle for PipeWire. Hold a mouse or keyboard button to unmute the default microphone source via wpctl.

Requirements

• Linux with PipeWire and wpctl available in PATH
• An input device (mouse or keyboard) with a usable key/button
• For --suppress, access to /dev/uinput (uinput kernel module + permissions)
• Rust toolchain (for building)

Build

cargo build --release

Usage

pttkey --key BTN_EXTRA
pttkey --key KEY_F9 --mode mute --no-sounds
pttkey --key KEY_LEFTCTRL+KEY_F --mode mute
pttkey --sound-on ~/on.wav --sound-off ~/off.ogg
pttkey --sound-on ~/on.wav --sound-volume 0.5
pttkey --sound-on false --sound-volume 0.3
pttkey --device /dev/input/event7 --key KEY_SPACE
pttkey --key KEY_F9 --suppress
pttkey --list-devices
pttkey --list-keys

Config

On first run, a config file is created at ~/.config/pttkey/config.toml. CLI flags update the config and trigger a user service restart. If the config directory cannot be written, a backup is stored at ~/.pttkey-config.toml. The app reloads the config automatically when the file changes.

Options

Argument	Meaning	Default / Notes
--key <NAME|CODE>	Evdev key name or numeric code. Can be repeated or combined with + for chords (e.g. --key KEY_LEFTCTRL+KEY_F).	Default: BTN_EXTRA
--device <PATH>	Input device path to use instead of auto-detect.	Optional
--mode <volume|mute>	Control by volume level or set-mute.	Default: volume
--reverse	Invert behavior so holding the key mutes.	Optional
--no-reverse	Disable reverse behavior (normal push-to-talk).	Optional
--on-level <FLOAT>	Volume when pressed.	Default: 1.0
--off-level <FLOAT>	Volume when released.	Default: 0.0
--sound-on <PATH>	Custom sound file for mic on (mp3, wav, ogg) or false to disable.	Optional
--sound-off <PATH>	Custom sound file for mic off (mp3, wav, ogg) or false to disable.	Optional
--sound-volume <FLOAT>	Volume for sounds.	Default: 1.0
--startup-state <muted|unmuted>	Initial mic state.	Default: muted
--sounds	Enable on/off sounds using system default sounds.	Enabled by default
--no-sounds	Disable on/off sounds.	Overrides --sounds
--suppress	Suppress only the configured key(s) from reaching other apps by re-emitting other events.	Optional
--no-suppress	Do not suppress key events.	Default
--list-keys	Print supported key names and exit.
--list-devices	Print input devices and exit.
--print-config	Print parsed configuration and exit.
--dry-run	Validate configuration and exit without changing mic state.

Supported key names

Usual keyboard and mouse keys are supported by name. You can also use numeric codes.

• Mouse: BTN_LEFT, BTN_RIGHT, BTN_MIDDLE, BTN_SIDE, BTN_EXTRA, BTN_FORWARD, BTN_BACK
• Letters: KEY_A through KEY_Z
• Numbers: KEY_0 through KEY_9
• Function keys: KEY_F1 through KEY_F12
• Modifiers: KEY_LEFTCTRL, KEY_RIGHTCTRL, KEY_LEFTSHIFT, KEY_RIGHTSHIFT, KEY_LEFTALT, KEY_RIGHTALT, KEY_LEFTMETA, KEY_RIGHTMETA
• Whitespace/controls: KEY_SPACE, KEY_TAB, KEY_ENTER, KEY_ESC, KEY_BACKSPACE, KEY_CAPSLOCK
• Navigation: KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END, KEY_PAGEUP, KEY_PAGEDOWN, KEY_INSERT, KEY_DELETE
• Punctuation: KEY_MINUS, KEY_EQUAL, KEY_LEFTBRACE, KEY_RIGHTBRACE, KEY_BACKSLASH, KEY_SEMICOLON, KEY_APOSTROPHE, KEY_GRAVE, KEY_COMMA, KEY_DOT, KEY_SLASH
• Numpad: KEY_NUMLOCK, KEY_KPSLASH, KEY_KPASTERISK, KEY_KPMINUS, KEY_KPPLUS, KEY_KPENTER, KEY_KP0-KEY_KP9, KEY_KPDOT
• Media: KEY_MUTE, KEY_VOLUMEDOWN, KEY_VOLUMEUP, KEY_PLAYPAUSE, KEY_NEXTSONG, KEY_PREVIOUSSONG, KEY_STOPCD

Use pttkey --list-keys to print the exact list accepted by the current build.

Install (user service)

You can also use ./install.sh to build, install, and set up the user service.

1. Copy the service file to your user systemd directory:

mkdir -p ~/.config/systemd/user
cp pttkey.service ~/.config/systemd/user/

2. Update the ExecStart path in ~/.config/systemd/user/pttkey.service if your checkout lives elsewhere, and add any flags you want (e.g. --key KEY_F9 --mode mute).

3. Enable and start the service:

systemctl --user daemon-reload
systemctl --user enable --now pttkey.service

Notes

• If the service cannot read your input device, add your user to the input group and re-login:

sudo usermod -aG input $USER

• Install the bundled udev rule (sets input devices to GROUP="input" and MODE="0660"):

sudo install -m 644 99-ptt-input.rules /etc/udev/rules.d/99-ptt-input.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

• Default sounds are bundled (mute.wav/unmute.wav); if they fail to play, paplay or canberra-gtk-play is used as fallback.

• --suppress uses /dev/uinput to forward non-PTT events. If it fails:

  • Ensure the uinput module is loaded (modprobe uinput).
  • Ensure your user can access /dev/uinput (often via input group or a udev rule).
  • If auto-detect selects the wrong device, pin --device to a /dev/input/by-id/...-event-* path.

• Stop the service with:

systemctl --user stop pttkey.service

Release checklist

1. Update Cargo.toml version and CHANGELOG.md.
2. Build and test: cargo build --release and cargo test.
3. Tag and push: git tag -a vX.Y.Z -m "vX.Y.Z" && git push --tags.