Music Keyboard (Global Background Note Player)

A Python desktop utility that listens to global keyboard events and plays musical notes in real time.

Recommended Python version: 3.11 or 3.12 (best binary wheel support for audio packages).

What this project does

• Runs continuously until manually stopped
• Captures keyboard input globally (even when this app is not focused)
• Maps all letter keys (A-Z) to notes by default
• Plays notes with minimal latency using preloaded audio
• Supports multi-key playback (chords)
• Prints key + note for debugging
• Supports custom mappings and instrument switching
• Supports one-shot sample slicing from a song (--sample-map-file)

Tech stack

• Global key listener: pynput
• Audio playback: pygame-ce (pygame.mixer)
• Language: Python 3

Project files

• music_keyboard.py - main application code
• requirements.txt - dependencies
• pyproject.toml - package metadata and keywords
• mapping.example.json - example custom key mapping
• sample_map.example.json - example one-shot slice mapping
• docs/KT.md - detailed knowledge-transfer document
• CONTRIBUTING.md - contribution and pre-PR checks

Keywords

python, music-keyboard, global-hotkeys, global-keyboard-listener, pynput, pygame-ce, audio-sampling, audio-slicing, sample-chopping, one-shot-sampler, soundboard, keyboard-sampler, real-time-audio, desktop-app, midi-inspired

Install

1. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies:

pip install -r requirements.txt

If dependency resolution is stale, update pip first:

python -m pip install --upgrade pip

Run

python3 music_keyboard.py

Stop with Ctrl+C.

Default key mapping (all letters)

Z X C V B N M:

• Z -> C3
• X -> D3
• C -> E3
• V -> F3
• B -> G3
• N -> A3
• M -> B3

A S D F G H J K L:

• A -> C4
• S -> D4
• D -> E4
• F -> F4
• G -> G4
• H -> A4
• J -> B4
• K -> C5
• L -> D5

Q W E R T Y U I O P:

• Q -> E5
• W -> F5
• E -> G5
• R -> A5
• T -> B5
• Y -> C6
• U -> D6
• I -> E6
• O -> F6
• P -> G6

Customize key-to-note mapping

1. Copy mapping.example.json and edit values.
2. Run:

python3 music_keyboard.py --mapping-file mapping.example.json

Mapping JSON format:

{
  "a": "C4",
  "s": "D4"
}

One-shot slice mapping (sample a song)

Use this mode when you want keys to trigger short chunks from one audio track.

Example config file: sample_map.example.json

Run:

python3 music_keyboard.py --sample-map-file sample_map.example.json

Sample map format:

{
  "source": "instruments/engeyum kadhal/Engeyum Kaadhal.wav",
  "keys": {
    "a": { "start": 5.0, "end": 5.3, "label": "Slice A" },
    "s": { "start": 5.3, "end": 5.6, "label": "Slice S" },
    "d": "samples/chop_d.wav"
  }
}

Supported per-key spec formats:

• "a": "path/to/file.wav": play whole file
• "a": [5.0, 5.3]: slice from top-level source
• "a": { "start": 5.0, "end": 5.3, "label": "Hook" }: labeled slice from source
• "a": { "file": "path.wav", "start": 1.2, "end": 1.5 }: slice from per-key file

Important:

• Slice mode (start/end) currently requires WAV input.
• One-shot sample-map mode replaces note/instrument mapping for that run.

Instrument options

1) Built-in generated instruments

python3 music_keyboard.py --instrument sine
python3 music_keyboard.py --instrument square
python3 music_keyboard.py --instrument triangle
python3 music_keyboard.py --instrument saw

List available instruments:

python3 music_keyboard.py --list-instruments

Interactive selection at startup:

python3 music_keyboard.py --choose-instrument

2) External sound-file instrument (bonus feature)

Provide a folder containing .wav files for every note used in your mapping, for example:

instruments/piano/C4.wav
instruments/piano/D4.wav
...

Run:

python3 music_keyboard.py --instrument instruments/piano

You can also pass --instrument piano if the folder exists at instruments/piano.

Low-latency tips

• Keep --buffer low (default 256 is a good starting point)
• Keep CPU load low when performing
• Use local WAV files if you want instrument-specific tone quality

Example:

python3 music_keyboard.py --buffer 128 --channels 48

Background/global listener notes by OS

• macOS: you must grant Accessibility/Input Monitoring permission to Terminal (or your Python app), or global key capture will not work.
• Linux: global hooks may depend on X11/Wayland setup and permissions.
• Windows: usually works directly, but some environments may require running terminal as administrator.

If install fails on macOS (SDL.h error)

This project uses pygame-ce in requirements.txt because it usually ships prebuilt wheels and avoids local SDL compilation.

If you still see an SDL build error:

1. Use Python 3.11 or 3.12 in your venv.
2. Recreate venv and reinstall:

deactivate
rm -rf .venv
python3.12 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

3. If you must compile locally, install SDL dev libs:

brew install sdl2 sdl2_image sdl2_mixer sdl2_ttf pkg-config

Run without console focus (bonus guidance)

• The app already works while not focused.
• To hide the console window:
  • Windows: launch with pythonw.exe.
  • macOS/Linux: run from a launcher/service manager (launchd/systemd) if you want headless startup behavior.

GitHub push checklist

1. Confirm local audio/sample files are not accidentally tracked.
2. Update project metadata in pyproject.toml (name, author, URLs).
3. Run a quick sanity check:

python3 -m py_compile music_keyboard.py

4. Commit and push:

git add .
git commit -m "Initial project setup: global music keyboard + sample slicing"
git push origin <your-branch>