io.github.dreamrec/livepilot

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

An agentic production system for Ableton Live 12.
426 tools. 52 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.

[!NOTE] LivePilot works with any MCP client — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf. All tools execute on Ableton's main thread through the official Live Object Model API. Everything is reversible with undo.

What LivePilot Does

Most MCP servers are tool collections — they execute commands. LivePilot is an agentic production system. It has seven layers that work together:

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  KNOWLEDGE               PERCEPTION              MEMORY              │
│  ──────────────          ──────────────          ──────────────       │
│                                                                      │
│  Device Atlas            9-band FFT              recall by mood,     │
│  1305 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      │               │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         └─────────────────┼──────────────────┘                       │
│                           ▼                                          │
│                  ┌─────────────────┐                                  │
│                  │   426 MCP Tools  │                                  │
│                  │   52 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 three capability tiers: Core (12.0+), Enhanced Arrangement (12.1.10+), Full Intelligence (12.3+).

MCP Server (mcp_server/) — Python FastMCP server. Validates inputs, routes commands to the Remote Script over TCP, manages the M4L bridge, runs the atlas, sample engine, composer, and all intelligence engines. 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 32 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 30 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. 1305 devices with browser URIs, 120 enriched with YAML sonic intelligence profiles (mood, genre, texture, recommended chains). 6 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre. The AI never hallucinates a device name or preset — it always resolves against the atlas first.

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 deep creative knowledge at runtime — not just LLM prompts, actual structured data.

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.

The Intelligence Layer

12 engines sit on top of the 426 tools. They give the AI musical judgment, not just musical execution.

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

26+ high-level intents ("add contrast," "tighten the low end," "build tension") that compile into tool sequences. Each move carries a risk level, target dimensions, and protection thresholds. The AI knows what it's risking with every action.

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

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

426 tools across 52 domains. Highlights below — full catalog here.

Core (210 tools)

M4L Bridge — 30 tools [optional]

The M4L Analyzer sits on the master track. UDP 9880 carries spectral data to the server. OSC 9881 sends commands back.

[!TIP] Most tools work without the analyzer — it adds 32 spectral/analyzer tools (frequency, loudness, perception) 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 — 6 tools

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

1305 devices total
  120 enriched with sonic intelligence (mood, genre, texture, chains)
 683 drum kits mapped with note assignments
   6 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre

atlas_search           Search devices by name, category, or tag
atlas_suggest          Suggest devices for a musical intent (e.g., "warm pad")
atlas_chain            Build a device chain from a genre or purpose
atlas_compare          Compare two devices side-by-side
atlas_detail           Get full enriched profile for a device
atlas_library_scan     Scan what's actually installed on this machine

Sample Engine — 6 tools

Three-source sample intelligence with critic-driven fitness scoring.

