KaraPad

App-aware macros for the CH57x 3-key + knob macro pad on macOS.

The pad has no idea which app is in front of you — its firmware just sends fixed keystrokes. KaraPad fixes that: flash the pad once with neutral trigger codes (F13–F18), then let Karabiner-Elements translate each trigger into the right shortcut for whatever app is frontmost.

Companion to MacroPad Studio — it is included here as a git submodule and is the single source of truth for the 394 presets. KaraPad does not modify it.

---

How it works

            ┌─────────┐   F13/.../F18    ┌────────────────────┐   real shortcut
  you press │  pad    │ ───────────────▶ │ Karabiner-Elements │ ─────────────▶  active app
            └─────────┘   (neutral)      │  + frontmost app   │
                                         └────────────────────┘

The same physical key sends F13 always. Karabiner looks at the frontmost app and rewrites F13 into, say, new layer in Photoshop, razor in Premiere, or copy in Finder — instantly, with no re-flashing and no sudo at runtime.

See docs/HOWITWORKS.md for the full model and limitations.

---

Quickstart

# 0. clone with the submodule
git clone --recurse-submodules https://github.com/fabiodalez-dev/KaraPad.git
cd KaraPad

# 1. one-time: flash the neutral triggers into the pad
python3 -m karapad.cli flash          # asks for your password (raw USB)

# 2. edit config/app-map.yaml — assign a preset to each app you care about
python3 -m karapad.cli bundle-id      # helper: prints bundle ids of open apps

# 3. generate the Karabiner rules and install them
python3 -m karapad.cli generate
python3 -m karapad.cli install

# 4. enable in Karabiner-Elements:
#    Complex Modifications -> Add rule -> enable "KaraPad"

Check everything with python3 -m karapad.cli doctor.

Requirements: Karabiner-Elements (brew install --cask karabiner-elements), ch57x-keyboard-tool (cargo install ch57x-keyboard-tool), Python 3 with pyyaml. Karabiner needs Input Monitoring permission (one-time, in System Settings → Privacy & Security).

---

Configuration

config/app-map.yaml assigns a MacroPad Studio preset to each app:

apps:
  - name: Photoshop
    bundle_id: "^com\\.adobe\\.Photoshop"
    preset: photo/photoshop-layers
  - name: DaVinci Resolve
    bundle_id: "com\\.blackmagic-design\\.DaVinciResolve"
    preset: video/davinci-edit
default:
  preset: utility/copy-paste-undo

preset is a path under vendor/MacroPadStudio/presets/ without .yaml. bundle_id is a regex (optional — falls back to data/bundle-ids.yaml).

---

CLI

Command	What it does
karapad flash	Upload the neutral F13–F18 trigger preset to the pad (once)
karapad generate	Build output/karapad.json from the app map + presets
karapad install	Copy the rules into Karabiner and back up any previous version
karapad bundle-id	List bundle ids of currently running apps
karapad doctor	Verify tool, Karabiner, submodule and output

---

Limitations

• Millisecond delays (<100>) inside preset sequences are dropped — Karabiner has no inline per-step delay. Sequences still fire, just back-to-back.
• The knob must be set to send F16/F17/F18 (done by the trigger preset), not volume.
• Versioned apps (Adobe) are matched by bundle-id prefix regex.

---

License

MIT — see LICENSE. Author: Fabio Dal Ez.

Built on ch57x-keyboard-tool and Karabiner-Elements.