livepilot 1.4.5 → 1.6.1

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)