livepilot 1.4.4 → 1.5.0

package/mcp_server/tools/analyzer.py

@@ -0,0 +1,508 @@
+"""Analyzer MCP tools — real-time spectral analysis and deep LOM access.
+
+20 tools requiring the LivePilot Analyzer M4L device on the master track.
+These tools are optional — all 107 core tools work without the device.
+"""
+
+from __future__ import annotations
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_spectral(ctx: Context):
+    """Get SpectralCache from lifespan context."""
+    cache = ctx.lifespan_context.get("spectral")
+    if not cache:
+        raise RuntimeError("Spectral cache not initialized")
+    return cache
+
+
+def _get_m4l(ctx: Context):
+    """Get M4LBridge from lifespan context."""
+    bridge = ctx.lifespan_context.get("m4l")
+    if not bridge:
+        raise RuntimeError("M4L bridge not initialized")
+    return bridge
+
+
+def _require_analyzer(cache) -> None:
+    """Raise a helpful error if the analyzer is not connected."""
+    if not cache.is_connected:
+        raise ValueError(
+            "LivePilot Analyzer not detected. "
+            "Drag 'LivePilot Analyzer' onto the master track from "
+            "Audio Effects > Max Audio Effect."
+        )
+
+
+@mcp.tool()
+def get_master_spectrum(ctx: Context) -> dict:
+    """Get 8-band frequency analysis of the master bus.
+
+    Returns band energies: sub (20-60Hz), low (60-200Hz), low_mid (200-500Hz),
+    mid (500-2kHz), high_mid (2-4kHz), high (4-8kHz), presence (8-12kHz),
+    air (12-20kHz). Values 0.0-1.0.
+
+    Also returns detected key/scale if enough audio has been analyzed.
+    Requires LivePilot Analyzer on master track.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+
+    result = {}
+    spectrum = cache.get("spectrum")
+    if spectrum:
+        result["bands"] = spectrum["value"]
+        result["age_ms"] = spectrum["age_ms"]
+
+    key_data = cache.get("key")
+    if key_data:
+        result["detected_key"] = key_data["value"]
+
+    return result
+
+
+@mcp.tool()
+def get_master_rms(ctx: Context) -> dict:
+    """Get real-time RMS and peak levels from the master bus.
+
+    More accurate than LOM meters — includes true RMS (not just peak hold).
+    Requires LivePilot Analyzer on master track.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+
+    result = {}
+    rms = cache.get("rms")
+    if rms:
+        result["rms"] = rms["value"]
+        result["age_ms"] = rms["age_ms"]
+
+    peak = cache.get("peak")
+    if peak:
+        result["peak"] = peak["value"]
+
+    pitch = cache.get("pitch")
+    if pitch:
+        result["pitch"] = pitch["value"]
+
+    return result
+
+
+@mcp.tool()
+async def get_detected_key(ctx: Context) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+
+    # First check the streaming cache for a recent key detection
+    key_data = cache.get("key")
+    if key_data:
+        return key_data["value"]
+
+    # Fall back to querying the bridge directly (key detection runs in JS
+    # and may not be forwarded via OSC streaming)
+    bridge = _get_m4l(ctx)
+    result = await bridge.send_command("get_key")
+    if "error" in result:
+        return result
+    if not result.get("key"):
+        return {"error": "Not enough audio analyzed yet. Play 4-8 bars for key detection."}
+    return result
+
+
+@mcp.tool()
+async def get_hidden_parameters(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("get_hidden_params", track_index, device_index)
+
+
+@mcp.tool()
+async def get_automation_state(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("get_auto_state", track_index, device_index)
+
+
+@mcp.tool()
+async def walk_device_tree(
+    ctx: Context,
+    track_index: int,
+    device_index: int = 0,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("walk_rack", track_index, device_index)
+
+
+# ── Phase 2: Sample Operations ─────────────────────────────────────────
+
+
+@mcp.tool()
+async def get_clip_file_path(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("get_clip_file_path", track_index, clip_index)
+
+
+@mcp.tool()
+async def replace_simpler_sample(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    file_path: str,
+) -> dict:
+    """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 replaces it, it cannot load into an empty Simpler.
+    If the Simpler is empty (freshly created with no sample), load a sample
+    manually first or use find_and_load_device to load a preset that already
+    contains a sample.
+
+    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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    result = await bridge.send_command(
+        "replace_simpler_sample", track_index, device_index, file_path
+    )
+
+    # Validate the response — the bridge may report success even when the
+    # sample silently failed to load (e.g., empty Simpler, bad path)
+    if "error" in result:
+        return result
+    if not result.get("sample_loaded"):
+        return {
+            "error": "Sample may not have loaded. Ensure the Simpler already "
+            "has a sample loaded — replace_sample silently fails on empty Simplers."
+        }
+    return result
+
+
+@mcp.tool()
+async def load_sample_to_simpler(
+    ctx: Context,
+    track_index: int,
+    file_path: str,
+    device_index: int = 0,
+) -> dict:
+    """Load an audio file into a NEW Simpler device on a track.
+
+    This is the full workflow for programmatic sample loading:
+    1. Loads a dummy sample via the browser (creates Simpler with a sample)
+    2. Replaces the dummy with your audio file
+    3. Returns the Simpler ready for slicing/warping
+
+    Use this instead of replace_simpler_sample when the track has no Simpler
+    or the Simpler is empty. Works with any audio file path.
+    Requires LivePilot Analyzer on master track.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+
+    # Step 1: Load a sample from the browser to create Simpler with content
+    ableton = ctx.lifespan_context["ableton"]
+    search = ableton.send_command("search_browser", {
+        "path": "samples",
+        "name_filter": "kick",
+        "loadable_only": True,
+        "max_results": 1,
+    })
+    results = search.get("results", [])
+    if not results:
+        return {"error": "No samples found in browser to bootstrap Simpler"}
+
+    # Load the dummy sample — Ableton auto-creates Simpler
+    uri = results[0]["uri"]
+    ableton.send_command("load_browser_item", {
+        "track_index": track_index,
+        "uri": uri,
+    })
+
+    # Step 2: Replace with the desired sample via M4L bridge
+    result = await bridge.send_command(
+        "replace_simpler_sample", track_index, device_index, file_path
+    )
+    if "error" in result:
+        return result
+    if not result.get("sample_loaded"):
+        return {"error": "Sample replacement failed after bootstrap"}
+
+    result["method"] = "bootstrap_and_replace"
+    return result
+
+
+@mcp.tool()
+async def get_simpler_slices(
+    ctx: Context,
+    track_index: int,
+    device_index: int = 0,
+) -> dict:
+    """Get slice point positions from a Simpler device.
+
+    Returns each slice's position in frames and seconds, plus sample metadata
+    (sample rate, length, playback mode). Use this to understand the rhythmic
+    structure of a sliced sample and program MIDI patterns targeting slices.
+    Requires LivePilot Analyzer on master track.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("get_simpler_slices", track_index, device_index)
+
+
+@mcp.tool()
+async def crop_simpler(
+    ctx: Context,
+    track_index: int,
+    device_index: int = 0,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("crop_simpler", track_index, device_index)
+
+
+@mcp.tool()
+async def reverse_simpler(
+    ctx: Context,
+    track_index: int,
+    device_index: int = 0,
+) -> dict:
+    """Reverse the sample loaded in a Simpler device.
+
+    Can be called again to un-reverse.
+    Requires LivePilot Analyzer on master track.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("reverse_simpler", track_index, device_index)
+
+
+@mcp.tool()
+async def warp_simpler(
+    ctx: Context,
+    track_index: int,
+    device_index: int = 0,
+    beats: int = 4,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("warp_simpler", track_index, device_index, beats)
+
+
+# ── Phase 2: Warp Markers ──────────────────────────────────────────────
+
+
+@mcp.tool()
+async def get_warp_markers(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("get_warp_markers", track_index, clip_index)
+
+
+@mcp.tool()
+async def add_warp_marker(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    beat_time: float,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command(
+        "add_warp_marker", track_index, clip_index, beat_time
+    )
+
+
+@mcp.tool()
+async def move_warp_marker(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    old_beat_time: float,
+    new_beat_time: float,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command(
+        "move_warp_marker", track_index, clip_index, old_beat_time, new_beat_time
+    )
+
+
+@mcp.tool()
+async def remove_warp_marker(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    beat_time: float,
+) -> dict:
+    """Remove a warp marker from an audio clip at the specified beat.
+
+    Only works on audio clips. Requires LivePilot Analyzer on master track.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command(
+        "remove_warp_marker", track_index, clip_index, beat_time
+    )
+
+
+# ── Phase 2: Clip & Display ────────────────────────────────────────────
+
+
+@mcp.tool()
+async def scrub_clip(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    beat_time: float,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command(
+        "scrub_clip", track_index, clip_index, beat_time
+    )
+
+
+@mcp.tool()
+async def stop_scrub(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+) -> dict:
+    """Stop scrubbing a clip. Call after scrub_clip to stop preview.
+
+    Requires LivePilot Analyzer on master track.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("stop_scrub", track_index, clip_index)
+
+
+@mcp.tool()
+async def get_display_values(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+) -> dict:
+    """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.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command("get_display_values", track_index, device_index)

package/mcp_server/tools/clips.py

@@ -144,27 +144,31 @@ def set_clip_loop(
     ctx: Context,
     track_index: int,
     clip_index: int,
-    enabled: bool,
-    start: Optional[float] = None,
-    end: Optional[float] = None,
+    enabled: Optional[bool] = None,
+    loop_start: Optional[float] = None,
+    loop_end: Optional[float] = None,
 ) -> dict:
-    """Enable/disable clip looping and optionally set loop start/end (in beats)."""
+    """Enable/disable clip looping and optionally set loop start/end (in beats).
+    All parameters are optional but at least one must be provided."""
     _validate_track_index(track_index)
     _validate_clip_index(clip_index)
+    if enabled is None and loop_start is None and loop_end is None:
+        raise ValueError("At least one of enabled, loop_start, or loop_end must be provided")
     params = {
         "track_index": track_index,
         "clip_index": clip_index,
-        "enabled": enabled,
     }
-    if start is not None:
-        if start < 0:
+    if enabled is not None:
+        params["enabled"] = enabled
+    if loop_start is not None:
+        if loop_start < 0:
             raise ValueError("Loop start must be >= 0")
-        params["start"] = start
-    if end is not None:
-        if end <= 0:
+        params["start"] = loop_start
+    if loop_end is not None:
+        if loop_end <= 0:
             raise ValueError("Loop end must be > 0")
-        params["end"] = end
-    if start is not None and end is not None and start >= end:
+        params["end"] = loop_end
+    if loop_start is not None and loop_end is not None and loop_start >= loop_end:
         raise ValueError("Loop start must be less than loop end")
     return _get_ableton(ctx).send_command("set_clip_loop", params)
 

package/mcp_server/tools/devices.py

@@ -106,9 +106,9 @@ def batch_set_parameters(
     ctx: Context,
     track_index: int,
     device_index: int,
-    parameters: list,
+    parameters: Any,
 ) -> dict:
-    """Set multiple device parameters in one call. parameters is a list of objects: [{"name_or_index": "Dry/Wet", "value": 0.5}, ...].
+    """Set multiple device parameters in one call. parameters is a JSON array of objects: [{"name_or_index": "Dry/Wet", "value": 0.5}, ...].
     track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
     _validate_track_index(track_index)
     _validate_device_index(device_index)

package/mcp_server/tools/mixing.py

@@ -1,6 +1,6 @@
-"""Mixing MCP tools — volume, pan, sends, routing, master.
+"""Mixing MCP tools — volume, pan, sends, routing, master, metering.
 
-8 tools matching the Remote Script mixing domain.
+11 tools matching the Remote Script mixing domain.
 """
 
 from __future__ import annotations
@@ -87,6 +87,42 @@ def set_master_volume(ctx: Context, volume: float) -> dict:
     return _get_ableton(ctx).send_command("set_master_volume", {"volume": volume})
 
 
+@mcp.tool()
+def get_track_meters(
+    ctx: Context,
+    track_index: Optional[int] = None,
+    include_stereo: bool = False,
+) -> dict:
+    """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)
+    """
+    params: dict = {}
+    if track_index is not None:
+        params["track_index"] = track_index
+    if include_stereo:
+        params["include_stereo"] = include_stereo
+    return _get_ableton(ctx).send_command("get_track_meters", params)
+
+
+@mcp.tool()
+def get_master_meters(ctx: Context) -> dict:
+    """Read real-time output meter levels for the master track (left, right, peak)."""
+    return _get_ableton(ctx).send_command("get_master_meters")
+
+
+@mcp.tool()
+def get_mix_snapshot(ctx: Context) -> dict:
+    """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."""
+    return _get_ableton(ctx).send_command("get_mix_snapshot")
+
+
 @mcp.tool()
 def get_track_routing(ctx: Context, track_index: int) -> dict:
     """Get input/output routing info for a track. Use negative track_index for return tracks (-1=A, -2=B)."""
@@ -100,22 +136,22 @@ def get_track_routing(ctx: Context, track_index: int) -> dict:
 def set_track_routing(
     ctx: Context,
     track_index: int,
-    input_type: Optional[str] = None,
-    input_channel: Optional[str] = None,
-    output_type: Optional[str] = None,
-    output_channel: Optional[str] = None,
+    input_routing_type: Optional[str] = None,
+    input_routing_channel: Optional[str] = None,
+    output_routing_type: Optional[str] = None,
+    output_routing_channel: Optional[str] = None,
 ) -> dict:
     """Set input/output routing for a track by display name. Use negative track_index for return tracks (-1=A, -2=B)."""
     _validate_track_index(track_index)
     params = {"track_index": track_index}
-    if input_type is not None:
-        params["input_type"] = input_type
-    if input_channel is not None:
-        params["input_channel"] = input_channel
-    if output_type is not None:
-        params["output_type"] = output_type
-    if output_channel is not None:
-        params["output_channel"] = output_channel
+    if input_routing_type is not None:
+        params["input_type"] = input_routing_type
+    if input_routing_channel is not None:
+        params["input_channel"] = input_routing_channel
+    if output_routing_type is not None:
+        params["output_type"] = output_routing_type
+    if output_routing_channel is not None:
+        params["output_channel"] = output_routing_channel
     if len(params) == 1:
         raise ValueError("At least one routing parameter must be provided")
     return _get_ableton(ctx).send_command("set_track_routing", params)

package/mcp_server/tools/tracks.py

@@ -127,12 +127,12 @@ def set_track_mute(ctx: Context, track_index: int, muted: bool) -> dict:
 
 
 @mcp.tool()
-def set_track_solo(ctx: Context, track_index: int, soloed: bool) -> dict:
+def set_track_solo(ctx: Context, track_index: int, solo: bool) -> dict:
     """Solo or unsolo a track."""
     _validate_track_index(track_index)
     return _get_ableton(ctx).send_command("set_track_solo", {
         "track_index": track_index,
-        "solo": soloed,
+        "solo": solo,
     })
 
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "AI copilot for Ableton Live 12 — 104 MCP tools for music production, sound design, and mixing",
+  "description": "AI copilot for Ableton Live 12 — 127 tools, device atlas (280+ devices), real-time audio analysis, and technique memory",
   "author": "Pilot Studio",
   "license": "MIT",
   "type": "commonjs",
@@ -27,7 +27,6 @@
     "midi",
     "daw",
     "ai",
-    "claude",
     "sound-design",
     "mixing",
     "arrangement"