livepilot 1.10.9 → 1.12.2

package/mcp_server/tools/follow_actions.py

@@ -0,0 +1,202 @@
+"""Follow Actions tools (Live 12.0+ clip, 12.2+ scene).
+
+8 tools matching the Remote Script follow_actions domain:
+- Clip follow actions (Live 12.0 revamp): get/set/clear, a preset
+  wrapper, and enum-name enumeration.
+- Scene follow actions (Live 12.2+): get/set/clear with "Longest"
+  mode (``linked``) and the 1-8 ``multiplier`` selector.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+# ── Clip follow actions (Live 12.0+) ─────────────────────────────────────
+
+
+@mcp.tool()
+def get_clip_follow_action(ctx: Context, track_index: int, clip_index: int) -> dict:
+    """Read a clip's follow-action state (Live 12.0+).
+
+    Returns:
+        enabled:   bool — follow-action master switch
+        action_a:  primary action name (stop, play_again, previous,
+                   next, first, last, any, other, jump)
+        action_b:  secondary action (used when chance_b > 0)
+        chance_a:  probability of action_a firing (0.0-1.0)
+        chance_b:  probability of action_b firing (0.0-1.0)
+        time:      follow-action trigger time in beats
+    """
+    return _get_ableton(ctx).send_command("get_clip_follow_action", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def set_clip_follow_action(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    action_a: Optional[str] = None,
+    action_b: Optional[str] = None,
+    chance_a: Optional[float] = None,
+    chance_b: Optional[float] = None,
+    time: Optional[float] = None,
+    enabled: Optional[bool] = None,
+) -> dict:
+    """Set a clip's follow action (Live 12.0+). Any omitted arg preserves.
+
+    action_a/b values (string): stop, play_again, previous, next,
+      first, last, any, other, jump.
+    chance_a/b: probability 0.0-1.0. Live normalizes the split between
+      the two actions — set chance_b=0 to always fire action_a.
+    time: follow-action trigger time in beats (e.g. 1.0 = one bar in 4/4,
+      4.0 = one bar in 4/4 if the clip is 4 beats long).
+    enabled: master on/off for follow actions on this clip.
+    """
+    payload: dict = {"track_index": track_index, "clip_index": clip_index}
+    if action_a is not None:
+        payload["action_a"] = action_a
+    if action_b is not None:
+        payload["action_b"] = action_b
+    if chance_a is not None:
+        if not 0.0 <= chance_a <= 1.0:
+            raise ValueError("chance_a must be 0.0-1.0")
+        payload["chance_a"] = chance_a
+    if chance_b is not None:
+        if not 0.0 <= chance_b <= 1.0:
+            raise ValueError("chance_b must be 0.0-1.0")
+        payload["chance_b"] = chance_b
+    if time is not None:
+        if time < 0.0:
+            raise ValueError("time must be >= 0.0")
+        payload["time"] = time
+    if enabled is not None:
+        payload["enabled"] = enabled
+    return _get_ableton(ctx).send_command("set_clip_follow_action", payload)
+
+
+@mcp.tool()
+def clear_clip_follow_action(ctx: Context, track_index: int, clip_index: int) -> dict:
+    """Disable follow action on a clip (Live 12.0+).
+
+    Sets follow_action_enabled=False without touching the action/chance
+    values, so re-enabling keeps the previous configuration.
+    """
+    return _get_ableton(ctx).send_command("clear_clip_follow_action", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def list_follow_action_types(ctx: Context) -> dict:
+    """List valid follow-action names (Live 12.0+).
+
+    Returns the 9 enum values usable for action_a/action_b:
+    stop, play_again, previous, next, first, last, any, other, jump.
+    """
+    return _get_ableton(ctx).send_command("list_follow_action_types", {})
+
+
+@mcp.tool()
+def apply_follow_action_preset(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    preset: str,
+) -> dict:
+    """Apply a named follow-action preset to a clip (Live 12.0+).
+
+    Presets:
+      loop_forever    — re-fires the clip each bar indefinitely
+                        (action_a=play_again, chance 100%)
+      random_walk     — 50/50 split between next and previous clip
+      next_after_one  — play the clip once, advance to next slot
+      stop_after_one  — play the clip once, then stop
+    Each preset sets action_a, action_b, chance_a, chance_b, time
+    and enables follow actions. Time is 1.0 beat across all presets.
+    """
+    valid = ["loop_forever", "random_walk", "next_after_one", "stop_after_one"]
+    if preset not in valid:
+        raise ValueError("preset must be one of %s" % ", ".join(valid))
+    return _get_ableton(ctx).send_command("apply_follow_action_preset", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "preset": preset,
+    })
+
+
+# ── Scene follow actions (Live 12.2+) ────────────────────────────────────
+
+
+@mcp.tool()
+def get_scene_follow_action(ctx: Context, scene_index: int) -> dict:
+    """Read a scene's follow-action state (Live 12.2+).
+
+    Returns:
+        enabled:    bool — scene follow-action master switch
+        time:       trigger time in beats
+        linked:     True = "Longest" mode (waits for longest clip's loop)
+        multiplier: 1-8, used when not linked (time * multiplier = trigger)
+    """
+    return _get_ableton(ctx).send_command("get_scene_follow_action", {
+        "scene_index": scene_index,
+    })
+
+
+@mcp.tool()
+def set_scene_follow_action(
+    ctx: Context,
+    scene_index: int,
+    enabled: Optional[bool] = None,
+    time: Optional[float] = None,
+    linked: Optional[bool] = None,
+    multiplier: Optional[int] = None,
+) -> dict:
+    """Set a scene's follow action (Live 12.2+). Any omitted arg preserves.
+
+    enabled:    on/off master switch for this scene's follow action
+    time:       trigger time in beats (e.g. 4.0 = one bar in 4/4)
+    linked:     True = "Longest" mode — waits for the longest clip in
+                the scene to complete one loop
+    multiplier: 1-8 — multiplies `time` when not linked. Used to trigger
+                the follow action every N beats.
+    """
+    payload: dict = {"scene_index": scene_index}
+    if enabled is not None:
+        payload["enabled"] = enabled
+    if time is not None:
+        if time < 0.0:
+            raise ValueError("time must be >= 0.0")
+        payload["time"] = time
+    if linked is not None:
+        payload["linked"] = linked
+    if multiplier is not None:
+        if not 1 <= multiplier <= 8:
+            raise ValueError("multiplier must be 1-8")
+        payload["multiplier"] = multiplier
+    return _get_ableton(ctx).send_command("set_scene_follow_action", payload)
+
+
+@mcp.tool()
+def clear_scene_follow_action(ctx: Context, scene_index: int) -> dict:
+    """Disable a scene's follow action (Live 12.2+).
+
+    Sets follow_action_enabled=False without touching time/linked/
+    multiplier, so re-enabling preserves the prior configuration.
+    """
+    return _get_ableton(ctx).send_command("clear_scene_follow_action", {
+        "scene_index": scene_index,
+    })

package/mcp_server/tools/grooves.py

@@ -0,0 +1,142 @@
+"""Groove Pool tools (Live 11+).
+
+7 tools matching the Remote Script grooves domain:
+- list_grooves / get_groove_info — enumerate the pool and inspect.
+- set_groove_params — adjust quantization/random/timing/velocity amounts.
+- assign_clip_groove / get_clip_groove — per-clip groove binding
+  (pass ``groove_id = -1`` to clear).
+- get/set_song_groove_amount — master groove dial (0.0-1.31).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+@mcp.tool()
+def list_grooves(ctx: Context) -> dict:
+    """List all grooves in the Groove Pool (Live 11+).
+
+    Returns each groove's id (index), name, base quantization grid
+    (integer enum, e.g. 1/16th = 4), quantization_amount, random_amount,
+    timing_amount, and velocity_amount. Use the id with
+    assign_clip_groove() or set_groove_params().
+    """
+    return _get_ableton(ctx).send_command("list_grooves", {})
+
+
+@mcp.tool()
+def get_groove_info(ctx: Context, groove_id: int) -> dict:
+    """Read a single groove's parameters (Live 11+).
+
+    groove_id is the index from list_grooves(). Returns the same shape
+    as one entry of list_grooves().
+    """
+    return _get_ableton(ctx).send_command("get_groove_info", {
+        "groove_id": groove_id,
+    })
+
+
+@mcp.tool()
+def set_groove_params(
+    ctx: Context,
+    groove_id: int,
+    quantization_amount: Optional[float] = None,
+    random_amount: Optional[float] = None,
+    timing_amount: Optional[float] = None,
+    velocity_amount: Optional[float] = None,
+) -> dict:
+    """Adjust a groove's parameters (Live 11+). Omitted args preserve.
+
+    Ranges:
+      quantization_amount, random_amount, timing_amount: 0.0-1.0
+      velocity_amount: -1.0 to 1.0 (signed — negative subtracts velocity)
+    Any field left unspecified keeps its current value. Returns the
+    full groove_info dict after the update.
+    """
+    payload: dict = {"groove_id": groove_id}
+    if quantization_amount is not None:
+        if not 0.0 <= quantization_amount <= 1.0:
+            raise ValueError("quantization_amount must be 0.0-1.0")
+        payload["quantization_amount"] = quantization_amount
+    if random_amount is not None:
+        if not 0.0 <= random_amount <= 1.0:
+            raise ValueError("random_amount must be 0.0-1.0")
+        payload["random_amount"] = random_amount
+    if timing_amount is not None:
+        if not 0.0 <= timing_amount <= 1.0:
+            raise ValueError("timing_amount must be 0.0-1.0")
+        payload["timing_amount"] = timing_amount
+    if velocity_amount is not None:
+        if not -1.0 <= velocity_amount <= 1.0:
+            raise ValueError("velocity_amount must be -1.0 to 1.0")
+        payload["velocity_amount"] = velocity_amount
+    return _get_ableton(ctx).send_command("set_groove_params", payload)
+
+
+@mcp.tool()
+def assign_clip_groove(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    groove_id: int = -1,
+) -> dict:
+    """Assign a groove to a clip (Live 11+).
+
+    groove_id: integer index from list_grooves(), or -1 to clear the
+    clip's groove (sets clip.groove = None). Returns
+    {track_index, clip_index, groove_id, groove_name} — both id and
+    name are None when cleared.
+    """
+    return _get_ableton(ctx).send_command("assign_clip_groove", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "groove_id": groove_id,
+    })
+
+
+@mcp.tool()
+def get_clip_groove(ctx: Context, track_index: int, clip_index: int) -> dict:
+    """Read a clip's current groove assignment (Live 11+).
+
+    Returns {groove_id, groove_name}. Both are null/None if the clip
+    has no groove assigned.
+    """
+    return _get_ableton(ctx).send_command("get_clip_groove", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def get_song_groove_amount(ctx: Context) -> dict:
+    """Read the master groove amount dial (Live 11+).
+
+    Scales the effect of ALL assigned grooves on playback. 0.0 = no
+    groove influence; 1.0 = nominal; up to 1.31 = exaggerated.
+    """
+    return _get_ableton(ctx).send_command("get_song_groove_amount", {})
+
+
+@mcp.tool()
+def set_song_groove_amount(ctx: Context, amount: float) -> dict:
+    """Set the master groove amount dial (Live 11+).
+
+    Scales all grooves' effect on playback. Range 0.0-1.31.
+    Live's spec nominally caps at 1.0 but the exposed property
+    accepts values up to ~1.31, matching the UI's maximum nudge.
+    """
+    if not 0.0 <= amount <= 1.31:
+        raise ValueError("amount must be 0.0-1.31")
+    return _get_ableton(ctx).send_command("set_song_groove_amount", {
+        "amount": amount,
+    })

package/mcp_server/tools/miditool.py

@@ -0,0 +1,280 @@
+"""MIDI Tool bridge (Live 12.0+ MIDI Generators / Transformations).
+
+4 tools that let LivePilot generators run inside a clip's native
+MIDI Tool slot. Traffic rides the existing UDP 9880/9881 M4L bridge
+with a new /miditool/* OSC prefix; the user drops one of the
+companion .amxd files (LivePilot_MIDITool_Transform.amxd for
+Transformations, LivePilot_MIDITool_Generate.amxd for Generators)
+onto the clip and configures which generator handles the note list
+via ``set_miditool_target``. Both .amxd files share the same
+miditool_bridge.js logic — the only difference is whether
+``live.miditool.in`` is in Transformation or Generator mode.
+
+See ``m4l_device/MIDITOOL_BUILD_GUIDE.md`` for the Max build.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from .. import m4l_bridge as _bridge_module
+
+
+# ── Install paths ───────────────────────────────────────────────────────────
+
+_M4L_DIR = os.path.normpath(
+    os.path.join(
+        os.path.dirname(os.path.abspath(__file__)),
+        "..", "..", "m4l_device",
+    )
+)
+
+# Two .amxd variants. Live 12 classifies them as Generator or Transformation
+# via the 'nagg' vs 'natt' amxdtype marker in project.amxdtype. They install
+# into DIFFERENT User Library subfolders for each role — Live's MIDI Tool
+# indexer treats the folder as the authoritative category.
+_AMXD_VARIANTS = (
+    ("LivePilot_MIDITool_Generate.amxd",  "MIDI Tools/Max Generators"),
+    ("LivePilot_MIDITool_Transform.amxd", "MIDI Tools/Max Transformations"),
+)
+
+# Also copy the JS bridge alongside the .amxd so Max can find it — the
+# device references `js miditool_bridge.js` and Max searches relative to
+# the .amxd's location.
+_BRIDGE_JS = "miditool_bridge.js"
+
+_MACOS_USER_LIB = os.path.expanduser("~/Music/Ableton/User Library")
+
+_BUILD_GUIDE_REL = "m4l_device/MIDITOOL_BUILD_GUIDE.md"
+
+
+def _get_miditool_cache(ctx: Context):
+    """Resolve the MidiToolCache from the lifespan context."""
+    cache = ctx.lifespan_context.get("miditool")
+    if cache is None:
+        raise ValueError(
+            "MIDI Tool cache not initialized — restart the MCP server"
+        )
+    return cache
+
+
+def _get_m4l_bridge(ctx: Context):
+    """Resolve the M4LBridge from the lifespan context."""
+    bridge = ctx.lifespan_context.get("m4l")
+    if bridge is None:
+        raise ValueError("M4L bridge not initialized — restart the MCP server")
+    return bridge
+
+
+# ── Tool 1: install_miditool_device ────────────────────────────────────────
+
+@mcp.tool()
+def install_miditool_device(ctx: Context) -> dict:
+    """Install LivePilot MIDI Tool .amxd files into Ableton's User Library.
+
+    Copies both variants from ``m4l_device/`` to the correct MIDI Tools
+    subfolders. Live 12 classifies a device as Generator vs Transformation
+    via the ``project.amxdtype`` marker ('nagg' vs 'natt') inside the .amxd,
+    AND indexes them from these specific folders:
+
+      - ``Generate.amxd``  → ``User Library/MIDI Tools/Max Generators/``
+      - ``Transform.amxd`` → ``User Library/MIDI Tools/Max Transformations/``
+
+    Also copies ``miditool_bridge.js`` alongside each .amxd so the ``[js]``
+    object can find it (Max searches relative to the .amxd's location).
+
+    Build the .amxd files first with ``scripts/build_miditool_amxd.py``,
+    which patches Live's factory Max MIDI Generator/Transformation
+    templates with our bridge wiring while preserving the amxdtype marker.
+
+    After running this, right-click User Library in Live's browser →
+    Refresh. Then open a MIDI clip's Generators or Transformations
+    dropdown — ``LivePilot MIDI Tool (Generate/Transform)`` will be listed
+    under User:.
+
+    Returns ``{installed: [...], skipped: [...], user_library}``.
+    macOS-only for this chunk.
+    """
+    if platform.system() != "Darwin":
+        raise NotImplementedError(
+            "install_miditool_device currently supports macOS only. "
+            "Windows install path is ~/Documents/Ableton/User Library/... "
+            "— copy manually until Windows support ships."
+        )
+
+    bridge_src = os.path.join(_M4L_DIR, _BRIDGE_JS)
+    if not os.path.isfile(bridge_src):
+        raise FileNotFoundError(
+            f"Bridge JS not found at {bridge_src}. Source tree is missing "
+            "miditool_bridge.js — re-clone or check out the branch."
+        )
+
+    installed = []
+    skipped = []
+    for filename, subfolder in _AMXD_VARIANTS:
+        src = os.path.join(_M4L_DIR, filename)
+        if not os.path.isfile(src):
+            skipped.append({
+                "variant": filename,
+                "reason": f"source not found at {src}. Run "
+                          "scripts/build_miditool_amxd.py to build it.",
+            })
+            continue
+        dest_dir = os.path.join(_MACOS_USER_LIB, subfolder)
+        os.makedirs(dest_dir, exist_ok=True)
+        dest = os.path.join(dest_dir, filename)
+        existed_before = os.path.isfile(dest)
+        shutil.copy2(src, dest)
+        # Also copy the bridge JS into the same folder so Max's [js] object
+        # can find it at runtime.
+        shutil.copy2(bridge_src, os.path.join(dest_dir, _BRIDGE_JS))
+        installed.append({
+            "variant": filename,
+            "installed_path": dest,
+            "existed_before": existed_before,
+            "category": subfolder.split("/")[-1],
+        })
+
+    if not installed:
+        raise FileNotFoundError(
+            "No .amxd variants found in m4l_device/. Run "
+            "scripts/build_miditool_amxd.py first to build them from "
+            "Live's factory templates, then re-run install_miditool_device()."
+        )
+
+    return {
+        "installed": installed,
+        "skipped": skipped,
+        "user_library": _MACOS_USER_LIB,
+        "hint": (
+            "Right-click User Library in Live's browser → Refresh, then "
+            "open a MIDI clip's Generators (for Generate.amxd) or "
+            "Transformations (for Transform.amxd) dropdown. The LivePilot "
+            "devices appear in the User section. Call set_miditool_target() "
+            "to configure which generator handles incoming requests "
+            "before firing the tool on a clip."
+        ),
+    }
+
+
+# ── Tool 2: set_miditool_target ────────────────────────────────────────────
+
+@mcp.tool()
+def set_miditool_target(
+    ctx: Context,
+    tool_name: str,
+    params: Optional[dict] = None,
+) -> dict:
+    """Configure which LivePilot generator handles MIDI Tool requests.
+
+    When Live fires the MIDI Tool on a clip, the bridge forwards
+    ``(notes, context)`` to the server; the server invokes the configured
+    generator and pushes transformed notes back for Live to write into
+    the clip.
+
+    Args:
+        tool_name: One of the registered generators. Call
+                   ``list_miditool_generators()`` to see names and
+                   required params. v1.11.0 ships with
+                   ``euclidean_rhythm``, ``tintinnabuli``, ``humanize``.
+        params:    Generator-specific options (see
+                   ``list_miditool_generators``). Pass ``None`` or ``{}``
+                   to use defaults.
+
+    Returns ``{tool_name, params, active}``.
+    """
+    known = _bridge_module.available_generators()
+    if tool_name not in known:
+        raise ValueError(
+            f"Unknown generator '{tool_name}'. "
+            f"Registered generators: {', '.join(known)}. "
+            "Call list_miditool_generators() for descriptions."
+        )
+
+    params = dict(params or {})
+    cache = _get_miditool_cache(ctx)
+    cache.set_target(tool_name, params)
+
+    # Tell the JS bridge too so it knows what's queued even if it wants to
+    # show UI state. The bridge itself still asks the server to run the
+    # generator — this is informational + future-proofing.
+    bridge = _get_m4l_bridge(ctx)
+    try:
+        bridge.send_miditool_config(tool_name, params)
+        config_sent = True
+    except Exception:
+        # Bridge may not be up yet; not fatal — the server-side target is set.
+        config_sent = False
+
+    return {
+        "tool_name": tool_name,
+        "params": params,
+        "active": True,
+        "config_pushed_to_bridge": config_sent,
+    }
+
+
+# ── Tool 3: get_miditool_context ───────────────────────────────────────────
+
+@mcp.tool()
+def get_miditool_context(ctx: Context) -> dict:
+    """Return the most recent MIDI Tool context received from the bridge.
+
+    Fields come from Live's ``live.miditool.in`` right outlet:
+        grid:      current grid subdivision (float beats)
+        selection: {start, end} clip time range Live will replace
+        scale:     {root, name, mode} current Scale Mode state
+        seed:      RNG seed Live passes to the tool for determinism
+        tuning:    {name, reference_pitch} Tuning System info (12.1+)
+
+    Also returns ``note_count`` (how many notes arrived in the last
+    request) and ``connected`` (True once the bridge has pinged).
+
+    If the bridge hasn't emitted a request in the last ~5 seconds,
+    returns ``{"connected": False}`` — the analyzer/miditool .amxd
+    may not be loaded, or no MIDI Tool fire has happened yet.
+    """
+    cache = _get_miditool_cache(ctx)
+    if not cache.is_connected:
+        return {"connected": False}
+
+    ctx_data = cache.get_last_context() or {}
+    notes = cache.get_last_notes() or []
+
+    return {
+        "connected": True,
+        "grid": ctx_data.get("grid"),
+        "selection": ctx_data.get("selection"),
+        "scale": ctx_data.get("scale"),
+        "seed": ctx_data.get("seed"),
+        "tuning": ctx_data.get("tuning"),
+        "note_count": len(notes),
+    }
+
+
+# ── Tool 4: list_miditool_generators ───────────────────────────────────────
+
+@mcp.tool()
+def list_miditool_generators(ctx: Context) -> dict:
+    """Enumerate the generators available for MIDI Tool targets.
+
+    Each entry reports ``name``, ``description``, ``required_params``,
+    and ``optional_params``. Use the names with
+    ``set_miditool_target(tool_name=...)`` to configure the bridge.
+    """
+    entries = []
+    for name in _bridge_module.available_generators():
+        meta = _bridge_module.GENERATOR_METADATA.get(name, {})
+        entries.append({
+            "name": name,
+            "description": meta.get("description", ""),
+            "required_params": list(meta.get("required_params", [])),
+            "optional_params": list(meta.get("optional_params", [])),
+        })
+    return {"generators": entries, "count": len(entries)}