livepilot 1.16.0 → 1.17.0

package/mcp_server/tools/analyzer.py

@@ -212,6 +212,7 @@ async def get_master_spectrum(
     ctx: Context,
     window_ms: int = 0,
     samples: int = 0,
+    sub_detail: bool = False,
 ) -> dict:
     """Get 8-band frequency analysis of the master bus.
 
@@ -236,6 +237,14 @@ async def get_master_spectrum(
     The sampled bands are also returned as `bands_min`, `bands_max` and
     `bands_std` so callers can see variance within the window — useful
     for detecting transient-heavy content vs. sustained material.
+
+    BUG-2026-04-22#15 fix — sub-band resolution:
+      Pass `sub_detail=True` to attach a `sub_detail` dict with three
+      finer buckets: `sub_deep` (20-45 Hz), `sub_mid` (45-60 Hz),
+      `sub_high` (60-80 Hz). Derived from the FluCoMa mel spectrum
+      (40 bands) rather than the 8-band cache, so it requires FluCoMa
+      to be active. When FluCoMa is unavailable, sub_detail is omitted
+      with a `sub_detail_warning` field explaining why.
     """
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
@@ -291,6 +300,8 @@ async def get_master_spectrum(
         key_data = cache.get("key")
         if key_data:
             result["detected_key"] = key_data["value"]
+        if sub_detail:
+            _attach_sub_detail(cache, result)
         return result
 
     # Legacy instantaneous path
@@ -303,10 +314,55 @@ async def get_master_spectrum(
     key_data = cache.get("key")
     if key_data:
         result["detected_key"] = key_data["value"]
+    if sub_detail:
+        _attach_sub_detail(cache, result)
 
     return result
 
 
+def _attach_sub_detail(cache, result: dict) -> None:
+    """Compute finer sub-band breakdown (20-45, 45-60, 60-80 Hz) from
+    FluCoMa's 40-band mel spectrum and attach to the result dict.
+
+    Mel band edges are perceptual, not linear Hz — we map approximately:
+    with a standard 40-band mel filterbank from 0-20kHz, the first
+    ~4 bands cover 0-80 Hz and are distributed roughly:
+      band 0: ~0-25 Hz
+      band 1: ~25-45 Hz
+      band 2: ~45-65 Hz
+      band 3: ~65-90 Hz
+    We use these mappings as approximations; exact cutoffs depend on
+    FluCoMa's filterbank config but this is tight enough for mixing
+    decisions (the question is "is energy in the 30 Hz or 60 Hz range?").
+    """
+    mel_snap = cache.get("mel_bands")
+    if not mel_snap or not mel_snap.get("value"):
+        result["sub_detail_warning"] = (
+            "FluCoMa mel spectrum not available — sub_detail requires "
+            "FluCoMa active on the M4L analyzer. Use check_flucoma to diagnose."
+        )
+        return
+    mel_bands = mel_snap["value"]
+    if not isinstance(mel_bands, list) or len(mel_bands) < 4:
+        result["sub_detail_warning"] = (
+            f"Mel spectrum has {len(mel_bands) if isinstance(mel_bands, list) else 0} "
+            "bands — need at least 4 for sub_detail decomposition."
+        )
+        return
+
+    def _mean(indices):
+        vals = [float(mel_bands[i]) for i in indices if i < len(mel_bands)]
+        return round(sum(vals) / len(vals), 4) if vals else 0.0
+
+    result["sub_detail"] = {
+        "sub_deep": _mean([0, 1]),      # ~0-45 Hz (kick fundamental)
+        "sub_mid": _mean([2]),          # ~45-60 Hz (808 body / kick upper)
+        "sub_high": _mean([3]),         # ~60-80 Hz (bass guitar low, sub-bass crossover)
+        "age_ms": mel_snap.get("age_ms"),
+        "source": "flucoma_mel_40",
+    }
+
+
 def _sanitize_pitch(pitch: Optional[dict]) -> Optional[dict]:
     """Validate a pitch reading from the M4L analyzer (BUG-F1).
 
@@ -751,7 +807,10 @@ async def add_drum_rack_pad(
       "method": "native_12_4",
     }
     """
-    from .._analyzer_engine.sample import _simpler_post_load_hygiene  # noqa
+    # _simpler_post_load_hygiene is already imported at module scope
+    # (line 29). Do not re-import inline — the earlier inline form used
+    # the wrong relative path (..; should've been .) and crashed at
+    # runtime with "No module named 'mcp_server._analyzer_engine'".
     ableton = ctx.lifespan_context["ableton"]
     caps = _live_caps(ctx)
     if not caps.has_replace_sample_native:
@@ -1534,6 +1593,96 @@ async def verify_device_health(
     }
 
 
+@mcp.tool()
+async def verify_all_devices_health(
+    ctx: Context,
+    test_midi_note: int = 60,
+    test_velocity: int = 100,
+    test_duration_ms: int = 250,
+    threshold: float = 0.005,
+    skip_audio_tracks: bool = True,
+    skip_empty_tracks: bool = True,
+) -> dict:
+    """Run verify_device_health across every eligible track in one call.
+
+    Session-wide silent-track detector. Useful right after opening a
+    project to surface dead plugins before mixing. Serial execution —
+    firing notes in parallel would make the meter readings ambiguous.
+
+    skip_audio_tracks:  audio tracks have no MIDI input, skip them (default True)
+    skip_empty_tracks:  tracks without any instrument also skip (default True)
+
+    Returns: {
+      "ok": bool,
+      "tracks_tested": int,
+      "alive": [track_index...],
+      "dead": [{track_index, track_name, peak_level}...],
+      "skipped": [{track_index, reason}...],
+    }
+    """
+    ableton = ctx.lifespan_context["ableton"]
+    try:
+        session = ableton.send_command("get_session_info", {})
+    except Exception as exc:
+        return {"ok": False, "error": f"get_session_info failed: {exc}"}
+    if not isinstance(session, dict):
+        return {"ok": False, "error": "Unexpected get_session_info response"}
+
+    tracks = session.get("tracks", []) or []
+    alive: list = []
+    dead: list = []
+    skipped: list = []
+
+    for t in tracks:
+        tid = t.get("index")
+        tname = t.get("name", f"Track {tid}")
+        if tid is None:
+            continue
+        is_audio = bool(t.get("is_audio_track") or t.get("type") == "audio")
+        if skip_audio_tracks and is_audio:
+            skipped.append({"track_index": tid, "track_name": tname,
+                            "reason": "audio_track_no_midi_input"})
+            continue
+        devices = t.get("devices") or []
+        if skip_empty_tracks and not devices:
+            skipped.append({"track_index": tid, "track_name": tname,
+                            "reason": "no_devices_on_track"})
+            continue
+
+        # Run the per-track health check.
+        result = await verify_device_health(
+            ctx, track_index=tid,
+            test_midi_note=test_midi_note,
+            test_velocity=test_velocity,
+            test_duration_ms=test_duration_ms,
+            threshold=threshold,
+        )
+        if not result.get("ok"):
+            skipped.append({"track_index": tid, "track_name": tname,
+                            "reason": result.get("error", "health_check_failed")})
+            continue
+        if result.get("alive"):
+            alive.append(tid)
+        else:
+            dead.append({
+                "track_index": tid,
+                "track_name": tname,
+                "peak_level": result.get("peak_level", 0),
+            })
+
+    return {
+        "ok": True,
+        "tracks_tested": len(alive) + len(dead),
+        "alive": alive,
+        "dead": dead,
+        "skipped": skipped,
+        "summary": (
+            f"{len(alive)} alive, {len(dead)} dead, "
+            f"{len(skipped)} skipped out of {len(tracks)} total tracks"
+        ),
+    }
+
+
 @mcp.tool()
 def get_momentary_loudness(ctx: Context) -> dict:
     """Get EBU R128 momentary LUFS + true peak from FluCoMa.

package/mcp_server/tools/automation.py

@@ -602,3 +602,171 @@ def analyze_for_automation(
         "spectrum": spectrum,
         "suggestions": suggestions,
     }
+
+
+# ── Track-level arrangement automation workaround (T5, 2026-04-22 handoff) ─
+#
+# The Live LOM has a well-known gap: you cannot directly write a
+# TRACK-level automation envelope into arrangement between clips or
+# outside any clip. You can only write CLIP-level automation (which
+# lives inside a specific clip). The workaround is the classic
+# session-clip + record-to-arrangement dance:
+#
+#   1. Build a session clip with the automation (set_clip_automation)
+#   2. Arm the track
+#   3. Jump to the target beat
+#   4. Start arrangement recording
+#   5. Fire the session clip
+#   6. Wait for the clip to play through at tempo
+#   7. Stop recording
+#   8. Stop the session clip (return control to arrangement)
+#
+# The recorded arrangement clip has the automation rendered as a native
+# arrangement envelope — which IS writable by Live even when the LOM
+# disallows direct API access.
+
+@mcp.tool()
+async def set_arrangement_automation_via_session_record(
+    ctx: Context,
+    track_index: int,
+    parameter_type: str,
+    points: list | str,
+    target_beat: float,
+    duration_beats: float,
+    session_clip_slot: int = 0,
+    device_index: Optional[int] = None,
+    parameter_index: Optional[int] = None,
+    send_index: Optional[int] = None,
+    cleanup_session_clip: bool = True,
+) -> dict:
+    """Write an arrangement automation envelope at a specific beat via session record.
+
+    Workaround for the Live LOM limitation that prevents direct writing of
+    track-level arrangement automation outside of an existing arrangement
+    clip. Creates a temporary session clip with the automation, arms the
+    track, records the clip into arrangement at target_beat, then cleans
+    up. The recorded arrangement clip has the automation baked in.
+
+    **Status: LIVE** as of 2026-04-22. Uses a two-phase protocol so Live's
+    main thread never blocks: phase 1 (start) fires the session clip into
+    arrangement record; this tool then asyncio.sleeps for the expected
+    record duration (computed from the live tempo that phase 1 returns);
+    phase 2 (complete) stops record, cleans up, and returns the new
+    arrangement clip's index + start/length. Total wall time ≈
+    duration_beats × 60/tempo + 0.5s handler overhead.
+
+    parameter_type:       "device" | "volume" | "panning" | "send"
+    points:               [{time, value, duration?}] — time relative to
+                          the session clip's start (0.0 = first beat)
+    target_beat:          where the recording should begin in the
+                          arrangement timeline (beats)
+    duration_beats:       how long to record (usually matches the session
+                          clip's natural length, but may be longer for
+                          multiple repeats)
+    session_clip_slot:    which session clip slot to use (default 0 — must
+                          be EMPTY or its current content will be overwritten)
+    device_index,
+    parameter_index:      required for parameter_type="device"
+    send_index:           required for parameter_type="send" (0=A, 1=B)
+    cleanup_session_clip: delete the temp session clip after recording
+                          completes (default True)
+
+    Returns a dict with the recorded arrangement clip index + verification
+    info, or an error if any step failed. Because this orchestrates a
+    real-time recording, any of the steps can fail at runtime (track
+    not armable, session clip already running, transport not cooperating).
+    Each failure is reported with the stage it happened at.
+    """
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0 (track-level automation only supports regular tracks)")
+    if parameter_type not in ("device", "volume", "panning", "send"):
+        raise ValueError("parameter_type must be 'device', 'volume', 'panning', or 'send'")
+    if parameter_type == "device":
+        if device_index is None or parameter_index is None:
+            raise ValueError("device_index and parameter_index required for parameter_type='device'")
+    if parameter_type == "send" and send_index is None:
+        raise ValueError("send_index required for parameter_type='send'")
+    points_list = _ensure_list(points)
+    if not points_list:
+        raise ValueError("points list cannot be empty")
+    if target_beat < 0:
+        raise ValueError("target_beat must be >= 0")
+    if duration_beats <= 0:
+        raise ValueError("duration_beats must be > 0")
+
+    ableton = _get_ableton(ctx)
+
+    # Two-phase protocol — the start handler can't block Live's main thread
+    # for the full recording duration (audio dropouts, UI freezes). So:
+    #   1. start — writes session clip, arms, seeks, fires, enables record
+    #   2. MCP-side asyncio.sleep for duration + buffer
+    #   3. complete — stops record, cleans up, returns arrangement clip info
+    # The session-clip route is unchanged; the orchestration moved to us.
+    start_params: dict = {
+        "track_index": track_index,
+        "parameter_type": parameter_type,
+        "points": points_list,
+        "target_beat": target_beat,
+        "duration_beats": duration_beats,
+        "session_clip_slot": session_clip_slot,
+    }
+    if device_index is not None:
+        start_params["device_index"] = device_index
+    if parameter_index is not None:
+        start_params["parameter_index"] = parameter_index
+    if send_index is not None:
+        start_params["send_index"] = send_index
+
+    start_result = ableton.send_command(
+        "arrangement_automation_via_session_record_start",
+        start_params,
+    )
+    if not isinstance(start_result, dict) or start_result.get("status") != "recording":
+        return {
+            "ok": False,
+            "phase": "start",
+            "error": "arrangement record failed to engage",
+            "details": start_result,
+        }
+
+    # Compute sleep: duration_beats * 60/tempo seconds + 0.5s buffer for
+    # Live's record-arm latency. Tempo comes back from the start handler
+    # (fresh Song.tempo read) so we don't hardcode 120.
+    import asyncio
+    tempo = float(start_result.get("tempo") or 120.0)
+    if tempo <= 0:
+        tempo = 120.0
+    seconds_per_beat = 60.0 / tempo
+    sleep_sec = duration_beats * seconds_per_beat + 0.5
+    # Safety ceiling — if something is misconfigured we shouldn't sleep
+    # forever. 10 minutes is far beyond any realistic arrangement clip.
+    sleep_sec = min(sleep_sec, 600.0)
+    try:
+        await asyncio.sleep(sleep_sec)
+    except Exception as exc:
+        # Even if sleep fails we try to complete so we don't leave the
+        # track armed + recording.
+        logger.warning("sleep interrupted: %s", exc)
+
+    complete_params = {
+        "track_index": track_index,
+        "session_clip_slot": session_clip_slot,
+        "target_beat": target_beat,
+        "duration_beats": duration_beats,
+        "cleanup_session_clip": cleanup_session_clip,
+    }
+    complete_result = ableton.send_command(
+        "arrangement_automation_via_session_record_complete",
+        complete_params,
+    )
+    ok = (
+        isinstance(complete_result, dict)
+        and complete_result.get("status") == "completed"
+    )
+    return {
+        "ok": bool(ok),
+        "tempo": tempo,
+        "slept_sec": sleep_sec,
+        "start": start_result,
+        "complete": complete_result,
+    }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 421 tools, 52 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
+  "description": "Agentic production system for Ableton Live 12 — 426 tools, 52 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
   "author": "Pilot Studio",
   "license": "BSL-1.1",
   "type": "commonjs",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.16.0"
+__version__ = "1.17.0"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router

package/remote_script/LivePilot/arrangement.py

@@ -1,7 +1,14 @@
 """
-LivePilot - Arrangement domain handlers (19 commands).
+LivePilot - Arrangement domain handlers (21 commands).
+
+As of 2026-04-22: adds the two-phase session-record workaround for
+track-level arrangement automation (T5 handoff). Live's LOM can't
+write track-level automation envelopes outside a clip directly —
+this handler pair writes to a session clip, records it into
+arrangement at a target beat, then cleans up.
 """
 
+from .clip_automation import set_clip_automation as _set_clip_automation_handler
 from .router import register
 from .utils import get_track
 
@@ -866,3 +873,211 @@ def force_arrangement(song, params):
         "is_playing": song.is_playing,
         "loop": song.loop,
     }
+
+
+# ── Session-record arrangement automation (T5 workaround) ────────────
+#
+# Two-phase protocol so the MCP server can sleep between the record
+# start and stop without blocking Live's main thread.
+#
+#   Phase 1: _start — write session clip, arm, seek, record, fire
+#   Phase 2: _complete — stop record, stop transport, locate new
+#                       arrangement clip, clean up session clip
+#
+# The MCP tool layer orchestrates: start → asyncio.sleep(duration * 60/tempo + 0.5) → complete.
+
+
+def _fire_slot(slot):
+    """Fire a clip slot robustly — Live's API changed between versions."""
+    # Newer Live: slot.fire() is the canonical way. `slot.clip.fire()`
+    # also works when a clip is present. Try slot-level first so empty
+    # slots (we may have just created a clip) fire the row reliably.
+    try:
+        slot.fire()
+    except AttributeError:
+        slot.clip.fire()
+
+
+def _ensure_session_clip_length(slot, points, min_length=1.0):
+    """Ensure slot has a session MIDI clip covering the points' time range.
+
+    Returns (clip, was_created). If the slot is empty we call
+    create_clip(length). If points extend past the existing clip
+    we leave it alone — the user may have intentional content before.
+    """
+    if not slot.has_clip:
+        max_t = 0.0
+        for p in points or []:
+            t = float(p.get("time", 0))
+            d = float(p.get("duration", 0.125))
+            max_t = max(max_t, t + d)
+        length = max(min_length, max_t)
+        slot.create_clip(length)
+        return slot.clip, True
+    return slot.clip, False
+
+
+@register("arrangement_automation_via_session_record_start")
+def arrangement_automation_via_session_record_start(song, params):
+    """Phase 1 of the T5 workaround.
+
+    Preps the record: ensures session clip exists with automation, arms
+    the track, seeks the arrangement to target_beat, enables record, and
+    fires the session clip. Returns tempo so the MCP layer can compute
+    the sleep duration before phase 2.
+    """
+    track_index = int(params["track_index"])
+    session_clip_slot = int(params.get("session_clip_slot", 0))
+    target_beat = float(params["target_beat"])
+    parameter_type = params["parameter_type"]
+    points = params.get("points") or []
+    if not points:
+        raise ValueError("points cannot be empty")
+
+    track = get_track(song, track_index)
+
+    # Probe 1: can we arm this track?
+    if not getattr(track, "can_be_armed", False):
+        raise ValueError(
+            "track %d cannot be armed — session-record workaround requires "
+            "an armable (MIDI or audio input) track" % track_index
+        )
+
+    slots = list(track.clip_slots)
+    if session_clip_slot < 0 or session_clip_slot >= len(slots):
+        raise IndexError(
+            "session_clip_slot %d out of range (0..%d)"
+            % (session_clip_slot, len(slots) - 1)
+        )
+    slot = slots[session_clip_slot]
+
+    # Probe 2: create a session clip if the slot is empty; otherwise reuse
+    clip, created = _ensure_session_clip_length(slot, points)
+
+    # Probe 3: write the automation envelope via the existing handler.
+    # We need to tell set_clip_automation which clip_index to target.
+    # set_clip_automation takes clip_index = the slot index. Perfect.
+    clip_auto_params = dict(params)
+    clip_auto_params["clip_index"] = session_clip_slot
+    # Drop keys that set_clip_automation doesn't expect
+    for k in ("target_beat", "duration_beats", "session_clip_slot",
+              "cleanup_session_clip"):
+        clip_auto_params.pop(k, None)
+    write_result = _set_clip_automation_handler(song, clip_auto_params)
+
+    # Probe 4: seek the arrangement to target_beat. Must be done
+    # BEFORE enabling record, or the record starts at wherever the
+    # playhead currently is.
+    song.back_to_arranger = True
+    song.current_song_time = max(0.0, target_beat)
+
+    # Probe 5: arm the track. Some tracks need `current_monitoring_state`
+    # clarification, but arming alone should route the session clip's
+    # output into arrangement record on most setups.
+    track.arm = True
+
+    # Probe 6: enable arrangement record + start transport. Live needs
+    # the transport playing for record_mode to engage.
+    if not song.is_playing:
+        song.start_playing()
+    song.record_mode = True
+
+    # Fire the session clip — its automation plays into arrangement.
+    _fire_slot(slot)
+
+    return {
+        "status": "recording",
+        "track_index": track_index,
+        "session_clip_slot": session_clip_slot,
+        "target_beat": song.current_song_time,
+        "tempo": float(song.tempo),
+        "session_clip_created": created,
+        "automation_write": write_result,
+        "record_mode": bool(song.record_mode),
+        "is_playing": bool(song.is_playing),
+    }
+
+
+@register("arrangement_automation_via_session_record_complete")
+def arrangement_automation_via_session_record_complete(song, params):
+    """Phase 2 of the T5 workaround.
+
+    Stops recording, stops transport, disarms the track, locates the
+    newly-recorded arrangement clip, and optionally cleans up the
+    temporary session clip used to source the automation.
+    """
+    track_index = int(params["track_index"])
+    session_clip_slot = int(params.get("session_clip_slot", 0))
+    cleanup = bool(params.get("cleanup_session_clip", True))
+    target_beat = float(params["target_beat"])
+    duration_beats = float(params.get("duration_beats", 0))
+
+    track = get_track(song, track_index)
+    slots = list(track.clip_slots)
+    if session_clip_slot < 0 or session_clip_slot >= len(slots):
+        raise IndexError(
+            "session_clip_slot %d out of range" % session_clip_slot
+        )
+    slot = slots[session_clip_slot]
+
+    # 1. Stop recording and transport
+    song.record_mode = False
+    was_playing = song.is_playing
+    if was_playing:
+        song.stop_playing()
+
+    # 2. Stop the session clip if still playing
+    try:
+        if slot.has_clip and getattr(slot, "is_playing", False):
+            slot.clip.stop()
+    except Exception:
+        pass
+
+    # 3. Disarm the track (leave as-was if never armed)
+    try:
+        track.arm = False
+    except Exception:
+        pass
+
+    # 4. Find the new arrangement clip at or near target_beat.
+    # Tolerance: half a beat — Live may nudge start by quantization.
+    track_clips = list(track.arrangement_clips)
+    new_clip = None
+    new_index = None
+    tolerance = 0.5
+    for i, c in enumerate(track_clips):
+        if abs(float(c.start_time) - target_beat) < tolerance:
+            new_clip = c
+            new_index = i
+            break
+
+    # 5. Cleanup the session clip if requested
+    session_clip_deleted = False
+    if cleanup and slot.has_clip:
+        try:
+            slot.delete_clip()
+            session_clip_deleted = True
+        except Exception:
+            pass
+
+    result = {
+        "status": "completed",
+        "track_index": track_index,
+        "arrangement_clip_found": new_clip is not None,
+        "arrangement_clip_index": new_index,
+        "session_clip_deleted": session_clip_deleted,
+        "record_mode": bool(song.record_mode),
+        "was_playing": was_playing,
+    }
+    if new_clip is not None:
+        result["arrangement_clip_start"] = float(new_clip.start_time)
+        result["arrangement_clip_length"] = float(new_clip.length)
+        try:
+            result["arrangement_clip_name"] = str(new_clip.name)
+        except Exception:
+            pass
+    elif duration_beats > 0:
+        # Guess based on expected range — helpful debug if the lookup missed
+        result["expected_clip_start"] = target_beat
+        result["expected_clip_end"] = target_beat + duration_beats
+    return result

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.dreamrec/livepilot",
-  "description": "421-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
+  "description": "426-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
   "repository": {
     "url": "https://github.com/dreamrec/LivePilot",
     "source": "github"
   },
-  "version": "1.16.0",
+  "version": "1.17.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.16.0",
+      "version": "1.17.0",
       "transport": {
         "type": "stdio"
       }