livepilot 1.4.5 → 1.6.1

package/mcp_server/tools/automation.py

@@ -0,0 +1,431 @@
+"""Automation MCP tools — clip envelope CRUD + intelligent curve generation.
+
+8 tools for writing, reading, and generating automation curves on session clips.
+Combines the clip automation handlers (Remote Script) with the curve generation
+engine (curves.py) for musically intelligent automation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastmcp import Context
+
+from ..curves import generate_curve, generate_from_recipe, list_recipes
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+def _ensure_list(v: Any) -> list:
+    if isinstance(v, str):
+        import json
+        return json.loads(v)
+    return list(v)
+
+
+@mcp.tool()
+def get_clip_automation(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+) -> dict:
+    """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.
+    """
+    return _get_ableton(ctx).send_command("get_clip_automation", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def set_clip_automation(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    parameter_type: str,
+    points: Any,
+    device_index: Optional[int] = None,
+    parameter_index: Optional[int] = None,
+    send_index: Optional[int] = None,
+) -> dict:
+    """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.
+    """
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "parameter_type": parameter_type,
+        "points": _ensure_list(points),
+    }
+    if device_index is not None:
+        params["device_index"] = device_index
+    if parameter_index is not None:
+        params["parameter_index"] = parameter_index
+    if send_index is not None:
+        params["send_index"] = send_index
+    return _get_ableton(ctx).send_command("set_clip_automation", params)
+
+
+@mcp.tool()
+def clear_clip_automation(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    parameter_type: Optional[str] = None,
+    device_index: Optional[int] = None,
+    parameter_index: Optional[int] = None,
+    send_index: Optional[int] = None,
+) -> dict:
+    """Clear automation envelopes from a session clip.
+
+    If parameter_type is omitted, clears ALL envelopes.
+    If provided, clears only that parameter's envelope.
+    """
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    }
+    if parameter_type is not None:
+        params["parameter_type"] = parameter_type
+    if device_index is not None:
+        params["device_index"] = device_index
+    if parameter_index is not None:
+        params["parameter_index"] = parameter_index
+    if send_index is not None:
+        params["send_index"] = send_index
+    return _get_ableton(ctx).send_command("clear_clip_automation", params)
+
+
+@mcp.tool()
+def apply_automation_shape(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    parameter_type: str,
+    curve_type: str,
+    duration: float = 4.0,
+    density: int = 16,
+    device_index: Optional[int] = None,
+    parameter_index: Optional[int] = None,
+    send_index: Optional[int] = None,
+    start: float = 0.0,
+    end: float = 1.0,
+    center: float = 0.5,
+    amplitude: float = 0.5,
+    frequency: float = 1.0,
+    phase: float = 0.0,
+    peak: float = 1.0,
+    decay: float = 4.0,
+    low: float = 0.0,
+    high: float = 1.0,
+    factor: float = 3.0,
+    invert: bool = False,
+    time_offset: float = 0.0,
+) -> dict:
+    """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
+    """
+    # Generate the curve
+    points = generate_curve(
+        curve_type=curve_type,
+        duration=duration,
+        density=density,
+        start=start, end=end,
+        center=center, amplitude=amplitude,
+        frequency=frequency, phase=phase,
+        peak=peak, decay=decay,
+        low=low, high=high,
+        factor=factor,
+        invert=invert,
+    )
+
+    # Apply time offset
+    if time_offset > 0:
+        for p in points:
+            p["time"] += time_offset
+
+    # Write to clip
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "parameter_type": parameter_type,
+        "points": points,
+    }
+    if device_index is not None:
+        params["device_index"] = device_index
+    if parameter_index is not None:
+        params["parameter_index"] = parameter_index
+    if send_index is not None:
+        params["send_index"] = send_index
+
+    result = _get_ableton(ctx).send_command("set_clip_automation", params)
+    result["curve_type"] = curve_type
+    result["curve_points"] = len(points)
+    return result
+
+
+@mcp.tool()
+def apply_automation_recipe(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    parameter_type: str,
+    recipe: str,
+    duration: float = 4.0,
+    density: int = 16,
+    device_index: Optional[int] = None,
+    parameter_index: Optional[int] = None,
+    send_index: Optional[int] = None,
+    time_offset: float = 0.0,
+) -> dict:
+    """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
+    """
+    points = generate_from_recipe(recipe, duration=duration, density=density)
+
+    if time_offset > 0:
+        for p in points:
+            p["time"] += time_offset
+
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "parameter_type": parameter_type,
+        "points": points,
+    }
+    if device_index is not None:
+        params["device_index"] = device_index
+    if parameter_index is not None:
+        params["parameter_index"] = parameter_index
+    if send_index is not None:
+        params["send_index"] = send_index
+
+    result = _get_ableton(ctx).send_command("set_clip_automation", params)
+    result["recipe"] = recipe
+    result["curve_points"] = len(points)
+    return result
+
+
+@mcp.tool()
+def get_automation_recipes(ctx: Context) -> dict:
+    """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.
+    """
+    return {"recipes": list_recipes()}
+
+
+@mcp.tool()
+def generate_automation_curve(
+    ctx: Context,
+    curve_type: str,
+    duration: float = 4.0,
+    density: int = 16,
+    start: float = 0.0,
+    end: float = 1.0,
+    center: float = 0.5,
+    amplitude: float = 0.5,
+    frequency: float = 1.0,
+    phase: float = 0.0,
+    peak: float = 1.0,
+    decay: float = 4.0,
+    low: float = 0.0,
+    high: float = 1.0,
+    factor: float = 3.0,
+    invert: bool = False,
+) -> dict:
+    """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.
+    """
+    points = generate_curve(
+        curve_type=curve_type,
+        duration=duration,
+        density=density,
+        start=start, end=end,
+        center=center, amplitude=amplitude,
+        frequency=frequency, phase=phase,
+        peak=peak, decay=decay,
+        low=low, high=high,
+        factor=factor,
+        invert=invert,
+    )
+    return {
+        "curve_type": curve_type,
+        "duration": duration,
+        "point_count": len(points),
+        "points": points,
+        "value_range": {
+            "min": min(p["value"] for p in points) if points else 0,
+            "max": max(p["value"] for p in points) if points else 0,
+        },
+    }
+
+
+@mcp.tool()
+def analyze_for_automation(
+    ctx: Context,
+    track_index: int,
+) -> dict:
+    """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.
+    """
+    ableton = _get_ableton(ctx)
+
+    # Get track devices
+    track_info = ableton.send_command("get_track_info", {
+        "track_index": track_index,
+    })
+
+    # Get current spectrum
+    spectral = ctx.lifespan_context.get("spectral")
+    spectrum = {}
+    if spectral and spectral.is_connected:
+        spectrum = spectral.get_spectrum()
+
+    # Get meter level
+    meters = ableton.send_command("get_track_meters", {
+        "track_index": track_index,
+    })
+
+    devices = track_info.get("devices", [])
+    suggestions = []
+
+    # Analyze based on device types and spectrum
+    for i, dev in enumerate(devices):
+        dev_name = dev.get("name", "").lower()
+        dev_class = dev.get("class_name", "").lower()
+
+        # Filter devices — suggest sweep automation
+        if any(kw in dev_class for kw in ["autofilter", "eq8", "filter"]):
+            suggestions.append({
+                "device_index": i,
+                "device_name": dev.get("name"),
+                "suggestion": "filter_sweep",
+                "reason": "Filter detected — automate cutoff for movement",
+                "recipe": "filter_sweep_up",
+            })
+
+        # Reverb/delay — suggest send throws or washout
+        if any(kw in dev_class for kw in ["reverb", "delay", "hybrid", "echo"]):
+            suggestions.append({
+                "device_index": i,
+                "device_name": dev.get("name"),
+                "suggestion": "spatial_automation",
+                "reason": "Space effect — automate mix/decay for depth changes",
+                "recipe": "washout",
+            })
+
+        # Distortion — suggest drive automation
+        if any(kw in dev_class for kw in ["saturator", "overdrive", "pedal", "amp"]):
+            suggestions.append({
+                "device_index": i,
+                "device_name": dev.get("name"),
+                "suggestion": "drive_automation",
+                "reason": "Distortion — automate drive for dynamic saturation",
+                "recipe": "breathing",
+            })
+
+        # Synths — suggest wavetable/macro automation
+        if any(kw in dev_class for kw in ["wavetable", "drift", "analog", "operator"]):
+            suggestions.append({
+                "device_index": i,
+                "device_name": dev.get("name"),
+                "suggestion": "timbre_evolution",
+                "reason": "Synth — automate timbre params for evolving sound",
+                "recipe": "breathing",
+            })
+
+    # Mixer suggestions based on spectrum
+    if spectrum:
+        sub = spectrum.get("sub", 0)
+        if sub > 0.15:
+            suggestions.append({
+                "suggestion": "high_pass_automation",
+                "reason": "Heavy sub content (%.2f) — HP filter sweep for builds" % sub,
+                "recipe": "build_rise",
+            })
+
+    # Always suggest send automation for spatial depth
+    suggestions.append({
+        "suggestion": "send_throws",
+        "reason": "Reverb/delay sends — automate for dub throws and spatial variation",
+        "recipe": "dub_throw",
+    })
+
+    return {
+        "track_index": track_index,
+        "track_name": track_info.get("name", ""),
+        "device_count": len(devices),
+        "current_level": meters.get("tracks", [{}])[0].get("level", 0),
+        "spectrum": spectrum,
+        "suggestions": suggestions,
+    }

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.5",
+  "version": "1.6.1",
   "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 — 135 tools, device atlas (280+ devices), real-time audio analysis, automation intelligence, and technique memory",
   "author": "Pilot Studio",
   "license": "MIT",
   "type": "commonjs",
@@ -27,7 +27,6 @@
     "midi",
     "daw",
     "ai",
-    "claude",
     "sound-design",
     "mixing",
     "arrangement"

package/plugin/agents/livepilot-producer/AGENT.md

@@ -24,8 +24,9 @@ Given a high-level description, you:
 6. **Program patterns** — write MIDI notes that fit the genre and style
 7. **Add effects** — load and configure effect chains for the desired sound
 8. **HEALTH CHECK** — verify effects aren't pass-throughs (Dry/Wet > 0, Drive set, etc.)
-9. **Mix** — balance volumes, set panning, configure sends
-10. **Final verify** — `get_session_info`, fire scenes, confirm audio output
+9. **Automate** — add movement and evolution to the mix (see Automation Phase below)
+10. **Mix** — balance volumes, set panning, configure sends
+11. **Final verify** — `get_session_info`, fire scenes, confirm audio output
 
 ## Mandatory Track Health Checks
 
@@ -49,6 +50,35 @@ After loading any instrument, run this checklist:
 - **For synths, use `search_browser` → `load_browser_item`** with exact URI. `find_and_load_device` can match sample files before the actual instrument (e.g., "Drift" matches a .wav sample first)
 - **After loading any effect**, set its key parameters to non-default values. A Saturator with Drive=0, a Reverb with Dry/Wet=0, or a Compressor with Threshold at max are all pass-throughs.
 
+## Automation Phase (after writing notes, before mixing)
+
+### Step 1: Spectral Diagnosis
+- Solo each track -> `get_master_spectrum` -> build spectral map
+- Identify frequency overlaps between tracks (masking)
+- Note problem areas: resonances, mud, harshness
+
+### Step 2: Per-Track Analysis
+- `analyze_for_automation` on each track -> get device-specific suggestions
+- Cross-reference with spectral map: which suggestions address the problems found?
+
+### Step 3: Write Automation (perception-action loop)
+For each automation decision:
+1. Read spectrum BEFORE
+2. Apply recipe or custom curve
+3. Read spectrum AFTER
+4. Compare: did it improve? If not, clear and adjust
+5. Store the final working automation parameters in memory
+
+### Step 4: Spatial Design
+- Add send automation for depth (dub throws, reverb washes)
+- Consider complementary automation: as one track's filter opens, another's narrows
+- Use cross-track spectral awareness to avoid new masking from automation
+
+### Step 5: Generative/Evolving Textures
+- Consider polyrhythmic automation for non-repeating evolution
+- Unlinked envelopes with prime-number beat lengths (3, 5, 7 beats)
+- Spectral-driven automation: use analyzer data to modulate parameters in real-time concepts
+
 ## Rules
 
 - Always use the livepilot-core skill for guidance on tool usage

package/plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "livepilot",
-  "version": "1.4.5",
-  "description": "AI copilot for Ableton Live 12 — 104 MCP tools for music production, sound design, and mixing",
+  "version": "1.6.1",
+  "description": "AI copilot for Ableton Live 12 — 135 tools, device atlas (280+ devices), real-time audio analysis, automation intelligence, and technique memory",
   "author": "Pilot Studio",
   "skills": [
     "skills/livepilot-core"