pianoterm

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 42 Open GitHub ↗

Linux CLI tool to assign shell commands to keys on a USB MIDI Keyboard

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# pianoterm

Run shell commands from your piano

## Description

Linux CLI tool to assign shell commands to keys or knobs on a USB MIDI Keyboard/Controller

## Usage

```bash
# options:
# find by alsa client name. (e.g. pianoterm -n "Digital Piano")
# specify config path. (e.g. pianoterm -p 22 -c ~/path/to/config)
# find by alsa client id. (e.g. pianoterm -p 22)

pianoterm [-p|-n] <port | name> [-c] <config_path>
```

Note: 
- Run 'acconect -i' to find the alsa client name/port

## Configuration

- default path: ~/.config/pianoterm/config

### Example Config

```conf
## Control audio playback
on_press
21 = playerctl previous # first key on an 88-key keyboard
22 = playerctl play-pause
23 = playerctl next

## Map directly to keyboard keys (Wayland)
on_press
107 = ydotool key 108:1
108 = ydotool key 103:1
on_release
107 = ydotool key 108:0
108 = ydotool key 103:0

## Run custom scripts
69 = /home/me/my_script.sh

## Assign multiple commands to run sequentially on the same key press
60 = notify-send "command 1"
60 = notify-send "command 2"

## Map controller events (pedal presses, knob switches, ...)
64 (127) = notify-send "Pressed pedal" # 127 in this case is the max pedal output
64 (0)   = notify-send "Released pedal"
```

### Syntax Explanation

- Keys and buttons:
```conf
# Default - on_press
[on_press|on_release|on_hold]

key = command
```

- Controllers (pedals, knobs, etc.):
```conf
# Must include a trigger value
# A trigger is numeric value greater than 0. (usually the pressure on a pedal, the volume on a knob, etc.)

key (trigger) = command
```

Notes:
- A different key and controller can share the same key.
- You can use aseqdump -p <port> to find keycodes and controller values.

## Building

```bash
git clone https://github.com/vustagc/pianoterm.git
cd pianoterm && make
```

## Playing Supertux on the Piano

https://github.com/user-attachments/assets/718a9328-6b70-4cfa-97d6-e355dd0e5b6a

pianoterm

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README