livepilot

██╗     ██╗██╗   ██╗███████╗██████╗ ██╗██╗      ██████╗ ████████╗
██║     ██║██║   ██║██╔════╝██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝
██║     ██║██║   ██║█████╗  ██████╔╝██║██║     ██║   ██║   ██║
██║     ██║╚██╗ ██╔╝██╔══╝  ██╔═══╝ ██║██║     ██║   ██║   ██║
███████╗██║ ╚████╔╝ ███████╗██║     ██║███████╗╚██████╔╝   ██║
╚══════╝╚═╝  ╚═══╝  ╚══════╝╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝

[!NOTE] LivePilot works with any MCP client, including Claude Code, Claude Desktop, Codex, Cursor, VS Code, and Windsurf. Changes inside the Live set use Ableton's undo stack. Downloads, saved memory, library scans, and installer changes happen outside the set and cannot be undone from Ableton.

[!WARNING] LivePilot is moving quickly. Pin a version for repeatable studio or live-performance setups, and check the changelog before updating.

---

Start Here

The setup wizard installs the Ableton Remote Script, creates the Python environment, copies the Max for Live Analyzer, and checks the connection:

npx livepilot --setup

Using Claude Desktop? Download the latest livepilot-<version>.mcpb from Releases and double-click it.

See Install for client-specific setup and manual options.

---

What's New in v1.30.0

LivePilot now spends far less context describing itself and gives clearer answers about what it actually knows.

• A focused first contact. Normal sessions advertise 28 useful entry points instead of sending all 474 schemas up front. The rest remain searchable and directly callable.
• Options that mean something. Decorative Composer, Atlas, and routing parameters are gone; sample roles and material filters now change the result; unsupported abstract events fail with concrete guidance instead of disappearing silently.
• Evidence with a label. Mix and evaluation reports separate measured audio, setup-derived heuristics, and artistic judgment. “Less bright” and other reduction goals now score in the right direction.
• Depth when it earns its keep. Quick creative requests take a quick path. Three-way exploration, broad memory reads, and full critic passes are reserved for real ambiguity.
• More resilient sessions. Startup no longer waits on optional services, ambiguous network failures do not replay destructive edits, and project memory follows the Live set rather than ordinary edits inside it.

Previous release v1.29.0 introduced learned perceptual taste, honest confidence gates, optional CLAP distance, and named Arrangement locators.

Full details in the CHANGELOG.

---

What LivePilot Does

LivePilot works at two levels: exact control when you know what you want, and informed help when you do not.

Job	What LivePilot brings
Work directly in Live	Control transport, tracks, clips, notes, devices, routing, mixing, automation, and Arrangement View through explicit tools.
Find the right sound	Search Ableton's library, your own plugins and racks, local samples, and Splice before loading anything.
Listen before judging	Read live spectral data or analyze rendered audio, then compare the result with the state before the edit.
Explore safely	Preview alternatives, keep the winner, and route changes inside the set through Ableton's undo stack.
Learn your taste	Remember which moves, devices, and versions you keep across sessions without treating taste as a universal score.
Stay aware of the song	Track identity, open creative threads, section roles, and protected elements so local fixes do not flatten the whole piece.

Under the hood: a 5,264-device atlas, 683 mapped drum kits, 29 sample-processing techniques, 44 semantic moves, real-time and offline listening, and 12 planning and evaluation systems. The sections below show how each part works.

---

Two Ways to Talk to LivePilot

Start with the language that fits the moment. Both routes reach the same tool surface.

Route A — Artist / aesthetic shorthand

"Sound like J Dilla."   "Make this feel more like Burial."   "BoC-style pads."

Use a producer or genre as shorthand for rhythm, density, space, texture, and device choices. LivePilot translates the reference into techniques rather than pretending to clone someone's identity.

Route B — Direct musical intent

"Push the snare 4 ms early, keep the kick on-grid, add ±2 ms timing variation to the hats, and cut 3 dB around 380 Hz on the snare."

When the detail matters, name it: notes, milliseconds, dB, frequency, modulation depth, envelope shape, send level, automation curve, scale degree, or voice leading.

Mixing the routes

Most sessions use both. Start broad, listen, then get specific where the track needs it.

