livepilot 1.10.8 → 1.10.9

package/mcp_server/tools/_analyzer_engine/context.py

@@ -0,0 +1,103 @@
+"""Analyzer lifespan-context accessors + health check.
+
+These were inline in ``analyzer.py`` pre-v1.10.9. Split out as part of
+BUG-C1 so the tool file contains only ``@mcp.tool()`` definitions.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from fastmcp import Context
+
+if TYPE_CHECKING:  # pragma: no cover — type-only imports
+    from ...m4l_bridge import M4LBridge, SpectralCache
+
+logger = logging.getLogger(__name__)
+
+
+def _get_spectral(ctx: Context):
+    """Get the SpectralCache from the lifespan context.
+
+    Attaches the active FastMCP ``Context`` to the cache so the analyzer
+    error path can distinguish "device missing" from "bridge disconnected"
+    — needed for the actionable error messages in ``_require_analyzer``.
+    """
+    cache = ctx.lifespan_context.get("spectral")
+    if not cache:
+        raise ValueError("Spectral cache not initialized — restart the MCP server")
+    setattr(cache, "_livepilot_ctx", ctx)
+    return cache
+
+
+def _get_m4l(ctx: Context):
+    """Get the M4LBridge from the lifespan context."""
+    bridge = ctx.lifespan_context.get("m4l")
+    if not bridge:
+        raise ValueError("M4L bridge not initialized — restart the MCP server")
+    return bridge
+
+
+def _require_analyzer(cache) -> None:
+    """Raise a user-actionable error if the analyzer device isn't reachable.
+
+    The error text is the most user-visible surface of the analyzer layer,
+    so it spends effort distinguishing:
+
+      * "not loaded on master" → concrete drag-and-drop instructions
+      * "loaded but UDP port 9880 held by another instance" → show the
+        PID/command of the holder so the user can close it
+      * "loaded but bridge disconnected for some other reason" → generic
+        reload/restart hint
+
+    The ``_livepilot_ctx`` attribute attached by ``_get_spectral`` is what
+    lets us probe the master-track devices here; without it, the caller
+    would have to pass ``ctx`` through every ``_require_analyzer`` site.
+    """
+    if cache.is_connected:
+        return
+
+    # Imported lazily to avoid a circular import: server.py imports this
+    # package's parent during tool registration.
+    from ...server import _identify_port_holder
+
+    ctx = getattr(cache, "_livepilot_ctx", None)
+    try:
+        track = (
+            ctx.lifespan_context["ableton"].send_command("get_master_track")
+            if ctx else {}
+        )
+    except Exception as exc:
+        logger.debug("_require_analyzer failed: %s", exc)
+        track = {}
+
+    devices = track.get("devices", []) if isinstance(track, dict) else []
+    analyzer_loaded = False
+    for device in devices:
+        normalized = " ".join(
+            str(device.get("name") or "").replace("_", " ").replace("-", " ").lower().split()
+        )
+        if normalized == "livepilot analyzer":
+            analyzer_loaded = True
+            break
+
+    if analyzer_loaded:
+        holder = _identify_port_holder(9880)
+        detail = (
+            "LivePilot Analyzer is loaded on the master track, but its UDP bridge is not connected. "
+        )
+        if holder:
+            detail += (
+                "UDP port 9880 is currently held by another LivePilot instance "
+                f"({holder}). Close the other client/server, then retry."
+            )
+        else:
+            detail += "Reload the analyzer device or restart the MCP server."
+        raise ValueError(detail)
+
+    raise ValueError(
+        "LivePilot Analyzer not detected. "
+        "Drag 'LivePilot Analyzer' onto the master track from "
+        "Audio Effects > Max Audio Effect."
+    )

package/mcp_server/tools/_analyzer_engine/flucoma.py

@@ -0,0 +1,23 @@
+"""FluCoMa-specific helpers (hints + pitch-name table).
+
+Extracted from ``analyzer.py`` as part of BUG-C1. Purely about formatting
+hints for the FluCoMa real-time streams — no Ableton or bridge access.
+"""
+
+from __future__ import annotations
+
+
+PITCH_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+
+
+def _flucoma_hint(cache) -> str:
+    """Return an error hint if no FluCoMa data has arrived on ``cache``.
+
+    If ANY stream has data, FluCoMa is working and the specific stream just
+    hasn't updated yet — return a 'play audio' hint. If NO streams have
+    data, FluCoMa may not be installed — return an install hint.
+    """
+    for key in ("spectral_shape", "mel_bands", "chroma", "loudness"):
+        if cache.get(key):
+            return "play some audio"
+    return "FluCoMa may not be installed. Install via: npx livepilot --setup-flucoma"

package/mcp_server/tools/_analyzer_engine/sample.py

@@ -0,0 +1,122 @@
+"""Simpler post-load hygiene + filename heuristics.
+
+Extracted from ``analyzer.py`` as part of BUG-C1. Covers:
+
+  * BPM-in-filename detection (used to tell warped loops from one-shots)
+  * Post-load verification + Snap=0 + warped-loop defaults for Simpler
+
+Context (docs/2026-04-14-bugs-discovered.md):
+
+The M4L bridge's ``replace_simpler_sample`` command can report success
+even when the sample is still the bootstrap placeholder. Simpler's
+display name also doesn't refresh after a replace. After loading, the
+``Snap`` parameter is ON by default which causes the Sample Start
+position to snap to a location outside the new sample's valid audio —
+resulting in silent playback. The hygiene here fixes both.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+
+logger = logging.getLogger(__name__)
+
+
+_BPM_IN_FILENAME_RE = re.compile(r"(\d{2,3})\s*bpm", re.IGNORECASE)
+
+
+def _is_warped_loop(file_path: str) -> bool:
+    """Return True if the filename contains a BPM marker (likely a tempo-locked loop)."""
+    stem = os.path.splitext(os.path.basename(file_path))[0]
+    return bool(_BPM_IN_FILENAME_RE.search(stem))
+
+
+def _filename_stem(file_path: str) -> str:
+    return os.path.splitext(os.path.basename(file_path))[0]
+
+
+async def _simpler_post_load_hygiene(
+    bridge,
+    ableton,
+    track_index: int,
+    device_index: int,
+    file_path: str,
+) -> dict:
+    """Apply post-load hygiene to a newly loaded Simpler and verify success.
+
+    Steps:
+      1. Read track info to verify the device's actual name matches the
+         expected sample stem. If it doesn't, return an error.
+      2. Set Snap=0 (Off) — required so sample playback works.
+      3. If filename indicates a warped loop, set S Start=0, S Length=1,
+         S Loop On=1 so the loop plays fully instead of being cropped.
+      4. Return a verified response dict.
+    """
+    expected_stem = _filename_stem(file_path)
+
+    # Step 1: verify device name matches expected file
+    try:
+        track_info = ableton.send_command(
+            "get_track_info", {"track_index": track_index}
+        )
+    except Exception as exc:
+        return {"error": f"Verification read failed: {exc}"}
+
+    devices = track_info.get("devices", []) or []
+    if device_index < 0 or device_index >= len(devices):
+        return {
+            "error": (
+                f"Device index {device_index} out of range after load "
+                f"(track has {len(devices)} devices)"
+            ),
+            "verified": False,
+        }
+    device = devices[device_index]
+    actual_name = str(device.get("name") or "")
+    verified = expected_stem in actual_name or actual_name in expected_stem
+    if not verified:
+        return {
+            "error": (
+                f"Sample verification FAILED — Simpler name '{actual_name}' "
+                f"does not match requested file '{expected_stem}'. The bridge "
+                f"reported success but the actual sample is different. "
+                f"Try `load_browser_item` with a user_library URI instead."
+            ),
+            "verified": False,
+            "actual_device_name": actual_name,
+            "expected_stem": expected_stem,
+        }
+
+    # Step 2: turn Snap OFF — required for reliable playback after replace
+    hygiene_params: list[dict] = [
+        {"name_or_index": "Snap", "value": 0},
+    ]
+
+    # Step 3: smart defaults for warped loops
+    if _is_warped_loop(file_path):
+        hygiene_params.extend([
+            {"name_or_index": "S Start", "value": 0.0},
+            {"name_or_index": "S Length", "value": 1.0},
+            {"name_or_index": "S Loop On", "value": 1},
+        ])
+
+    try:
+        ableton.send_command("batch_set_parameters", {
+            "track_index": track_index,
+            "device_index": device_index,
+            "parameters": hygiene_params,
+        })
+    except Exception as exc:
+        logger.debug("_simpler_post_load_hygiene failed: %s", exc)
+        # non-fatal — verification already succeeded
+        pass
+
+    return {
+        "verified": True,
+        "device_name": actual_name,
+        "track_index": track_index,
+        "device_index": device_index,
+        "warped_loop_defaults_applied": _is_warped_loop(file_path),
+    }

