Get detailed information about the current Ableton session (tempo, time signature, track/return/scene counts, master mixer).

Get detailed info about a track: name, mute/solo/arm, volume/pan, clip slots, and the ordered list of devices (with their indices).

Pass track='master' or track='return:0' to inspect the master bus or a
return track (those have no clip slots).

Create a new MIDI track. index=-1 appends at the end. Re-read get_session_info afterwards to learn the real new index.

Set the name of a track.

Create a new empty MIDI clip. length is in BEATS (not bars).

Add MIDI notes to a clip (additive — call repeatedly to build large clips).

Each note dict: pitch (0-127), start_time (beats), duration (beats),
velocity (1-127), mute (bool, optional).

Set the name of a clip.

Set the session tempo in BPM.

Load an instrument or effect device onto a track by its browser URI.

Discover URIs with get_browser_tree / get_browser_items_at_path. After
loading, use get_device_parameters + set_device_parameter to dial it in.
Pass track='master' or track='return:0' to load onto the master bus or a
return track (e.g. a Reverb on a return, or the master-bus chain).

Load a Drum Rack, then load the first loadable kit found at kit_path.

Start playing a clip (launches the clip slot).

Stop a playing clip slot.

Start the session transport.

Stop the session transport.

Get the top-level browser categories ('all', 'instruments', 'sounds', 'drums', 'audio_effects', 'midi_effects'). Use get_browser_items_at_path to drill in and find loadable URIs.

List browser items at a path like 'instruments/Operator' or 'drums'. Each item reports name, is_folder, is_loadable and uri.

List every automatable parameter of a device on a track.

Returns JSON with the device name and a list of parameters, each:
index, name, value, min, max, is_quantized, value_items (enum labels for
quantized params, else null), display_value (e.g. '440 Hz', 'Lowpass'),
default_value, is_enabled. Use this to discover what you can change, then
call set_device_parameter. track='master'/'return:N' targets those tracks.

Set one device parameter — this is how you change a sound's tone.

- parameter: the parameter index (int) OR its exact name (str, case-insensitive).
- value: native units. For a continuous param a float in [min, max]
  (e.g. a frequency/dB/ms). For a quantized param, either an integer index
  into value_items or the exact value_items label string (e.g. "Lowpass").
- value_normalized: alternative to value, a 0.0-1.0 fraction mapped to
  min + x*(max-min); for quantized params it picks the value_items index.

Provide exactly one of value / value_normalized. The reply reports the
resulting display_value and whether the write applied (a parameter driven
by a macro is not writable).

Turn a device on or off (its bypass / 'Device On' switch). track='master'/'return:N' targets those tracks.

Delete a device from a track. track='master'/'return:N' targets those tracks.

List the macro controls of a Rack device (Instrument/Audio/MIDI/Drum Rack). Returns JSON like get_device_parameters but limited to the rack's macros. Set them with set_macro (or set_device_parameter).

Set a Rack macro by index (0-based) or name. Same value/value_normalized semantics as set_device_parameter.

Set a track's volume fader (0.0-1.0). NOTE: this is the fader position, not dB — ~0.85 ≈ 0 dB (unity), 1.0 ≈ +6 dB. value and value_normalized are equivalent here (the fader range is already 0..1). Reply reports the dB. track='master' sets the master fader.

Set a track's pan, -1.0 (hard left) .. 0.0 (center) .. +1.0 (hard right). track='master'/'return:N' targets those tracks.

Set a track's send level (0.0-1.0) to return track send_index (0-based).

Mute (on=True) or unmute (on=False) a track.

Solo (on=True) or unsolo (on=False) a track.

Arm (on=True) or disarm (on=False) a track for recording.

Set a track's color as a packed RGB integer (0xRRGGBB, e.g. 16711680 = red).

Create a new audio track. index=-1 appends at the end.

Create a new return track (appended after existing returns).

Delete a track. All higher track indices shift down — re-read get_session_info afterwards.

Duplicate a track (with its devices and clips). Re-read get_session_info afterwards to learn indices.

Read all MIDI notes from a clip. Returns JSON with a list of notes (pitch, start_time, duration, velocity, mute, and note_id when available).

Remove MIDI notes from a clip within a time/pitch region. Defaults clear the whole clip (from_time=0, full length, all pitches). time_span=None means 'to the end of the clip'.

Set a clip's loop attributes (only the ones you pass are changed): looping on/off, loop_start/loop_end (beats), start_marker/end_marker.

Duplicate a clip into the next clip slot on the same track.

Delete the clip in a clip slot.

Set a clip's color as a packed RGB integer (0xRRGGBB).

Create a new scene. index=-1 appends at the end.