---

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  KNOWLEDGE               PERCEPTION              MEMORY              │
│  ──────────────          ──────────────          ──────────────       │
│                                                                      │
│  Device Atlas            9-band FFT              recall by mood,     │
│  5264 devices            RMS / peak              genre, texture      │
│  120 enriched             pitch tracking          29 techniques       │
│  683 drum kits           key detection           replay into session │
│                                                                      │
│  Sample Engine           Corpus Intelligence     Taste Graph          │
│  Splice (local SQLite)   EmotionalRecipe         move preferences    │
│  Browser search          GenreChain              device affinities   │
│  Filesystem scan         PhysicalModelRecipe     novelty tolerance   │
│  6 fitness critics       AutomationGesture                           │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │  Device      │  │  M4L         │  │  Technique   │               │
│  │  Atlas       │──│  Analyzer    │──│  Memory      │               │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                  │                        │
│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐               │
│  │  Sample      │  │  Corpus      │  │  Composer    │               │
│  │  Engine      │  │  Intelligence│  │  Engine      │               │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         └─────────────────┼──────────────────┘                       │
│                           ▼                                          │
│                  ┌─────────────────┐                                  │
│                  │   474 MCP Tools  │                                  │
│                  │   57 domains     │                                  │
│                  └────────┬────────┘                                  │
│                           │                                          │
│           Remote Script ──┤── TCP 9878                                │
│           M4L Bridge ─────┤── UDP 9880 / OSC 9881                    │
│           Splice (local) ─┤── SQLite (downloaded samples)             │
│                           │                                          │
│                  ┌────────────────┐                                   │
│                  │  Ableton Live  │                                   │
│                  │      12        │                                   │
│                  └────────────────┘                                   │
└──────────────────────────────────────────────────────────────────────┘

How the pieces connect

Remote Script (remote_script/LivePilot/) — A Python ControlSurface that runs inside Ableton's process. Listens on TCP 9878. All Live Object Model calls execute on Ableton's main thread via schedule_message. Detects Ableton version at startup and enables four capability tiers: Core (12.0+), Enhanced Arrangement (12.1.10+), Full Intelligence (12.3+), Collaborative (12.4+).

MCP Server (mcp_server/) — Python FastMCP server. Validates inputs, routes commands to the Remote Script over TCP, manages the M4L bridge, and runs the atlas, sample engine, composer, planning, and evaluation systems. This is what your AI client connects to.

M4L Bridge (m4l_device/) — Optional Max for Live Audio Effect on the master track. Provides deep LOM access through Max's LiveAPI that the ControlSurface API can't reach. UDP 9880 (M4L to server) carries spectral data and LiveAPI responses. OSC 9881 (server to M4L) sends commands. The 38 spectral/analyzer tools strictly require the bridge; device and sample tools that call the bridge also have graceful fallbacks, so core functionality works without it. Backed by 32 bridge commands for hidden parameters, Simpler internals, warp markers, display values, and Simpler warp / Compressor sidechain writes that live on child objects Python can't reach.

Device Atlas (mcp_server/atlas/) — In-memory indexed JSON database. 5264 devices with browser URIs (bundled baseline), 120 enriched with YAML sonic profiles (mood, genre, texture, recommended chains). 7 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack. Reverse-index device_techniques_index.json powers atlas_techniques_for_device (146 cross-references across 58 devices). Device and preset choices resolve against the atlas before loading, which reduces guessed names and dead ends. v1.22.0+: run scan_full_library after install to index your packs, User Library, and plugins into ~/.livepilot/atlas/device_atlas.json — your personal atlas overrides the baseline and survives npm updates.

Sample Engine (mcp_server/sample_engine/) — Searches three sources simultaneously: BrowserSource (Ableton's library), SpliceSource (local Splice catalog via SQLite), FilesystemSource (user directories). Every result passes through a 6-critic fitness battery (key, tempo, spectral, genre, mood, technical). 29 processing techniques (Surgeon precision vs. Alchemist experimentation). Builds complete sample processing plans with warp, slice, and effect recommendations.

Splice Client (mcp_server/splice_client/) — Searches Splice's catalog through two layers: the local SQLite database (sounds.db, already-downloaded samples) and the live gRPC API (full catalog, including samples you haven't downloaded yet). The gRPC client auto-detects Splice's dynamic port via port.conf, handles self-signed TLS, and enforces a 5-credit safety floor before any download. Per-call timeouts (5–10s) prevent a hung Splice process from stalling the MCP event loop. Graceful fallback to SQL-only if grpcio isn't installed. No API key needed — authentication comes from the running Splice desktop app.

Composer (mcp_server/composer/) — Prompt-to-plan pipeline. Parses natural language ("dark minimal techno 128bpm with industrial textures") into a CompositionIntent (genre, mood, tempo, key). Plans layers using role templates (kick, bass, percussion, texture, lead, pad, fx). Compiles to a step-by-step plan of tool calls that the agent executes. Does not execute autonomously — returns the plan. 4 genre defaults (house, techno, trap, ambient) — genres outside this set fall back to a neutral layer plan.

Corpus (mcp_server/corpus/) — Parsed device-knowledge markdown converted to queryable Python structures: EmotionalRecipe, GenreChain, PhysicalModelRecipe, AutomationGesture. Feeds Wonder Mode, Sound Design critics, and the Composer with structured production references at runtime.

