⌁keyboard-mp3
Tiny utility · Version 1.0.0

Give every
keystroke a sound.

A small Bash-powered utility that plays your chosen MP3 whenever you press a key. Set it up once, control it from your terminal, and let the clicks begin.

Get started ⌘ View source
✓ macOS + Linux✓ MP3 playback✓ Terminal-first
Terminal — keyboard-mp3
you@machine ~ $ keyboard-mp3 change "$HOME/Music/keyboard.mp3"
Sound file set to: /home/you/Music/keyboard.mp3
you@machine ~ $ keyboard-mp3 on
Keyboard sound started.
MP3: /home/you/Music/keyboard.mp3
you@machine ~ $ keyboard-mp3 status
LISTENER STATUS: RUNNING PID 4821
# Terminal preview for illustration — not a live system.
Small tool, simple workflow

Your keyboard.
Your sound.

Keyboard-MP3 keeps the workflow straightforward: configure a file, start the background listener, and manage it with a few memorable commands.

⌨

Global key listening

Uses Python's pynput listener to react to key presses outside the terminal when the operating system permits it.

♫

Your MP3, on repeat

Choose an existing MP3 file and use it as the sound played when a key is pressed. Playback is handled by pygame.

◉

Runs in the background

Start the listener from your shell and keep using other applications. Stop it when you want quiet again.

⇄

Change sounds quickly

Point the utility to another sound file from the terminal. If the listener is running, the CLI attempts to restart it.

⌘

Terminal-native controls

No large control panel to navigate. Use on, off, status, and change.

▤

Local configuration

The utility stores its sound path, helper, virtual environment, PID file, and log under your home directory.

Know before you run it

Designed for macOS and Linux.

The command-line interface is Bash-based and the listener is Python-based. Global keyboard monitoring depends on your desktop session and operating-system permissions.

 macOS

macOS may ask you to grant your terminal application permission to observe keyboard input.

  • ✓Check System Settings → Privacy & Security → Accessibility.
  • ✓If needed, also check Input Monitoring.
  • ✓Quit and reopen the terminal, then restart the listener.

🐧 Linux

Support varies by desktop environment, display server, and input-device permissions.

  • ✓Check your session type with echo "$XDG_SESSION_TYPE".
  • ✓X11 is generally more permissive for global key listeners.
  • ✓Wayland commonly restricts global keyboard monitoring; pynput may not detect keys in other apps.
Important: This utility listens for global key-press events and does not intentionally block or change normal keyboard input. Only install and run it on a computer you control. Avoid running it as root just to bypass input permissions.
Get up and running

Install once. Control from anywhere.

Download the installer from the repository, run it from a terminal, then set the sound file you want to use.

01 / Install

Requires Python 3 and a working Python virtual-environment setup.

bash ~/Downloads/install-keyboard-mp3.sh

02 / Configure

Replace the example with the full path to an existing MP3 file.

export PATH="$HOME/bin:$PATH" keyboard-mp3 change "$HOME/Music/keyboard.mp3"

03 / Start listening

Start the listener and type in another application to test it.

keyboard-mp3 on

04 / Stop when needed

Turn the sound off or check whether the listener is running.

keyboard-mp3 status keyboard-mp3 off

Linux note: on Debian/Ubuntu, you may need system packages for Python venv/build dependencies or audio libraries if pip cannot install a dependency. Package requirements vary by system.

Command reference

One command at a time.

Select a command to see what it does and copy an example.

COMMAND / ON

Start the listener

Launches the keyboard listener in the background using the currently configured sound file. If a listener is already running, the CLI reports that state.

keyboard-mp3 on
Under the hood

Local files. Easy to inspect.

Keyboard-MP3 keeps its helper, environment, configuration, and runtime log in predictable locations under your home directory.

  • ▸~/bin/keyboard-mp3 — Bash command-line interface
  • ▸~/.local/share/keyboard-mp3/listener.py — Python listener and audio helper
  • ▸~/.local/share/keyboard-mp3/venv/ — Python virtual environment and dependencies
  • ▸~/.local/share/keyboard-mp3/sound-path — Configured sound-file path
  • ▸~/.local/share/keyboard-mp3/listener.pid — Background process ID file
  • ▸~/.local/share/keyboard-mp3/listener.log — Listener output and error log
cat ~/.local/share/keyboard-mp3/listener.log
Troubleshooting

Something not clicking?

Start with these common fixes before digging into the log.

Why does `keyboard-mp3` say command not found?

Ensure ~/bin is on your PATH: run export PATH="$HOME/bin:$PATH". Open a new terminal or source the relevant shell startup file afterward.

Why are no key presses detected?

On macOS, review Accessibility and Input Monitoring permissions. On Linux, check whether your session uses X11 or Wayland; Wayland may prevent global monitoring.

Why is there no sound?

Confirm the configured file exists, check system output volume, and inspect ~/.local/share/keyboard-mp3/listener.log for audio or MP3-loading errors.

Can I use a path containing spaces?

Yes. Quote the path, for example: keyboard-mp3 change "$HOME/Music/My Keyboard Sound.mp3".

Does the website itself listen to my keyboard?

No. This is a documentation and demo site. It cannot install or control the native Python listener on your computer.

How do I uninstall it?

Run keyboard-mp3 off, then remove ~/bin/keyboard-mp3 and ~/.local/share/keyboard-mp3. Remove the PATH line from your shell startup file if you no longer need it.

Open source · Version 1.0.0

Ready to make some noise?

Explore the source, read the README, or contribute improvements on GitHub.

Explore the repository ↗