SOURCES ─────────── BrowserSource  (Ableton's built-in library)
                    SpliceSource   (local Splice catalog via SQLite)
                    FilesystemSource (user-specified directories)

CRITICS ─────────── key fitness · tempo fitness · spectral match
                    genre alignment · mood alignment · technical quality

TECHNIQUES ─────── 29 processing recipes:
                    Surgeon (precise, transparent) vs.
                    Alchemist (experimental, transformative)

analyze_sample         Build a complete SampleProfile (material, key, BPM, spectral)
search_samples         Multi-source search with critic scoring
suggest_sample_move    Recommend processing technique for a sample
build_sample_plan      Full processing pipeline: warp + slice + effects
list_sample_techniques Browse the 29-technique library
get_sample_technique   Get detailed recipe for a specific technique

Splice Integration

LivePilot reads Splice's local SQLite database to search your downloaded samples with full metadata. No API key needed — it reads the database file directly.

What it does:

• Searches your downloaded Splice samples with key, BPM, genre, and tag metadata
• Integrates as a third source alongside Ableton's browser and filesystem scanning
• Works without a Splice subscription — any previously downloaded samples are searchable

How it works: The Sample Engine's SpliceSource reads ~/Library/Application Support/com.splice.Splice/users/default/*/sounds.db — Splice's local SQLite catalog of downloaded samples. Read-only, no network calls.

Requirements: Splice desktop app running (the MCP server talks to it over gRPC at a dynamic port advertised via port.conf, with self-signed TLS). For fully offline search, previously-downloaded samples are always searchable via the local SQLite fallback even if the Splice app isn't running.

Composer — 3 tools

Prompt-to-plan auto-composition engine.

"dark minimal techno 128bpm with industrial textures and ghostly vocals"
    │
    ▼
┌─────────────────┐
│  Prompt Parser   │ → CompositionIntent (genre, mood, tempo, key)
└────────┬────────┘
         ▼
┌─────────────────┐
│  Layer Planner   │ → role templates (kick, bass, perc, texture, lead, pad, fx)
└────────┬────────┘
         ▼
┌─────────────────┐
│  Plan Compiler   │ → executable tool sequences
└────────┬────────┘
         ▼
┌─────────────────┐
│ Execution Router │ → dispatches: create tracks, search samples, load devices,
│                  │   program notes, set volumes, build arrangement
└─────────────────┘

• 4 genre defaults: house, techno, trap, ambient (unknown genres fall back to a neutral plan)
• Returns step-by-step plans — the agent executes each tool call in sequence
• compose — plan a multi-layer composition from text prompt
• augment_with_samples — plan sample-based layers for existing session
• get_composition_plan — dry-run preview (see the plan without credit checks)

Device Forge — 3 tools

Generate M4L audio effect devices from gen~ templates and install them into Ableton's browser.

forge_device           Generate a device from a gen~ template
forge_list_templates   Browse available gen~ templates
forge_install          Install generated device to browser

Agentic Intelligence — 79 tools

The V2 intelligence layer. These tools analyze, diagnose, plan, evaluate, and learn.

View all 426 tools →

Install

Easiest: Claude Desktop Extension (1 click)

Download livepilot.mcpb and double-click it. Claude Desktop installs everything automatically. Then:

1. Open Ableton Live 12
2. Preferences → Link, Tempo & MIDI → Control Surface → LivePilot
3. Start chatting

[!TIP] The Desktop Extension auto-installs the Remote Script and M4L Analyzer on first launch.

Quick: One Command Setup

npx livepilot --setup

Runs the full setup wizard: checks Python, installs the Remote Script, creates the Python environment, copies the M4L Analyzer, and tests the Ableton connection.

Manual: Step by Step

npx livepilot --install

claude mcp add LivePilot -- npx livepilot
claude plugin add github:dreamrec/LivePilot/plugin

npx livepilot --install-codex-plugin

{
  "mcpServers": {
    "LivePilot": { "command": "npx", "args": ["livepilot"] }
  }
}

npm install -g livepilot
livepilot --install

{
  "mcpServers": {
    "LivePilot": { "command": "livepilot" }
  }
}

{
  "mcpServers": {
    "LivePilot": { "command": "npx", "args": ["livepilot"] }
  }
}

{
  "servers": {
    "LivePilot": { "command": "npx", "args": ["livepilot"] }
  }
}

Verify

npx livepilot --status

Plugin

Codex App

npx livepilot --install-codex-plugin

Claude Code

claude plugin add github:dreamrec/LivePilot/plugin

Producer Agent — an orchestrated multi-step assistant for building, layering and refining sessions. Consults memory for style context, searches the atlas for instruments, searches samples, creates tracks, programs MIDI, chains effects, reads the spectrum to verify, and arranges sections. The agent proposes plans; the user confirms and listens. LivePilot is a high- trust operator, not an autonomous producer.

Core Skill — operational discipline connecting all layers. Consult atlas before loading. Read analyzer after mixing. Check memory before creative decisions. Verify every mutation.

CLI

npx livepilot              # Start MCP server (stdio)
npx livepilot --setup      # Full setup wizard
npx livepilot --install    # Install Remote Script
npx livepilot --uninstall  # Remove Remote Script
npx livepilot --install-codex-plugin   # Install bundled Codex plugin
npx livepilot --uninstall-codex-plugin # Remove bundled Codex plugin
npx livepilot --status     # Check Ableton connection
npx livepilot --doctor     # Full diagnostic check
npx livepilot --version    # Show version

Compatibility

Version tiers:

• Core (12.0+): All session tools, mixing, devices, MIDI, theory, generative, memory
• Enhanced Arrangement (12.1.10+): Native arrangement clips, arrangement automation
• Full Intelligence (12.3+): insert_device_native, complete device insertion pipeline

Development

git clone https://github.com/dreamrec/LivePilot.git
cd LivePilot
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
# Test runner is not in requirements.txt (runtime-only deps) — install it explicitly:
.venv/bin/pip install pytest pytest-asyncio
.venv/bin/pytest tests/ -v

See CONTRIBUTING.md for architecture details, code guidelines, and how to add tools.

Documentation

Community

• Discussions — questions, ideas, show & tell
• Bug reports
• Feature requests
• Contributing guide
• Security policy

Support

LivePilot is source-available under the Business Source License 1.1. If it saves you time in your sessions:

Sponsor on GitHub

Sponsors get early access to new features, premium skills, curated technique libraries, and direct support.

BSL-1.1 — Pilot Studio

Sister projects: TDPilot (TouchDesigner) · ComfyPilot (ComfyUI)