Execution Router (mcp_server/runtime/execution_router.py) — Classifies each step in a multi-step plan as remote_command (TCP to Ableton), bridge_command (OSC to M4L), or mcp_tool (internal), then dispatches it through the correct channel.

---

How LivePilot Makes Decisions

Tools make the edit. These 12 systems help decide what to try, what to protect, what to compare, and what to remember.

SongBrain — What the Song Is

Builds a real-time model of the session: identity core (what defines this track), sacred elements (what must not be casually damaged), section purposes (what each part is doing emotionally), energy arc (where the song is heading). Detects identity drift when edits pull the track away from what made it work.

Taste Graph — What You Like

Learns your production preferences across sessions. Tracks which move families you keep vs. undo, which devices you gravitate toward, how experimental you want suggestions (novelty band), and which dimensions you avoid. Every accept/reject updates the graph. Two producers using the same tools get different recommendations.

Semantic Moves — Musical Actions, Not Parameters

44 high-level intents across 7 families (mix, arrangement, transition, sound_design, performance, device_creation, sample) — "add contrast," "tighten the low end," "make kick and bass lock," "sample vocal ghost," "destroy then rebuild." Each move compiles into a concrete tool sequence with risk level, target dimensions, and protection thresholds. Analyzer-gated moves (tighten_low_end, make_kick_bass_lock) mark their spectrum pre-reads as optional so the plan continues even when the analyzer isn't available. The plan shows its tradeoffs before anything changes.

Wonder Mode — Stuck-Rescue Workflow

When a session is stuck — repeated undos, overpolished loops, no structural progress — Wonder Mode activates:

1. Diagnose — classify the stuckness (loop trap? missing contrast? identity unclear?)
2. Generate — find semantic moves that address the diagnosis, enforcing real distinctness
3. Preview — apply each variant, capture, undo. Hear before committing
4. Commit or Reject — choice recorded into taste and session continuity

Creative Engines

Engine	What it does
Mix Engine	Critic-driven analysis: masking, headroom, stereo, dynamics. Plans corrective moves with before/after evaluation
Sound Design Engine	Analyzes patches for static timbre, missing modulation, weak transients. Suggests parameter moves
Transition Engine	Classifies transition types (drop, build, breakdown). Scores quality, plans improvements from archetypes
Composition Engine	Section analysis, motif detection, emotional arcs. Plans structural moves
Performance Engine	Safety-constrained suggestions for live sets. Knows which moves risk audio dropouts
Reference Engine	Distills principles from reference tracks. Maps them to your session as concrete moves

Hook Hunter

Identifies the most salient musical idea — ranks candidates by recurrence across scenes, motif salience, and section placement (payoff-section boost). Tracks whether hooks are developed, neglected, or undermined, and flags when a transition fails to deliver expected payoff. Rhythm-side ranking is currently heuristic (drum-track detection + clip reuse); true onset-based rhythmic features are on the roadmap.

Session Continuity

Maintains creative threads ("the chorus needs more lift") and turn resolutions across the session. When you return to a project: "Last time, you kept the filter sweep for the bridge. The chorus lift thread is still open."

Evaluation Loop

Every engine follows: measure before → act → measure after → compare. If a change made things worse (more masking, lost headroom, identity drift), the system flags it before you move on.

---

Tools

LivePilot has 474 tools across 57 domains, but it no longer sends that entire schema to the AI on every connection. The default producer profile exposes a focused 26-tool production loop plus search_tools and call_tool; every other tool remains searchable and directly callable by name. This keeps the initial catalog under 40 KB while preserving the full system.

Use LIVEPILOT_TOOL_PROFILE=composition, mixing, or sampling to pin more domain tools. Set LIVEPILOT_TOOL_PROFILE=full for legacy clients or catalog diagnostics. Highlights below — full catalog here.

Core Ableton Control — highlights

Domain	#	What it covers
Transport	12	playback, tempo, time sig, loop, metronome, undo/redo, cue points, diagnostics
Tracks	17	create MIDI/audio/return, delete, duplicate, arm, mute, solo, color, freeze, flatten
Clips	11	create, delete, duplicate, fire, stop, loop, launch mode, warp mode, quantize
Notes	8	add/get/remove/modify MIDI notes, transpose, duplicate, per-note probability
Devices	19	load by name or URI, insert native (12.3+), get/set parameters, batch edit, racks, chains, drum chain note assignment, presets, plugin deep control
Scenes	12	create, delete, duplicate, fire, name, color, tempo, scene matrix
Browser	4	search library, browse tree, load items, filter by category
Mixing	11	volume, pan, sends, routing, meters, return tracks, master, full mix snapshot
Arrangement	21	timeline clips, native arrangement clips (12.1.10+), arrangement notes, automation, recording, cue points
Automation	8	16 curve types, 15 recipes (filter sweep, sidechain pump, dub throw...), spectral suggestions
Theory	7	Krumhansl-Schmuckler key detection, Roman numeral analysis, species counterpoint, SATB harmonization
Harmony	4	neo-Riemannian PRL transforms, Tonnetz navigation, voice leading paths, chromatic mediants
Generative	5	Euclidean rhythm (Bjorklund), tintinnabuli (Arvo Part), phase shift (Steve Reich), additive process (Philip Glass)
Memory	8	save, recall, replay, manage production techniques by mood/genre/texture
MIDI I/O	4	export/import .mid, offline analysis, piano roll extraction
Perception	4	offline loudness (integrated LUFS, LRA), spectral analysis, reference comparison

