| get_session_infoA | Read top-level transport and time-signature state. Side effects: none.
Example: get_session_info() returns tempo and playhead state.
Edge cases: fails when the Remote Script is unavailable. |
| get_session_overviewA | Compose a compact Session snapshot from three existing read tools. Side effects: none; performs three read-only TCP bridge calls.
Example: get_session_overview() returns session, tracks, and scenes.
Edge cases: a bridge failure is returned by the corresponding component read. |
| get_bridge_statusA | Probe the Live bridge and explain environment-specific connection failures. Side effects: opens a loopback connection and performs one read-only session query.
Example: get_bridge_status() distinguishes MCP discovery from Live availability.
Edge cases: WSL NAT failures include a Windows-Python launcher hint. |
| get_track_listA | List regular, return, and master tracks with session path-ids. Side effects: none.
Example: get_track_list() returns [{"id": "track:0", ...}].
Edge cases: path-ids must be refreshed after structural track changes. |
| get_track_stateA | Read mixer, device, and Session clip-slot state for one track. Side effects: none.
Example: get_track_state(0) inspects the first track.
Edge cases: an out-of-range index returns INVALID_PARAMS. |
| get_locatorsA | List Arrangement cue points with names and beat times. Side effects: none.
Example: get_locators() returns [{"name": "Verse", "time": 8.0}].
Edge cases: Live beat-time objects are serialized as floats. |
| take_snapshotA | Capture a normalized full-state debugging snapshot. Side effects: none.
Example: take_snapshot() returns schema version, tracks, and context.
Edge cases: large Sets produce correspondingly large JSON results. |
| get_ableton_logsA | Read the tail of the newest Ableton Log.txt on Windows. Side effects: reads a local log file; it does not contact Live.
Example: get_ableton_logs(50) returns the last fifty lines.
Edge cases: returns a diagnostic string when no log can be located. |
| get_control_surfacesA | List MIDI Remote Scripts currently exposed by Live. Side effects: none.
Example: get_control_surfaces() confirms this script loaded.
Edge cases: unavailable surfaces may be omitted by Live. |
| get_scenesA | List Session View scenes and whether each scene is empty. Side effects: none.
Example: get_scenes() returns scene indexes and names.
Edge cases: a scene is non-empty when any contained slot has a clip. |
| get_scene_stateB | Read one scene and its per-track clip-slot summary. Side effects: none.
Example: get_scene_state(0) inspects the first scene.
Edge cases: an invalid scene index returns INVALID_PARAMS. |
| get_project_metadataA | Read Set name, file path, and dirty state. Side effects: none.
Example: get_project_metadata() identifies the loaded Set.
Edge cases: unsaved Sets can have an empty file path. |
| get_loop_settingsB | Read Arrangement loop enablement, start, and length. Side effects: none.
Example: get_loop_settings() returns loop geometry in beats.
Edge cases: values can change with user interaction during a session. |
| get_selected_contextA | Read the currently selected track, scene, and device. Side effects: none.
Example: get_selected_context() returns selected path-ids.
Edge cases: absent selections use null or index -1. |
| get_clip_summaryA | List Session clip slots and clip metadata for one track. Side effects: none.
Example: get_clip_summary(0) lists the first track's slots.
Edge cases: return and master tracks produce WRONG_TYPE. |
| get_clip_notesA | Read MIDI notes from one Session clip. Side effects: none.
Example: get_clip_notes(0, 1) reads slot one on track zero.
Edge cases: audio clips return WRONG_TYPE and empty slots return an empty list. |
| get_clip_infoA | Read stable metadata for one Session clip slot. Side effects: none.
Example: get_clip_info(0, 1) returns loop, type, color, and signature fields.
Edge cases: empty slots return has_clip=false instead of an error. |
| get_device_listA | List devices and parameter snapshots on one track. Side effects: none.
Example: get_device_list(0) returns device path-ids.
Edge cases: special tracks may expose an empty device list. |
| get_parameter_valueA | Read a named device parameter and its bounds. Side effects: none.
Example: get_parameter_value(0, 0, "Device On") reads a top-level
parameter; get_parameter_value(4, 1, "Out Low", chain_index=0, chain_device_index=0) reads one nested inside a rack chain.
Edge cases: names are exact and missing parameters return INVALID_PARAMS.
chain_index without chain_device_index addresses the chain's mixer,
which exposes only volume and panning. |
| set_parameter_valueA | Write a named device parameter and verify the observed Live value. Side effects: mutates one device parameter in one Live undo step.
Example: set_parameter_value(0, 0, "Filter Freq", 0.75) updates a device;
set_parameter_value(4, 1, "Out Low", 20, chain_index=0, chain_device_index=0)
reaches a Velocity device nested inside a rack chain.
Edge cases: chain_index alone addresses the chain's own mixer, where only
volume and panning exist. Disabled, unknown, and out-of-range
parameters return structured errors. |
| get_plugin_presetsA | List a VST/VST3/AU plugin's presets and report its Configure state. Side effects: none.
Example: get_plugin_presets(2, 2) returns the preset names plus
selected_preset_index for the plugin on track two.
Edge cases: native Live devices return WRONG_TYPE; a plugin whose
parameters were never added through Live's Configure button reports
plugin_state.hint = "PLUGIN_NOT_CONFIGURED". |
| set_plugin_presetA | Select one plugin preset by index or exact name and verify the readback. Side effects: switches the plugin preset in one Live undo step.
Example: set_plugin_preset(2, 2, preset_name="Rock Kit") selects a
preset without the Configure step set_parameter_value needs.
Edge cases: pass exactly one selector; unknown names, out-of-range indexes,
and plugins that expose no presets return structured errors. |
| get_routingA | Read input and output routing labels for one track. Side effects: none.
Example: get_routing(0) reports the first track's routes.
Edge cases: unavailable routes are returned as empty strings. |
| get_browser_categoriesA | List top-level Live Browser categories available in this version. Side effects: none.
Example: get_browser_categories() returns category display names.
Edge cases: version-specific missing categories are omitted. |
| search_browserA | Search the Live Browser with bounded TCP-side traversal. Side effects: none.
Example: search_browser("Operator", "instruments", 25) finds native devices.
Edge cases: traversal is capped by depth, children, visited nodes, and result limit. |
| diff_snapshots_toolA | Compare two snapshots recursively on the MCP-server side. Side effects: none; no socket call is made.
Example: diff_snapshots_tool(old, new) reports changed paths.
Edge cases: list entries are compared by position, not object identity. |
| get_song_lengthA | Read the derived Arrangement song length in beats. Side effects: none.
Example: get_song_length() returns {"song_length": 64.25}.
Edge cases: the LOM property is read-only; no setter tool exists. |
| live_find_trackA | Find tracks by case-insensitive name substring and return fresh path-ids. Side effects: none.
Example: live_find_track("bass") resolves matching tracks.
Edge cases: no match is a valid empty result. |
| live_find_deviceA | Find devices in a track by case-insensitive name substring and return fresh path-ids. Side effects: none.
Example: live_find_device(0, "operator") resolves matching devices on track 0.
Edge cases: no match is a valid empty result. |
| live_find_clipA | Find clip slots in a track by case-insensitive name substring and return fresh path-ids. Side effects: none.
Example: live_find_clip(0, "verse") resolves matching clips on track 0.
Edge cases: no match is a valid empty result. |
| list_device_paramsA | Resolve a track path-id and list all device parameters. Side effects: none.
Example: list_device_params("track:0") returns parameter path-ids.
Edge cases: missing targets return STALE_REFERENCE with a recovery hint. |
| create_cue_pointA | Create or idempotently rename a cue point at a beat time. Side effects: mutates the Set in one undo step and temporarily moves the playhead.
Example: create_cue_point("Verse", 8.0) creates a locator.
Edge cases: verified movement failure raises PLAYHEAD_NOT_MOVED before toggling.
Arrangement-grid snap is reversed and raises CUE_SNAPPED_TO_GRID. |
| bulk_create_cue_pointsA | Create or rename multiple cue points as one command. Side effects: mutates all successful items inside one undo step.
Example: bulk_create_cue_points([{"name": "A", "time": 0}]).
Edge cases: per-item errors are aggregated instead of aborting later items;
off-grid snaps are reversed and reported as CUE_SNAPPED_TO_GRID. |
| delete_cue_pointA | Delete a cue point by verified move-and-toggle. Side effects: mutates the Set in one undo step and temporarily moves the playhead.
Example: delete_cue_point(8.0) deletes a cue near beat eight.
Edge cases: no cue at the time returns deleted: false; an Arrangement-grid
snap is reversed and raises CUE_SNAPPED_TO_GRID. |
| set_current_song_timeA | Move the Arrangement playhead with set/read/retry verification. Side effects: writes transport state in one undo step.
Example: set_current_song_time(32.0) moves to beat thirty-two.
Edge cases: a stuck setter raises PLAYHEAD_NOT_MOVED after three attempts. |
| set_tempoA | Set the Live Set tempo in BPM. Side effects: writes tempo in one undo step.
Example: set_tempo(128.0) sets 128 BPM.
Edge cases: values outside 20..999 or non-finite values are rejected. With
dry_run=True, the change is validated but not committed. |
| start_playbackA | Start Live's transport. Side effects: starts playback in one undo-scoped command.
Example: start_playback() returns the observed playing state.
Edge cases: Live can reject the call while shutting down. |
| stop_playbackA | Stop Live's transport. Side effects: stops playback in one undo-scoped command.
Example: stop_playback() returns the observed playing state.
Edge cases: Live can reject the call while shutting down. |
| set_loopA | Enable or disable the Arrangement loop. Side effects: writes loop state in one undo step.
Example: set_loop(True) enables looping.
Edge cases: only a boolean value is accepted. |
| set_loop_startA | Set Arrangement loop start with read-back verification. Side effects: writes loop geometry in one undo step.
Example: set_loop_start(16.0) starts the loop at beat sixteen.
Edge cases: a stuck setter raises PLAYHEAD_NOT_MOVED. |
| set_loop_lengthA | Set Arrangement loop length with read-back verification. Side effects: writes loop geometry in one undo step.
Example: set_loop_length(8.0) makes an eight-beat loop.
Edge cases: length must be positive and a stuck setter raises an error. |
| run_batchA | Run allowed mutations sequentially inside one Live undo step. Side effects: successful prefix mutations persist until one Ctrl+Z; no rollback occurs.
Example: run_batch([{"type": "set_tempo", "params": {"tempo": 128}}]).
Edge cases: execution aborts at the first error and nested batches are rejected. |
| add_notes_to_clipA | Add validated MIDI notes to an existing Session clip. Side effects: adds notes in one undo step; existing notes remain.
Example: add_notes_to_clip(0, 0, [{"pitch": 60, ...}]).
Edge cases: audio clips, empty slots, and invalid MIDI ranges are rejected. |
| fire_clipA | Fire an existing Session clip through its clip slot. Side effects: launches playback in one undo-scoped command.
Example: fire_clip(0, 1) launches slot one on track zero.
Edge cases: empty or invalid slots are rejected. |
| create_clipA | Create an empty MIDI clip in an empty Session slot. Side effects: creates a clip in one undo step.
Example: create_clip(0, 1, 4.0) creates a four-beat clip.
Edge cases: only empty slots on MIDI tracks accept this operation. With
dry_run=True, the change is validated but not committed. |
| delete_clipB | Delete one occupied Session clip slot. Side effects: deletes a clip in one Live undo step.
Example: delete_clip(0, 1) removes the clip in slot one.
Edge cases: empty slots return BAD_INPUT. |
| clear_clip_notesA | Remove every MIDI note from one Session clip and report the observed delta. Side effects: clears notes in one Live undo step.
Example: clear_clip_notes(0, 1) empties a MIDI clip without deleting it.
Edge cases: empty or audio clips return structured errors. |
| fire_sceneA | Fire one Session scene using Live's current launch quantization. Side effects: triggers all playable clips in the selected scene.
Example: fire_scene(0) launches the first scene.
Edge cases: an out-of-range index returns INVALID_PARAMS. |
| set_track_propertyA | Set and verify one boolean track property. Side effects: changes mute, solo, or arm in one Live undo step.
Example: set_track_property(0, "mute", True) mutes the first track.
Edge cases: arm is rejected for return and master tracks. |
| set_track_colorA | Set and verify one track colour, by palette index or packed RGB. Side effects: writes Track.color_index or Track.color in one Live
undo step and reads the value back; clips are never recoloured.
Example: set_track_color(0, color_index=12) or
set_track_color(0, color=0x336699).
Edge cases: exactly one of color_index (0..69) and color
(0x000000..0xFFFFFF) is required; a track that does not expose the
property returns WRONG_TYPE and a rejected write returns
VERIFICATION_FAILED — the write is never retried. |
| set_clip_colorA | Set and verify one clip colour, by palette index or packed RGB. Side effects: writes Clip.color_index or Clip.color in one Live
undo step and reads the value back. Only the addressed clip changes.
Example: set_clip_color(0, 1, color_index=12) colours a Session clip;
set_clip_color(0, 0, scope="arrangement", color=0x336699) colours the
first Arrangement clip on that track.
Edge cases: exactly one of color_index (0..69) and color
(0x000000..0xFFFFFF) is required. An empty Session slot returns
BAD_INPUT. Arrangement scope needs Track.arrangement_clips (Live
11+); a host without it returns CAPABILITY_UNAVAILABLE — run
diagnose_clip_targets to see what is reachable. The write is issued
once and never retried. |
| diagnose_clip_targetsA | Report which clips set_clip_color can and cannot reach. Side effects: none; a read-only sweep of Session slots and Arrangement
clips.
Example: diagnose_clip_targets(0) inspects one track;
diagnose_clip_targets() sweeps the whole Set.
Edge cases: returns arrangement_supported: false and an inaccessible
entry for a host that does not expose Track.arrangement_clips, instead
of reporting zero Arrangement clips. |
| get_arrangement_clipsA | List one track's Arrangement clips with their placement on the timeline. Side effects: none.
Example: get_arrangement_clips(3) returns each clip's start_time,
end_time and length in beats, sorted by position.
Edge cases: a host without Track.arrangement_clips returns
CAPABILITY_UNAVAILABLE instead of an empty list. |
| duplicate_session_clip_to_arrangementA | Place a Session clip onto the Arrangement timeline at an exact beat. Side effects: adds one Arrangement clip in one Live undo step. The Session
clip stays where it is, and clip envelopes travel with the copy.
Example: duplicate_session_clip_to_arrangement(38, 0, 468.0) drops slot
one of track 38 at beat 468.
Edge cases: an empty slot returns BAD_INPUT; a host without
Track.duplicate_clip_to_arrangement returns CAPABILITY_UNAVAILABLE. |
| delete_arrangement_clipA | Delete one clip from the Arrangement timeline. Side effects: removes one Arrangement clip in one Live undo step.
Example: delete_arrangement_clip(3, 2) deletes the third clip of the
track's Arrangement lane.
Edge cases: clip_index indexes Track.arrangement_clips; re-read it
after any structural change because the indices shift. |
| get_device_chainsA | Open one rack and list its chains, their mixer state and inner devices. Side effects: none.
Example: get_device_chains(39, 0) reveals the four guitar chains and
the volume of each, which get_device_list cannot show.
Edge cases: a device that is not a rack returns WRONG_TYPE. |
| get_midi_chain_reportA | Report the MIDI effects that rewrite what a clip says, before writing one. Side effects: none.
Example: get_midi_chain_report(58) reveals that a Note Length device
overrides every written duration and which parameter actually controls it.
Edge cases: a track with no such device returns rewrites_input: false. |
| describe_instrumentA | Describe a track's instrument and what the user must still set up. Side effects: none.
Example: describe_instrument(60) returns the SWAM plugin's automatable
parameters, or a setup_requests entry asking the user to press
Configure when a plugin exposes none.
Edge cases: a track without an instrument returns has_instrument: false
with the request to load one. |
| get_clip_automationA | Read back one clip envelope as a sampled curve. Side effects: none.
Example: get_clip_automation(38, 0, "FILTER", resolution=0.5) returns
the written shape so intent can be compared against reality.
Edge cases: the LOM exposes no breakpoint list, so the answer is sampled at
resolution beats; a parameter name shared by several devices returns
AMBIGUOUS_MATCH unless device_index is given. |
| create_clip_automation_curveA | Write a smooth envelope from a handful of control points. Side effects: replaces one clip envelope in one Live undo step.
Example: create_clip_automation_curve(38, 0, "FILTER", [{"time": 0, "value": 12}, {"time": 16, "value": 110}], shape="exp")
expands into contiguous steps on the server.
Edge cases: Live's envelopes are stepped, so the expansion is a dense
staircase capped at 500 steps; raise resolution if it overflows. |
| add_notes_patternA | Repeat one note cell N times instead of sending every note. Side effects: adds notes in one Live undo step; existing notes remain.
Example: add_notes_pattern(59, 0, cell, cell_length=4, repeats=16, transpose_per_repeat=0) writes a sixteen-bar ostinato from one bar.
Edge cases: the same validation as add_notes_to_clip applies to every
expanded note; pitch and velocity are clamped to the MIDI range. |
| set_arrangement_clip_propertiesA | Rename or mute one Arrangement clip, verified by readback. Side effects: changes one Arrangement clip in one Live undo step.
Example: set_arrangement_clip_properties(44, 2, muted=False) unmutes a
clip that was silenced by hand.
Edge cases: clip_index indexes Track.arrangement_clips and shifts
after structural changes; provide at least one of name or muted. |
| move_arrangement_clipA | Move one Arrangement clip to a new beat. Side effects: copies the clip to time and deletes the original, both
verified. The LOM exposes no setter for Clip.start_time, so this is the
only way to reposition; a failed copy leaves the original in place.
Example: move_arrangement_clip(3, 2, 96.0).
Edge cases: indices shift after the move — re-read with
get_arrangement_clips. |
| move_trackA | Attempt to move one track to another index; Live's API cannot do this. Side effects: none — the request is validated and refused.
Example: move_track(3, 0) returns CAPABILITY_UNAVAILABLE with the
LOM and Extension SDK evidence in details.
Edge cases: invalid indexes return INVALID_PARAMS and return/main
tracks return WRONG_TYPE, so a malformed request stays
distinguishable from the capability gap. Create tracks at the index you
want, or reorder by hand in Live. |
| reorder_tracksA | Attempt to reorder every track at once; Live's API cannot do this. Side effects: none — the request is validated and refused.
Example: reorder_tracks([2, 0, 1]) returns CAPABILITY_UNAVAILABLE
with the API evidence in details.
Edge cases: order must be a permutation of the regular track indexes;
anything else returns BAD_INPUT before the capability refusal. |
| move_track_to_groupA | Attempt to move a track into a Group Track; Live's API cannot do this. Side effects: none — the request is validated and refused.
Example: move_track_to_group(4, 1) returns CAPABILITY_UNAVAILABLE
with the API evidence in details.
Edge cases: Track.group_track is read-only in the LOM and the
Extension SDK exposes only a getter. A non-foldable target returns
WRONG_TYPE; a self-nesting or cyclic request returns BAD_INPUT. |
| ungroup_trackA | Attempt to take a track out of its group; Live's API cannot do this. Side effects: none — the request is validated and refused. Nothing is
deleted under any circumstance.
Example: ungroup_track(2) returns CAPABILITY_UNAVAILABLE with the
API evidence in details.
Edge cases: a track that is not grouped returns WRONG_TYPE before the
capability refusal. |
| merge_groupsA | Attempt to move one group's members into another; Live's API cannot. Side effects: none — the request is validated and refused. This bridge
never deletes a track, so an emptied group would always be left in place.
Example: merge_groups(5, 1) returns CAPABILITY_UNAVAILABLE with
the API evidence in details.
Edge cases: both indexes must be Group Tracks (WRONG_TYPE otherwise),
must differ, and must not nest into each other (BAD_INPUT).
delete_empty_source=True is rejected with BAD_INPUT. |
| set_clip_propertiesB | Set and verify selected Session clip loop bounds or name. Side effects: changes one clip in one Live undo step.
Example: set_clip_properties(0, 1, loop_end=8, name="Verse") edits a clip.
Edge cases: the final loop interval must remain positive and non-empty. |
| create_clip_automationA | Replace one Session clip parameter envelope with verified breakpoints. Side effects: clears and rewrites one clip envelope in one Live undo step.
Example: create_clip_automation(0, 1, "volume", [{"time": 0, "value": 0.5}]).
Edge cases: requires Session-clip automation APIs and accepts at most 500
points. A parameter name carried by several devices of the track returns
AMBIGUOUS_MATCH; pass device_index to choose one. Envelopes are
stepped, so a smooth ramp needs dense points — or use
create_clip_automation_curve and let the server expand it. |
| get_composition_structureB | Retrieve the full track layout, scene count, and composition properties. Side effects: none.
Example: get_composition_structure() returns tracks, scenes, unnamed tracks.
Edge cases: large Sets produce correspondingly large JSON results. |
| diagnose_midi_clipA | Scan a MIDI clip for overlapping notes, notes outside scale, and quantization issues. Side effects: none.
Example: diagnose_midi_clip(0, 0, "C", "major") checks scale conformance.
Edge cases: audio clips return WRONG_TYPE; omitting scale skips pitch analysis. |
| create_midi_trackA | Create a new MIDI track inside Ableton Live under safe constraints. Side effects: mutates the Set by adding a track in one undo step.
Example: create_midi_track("Bass") appends a named MIDI track.
Edge cases: fails with TRACK_LIMIT_REACHED when ≥ 96 tracks exist. |
| create_audio_trackA | Create a new audio track in Ableton Live. Side effects: mutates the Set by adding an audio track in one undo step.
Example: create_audio_track(name="vocals") appends a named audio track;
create_audio_track(index=2) inserts at position 2.
Edge cases: raises LIVE_UNAVAILABLE when the Live host does not
expose Song.create_audio_track. Note: this audio variant does not
reuse the 96-track TRACK_LIMIT_REACHED guard — Live itself enforces
the per-host track cap. |
| rename_trackA | Rename a track in the Live Set. Side effects: mutates the track name in one undo step.
Example: rename_track(0, "Drums") renames the first track.
Edge cases: an out-of-range index returns INVALID_PARAMS. |
| get_warp_stateA | Retrieve warping status, warp mode, and warp markers of an audio clip. Side effects: none. Routed via the Extension Host WebSocket bridge.
Example: get_warp_state(1, 0) reads warp data from track 1, clip 0.
Edge cases: requires the AbletonMCPServer Extension to be installed. |
| set_warp_stateC | Modify warp parameters on an audio clip. Side effects: mutates warp state via the Extension Host.
Example: set_warp_state(1, 0, warping=True, warp_mode="complex")
Edge cases: requires the AbletonMCPServer Extension to be installed. |
| load_device_to_trackA | Load a device onto a track using the Extensions SDK browser API. Side effects: mutates the track device chain via the Extension Host.
Example: load_device_to_track(0, device_name="Operator") loads Operator
on track 0. device_uri is retained as a deprecated alias for callers
that still pass a query URI.
Edge cases: requires the AbletonMCPServer Extension to be installed. |
| lifecycle_statusA | Read Live save/quit API availability and return a GUI-workflow fallback. Side effects: none.
Example: lifecycle_status() reports song_save_available and app_quit_available.
Edge cases: missing Live APIs degrade to False flags; never raises. |
| save_setA | Save the Live Set via Song.save() when exposed, otherwise return a GUI workflow. Side effects: invokes Song.save() in one undo step when available.
Example: save_set(require_api=True) raises when the API is missing.
Edge cases: missing API returns a structured GUI workflow response. |
| quit_abletonB | Save the Live Set (when requested) then schedule Application.quit after a small UI delay. Side effects: invokes Song.save() and schedules Application.quit.
Example: quit_ableton(quit_delay_ticks=5) waits five UI ticks.
Edge cases: missing APIs return a structured GUI workflow refusal. |
| live_fadeA | Interpolate one track's mixer volume to a target value over duration seconds. Side effects: blocks the Live main thread for up to duration seconds plus
steps; first such command in our bridge. Writes mixer_device.volume in
one undo step.
Example: live_fade(track_index=0, target_percent=0) ramps the first
track to silence; live_fade(track_index=0, target_percent=120, allow_over_unity=True) exceeds unity and may clip.
Edge cases: rejects duration above 60 seconds and target_percent
above 100 without allow_over_unity. Provide exactly one of
target_percent or target_value. |
| scaffold_extensionA | Create a template Ableton Extension project folder. The scaffold produces an extension that follows the same shape as
the repository's own AbletonMCPServer_Extension: it imports
@ableton-extensions/sdk, declares dist/extension.js as the
package entry in both package.json["main"] and
manifest.json["entry"], and bundles via tsx build.ts. Vendor
tarballs shipped with the package are copied locally into the new
project so local SDK/CLI packages are used during build. In the
acceptance report, offline_passed indicates a probe that runs
without requiring a connection to Ableton Live. Side effects: creates files on disk. No Ableton connection required.
Example: scaffold_extension("MyEffect", output_directory="/tmp/ext")
Edge cases: returns a status="error" JSON when vendor tarballs are
missing or output directory is not writable; never raises during disk writes. |
| build_extensionA | Run a build of an Ableton Extension project. Side effects: runs npm install and npm run build in the
supplied project directory. Contract (v0.5.1): the JSON document returned by this tool has the
following shape:: {
"status": "built" | "error",
"entrypoint": "dist/extension.js",
"entrypoint_exists": true,
"steps": [
{"step": "install", "returncode": 0,
"stdout": "...", "stderr": "..."},
{"step": "build", "returncode": 0,
"stdout": "...", "stderr": "..."}
],
"artifacts": ["dist/extension.js", "..."]
}
entrypoint is read from package.json["main"] (falling back
to manifest.json["entry"] when main is missing) so the
contract reflects the project's own declaration. artifacts is
populated when status == "built" and lists every file under
dist/ relative to the project root. When the build completes
but the declared entrypoint is missing on disk, status flips
to "error" and entrypoint_exists is false.
Example: build_extension("/path/to/my-extension") runs
npm install then npm run build and returns the JSON
document above. Requires Node.js and npm on the host machine.
Edge cases: returns {"status": "error", "message": ...}
when package.json is missing; never raises during the
subprocess execution — every step's returncode is reported
in the steps array instead. |
| analyze_audioA | Compute LUFS-I, true-peak, RMS, and per-band energy summary for a
local audio file. Side effects: reads the file from disk.
Example: analyze_audio(path="/stems/kick.wav") returns LUFS-I plus
per-band energy summary.
Edge cases: missing files and unsupported encodings return a structured
{"ok": False, "reason": ...}. |
| find_frequency_maskingA | Identify frequency bands where target_path exceeds reference_path
by threshold_db dB or more. Side effects: reads both files.
Example: find_frequency_masking(target_path=master, reference_path=kick)
suggests band-level cuts.
Edge cases: mismatched sample rates raise a structured error; identical
paths are rejected at the model. |
| analyze_mixA | Run per-stem analysis and pair-wise masking across up to 16 local audio files. Side effects: reads each stem from disk.
Example: analyze_mix(stems=["/stems/kick.wav", "/stems/bass.wav"]) returns
per-stem LUFS plus pair-wise masking scores.
Edge cases: more than 16 stems raises a structured error; missing files
are reported per-stem via {"ok": False, "reason": ...}. |
| extract_single_cycleB | Find a candidate single-cycle loop in a local audio file plus its
detected pitch. Side effects: reads the file from disk.
Example: extract_single_cycle(path="/stems/kick.wav") returns the
detected pitch plus the single-cycle sample buffer.
Edge cases: aperiodic content returns {"ok": False, "reason": ...}
instead of crashing. |
| music_generate_drum_grooveA | Generate a deterministic kick-and-hat groove, optionally into a clip. Side effects: none unless apply is true, which creates one clip and its
notes in a single undo step.
Example: music_generate_drum_groove(bars=4, seed=7) returns the notes
without touching Live.
Edge cases: apply without track_index and clip_index is
rejected at the model. traits accepts groove, electro, weirdness and
space in 0..1, applied in that fixed order; the response names the axes
that actually changed the notes under traits_applied. |
| music_generate_bassA | Generate a deterministic root-only bass line, optionally into a clip. Side effects: none unless apply is true, which creates one clip and its
notes in a single undo step.
Example: music_generate_bass(bars=4, seed=7, root_midi=40) returns an E
bass line without touching Live.
Edge cases: every note is root_midi in some octave, folded back into
the MIDI range, octave leaps from weirdness included. traits behaves
exactly as it does for the drum groove. |
| music_plan_productionA | Lay a conventional section grid over a prompt and report what is missing. Side effects: none; this tool never reaches Live.
Example: music_plan_production(prompt="a track at 128 bpm", bars=64)
returns six tiled sections plus the resolved tempo.
Edge cases: no language model backs this tool. It reads only what the
prompt states literally and lists everything else under unresolved
instead of inventing it. |
| groove_searchB | Search the configured immutable groove seed bundle. Side effects: none; this is an offline deterministic read.
Example: groove_search(query="laid back", limit=5).
Edge cases: invalid cursors and missing criteria fail before runtime I/O. |
| groove_evidenceB | Return bounded provenance and projection evidence for one artifact. Side effects: none; this is an offline deterministic read.
Example: groove_evidence(artifact_id="ga1_...").
Edge cases: raw notes, payloads, paths, and SQL are never returned. |
| groove_generateA | Create a deterministic derived artifact in the local content store. Side effects: writes only a content-addressed local artifact; never calls Live.
Example: groove_generate(source={"artifact_id": "ga1_..."}, transforms={}, bars=4, seed=7).
Edge cases: rights, bounds, and unknown transform axes fail explicitly. |
| groove_compareB | Compare bounded cards and projections without exposing event payloads. Side effects: none; this is an offline deterministic read.
Example: groove_compare(artifact_ids=["ga1_...", "ga1_..."], metrics=["features"]).
Edge cases: incompatible projection sets remain explicit in compatibility. |
| groove_applyB | Preview or explicitly commit one mapped groove to one empty clip slot. Side effects: preview is offline; commit performs one guarded Live batch.
Example: groove_apply(..., mode="preview") returns a bounded receipt.
Edge cases: rights, mapping, capability, epoch, and slot races are explicit. |
| plan_user_journeyA | Plan a capability-aware guided journey as a fixed stage grid. Side effects: none; the plan names tools but calls none of them.
Example: plan_user_journey("sequence_drums", "half time, dark").
Edge cases: identity or exact-copy language returns a clarification request. |
