livepilot 1.5.0 → 1.6.1

package/mcp_server/server.py

@@ -55,6 +55,7 @@ from .tools import browser      # noqa: F401, E402
 from .tools import arrangement  # noqa: F401, E402
 from .tools import memory       # noqa: F401, E402
 from .tools import analyzer     # noqa: F401, E402
+from .tools import automation   # noqa: F401, E402
 
 
 # ---------------------------------------------------------------------------

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/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "AI copilot for Ableton Live 12 — 127 tools, device atlas (280+ devices), real-time audio analysis, and technique memory",
+  "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",

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.5.0",
-  "description": "AI copilot for Ableton Live 12 — 127 tools, device atlas (280+ devices), real-time audio analysis, and technique memory",
+  "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"

package/plugin/skills/livepilot-core/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: livepilot-core
-description: Core discipline for controlling Ableton Live 12 through LivePilot's 127 MCP tools, device atlas (280+ devices), M4L analyzer (spectrum/RMS/key detection), and technique memory. Use whenever working with Ableton Live through MCP tools.
+description: Core discipline for controlling Ableton Live 12 through LivePilot's 135 MCP tools, device atlas (280+ devices), M4L analyzer (spectrum/RMS/key detection), automation intelligence (16 curve types, 15 recipes), and technique memory. Use whenever working with Ableton Live through MCP tools.
 ---
 
 # LivePilot Core — Ableton Live 12 AI Copilot
 
-LivePilot is an agentic production system for Ableton Live 12. It combines 127 MCP tools with three layers of intelligence:
+LivePilot is an agentic production system for Ableton Live 12. It combines 135 MCP tools with three layers of intelligence:
 
 - **Device Atlas** — A structured knowledge corpus of 280+ instruments, 139 drum kits, and 350+ impulse responses. Consult the atlas before loading any device. It contains real browser URIs, preset names, and sonic descriptions. Never guess a device name — look it up.
 - **M4L Analyzer** — Real-time audio analysis on the master bus (8-band spectrum, RMS/peak, key detection). Use it to verify mixing decisions, detect frequency problems, and find the key before writing harmonic content.
 - **Technique Memory** — Persistent storage for production decisions. Consult `memory_recall` before creative tasks to understand the user's taste. Save techniques when the user likes something. The memory shapes future decisions without constraining them.
 
-These layers sit on top of 127 deterministic tools across 11 domains: transport, tracks, clips, MIDI notes, devices, scenes, mixing, browser, arrangement, technique memory, and real-time DSP analysis.
+These layers sit on top of 135 deterministic tools across 12 domains: transport, tracks, clips, MIDI notes, devices, scenes, mixing, browser, arrangement, technique memory, real-time DSP analysis, and automation.
 
 ## Golden Rules
 
@@ -64,7 +64,7 @@ These layers sit on top of 127 deterministic tools across 11 domains: transport,
 - MIDI track with no instrument loaded
 - Notes programmed but clip not fired
 
-## Tool Domains (127 total)
+## Tool Domains (135 total)
 
 ### Transport (12)
 `get_session_info` · `set_tempo` · `set_time_signature` · `start_playback` · `stop_playback` · `continue_playback` · `toggle_metronome` · `set_session_loop` · `undo` · `redo` · `get_recent_actions` · `get_session_diagnostics`
@@ -99,6 +99,29 @@ These layers sit on top of 127 deterministic tools across 11 domains: transport,
 ### Analyzer (20) — requires LivePilot Analyzer M4L device on master track
 `get_master_spectrum` · `get_master_rms` · `get_detected_key` · `get_hidden_parameters` · `get_automation_state` · `walk_device_tree` · `get_clip_file_path` · `replace_simpler_sample` · `load_sample_to_simpler` · `get_simpler_slices` · `crop_simpler` · `reverse_simpler` · `warp_simpler` · `get_warp_markers` · `add_warp_marker` · `move_warp_marker` · `remove_warp_marker` · `scrub_clip` · `stop_scrub` · `get_display_values`
 
+### Automation (8)
+Clip automation CRUD + intelligent curve generation with 15 built-in recipes.
+
+**Tools:** `get_clip_automation` · `set_clip_automation` · `clear_clip_automation` · `apply_automation_shape` · `apply_automation_recipe` · `get_automation_recipes` · `generate_automation_curve` · `analyze_for_automation`
+
+**Key discipline:**
+
+**The Feedback Loop (MANDATORY for all automation work):**
+1. PERCEIVE: `get_master_spectrum` + `get_track_meters` -> understand current state
+2. DIAGNOSE: What needs to change? Use diagnostic filter technique if unsure
+3. DECIDE: Which parameter, which curve, which recipe?
+4. ACT: `apply_automation_shape` or `apply_automation_recipe`
+5. VERIFY: `get_master_spectrum` again -> did it work?
+6. ADJUST: If not right, `clear_clip_automation` -> try different curve/params
+7. NEVER write automation without reading spectrum first and after
+
+**Rules:**
+- Use `analyze_for_automation` before writing — let spectral data guide decisions
+- Use recipes for common patterns (filter_sweep_up, dub_throw, sidechain_pump)
+- Use `apply_automation_shape` for custom curves with specific math
+- Clear existing automation before rewriting: `clear_clip_automation` first
+- Load `references/automation-atlas.md` for curve theory, genre recipes, diagnostic technique, and cross-track spectral mapping
+
 ## Workflow: Building a Beat
 
 1. `get_session_info` — check current state
@@ -240,10 +263,11 @@ Deep production knowledge lives in `references/`. Consult these when making crea
 
 | File | What's inside | When to consult |
 |------|--------------|-----------------|
-| `references/overview.md` | All 127 tools mapped with params, units, ranges | Quick lookup for any tool |
+| `references/overview.md` | All 135 tools mapped with params, units, ranges | Quick lookup for any tool |
 | `references/midi-recipes.md` | Drum patterns by genre, chord voicings, scales, hi-hat techniques, humanization, polymetrics | Programming MIDI notes, building beats |
 | `references/sound-design.md` | Stock instruments/effects, parameter recipes for bass/pad/lead/pluck, device chain patterns | Loading and configuring devices |
 | `references/mixing-patterns.md` | Gain staging, parallel compression, sidechain, EQ by instrument, bus processing, stereo width | Setting volumes, panning, adding effects |
 | `references/ableton-workflow-patterns.md` | Session/Arrangement workflow, song structures by genre, follow actions, clip launch modes, export | Organizing sessions, structuring songs |
 | `references/m4l-devices.md` | Browser organization, MIDI effects, rack systems, device loading patterns | Finding and loading devices, using racks |
 | `references/memory-guide.md` | Qualities template, good/bad examples for each technique type | Saving techniques, writing qualities |
+| `references/automation-atlas.md` | Curve theory, perception-action loop, genre recipes, diagnostic filter technique, spectral mapping | Writing automation, choosing curves, mixing with spectral feedback |