package/mcp_server/tools/_motif_engine.py

@@ -201,24 +201,39 @@ def detect_motifs(
         salience = _score_salience(pattern, len(occurrences), total_note_count)
         fatigue = _score_fatigue(len(occurrences), total_bars)
 
-        # Get representative pitches from first occurrence
+        # Get representative pitches + inter-onset intervals from first occurrence.
+        # Rhythm is the list of start_time deltas between successive notes in
+        # the pattern window; until v1.10.9 this field was left empty with a
+        # "TODO: Phase 3" marker, which is what forced Hook Hunter's rhythm
+        # side to fall back to drum-track-name regex. Populating it here lets
+        # downstream code actually reason about rhythmic distinctiveness.
         first_occ = occurrences[0] if occurrences else {}
         first_track = first_occ.get("track", 0)
         first_pos = first_occ.get("start_position", 0)
-        rep_pitches = []
+        rep_pitches: list[int] = []
+        rhythm_intervals: list[float] = []
         if first_track in notes_by_track:
             sorted_notes = sorted(notes_by_track[first_track],
                                   key=lambda n: n.get("start_time", 0))
+            span = min(len(pattern) + 1, len(sorted_notes) - first_pos)
             rep_pitches = [
                 sorted_notes[first_pos + j].get("pitch", 60)
-                for j in range(min(len(pattern) + 1, len(sorted_notes) - first_pos))
+                for j in range(span)
+            ]
+            rhythm_intervals = [
+                round(
+                    float(sorted_notes[first_pos + j + 1].get("start_time", 0.0))
+                    - float(sorted_notes[first_pos + j].get("start_time", 0.0)),
+                    4,
+                )
+                for j in range(span - 1)
             ]
 
         motif = MotifUnit(
             motif_id=f"motif_{len(motifs):03d}",
             kind="melodic" if any(abs(i) > 0 for i in pattern) else "rhythmic",
             intervals=list(pattern),
-            rhythm=[],  # TODO: rhythm detection in Phase 3
+            rhythm=rhythm_intervals,
             representative_pitches=rep_pitches,
             occurrences=occurrences,
             salience=salience,

package/mcp_server/tools/analyzer.py

@@ -2,90 +2,38 @@
 
 30 tools requiring the LivePilot Analyzer M4L device on the master track.
 These tools are optional — all core tools work without the device.
+
+Helpers live in ``_analyzer_engine/`` (context accessors, Simpler
+post-load hygiene, FluCoMa hint formatting). This file contains the
+``@mcp.tool()`` surface only — keeping decorator order stable was
+important for BUG-C1's refactor.
 """
 
 from __future__ import annotations
 
 import logging
 import os
-import re  # used below in filename parsing helpers
 from typing import Optional
 
 from fastmcp import Context
 
 from ..server import mcp, _identify_port_holder
+from ._analyzer_engine import (
+    PITCH_NAMES,
+    _filename_stem,
+    _flucoma_hint,
+    _get_m4l,
+    _get_spectral,
+    _is_warped_loop,
+    _require_analyzer,
+    _simpler_post_load_hygiene,
+)
 
-# Logger must be defined before any helper that uses it — _require_analyzer
-# below calls logger.debug on an exception path, so defining the logger later
-# in the file risked NameError under unusual import orderings.
 logger = logging.getLogger(__name__)
 
 CAPTURE_DIR = os.path.expanduser("~/Documents/LivePilot/captures")
 
 
-def _get_spectral(ctx: Context):
-    """Get SpectralCache from lifespan context."""
-    cache = ctx.lifespan_context.get("spectral")
-    if not cache:
-        raise ValueError("Spectral cache not initialized — restart the MCP server")
-    # Keep the active request context attached so analyzer error paths can
-    # distinguish "device missing" from "bridge disconnected".
-    setattr(cache, "_livepilot_ctx", ctx)
-    return cache
-
-
-def _get_m4l(ctx: Context):
-    """Get M4LBridge from lifespan context."""
-    bridge = ctx.lifespan_context.get("m4l")
-    if not bridge:
-        raise ValueError("M4L bridge not initialized — restart the MCP server")
-    return bridge
-
-
-def _require_analyzer(cache) -> None:
-    """Raise a helpful error if the analyzer is not connected."""
-    if not cache.is_connected:
-        ctx = getattr(cache, "_livepilot_ctx", None)
-        try:
-            track = (
-                ctx.lifespan_context["ableton"].send_command("get_master_track")
-                if ctx else {}
-            )
-        except Exception as exc:
-            logger.debug("_require_analyzer failed: %s", exc)
-            track = {}
-
-        devices = track.get("devices", []) if isinstance(track, dict) else []
-        analyzer_loaded = False
-        for device in devices:
-            normalized = " ".join(
-                str(device.get("name") or "").replace("_", " ").replace("-", " ").lower().split()
-            )
-            if normalized == "livepilot analyzer":
-                analyzer_loaded = True
-                break
-
-        if analyzer_loaded:
-            holder = _identify_port_holder(9880)
-            detail = (
-                "LivePilot Analyzer is loaded on the master track, but its UDP bridge is not connected. "
-            )
-            if holder:
-                detail += (
-                    "UDP port 9880 is currently held by another LivePilot instance "
-                    f"({holder}). Close the other client/server, then retry."
-                )
-            else:
-                detail += "Reload the analyzer device or restart the MCP server."
-            raise ValueError(detail)
-
-        raise ValueError(
-            "LivePilot Analyzer not detected. "
-            "Drag 'LivePilot Analyzer' onto the master track from "
-            "Audio Effects > Max Audio Effect."
-        )
-
-
 @mcp.tool()
 async def reconnect_bridge(ctx: Context) -> dict:
     """Attempt to reconnect the M4L UDP bridge (port 9880).
@@ -305,102 +253,10 @@ async def get_clip_file_path(
 #      S Start=0, S Length=1, S Loop On=1 so the full loop plays in its
 #      musical phrasing. For ONE-SHOTS, leave defaults alone.
 
-_BPM_IN_FILENAME_RE = re.compile(r"(\d{2,3})\s*bpm", re.IGNORECASE)
-
-
-def _is_warped_loop(file_path: str) -> bool:
-    """Return True if the filename contains a BPM marker (likely a tempo-locked loop)."""
-    stem = os.path.splitext(os.path.basename(file_path))[0]
-    return bool(_BPM_IN_FILENAME_RE.search(stem))
-
-
-def _filename_stem(file_path: str) -> str:
-    return os.path.splitext(os.path.basename(file_path))[0]
-
-
-async def _simpler_post_load_hygiene(
-    bridge,
-    ableton,
-    track_index: int,
-    device_index: int,
-    file_path: str,
-) -> dict:
-    """Apply post-load hygiene to a newly loaded Simpler and verify success.
-
-    Steps:
-      1. Read track info to verify the device's actual name matches the
-         expected sample stem. If it doesn't, return an error.
-      2. Set Snap=0 (Off) — required so sample playback works.
-      3. If filename indicates a warped loop, set S Start=0, S Length=1,
-         S Loop On=1 so the loop plays fully instead of being cropped.
-      4. Return a verified response dict.
-    """
-    expected_stem = _filename_stem(file_path)
-
-    # Step 1: verify device name matches expected file
-    try:
-        track_info = ableton.send_command(
-            "get_track_info", {"track_index": track_index}
-        )
-    except Exception as exc:
-        return {"error": f"Verification read failed: {exc}"}
-
-    devices = track_info.get("devices", []) or []
-    if device_index < 0 or device_index >= len(devices):
-        return {
-            "error": (
-                f"Device index {device_index} out of range after load "
-                f"(track has {len(devices)} devices)"
-            ),
-            "verified": False,
-        }
-    device = devices[device_index]
-    actual_name = str(device.get("name") or "")
-    verified = expected_stem in actual_name or actual_name in expected_stem
-    if not verified:
-        return {
-            "error": (
-                f"Sample verification FAILED — Simpler name '{actual_name}' "
-                f"does not match requested file '{expected_stem}'. The bridge "
-                f"reported success but the actual sample is different. "
-                f"Try `load_browser_item` with a user_library URI instead."
-            ),
-            "verified": False,
-            "actual_device_name": actual_name,
-            "expected_stem": expected_stem,
-        }
-
-    # Step 2: turn Snap OFF — required for reliable playback after replace
-    hygiene_params: list[dict] = [
-        {"name_or_index": "Snap", "value": 0},
-    ]
-
-    # Step 3: smart defaults for warped loops
-    if _is_warped_loop(file_path):
-        hygiene_params.extend([
-            {"name_or_index": "S Start", "value": 0.0},
-            {"name_or_index": "S Length", "value": 1.0},
-            {"name_or_index": "S Loop On", "value": 1},
-        ])
-
-    try:
-        ableton.send_command("batch_set_parameters", {
-            "track_index": track_index,
-            "device_index": device_index,
-            "parameters": hygiene_params,
-        })
-    except Exception as exc:
-        logger.debug("_simpler_post_load_hygiene failed: %s", exc)
-        # non-fatal — verification already succeeded
-        pass
-
-    return {
-        "verified": True,
-        "device_name": actual_name,
-        "track_index": track_index,
-        "device_index": device_index,
-        "warped_loop_defaults_applied": _is_warped_loop(file_path),
-    }
+# _BPM_IN_FILENAME_RE, _is_warped_loop, _filename_stem, and the
+# _simpler_post_load_hygiene coroutine now live in
+# ``_analyzer_engine/sample.py`` — re-exported via this module's imports
+# at the top of the file so tests importing them by name still resolve.
 
 
 @mcp.tool()
@@ -847,21 +703,9 @@ async def capture_stop(ctx: Context) -> dict:
     return await bridge.send_command("capture_stop")
 
 # ── Phase 4: FluCoMa Real-Time ───────────────────────────────────────────
-
-PITCH_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
-
-
-def _flucoma_hint(cache) -> str:
-    """Return an error hint if no FluCoMa data has arrived.
-
-    If ANY stream has data, FluCoMa is working and the specific stream just
-    hasn't updated yet — return a 'play audio' hint. If NO streams have data,
-    FluCoMa may not be installed — return an install hint.
-    """
-    for key in ("spectral_shape", "mel_bands", "chroma", "loudness"):
-        if cache.get(key):
-            return "play some audio"
-    return "FluCoMa may not be installed. Install via: npx livepilot --setup-flucoma"
+#
+# PITCH_NAMES + _flucoma_hint now live in ``_analyzer_engine/flucoma.py``
+# and are re-exported via the top-of-file imports for tests/subclassers.
 
 
 @mcp.tool()