Launch a scene (fires every track's clip in that scene row).

Set a scene's name.

Delete a scene. Higher scene indices shift down.

Set the song time signature, e.g. numerator=3, denominator=4 for 3/4.

Turn the metronome on or off.

Move the transport playhead to a position in beats from song start.

Report transport/record state: is_playing, record_mode (Arrangement Record ● armed?), session_record, current_song_time (beats), back_to_arranger, clip_trigger_quantization, tempo and time signature. Use it to verify a capture is running and to watch the playhead advance.

Arm/disarm Arrangement (global) Record — the transport's ● button. With it ON, launching Session clips/scenes records them into the Arrangement timeline. This is the capability that lets a Session-view loop be captured for export (Live's exporter only renders the Arrangement). For the full automated capture use capture_session_to_arrangement instead.

Set the global clip-launch quantization by index (0 = None, which launches clips immediately). capture_session_to_arrangement sets this to None for a tight start and restores it afterwards; exposed here for manual control.

Record a Session scene into the Arrangement so the song can be exported.

Live's Export Audio/Video only renders the Arrangement, so a Session-view
loop must first be printed there. This automates the whole capture — no
manual Arrangement-record arming:

  1. stop, rewind to 1.1.1, force Session Record off, and (if tighten_launch)
     set clip-launch quantization to None for a tight start at bar 1,
  2. arm Arrangement Record (the ● button),
  3. fire scene `scene_index` — its clips begin printing into the Arrangement,
  4. wait one full pass (`length_beats` + `tail_beats`), polling the playhead,
  5. stop, disarm record, restore quantization, rewind, return to Arrangement.

length_beats = bars * time_signature_numerator (e.g. 128 bars of 4/4 = 512).
`tail_beats` lets the final notes ring before stopping. Re-recording the same
span overwrites the previously captured Arrangement region for the scene's
tracks, so re-exports stay clean.

wait=True (default) blocks until the pass finishes and returns the result.
wait=False arms + fires and returns immediately (then call stop_playback and
set_arrangement_record(False) yourself once the playhead reaches length_beats).
max_wait_seconds caps the blocking wait (0 = auto: one pass + 15 s headroom).

Diagnostic: confirm the connection and report the Remote Script version that is actually loaded in Ableton (useful after reinstalling the script).

Read a track's output meter (0..1) for left/right and overall level. track can be an int index, 'master', or 'return:N'. Meters only move while audio plays — fire a clip/scene first, then sample (call a few times).

Read the master bus output meter (0..1). Sample while a scene is playing to gauge overall level / spot clipping (level near 1.0 = too hot).

Launch (or focus) Ableton Live 12, optionally opening a .als, then wait for the AbletonMCP control-surface bridge to come up on :9877. Use this to start Ableton before composing, or to reopen a saved project.

File ▸ New Live Set (Cmd-N) for a clean slate. The control surface is a global preference, so the :9877 bridge survives. Requires Accessibility.

File ▸ Save (Cmd-S) — for a Set already saved to disk. Requires Accessibility.

File ▸ Save As to a specific path, e.g. '.../projects// Project/.als'. Drives the macOS save sheet via AppleScript (best-effort) and returns expected_path — verify the file exists afterwards. Requires Accessibility.

Open Export Audio/Video (Cmd-Shift-R) and copy target_path to the clipboard for pasting into the save sheet. Returns the remaining steps; does NOT press Render (you confirm the export). Requires Accessibility.

Analyze a rendered/captured audio file — the objective 'listening' step.

Returns peak/RMS dBFS, crest factor, clipping; LUFS (integrated/short-term/
LRA) and true peak (dBTP); a 10-band spectrum (+ legacy 4-band) with centroid,
rolloff and flatness; transient/punch (onset strength/rate, per-band crest);
stereo correlation + overall/per-band width; DC offset, noise floor and
leading/trailing silence. `loudness_method` says whether LUFS came from
pyloudnorm or the numpy fallback. Capture a track/section first (record_audio)
or render via the export path, then analyze. Needs numpy+soundfile.

Diff two audio files (b relative to a) into human-readable deltas — loudness, per-band level, brightness (centroid), punch (low-band crest), width and dynamics, plus a one-line headline. Sub-perceptual changes are suppressed. This is the closed loop's progress meter: capture before/after a parameter move and compare to confirm the change helped.

Capture Live's audio output to a WAV via a loopback device (BlackHole) — the per-track 'ears'. Give a duration as bars (resolved from the session tempo/meter) or seconds; capture is REALTIME so prefer 2–4 bars.

source: a track index (int) to capture ONE track — it is soloed for the
capture and the prior solo state is restored — or 'master' / 'return:N'
(no solo). scene: the Session scene to fire so clips actually play (this
project composes in Session view — pass the arrangement scene index);
omit scene to play the Arrangement from position_beats instead.

Needs BlackHole + a Multi-Output Device set as Live's output, ffmpeg, and a
one-time Microphone grant. If no loopback device is found the reply explains
how to install it and names the manual-export fallback. Returns the WAV path
(in the temp dir) — feed it to analyze_audio / compare_audio.

Capture source (see record_audio) then analyze it in one call — the single primitive the tuning loop uses: change a parameter, then record_and_analyze(source=track, bars=2, scene=N) to read the result. Returns {capture, analysis}.