Architecture
To catch keyboard shortcuts Protocol 0 needs to run both outside and inside Live. So it's built on both a background agent process, and a remote script running inside Ableton. They talk over local HTTP.
The two surfaces
The agent
A single standalone process, registered to autostart at logon. It owns the global keyboard hook and serves the keymapper web UI at 127.0.0.1:9010. The keymapper unlocks once Ableton is running with the remote script active.
The remote script
Runs inside Live as a MIDI Remote Script and exposes a REST action API. It executes actions through the Live API (LOM) on the Live thread.
Why not an Ableton extension
Ableton extensions are really cool. But they have, at the moment, two limitations:
- they cannot process midi (and midi mapping is on the roadmap)
- they can only load stock devices (and I think loading plugins is useful)
What the detector does with a keypress
When Ableton is the foreground window, the agent's keyboard hook resolves the pressed combo against shortcuts.json and the matched binding decides what happens. There are two kinds of binding:
- A smart action — the binding points at a named action (e.g. load a device by name). The detector calls the script's REST action API, which runs it through the Live API.
- A plain remap — the binding maps one key (or combo) to another, so the detector simply re-emits a keyboard event (e.g.
Caps Lock → Esc). Live just sees the substituted key.
Both routes end up in Ableton, but they get there differently: a remap lands as a normal keyboard shortcut (Live can't tell it apart from a real keypress), while a smart action drives Live through internal remote scripting — the only path that crosses the HTTP boundary.
The keyboard hook can't live inside the script — Ableton's embedded Python is a restricted runtime that can't host a global hook. That single constraint is why detection lives in the agent and only smart-action calls cross the HTTP boundary into Live.
Packaging & platform
An installer deploys both surfaces in one step: it installs the agent executable, copies the remote script into Ableton's MIDI Remote Scripts folder, and adds a Startup-folder shortcut so the agent autostarts at logon (visible and removable from Task Manager → Startup). Protocol 0 is Windows-first today — the installer, autostart, and PyInstaller packaging are Windows-specific — but the architecture itself (HTTP boundary, global config, agent/script split) is portable. macOS support would replace the packaging and autostart layer, not the core design.
The full rationale and durable design intent live in CONSTITUTION.md.