PedalCombinationToShot

Tap two piano pedals at once to take a screenshot, like pressing power + volume on a phone.

It listens to a MIDI piano (or any MIDI keyboard with pedals) and takes a screenshot when your chosen pedals are pressed together.

Works on Windows, macOS and Linux.

Install & run (uv)

uv sync
uv run PedalCombinationToShot --list-ports      # find your piano
uv run PedalCombinationToShot                   # sustain + soft -> screenshot

Or install it as a global command:

uv tool install .
PedalCombinationToShot --help

Options

Option	What it does
-l, --list-ports	List MIDI input ports and exit
-p, --port PORT	MIDI input: index, exact name, or part of the name (default: first real port)
-P, --pedals PEDAL...	Pedals in the combo: names or CC numbers, e.g. sustain soft or 64,66,67 (default: sustain soft)
-c, --command CMD	Custom screenshot command (see below). Default: built-in per-OS method
-o, --output-dir DIR	Where built-in screenshots are saved (default ~/Pictures/PedalCombinationToShot)
--prefix TEXT	Filename prefix (default pedal-shot)
-w, --window MS	All pedals must be pressed within this time (default 500)
--cooldown MS	Minimum time between screenshots (default 1000)
-t, --threshold 0-127	CC value that counts as "pressed" (default 64)
--channel 1-16	Only listen to one MIDI channel
-m, --monitor	Print incoming pedal messages, take no screenshots
-n, --dry-run	Detect the combo but don't screenshot
--beep	Ring the terminal bell on trigger
--list-pedals	List known pedal names

Pedal names: sustain (CC64), portamento (65), sostenuto (66), soft (67), legato (68), hold2 (69). Aliases: damper/right, middle, una-corda/left.

Not sure which CC your pedals send? Run --monitor and press them.

Custom screenshot command

--command runs through your shell. Use these placeholders (already shell-quoted):

• {file} - full path of the PNG to write
• {dir} - the output directory

# Flameshot
PedalCombinationToShot --command "flameshot full -p {dir}"
# macOS interactive selection
PedalCombinationToShot --command "screencapture -i {file}"
# Linux, region select
PedalCombinationToShot --command "maim -s {file}"
# Windows: Snipping Tool shortcut via PowerShell
PedalCombinationToShot --command "powershell -c \"Start-Process ms-screenclip:\""

If the command doesn't contain {file}, it's simply run as-is (good for tools that manage their own files).

Default screenshot methods

OS	Method
Windows	mss (pure Python)
macOS	screencapture
Linux (X11)	mss, then gnome-screenshot / spectacle / maim / scrot / import
Linux (Wayland)	grim / gnome-screenshot / spectacle, then mss as a last resort

Platform notes

• macOS: grant your terminal Screen Recording permission (System Settings > Privacy & Security), otherwise screenshots may show only the wallpaper.
• Linux: if python-rtmidi has to build from source you need libasound2-dev and libjack-dev. On Wayland, install grim (wlroots) or use gnome-screenshot / spectacle.
• Windows: some MIDI drivers only allow one app to open the port at a time. Close your DAW first.

Development

uv run pytest

Layout:

src/pedal_combination_to_shot/
  cli.py         argparse + main loop
  detector.py    pedal-combo detection logic
  midi.py        MIDI port helpers
  pedals.py      pedal names <-> CC numbers
  screenshot.py  cross-platform screenshots