io.github.dreamrec/livepilot

List available semantic moves — high-level musical intents. Semantic moves express WHAT to achieve musically, not HOW parametrically. Each move compiles into a sequence of existing deterministic tools. domain: filter by family (e.g. mix, arrangement, transition, sound_design, sample, performance) style: filter by genre/style (reserved for future use) Returns: list of moves with move_id, family, intent, targets, risk_level.

Preview what a semantic move will do before applying it. Returns the static plan_template + verification_plans, PLUS an additive compiled_plan field built by compiling the move against a lightweight kernel of the current session. Use compiled_plan to inspect the concrete tool calls the move would emit right now; use plan_template to understand the move's shape independent of session state. args (v1.20+): user-supplied seed parameters threaded into the kernel as ``kernel["seed_args"]``. Routing / content / metadata moves require these (e.g., ``{"return_track_index": 0, "device_chain": ["Echo", ...]}``). Pre-v1.20 moves read only from ``session_info`` and ignore seed_args. Existing callers reading plan_template are unaffected by the addition.

Propose the best semantic moves for a natural language request, ranked by keyword fit AND the active taste graph. Shipped in v1.10.9: ranking is no longer pure keyword overlap — it now blends keyword match with taste alignment (``dimension_weights`` on each move's targets), an anti-preference penalty (``dimension_avoidances``), and a small family bonus from ``move_family_scores``. Cold-start users with zero recorded evidence get the same ranking as before; users with history see recommendations pulled toward dimensions they've kept and away from ones they've undone. request_text: what the user wants (e.g., "make this punchier", "tighten the low end", "reduce repetition") limit: max suggestions to return (default 3)

Compile and optionally execute a semantic move against the current session. Resolves the move's intent into concrete, parameterized tool calls based on the current session topology (track names, roles, devices). mode controls behavior: - "improve" / "finish": compile and RETURN the plan for user approval. The agent should present the steps and ask "Shall I do it?" - "explore": compile and EXECUTE immediately, capturing before/after. - "observe" / "diagnose": compile only, never execute. Return the plan. args (v1.20+): user-supplied seed parameters threaded into the kernel as ``kernel["seed_args"]``. Required by routing / content / metadata moves — e.g., ``apply_semantic_move("build_send_chain", mode="explore", args={"return_track_index": 0, "device_chain": ["Echo", "Auto Filter"]})``. Pre-v1.20 moves read only from ``session_info`` and ignore seed_args. Returns: CompiledPlan with concrete steps, summary, and execution status.

List the rubrics the grader can evaluate. Returns the rubric names registered in `mcp_server.grader.client`. Each rubric corresponds to a binding rule from CLAUDE.md (§7.3, §1, §4, §5, §2). See `livepilot/rubrics/<rubric_id>.md` for criteria detail.

Run a rubric across the current session, return verdict + brief. State modes: - heavy=False (default): `get_session_info` + per-track `get_track_info`. ~3s on a 4-track session. Sufficient for `layer_accumulation` and `default_preset_check`. - heavy=True: adds per-clip `get_notes`, per-clip `get_clip_automation`, per-Wavetable `get_wavetable_mod_matrix`, and (when `include_masking=True`) session-level `get_masking_report`. Required for `layer_precision` to produce non-n/a verdicts on sequence/modulation/masking criteria, and for `modulation_presence` to leave n/a. Args: rubric_id: Name of a registered rubric (see `grader_list_rubrics`). heavy: When True, fetch per-clip + session-level signals. Slower but needed for §4/§5 criteria beyond `stereo_per_track`. include_brief: When True (default), attaches a markdown revision brief formatted for an orchestrating agent. include_masking: When True (default; only relevant when heavy=True), includes the session-level masking report. Adds ~200–600ms. Returns: { "rubric_id": str, "passed": bool, "criteria": [{id, severity, summary, issues, evidence}, ...], "revision_brief": str, # present when include_brief=True "track_count_audited": int, "state_mode": "light" | "heavy", "elapsed_ms": int, }

Run ALL rubrics against the current session in one call. Builds session state once and evaluates every registered rubric against it. ~5× cheaper than calling `grader_evaluate` per rubric because state-fetching is the dominant cost. Default `heavy=True` — assumes a full audit. Pass `heavy=False` for a fast §1/§7.3-only sweep. Args: heavy: When True (default), uses heavy state. When False, only §1 default_preset_check and §7.3 layer_accumulation produce useful verdicts; the others return n/a. include_brief: Attach per-rubric revision_brief markdown. include_masking: Include session-level masking report (heavy only). Returns: { "rubrics": { "<rubric_id>": {<verdict + brief>}, ... }, "any_failed": bool, # True if any rubric verdict is fail "any_advisory": bool, # True if any rubric has warns "track_count_audited": int, "state_mode": "light" | "heavy", "elapsed_ms": int, "combined_brief": str, # merged across rubrics }

First-run setup — survey the user's filesystem for sensible scan candidates and return an approval packet for the agent to walk through with the user. Does NOT scan anything. Returns: - candidates: list of {category, path, file_count, sample_filenames, description, recommended_default} - plugin_detection_offer: separate prompt for installed-plugin detection - instructions: how the agent should proceed (ask each, then add approved) - do_not_scan: paths that require explicit per-folder opt-in (e.g. .als projects) Categories surfaced (when present on this machine): - user_library_racks — ~/Music/Ableton/User Library/Presets/*.adg - max_devices — ~/Documents/Max <N>/Max for Live Devices/*.amxd - plugin_presets — ~/Library/Audio/Presets/*.{aupreset,vstpreset,...} - samples_advisory — sample folders (scanner not yet implemented) Personal .als project folders are NEVER auto-suggested (privacy-sensitive).

Initialize the user-corpus output directory + manifest.yaml. Creates ``~/.livepilot/atlas-overlays/user/`` (if missing) and writes a default manifest if one doesn't already exist. Idempotent: safe to call multiple times — preserves an existing manifest. Returns ------- {manifest_path, output_root, sources, scanners_available, created: bool}

Register a new scan source in the user manifest. Parameters ---------- source_id : unique short identifier, e.g. "my-projects". Used in entity_id slugs and the namespace (user.<source_id>). type : scanner type_id. Run corpus_list_scanners to see options. Built-ins: "als", "adg", "amxd", "plugin-preset". path : filesystem path to scan. May contain ``~``. recursive : descend into subdirectories. Default True. exclude_globs : list of glob patterns to skip (e.g. ["*Backup*"]).

Remove a source from the manifest. Does NOT delete previously-written sidecars under the output root — those persist until you remove them manually. This makes redefining a source safe: removed → add → scan, no data loss.

Run scans on the user corpus. Parameters ---------- source_id : optional. If non-empty, scan ONLY that source. Otherwise scan every source in the manifest. Returns ------- { sources: [{source_id, type_id, files_scanned, files_skipped, files_errored, errors, elapsed_sec}, ...], total_scanned, total_skipped, total_errored, output_root, }

Report manifest contents + freshness for each source.

Phase 2.1 + 2.2 — detect installed VST3 / AU / VST2 / AAX / LV2 plugins and extract identity metadata (vendor, version, unique_id, format) from each plugin's bundle without needing a DAW host. Parameters ---------- formats : optional list of formats to restrict to, e.g. ["VST3", "AU"]. Default = all formats found at OS-standard paths. persist : write the detected inventory to ~/.livepilot/atlas-overlays/user/plugins/_inventory.json (default True) Returns ------- {plugins: [...], totals: {...}, inventory_path}

Phase 2.3 + 2.4 — find local manual files for a detected plugin and extract their text. Parameters ---------- plugin_id : the plugin to search for (must already be in _inventory.json from corpus_detect_plugins). Required. extract : also extract text from the top candidate (default True) persist : write extracted text to ~/.livepilot/atlas-overlays/user/plugins/<plugin_id>/manual.txt Returns ------- {plugin_id, candidates, extraction: {...}, manual_path}

Run the 6-critic battery to evaluate how well a sample fits the current song. Returns overall score, per-critic scores, recommendations, and both surgeon (precise) and alchemist (transformative) plans. intent: rhythm, texture, layer, melody, vocal, atmosphere, transform philosophy: surgeon, alchemist, auto (context-decides)

Dedupe the plugin inventory by canonical vendor + name; prefer VST3 as primary format; pick the prettiest vendor string across formats. Writes `plugins/_canonical.json` next to `_inventory.json`. The canonical inventory is what efficient Phase 3+4 research consumes — instead of running research separately on the AU and VST3 versions of the same plugin, the canonicalized record represents BOTH formats with `formats_available: [AU, VST3]` so a single identity.yaml covers both. Filtering: skip_vendors — list of vendor names to drop (default: ["Apple", "Splice"]) — exclude system AUs + utility apps skip_name_prefixes — list of name-prefix patterns to drop (default: ["Splice"]) — exclude installer/helper plugins Returns ------- {canonical_count, formats_distribution, top_vendors, canonical_path}

Group canonical plugins by vendor; return a cluster manifest the agent uses to dispatch Phase 3+4 research efficiently. For each cluster (vendor with >= min_cluster_size plugins) the agent runs ONE shared WebSearch pass + writes N identity yamls — vs N independent research passes for singletons. Cluster research lowers per-plugin token cost by 3-5x for vendors documented as a coherent product line. Returns ------- { clusters: [{vendor, plugin_count, plugin_ids: [...]}], singletons: [{plugin_id, vendor, name}], total_plugins, cluster_count, singleton_count, identity_yaml_status: {covered: [ids], missing: [ids]}, }

Slim a plugin's identity.yaml to the lean overlay-required shape. Use when the user explicitly deprioritizes a plugin ("don't waste tokens on this one") OR when post-processing a Phase 4 batch where some plugins received deeper research than the user wants persisted. Keeps the file queryable via atlas_search but drops the long key_techniques / parameter_glossary / comparable_plugins sections. Result preserves: entity_id, entity_type, name, description, tags (with `research-priority:<level>` appended), artists, plugin_id, vendor, format, formats_available, sonic_fingerprint (capped at 400 chars). Result drops: reach_for, avoid, key_techniques, parameter_glossary, comparable_plugins, genre_affinity, producer_anchors, cache_provenance. Parameters ---------- plugin_id : the plugin to trim. Required. research_priority : tag value: "low" / "medium" / "skip". Default "low".

Phase 3 — emit a structured WebSearch task packet for the agent to fulfill. This tool does NOT call the web. It returns the queries + cache locations + instructions; the Claude agent uses WebSearch + WebFetch + sonnet subagents to fulfill them. Returns ------- The Phase 3 packet — see PLUGIN_KNOWLEDGE_ENGINE.md §"Research target packet".

Phase 4 — emit sonnet-subagent briefs for plugin identity synthesis. For each requested plugin, builds a self-contained brief that an agent dispatches to a sonnet subagent (via the Agent tool) which writes one identity.yaml at the brief's output_path. Parameters ---------- plugin_ids : list of plugin_ids to emit briefs for. If empty, emits for every plugin in the inventory. inline_limit : maximum number of FULL briefs returned inline (default 5, matching the 'Cap parallel subagents at ~5' instruction). Any plugins beyond this cap are returned as lightweight stubs ({plugin_id, output_path}) in `deferred` so a single call can never return a multi-MB response over a large inventory. Pass explicit `plugin_ids` (or a larger inline_limit) to get the full brief for a specific batch. Returns ------- {briefs: [{plugin_id, brief, output_path}, ...], deferred: [{plugin_id, output_path}, ...], total, inline_count, inline_limit}

Enumerate registered scanner types and their supported file extensions. Useful for discovering what content types the corpus builder can handle on this install. Custom scanners registered by the user via @register_scanner show up here too.

Extract a SynthProfile for a native synth on the given track+device. Fetches live parameter state + display_values from Ableton, then hands them to the synthesis_brain adapter for that device. When the device isn't a supported native (Wavetable / Operator / Analog / Drift / Meld), returns an opaque SynthProfile — raw params survive for manual inspection but no strategies are proposed. role_hint: optional tag ("pad", "lead", "bass", "pluck", "stab", "drone") that gates adapter strategy selection. Leave empty when the role is ambiguous. Returns: SynthProfile dict with device_name, opacity, track_index, device_index, parameter_state, display_values, role_hint, modulation, articulation, notes.

Phase-3 develop mode: server-side execute the agent's variant plan. Receives a plan with the agent-designed variant set: { "scope": "develop", "clip_length_beats": float (default 4.0), "tempo": float (optional override), "variants": [ { "track_index": int, "scene_index": int, "name": str, "notes": [{"pitch": int, "start_time": float, "duration": float, "velocity": int}, ...] "sample_uri": str (optional — for sample-trigger swaps) }, ... ] } The agent decides variant count, names, scenes, MIDI per call — no fixed taxonomy. Empty notes list creates an empty clip (drum-dropout pattern). Returns: status, clips_created, scenes_populated, sample_swaps, preflight result, postflight result, errors list.

Propose branch seeds + pre-compiled plans for a native synth. Fetches the device's current parameters (via analyze_synth_patch), hands them to the appropriate adapter, and returns the emitted (seed, plan) pairs as two parallel lists suitable for create_experiment(seeds=..., compiled_plans=...). target: optional TimbralFingerprint dict ({"brightness": 0.3, ...}). Seeds that know about target direction (synthesis_brain adapters) will score their diffs against it during run_experiment with render_verify=True. When omitted, adapters shift based on freshness alone and role_hint gating. freshness: 0.0-1.0; threaded into kernel for adapter magnitude scaling. Returns: { "device_name": str, "branch_count": int, "seeds": [BranchSeed.to_dict(), ...], "compiled_plans": [plan_dict, ...] (parallel to seeds), "warnings": list, } Each seed's producer_payload captures strategy + topology_hint so PR3/PR4 winner-commit and render-verify can refine behavior without losing provenance.

Build a TimbralFingerprint from analysis dicts. Pure transform — no I/O. Useful when you already have spectrum + loudness + spectral_shape dicts (e.g. from analyze_spectrum_offline + analyze_loudness + get_spectral_shape) and want the 9-dimensional fingerprint without going through the full render-verify pipeline. Inputs are all optional; the fingerprint degrades gracefully to neutral (all-zero) when no signal data is present. Returns: TimbralFingerprint dict with brightness, warmth, bite, softness, instability, width, texture_density, movement, polish — each in [-1.0, 1.0].

Generate a Max for Live device from gen~ codebox code. The gen_code parameter accepts GenExpr DSP code that will be compiled at runtime by Max's gen~ engine. Safety clipping is automatically added. Args: name: Device name (used for filename and display) gen_code: GenExpr source code for the gen~ codebox description: Device description device_type: "audio_effect", "midi_effect", "instrument", "midi_generator", or "midi_transformation" params: List of parameter dicts with keys: name, default, min_val, max_val, unit_style install: If True, copy to Ableton User Library automatically

List available gen~ DSP building block templates. Templates are pre-built GenExpr algorithms that can be used directly or as starting points for custom devices. Each template has working code, parameters, and descriptions. Args: category: Filter by category (chaos, delay, distortion, filter, modulation, synthesis, texture, utility). Empty = all.

Copy a .amxd file to Ableton's User Library. Args: source_path: Path to the .amxd file to install

Build the musical identity model for the current song. Analyzes the session to identify: - identity_core: the strongest defining idea - sacred_elements: motifs/textures/grooves that must be preserved - section_purposes: what each section is trying to do emotionally - energy_arc: rise/fall shape across sections - open_questions: what the song has not resolved yet Call this at the start of complex creative workflows. Returns the full SongBrain as a dict.

Explain the current song's identity in human musical language. If no SongBrain exists yet, builds one first. Returns a structured explanation suitable for the agent to talk about the song naturally.

Detect whether recent changes have damaged the song's identity. Compares the current state against a previous SongBrain snapshot. If before_brain_id is provided, looks up that specific snapshot. If empty, uses the last cached brain. If no previous brain exists, builds baseline and reports no drift. before_brain_id: optional brain_id from a previous build_song_brain call. Returns drift score, changed elements, sacred damage, and recommendation.

Emit N distinct compositional hypotheses for a single prompt (PR5/v2). Branch-native companion to compose(): instead of one deterministic layer plan, produces up to ``count`` BranchSeeds with different strategic angles the user can audition via create_experiment + run_experiment. Each seed carries a pre-compiled scaffolding plan (set_tempo + create_midi_track per layer + create_scene per section) that gets escalated to a fully resolved plan by commit_experiment when the winning branch is chosen. Strategies (gated on freshness): canonical — intent unchanged, genre defaults (shipped at every freshness level) energy_shift — intent.energy inverted around 0.5 (freshness >= 0.4) layer_contrast — one role swapped (pad-anchor instead of bass) (freshness >= 0.7) Returns: { "request_text": str, "branch_count": int, "seeds": [BranchSeed.to_dict(), ...], "compiled_plans": [plan_dict, ...] (parallel to seeds; scaffold), } Each seed's producer_payload carries {strategy, intent, request_text, reason} so commit_experiment can rehydrate the CompositionIntent and run the full ComposerEngine.compose() for the winner.

Record one kept-over-discarded decision as training data. ``preferred_file`` is the capture you KEPT, ``rejected_file`` the one you moved on from — both capture names or absolute paths. Order matters: it is the label. Call this at the moment of decision, when you know which render survived. A pair is cheap and reversible; the model is only as good as the honesty of these labels, so record what you actually preferred rather than what you think you should have. ``group`` marks which session/material the pair came from, and defaults to the shared prefix of the two filenames. It matters more than it looks: cross-validation holds out whole groups, because several pairs from one session make each other trivially easy to predict. On real captures that difference was 100% versus 57%. Set it explicitly if the filenames do not reflect the true grouping. Two things about HOW you compare, which matter more than how many pairs you record. Do not A/B every candidate against one fixed baseline — not even a re-captured one, since ``capture_audio`` records live playback and produces a different file each time for the same material. Pairs sharing a reference are one piece of evidence, not several, and a corpus built that way cannot be certified at all (see ``anchor_asymmetry`` in the train report). Compare candidates against EACH OTHER. And record from at least ``taste_head.MIN_GROUPS_FOR_SIGNIFICANCE`` separate sessions — significance counts sessions, not pairs, so more pairs from the sessions you already have will not move it. Recording invalidates any previously fitted head — rerun ``taste_train``.

Fit the taste head and report how much it actually learned. Returns cross-validated accuracy, a p-value against chance, and a plain-language verdict. Read the verdict, not the accuracy. Training accuracy is deliberately NOT reported: CLAP embeddings are 512-dimensional and a realistic corpus is tens of pairs, so a linear head fits ~100% of the training data whether or not it learned anything — including on random labels. Even held-out accuracy needs the significance test: measured on synthetic data, 20 pairs of pure noise produced 65% leave-one-out accuracy, indistinguishable from a genuinely learnable signal at that sample size. ``significant`` has three states and they are not interchangeable. ``true`` is earned. ``false`` means tested and failed. ``null`` means it could not be tested at all — too few independent sessions, or the pairs turned out to share captures. Treat ``null`` exactly as you would ``false``: as no evidence. ``groups_merged`` and ``shared_reference_detected`` are worth reading. They fire when sessions you recorded separately turn out to share a reference — byte-identical for the first, merely the same material for the second — which is the single most common way a corpus looks bigger than the evidence in it. ``l2`` raises or lowers regularisation. The default is strong on purpose — with far more dimensions than pairs, the penalty is what stops the head memorising rather than generalising.

Rank captures by the learned taste head — best first. Pass two or more captures (names or absolute paths) to order them by predicted preference. For exactly two, a ``probability`` is included: P(first preferred over second) under the fitted head. Ranking, not scoring, is the honest interface. Bradley-Terry is shift-invariant, so an individual score has no absolute meaning — only differences between candidates do. Never threshold a single value. Returns an untrained/insufficient state rather than guessing if the head has not been fitted, and carries the head's ``cv_accuracy``, ``cv_scheme`` and ``significant`` flag alongside the ranking so a weak model cannot be mistaken for a confident one.

Full offline perceptual report for one master-bus capture. Analyzes a WAV/AIFF produced by ``capture_audio`` (pass the capture name or an absolute path). Returns: - ``snapshot`` — canonical sonic snapshot (9-band spectrum, rms, peak, spectral_shape, onset, novelty, loudness) directly usable as ``evaluate_move``'s before_snapshot/after_snapshot - ``extended`` — offline-only measurements: stereo width + correlation + bass-mono check, groove microtiming (pass ``bpm`` = session tempo for grid-based metrics; timing resolution ~4 ms), transient character, per-band loudness movement, technical polish (clipping, DC, headroom) - ``dimensions`` — 0..1 values; the nine canonical ones are computed by the evaluation stack's own extractor, extended ones (width, polish, motion_cv, groove_tightness) use non-canonical names ``seconds`` caps analysis to the first N seconds of the file (omitted/0 analyzes the full file); ``bpm`` omitted/0 falls back to tempo estimation. See livepilot-core references/perception.md #listen_capture--listen_ab--offline-perception-loop for the full offline-vs-real-time model. ``embed=True`` additionally returns an ``embedding`` block with a 512-dim CLAP vector — the taste anchor to persist alongside a kept/undone outcome so a preference model can be trained on real outcomes later. Off by default: it needs the optional ``torch``+``transformers`` extra and adds ~6 KB to the response. Reports ``available: false`` with an install hint when absent — the DSP measurements above are unaffected either way.

Compare two captures of the same musical span — what changed after a creative move. This is the perception loop's reflex arc: capture before a move, capture after, and this tool reports the empirical perceptual delta. Pass ``bpm`` = session tempo for reliable groove metrics (``bpm`` omitted/0 falls back to tempo estimation; ``seconds`` omitted/0 analyzes the full files). Returns: - ``verdict`` — human-readable summary of significant changes - ``dimension_deltas`` — per-dimension before/after/delta (canonical dimensions computed by the evaluation stack's own extractor) - ``significant_changes`` — feature changes above measurement-noise thresholds, ranked by magnitude - ``before_snapshot`` / ``after_snapshot`` — pass these directly to ``evaluate_move(goal_vector=..., before_snapshot=..., after_snapshot=...)`` for a numeric keep/undo verdict against a goal - ``before_extended`` / ``after_extended`` — full offline measurements per side (groove, stereo, loudness, transients, motion, polish) Both captures should cover the same musical material at the same session position (loop the section, capture, move, capture). Note: reusing fixed names like "before"/"after" across rounds intentionally overwrites the previous round's captures — use distinct names if you need to keep earlier rounds. See livepilot-core references/perception.md #listen_capture--listen_ab--offline-perception-loop for the full offline-vs-real-time model. ``embed=True`` adds a ``perceptual_distance`` block: one learned cosine distance for "do these sound like different things", which the per-feature deltas above cannot express on their own. Calibration from the 2026-07-31 benchmark — <0.05 is indistinguishable from re-rendering the same take, 0.05-0.1 is a real but modest change, >0.1 is clearly a different version. Needs the optional ``torch``+``transformers`` extra; reports ``available: false`` with an install hint otherwise.

Phase-3 of full mode (v1.24 LLM-creative): execute the agent-designed plan. compose(mode="full") returns a FullBrief with genre/artist vocabulary, the 42-event structural lexicon, and atlas instrument candidates. The agent reads the brief, designs the song's form (section sequence, bar counts, drop placement, variant per track per section), and submits that designed plan here. See mcp_server.composer.full.apply.apply_full_plan_v2 for the full plan shape. Required fields: form (list of section dicts), tracks (list of track specs with variants + arrangement_clips). Replaces the deterministic engine path (BUG-FULL-MODE-18 fix): the old flow tiled one source clip across all sections; the new flow emits one source clip per variant so each section can have a genuinely different pattern.

Plan, brief, or execute a multi-layer composition from a text prompt or an existing seed loop. Three modes: ``mode="full"`` (default) — plan-only. Parses prompt into genre/mood/ tempo/key, plans layers using role templates, returns an executable plan of tool calls for the agent to step through. This is the rich composition path. ``mode="fast"`` — **LLM-creative two-phase flow** (2026-05-01 redesign): Phase 1 (this call): returns a CREATIVE BRIEF with parsed intent, atlas-filtered instrument candidates per role, scale-pitch context, genre creative guidance. Does NOT generate any musical content. Pre-flight handles fresh-project detection, analyzer load, default- track cleanup, and tempo set so the agent can focus on creativity. Phase 2 (agent's job): read the brief, pick instruments creatively from instruments_by_role, design MIDI notes inline (genuinely fresh per call, not from templates), submit a complete plan to ``compose_fast_apply``. Phase 3 (compose_fast_apply): server-side execute the plan — create tracks, load instruments, populate clips with the agent's notes, fire scene. ``mode="develop"`` — extend an existing 8-bar loop into a fuller arrangement. Reads the seed at seed_scene_index (default 0), builds a brief with identity + vocabulary, returns it. Agent designs the variant set, calls develop_apply. prompt: "dark minimal techno 128bpm" / "downtempo lo-fi Cm" / "trap" mode: "full" | "fast" | "develop" bars: clip length in bars (fast mode only — default 4) target_scene: scene index to populate (full mode legacy param; fast mode now lets the agent pick via compose_fast_apply) seed_scene_index: scene to read as the seed (develop mode only, default 0) max_credits: max Splice credits budget for full-mode plans (default 50) dry_run: full-mode only — skip credit checks Fast mode returns: a brief dict with creative context. Call compose_fast_apply with your designed plan to actually create tracks. Develop mode returns: a brief dict with seed_state + design_targets. Call develop_apply with your designed variant plan. Full mode returns the existing plan dict.

Phase-3 of the LLM-creative fast mode (2026-05-01). Receives a complete layer plan designed by the agent (informed by the brief returned from ``compose(mode="fast")``) and bulk-executes it server-side: creates MIDI tracks, loads instruments by URI, creates clips, populates them with the agent's notes, fires the scene. ALL underlying TCP commands run in this single call so the agent doesn't pay round-trip cost between create_track / load / clip / notes. Plan shape: { "layers": [ { "role": "kick" | "snare" | "hat" | "perc" | "clap" | "bass" | "pad" | "lead" | "atmos" | "vox" | "fx", "uri": "atlas URI from brief.instruments_by_role[role]", "track_name": "optional display name (defaults to ROLE)", "notes": [ {"pitch": int 0-127, "start_time": float beats from clip start, "duration": float beats, "velocity": int 0-127}, ... ], # Phase B (2026-05-01): native-device effect chain on this # track, applied AFTER the instrument loads. Each entry # inserts one device (insert_device — 12.3+ API) and # optionally sets a few of its parameters. # Brief.creative_guidance.effect_chain_hints[role] is a # canonical starting point, but the agent should adapt # values to fit the prompt's mood (subtler in ambient, # heavier in trap, etc.). "effects": [ {"device": "Saturator", "params": {"Drive": 0.4}}, {"device": "EQ Eight", "params": {}}, ... ], # Phase B: track sends. return_name is case-insensitive; # if no return matches, the entry is skipped (no fail). "sends": [ {"return_name": "A-Reverb", "value": 0.25}, {"send_index": 1, "value": 0.10}, ... ] }, ... ], "scene_index": int or null (auto-pick first empty if null), "bars": int (clip length, default 4), "tempo": int or null (skip if already set in brief) } The agent should design notes creatively per call — don't reuse a template. Variation is the whole point of this two-phase flow. Returns: tracks_created, scene_fired, per-layer load+note status, effects_loaded + sends_set totals, plus techniques_used aggregating each layer's applied_technique (Tier-1C) so the user sees per-layer provenance: what producer-voice snippet from which Ableton tutorial informed each layer's design.

Tier-3: Ableton Knowledge consultation orchestrator. Takes a free-text production question + optional session context, returns a structured consultation plan: which Ableton Knowledge MCP tools to fire (search_transcripts / search_live_manual / search_videos / search_knowledge_base), with what queries, in what order, plus a synthesis template for the agent to combine the results into a direct answer for the user. The agent runs the recommended searches inline, synthesizes per the template, and surfaces sources alongside the answer. Examples: consult_ableton_knowledge("what does the Saturator Drive knob do?") → intent: device → plan: [search_live_manual("what does the Saturator Drive knob do?"), search_videos("what does the Saturator Drive knob do?"), search_transcripts("what does the Saturator Drive knob do?")] + synthesis template consult_ableton_knowledge("how do I make my kick punchier?", {"current_genre": "techno"}) → intent: sound_design → plan: [search_transcripts("techno how do I make my kick punchier?"), search_videos("techno how do I make my kick punchier? tutorial"), search_knowledge_base("how do I make my kick punchier?")] + synthesis template session_context (optional): { "current_genre": "techno", "current_key": "Am", "tracks": [{role, instrument}, ...] } — informs query specificity (e.g. "kick punch" becomes "techno kick punch"). Returns: { "question": str, "intent_classification": "sound_design" | "arrangement" | "mixing" | "device" | "general", "search_plan": [{tool, query, why}, ...], "synthesis_template": str, "expected_response_shape": dict, }

Plan sample-based layers to add to the existing session. Parses the request and builds a plan for new tracks with sample search queries, processing techniques, and volume/pan settings. Does NOT execute — returns the plan for the agent to step through. request: "add organic textures" or "layer a vocal chop over the verse" max_credits: maximum Splice credits budget for the plan (default 10) max_layers: maximum number of new tracks in the plan (default 3) Returns a compiled plan with step-by-step tool calls.

Preview what compose would do without executing or spending credits. Returns the full layer plan with search queries, technique selections, processing chains, and arrangement sections. Use to review before committing to a full composition. prompt: "dark minimal techno 128bpm with industrial textures"

Read-only analyzer for develop mode — returns SeedState for a scene. Inspects the scene's clips, classifies each track as sample_trigger or midi_riff, infers role from track name, and reports key/tempo/ time signature. The agent uses this BEFORE calling compose(mode='develop') to verify the loop is extendable, OR as a standalone diagnostic. Returns: dict per mcp_server.composer.develop.seed_introspector.introspect_seed. No writes to the session.

Analyze a sample and build a complete SampleProfile. Detects material type, key, BPM, spectral character, and recommends Simpler mode, slice method, and warp mode. Provide either file_path OR track_index + clip_index to analyze a clip in the session. Falls back to filename-only analysis if M4L bridge unavailable.

Search for samples across Splice library, Ableton browser, and local filesystem. Searches all enabled sources in parallel, ranked Splice-first, then browser, then filesystem. Splice results carry key/BPM/genre/tags/ pack/is_premium/price/is_free/preview_url metadata. With the Splice desktop app running + grpcio installed: searches Splice's ONLINE catalog, returning un-downloaded items too. Without gRPC: falls back to the local SQLite index (downloaded samples only). query: search text like "dark vocal", "breakbeat", "foley metal" q: alias for `query` (accepts either name for ergonomics) material_type: filter by type (vocal, drum_loop, texture, etc.) key: prefer samples in this key (e.g., "Cm", "F#") bpm_range: "min-max" BPM range (e.g., "120-130") source: "splice", "browser", "filesystem", or None for all collection_uuid: scope Splice results to a user collection (Likes, bass, keys, etc.). Obtain via splice_list_collections. When set, browser/filesystem sources are skipped — this is taste-scoped search. max_results: maximum results to return (default 10) free_only: if True, only return samples that cost nothing to license (IsPremium=False or Price=0). Under the Ableton Live plan these don't deplete the daily quota; under credit-metered plans they bypass the credit floor.

Suggest sample manipulation techniques from the technique library. Returns ranked techniques with executable step outlines for the given sample + intent combination. file_path: path to the sample intent: rhythm, texture, layer, melody, vocal, atmosphere, transform, challenge philosophy: surgeon, alchemist, auto

Full end-to-end sample workflow: analyze, critique, select technique, compile plan. Provide file_path for a known sample, or search_query to find one. Returns a complete compiled plan ready for execution. intent: rhythm, texture, layer, melody, vocal, atmosphere, transform philosophy: surgeon, alchemist, auto target_track: existing track index, or None for new track section_type: optional section context (intro, verse, chorus, drop, etc.) desired_role: optional sample role (hook_sample, texture_bed, break_layer, etc.)

Analyze current song and identify where samples could improve it. Returns opportunities with suggested material types and techniques. Used by Wonder Mode diagnosis for sample-aware creative rescue.

Plan an end-to-end slice workflow for a sample. Generates a Simpler slice strategy, MIDI note mapping, and starter pattern based on musical intent. Returns a compiled workflow plan — does NOT execute. The agent steps through each tool call in sequence. Provide either file_path (new sample to load) or track_index + device_index (existing Simpler with loaded sample). intent: rhythm | hook | texture | percussion | melodic bars: number of bars for the pattern (default 4) target_section: optional section name for arrangement hints style_hint: optional genre/style context (e.g. "dilla", "burial")

Get the user's current Splice plan, credits, and daily sample quota. Returns both pockets of the Splice subscription model: - `credits_remaining`: Splice.com credits for presets/MIDI/Instrument - `daily_quota`: sample-download counter (Ableton Live plan only) - `download_gating`: "daily_quota" (Ableton Live plan) or "credit_floor" (Sounds+/Creator/Creator+ — protects the last CREDIT_HARD_FLOOR credits) Full example response: livepilot-sample-engine references/ splice-tools-notes.md#get_splice_credits--full-response-example-ableton-live-plan. Returns connected=False (with zero credits) when the Splice desktop app isn't running or grpcio isn't installed.

Search Splice's ONLINE catalog via gRPC. Unlike `search_samples` which can fall back to the local SQLite index, this tool ONLY queries the online catalog — if Splice isn't connected it returns an error instead of local-only results. Use this when you specifically want fresh catalog content. query: free-text search ("mellotron", "lofi chord", "soul vocal") bpm_min: minimum BPM (0 = no lower bound) bpm_max: maximum BPM (0 = no upper bound) key: musical key (e.g. "cm", "f#", "a") sample_type: "loop", "oneshot", or "" for any genre: genre filter (e.g. "hip hop", "ambient") per_page: results per page (1-50) page: page number (1-indexed) Returns: { "connected": bool, "total_hits": int, # total catalog matches "samples": [...], # sample metadata with file_hash for download } Each sample entry contains `file_hash` which you can pass to `splice_download_sample` to trigger a download.

Run all sound design critics and return detected issues only. Lighter than analyze_sound_design — skips move planning. Args: track_index: Index of the track to analyze.

Download a Splice sample by file_hash — plan-aware gating. Use `splice_catalog_hunt` or `search_samples` first to find samples and their `file_hash`. The gating logic runs BEFORE any network call: - Ableton Live plan: uses your 100/day unmetered quota (not credits). Tracked locally in ~/.livepilot/splice_quota.json so repeated runs warn at 90/100 and refuse at 100 (resets at UTC midnight). - Credit-metered plans (Sounds+/Creator): enforces CREDIT_HARD_FLOOR=5 so the agent can't drain your monthly allotment. - Free samples (IsPremium=False or Price=0): bypass both gates. Arguments: file_hash: the sample identifier from search results copy_to_user_library: if True (default), also copies to ~/Music/Ableton/User Library/Samples/Splice/ so Ableton's browser can reach it via `load_browser_item` with a `query:UserLibrary#...` URI. force: bypass local quota checks (still honors server-side limits). Use for deterministic tests — NOT for production flows. Returns: { "ok": bool, "local_path": str, # Splice's own download path "user_library_path": str, # if copy_to_user_library=True "browser_uri": str, # ready for load_browser_item "decision": {...}, # plan-aware gating summary "credits_remaining": int, "daily_quota": {...}, # post-download quota snapshot }

Fetch a Splice sample's preview audio — ZERO credits, ZERO quota cost. Every catalog sample has a `PreviewURL` (low-bitrate MP3) that Splice streams freely. Use this to audition before calling `splice_download_sample`. Perfect for: - Quickly hearing 10 candidates before committing to one download - Staying under the daily sample quota on the Ableton Live plan - Letting agents judge fit without spending anything Arguments: file_hash: the sample identifier from search results cache: if True (default), write the preview to ~/Library/Caches/LivePilot/splice_previews/ for Ableton to load Returns: { "ok": bool, "preview_url": str, "local_preview_path": str, # if cache=True and download succeeded "filename": str, "duration_sec": float, "cost": "free", # always, for every plan }

List the user's Splice Collections (Likes, custom folders, Daily Picks…). Collections are user-curated sample/preset/pack bookmarks. They are the strongest available taste signal: each one represents the user's deliberate grouping. Use `splice_search_in_collection` to scope a search to one collection's samples — better than keyword-only search. Returns: { "ok": true, "total_count": int, "collections": [ {"uuid": "...", "name": "Likes", "sample_count": 47, ...}, ], }

List samples inside a Splice Collection by UUID. Get the UUID from `splice_list_collections`. The returned samples carry full metadata (key, BPM, is_free, preview_url) identical to `splice_catalog_hunt` — you can feed them straight into `splice_preview_sample` or `splice_download_sample`.

Add one or more samples to a user Collection. Persists server-side — the change appears in the Splice desktop app and web UI immediately. Use this to let LivePilot "save for later" items it finds during composition work.

Remove one or more samples from a user Collection (server-side).

Create a new user Collection. Returns the new UUID on success.

List presets the user has purchased from Splice. Covers Splice Instrument and Rent-to-Own plugin presets. Each entry includes `plugin_name` so the agent can route loading to the right plugin — e.g., a Serum preset vs. a Splice Instrument preset. Returns: { "ok": true, "total_hits": int, "presets": [ {"uuid": "...", "filename": "Deep House Pluck.fxp", "plugin_name": "Serum", "local_path": "...", ...}, ], }

Fetch metadata for a single preset (uuid, file_hash, or plugin_name).

Trigger a preset download (uses Splice.com credits, not the sample quota). Splice credits ARE used for presets under every plan — this is the "second pocket" of the subscription model. We still honor CREDIT_HARD_FLOOR=5 so the agent can't drain the monthly allotment.

Fetch full metadata for a Splice sample pack by UUID. Pack UUIDs come from search results (each sample carries `pack_uuid`). Useful for discovering related samples by pack, or surfacing pack-level genre/provider info that search results omit.

Natural-language sample search — the Sounds Plugin's "Describe a Sound". Splice's AI matches free-form descriptions like "dark ambient pad with shimmer" or "tight 90s house hi-hat" to catalog samples. Endpoint history: livepilot-sample-engine references/splice-tools-notes.md #splice_describe_sound--splice_generate_variation--endpoint-history. description: free-text prompt ("warm analog bass under 80bpm") bpm: optional BPM filter key: optional musical key ("Dm", "F#") limit: max results (default 20) rephrase: let Splice's ML rephrase the query for better matches (default True). Returned as `rephrased_query_string`. Returns `{ok, query, samples[], total_hits, rephrased_query_string, tag_summary[], ...}`. Each sample has uuid/name/bpm/key/duration/ instrument/tags/pack_name/files. Use the uuid with `splice_download_sample(uuid)` to pull the audio file.

Find catalog samples similar to a given Splice sample — the "Variations" feature. Splice's right-click "Variations" menu item surfaces other catalog samples with similar sonic character. Up to 10 results per call. No credit cost — a recommender lookup, not AI audio synthesis (the "generate" naming was aspirational). Endpoint history: livepilot- sample-engine references/splice-tools-notes.md #splice_describe_sound--splice_generate_variation--endpoint-history. uuid: source sample's catalog uuid (from `splice_describe_sound` results or any other Splice metadata call) is_legacy: match how Splice's own client sets it — default True is correct for all mainstream catalog samples; set False only if working with post-catalog-v2 assets Returns `{ok, uuid, similar_samples[], count}`. Each entry has the same flat shape as a describe_sound sample (uuid/name/bpm/key/ duration/tags/pack_name/files). Use the uuid of any result with `splice_download_sample()` to pull the audio.

Diagnose the Splice HTTPS bridge configuration and readiness. Reports which endpoints are configured, whether a session token is reachable from the gRPC client, and what the next step is to unblock `splice_describe_sound` and `splice_generate_variation`. Use this BEFORE calling either tool if you want a clear readout of "what's missing, and how do I fix it" instead of per-tool ENDPOINT_NOT_CONFIGURED errors.

Build full sound design state and run all critics for a track. Returns the complete timbral analysis including patch model, layer strategy, all detected issues, and suggested moves. Args: track_index: Index of the track to analyze.

Get ranked move suggestions based on current sound design issues. Runs critics and planner, returns sorted moves with estimated impact and risk scores. BUG-B36 fix: when zero sound-design issues but sibling mix/ composition engines flag problems on the same track, returns a `cross_engine_hint` pointing the user to the right tool instead of silently reporting empty. Args: track_index: Index of the track to analyze.

Get the structural patch model for a track's device chain. Returns device chain, functional blocks, controllable vs opaque blocks, and inferred musical roles. Args: track_index: Index of the track to inspect.

Build full mix state and run all critics. Returns the complete mix analysis including all sub-states (balance, masking, dynamics, stereo, depth) and all detected issues. target_style: intended dynamics target for the dynamics critic. "dynamic" (default) — standard mix expectations. "loud_master" — deliberately loud, heavily-limited master: the over_compressed check is suppressed (3-6dB crest is the intended sound there, not a defect).

Run all mix critics and return detected issues only. Lighter than analyze_mix — skips move planning. target_style: "dynamic" (default) or "loud_master" — see analyze_mix.

Get ranked move suggestions based on current mix issues. Runs critics and planner, returns sorted moves with estimated impact and risk scores.

Score a mix change using the evaluation fabric. Compare before/after spectral snapshots and evaluate whether the mix move improved the targeted dimensions without harming protected ones. Args: before_snapshot: Spectral snapshot before the move. after_snapshot: Spectral snapshot after the move. targets: Goal targets {dimension: weight} (e.g. {"clarity": 0.5}). protect: Protected dimensions {dimension: threshold}.

Get detailed frequency collision report. Shows all detected masking pairs, severity, and the worst collision pair.

Lightweight mix overview — track count, issue count, dynamics state. Faster than full analysis for quick status checks.

Create an experiment set to compare multiple approaches. Three input modes (in priority order): 1. seeds (PR3+): a list of BranchSeed dicts. Each seed becomes one branch. compiled_plans (optional parallel list) attaches pre-compiled plans for freeform / synthesis / composer producers. Seed dict shape: {seed_id, source, move_id, hypothesis, protected_qualities, affected_scope, distinctness_reason, risk_label, novelty_label, analytical_only} Missing fields default per BranchSeed. This is the canonical path for producers that have already done their own selection work. 2. move_ids: legacy path — one semantic_move seed per move_id. Unchanged behavior; internally delegates to the seeds path. 3. Auto-proposal: neither seeds nor move_ids provided. Scans the semantic move registry by keyword overlap with request_text and takes the top ``limit`` moves (default 3). Returns: experiment set with branch IDs ready for run_experiment.

Run all pending branches in an experiment. For each branch: 1. Compile the semantic move against current session (skipped when branch.compiled_plan is already set — PR3+) 2. Capture before state 3. Execute the compiled plan (through the async router) 4. Capture after state 5. Undo all successful steps (revert to checkpoint) 6. Evaluate the branch and classify its outcome via evaluation.policy 7. Record per-step results on branch.execution_log Branches run sequentially (Ableton has linear undo). exploration_rules: when True, branches that fail technical gates (score < 0.40, non-positive measurable delta) are classified as "interesting_but_failed" instead of "failed" — they stay in the experiment for audit but don't appear in the ranking. Protection violations STILL force undo regardless of this flag — that's a safety invariant, not a taste judgment. render_verify (PR4/v2): when True, each branch also captures audio before and after execution, analyzes spectrum + loudness offline, extracts a TimbralFingerprint, and attaches the before/after fingerprint + diff to the branch snapshots. The diff is fed into classify_branch_outcome as real measurable evidence — the classifier no longer relies on meter heuristics alone. Default False preserves speed; opt in when you want the classifier to respond to spectral movement, not just track-meter drops. render_duration_seconds: capture length per snapshot when render_verify is on. Default 2.0 seconds. Each branch adds ~2 * duration_seconds of capture time plus ~1-2s of offline analysis — a 3-branch experiment at 2s adds ~15-18s. Default render_verify=False preserves pre-PR4 behavior exactly.

Compare and rank all evaluated branches in an experiment. Returns branches sorted by score with their evaluations and summaries.

Commit the winning branch — re-apply its moves permanently. Routes the compiled plan through the async router (v1.10.3 truth). Returns a result dict with per-step execution_log. If any step failed, branch.status is set to 'committed_with_errors' and the response reports steps_failed > 0, so callers can tell the commit was partial.

Discard an entire experiment — no changes are kept.

Record a user dislike for a dimension+direction. direction must be 'increase' or 'decrease'.

Check the session ledger for entries eligible for memory promotion.

Activate Wonder Mode — stuck-rescue workflow with real diagnosis. Diagnoses why the session needs creative rescue, generates 1-3 genuinely distinct executable variants (plus honest analytical fallbacks), and opens a creative thread for tracking. Returns wonder_session_id for use with create_preview_set, commit_preview_variant, and discard_wonder_session. request_text: the creative request or description of being stuck kernel_id: optional session kernel reference

Rank wonder-mode variants by taste + identity + novelty + coherence. Standalone re-ranker for any list of variant dicts. Preserves ALL input fields (what_changed, compiled_plan, move_id, targets_snapshot). Uses the current SongBrain and session taste graph for scoring. When input dicts lack targets_snapshot, sacred element penalty is skipped gracefully. variants: list of variant dicts with at least variant_id, novelty_level, identity_effect, taste_fit fields Returns ranked list with composite scores, breakdowns, and recommendation.

Reject all Wonder variants and close the session. The creative thread stays open — the problem isn't solved. Records a rejected turn resolution and updates taste. wonder_session_id: the session to discard

Find the most salient hook in the current session. Analyzes melodic motifs, distinctive rhythmic cells, and signature textures to identify what the track is most "about." Returns the primary hook with salience scores, or a note if no clear hook is detected.

List and rank all hook candidates in the session. Returns candidates sorted by salience — a composite of memorability, recurrence, contrast potential, and development potential. limit: max candidates to return (default 5)

Suggest development strategies for a hook. hook_id: the hook to develop (from rank_hook_candidates). If provided, strategies are adapted to the hook's type (melodic, rhythmic, timbral, harmonic, textural). mode: development style — "chorus" (lift/strengthen), "variation" (melodic variation), "counterline" (complementary line), "breakdown" (stripped version), "fill" (ornamental version) Returns development strategies with musical explanations.

Measure the salience of a specific hook or the primary hook. Returns detailed scores for memorability, recurrence, contrast potential, and development potential.

Score a section's emotional impact as a musical phrase. Evaluates arrival strength, anticipation, contrast, groove continuity, and payoff balance. Phrase-level judgment outranks parameter-only evaluation for arrangement and transition decisions. section_index: which section/scene to evaluate (0-based) target: what it should function as — "hook", "drop", "chorus", "transition", or "loop"

Detect where the song should deliver a payoff but doesn't. Checks chorus, drop, and hook sections for flat arrivals, weak contrast, missing setups, and absent hooks. Returns failures with severity and repair suggestions.

Generate repair strategies for detected payoff failures. Runs payoff detection first, then suggests specific fixes for each failure.

Detect if a strong hook exists but is underused across sections. Checks whether the primary hook appears in enough sections to create adequate repetition and memorability. A hook that only appears in one section is "neglected" — it needs to recur. Returns neglect analysis with underused sections and suggestions.

Compare phrase-level emotional impact across multiple sections. Runs score_phrase_impact for each section and returns a ranked comparison with delta analysis between the strongest and weakest. section_indices: list of 0-based section indices to compare target: what the sections should function as — "hook", "drop", "chorus", "transition", or "loop"

Get the narrative of the current session. At the start of a resumed session, the agent can say what the track was trying to become, what changed last time, and what still feels open. Returns identity summary, recent turns, open creative threads, and mood arc.

Resume the most recent unresolved creative intent. Finds the latest open creative thread and suggests continuing it. Stale threads (untouched for >30 minutes) are excluded.

Record what happened in a creative turn. Call this after each significant creative action to build the session story. Tracks outcomes, identity effects, and user sentiment. request_text: what was requested outcome: "accepted", "rejected", "modified", or "undone" move_applied: which semantic move was used (if any) identity_effect: "preserves", "evolves", "contrasts", or "resets" user_sentiment: "loved", "liked", "neutral", "disliked", or "hated"

Rank candidates with separated taste and identity scoring. Taste (cross-session preference) ranks options. Identity (in-song) constrains/shapes options. Explicit user instructions override both. candidates: list of dicts with at least "id", "novelty_level", and "identity_effect" fields Returns ranked list with taste_score, identity_score, composite, and explanations for each.

Open a new creative thread — an unresolved creative goal. Use this to track intentions that span multiple actions, like "develop the chorus hook" or "fix the transition energy." Threads are surfaced by get_session_story and resume_last_intent. description: what the creative goal is domain: "arrangement", "sound_design", "mix", "harmony", "identity" priority: 0-1 importance level

List all open (non-stale) creative threads in the session. Returns unresolved creative goals, abandoned directions worth revisiting, and what the next best unresolved question is. Stale threads (untouched for >30 minutes) are excluded.

Explain how taste preference and song identity score a candidate. Shows the tension between what the user tends to like (taste) and what the current song needs (identity). Useful for understanding why a variant was ranked the way it was. candidate_id: the candidate to explain novelty_level: 0-1 how novel the candidate is identity_effect: "preserves", "evolves", "contrasts", or "resets"

Check playback robustness — mono safety, small speakers, harshness. Returns a full translation report with robustness classification (robust/fragile/critical), boolean safety flags, and suggested corrective moves.

Get just the translation issues without the full report. Lighter than check_translation — returns only detected issues from the 5 playback robustness critics.

Analyze the transition boundary between two sections. Builds a TransitionBoundary, selects an archetype, scores the boundary, and runs all 5 transition critics. Args: from_section: Name or ID of the outgoing section. to_section: Name or ID of the arriving section. Returns: boundary, archetype, score, issues, and recommended moves.

Plan a transition between two sections with concrete gestures. Selects the best archetype for the boundary and generates lead-in and arrival gesture sequences. Args: from_section: Name or ID of the outgoing section. to_section: Name or ID of the arriving section. Returns: plan with archetype, gestures, payoff estimate, and issues.

Score the transition quality between two sections. Returns a multi-dimensional score: boundary clarity, payoff strength, energy redirection, identity preservation, and cliche risk. Args: from_section: Name or ID of the outgoing section. to_section: Name or ID of the arriving section. Returns: score breakdown and overall rating.

Get current live performance overview — scenes, energy, safe moves. Returns scene roles with energy levels, current energy window with steering direction, available safe moves, and blocked move types. Use this to understand the performance context before making changes.

Get available safe moves for live performance. Returns only performance-safe moves based on current scene and energy direction. All moves are reversible and low-risk. Also returns the full blocked move list for transparency.

Plan a safe transition between two scenes. Generates an energy path and gesture sequence for smooth scene-to-scene handoffs during live performance. Args: from_scene: Source scene index. to_scene: Destination scene index.

Create a preview set with multiple creative options. Generates safe / strong / unexpected variants for comparison. Each variant includes what it changes, why it matters, and what it preserves from the song's identity. request_text: what the user wants (e.g., "make this more magical") kernel_id: optional session kernel reference strategy: "creative_triptych" (default) or "binary" wonder_session_id: optional — links to a WonderSession for lifecycle tracking Returns: preview set with variant summaries.

Compare and rank variants in a preview set. Rankings combine taste fit, novelty balance, and identity preservation. Returns ranked list with scores and a recommended pick. set_id: the preview set to compare taste_weight: how much to weight user taste fit (0-1) novelty_weight: how much to weight novelty balance (0-1) identity_weight: how much to weight identity preservation (0-1)

Commit the chosen variant from a preview set — APPLIES the plan. v1.10.3 Truth Release: this tool used to only mark the variant as committed in the in-memory store and leave plan application to the caller, which was a trust leak — users expected "commit" to actually apply the chosen variant. It now actually runs the variant's compiled plan through the async execution router. No undo after, the changes stick. Returns: { committed: bool (true if all steps applied, false if plan failed), variant_id, label, intent, move_id, identity_effect, what_preserved, execution_log: [{tool, backend, ok, error/result} per step], steps_ok: int, steps_failed: int, status: "committed" | "committed_with_errors" | "failed", } If the variant is analytical-only (no compiled_plan), the tool records the choice and returns status="analytical_only" WITHOUT pretending to execute anything — callers get a clear signal instead of a silent no-op.

Render a short preview of a specific variant for evaluation. Captures a snapshot of what the variant would sound like if applied, without permanently changing the session. Uses Ableton's undo system to revert after capture. set_id: the preview set containing the variant variant_id: which variant to render bars: how many bars to capture (default 8) Returns the variant's snapshot data and summary.

Discard an entire preview set and all its variants. Use when the user doesn't want any of the options.

Check whether an intended tool call complies with the active creative brief. v1.18.3 #7 + #8 runtime enforcement for the director's anti_patterns and locked_dimensions brief fields. Call this BEFORE executing any risky tool from director's Phase 6 — especially when the brief has non-empty anti_patterns or locked_dimensions. brief: the compiled Creative Brief dict. May contain anti_patterns (list of prose phrases), locked_dimensions (list of: structural/rhythmic/timbral/spatial), reference_anchors, etc. tool_name: the MCP tool name you're about to call. tool_args: dict of arguments you'll pass to that tool. Returns: { "ok": bool, "violations": [ { "rule": "anti_pattern" | "locked_dimension", "detail": <the anti_pattern phrase OR the locked dimension>, "reason": "Why this call appears to violate the brief", "suggestion": "What to do about it", }, ... ], } Violations are NEVER automatic blocks — they're reports. The director decides whether to proceed, surface to user, or abandon. Empty brief (no anti_patterns, no locked_dimensions) always returns ok=True. Best-effort keyword heuristic, NOT semantic understanding. Will miss subtle violations (e.g., 'too muddy' → 300 Hz cut needs judgment this checker doesn't have). Will catch obvious ones (e.g., 'bright top-end' → Hi Gain positive boost).

Merge 2+ concept packets into a single hybrid brief (v1.19 Item B). When the user says "Basic Channel meets Dilla swing" or "Villalobos but sparse like Gas", the director needs an explicit merge algorithm — not LLM ad-hoc reasoning. This tool loads the named concept packets from ``livepilot/skills/livepilot-core/references/concepts/`` and merges them per the rules in ``livepilot/skills/livepilot-creative-director/references/hybrid-compilation.md``. Merge rule summary: - ``sonic_identity`` / ``avoid`` / ``reach_for.*`` / ``*_idioms``: UNION, deduplicated, first-packet order preserved. - ``dimensions_deprioritized`` and ``move_family_bias.deprioritize``: INTERSECTION — only deprioritize if ALL source packets do. Safer default for hybrids where one packet may want what the other ignores. - ``move_family_bias.favor``: INTERSECTION when non-empty (hybrid focuses where both agree); UNION fallback otherwise with a warning. - ``evaluation_bias.target_dimensions``: WEIGHTED AVERAGE (default uniform weights). - ``evaluation_bias.protect``: MAX per dimension — stricter floor wins. - ``novelty_budget_default``: MAX (hybrids skew exploratory). - ``tempo_hint``: NEAREST-OVERLAP — intersect overlapping ranges, or warn + midpoint on disjoint ranges. Args: packet_ids: list of ≥2 packet IDs. Accepts filename stems (``"basic-channel"``), aliases (``"dilla"``), or packet ``id`` values (``"dub_techno__basic_channel"``). weights: optional per-packet weights for the ``target_dimensions`` average. Must match ``packet_ids`` length. Normalized internally; defaults to uniform. Returns: A brief dict structurally compatible with ``check_brief_compliance``. Exposes the merged ``avoid`` list both as ``avoid`` (packet semantic) and ``anti_patterns`` (brief semantic). Includes a ``warnings`` list surfacing any ambiguity the merge algorithm couldn't resolve cleanly. Raises: ValueError (surfaced as an error-dict response) on fewer than 2 packets, an unresolvable packet id, or a weights-length mismatch.

Return all recorded anti-preferences — dimensions the user has repeatedly disliked.

Return recent session memory entries — ephemeral observations, hypotheses, decisions.

Add an ephemeral session memory entry. Categories: - observation / hypothesis / decision / issue (pre-v1.20) - move_executed, tech_debt, override (v1.20 director Phase 6 — escape-hatch discipline + anti-pattern override logging)

Return all taste dimensions — user preferences inferred from kept/undone outcomes.

Get the full TasteGraph — extended preferences including move families, device affinities, novelty tolerance, and dimension weights. The TasteGraph combines taste dimensions, anti-preferences, and move/device tracking into a single model for personalized ranking.

Explain why the system thinks the user prefers certain approaches. Returns human-readable explanations of inferred taste based on evidence from kept moves, undone moves, device usage, and anti-preferences.

Rank semantic moves by taste fit for the current user. move_specs: list of dicts with {move_id, family, targets, risk_level} Returns: the same moves sorted by taste_score (descending). Use this after propose_next_best_move to personalize the ranking.

Record a user preference for more/less of a dimension. dimension: quality axis (e.g., "warmth", "width", "punch") direction: "increase" or "decrease" evidence: optional note about what triggered this preference Complements record_anti_preference — this records what users LIKE, not just what they dislike.

Detect recurring melodic and rhythmic patterns across all tracks. Scans note data from all session clips to find repeated interval patterns. Returns motifs sorted by salience (most memorable first), with occurrence locations, fatigue risk, and suggested transformations. Use this to understand what musical ideas are present and which ones need development or variation. BUG-B7 fix: sessions with many clips produced 90 KB+ payloads that exceeded inline-tool-response limits. Callers now page the list and can opt into a compact summary view that drops per-motif occurrence arrays and suggested_developments. Args: limit: maximum motifs returned per call (default 50, max 500). offset: skip this many of the highest-salience motifs (for paging). summary_only: return only motif_id + kind + salience + fatigue_risk + occurrence_count per motif, dropping occurrences and other lists. Use when you need a bird's-eye view.

Transform a musical motif using classical composition techniques. motif_intervals: interval pattern (list of semitone distances, e.g., [2, -1, 3]) Get this from get_motif_graph → motif.intervals transformation: inversion | retrograde | augmentation | diminution | fragmentation | register_shift_up | register_shift_down reference_pitch: starting MIDI pitch for output (default: C4=60) Returns: list of notes ready for add_notes. Example: transform_motif([2, 2, -1, 2], "inversion", 60) → notes descending instead of ascending

Get info about a device: name, class, type, active state, parameter count. track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.

Get all parameters for a device with names, values, and ranges. track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.

Rename a chain inside any Rack device — Instrument, Audio Effect, or Drum (Live 12.3+). Works with Drum Racks (the primary use case — naming pads "Kick", "Snare", "Clap", etc.) as well as Instrument/Audio Effect Racks. track_index: track containing the rack device_index: rack device index on the track chain_index: 0-based chain to rename name: new chain name (non-empty; Live may truncate)

Set which MIDI note triggers a Drum Rack chain (Live 12.3+). Standard drum mapping: C1 (36) = Kick, D1 (38) = Snare, F#1 (42) = Closed HH, A#1 (46) = Open HH, C#2 (49) = Crash, D#2 (51) = Ride note: MIDI note 0-127, or -1 for 'All Notes'

Set a device parameter by name or index. track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master. ⚠️ PARAMETER RANGES ARE NOT ALWAYS 0-1. Ableton devices use MIXED units depending on the parameter. Always read `value_string` in the response (or min/max from get_device_parameters) before assuming 0-1 semantics — it's the SOURCE OF TRUTH for what the user sees. Full per-device table: livepilot-devices references/ device-parameter-units.md. Quick hits: - **Compressor 2** (modern, default): 0-1 NORMALIZED. `Threshold 0.85 ≈ 0 dB`, `Ratio 0.75 = 4:1`, `Release 0.16 = 30 ms`. A dB value like -22 will fail here. Compressor I (legacy): pre-2010 units, dB direct. - **Saturator** `Drive`, `Output`, `Threshold`, `Color *`: 0-1 NORMALIZED (Drive 0.5 ≈ 0 dB, Drive 0.6 ≈ +7 dB). - Auto Filter `Frequency`: 20-135 index (NOT normalized). - EQ Three `Frequency Hi/Lo`: 50Hz-15kHz absolute. - Wavetable / Drift / Analog / Operator macros: 0-1 normalized ✓. - Pedal `Output`: -20..+20 dB direct; `Bass/Mid/Treble`: -1..+1. When in doubt, call get_device_parameters first to inspect min/max/is_quantized. On out-of-range rejection, the error is enriched with the actual min/max/value_string for that parameter — no follow-up get_device_parameters round-trip needed. Response includes `snapped: bool` when Ableton silently quantized the value to the nearest step (quantized-enum params).

Set multiple device parameters in one call. parameters (or operations): JSON array of objects. Each entry uses exactly one of: - {"parameter_index": N, "value": V} (preferred, aligned with set_device_parameter) - {"parameter_name": "Dry/Wet", "value": V} (preferred) - {"name_or_index": X, "value": V} (legacy, still accepted) ``operations`` is accepted as an alias for ``parameters`` (either works). track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master. Response includes a ``snapped_params`` list when quantized-enum parameters were silently snapped by Ableton (requested 0.3, received 0; e.g. Beat Repeat's Gate). Empty list means every requested value round-tripped within 1e-5 tolerance. Callers driving deterministic state should inspect ``snapped_params`` before assuming success.

Enable or disable a device. track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.

Delete a device from a track. Use undo to revert if needed. track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.

Load a device onto a track using a browser URI string. track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.

Move a device to a new position on the same or different track. track_index: 0+ for regular tracks, -1/-2/... for return tracks, -1000 for master.

Search the browser for a device by name and load it onto a track. track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master. allow_duplicate (default False): if a device with the same name is already on the track's chain, the default behavior is to NO-OP and return the existing device's location with `already_present: True`. Pass allow_duplicate=True to force a second instance (e.g., parallel processing chains where you genuinely want two of the same device).

Insert a native Live device by name — 10x faster than browser search (Live 12.3+). Only works for native devices (Reverb, Compressor, EQ Eight, Drift, etc.). For plugins, M4L devices, or presets, use find_and_load_device or load_browser_item. track_index: 0+ for regular tracks, -1/-2 for returns, -1000 for master device_name: exact device name (e.g. 'Reverb', 'Auto Filter', 'Wavetable') position: device chain position (0 = first, -1 = end of chain) device_index: required when inserting into a rack chain (identifies the rack) chain_index: insert into this chain of a rack device (for building drum kits) Drum Rack construction workflow (12.3+, full detail: livepilot-devices references/device-parameter-units.md#drum-rack-construction-workflow-123): insert_device(track, 'Drum Rack') to create the rack, then insert_rack_chain + set_drum_chain_note + insert_device(..., chain_index=0) to add each pad's instrument. On Live < 12.3: returns an error suggesting find_and_load_device instead.

Insert a new chain into a Rack device — Instrument Rack, Audio Effect Rack, or Drum Rack (Live 12.3+). Use with insert_device + set_drum_chain_note to build Drum Racks from scratch — see insert_device's docstring for the full 4-step workflow. track_index: track containing the rack device_index: rack device index on the track position: chain position (-1 = append to end)

Set Simpler's playback mode. playback_mode: 0=Classic, 1=One-Shot, 2=Slice. slice_by (Slice only): 0=Transient, 1=Beat, 2=Region, 3=Manual. sensitivity (0.0-1.0, Transient only).

Get all chains in a rack device with volume, pan, mute, solo.

Set volume and/or pan for a chain in a rack device.

List available presets for an Ableton device (e.g. 'Corpus', 'Drum Buss', 'Wavetable'). Searches audio_effects, instruments, and midi_effects categories. Returns preset names and URIs that can be loaded with load_device_by_uri.

Get ALL parameters from a VST/AU plugin including unconfigured ones. Returns every parameter the plugin exposes — not just the 128 that Ableton's Configure panel shows. Includes name, value, min, max, default, and display string for each. Only works on PluginDevice/AuPluginDevice types. Requires LivePilot Analyzer on master track.

Add a plugin parameter to Ableton's Configure list for automation. After mapping, the parameter becomes visible in the device's macro panel and can be automated with set_device_parameter or set_clip_automation like any native parameter. Requires LivePilot Analyzer on master track.

List a VST/AU plugin's internal presets and banks. Returns preset names and the currently selected preset index. Only works on PluginDevice/AuPluginDevice types. Requires LivePilot Analyzer on master track.

Get the Rack's variation count, currently selected variation index, and visible macro count (Live 11+). Variations are macro snapshots — store a scene of macro values, recall later. Returns {count, selected_index, visible_macro_count}. selected_index may be -1 if no variation is currently selected. Errors if the device is not a Rack (Instrument/Audio Effect/Drum Rack).

Store the Rack's current macro values as a new variation (Live 11+). Appends a new variation at the end of the list. Returns the new total {count, new_index} where new_index = count - 1.

Select and recall a stored Rack variation by index (Live 11+). Sets selected_variation_index then calls recall_selected_variation(), immediately pushing the stored macro values to the live Rack. Returns {selected_index}.

Delete a Rack variation by index (Live 11+). Selects the given index first then deletes it. Returns the new {count} after removal.

Randomize the Rack's macro values using Live's built-in randomize dice (Live 11+). Does not store a variation — just scrambles the current macros. Combine with store_rack_variation to snapshot the random state.

Add one macro to a Rack, raising visible_macro_count by 1 (Live 11+). Maxes at 16 macros. Returns the new {visible_macro_count}.

Remove the last macro from a Rack, lowering visible_macro_count by 1 (Live 11+). Minimum is 1 macro. Returns the new {visible_macro_count}.

Set the Rack's visible_macro_count directly (1-16, Live 11+). Faster than calling add_rack_macro/remove_rack_macro repeatedly to reach a target count. Returns the new {visible_macro_count}.

Insert a slice at a sample-frame position on a Simpler (Live 11+). time_samples is in raw sample frames (NOT beats, NOT seconds). Call get_simpler_slices first to see existing slice positions. The Simpler must be in Slice playback mode for slices to matter musically, but this tool does not force that — errors only if the device is not a Simpler or has no sample loaded. Returns {slice_count} after insertion.

Move an existing slice from one sample-frame position to another (Live 11+). Both values are in raw sample frames. old_time_samples must match an existing slice exactly — use get_simpler_slices to read current positions. Returns {ok, old_time_samples, new_time_samples}.

Remove a slice at an exact sample-frame position (Live 11+). time_samples must EXACTLY match an existing slice position. Read current positions with get_simpler_slices first. Returns {slice_count} after removal.

Remove all manual slices from the Simpler (Live 11+). Clears the slice list outright. Combine with reset_simpler_slices or import_slices_from_onsets to regenerate. Returns {slice_count: 0}.

Reset the Simpler's slices to Live's default detection (Live 11+). Re-runs detection under the CURRENT slicing_style and sensitivity. Use import_slices_from_onsets instead if you want to force Transient mode AND set sensitivity in one call. Returns the resulting {slice_count}.

Force Transient slicing mode, set sensitivity, and re-detect (Live 11+). Writes slicing_style=Transient and slicing_sensitivity, then calls reset_slices(). sensitivity must be 0.0-1.0; 0.5 is moderate, higher produces more slices. Returns {slice_count, sensitivity}.

Enumerate visible modulation target parameter names on a Wavetable (Live 11+). Returns {targets: [...]} — the list depends on the current patch configuration (e.g. which oscillators are active). Feed these strings into add_wavetable_mod_route / set_wavetable_mod_amount as the target argument.

Create a modulation routing on a Wavetable device (Live 11+). source must be one of: "Env 2", "Env 3", "LFO 1", "LFO 2", "MIDI Key", "MIDI Velocity", "MIDI Aftertouch", "MIDI Pitchbend", "Macro 1".."Macro 8". target must be a name from get_wavetable_mod_targets — valid targets depend on the current patch. Returns {source, target, actual_target} where actual_target is the parameter name Live resolved the routing to.

Set the modulation amount for a Wavetable source→target routing (Live 11+). amount is bipolar: -1.0 to 1.0. 0.0 effectively disables the routing. source and target use the same names documented on add_wavetable_mod_route. Returns {source, target, amount}.

Read the current modulation amount for a Wavetable source→target routing (Live 11+). Returns {source, target, amount, actual_target}. amount is -1.0 to 1.0. actual_target is the parameter name Live resolved the routing to — use it to confirm the routing went where you expected.

Dump all non-zero modulation routings on a Wavetable device (Live 11+). Iterates every source × visible target and returns any routing with a non-zero amount. O(sources × targets) but safe — useful to audit a patch or snapshot its modulation state. Returns {routings: [{source, target, amount}, ...]}.

Read a device's A/B compare state (Live 12.3+). Returns current_state ('A'|'B'|'unknown') and has_b (bool). If the LOM doesn't expose A/B attributes, returns 'unknown' with a 'note' field explaining the limitation.

Swap a device's A/B state (Live 12.3+).

Copy one A/B state to the other (Live 12.3+). direction: 'a_to_b' or 'b_to_a'.

List all active ControlSurface instances (Push, APC, Launchkey, etc.). Returns {surfaces: [{index, name, class_name}]}. Read-only diagnostic — mirrors Live.Application.get_application().control_surfaces. Use the index with get_control_surface_info() for per-surface detail.

Read detailed info about a single control surface. index: 0-based position in list_control_surfaces() results. Returns {index, name, class_name, component_count}. Component count falls back to 0 when the surface doesn't expose a .components iterable.

Reload every Remote Script handler module in Ableton — dev-loop helper. Client-side wrapper for the `reload_handlers` TCP command exposed by the Remote Script (see `remote_script/LivePilot/__init__.py`). Re-discovers handler submodules via pkgutil.iter_modules and reloads each one, re-firing @register decorators against a freshly-cleared router. Lets you edit a handler file → run installer → call this tool, without a Control Surface toggle or Ableton restart. Does NOT reload `router`, `server`, or `__init__.py` — Ableton's embedded Python handles only leaf-submodule reloads correctly. Returns {reloaded: True, handler_count: int} so callers can assert the post-reload registration surface. Raises if the Remote Script is pre-PR#16 (will surface as `[NOT_FOUND] Unknown command type`).

Run full composition analysis on the current Ableton session. Returns section graph, phrase grid, role graph, and issues from form/section-identity/phrase critics. This is the "one call to understand the arrangement structure." Uses scene names + clip activity to infer sections, note data for phrases, and track names + note patterns for role assignment. The issues section contains actionable structural recommendations.

Get just the section graph — lightweight structural overview. Infers sections from scene names and clip activity. Returns section types, energy levels, density, and active tracks per section. Faster than analyze_composition when you only need structure.

Get phrase boundaries for a specific section. section_index: which section to analyze (0-based, from get_section_graph). Returns phrase boundaries, cadence strengths, and note densities.

Plan a musical gesture — map abstract intent to concrete automation. intent: reveal | conceal | handoff | inhale | release | lift | sink | punctuate | drift target_tracks: list of track indices the gesture applies to start_bar: where the gesture begins duration_bars: how long (0 = use gesture default) foreground: is this a focal point or background motion? Returns a GesturePlan with: curve_family, parameter_hints, direction, and timing — ready for use with apply_automation_shape. Example: plan_gesture(intent="reveal", target_tracks=[6], start_bar=8) → exponential curve on filter_cutoff, sweep up over 4 bars

Evaluate whether a composition move improved the arrangement. Takes before/after issue lists (from analyze_composition) and compares severity and count. Returns a score and keep/undo recommendation. before_issues: issues list from analyze_composition BEFORE the move after_issues: issues list from analyze_composition AFTER the move target_dimensions: optional composition dimensions being targeted protect: optional dimensions to preserve Returns: {score, keep_change, issue_delta, severity_improvement, notes}

Analyze the harmonic content of a section — key, chords, voice-leading, tension. Combines identify_scale, analyze_harmony, classify_progression, and find_voice_leading_path into a single structured HarmonyField. section_index: which section to analyze (0-based, from get_section_graph). Returns: key, mode, chord_progression, voice_leading_quality, instability, resolution_potential.

Analyze transition quality between all adjacent sections. Checks for: hard cuts, missing pre-arrival subtraction, groove breaks, harmonic non-sequiturs, and weak builds without role rotation. Returns issues with recommended composition moves for each boundary.

Apply a compound gesture template — multiple coordinated automation gestures. template_name: pre_arrival_vacuum | sectional_width_bloom | phrase_end_throw | turnaround_accent | outro_decay_dissolve | bass_tuck_before_kick | harmonic_tint_rise | response_echo | texture_drift_bed | tension_ratchet | re_entry_spotlight target_tracks: list of track indices anchor_bar: reference point (section boundary bar number) foreground: is this a focal point? Returns: list of GesturePlans — execute each with apply_automation_shape.

Get composition move success rates grouped by section type. Analyzes stored composition outcomes to answer: which moves work best in which section types? Use before making structural changes to learn from past sessions. section_type: filter to a specific type (intro, verse, chorus, etc.) Leave empty for all types.

Set a track's volume (0.0-1.0). Use negative track_index for return tracks (-1=A, -2=B).

Set a track's panning (-1.0 left to 1.0 right). Use negative track_index for return tracks (-1=A, -2=B).

Set a send level on a track (0.0-1.0).

Get info about all return tracks: name, volume, panning.

Get master track info: volume, panning, devices.

Set the master track volume (0.0-1.0).

Read real-time output meter levels for tracks. Returns peak level (0.0-1.0) for each track. Call while playing to check levels, detect clipping, or verify a track is producing sound. track_index: specific track (omit for all tracks) include_stereo: include left/right channel meters (adds GUI load) samples: number of snapshots to take (default 1). When > 1, returns peak-over-window for `level`/`left`/`right` (BUG-2026-04-22#7 fix — single reads are unreliable because Live samples `level` and `left/right` at slightly different moments and they can disagree). sample_interval_ms: ms between snapshots when samples > 1 (default 50). BUG-B3 (still active): when playback is stopped, `level` reports peak-hold from the last loud moment while `left`/`right` report instantaneous channel levels (decay to 0). We tag responses with `is_playing`; when stopped + stereo requested, left/right → null.

Read real-time output meter levels for the master track (left, right, peak).

Get a complete mix snapshot: all track meters, volumes, pans, mute/solo, return tracks, and master levels. One call to assess the full mix state. Call while playing for meaningful meter readings.

Get input/output routing info for a track. Use negative track_index for return tracks (-1=A, -2=B).

Set input/output routing for a track by display name. Use negative track_index for return tracks (-1=A, -2=B).

Research a production technique — search device atlas + memory for answers. Synthesizes findings from the device atlas (built-in device knowledge), technique memory (past session learnings), and reference corpus into a structured TechniqueCard with devices, method, and verification steps. query: what you want to learn (e.g., "how to sidechain bass to kick") scope: "targeted" (device atlas + memory) or "deep" (adds web search) Returns: findings ranked by relevance, synthesized technique card, confidence.

Set loop on/off and optional loop region (start beat, length in beats).

Undo the last action in Ableton.

Redo the last undone action in Ableton.

Get a log of recent commands sent to Ableton (newest first). Useful for reviewing what was changed.

Analyze the emotional arc of the arrangement — tension, climax, resolution. Checks for: monotone energy, all-climax (no rest), build without payoff, no resolution at the end, peak too early. Returns: tension curve and issues with recommended composition moves. 📌 On the `tension_curve` vs other energy metrics (BUG-B21 clarification): LivePilot exposes THREE intentionally different "energy-like" signals — they are NOT scaled versions of each other: 1. `get_section_graph.energy` / `get_performance_state.energy_level` → density-based (active-track ratio per section). After the Batch 6 cross-engine unification these two are identical. Use when asking "how busy is this section?" 2. `get_emotional_arc.tension` (this tool) → narrative-arc signal weighted by harmonic instability (derived per section from key-detection confidence — low confidence reads as unstable — plus a bump when the mode shifts from the previous section), section placement, and payoff/contrast. Use when asking "where does the song want to go emotionally?" — tension can be HIGH in a sparse-but-anticipatory section (low density) and LOW in a busy-but-resolved section (high density). 3. `get_performance_state.energy_window.target_energy` → forward-looking — next-scene target, not current state. If the three readings disagree for the same section, that's the DESIGN: density ≠ tension ≠ intended destination. Pick the one that matches your question.

Get production tactics for a specific artist style or genre. Returns structured recipe cards with device chains, arrangement patterns, automation gestures, and verification steps. artist_or_genre: e.g., "burial", "techno", "daft punk", "ambient", "trap" Returns: list of StyleTactic cards with actionable production instructions.

Save a new technique to the memory library with stylistic qualities. type must be one of: beat_pattern, device_chain, mix_template, browser_pin, preference. qualities must include at minimum a 'summary' field.

Search the technique library by text query and/or filters. Returns summaries (no payload).

Fetch a full technique by ID, including payload for replay.

Retrieve a technique with a replay plan for the agent to execute. adapt=false: returns step-by-step replay plan for exact reconstruction. adapt=true: returns technique for creative adaptation.

Browse the technique library with optional filtering.

Star and/or rate a technique (rating 0-5).

Update name, tags, or qualities on an existing technique. Qualities are merged (lists replace).

Delete a technique from the library (creates backup first).

Get comprehensive Ableton session state: tempo, tracks, scenes, transport.

Set the song tempo in BPM (20-999).

Set the time signature (e.g., 4/4, 3/4, 6/8).

Start playback from the beginning.

Stop playback — halts the session transport and the arrangement cursor returns to its last position.

Continue playback from the current position.

Enable or disable the metronome click. If enabled is omitted, toggles the current state (true toggle). If enabled is provided, sets to that value explicitly.

Analyze the session for potential issues: armed tracks, solo/mute leftovers, unnamed tracks, empty clips/scenes, MIDI tracks without instruments. Returns issues with severity (warning/info) and stats. check_clip_keys: when True, also cross-checks every audio clip's filename-encoded key against the detected session key (BUG-D1 scan). Each mismatch appears as a diagnostic entry with the exact set_clip_pitch call that would correct it. Requires the M4L bridge (uses get_clip_file_path + get_detected_key); skipped gracefully if the bridge is unavailable. Off by default because it round-trips the bridge once per audio clip and can add noticeable latency on large sessions.

Tap the tempo (one tap). Live averages consecutive taps to set BPM.

Nudge tempo up or down by Live's internal nudge delta. direction: 'up' or 'down'.

Enable/disable exclusive arm mode (only one track armed at a time).

Enable/disable exclusive solo mode (only one track soloed at a time).

Capture currently-playing clips and insert them as a new scene. Distinct from capture_midi.

Set pre-record count-in duration (0-4 bars).

Read Ableton Link + count-in state (enabled, start/stop sync, tempo follower, is_counting_in).

Enable or disable Ableton Link (network tempo synchronization).

Force Ableton Link to a specific beat time (if supported by this Live version).

Analyze the integrated loudness of an audio file (OFFLINE — needs a rendered file). ⚠ This tool reads a file on disk. It does NOT connect to Ableton. For live session monitoring while a track is playing, use analyze_loudness_live() instead — no file needed. Computes integrated LUFS (EBU R128), true peak, RMS, crest factor, loudness range (LRA), and streaming platform compliance. Args: file_path: Absolute path to the audio file (.wav, .flac, .ogg, .aiff). detail: "summary" (default) or "full" — "full" includes the short_term_lufs array (up to 100 points, mean-pooled). Returns: On success: dict with integrated_lufs, true_peak_dbtp (4x oversampled), sample_peak_dbfs (raw sample peak, kept for backward compat), rms_dbfs, crest_factor_db, lra_lu, meets_streaming {spotify, apple, youtube, tidal}, and optionally short_term_lufs. On error: {"error": ..., "code": ...}

Analyze the frequency spectrum of an audio file (offline — no Ableton needed). Uses scipy STFT to compute spectral centroid, rolloff, flatness, bandwidth, and 5-band energy balance (sub_60hz, low_250hz, mid_2khz, high_8khz, air_16khz). Args: file_path: Absolute path to the audio file (.wav, .flac, .ogg, .aiff). n_fft: FFT window size (default 2048). hop_length: Hop size in samples (default 512). Returns: On success: dict with centroid_hz, rolloff_hz, spectral_flatness, bandwidth_hz, band_balance. On error: {"error": ..., "code": ...}

Compare a mix to a reference track (offline — no Ableton needed). Computes loudness delta (LUFS), spectral centroid delta, stereo width comparison, per-band energy deltas, and actionable mixing suggestions. When normalize=True (default), both files are LUFS-normalized to -14 LUFS before spectral comparison so frequency differences aren't skewed by volume. Args: mix_path: Absolute path to the mix file (.wav, .flac, .ogg, .aiff). reference_path: Absolute path to the reference file. normalize: LUFS-normalize before spectral comparison (default True). Returns: On success: dict with loudness_delta_lufs, mix_lufs, reference_lufs, centroid_delta_hz, stereo_width_mix, stereo_width_ref, band_deltas, suggestions. On error: {"error": ..., "code": ...}

Read metadata from an audio file (offline — no Ableton needed). Uses mutagen for tag reading (title, artist, album, BPM, etc.) and soundfile for format information. Falls back gracefully if mutagen cannot parse the file. Args: file_path: Absolute path to the audio file (.wav, .flac, .ogg, .aiff, .mp3, .m4a). Returns: On success: dict with format, duration, sample_rate, channels, bitrate, tags, has_artwork, file_size. On error: {"error": ..., "code": ...}

Duplicate a clip from one slot to another.

Export a session clip's notes to a .mid file. Fetches notes from the clip and writes them to a standard MIDI file. Auto-generates filename from track/clip if not provided.

Load a .mid file into a session clip. Reads MIDI, converts timing to beats using the file's own tempo map, and writes notes into the target clip slot. When create_clip=True (default), creates a new clip if the slot is empty; if a clip already exists, clears its notes before importing.

Analyze a .mid file — works offline, no Ableton needed. Returns note count, duration, tempo, pitch range, instruments, velocity stats, density curve, and estimated key.

Extract a 2D piano roll matrix from a .mid file. Offline-capable. Returns a velocity matrix [pitch_index][time_step] trimmed to the actual pitch range. Resolution is in beats (0.125 = 32nd note). To keep the response bounded, the emitted matrix is capped at ``_PIANO_ROLL_CELL_BUDGET`` cells (pitch_range * time_steps). When the full roll exceeds the budget the tool returns a structured error with the offending dimensions instead of a multi-MB matrix; coarsen ``resolution`` (larger value = fewer time steps) to fit.

Analyze harmony of a MIDI clip: chords, Roman numerals, progression. Reads notes directly from a session clip — no bouncing needed. Auto-detects key if not provided. Returns chord progression with Roman numeral analysis. The tool computes the data; interpret the musical meaning yourself.

Suggest the next chord based on the current progression. Analyzes existing chords and suggests theory-valid continuations. style: common_practice, jazz, modal, pop — affects which progressions are preferred. Returns concrete chord suggestions with pitches ready for add_notes.

Detect music theory issues: parallel fifths/octaves, out-of-key notes, voice crossing, unresolved dominants. strict=False: Only clear errors (parallels, out-of-key). strict=True: Also flag style issues (large leaps, missing resolution). Returns ranked issues with beat positions.

Identify the scale/mode of a MIDI clip beyond basic major/minor. Uses Krumhansl-Schmuckler-style profiles with 8 mode profiles (major, minor, dorian, phrygian, lydian, mixolydian, locrian, and phrygian dominant / Hijaz). Returns ranked key matches with confidence scores.

Generate a multi-voice harmonization of a melody from a MIDI clip. Hymn-style SATB convention: the original melody IS the soprano voice. The algorithm finds diatonic chords containing each melody note and voices them below the melody (bass + tenor + alto for 4-voice mode; just bass for 2-voice mode). voices: 2 (melody + bass) or 4 (SATB). Default 4. Response keys: - melody: the input melody as passed in (identical pitches to soprano) - soprano: same as melody (hymn-style convention) - alto / tenor: inner voices (4-voice only) - bass: root-aware bass line — BUG-B26 fix prevents tonic pedal - chord_sequence: the chord chosen per melody note (degree + name) BUG-B27: `soprano` and `melody` are intentionally identical — the tool's job is to add harmony UNDER an existing melody, not replace it. Both fields are returned so callers can pipe whichever makes their downstream code cleaner. Processing time: 2-5s.

Generate a countermelody using species counterpoint rules. species: 1 (note-against-note), 2 (2 notes per melody note). Follows strict rules: no parallel fifths/octaves, contrary motion preferred, consonant intervals on strong beats. Returns note data ready for add_notes on a new track. Processing time: 2-5s.

Transpose a MIDI clip to a new key with musical intelligence. mode: - diatonic: Maps scale degrees (C major -> G major keeps intervals relative to the scale). Chromatic notes shift by tonic distance. - chromatic: Simple semitone shift (preserves exact intervals). Returns transposed note data ready for add_notes or modify_notes.

Get an overview of browser categories and their children.

List items at a browser path (e.g., 'instruments/Analog'). BUG-2026-04-22#5 fix — the /drums folder returned 68KB+ of JSON on single calls, blowing past tool token caps. These params give agents a way to page and filter natively without dumping to temp files. path: browser path (e.g., 'drums', 'samples/Packs/Foo') limit: maximum items returned (default 500, max 5000) offset: number of items to skip (default 0) filter_pattern: case-insensitive substring to filter item names by (applied server-side when possible, client-side fallback)

Search the browser tree under a path, optionally filtering by name. BUG-2026-04-22#4 fix — `query` is now accepted as an alias for `name_filter`, aligning this tool's schema with `search_samples`. Callers passing either keyword work. path: top-level category to search under. Valid categories: instruments, audio_effects, midi_effects, sounds, drums, samples, packs, user_library, plugins, max_for_live, clips. Common aliases are normalised automatically: "effects" / "fx" → "audio_effects" "midi_fx" → "midi_effects" name_filter: case-insensitive substring filter on item name query: alias for name_filter (accepts either) max_depth: how deep to recurse into subfolders (default 8) max_results: maximum number of results to return (default 100)

Load a browser item (instrument/effect/sample) onto a track by URI. URI grammar — see livepilot/skills/livepilot-devices/references/ load_browser_item-uri-grammar.md for the full reference. Three known forms produced by search_browser / get_browser_items / get_browser_tree: - query:Drums#FileId_29738 (pack content) - query:Synths#Operator (native device by name) - query:UserLibrary#Samples:Splice:Filename.wav (path-style) Always pass URIs verbatim from search results. Never construct them by hand — guessed names match greedily and can load the wrong item. Context-dependent behavior (BUG-2026-04-22 #16): - Empty track: creates a Simpler with the sample loaded. - Track with an instrument: drops the new device after the existing one. - Track with a Drum Rack: the FIRST call creates a chain on note 36; subsequent calls REPLACE that chain instead of appending to the next pad. Use add_drum_rack_pad for pad-by-pad kit construction. role (optional, BUG-2026-04-22 #17 + #18): apply role-aware Simpler defaults after load. Skips silently if no Simpler was created (e.g., when loading a native synth or effect). - "drum" : Snap=0, Vol=0dB, Trigger Mode=0 (Trigger), root=C1 (36) - "melodic" : Snap=1, Vol=0dB, Trigger Mode=1 (Gate), root=C3 (60) - "texture" : Snap=0, Vol=-6dB, Trigger Mode=1 (Gate), root=C3 (60) Omit role to keep Live's raw defaults (Volume=-12dB, Snap=1). NOTE on Trigger Mode polarity (BUG-2026-04-22 #9): the value is REVERSED from intuition. Trigger Mode=0 means Trigger (one-shot, drum-style), Trigger Mode=1 means Gate (held, melodic-style).

Install LivePilot MIDI Tool .amxd files into Ableton's User Library. Copies both variants from ``m4l_device/`` to the correct MIDI Tools subfolders. Live 12 classifies a device as Generator vs Transformation via the ``project.amxdtype`` marker ('nagg' vs 'natt') inside the .amxd, AND indexes them from these specific folders: - ``Generate.amxd`` → ``User Library/MIDI Tools/Max Generators/`` - ``Transform.amxd`` → ``User Library/MIDI Tools/Max Transformations/`` Also copies ``miditool_bridge.js`` alongside each .amxd so the ``[js]`` object can find it (Max searches relative to the .amxd's location). Build the .amxd files first with ``scripts/build_miditool_amxd.py``, which patches Live's factory Max MIDI Generator/Transformation templates with our bridge wiring while preserving the amxdtype marker. After running this, right-click User Library in Live's browser → Refresh. Then open a MIDI clip's Generators or Transformations dropdown — ``LivePilot MIDI Tool (Generate/Transform)`` will be listed under User:. Returns ``{installed: [...], skipped: [...], user_library}``. macOS-only for this chunk.

Configure which LivePilot generator handles MIDI Tool requests. When Live fires the MIDI Tool on a clip, the bridge forwards ``(notes, context)`` to the server; the server invokes the configured generator and pushes transformed notes back for Live to write into the clip. Args: tool_name: One of the registered generators. Call ``list_miditool_generators()`` to see names and required params. v1.11.0 ships with ``euclidean_rhythm``, ``tintinnabuli``, ``humanize``. params: Generator-specific options (see ``list_miditool_generators``). Pass ``None`` or ``{}`` to use defaults. Returns ``{tool_name, params, active}``.

Return the most recent MIDI Tool context received from the bridge. Fields come from Live's ``live.miditool.in`` right outlet: grid: current grid subdivision (float beats) selection: {start, end} clip time range Live will replace scale: {root, name, mode} current Scale Mode state seed: RNG seed Live passes to the tool for determinism tuning: {name, reference_pitch} Tuning System info (12.1+) Also returns ``note_count`` (how many notes arrived in the last request) and ``connected`` (True once the bridge has pinged). If the bridge hasn't emitted a request in the last ~5 seconds, returns ``{"connected": False}`` — the analyzer/miditool .amxd may not be loaded, or no MIDI Tool fire has happened yet.

Enumerate the generators available for MIDI Tool targets. Each entry reports ``name``, ``description``, ``required_params``, and ``optional_params``. Use the names with ``set_miditool_target(tool_name=...)`` to configure the bridge.

Show neo-Riemannian neighbors of a chord on the Tonnetz. P (Parallel) flips the third: C major → C minor. L (Leading-tone) shifts by semitone: C major → E minor. R (Relative) shifts by whole tone: C major → A minor. Use depth 2-3 to see compound transforms (PL, PR, PRL, etc.).

Find the shortest neo-Riemannian path between two chords. Returns each intermediate chord and the specific voice movements. This is the 'film score progression finder' — chromatic mediants, hexatonic poles, and other cinematic chord moves.

Classify a chord progression by its neo-Riemannian transform pattern. Identifies hexatonic cycles (PL), octatonic cycles (PR), diatonic cycles (LR), and other known patterns. Pairs with analyze_harmony to understand why a progression sounds 'cinematic' or 'otherworldly'.

Suggest all chromatic mediant relations for a chord. Chromatic mediants are chords a major/minor third away — they share 0-1 common tones, creating maximum color shift with minimal voice movement. Includes 'cinematic picks' highlighting the most film-score-friendly options.

Compile a user request into a validated GoalVector. The agent interprets the user's natural language into quality dimensions, then this tool validates the schema and normalizes weights. targets: dict of dimension → weight (e.g., {"punch": 0.4, "weight": 0.3, "energy": 0.3}). Weights are normalized to sum to 1.0. protect: dict of dimension → minimum threshold (e.g., {"clarity": 0.8}). If a dimension drops below this value after a move, the move is undone. mode: observe | improve | explore | finish | diagnose aggression: 0.0 (subtle) to 1.0 (bold) research_mode: none | targeted | deep Valid dimensions: energy, punch, weight, density, brightness, warmth, width, depth, motion, contrast, clarity, cohesion, groove, tension, novelty, polish, emotion.

Build a WorldModel snapshot of the current Ableton session. Reads session info, spectral data (if analyzer available), per-track device health, and infers track roles from names. Degrades gracefully if M4L Analyzer is not loaded. Returns topology (tracks, devices, scenes), sonic state (spectrum, RMS, key), technical state (analyzer/FluCoMa availability, plugin health), and inferred track roles.

Evaluate whether a production move improved the mix toward the goal. Two call modes: **Structured** (full numeric scoring): supply goal_vector + before_snapshot + after_snapshot. Snapshots must contain spectrum (9-band dict sub_low → air) + rms + peak — capture via get_master_spectrum + get_master_rms before and after the move. Returns a numeric score and keep/undo recommendation. **Description-only** (quick log, no snapshots needed): supply only ``description``. Returns {evaluated: false, logged: true} — move is recorded as a session event but no numeric score is computed. Useful for mid-session bookkeeping when you haven't pre-captured snapshots. Hard rules (structured mode only) enforce undo when: - No measurable improvement (delta <= 0) - Protected dimension dropped below its threshold or by > 0.15 - Total score < 0.40 When all target dimensions are unmeasurable (e.g., groove, tension), the tool defers keep/undo to the agent's musical judgment. Returns consecutive_undo_hint=true when keep_change=false — the agent should track consecutive undos and switch to observe mode after 3.

Analyze accumulated outcome memories to identify user taste patterns. Reads outcome-type memories from the technique library and returns: - keep_rate: what percentage of moves does this user keep? - dimension_success: which quality dimensions improve most often? - common_kept_moves: which action types work best? - common_undone_moves: which action types fail most? - taste_vector: inferred dimension preferences from history Use this before choosing moves to align with user taste. The more outcomes stored (via memory_learn type="outcome"), the better the taste analysis becomes.

Search for technique cards — structured production recipes. Technique cards are reusable recipes saved from successful production outcomes. Each card has: problem, context, devices, method, verification. query: search term (e.g., "wider pad", "punchy kick", "sidechain bass") limit: max results

Get the user's production taste profile from outcome history. Analyzes kept vs undone moves to identify: preferred dimensions, avoided dimensions, taste vector weights, and overall keep rate. Use this to understand what this user values in production. limit: how many outcomes to analyze (default: 50) Returns: {taste_vector, preferred_dimensions, avoided_dimensions, keep_rate, sample_size}

Launch/fire a clip slot.

Get a resource budget for the current agent turn. Returns six resource pools that prevent overcommitting: - latency_ms: time budget for this turn - risk_points: how much risk is allowed (0-1) - novelty_points: how much novelty is allowed (0-1) - change_count: max production moves this turn - undo_count: max consecutive undos before switching to observe - research_calls: max research lookups this turn mode: observe | improve | explore | finish | diagnose | performance - observe: very low risk, zero changes, read-only - improve: balanced defaults - explore: high novelty, high risk, more moves - finish: conservative, low novelty, few changes - diagnose: zero changes, research-focused - performance: very low latency, minimal risk aggression: 0.0 (subtle) to 1.0 (bold) — scales risk and change limits Use spend functions via the conductor to track consumption during the turn.

Route a production request to the right engine(s). Analyzes natural language to determine which engines should handle the request, in what priority order, with what entry tools. request: what the user wants (e.g., "make this punchier", "turn the loop into a song", "make it sound like Burial") Returns: routing plan with engine priorities, entry tools, and capability requirements.

Close the evaluation loop: run experiments until threshold or timeout. Each iteration creates an experiment from one candidate_move_sets entry, runs all branches (which auto-undo per-branch via the experiment engine), and checks the top-ranked branch's score against the GoalVector. If score >= threshold, commit that branch permanently and stop. Otherwise discard the experiment and try the next candidate set. On timeout, commit the best-so-far (on_timeout='commit_best') or commit nothing (on_timeout='discard_on_timeout'). Args: goal_vector: Compiled GoalVector dict (from compile_goal_vector) or JSON string. Provides the scoring target passed through to the evaluation scorer inside each run_experiment call. candidate_move_sets: List of move_id lists — one per iteration. Example: [["make_punchier", "widen_stereo"], ["tighten_low_end"]]. Iteration 0 tries the first list, iteration 1 the second, etc. If shorter than max_iterations, iteration stops when exhausted. threshold: Winner score required to commit early. 0.0–1.0. Default 0.70. max_iterations: Hard cap on outer-loop iterations. Default 3. on_timeout: "commit_best" (commit highest-scoring experiment at end) or "discard_on_timeout" (no commit if threshold never met). render_verify: When True each branch captures + analyzes audio (~6s extra per branch). Default False. Returns: IterationResult dict with status, iterations_run, committed_experiment_id, committed_branch_id, final_score, steps, reason. Safety: Only commits when threshold_met OR (on_timeout='commit_best' AND best-so-far exists). Never double-undoes — per-branch undo is handled inside run_experiment; this tool only issues commit or discard.

Transform the current loop/session into a full arrangement blueprint. Analyzes the existing tracks and their roles, then proposes: - Section sequence (intro → verse → build → drop → etc.) - Element reveal order (what enters/exits when) - Gesture automation suggestions for transitions - Orchestration plan (which tracks play in which sections) target_bars: desired total arrangement length (default: 128 bars) style: free-text style label (e.g. "electronic", "ambient") — recorded as a hint on the result. The framework no longer hardcodes genre→form templates (vocabulary-not-form, v1.24); supply explicit form via `sections` if desired. sections: optional explicit form — a list of [section_type, energy_target, density_target, bars] entries (or the dict form {"type","energy","density","bars"}). When omitted a generic genre-neutral arc (INTRO…OUTRO) is used so the tool always returns a plan. Returns: full ArrangementPlan with actionable section-by-section instructions.

Apply a structural transformation to the arrangement. Proposes radical structural moves — reorder sections, expand loops, compress verbose arrangements, insert bridges. Returns the proposed new section graph without modifying the actual session. transformation: insert_bridge_before_final_chorus | swap_verse_positions | extend_section | compress_section | insert_breakdown | duplicate_section | remove_section | reverse_section_order | split_section section_index: which section to transform (required for targeted operations, -1 = auto) bars: how many bars for extend/compress/insert operations Returns: before/after section graphs with description and bar delta.

Read a clip's follow-action state (Live 12.0+). Returns: enabled: bool — follow-action master switch action_a: primary action name (stop, play_again, previous, next, first, last, any, other, jump) action_b: secondary action (used when chance_b > 0) chance_a: probability of action_a firing (0.0-1.0) chance_b: probability of action_b firing (0.0-1.0) time: follow-action trigger time in beats

Set a clip's follow action (Live 12.0+). Any omitted arg preserves. action_a/b values (string): stop, play_again, previous, next, first, last, any, other, jump. chance_a/b: probability 0.0-1.0. Live normalizes the split between the two actions — set chance_b=0 to always fire action_a. time: follow-action trigger time in beats (e.g. 1.0 = one bar in 4/4, 4.0 = one bar in 4/4 if the clip is 4 beats long). enabled: master on/off for follow actions on this clip.

Stop a playing clip.

Disable follow action on a clip (Live 12.0+). Sets follow_action_enabled=False without touching the action/chance values, so re-enabling keeps the previous configuration.

List valid follow-action names (Live 12.0+). Returns the 9 enum values usable for action_a/action_b: stop, play_again, previous, next, first, last, any, other, jump.

Apply a named follow-action preset to a clip (Live 12.0+). Presets: loop_forever — re-fires the clip each bar indefinitely (action_a=play_again, chance 100%) random_walk — 50/50 split between next and previous clip next_after_one — play the clip once, advance to next slot stop_after_one — play the clip once, then stop Each preset sets action_a, action_b, chance_a, chance_b, time and enables follow actions. Time is 1.0 beat across all presets.

Read a scene's follow-action state (Live 12.2+). Returns: enabled: bool — scene follow-action master switch time: trigger time in beats linked: True = "Longest" mode (waits for longest clip's loop) multiplier: 1-8, used when not linked (time * multiplier = trigger)

Set a scene's follow action (Live 12.2+). Any omitted arg preserves. enabled: on/off master switch for this scene's follow action time: trigger time in beats (e.g. 4.0 = one bar in 4/4) linked: True = "Longest" mode — waits for the longest clip in the scene to complete one loop multiplier: 1-8 — multiplies `time` when not linked. Used to trigger the follow action every N beats.

Disable a scene's follow action (Live 12.2+). Sets follow_action_enabled=False without touching time/linked/ multiplier, so re-enabling preserves the prior configuration.

List all take lanes on a track (Live 12.0+). Returns {lanes: [{index, name, is_frozen, clip_count}]}. Works on any Live 12.x — pure introspection, no version gate. Returns an empty list on tracks that don't expose take_lanes.

Create a new take lane on a track (Live 12.2+). Returns {lane_index, name}. Raises if the Live version predates 12.2 or if the specific build doesn't expose Track.create_take_lane.

Rename an existing take lane (Live 12.2+). Returns {name} — the name after the update (Live may normalize whitespace or reject duplicates in some builds).

Create an arrangement audio clip on a specific take lane (Live 12.2+). start_time / length are in beats. length must be > 0. The track must be an audio track; Live raises on MIDI tracks. Returns {ok, track_index, lane_index, start_time, length}.

Create an arrangement MIDI clip on a specific take lane (Live 12.2+). start_time / length are in beats. length must be > 0. The track must be a MIDI track; Live raises on audio tracks. Returns {ok, track_index, lane_index, start_time, length}.

List the arrangement clips on a specific take lane (Live 12.0+). Returns {clips: [{name, start_time, length, is_midi_clip}]}. Pure introspection — no version gate.

Get detailed info about a clip: name, length, loop, launch settings.

Create an empty MIDI clip in a clip slot (length in beats).

Delete a clip from a clip slot. This removes all notes and automation. Use undo to revert.

Rename a clip in the Session view. The new name appears on the clip slot and in Device Chain displays.

Set clip color (0-69, Ableton's color palette).

Enable/disable clip looping and optionally set loop start/end (in beats). All parameters are optional but at least one must be provided.

Set clip launch mode (0=Trigger, 1=Gate, 2=Toggle, 3=Repeat) and optional quantization.

Set pitch transposition and/or gain on an audio clip (BUG-A5). Audio clips only. Use this to correct sample pitch to match session key (e.g. a D#min Splice clip in a Dm session -> coarse=-1). coarse: semitones, -48..+48 fine: cents, -50..+50 gain: linear, 0..1 (Live's internal scale, not dB) At least one of coarse/fine/gain must be provided.

Set warp mode for an audio clip (0=Beats, 1=Tones, 2=Texture, 3=Re-Pitch, 4=Complex, 6=Complex Pro).

Cross-check a clip's filename-encoded key against the session key (BUG-D1). Splice-style sample filenames encode the sample's key (e.g. ``AU_THF2_128_vocal_..._D#min.wav``). This tool parses that token, compares it to the analyzer-detected session key, and — when they disagree — computes the semitone delta needed to realign, returning the exact ``set_clip_pitch(coarse=...)`` call that would correct it. Return shape:: { "track_index": 6, "clip_index": 0, "filename_key": {"root": "D#", "mode": "minor", "token": "D#min"}, "session_key": {"root": "D", "mode": "minor"}, "status": "mismatch" | "match" | "unknown", "semitone_delta": -1, # clip needs to shift DOWN 1 "recommended_fix": { "tool": "set_clip_pitch", "args": {"track_index": 6, "clip_index": 0, "coarse": -1} }, "reason": "Clip is D#min, session is Dm — shift -1 semitone." } Returns ``status="unknown"`` (not an error) when: - the clip is MIDI (no audio file path) - the filename has no parseable key token - the analyzer hasn't detected a session key yet Requires the M4L bridge for both ``get_clip_file_path`` and ``get_detected_key``. Degrades gracefully without it.

Read a clip's per-clip scale override (Live 12.0+). Per-clip scales are independent of Song.scale_*. A clip can have Scale Mode enabled with a different root/name than the Song. Returns {root_note (0-11), scale_mode (bool), scale_name (str)}. Raises if the clip slot is empty.

Set a clip's per-clip scale override (Live 12.0+). Overrides the Song-level scale for this clip only. Useful for key changes within a set, or for clips that live in a different mode than the rest of the arrangement. root_note: 0-11 (C=0, C#=1, ... B=11) scale_name: must match one of Live's built-in scales (call list_available_scales() if unsure)

Enable or disable Scale Mode on a single clip (Live 12.0+). When enabled on a clip, its notes are constrained/highlighted by the clip's own root_note + scale_name (set via set_clip_scale).

Attempt to reconnect the M4L UDP bridge (port 9880). Use this when the bridge was unavailable at server startup (port conflict) but is now free. Binds the UDP listener so spectral analysis and bridge commands become available without restarting the MCP server.

Add a warp marker to an audio clip at the specified beat position. Warp markers pin audio to beats, enabling time-stretching of surrounding regions. Add at downbeats to lock timing, then move them for tempo changes. Only works on audio clips. Requires LivePilot Analyzer on master track.

Remove a warp marker from an audio clip at the specified beat. Only works on audio clips. Requires LivePilot Analyzer on master track.

Get 9-band frequency analysis of the master bus. Values 0.0-1.0. Bands (low->high): sub_low (20-60Hz), sub (60-120Hz), low (120-250Hz), low_mid (250-500Hz), mid (500Hz-1kHz), high_mid (1-2kHz), high (2-4kHz), presence (4-8kHz), air (8-20kHz). Full Hz-range/use-case table: livepilot-core references/perception.md#get_master_spectrum-9-band-table. Legacy pre-v1.16 .amxd builds emit 8 bands (no sub_low split) — auto-detected from the OSC payload. Also returns detected key/scale if enough audio has been analyzed. Requires LivePilot Analyzer on master track. window_ms (default 0): 0 returns a single instantaneous snapshot. >0 (max 10000) mean-pools `samples` readings (default window_ms/50, min 3, max 100) over that window instead — use for a stable mix read since single frames swing wildly on transients. Also returns bands_min/bands_max/bands_std for variance across the window, plus distinct_frames (unique analyzer frames seen — duplicates re-read from a stalled stream don't count) and a warning when duplicates dominate, since bands_std reads 0 over a stalled stream. sub_detail=True: attaches sub_detail {sub_deep 20-45Hz, sub_mid 45-60Hz, sub_high 60-80Hz} derived from the FluCoMa 40-band mel spectrum (requires FluCoMa active; omitted with sub_detail_warning otherwise).

Get real-time RMS and peak levels from the master bus. More accurate than LOM meters — includes true RMS (not just peak hold). Pitch readings are validated: the field is only present when the polyphonic pitch detector produced a reading with non-zero amplitude and a MIDI note in [0, 127] (BUG-F1). Requires LivePilot Analyzer on master track.

Get the detected musical key and scale of the current session. Uses the Krumhansl-Schmuckler key-finding algorithm on accumulated pitch data from the master bus. Needs 4-8 bars of audio to be reliable. Returns key (C, C#, D, etc.), scale (major/minor), and confidence (number of pitch samples collected). Requires LivePilot Analyzer on master track.

Get ALL parameters for a device, including hidden ones not accessible via the standard ControlSurface API. Returns parameter name, value, min, max, default, automation state, and value string for every parameter — even non-automatable ones. Requires LivePilot Analyzer on master track.

Get automation state for all parameters on a device. Returns only parameters that HAVE automation: - state 1 = automation active (envelope is playing) - state 2 = automation overridden (user moved knob manually) Use this before writing automation to avoid overwriting existing curves. Requires LivePilot Analyzer on master track.

Walk the full device chain tree including nested racks, drum pads, and grouped devices. Returns the complete hierarchy up to 6 levels deep. Use this to see inside Instrument Racks, Effect Racks, and Drum Racks that the standard get_device_info can't penetrate. Requires LivePilot Analyzer on master track.

Get the audio file path of a clip on disk. Returns the absolute path to the audio file, clip name, and length. Only works on audio clips — MIDI clips have no file path. Use this to get a path for replace_simpler_sample. Requires LivePilot Analyzer on master track.

Load an audio file into a Simpler device by absolute file path. Replaces the currently loaded sample. The Simpler must already have a sample loaded — this cannot load into an empty Simpler. If empty, load a sample manually first or use find_and_load_device to load a preset that already contains a sample. **Prefer `load_browser_item(track, uri)` when the file is browser- indexed** — more reliable (see livepilot-core references/ perception.md#replace_simpler_sample--load_sample_to_simpler). This tool verifies by reading back the device name post-load and returns an error if the replace didn't actually take effect. Nested addressing (Live 12.4+ only): when `chain_index` is provided, the device is resolved at `track.devices[device_index] .chains[chain_index].devices[nested_device_index or 0]` — how Drum Rack pad-by-pad construction works (see `add_drum_rack_pad` for the high-level workflow). Only the native 12.4 path honors chain_index; the M4L bridge fallback cannot resolve nested paths. Also auto-applies post-load hygiene: - Sets Simpler Snap=0 (required for playback after replace) - For warped loops (filename contains 'NNbpm'), sets S Start=0, S Length=1, S Loop On=1 Use get_clip_file_path to get the path of a resampled clip, then pass it here to load it into Simpler for slicing. Requires LivePilot Analyzer on master track.

Move a warp marker from one beat position to another. Changes the tempo of the audio segment between this marker and its neighbors. Moving later = slower, moving earlier = faster. Use for tape-stop effects, tempo ramps, and groove manipulation. Only works on audio clips. Requires LivePilot Analyzer on master track.

Load an audio file into a NEW Simpler device on a track. Creates a Simpler (native insert+replace on Live 12.4+; a bootstrap-sample-then-replace workaround on earlier versions), applies post-load hygiene (Snap=0, loop defaults for warped loops), then verifies by reading back the device name — errors if the Simpler still has the bootstrap placeholder. Full rationale: livepilot-core references/perception.md #replace_simpler_sample--load_sample_to_simpler. Use this instead of replace_simpler_sample when the track has no Simpler or the Simpler is empty. Works with any audio file path. **For files that exist in Ableton's browser index** (Samples, User Library, Packs), PREFER `load_browser_item(track, uri)` — more reliable. This tool is a workaround for non-browser-indexed files. Requires LivePilot Analyzer on master track.

Add a new pad (chain) to a Drum Rack and load a sample into it — atomic. One call does the full build: locate/auto-detect the Drum Rack (auto-detect searches for class_name containing "DrumGroupDevice"), insert a new chain, assign the trigger note, insert an empty Simpler into that chain, native-replace the sample with nested addressing, Snap=0 post-load. Full history: livepilot-core references/ perception.md#add_drum_rack_pad. Requires Live 12.4+ for the nested-addressing sample load. On earlier versions returns an error directing to the bridge-based workaround (call insert_rack_chain / set_drum_chain_note / insert_device / replace_simpler_sample individually). track_index: track containing the Drum Rack pad_note: MIDI note for the pad (0..127). Standard drum map: 36=Kick, 38=Snare, 42=Closed HH, 46=Open HH. file_path: absolute path to the audio file rack_device_index: optional device_index of the Drum Rack on the track. If None, auto-detects the first Drum Rack. chain_name: optional display name for the new chain. Returns {ok, track_index, rack_device_index, chain_index, pad_note, nested_device_index (where the Simpler landed), device_name, method:"native_12_4"}.

Get slice point positions from a Simpler device. Returns each slice's position in frames and seconds, the MIDI pitch that triggers it (slice 0 = C1 / MIDI 36, slice 1 = C#1 / MIDI 37, etc. per BUG-F2), plus sample metadata (sample rate, length, playback mode). **Always use the returned `midi_pitch` when programming MIDI notes to trigger slices.** The Live 12 Simpler Slice-mode base note is C1, NOT C3 — writing notes at pitch 60+ on a sample with <24 slices triggers nothing and produces silent output. Use this to understand the rhythmic structure of a sliced sample and program MIDI patterns targeting slices. Requires LivePilot Analyzer on master track.

Classify each Simpler slice as KICK / SNARE / HAT / ghost via FFT analysis. Reads slice positions via ``get_simpler_slices``, loads the backing WAV file, and runs 4-band spectral classification on each segment. Returns the enriched slice list with a ``label`` field per entry plus feature breakdown (peak, rms, sub_pct, low_pct, mid_pct, high_pct). **Always run this before programming drum patterns on a sliced break.** Slice content depends on transient detection order in the source audio — slice 0 is NOT guaranteed to be a kick. Assuming drum-rack convention produces wrong grooves that take iterations to diagnose. Classification thresholds: livepilot-core references/ perception.md#classify_simpler_slices--classification-thresholds (KICK: sub+low >= 45%, high < 40%. HAT: high >= 70% AND mid < 25%. SNARE: mid >= 25% AND high >= 40% AND peak >= 0.6. ghost: peak < 0.35). Parameters: track_index, device_index: the Simpler to analyze file_path: (optional) explicit WAV path. If omitted, resolved automatically via Remote Script then M4L bridge fallback. Pass explicitly only against a stale .amxd freeze that predates auto-resolution (returns the bridge error string so the caller knows to re-freeze). Returns: dict with ``slices`` list. Each slice entry has: index, frame, seconds, midi_pitch (36+index), label, peak, rms, sub_pct, low_pct, mid_pct, high_pct. Requires LivePilot Analyzer on master track.

Crop a Simpler's sample to the currently active region. Destructive — removes audio outside the region. Use undo to revert. Requires LivePilot Analyzer on master track.

Reverse the sample loaded in a Simpler device. Can be called again to un-reverse. Requires LivePilot Analyzer on master track.

Warp a Simpler's sample to fit the specified number of beats. The sample will time-stretch to match the project tempo at the given beat count. E.g., beats=4 makes it exactly 1 bar at current tempo. Requires LivePilot Analyzer on master track.

Get all warp markers from an audio clip. Returns each marker's beat_time (position in arrangement) and sample_time (position in the original audio file). Use this to understand timing, extract groove templates, or prepare for manipulation. Only works on audio clips. Requires LivePilot Analyzer on master track.

Scrub/preview a clip at a specific beat position. Plays audio from that position until stop_scrub is called. Use to audition sections, preview slices, or find the right warp marker spot. Requires LivePilot Analyzer on master track.

Stop scrubbing a clip. Call after scrub_clip to stop preview. Requires LivePilot Analyzer on master track.

Get human-readable display values for all device parameters. Returns the value as shown in Live's UI (e.g., '440 Hz', '-6.0 dB', '50 %') instead of raw normalized floats. Skips irrelevant parameters. Requires LivePilot Analyzer on master track.

Capture audio from Ableton Live to a WAV file on disk. Records from the specified source (currently 'master') for the given duration. Files are written to ~/Documents/LivePilot/captures/. If filename is empty, a timestamped name is generated automatically. The captures folder keeps the newest 200 audio files — older captures are evicted automatically after each new capture. Returns the path to the written file and capture metadata (plus a ``warning`` field if the file could not be confirmed flushed). Requires LivePilot Analyzer on master track.

Stop an in-progress audio capture early. Tells the M4L bridge to stop recording, relocates the partial file into the captures directory, and resolves the in-flight capture_audio call with a partial result (stopped_early=True) carrying the final file_path — so both this call and the original capture_audio call learn where the partial recording landed (review 2026-07-30). Requires LivePilot Analyzer on master track.

Get 7 real-time spectral descriptors from FluCoMa. Returns centroid, spread, skewness, kurtosis, rolloff, flatness, crest. Requires FluCoMa package in Max.

Get 40-band mel spectrum from FluCoMa (5x resolution of get_master_spectrum). Requires FluCoMa package in Max.

Get 12 pitch class energies from FluCoMa for real-time chord detection. Requires FluCoMa package in Max.

Get real-time onset/transient detection from FluCoMa. Requires FluCoMa package in Max.

Get real-time spectral novelty for section boundary detection from FluCoMa. Requires FluCoMa package in Max.

Fire a test MIDI note at a track's instrument and check for output. parameter_count alone can't tell you whether an AU/VST is alive — plenty of "loaded" plugins return N params and silence. Real-world check: snapshot the track meter, emit a MIDI note at the specified pitch/velocity, sample the meter for `test_duration_ms` (peak across samples, dodging a left=right=0-while-level>0 meter artifact), and compare the peak to `threshold`. Common dead-device causes and history: livepilot-core references/perception.md#verify_device_health--verify_all_devices_health. track_index: track with the instrument to verify test_midi_note: pitch to fire (default C3 / 60 — safe for most samples) test_velocity: 1-127 (default 100) test_duration_ms: capture window for the meter (default 300ms) threshold: peak level below which the device is considered dead (default 0.005 — roughly -46 dBFS) Returns {ok, alive, peak_level, threshold, samples_taken, hint (actionable advice when dead)}. Requires LivePilot Analyzer on master track and a playable instrument on the target track. Prefer this over trying to eyeball parameter_count.

Run verify_device_health across every eligible track in one call. Session-wide silent-track detector. Useful right after opening a project to surface dead plugins before mixing. Serial execution — firing notes in parallel would make the meter readings ambiguous. skip_audio_tracks: audio tracks have no MIDI input, skip them (default True) skip_empty_tracks: tracks without any instrument also skip (default True) Returns: { "ok": bool, "tracks_tested": int, "alive": [track_index...], "dead": [{track_index, track_name, peak_level}...], "skipped": [{track_index, reason}...], }

Get EBU R128 momentary LUFS + true peak from FluCoMa. Real-time LUFS metering — industry standard. Complements get_master_rms. Requires FluCoMa package in Max.

Analyze the currently-playing master output's loudness over a window (LIVE). Use this tool during a session — no rendered file needed. For offline analysis of an exported audio file use analyze_loudness() instead. Samples the LivePilot analyzer's realtime momentary LUFS / true peak stream over `window_sec` and reports integrated + max statistics. Requires FluCoMa package in Max and playback to be running. Best called while the section you want to measure is actually playing. window_sec: capture duration in seconds (default 10, max 120) sample_interval_ms: ms between samples (default 200 ≈ 5 Hz) Returns: { "integrated_lufs": float, # mean momentary LUFS over window "max_momentary_lufs": float, # peak momentary reading "min_momentary_lufs": float, # quietest reading "range_lu": float, # max - min (proxy for LRA) "max_true_peak_dbtp": float, # max true peak across window "samples_collected": int, "distinct_frames": int, # unique analyzer frames (duplicates # re-read from a stalled stream don't # count; a warning is attached when # duplicates dominate) "window_sec": float, "is_playing": bool, }

Check if FluCoMa is installed and sending data.

Toggle a Simpler's sample warping + set the warp algorithm (BUG-A2). Python's Remote Script ControlSurface API can't reach Simpler's `warping` or `warp_mode` — they live on the sample child object (SimplerDevice.sample.*) that only Max for Live's JavaScript LiveAPI can step into. This tool routes through the M4L bridge to do the write. When enabling warping, pass the desired warp_mode too so Live doesn't default to whatever was there last: warp_mode 0 = Beats (good for drums / percussive loops) warp_mode 1 = Tones (mono harmonic material) warp_mode 2 = Texture (poly / ambient material) warp_mode 3 = Re-Pitch (classic pitch-shift feel) warp_mode 4 = Complex (music / full mixes — higher CPU) warp_mode 6 = Complex Pro (highest quality — highest CPU) Args: track_index: 0+ for regular tracks device_index: Simpler device's position in the chain warping: True → enable sample warp; False → disable warp_mode: 0-6 (omit to leave the current mode unchanged) Requires LivePilot Analyzer on master track.

Configure a Compressor's sidechain INPUT ROUTING (BUG-A3). Complements set_device_parameter's `S/C On` toggle: that enables the sidechain, this picks WHICH track/channel feeds the detector. The routing properties (`sidechain_input_routing_type`, `sidechain_input_routing_channel`) aren't in Compressor's automatable parameter list, but Python's Remote Script reaches them directly as device properties (same LOM pattern as set_track_routing). Args: track_index: 0+ regular, -1/-2 returns, -1000 master device_index: Compressor position in the chain source_type: sidechain source display name (e.g. "1-Kick", "Ext. In", "No Input") source_channel: tap point on the source (e.g. "Post FX", "Pre FX", "Post Mixer") Omit a param to leave that property unchanged. If a display name doesn't match, the error message includes the full list of available options from the running Live session. Routes through the Remote Script (TCP) — does NOT require the M4L analyzer. This is the Python-side path introduced after the M4L bridge approach hit LiveAPI shape issues in Live 12.3.6.

Idempotent pre-flight: load LivePilot_Analyzer on master if missing. Safe to call at the start of any session or before any move that declares analyzer dependency. Calling it repeatedly is cheap — subsequent calls short-circuit via a single get_master_track read. CLAUDE.md invariant: "LivePilot_Analyzer must be LAST on master." This tool reports whether the invariant holds via ``is_last_on_master``; it does NOT move the device (that's a user action in Ableton's GUI). Return shape: - status: one of {"already_loaded", "loaded", "install_required", "failed"} - device_index: int — position of the analyzer on master (when present) - is_last_on_master: bool — True when analyzer is the last device - duplicate_count: int — 2+ when multiple analyzers exist (shouldn't) - warning: str | None — surfaces last-on-master violations - hint: str — actionable next step when status != "already_loaded"/"loaded" - error: str | None — present on status="failed"

Generate a Euclidean rhythm using the Bjorklund algorithm. Distributes pulses as evenly as possible across steps. Identifies known rhythms (tresillo, cinquillo, bossa nova, etc.) when matched. Returns note array — use add_notes to place in a clip.

Stack multiple Euclidean rhythms for polyrhythmic textures. Each layer specifies pulses, steps, pitch, and optional velocity/rotation. Returns combined note array ready for add_notes.

Generate a tintinnabuli voice (Arvo Pärt technique). For each melody note, finds the nearest note of the specified triad. Returns the tintinnabuli voice as a separate note array — combine with the original melody via add_notes for the full Pärt effect. Only major and minor triads are supported.

Generate a phase-shifted canon (Steve Reich technique). Voice 0 loops the pattern normally. Each subsequent voice drifts by shift_amount beats per repetition, creating gradual phase displacement. Returns combined note array with velocity-encoded voices.

Generate an additive process (Philip Glass technique). Forward: builds melody note by note (1, then 1-2, then 1-2-3...). Backward: full melody, then removes from front. Both: forward then backward. Returns note array — use add_notes to place in a clip.

Add MIDI notes to a clip. notes is a JSON array: [{pitch, start_time, duration, velocity?, probability?, velocity_deviation?, release_velocity?}].

Get MIDI notes from a clip region. Returns note_id, pitch, start_time, duration, velocity, mute, probability.

Remove all MIDI notes in a pitch/time region. Use undo to revert. Defaults remove ALL notes in the clip.

Remove specific MIDI notes by their IDs (JSON array of ints). Use undo to revert.

Modify existing MIDI notes by ID. modifications is a JSON array: [{note_id, pitch?, start_time?, duration?, velocity?, probability?}].

Duplicate specific notes by ID (JSON array of ints), with optional time offset (in beats).

Transpose notes in a time range by semitones (positive=up, negative=down). Set arrangement=True to target an arrangement clip by its index in track.arrangement_clips instead of a session clip slot.

Quantize a clip's notes to a grid. grid is a RecordQuantization enum: 0=None, 1=1/4, 2=1/8, 3=1/8T, 4=1/8+T, 5=1/16, 6=1/16T, 7=1/16+T, 8=1/32. amount 0.0-1.0.

Get detailed info about a track: clips, devices, mixer state. BUG-2026-04-22#11 FIX: track_index=-1000 (the master-track convention used by set_track_volume, find_and_load_device, etc.) now dispatches to the get_master_track endpoint instead of rejecting. This makes -1000 work consistently across every track-addressing tool.

Check whether a loaded device is alive (BUG-2026-04-22 #19). Static health check based on get_device_info — no test note required. A device is considered DEAD when: - class_name contains "PluginDevice" (AU/VST) AND parameter_count <= 1 (the shell loaded but the DSP engine crashed / wasn't activated) - health_flags contains "opaque_or_failed_plugin" Returns: {alive: bool, reason: str, parameter_count: int, class_name: str, health_flags: list, recommendation: str | None} The `recommendation` is a one-liner like "delete and load native alternative" when the device is dead. None when alive.

Create a new MIDI track. index=-1 appends at end. `color` and `color_index` are accepted interchangeably (BUG-2026-04-26#3). Both reference Ableton's 0-69 color palette. Pass either; passing both with different values is rejected. Response (v1.20.2+): when `name` is provided, the response carries a ``name_collision`` bool and ``existing_tracks_with_same_name`` list[int]. Downstream role-based resolvers (find_tracks_by_role) match duplicate names and apply mix changes twice — check the warning before proceeding with mix moves on the new track's role.

Create a new audio track. index=-1 appends at end. `color` and `color_index` are accepted interchangeably (BUG-2026-04-26#3). See create_midi_track for full semantics. Response (v1.20.2+): ``name_collision`` + ``existing_tracks_with_same_name`` same as create_midi_track — see BUG #5 rationale there.

Create a new return track.

Delete a track by index. Use undo to revert if needed. Ableton requires at least one track in the session. Attempting to delete the last remaining track raises ValueError with actionable guidance rather than surfacing Ableton's misleading default STATE_ERROR text (BUG-F3).

Duplicate a track (copies all clips, devices, and settings).

Rename a track. The new name appears in both the Session and Arrangement views and survives session save.

Set track color (0-69, Ableton's color palette).

Mute or unmute a track.

Solo or unsolo a track.

Arm or disarm a track for recording.

Stop all playing clips on a track.

Fold or unfold a group track to show/hide its children.

Set input monitoring (0=In, 1=Auto, 2=Off). Only for regular tracks, not return tracks.

Freeze a track — render all devices to audio for CPU savings. Freeze is async in Ableton: this initiates the render and returns immediately. Poll get_freeze_status to check when it's done. Freezing a track that's already frozen is a no-op. Note: freeze() is not available via ControlSurface API in all Live versions. If this fails, use Ableton's Freeze Track menu command (Cmd+F on Mac) manually instead.

Flatten a frozen track — commit rendered audio permanently. Destructive: replaces all devices with the rendered audio file. The track must already be frozen. Use undo to revert.

Check if a track is frozen. Use after freeze_track to poll for completion, or before flatten_track to verify the track is ready to flatten.

Jump playhead within a running session clip, in beats from start.

Read a track's CPU performance impact metric.

Return the Blue Hand (appointed/focused) device location as (track_index, device_index, track_name, device_name).

List all grooves in the Groove Pool (Live 11+). Returns each groove's id (index), name, base quantization grid (integer enum, e.g. 1/16th = 4), quantization_amount, random_amount, timing_amount, and velocity_amount. Use the id with assign_clip_groove() or set_groove_params().

Read a single groove's parameters (Live 11+). groove_id is the index from list_grooves(). Returns the same shape as one entry of list_grooves().

Adjust a groove's parameters (Live 11+). Omitted args preserve. Ranges: quantization_amount, random_amount, timing_amount: 0.0-1.0 velocity_amount: -1.0 to 1.0 (signed — negative subtracts velocity) Any field left unspecified keeps its current value. Returns the full groove_info dict after the update.

Assign a groove to a clip (Live 11+). groove_id: integer index from list_grooves(), or -1 to clear the clip's groove (sets clip.groove = None). Returns {track_index, clip_index, groove_id, groove_name} — both id and name are None when cleared.

Read a clip's current groove assignment (Live 11+). Returns {groove_id, groove_name}. Both are null/None if the clip has no groove assigned.

Read the master groove amount dial (Live 11+). Scales the effect of ALL assigned grooves on playback. 0.0 = no groove influence; 1.0 = nominal; up to 1.31 = exaggerated.

Set the master groove amount dial (Live 11+). Scales all grooves' effect on playback. Range 0.0-1.31. Live's spec nominally caps at 1.0 but the exposed property accepts values up to ~1.31, matching the UI's maximum nudge.

List all automation envelopes on a session clip. Returns which parameters have automation, including device name, parameter name, and type (mixer/send/device). Use this to see what's already automated before writing new curves.

Write automation points to a session clip envelope. parameter_type: "device", "volume", "panning", or "send" points: [{time, value, duration?}] — time relative to clip start (beats) values: 0.0-1.0 normalized (or parameter's actual min/max range) For device params: provide device_index + parameter_index. For sends: provide send_index (0=A, 1=B, etc). Tip: Use apply_automation_shape to generate points from curves/recipes instead of calculating points manually.

Clear automation envelopes from a session clip. If parameter_type is omitted, clears ALL envelopes. If provided, clears only that parameter's envelope.

Generate and apply an automation curve to a session clip. Combines curve generation with clip automation writing in one call. curve_type: linear, exponential, logarithmic, s_curve, sine, sawtooth, spike, square, steps, perlin, brownian, spring, bezier, easing, euclidean, stochastic duration: curve length in beats density: number of automation points time_offset: shift the entire curve forward by N beats Curve-specific params: - linear/exp/log: start, end, factor (steepness 2-6) - sine: center, amplitude, frequency, phase - sawtooth: start, end, frequency (resets per duration) - spike: peak, decay (higher = faster) - square: low, high, frequency - s_curve: start, end Musical guidance: - Filter sweeps: use exponential (perceptually even) - Volume fades: use logarithmic (matches ear's response) - Crossfades: use s_curve (natural acceleration/deceleration) - Pumping: use sawtooth with frequency matching beat divisions - Throws: use spike with short duration (1-2 beats) - Tremolo/pan: use sine with frequency in musical divisions

Return Live's built-in scale names (Live 12.0+). Use before set_song_scale() to validate names or offer the user a list. Returns e.g. ["Major", "Minor", "Dorian", "Mixolydian", ...].

Read the current Tuning System state (Live 12.1+). Exposes Ableton's microtonal tuning: name, pseudo-octave size (in cents), note range, reference pitch (Hz), and per-degree cent offsets from 12-TET. Use for maqam, just intonation, or any non-12-TET workflow.

Set the Tuning System's reference pitch in Hz (Live 12.1+). Default is 440.0. Common alternatives: 432.0 (A432), 415.3 (Baroque).

Apply a named automation recipe to a session clip. Recipes are predefined curve shapes for common production techniques. Use get_automation_recipes to list all available recipes. Available recipes: - filter_sweep_up: LP filter opening (exponential, 8-32 bars) - filter_sweep_down: LP filter closing (logarithmic, 4-16 bars) - dub_throw: send spike for reverb/delay throw (1-2 beats) - tape_stop: pitch dropping to zero (0.5-2 beats) - build_rise: tension build on HP filter + volume (8-32 bars) - sidechain_pump: volume ducking per beat (sawtooth, 1 beat loop) - fade_in / fade_out: perceptually smooth volume fades - tremolo: periodic volume oscillation - auto_pan: stereo movement via pan sine - stutter: rapid on/off gating - breathing: subtle filter movement (acoustic instrument feel) - washout: reverb/delay feedback increasing - vinyl_crackle: slow bit reduction movement - stereo_narrow: collapse to mono before drop

List all available automation recipes with descriptions. Each recipe includes: curve type, description, typical duration, and recommended target parameter. Use apply_automation_recipe to apply any recipe to a clip.

Generate automation curve points WITHOUT writing them. Returns the points array for preview/inspection. Use this to see what a curve looks like before committing it to a clip. Pass the returned points to set_clip_automation or set_arrangement_automation to write them.

Analyze a track's spectrum and suggest automation targets. Reads the track's current spectral data and device chain, then suggests which parameters would benefit from automation based on the frequency content and device types present. Requires LivePilot Analyzer on master track and audio playing.

Write an arrangement automation envelope at a specific beat via session record. Workaround for the Live LOM limitation that prevents direct writing of track-level arrangement automation outside of an existing arrangement clip. Creates a temporary session clip with the automation, arms the track, records the clip into arrangement at target_beat, then cleans up. The recorded arrangement clip has the automation baked in. **Status: LIVE** as of 2026-04-22. Uses a two-phase protocol so Live's main thread never blocks: phase 1 (start) fires the session clip into arrangement record; this tool then asyncio.sleeps for the expected record duration (computed from the live tempo that phase 1 returns); phase 2 (complete) stops record, cleans up, and returns the new arrangement clip's index + start/length. Total wall time ≈ duration_beats × 60/tempo + 0.5s handler overhead. parameter_type: "device" | "volume" | "panning" | "send" points: [{time, value, duration?}] — time relative to the session clip's start (0.0 = first beat) target_beat: where the recording should begin in the arrangement timeline (beats) duration_beats: how long to record (usually matches the session clip's natural length, but may be longer for multiple repeats) session_clip_slot: which session clip slot to use (default 0 — must be EMPTY or its current content will be overwritten) device_index, parameter_index: required for parameter_type="device" send_index: required for parameter_type="send" (0=A, 1=B) cleanup_session_clip: delete the temp session clip after recording completes (default True) Returns a dict with the recorded arrangement clip index + verification info, or an error if any step failed. Because this orchestrates a real-time recording, any of the steps can fail at runtime (track not armable, session clip already running, transport not cooperating). Each failure is reported with the stage it happened at.

Read Live's current Scale Mode state (Live 12.0+). Returns: root_note: 0-11 (C=0, C#=1, ... B=11) scale_mode: bool — is Scale Mode currently enabled scale_name: e.g. "Major", "Minor Pentatonic", "Dorian" scale_intervals: tuple of semitone offsets from root_note available_scales: all scale names Live knows about Prefer this over our own `identify_scale` detector when you want the user's actual Live selection rather than an audio-detected key.

Set the Song-level Scale Mode root + scale name (Live 12.0+, Live 12.4 compat). root_note: int 0-11 (C=0, C#=1, ... B=11) OR note-name string like "C#", "F", "Bb". Both are accepted — BUG-2026-04-22#2 fix. scale_name: case-insensitive — matches Live's built-in scale names. Call list_available_scales() first if unsure. Live 12.4 note: Ableton dropped `Song.scale_names` from the Python LOM, which made this tool and list_available_scales raise an INTERNAL error. The remote script now falls back to the documented built-in scale list when the attribute is missing — so both tools work on 12.4+ again.

Enable or disable Scale Mode on the current set (Live 12.0+). When enabled, Live's MIDI input and some devices become scale-aware.

Adjust the cent offset for a single scale degree (Live 12.1+). degree: 0-based scale-degree index (length depends on the loaded tuning system — call get_tuning_system() first to see the note_tunings array length). cent_offset: cents from 12-TET. Examples: -13.686 -> pure minor third +1.955 -> pure major third (third harmonic)

Reset all per-degree tuning offsets to 12-TET (Live 12.1+). Clears all per-note microtonal offsets. Doesn't change the tuning system's name or reference pitch — just the offsets.

Get all arrangement clips on a track.

Jump to a specific beat time in the arrangement.

Capture recently played MIDI notes into a new clip.

Start recording. arrangement=True for arrangement, False for session.

Stop all recording (both session and arrangement).

Get all cue points in the arrangement.

Jump to a cue point by index.

Set or delete a cue point at the current playback position.

Duplicate a session clip into Arrangement View at a specific beat position. clip_slot_index: which session clip slot to use as the source pattern start_time: beat position in arrangement (0.0 = song start, 4.0 = bar 2) length: total clip length in beats on the timeline loop_length: pattern length to loop within the clip (e.g. 8.0 for an 8-beat pattern inside a 128-beat section). Defaults to the source clip's length. Must be > 0. Copies are tiled every min(loop_length, source length) beats so the region is always filled seamlessly — a loop_length larger than the source no longer leaves a silent gap between copies. When loop_length < source length, overlapping copies are placed every loop_length beats and each copy's internal loop region is set to loop_length beats (Ableton's "later clip takes priority" rule ensures correct playback). name: optional clip display name color_index: optional 0-69 Ableton color Returns clip_index in the track's arrangement_clips list.

Create an empty MIDI clip directly in Arrangement View (Live 12.1.10+). Unlike create_arrangement_clip (which duplicates a session clip), this creates a native arrangement clip with full automation envelope support — volume rides, filter sweeps, send automation all work natively. Requires Live 12.1.10+. Falls back with a clear error on older versions. track_index: 0+ for regular MIDI tracks start_time: beat position (0.0 = song start, 4.0 = bar 2 in 4/4) length: clip length in beats name: optional clip display name color_index: optional 0-69 Ableton color

Add MIDI notes to an arrangement clip. clip_index: index in track.arrangement_clips (returned by create_arrangement_clip or get_arrangement_clips) notes: list of dicts with: pitch (0-127), start_time (beats, relative to clip start), duration (beats), velocity (1-127), mute (bool) start_time in notes is relative to the clip start, not the song timeline.

Write automation envelope points into an arrangement clip. parameter_type: "device", "volume", "panning", or "send" points: list of {time, value, duration?} dicts — time is relative to clip start (0.0 = first beat of clip), value is the parameter's native range (0.0-1.0 for most, check get_device_parameters for exact min/max). duration defaults to 0.125 beats (step automation). For smooth ramps, use many closely-spaced points. For parameter_type="device": device_index + parameter_index required. For parameter_type="send": send_index required (0=A, 1=B, ...).

Transpose notes in an arrangement clip by semitones (positive=up, negative=down). clip_index: index in track.arrangement_clips (from get_arrangement_clips) semitones: number of semitones to shift (-127 to 127) from_time: start of note range (beats, relative to clip start) time_span: length of note range in beats (defaults to full clip)

Rename an arrangement clip by its index in the track's arrangement_clips list.

Switch playback from session clips back to the arrangement timeline.

Force ALL tracks to follow the arrangement and start playback. Atomically: stops all session clips, releases every track from session override, sets back-to-arranger, jumps to position, and starts playing. This is the "play my arrangement from the top" command. beat_time: position to start from (default 0 = beginning) loop_start: loop region start in beats (default 0) loop_length: loop region length in beats (0 = no loop change) play: whether to start playback (default True)

Get MIDI notes from an arrangement clip. Returns note_id, pitch, start_time, duration, velocity, mute, probability. Times are relative to clip start.

Remove all MIDI notes in a pitch/time region of an arrangement clip. Defaults remove ALL notes.

Remove specific MIDI notes from an arrangement clip by their IDs.

Modify existing MIDI notes in an arrangement clip by ID. modifications is a JSON array: [{note_id, pitch?, start_time?, duration?, velocity?, probability?}].

Duplicate specific notes in an arrangement clip by ID, with optional time offset (beats).

Get info for all scenes: name, tempo, color.

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

Delete a scene by index. Use undo to revert if needed.

Duplicate a scene (copies all clip slots).

Fire (launch) a scene, triggering all its clips.

Rename a scene. Pass empty string to clear the name.

Set scene color (0-69, Ableton's color palette).

Set scene tempo in BPM (20-999). Fires when the scene launches.

Get the full session clip grid: every track x every scene. Returns clip states (empty/stopped/playing/triggered/recording), clip names, and colors. Use this for a bird's-eye view of the entire session before making clip launch decisions.

Fire a scene, optionally filtering to specific tracks. If track_indices is omitted, fires the entire scene (all tracks). If provided (JSON array of ints), fires only those tracks' clip slots from the scene — useful for launching drums + bass without triggering the lead, or building up layers gradually.

Stop all playing clips in the session. Panic button.

Get all currently playing or triggered clips. Returns track index/name, clip index/name, and whether each clip is actively playing or just triggered (waiting for quantization).

Build a reference profile from an audio file or style/genre name. Provide either reference_path (for audio comparison) or style (for style tactic lookup). If both are provided, audio takes priority. Args: reference_path: Absolute path to a reference audio file (.wav, .flac, .aiff). mix_path: Absolute path to your bounced mix file (required for audio comparison). style: Artist or genre name (e.g. "burial", "techno", "lo-fi"). Returns: ReferenceProfile as dict with source_type, loudness_posture, spectral_contour, width_depth, density_arc, section_pacing, harmonic_character, transition_tendencies.

Analyze gaps between your project and a reference. Computes deltas across spectral, loudness, width, density, pacing, and harmonic domains. Flags which gaps are relevant and which would destroy your project's identity if closed. Args: reference_path: Absolute path to a reference audio file. mix_path: Absolute path to your bounced mix file (required for audio comparison). style: Artist or genre name for style-based comparison. goal_dimensions: Comma-separated domains to focus on (e.g. "spectral,width"). Empty = all domains. Returns: GapReport as dict with gaps, relevant_gaps, identity_warnings, and overall_distance.

Plan concrete moves to close reference gaps. Builds a reference profile, analyzes gaps, then routes each gap to the appropriate engine (mix_engine or composition) with ranked tactics and identity warnings. Args: reference_path: Absolute path to a reference audio file. mix_path: Absolute path to your bounced mix file (required for audio comparison). style: Artist or genre name for style-based comparison. goal_dimensions: Comma-separated domains to focus on. Returns: ReferencePlan as dict with gap_report, ranked_tactics, and target_engines.

Run the §5 layer-precision audit on a single track in one call. Replaces 8 manual checks (timbre, sequence, stereo, masking, modulation, params, samples, effects) with one server-side aggregation. Returns structured report with PASS/WARN/FAIL per check + ranked fixes. Args: track_index: Track to audit. role: Optional role override ("kick"/"snare"/"hat"/"perc"/"bass"/ "pad"/"lead"/"atmos"/"vox"/"fx"). If omitted, inferred from track name + first instrument class. include_masking: If True (default), pulls cross-track masking report and filters for this track. Adds ~200-600ms. include_timbre: If True, pulls per-track timbre fingerprint via the M4L bridge. Costs an extra spectral read; default False so the tool stays fast on bridge-less sessions. Returns one structured report — no follow-up calls needed.

Build a full Project Brain snapshot from the current Ableton session. Gathers session info, scenes, clip matrix, track infos with device data, builds all five subgraphs (session, arrangement, role, automation, capability), and returns the canonical project state. This is the primary entry point for engines that need a coherent view of the project. Call once at session start, then use scoped refreshes.

Get a lightweight Project Brain summary — track count, section count, stale status. Faster than build_project_brain when you just need an overview. Builds session graph only, skips deep inference.

Apply creative constraints to focus suggestions. Constraints modify planning and ranking, not just validation. When stuck, try adding constraints instead of more unconstrained advice. Available constraints: - use_loaded_devices_only — only use what's already loaded - no_new_tracks — work within existing tracks - subtraction_only — only remove/reduce, no additions - arrangement_only — only structural changes - mood_shift_without_new_fx — shift mood with existing tools - make_it_stranger_but_keep_the_hook — push novelty safely - club_translation_safe — keep changes club/DJ-friendly - performance_safe_creative — only live-safe changes constraints: list of constraint names to activate

Learn musical principles from a reference — not surface traits. Extracts: emotional posture, density motion, arrangement patience, texture treatment, width strategy, and payoff architecture. Never outputs a plan that copies surface traits directly. Always translates through the current song's identity. reference_description: text description of the reference style_name: optional style/genre name for style-based references

Map distilled reference principles to the current song. Must call distill_reference_principles first. Translates each principle through the song's identity, loaded tools, and hook. Returns actionable mappings — how to apply each principle while preserving the song's own character.

Generate creative variants under active constraints. Combines constraint filtering with the Preview Studio's triptych. Each variant respects the constraint set — e.g., "subtraction_only" means no variant adds new elements. request_text: what the user wants constraints: list of constraint names to apply (or uses currently active) kernel_id: optional session kernel reference

Generate creative variants inspired by a distilled reference. Requires a prior call to distill_reference_principles. Uses the distilled principles (not surface traits) to shape each variant through the current song's identity. request_text: optional extra context for what the user wants kernel_id: optional session kernel reference

Evaluate a move using the unified Evaluation Fabric. Routes to the appropriate engine-specific evaluator. Args: engine: "sonic", "composition", "mix", "transition", or "translation" before_snapshot: State before the move (format depends on engine) after_snapshot: State after the move (format depends on engine) targets: Goal targets — for sonic: {dimension: weight}, ignored for others protect: Protected dimensions — for sonic: {dimension: threshold} Returns: EvaluationResult as dict with score, keep_change, goal_progress, collateral_damage, dimension_changes, notes, etc.

Detect repetition fatigue — are patterns overused? Analyzes clip reuse across scenes, motif overuse, and section staleness. Returns fatigue level (0=fresh, 1=stale), specific issues, and recommendations. Use this when the track "feels repetitive" or when arrangement has been looping without variation.

Detect role conflicts — are tracks fighting for the same musical space? Checks for: multiple bass tracks, competing leads, overlapping drum layers. Also flags missing essential roles (no bass, no drums). Returns conflict list with severity and recommendations.

Infer what each section/scene is trying to do musically. Labels each scene as: setup, tension, payoff, contrast, release, development, or outro — based on density, position, and energy changes. Use this to understand the song's structure before making arrangement decisions.

Score the emotional arc of the arrangement. Measures: arc clarity (build→climax→resolve), contrast between sections, payoff strength (does the climax feel earned?), and resolution (does it end well?). Returns an overall score (0-1) and specific issues with recommendations.

Analyze a captured audio phrase for musical quality. Evaluates: arc clarity, contrast, fatigue risk, payoff strength, identity strength, and translation risk. file_path: path to a captured audio file (from capture_audio) target: what the phrase is ("loop", "drop", "chorus", "transition", "intro", "outro") Requires capture_audio + analyze_loudness + analyze_spectrum_offline first.