# messier-live

Agent-driven live sets in Ableton Live. An MCP server that gives an AI a real
DJ rig: two decks over Session View, a beat clock it can actually hear,
performance FX macros, and a crate that knows every track's BPM and key.

Spun out of [KOTOPIA9X/kaios](https://github.com/KOTOPIA9X/kaios)'s
`kaios_music`, stripped to the live-performance core.

## Architecture

```
Claude / any MCP client
        │ MCP (stdio)
messier-live server (Python)
        │ TCP :9877 (commands)          UDP :9878 (telemetry, 10 Hz)
        ▼                                ▲
MessierLive Remote Script ── inside Ableton Live
```

Telemetry is the point: the Remote Script pushes transport, bar/beat, playing
clips, and levels ten times a second, so the agent fires clips on the downbeat,
crossfades in bars instead of seconds — and the same stream later feeds a
website visualizer.

## Install

```bash
# 1. the server
pip install -e ".[analysis]"

# 2. the remote script
cp -r remote_script/MessierLive "~/Music/Ableton/User Library/Remote Scripts/"
# Ableton > Settings > Link/MIDI > Control Surface: MessierLive

# 3. register with Claude Code
claude mcp add messier-live -- messier-live
```

## Prepare a set

```bash
# analyze your tracks (BPM, key -> Camelot, energy) into ~/.messier-live/crate.json
python -m messier_live.crate.analyze ~/Music/dj-crate
```

Build the Live set template — two deck tracks with an EQ Three and a `PERF`
FX rack each ([templates/README.md](templates/README.md)).

## Tools

| Layer | Tools |
|---|---|
| session | `diagnose`, `live_status`, `get_session_info`, `play`, `stop`, `set_tempo`, `save_project` |
| decks | `setup_decks`, `deck_status`, `load_to_deck`, `fire_deck` (bar-quantized), `stop_deck`, `set_deck_volume`, `crossfade`, `eq_kill` |
| fx | `set_fx_macro`, `fx_sweep`, `fx_pulse`, `kill_all_fx`, `list_deck_devices`, `get_device_parameters`, `set_device_parameter` |
| crate | `crate_list`, `suggest_next_track` (BPM ±8% + Camelot + energy), `prepare_deck` |

A set, from the agent's side:

```
diagnose() → deck_status()
suggest_next_track(bpm=140, camelot="7A", energy_direction="up")
prepare_deck("B", "<file>", match_tempo=False)
crossfade(to_deck="B", bars=8)
fx_pulse("A", "Glitch", bars=1)   # on the way out
eq_kill("B", "low"); eq_kill("B", "low", restore=True)  # drop trick
```

See **[USAGE.md](USAGE.md)** for the full manual: set prep, tagging,
running sets, and the human/agent collaboration contract (touch detection,
16-bar ownership, modes).

## Collaboration layer

Telemetry v2 reports every shared control (macros, EQ, faders, clips) at
10 Hz. The agent journals its own writes; unexplained drift = a human hand.
Touched controls become human-owned (16 bars for FX/EQ/faders, until-stop
for clips), all agent tools yield on them, and a fired clip re-routes the
set plan through the human's choice. Modes: `solo` / `copilot` / `crew`.

## Roadmap

- [ ] WebSocket relay: rebroadcast telemetry + agent narration for a live website visualizer
- [ ] Serum2 track: agent-composed stabs/risers between tracks
- [ ] Preset hotswap (`load_preset` by name via browser API)
- [ ] Recorded set replay logs (for the visualizer's offline mode)
- [ ] Global set optimizer (current planner is greedy with lookahead-0)