ableton-live-mcp
CLAUDE.md11 starsChanged 36 days agoMITView on GitHub
Guidance for AI coding agents working in this repository. An MCP server (MCP_Server/, Python 3.10+, MCP Python SDK 2.x MCPServer) that controls Ableton Live through a MIDI Remote Script (AbletonMCP_Remote_Script/__init__.py) running inside Live's embedded Python. They talk JSON over TCP on 127.0.0.1:9877, protocol 2: one JSON object per line each way, requests carry an id the reply echoes, and the first request is hello with the per-launch token Live writes to ~/.ableton-mcp/live-session.json (mode 600). Bare objects without a newline (protocol…
In this repository5 other files it gives its agents.
- ableton-liveSkill
- ableton-setupSkill
- compose-in-liveSkill
- mix-and-masterSkill
- turkish-makamSkill
The file
We split this CLAUDE.md into the rules it gives an agent
11 rules. About 0 are common, 3 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 79
Keep the two copies identical: After editing AbletonMCP_Remote_Script/__init__.py, run cp AbletonMCP_Remote_Script/__init__.py …
- Very specific: line 83
Bump versions together: when the command surface changes: SCRIPT_VERSION in the script and EXPECTED_REMOTE_SCRIPT_VERSION in …
- Very specific: line 101
Stay compatible with Live's Python: no f-strings or Python-3.8+-only syntax in the script.
- Very specific: line 239
Keep the SDK out of runtime imports everywhere but src/extension.ts (tests run the other files on plain Node with type stripping).
- Very specific: line 394
Every new build_tracks option passed and read back: sample_path on a Simpler and on pads, playback_mode, start_marker, choke_group, …
- Very specific: line 459
Every pad's chain plays at C3 (60), built by insert_chain or by the browser.
- Distinctive: line 466
Not verified in Live (check each in a scratch set before claiming it):
- Distinctive: line 500
No writer on purpose: it would be the way around the Trial's disabled saving, and a damaged set is worse than none.
- Distinctive: line 518
Context cost: Every tool's description and schema is sent to the model each session (69 core tools ≈ 15k tokens, down from 22k.
- Very specific: line 547
Prefer composing op_set / op_call / op_display into one batch(...) call over several round-trips.
- Very specific: line 553
Put pure logic in music.py / audio_analysis.py with unit tests.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Guidance for AI coding agents working in this repository.
What this is
An MCP server (MCP_Server/, Python 3.10+, MCP Python SDK 2.x MCPServer) that controls Ableton Live
through a MIDI Remote Script (AbletonMCP_Remote_Script/__init__.py) running
inside Live's embedded Python. They talk JSON over TCP on 127.0.0.1:9877,
protocol 2: one JSON object per line each way, requests carry an id the reply
echoes, and the first request is hello with the per-launch token Live writes
to ~/.ableton-mcp/live-session.json (mode 600). Bare objects without a
newline (protocol 1, older clients) are still parsed, but need the token too.
Forked from ahujasid/ableton-mcp, whose remote is upstream.
Layout
| Path | Role |
AbletonMCP_Remote_Script/__init__.py | The Live-side script. Single file: the installer copies only this file. |
MCP_Server/bundled_ableton_remote_script/AbletonMCP_init.py | Byte-identical copy of the script, shipped in the wheel. |
MCP_Server/server.py | The shared connection and the original tools; registers extended_tools at the bottom. |
MCP_Server/connection.py | AbletonConnection: hello + token, line framing, reply ids, fallback to protocol 1 for scripts before 2.0. |
MCP_Server/extended_tools.py | All newer tools, written in terms of the generic commands (lom_get/set/call, batch, …). |
MCP_Server/tooling.py | register_tool: annotations, profiles (ABLETON_MCP_PROFILE), errors as MCP tool errors with their message, the MCP Apps panel a tool shows. |
MCP_Server/live_updates.py | Pushes ableton://events / ableton://session/overview updates: resources/subscribe (2025-11-25) and subscriptions/listen (2026-07-28). Its long polls use a connection of their own (on the tools' one every command would queue behind them). |
MCP_Server/ui/ | MCP Apps panels (ui:// HTML resources) registered through the SDK's Apps extension. |
MCP_Server/prompts.py | MCP prompts (workflows) and the streaming loudness targets. |
MCP_Server/doctor.py | Setup diagnostics behind the doctor tool and ableton-mcp-doctor. |
MCP_Server/midi_files.py | Standard MIDI File read/write (mido) for clip import/export. |
MCP_Server/companion.py | Client for the Extensions SDK add-on: finds its session file, sends one command. |
extension/ | AbletonMCP Companion, the Extensions SDK add-on (TypeScript): share selection, confirm dialog, pre-FX render. |
MCP_Server/m4l_device.py | Builds the AbletonMCP Analyzer (.amxd) as bytes: the Max patch as JSON. |
MCP_Server/midi_tools.py, MCP_Server/midi_tools/*.js | Max for Live MIDI Tools (Usul, Makam Melody, Makam Snap) for Live 12's Generate/Transform tabs: v8 code in a v8.codebox, tables written from turkish.py/music.py; install_midi_tools. |
MCP_Server/analyzer.py | UDP/OSC listener for the analyzer's messages; levels, bands, correlation, approximate LUFS. |
MCP_Server/ml.py | Runs machine-learning jobs (Demucs, Basic Pitch, CLAP, MusicGen) in uv-built environments; Basic Pitch's presets, octave-ghost removal, bends in cents, velocities from levels, notes placed in beats; the CLAP sound index; generation prompts and folders. |
MCP_Server/ml_worker.py | The job side: runs in those environments, imports nothing from MCP_Server, talks JSON lines. |
MCP_Server/reference_jobs.py | reference-dissector (refdissect) as detached jobs: the pinned commit (REFDISSECT_COMMIT), each step's command, job records in ~/.ableton-mcp/jobs, one job at a time, lost and cancelled jobs, the summaries reference_job gives. |
MCP_Server/reference_runner.py | The job side: run by path (python -I) in its own process group, stdlib only; runs the steps, keeps the record (and the work folder's job.json) up to date. |
MCP_Server/blueprint.py, MCP_Server/schemas/blueprint-v1.schema.json, docs/blueprint-v1.md | The blueprint format build_from_blueprint builds: schema, validator, files to copy (scaled where they peak over full scale), excerpts (bars), the build_tracks spec. |
MCP_Server/als.py | Reads Live Set files (.als) without Live: settings, tracks, devices, clips and notes, samples, comparing and finding sets. Never writes them. |
MCP_Server/device_recipes.py | Ready-made device chains (parameter names as Live 12.3 shows them). |
MCP_Server/memory.py | Notes that outlast a conversation: in the set (Song.set_data, key ableton_mcp_memory) and in ~/.ableton-mcp/memory.json; the memory tool and the overview's memory. |
MCP_Server/snapshots.py | Capture / compare / restore mixer and device parameters (A/B), stored in ~/.ableton-mcp/snapshots. |
MCP_Server/music.py | Pure music theory + generators + note transforms over note dicts. No Live access. |
MCP_Server/turkish.py | Makams (AEU commas, 12-tone approximation, .ascl tunings) and usuls (düm/tek cycles). Pure. |
MCP_Server/audio_analysis.py | numpy/scipy/soundfile analysis (BS.1770 LUFS, spectrum, stereo, tempo, key, each note's level at its pitch). |
MCP_Server/mix_analysis.py | Masking between stems, stem findings, reference comparison with EQ Eight settings. |
MCP_Server/remote_script_install.py | ableton-mcp-install-script; holds EXPECTED_REMOTE_SCRIPT_VERSION. |
MCP_Server/script_handshake.py | Version/capability handshake with the script. |
MCP_Server/fake_live.py | In-memory fake of the LOM (objects carry _live_ptr, listeners, Live 11 note API, enums, an undo history by Live's rules, the recipes' devices, Drum Rack chains, replace_sample, Live's version: 12.4.6). Tests and the simulator use it. |
MCP_Server/transitions.py | Pure Arrangement logic: unrolling split/looped clips, fills, risers, gaps, automation curves. Tools build on it with rewrite_range (extended_tools). |
MCP_Server/simulator.py | ableton-mcp-simulator: the bundled Remote Script over fake_live, served like Live (port + session file); writes the set as JSON and an eval case's verdicts. |
evals/ | claude plugin eval suite: 33 cases against the simulator, graded on checks.json (see evals/README.md). |
packaging/build_mcpb.py, packaging/mcpb/ | Claude Desktop extension: manifest template, icon, build script (fills in version and tools). |
.claude-plugin/, skills/ | Claude Code plugin (MCP server + skills) and its marketplace entry. |
.github/workflows/ | CI (tests, lint, wheel/sdist/.mcpb) and tag-triggered GitHub releases. |
Commands
uv sync
uv run --with pytest pytest -q # whole suite, no Live needed
uv run ableton-mcp-install-script # copy script into Live's User Library
uv run ableton-mcp-install-script --sync-bundle # copy repo script → bundled copy
uv run ableton-mcp # run the MCP server (stdio)
uv run ableton-mcp-doctor # diagnose versions, copies, connection, Live log
uv run ableton-mcp-simulator # a fake Live set to run the server against
claude plugin eval . --scaffold --allow-real-servers \
--allow-tools "mcp__plugin_ableton-live_ableton__*" --ablation none -j 4 # evals/
uvx ruff check . # lint (rules in pyproject.toml)
uv run python packaging/build_mcpb.py # dist/ableton-live-mcp-<version>.mcpb (needs Node.js)
claude plugin validate . # plugin manifest + skills
uv run python -m MCP_Server.blueprint FILE.json # a blueprint's problems (schema, references, files)Rules when changing the Remote Script
- Keep the two copies identical. After editing
AbletonMCP_Remote_Script/__init__.py, runcp AbletonMCP_Remote_Script/__init__.py MCP_Server/bundled_ableton_remote_script/AbletonMCP_init.py(or--sync-bundle). Tests load the bundled copy. - Bump versions together when the command surface changes:
SCRIPT_VERSIONin the script andEXPECTED_REMOTE_SCRIPT_VERSIONinremote_script_install.py; add new commands toSCRIPT_CAPABILITIES(a test checks every handler is advertised). - Register commands in the handler table (
_command_handlers/_lom_command_handlers). Never addif/elifdispatch. - There are no threads. The sockets are non-blocking and polled on Live's
main thread (a
Live.Base.Timerevery 10 ms,update_displayas fallback); a command runs inside that poll, so a handler must never block or wait for Live to change. Waiting belongs to the server (poll again) or to a deferred reply likepoll_eventswithwait. Commands that can take long get a larger timeout inconnection.LONG_RUNNING_COMMANDSon the server.helloand waitingpoll_eventsare handled by the transport (_handle_request) because they act on the connection. - Read-only commands go in
READ_ONLY_COMMANDS, read-only LOM methods inREAD_ONLY_METHODS(methods namedget_*/is_*count too), and a batch of read-only steps is read-only. Everything else runs betweenSong.begin_undo_step()andSong.end_undo_step()(see Undo below). - Stay compatible with Live's Python: no f-strings or Python-3.8+-only
syntax in the script; it must import with
_Frameworkstubbed (tests do this). - Private names are blocked in paths (
lom_check_name); keep it that way. The token keeps other users and web pages out, not other programs running as this user. A connection whose first byte is not{is dropped unanswered (a browser's POST to localhost would otherwise run its JSON body line). - Live loads the script once per launch: changes need a Live restart to take effect.
Live behaviour verified on Live 12.3.5 (don't "fix" these back)
- Undo: Live appends every script change to one open undo step until the
user acts, so one Cmd+Z would revert all agent edits. From a
schedule_messagecallback,end_undo_step()after each command was enough; from aLive.Base.Timercallback (12.3.8) it is not, and onlybegin_undo_step()before plusend_undo_step()after each modifying command keeps one step per command. Parameter changes (volume, tempo, mute) are always a separate step from structural ones (name, color, create), and Live may still merge two changes of the same parameter made within a few hundred ms (like a knob turn) — that is Live, not a bug. - Undo history (12.4, probes with a marker change before each case):
one command (a batch too) leaves one step for its parameter changes
(device parameters, mixer, tempo, mute) and one for everything else
(names, colors, clips, notes, devices, tracks), so a batch mixing both
takes two undos. A value set to what it already was leaves no step, and
neither do transport, the playhead, selection, loop, metronome, arm or
solo.
journal.undo_stepsand the fake's undo (fake_live.FakeSong) follow these rules; verified end to end withagent_changes(undo=1). - Arrangement automation (12.4):
create_automation_envelopeon an Arrangement clip is refused ("Not a session clip"), andautomation_envelopethere returns None even when the clip has one. A Session clip copied withduplicate_clip_to_arrangementkeeps its envelopes, and they play. A copy laid over a clip splits it: both parts keep all the notes and move their start/end markers. An envelope step needs a duration (zero-length steps do nothing). Parameter changes made while the Arrangement records become track automation on any track; the pass leaves an undo step per value set plus one (measured with 2 to 48 values), the first undo removing the automation.transitions.pyandrewrite_rangebuild on these. - Song.set_data/get_data (12.4): strings (any Unicode), numbers, lists and dicts round-trip; no undo step. The Trial cannot save, so keeping the data through save and reopen rests on Ableton's documentation here.
- Value objects outside
Live.*:RoutingTypereports moduleTrackand has no_live_ptr;_lom_valueturns any non-builtin object into a$ref. - Vector types: some lists are Live vector classes, not tuples;
lom_is_sequenceonly excludes objects that have_live_ptr. - Display rounding: parameter displays are rounded, so
param_set_displaypicks the bisection candidate whose display is closest to the target. - Enums: assigning a plain int to an enum property needs conversion through
the enum type (
_enum_member); methods taking enums get{"$enum": ...}. - Live updates have restored an old
AbletonMCPfolder inside the app bundle (…/Contents/App-Resources/MIDI Remote Scripts/), which shadows the User Library copy. - Quitting Live with unsaved changes shows "Changes will be lost. Proceed?"; its buttons ignore Accessibility clicks, Return confirms.
Measured on Live 12.3.8:
- Meters:
output_meter_left/right/levelare linear in dB: dBFS = 76 × meter − 70 (a 0 dBFS sine reads 0.921; 0 → −70 dB, 1 → +6 dB). They show smoothed peaks, and their listeners fire only when the value changes. - Latency: with the socket polled by a 10 ms
Live.Base.Timeron the main thread (script 2.0) a command takes ~10 ms round trip (get_session_overview~20 ms). The old socket-thread design took ~410 ms: Live's Python only lets a background thread run on its ~100 ms tick. Changing the set from the timer callback works. Batching still saves round trips. Live.Base.Timer(callback=..., interval=<ms>, repeat=True).start()exists in Live 12 (Ableton's Move and MxDCore scripts use it).Track.insert_device(name[, index])inserts a native device by its browser name and returns the Device;create_audio_track/create_midi_trackreturn the new Track.- Live 12 calls the master track "Main".
DeviceParameter.display_valueis a bare number in display units; asklom_getfor$displayto get the text ("-6.0 dB").- Glue Compressor's stepped controls display without units (".6", "A" for
Auto);
parse_display_numberaccepts the leading-dot form. - Browser: the roots are Live 12's sidebar labels.
samplesis one flat list (~12,000 items on this machine, walked in ~0.1 s),drumsholds kits andDrum Hits/<Kick, Snare, Hihat, …>(user samples included).BrowserItemhas no_live_ptr;browser_searchregisters results byid(obj)so{"$ref": "id N"}reaches them. Selecting a pad (rack.view.selected_drum_pad) and thenbrowser.load_item(sample)puts the sample on that pad as a Simpler (~100 ms each). - Recording several tracks at once: in one call, only the first audio
track created gets its
available_input_routing_typesfilled; create the tracks in one call and set their inputs in the next (record_sectionretries). A track's input channel "Post Mixer" takes its sound after devices, fader and pan.ClipSlot.fire(length)(positional) on an armed empty slot records a fixed-length Session clip from the next launch boundary; firing a scene and those slots in one batch starts them together. - Deferred state: a playhead moved by
current_song_timeis not in effect until the callback returns —set_or_delete_cue()in the same call toggles a cue at the old position (and would delete a cue there). Move the playhead in one call, toggle in the next (place_locators); the script'screate_locatortoggles on the next update viaschedule_message. - Where playback starts (12.4.2, measured):
continue_playingresumes where Live last stopped, even aftercurrent_song_timewas set (and read back) while stopped;start_playingstarts atSong.start_time, which takes effect inside the same batch.record_sectiontherefore setsstart_timeand callsstart_playing, and putsstart_timeback (it leaves no undo step). Withcontinue_playingevery section was recorded from the last stop position, the requested section somewhere inside the file. - Tunings:
Song.tuning_systemis None until a tuning is loaded, andbrowser.load_itemon an.asclin User Library › Tunings does not load it (12.4) — the user double-clicks it. Live picks up new files there after a few seconds. - Live 12.4 renamed device parameters: "Output Gain"/"Gain"/"Makeup"/
"Master Output" → "Output", EQ Eight "N Resonance A" → "N Q A", and names in
Reverb, Delay, Auto Filter, Echo, Chorus-Ensemble and Roar. Settings go
through
resolve_parameter_names, which maps either version's name onto the device (PARAMETER_RENAMES); recipes keep the 12.3 names. - Sidechain (12.4): Compressor has
input_routing_type(its sidechain source, e.g.available_input_routing_types 'Kick'); Gate has none, so its sidechain cannot be set from a script. - Recordings (
record_section,capture_stems) are written at the audio device's sample rate (48 kHz on the test machine). Read as 44.1 kHz, a 16-beat capture drifted by 9 % (2026-10-18). - Loaded samples stay loaded (12.4): Live keeps playing what it loaded under a file name after the file is overwritten on disk, until it restarts. Overwritten library samples kept their old sound in a set for a day (a capture still held the old sample's second hit). Give changed content a new file name.
- Default levels (12.4): a new Simpler's Volume is −12 dB, Operator's −18 dB;
raising Simpler to 0 dB made recordings clip at 0 dBFS (
capture_stemsnow reportsclipped_samples). - Clip note times count from the clip's start, also for an Arrangement clip placed later in the song.
- Ableton's updater installed Live 12.4 when Live was quit on 2026-10-10; script 2.0 and the timer transport work the same there.
Extensions SDK add-on (extension/, not yet run inside Live)
- Needs Live 12.4.5+ Suite (beta); the Trial cannot load extensions, so it is
checked against the SDK's declarations (every class takes the API version,
Track<"1.0.0">) and, intest/host.test.ts, as a bundle in avmcontext set up like the Extension Host: noglobal, noURL,requirefornode:modules, integers as bigint, errors from another realm. - Keep the SDK out of runtime imports everywhere but
src/extension.ts(tests run the other files on plain Node with type stripping);types/ableton-sdk.d.tsdeclares only what the add-on uses, without default type arguments, so it fails where the real SDK would. - The server side (
companion.py, toolsget_live_selection,confirm_in_live,render_track_audio, the doctor'scompanionline) is tested against a Python stand-in of the protocol.
Max for Live analyzer (built and checked in Live 12.4 Trial, Max 9)
- An unfrozen .amxd is chunks:
ampf+ uint32 4 + type (aaaaaudio effect),meta+ uint32 4 + 4 zero bytes,ptch+ uint32 length + the patcher JSON ending in NUL (as Live's ownMisc/Max Devices/Max Audio Effect.amxd; Ableton's devices are encrypted,ciph).project.amxdtypeis the type as a big-endian int. - Max's
live.pathids are not the Remote Script's LOM ids (the first device reported id 1), so the device sends its track's name, read withlive.object get nameon every message. fffb~'s resonant bands let the bass leak upwards (5–15 dB too much above 1 kHz); a chain ofcross~crossovers at the octave edges matches octave filters within ~1 dB and sums to the full-band power.- Live keeps a loaded device's patch when the file changes: the OSC address
carries a version (
/ableton-mcp/analyzer/2), andinstall_analyzerreplaces a copy that still sends an older one. - The device file is generated, never committed: change
m4l_device.py, bumpVERSION, and check in Live (it must load and send).
MIDI Tools (verified in Live 12.4 with Max 9.1.4, 2026-10-11)
- An .amxd of type
nagg(generator) ornatt(transformation), same chunks as other devices (Live's templates:Misc/Max MIDI Tools). Files in<User Library>/MIDI Tools/Max GeneratorsandMax Transformationsappear under "User:" in the clip view's tool menus;browser.load_itemon one does nothing visible. live.miditool.insends the context from its right outlet, then the notes; the context hasclip.time_selection_start/end(the whole clip when nothing is selected),scaleandseed.v8.codeboxkeeps its code in the patch (code,filename: none) and takes dicts as objects (msg_dictionary,outlet_dictionary).- A transformation gets only the selected notes (after Generate, the new
notes stay selected). Banging
live.miditool.inwhen a control changes after Apply replaces that apply's result in place. - Checked by driving Live's UI: Quartz mouse events work (AppleScript
click atreaches the element but does not press it, and the tool tabs' accessibility elements all report the first tab). Tests run the JS in Node with Max's globals stood in for (tests/test_midi_tools.py).
Machine learning (measured on an M-series Mac, 2026-10-11)
- Each job runs
ml_worker.pythroughuv run --isolated --no-project --python X --with …(ml.ENVIRONMENTS): torch never loads into the server and the memory is gone when the job ends. uv sets$UVfor what it runs, so the server finds it. Progress comes back as JSON lines and goes out as MCP progress notifications. - Basic Pitch 0.4.0 pins TensorFlow < 2.15 on Python 3.11+ (macOS), which no
longer installs: its environment is Python 3.10, where it uses Core ML
(macOS), ONNX (Windows) or TFLite. Its resampy needs
pkg_resources:setuptools<81. - Demucs 4.1 (Hugging Face weights,
apply_model(callback=…)for progress) runs on MPS: a 20 s mix in ~9 s once cached; known stems came back at 14–19 dB SDR (drums, bass, vocals), 10 dB for "other". - CLAP:
laion/larger_clap_musicgives every text the same vector under transformers 5.x (its text pooler loads untrained), so the model islaion/clap-htsat-unfused: P@10 0.72 for text queries over 10 drum classes (chance 0.10), 0.62 sound-to-sound; ~0.06–0.1 s per sound, so indexing stops at 1,500 files per call (INDEX_PER_CALL). - MusicGen small (
facebook/musicgen-small, transformers 5.19, torch 2.14): the first run downloaded ~2.4 GB in ~5 minutes; then a 6 s take needs ~17–19 s in all (start, load, generate), an 8 s loop ~19 s. MPS generates about twice as fast as the CPU (6.3 s against 13.6 s for 5 s). One seed looked broken on MPS (all bass), but across seeds both devices gave the same spectral spread and MPS kept "C major" prompts in C, so it stays the default (the EnCodec decoder gives identical audio on either). transformers 5.x no longer feeds MusicGen'sstreamer; progress comes from aLogitsProcessor, called once per step. Weights CC-BY-NC 4.0. Stable Audio Open (gated, needs a Hugging Face token) is not included. lowest/highestuse Live's note names (A1 = MIDI 45 = 110 Hz) or Hz ("82.4 Hz",music.frequency).- Basic Pitch 0.4.0 (2026-10-19):
predict()'s note events always carry bends (thirds of a semitone per 11.6 ms frame);multiple_pitch_bendsonly shapes its MIDI object. They read one bin sharp: in-tune sines at 110–880 Hz gave +1 in 99.4–100 % of frames, soml.bend_centssubtracts one. Without melodia a note needs an attack: onset 0.6 found 3 of 16 pure sines with a 10 ms fade-in (chords and legacy 15 and 14) and 2 notes on six 808 stems of 56 notes each. The melodic preset therefore decodes the model's output twice (ml_worker.melodia_ranges): melodia off from MIDI 52 up, on below, thenml.drop_octave_ghosts.constrain_frequencyzeroes the arrays in place, so each decoding gets a copy. Notes at 29–52 Hz start a median 109 ms late (IQR 48–187 ms). At those notes' pitch the onset head read a median 0.29 at the true onset and peaked at 0.37, 81 ms later; 0.3 % of the 336 notes reached 0.6 and 7 % 0.5, and onset thresholds from 0.2 to 0.6 all gave F1 ≤ 0.17 on those stems. - Tests mock
ml.run(and test the protocol with the worker'sechotask);ABLETON_MCP_ML_TESTS=1adds two runs with the real Basic Pitch model (an A4 and its bends; a driven 808 line the default preset must find).
Replica mode: Simpler and Drum Rack pads, measured in Live 12.4.6
Measured in Live 12.4.6 (Trial) on 2026-10-19 with Remote Script 2.1.0 and
this branch's build_tracks: values read back, and capture_stems
recordings at the audio device's 48 kHz.
SimplerDevice.replace_sample(path)loads a file into a Simpler just inserted withinsert_device(no sample yet): it returns None within ~13 ms andsample file_pathreads back the exact path (build_trackswaits up to 2 s for it, then falls back to the browser). Unlike the browser, it reads the file again: after the file is overwritten on disk,replace_samplewith the same path, or a new Simpler on it, plays the new content, while a pad loaded through the browser by the same name still plays the old one (see "Loaded samples stay loaded" above).- Drum Rack pads without the browser:
RackDevice.insert_chain()returns the new DrumChain (build_tracksfinds new chains by comparing the rack's chain ids instead), which starts onin_note36 without_note60, not on −1 (All Notes) as infake_live;build_trackssetsin_noteeither way.Chain.insert_device("Simpler")andreplace_samplethen load the pad, and the chain takes the file's name;DrumPad.delete_all_chains()ran on a pad whose file Live refused before the browser loaded it. Two chains on one note both sound (the pad reads "Multi"). - Defaults differ by route: a Simpler made with
insert_device(a track's, or a pad's built by path) is Classic, with its filter on and "Vol < Vel" 35 %; a pad loaded through the browser is One-Shot, with the filter off and 45 %. Both start at Volume −12 dB.playback_modeset as 0 or 1 (classic, one_shot) reads back. Sample.start_markercounts sample frames of the file: 441 and 4410 moved a 44.1 kHz file's onset by 10.000 and 100.000 ms ("S Start" still showed 0.00 %).- Transpose (±48) keeps whole semitones: a fraction is truncated toward
zero (11.99 → 11, −11.99 → −11), so 11.99 plays 1100 cents up. Detune
keeps whole cents from −50 to +50: a number is truncated (11.5 → 11,
49.9 → 49; 60 is refused), while display text goes to the nearest value
(
"11.5 ct"→ +12). Played pitches follow the stored values within 0.002 cents. - Velocity sets a Simpler's level: dB = 0.4 × A × (velocity − 70) − 0.096 over its Volume, A being "Vol < Vel" as a fraction (within 0.002 dB over 6 amounts × 18 velocities; fractional velocities follow it too). So velocity 70 plays at the Volume (less 0.096 dB) whatever the amount, and velocity 127 adds 7.9 dB at 35 %, 10.2 dB at 45 %. Volume set by the display "0.0 dB" lands on −0.005 dB.
- A choke group cuts the sounding pad with a linear 1 ms fade from the new hit's onset. Groups 0 (none) to 16 are accepted; 17, 99 and −1 are refused ("Invalid choke group.").
- Simpler's "Snap" (on by default) stops a sample 10–30 ms before its end with a short fade, the same on every hit (a kick 28.8 of its 163.5 ms, a hat 9.9 of 71.4); with Snap off it plays to the last frame.
- Glide, with one voice and overlapping notes, slides linearly in semitones over exactly the Glide Time (29.95, 59.95, 119.5 and 249.5 ms for 30, 60, 120 and 250 ms) for intervals of 2, 5, 7 and 12 semitones alike, without restarting the sample; notes 25 ms apart jump (in Portamento too).
- Timing: a note starts on the first device sample at or after its time and sounds 0.469 samples later (the default filter's group delay), the same in three passes; a recording adds no offset of its own (an Arrangement click lands 0.016 samples from its beat). The drum hits of a 5-track build landed within 0.04 ms of their times (mean +0.017 ms).
- Every new
build_tracksoption passed and read back:sample_pathon a Simpler and on pads,playback_mode,start_marker,choke_group,warping: false,"Detune": "-12 ct"insettings,signature("7/8"), the browser fallback for a file Live refuses (a Simpler'sloaded_by_namecarries Live's message, a pad's says "the Simpler holds no sample"), and the refusals before anything is built (a relative or missing path, choke group 17, playback mode "loop", a negative start marker, 7/9; no track was created). The 5-track build (an 808 Simpler and Drum Rack pads, by path) took 7.7 s with no fallback. The version check (Application.get_major/minor/bugfix_version()) let path loading run.
Measured again on 2026-10-29 (Live 12.4.6 Trial, 48 kHz device) in
reference-dissector's two live checks, which built 8 plans and a song with
2.2.0's build_tracks (pads through the browser, so One-Shot; the 808 a
Simpler made with insert_device, so Classic) and recorded each pad and
the 808 with capture_stems:
- One-Shot pads hit again cut the sounding hit with a straight-line fade over 1 ms and start the new one 1.000 ms late (median of 391 hits on 18 pads; 98 % within 0.95–1.05 ms). A hit that comes after the file (or Snap) has ended starts on time.
- The Classic 808 Simpler releases over its default Ve Release of 50 ms: −1.683 dB a millisecond, −40 dB 23.8 ms after the note's end, silent (−60 dB) at 35.7 ms. A note after one of its own pitch restarts the voice 0.94–1.05 ms late. Its filter (on, 22 kHz) delays each note by 0.13–0.46 ms, more for lower notes, and cuts upper harmonics.
- Simpler loses top end against the file it plays: about −0.14, −0.32 and −0.9 to −2.5 dB at 4–8, 8–12 and 12–20 kHz for a 48 kHz file at Transpose 0; 44.1 kHz files lose more (−1.6 to −1.8 dB at 12–16 kHz, −3.1 to −3.7 dB at 16–18 kHz).
- Volume by display text is held a display step low: "-6.6 dB" reads back −6.605 dB, "-14.9 dB" −14.95 dB; hits play the held value within 0.003 dB.
- By file name, the browser's first hit is what loads: a name two files
shared put an 808 on an open-hat pad, and a name the browser never listed
("3 .wav") made
build_tracksraise after its 40 s wait, leaving the tracks already made in the set.sample_pathdoes not go through the browser. - Cues land on the Arrangement's grid, which depends on its zoom:
set_or_delete_cueat beats 9, 21 and 33 made cues at 8, 20 and 32 in 4/4 and at 12, 24 and 36 in 3/4 at the default zoom, andplace_locatorsreported them as failed; after fourzoom_viewsteps in, beat 9 was placed exactly. - Eight clients at most. The script serves
MAX_CLIENTS(8) connections; a ninth is closed at once ("Refusing a connection" in Live's log), which the client sees as "Connection reset by peer". Each MCP server holds one, so eight sessions with the plugin fill it.
Measured on 2026-11-14 (Live 12.4.6 Trial, 48 kHz device) by
reference-dissector's live-build, which builds a plan through
build_from_blueprint (Simplers by path), against its live-build
--direct (pads through the browser), each recorded with capture_stems:
- An 8-bar excerpt (8 tracks, 133 notes, 4.4 s) and PIRAMIT's whole plan
(10 tracks, 1,881 notes in one
build_trackscall, 7.1 s;--direct7.6 s) built with clean read-backs: every Simpler held its file (4 and 11), 13 of 13 pad Volumes held as numbers (none needed the text), every locator placed, 4/4 read back. - A Simpler made with
insert_devicestarts with a 0.1 ms Fade In; a pad the browser loads starts at 0 (Fade Out 0.1 ms on both). It was the only audible difference between the two builds: 4 samples at 48 kHz at each kick and hat onset (the drum track's residual −68.4 dB). With "Fade In" set to 0 (refdissect's blueprints do) every track of both plans recorded equal to--direct's sample for sample. - Every pad's chain plays at C3 (60), built by
insert_chainor by the browser. A pad made by path differs from the browser's in what a One-Shot pad with no modulation does not play (voices 6 against 3; LFO and pitch envelope on with no amount; envelope times). - The Remote Script served 4 clients; the build's connection was not refused.
Not verified in Live (check each in a scratch set before claiming it):
- The rack rebuilt by name when
insert_chain,in_noteorChain.insert_devicefails (the rack is deleted withTrack.delete_deviceand a new one gets every pad from the browser: no call deletes a single rack chain). Live 12.4.6 refused none of them, so onlyfake_livehas seen it. - Samples on Live before 12.4 (the browser, by file name).
playback_modeslicing (2), and one_shot set byplayback_modeon a pad built by path (overlapping hits were measured on One-Shot pads loaded through the browser, above).audio_to_midion a warped clip:Clip.sample_to_beat_time(frames)minusstart_marker(beats) as the note's beat in the new clip; on an unwarped clipstart_markerin seconds;Clip.sample_rate, else the file's rate.- A 44.1 kHz audio device: every recording ran at 48 kHz.
Live Set files (.als), as read from Live 12.4's own sets
- gzip-compressed XML; parsing drops automation and modulation subtrees as it goes (a 27 MB set takes ~80 MB instead of ~215 MB, ~0.4 s).
- Device elements are named by
Device.class_name(Eq8, StereoGain …);als.DEVICE_NAMESwas read from Live 12.4 by inserting each native device. Max for Live devices areMxDevice*named by their.amxdfile; plug-ins arePluginDevicewithPluginDesc/Vst3PluginInfo(or VST2, AU). - Time signature:
(numerator - 1) + 99 * log2(denominator)(201 = 4/4). ScaleInformation: root 0 = C and the scale as an index (0 Major, 1 Minor checked against the demo set's notes; the rest in Live/Push order). - A clip plays
Loop/LoopStart..LoopEndwhether the loop is on or off (with it off they are the start and end markers); arrangement clips sit atCurrentStart..CurrentEnd. Drum pad note = 128 −ReceivingNote. - Sample paths:
RelativePathType1 = project folder, 5 = a Live Pack (LivePackName, e.g. the Core Library in the app bundle), 6 = Library, 7 = Live's Builtin folder;Pathis absolute on the machine that saved it. - No writer on purpose: it would be the way around the Trial's disabled saving, and a damaged set is worse than none.
Server-side conventions
- New tools go in
extended_tools.register()with the local@tooldecorator;@tool(read_only=True),@tool(destructive=True)(deletes or replaces content) or@tool(idempotent=True)set the MCP annotations,ui="ui://…"the panel. Registration goes throughtooling.register_tool: sync tools run on the SDK's worker threads, and any exception becomes aToolErrorcarrying its message (mcp 2.x would otherwise show only "Error executing tool …"), so raise on failure instead of returning error text. Longasynctools takectx: Context | None = Noneand callreport_progress(ctx, …). - mcp 2.x:
from mcp.server.mcpserver import MCPServer, Context; types use snake_case attributes (input_schema,read_only_hint);call_tool()returns aCallToolResult. Clients negotiate 2025-11-25 (mode="legacy") or 2026-07-28; push updates and tests cover both. The original tools inserver.pyuse@legacy_tool("core" | "full"); "full" ones only appear withABLETON_MCP_PROFILE=full. - Context cost. Every tool's description and schema is sent to the model
each session (69 core tools ≈ 15k tokens, down from 22k; with Phase 4's
tools 76 ≈ 16.7k, measured 2026-10-11; the four reference tools add
3,123 characters, ≈ 0.8k tokens, to the full profile only), and every
result on every call.
So:
register_toolstrips pydantic titles,"default": nulland nullableanyOffrom the advertised schema (compact_schema; validation still uses the signature);to_jsonwrites compact JSON; notes go out as rows undernote_columns(note_table, ~80% smaller than objects). Keep docstrings to what the model needs to call the tool right; tools a newer one replaces belong in thefullprofile. - Safety net.
journal.pygives each tool call an entry (a contextvar set inregister_tool);AbletonConnection.send_commandreports every command with its result, andjournal.undo_stepscounts the steps Live recorded by the rules under "Undo history" below (journal.is_read_onlymirrors the script's READ_ONLY_COMMANDS/METHODS; a test keeps them equal), soagent_changes(undo=N)undoes exactly the last N calls. Parameter tools callauto_snapshotfirst (the last 10 are kept; tests write them to a temp folder via conftest).@tool(..., preview=True)+ apreviewparameter:PREVIEWmakesprepare_clip/write_notesno-ops andsendrefuse any change. Deletes takego_ahead: Annotated[ElicitationResult[_Confirm], Resolve(ask_…)]: the SDK runs the module-level resolver first and asks through elicitation in either protocol era (2026-07-28 has no back-channel, soctx.elicitinside a tool fails there); resolvers must be module-level, because the SDK resolves the annotation strings withget_type_hintsand silently drops unresolvable ones. A plain resolver return reaches the tool wrapped asAcceptedElicitation(data=…). - Generators read the set's meter and Key & Scale through
song_context()/resolve_key(); explicit arguments win. - Prefer composing
op_set/op_call/op_displayinto onebatch(...)call over several round-trips; returnbatch_summary(...). - Address tracks with
track_path()(index, name,master,return A), devices withdevice_path(), clips withclip_path(); quote names viaselector(). - Tools that wait (recording, long-polling) are
asyncand useasend()so they don't block the event loop. - Put pure logic in
music.py/audio_analysis.pywith unit tests; keep tools thin.
Panels (MCP Apps)
- A panel is one self-contained HTML document (
ui/panels.py, shared bridge and theme inui/base.py): no external URLs, noinnerHTML(names come from the user's set), host theme variables with light/dark fallbacks. It speaks the ext-apps protocol by hand:ui/initialize(protocol2026-01-26) →ui/notifications/initialized, thentool-input/tool-result; buttons call tools withtools/callonly when the host offersserverTools, otherwise they are disabled. - Wire a tool with
@tool(..., ui=ui.<PANEL>); its text result must stay complete for clients without Apps.tests/test_ui.pychecks serving, wiring and (with node) that every panel's script parses; check the look in a real or mock host (headless Chrome) after changing a panel.
Reference jobs and blueprints (build_from_blueprint checked in Live; the jobs not yet run with real refdissect)
- refdissect runs as
uv run --isolated --no-project --python 3.12 --with "reference-dissector @ <archive of REFDISSECT_COMMIT>" refdissect …(reference_jobs.refdissect_command), never imported: its memory (2 GB for an analysis), its Python (3.11+) and its pins (torch for Demucs) stay out of the server. Move the pin by changingREFDISSECT_COMMITto a commit of reference-dissector's main;ABLETON_MCP_REFDISSECT=<checkout>runs a local checkout instead anddoctornames which one is used. - A job's steps are refdissect's own commands (separate, analyze, melodic,
match, fit-808, plan, blueprint; inventory and index-library for the
library). A missing subcommand (argparse's "invalid choice") skips an
optional step instead of failing the job:
blueprintexists only in a refdissect that writes this format. - Records are written atomically and by one process at a time: the server
before the runner starts and after it is gone (cancel), the runner in
between. "lost" is never written; it is read from a running record whose
runner is gone or that has not been written for
STALE_S. The runner leads a session of its own, so its pid names the job's process group even after it dies (killpg(pid));is_runnerchecks the pid's command line (ps), so a pid another process took is never signalled (Unix gives no process the id of a living group, so leftovers cannot hide behind one). build_from_blueprintruns inside the server on its connection (no ninth client), callsbuild_tracksonce, then reads back. Its steps follow refdissect'slive-build --directas measured in Live 12.4.6 (meter before locators, Volume as a number then as text, choke groups on the chain,voicesafter the build). Checked in Live 12.4.6 on 2026-11-14 through refdissect'slive-build(below, under replica mode).- refdissect's
live-build(its[live]extra) importsMCP_Server.serverafter settingABLETON_MCP_PROFILE=full, calls the tool in-process (mcp.call_tool("build_from_blueprint", {"blueprint": <file>, "bars": "A-B"})), callsblueprint.excerpt(data, (a, b), base, out_dir)directly for--stems-out, and reads the report's keys (tracks,problems,locators,locators_movedwithname/asked/live/deleted,checks.samples|volumes|choke_groups|voices|time_signaturewithwant/live/same,volumes.held_by_text/not_held,files,excerpt,ok). These are an interface: change one only with refdissect, and say so in the CHANGELOG. - The jobs themselves (
dissect_reference,index_sound_library,reference_job) have not yet run refdissect for real (uv, the pinned archive, Demucs and the models); only the stand-in below. Paths go to refdissect absolute (its steps run in the work or library folder). - A rerun
planbringsblueprintalong; a blueprint file whosemeta.plan_sha1no longer matches itsplan.jsonis refused (blueprint.plan_changed). - libsndfile writes the time into a float WAV's PEAK chunk: two writes of
the same samples a second apart differ in bytes. Scaled copies and cut
stems are therefore compared and named by their audio
(
blueprint.audio_digest), never by the file's SHA-1. - A process group whose only member is its unreaped zombie leader still
answers
killpg(pgid, 0)(Linux) or refuses it with EPERM (macOS);group_aliveaskspsfor a member that is not a zombie. - Tests stand a script in for refdissect (
tests/test_reference_jobs.py: real processes, no uv, no models); conftest points the jobs and data folders at temporary ones. The eval case needsABLETON_MCP_PROFILE=full.
Packaging and releases
- One version, three places:
pyproject.toml,.claude-plugin/plugin.jsonand the plugin entry in.claude-plugin/marketplace.json(a test checks they agree). The.mcpbmanifest takes it from pyproject at build time. - The
.mcpbis a "uv" bundle: source,pyproject.tomlanduv.lock, which Claude Desktop installs with uv. The wheel's packages come frompackages.find(MCP_Server*), so new subpackages ship by themselves. - Skills name tools as
`tool_name(...)`; a test fails when a skill names a tool that no longer exists.claude plugin validate .warns that CLAUDE.md at the plugin root is not plugin context: expected, it is for this repo. - A
v<version>tag publishes a GitHub release (wheel, sdist, .mcpb). Nothing goes to PyPI:ableton-live-mcpis taken there.
Testing
tests/test_lom_bridge.pydrives the script's handlers directly and, in thelive_serverfixture, runs the real TCP server + real MCP tools againstfake_live.FakeSong. ExtendMCP_Server/fake_live.pywhen a tool touches new LOM surface; its undo followsjournal.py's rules, so keep both in step with what Live does.tests/test_evals.pyruns a scripted correct solution of every eval case through the real server's tools against the simulator; a new case needs one inSOLUTIONS. The server takes Live's port from the session file (connection.live_port), which is how eval runs find their simulator.- Give tools in a test a fake connection (
extended_tools.register(mcp, lambda: conn)) or one that raises. The server's own connection reads~/.ableton-mcp/live-session.json, else port 9877, and so reaches a Live open on the machine;test_evals.pyandtest_arrangement_tools.pyuse it only after pointingABLETON_MCP_SESSION_FILEat their simulator. - Anything that depends on real Live behaviour (undo, routing objects, recording) must also be checked against a running Live before claiming it works.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