M4L Bridge — 38 analyzer tools [optional], 32 bridge commands

The M4L Analyzer sits on the master track. UDP 9880 carries spectral data to the server. OSC 9881 sends commands back. The ensure_analyzer_on_master pre-flight (v1.20.3) loads the analyzer idempotently when an audio-dependent decision needs it.

[!TIP] Most tools work without the analyzer — it adds 38 spectral/analyzer tools (frequency, loudness, perception, Simpler, warp) and closes the feedback loop.

SPECTRAL ─────── 9-band frequency decomposition (sub_low → air)
                 sub_low (20-60 Hz) split off so kick fundamentals don't hide inside sub
                 true RMS / peak metering
                 Krumhansl-Schmuckler key detection

DEEP LOM ─────── hidden parameters beyond ControlSurface API
                 automation state per parameter
                 recursive device tree (6 levels into nested racks)
                 human-readable display values as shown in Live's UI

SIMPLER ──────── replace / load samples
                 get slice points, crop, reverse
                 warp to N beats, get audio file paths

WARP ─────────── get / add / move / remove markers
                 tempo manipulation at the sample level

Device Atlas — 13 tools

The atlas is an in-memory indexed database of Ableton's entire device library.

5264 devices total
  120 enriched with sonic intelligence (mood, genre, texture, chains)
   47 with aesthetic-tagged signature_techniques
  683 drum kits mapped with note assignments
    7 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack
  146 technique cross-references across 58 devices (reverse-index)

atlas_search                   Search devices by name, category, or tag
atlas_device_info              Full enriched profile for a single device
atlas_suggest                  Suggest devices for a musical intent (e.g., "warm pad")
atlas_chain_suggest            Build a device chain from a genre, artist, or purpose
atlas_compare                  Compare two devices side-by-side
atlas_describe_chain           Free-text describe-a-chain ("granular pad like Tim Hecker")
atlas_techniques_for_device    Reverse-lookup: what techniques reference this device?
atlas_pack_info                Inspect a single Ableton pack — devices + enrichment coverage
scan_full_library              Scan what's actually installed on this machine
reload_atlas                   Hot-reload the atlas after adding enrichments
extension_atlas_search         [v1.23.0+] Search user-local atlas overlays
extension_atlas_get            [v1.23.0+] Fetch a single overlay entry by namespace
extension_atlas_list           [v1.23.0+] Enumerate overlay namespaces + entity_type counts

# Pack-Atlas Phase C-F (v1.23.4+) — corpus-driven orchestration
atlas_macro_fingerprint        [v1.23.4+] "More like this" — find similar presets across 3,813 sidecars by macro fingerprint
atlas_transplant               [v1.23.4+] Adapt a demo / preset / workflow to new BPM, scale, or aesthetic — PRESERVE / SCALE / REMAP / REPLACE decisions
atlas_demo_story               [v1.23.4+] Track-by-track narrative + production sequence inference for any of 104 factory demo .als
atlas_extract_chain            [v1.23.4+] Surgically rebuild a demo track's device chain as an executable plan (load_browser_item + insert_device + set_device_parameter)
atlas_pack_aware_compose       [v1.23.4+] Bootstrap a project with pack-coherent track selection from an aesthetic brief; supports `pack_diversity="eclectic"` mode
atlas_cross_pack_chain         [v1.23.4+] Execute any of 15 cross-pack workflow recipes step-by-step with aesthetic overrides (target_scale / target_bpm / transpose_semitones)

v1.23.0 — User-local extensions: Drop YAML files at ~/.livepilot/atlas-overlays/<namespace>/ to extend the atlas with custom hardware libraries, signature chains, or technique recipes — survives npm updates. See docs/EXTENSION_API.md.

v1.23.4 — Pack-Atlas Phases C/D/E/F: Six new corpus-driven orchestration tools turn the 3,917 parsed pack sidecars + 104 demo .als parses into actionable artifacts — find similar presets, transplant aesthetics across BPM/scale/genre, narrate a demo, extract a track's chain as a runnable plan, bootstrap pack-coherent compositions, run any of 15 cross-pack workflow recipes. All execution is dry-run by default — returns plans, doesn't auto-mutate the session.

User Corpus — 14 tools [v1.23.4+]