livepilot 1.9.8 → 1.9.11

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.9.8"
+__version__ = "1.9.11"

package/mcp_server/connection.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import socket
+import subprocess
 import threading
 import time
 import uuid
@@ -44,6 +45,33 @@ def _friendly_error(code: str, message: str, command_type: str) -> str:
     return " ".join(parts)
 
 
+def _identify_other_tcp_client(host: str, port: int) -> str | None:
+    """Return a short description of another established client on the Live port."""
+    try:
+        out = subprocess.check_output(
+            ["lsof", "-nP", f"-iTCP:{port}"],
+            text=True,
+            timeout=3,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError, ValueError, OSError):
+        return None
+
+    target = f"->{host}:{port}"
+    my_pid = os.getpid()
+    for line in out.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) < 2 or target not in line or "(ESTABLISHED)" not in line:
+            continue
+        try:
+            pid = int(parts[1])
+        except ValueError:
+            continue
+        if pid == my_pid:
+            continue
+        return f"PID {pid} ({parts[0]})"
+    return None
+
+
 class AbletonConnection:
     """TCP client that sends JSON commands to the LivePilot Remote Script."""
 
@@ -197,6 +225,13 @@ class AbletonConnection:
         except socket.timeout as exc:
             self._recv_buf = buf
             self.disconnect()
+            other_client = _identify_other_tcp_client(self.host, self.port)
+            if other_client:
+                raise AbletonConnectionError(
+                    "Timeout waiting for response from Ableton. "
+                    f"Another LivePilot client appears to be connected on {self.host}:{self.port} "
+                    f"({other_client}). Disconnect the other client and retry."
+                ) from exc
             raise AbletonConnectionError(
                 f"Timeout waiting for response from Ableton ({RECV_TIMEOUT}s)"
             ) from exc

package/mcp_server/m4l_bridge.py

@@ -21,6 +21,50 @@ import time
 from typing import Any, Optional
 
 
+def _encode_string_arg(value: str) -> str:
+    """Encode a Python string arg into an ASCII-safe OSC payload.
+
+    The Max JS side decodes values with the ``b64:`` prefix back to UTF-8.
+    Keeping the wire payload ASCII-only avoids OSC/client issues with
+    non-ASCII file paths and device names.
+    """
+    encoded = base64.urlsafe_b64encode(value.encode("utf-8")).decode("ascii")
+    return "b64:" + encoded.rstrip("=")
+
+
+def _normalize_macos_path(path: str) -> str:
+    """Convert Max-style HFS-ish paths into POSIX paths when possible."""
+    if len(path) >= 3 and path[1] == ":" and path[2] in ("/", "\\"):
+        return path
+
+    colon = path.find(":")
+    slash = path.find("/")
+    if colon <= 0 or (slash != -1 and colon > slash):
+        return path
+
+    rest = path[colon + 1:]
+    if ":" in rest:
+        rest = rest.replace(":", "/")
+    if not rest.startswith("/"):
+        rest = "/" + rest.lstrip("/\\")
+    return rest
+
+
+def _normalize_bridge_payload(value: Any) -> Any:
+    """Normalize filesystem paths inside bridge payloads."""
+    if isinstance(value, dict):
+        normalized = {}
+        for key, item in value.items():
+            if key == "file_path" and isinstance(item, str):
+                normalized[key] = _normalize_macos_path(item)
+            else:
+                normalized[key] = _normalize_bridge_payload(item)
+        return normalized
+    if isinstance(value, list):
+        return [_normalize_bridge_payload(item) for item in value]
+    return value
+
+
 class SpectralCache:
     """Thread-safe cache for incoming spectral data from M4L.
 
@@ -226,7 +270,7 @@ class SpectralReceiver(asyncio.DatagramProtocol):
             # URL-safe base64 decode (- and _ instead of + and /)
             padded = encoded + "=" * (-len(encoded) % 4)
             decoded = base64.urlsafe_b64decode(padded).decode('utf-8')
-            result = json.loads(decoded)
+            result = _normalize_bridge_payload(json.loads(decoded))
             if self._response_callback and not self._response_callback.done():
                 self._response_callback.set_result(result)
         except Exception as exc:
@@ -256,7 +300,7 @@ class SpectralReceiver(asyncio.DatagramProtocol):
         try:
             padded = encoded + "=" * (-len(encoded) % 4)
             decoded = base64.urlsafe_b64decode(padded).decode('utf-8')
-            result = json.loads(decoded)
+            result = _normalize_bridge_payload(json.loads(decoded))
             if self._capture_future and not self._capture_future.done():
                 self._capture_future.set_result(result)
         except Exception as exc:
@@ -343,8 +387,13 @@ class M4LBridge:
             self.receiver._capture_future = None
 
     def _build_osc(self, address: str, args: tuple) -> bytes:
-        """Build a minimal OSC message."""
-        # Address string (null-terminated, padded to 4 bytes)
+        """Build a minimal OSC message.
+
+        OSC addresses are ASCII-only command names.
+        String arguments are encoded into an ASCII-safe ``b64:...`` payload
+        and decoded back to UTF-8 in the Max bridge.
+        """
+        # Address string — always ASCII (command names like "get_params")
         addr_bytes = address.encode('ascii') + b'\x00'
         while len(addr_bytes) % 4 != 0:
             addr_bytes += b'\x00'
@@ -361,7 +410,8 @@ class M4LBridge:
                 arg_data += struct.pack('>f', arg)
             elif isinstance(arg, str):
                 type_tags += "s"
-                s_bytes = arg.encode('ascii') + b'\x00'
+                encoded = _encode_string_arg(arg)
+                s_bytes = encoded.encode('ascii') + b'\x00'
                 while len(s_bytes) % 4 != 0:
                     s_bytes += b'\x00'
                 arg_data += s_bytes

package/mcp_server/server.py

@@ -3,7 +3,6 @@
 from contextlib import asynccontextmanager
 import asyncio
 import os
-import signal
 import subprocess
 
 from fastmcp import FastMCP, Context  # noqa: F401
@@ -12,12 +11,11 @@ from .connection import AbletonConnection
 from .m4l_bridge import SpectralCache, SpectralReceiver, M4LBridge
 
 
-def _kill_port_holder(port: int) -> None:
-    """Kill whichever process holds the given UDP port.
+def _identify_port_holder(port: int) -> str | None:
+    """Identify which process holds the given UDP port (for logging only).
 
-    Used to reclaim port 9880 when a stale duplicate server instance
-    is hogging it (common when both project .mcp.json and plugin
-    .mcp.json launch the server).
+    Returns a string like "PID 12345 (python3 mcp_server)" or None if
+    identification fails. Never kills or modifies the holder.
     """
     try:
         out = subprocess.check_output(
@@ -29,18 +27,17 @@ def _kill_port_holder(port: int) -> None:
         for pid_str in out.splitlines():
             pid = int(pid_str)
             if pid != my_pid:
-                # Only kill if it looks like a Python/LivePilot process
                 try:
                     cmdline = subprocess.check_output(
                         ["ps", "-p", str(pid), "-o", "command="],
                         text=True, timeout=2,
                     ).strip()
-                    if "mcp_server" in cmdline or "livepilot" in cmdline.lower():
-                        os.kill(pid, signal.SIGTERM)
+                    return f"{pid} ({cmdline[:60]})"
                 except (subprocess.CalledProcessError, FileNotFoundError):
-                    pass  # Can't verify — don't kill
+                    return str(pid)
+        return None
     except (subprocess.CalledProcessError, FileNotFoundError, ValueError):
-        pass  # lsof not found or no process — nothing to kill
+        return None
 
 
 @asynccontextmanager
@@ -60,28 +57,18 @@ async def lifespan(server):
             local_addr=('127.0.0.1', 9880),
         )
     except OSError:
-        # Port 9880 already bound — likely a duplicate server instance
-        # (project .mcp.json + plugin .mcp.json both launching).
-        # Kill the stale holder so this instance gets the port.
+        # Port 9880 already bound — another LivePilot instance is running.
+        # Do NOT kill the holder; degrade gracefully instead.
         import sys
+        holder_info = _identify_port_holder(9880)
         print(
-            "LivePilot: UDP port 9880 in use — reclaiming from stale instance",
+            "LivePilot: UDP port 9880 already in use%s — "
+            "analyzer/bridge tools will be unavailable. "
+            "Stop the other LivePilot instance to enable them."
+            % (f" (PID {holder_info})" if holder_info else ""),
             file=sys.stderr,
         )
-        _kill_port_holder(9880)
-        await asyncio.sleep(0.3)
-        try:
-            transport, _ = await loop.create_datagram_endpoint(
-                lambda: receiver,
-                local_addr=('127.0.0.1', 9880),
-            )
-        except OSError:
-            print(
-                "LivePilot: WARNING — could not bind UDP 9880, "
-                "analyzer tools will be unavailable",
-                file=sys.stderr,
-            )
-            transport = None
+        transport = None
 
     try:
         yield {

package/mcp_server/tools/_perception_engine.py

@@ -77,6 +77,25 @@ def _normalize_to_lufs(
     return tmp_path
 
 
+# ---------------------------------------------------------------------------
+# True-peak helper
+# ---------------------------------------------------------------------------
+
+def _true_peak_dbtp(data: np.ndarray, sr: int) -> float:
+    """Estimate EBU R128 true peak via 4x oversampling.
+
+    Uses scipy's resample_poly for phase-accurate upsampling,
+    then measures the absolute peak of the oversampled signal.
+    Returns the result in dBTP (decibels relative to true peak).
+    """
+    from scipy.signal import resample_poly
+
+    # 4x oversample each channel independently
+    oversampled = resample_poly(data, up=4, down=1, axis=0)
+    peak_linear = float(np.max(np.abs(oversampled)))
+    return float(20.0 * np.log10(max(peak_linear, 1e-10)))
+
+
 # ---------------------------------------------------------------------------
 # compute_loudness
 # ---------------------------------------------------------------------------
@@ -89,8 +108,8 @@ def compute_loudness(file_path: str, detail: str = "summary") -> dict[str, Any]:
         detail: "summary" (default) or "full" (includes short_term_lufs array).
 
     Returns:
-        dict with integrated_lufs, sample_peak_dbfs, rms_dbfs, crest_factor_db,
-        lra_lu, meets_streaming, and optionally short_term_lufs.
+        dict with integrated_lufs, true_peak_dbtp, sample_peak_dbfs, rms_dbfs,
+        crest_factor_db, lra_lu, meets_streaming, and optionally short_term_lufs.
     """
     import pyloudnorm as pyln
 
@@ -110,12 +129,15 @@ def compute_loudness(file_path: str, detail: str = "summary") -> dict[str, Any]:
     peak_linear = float(np.max(np.abs(data)))
     sample_peak_dbfs = float(20.0 * np.log10(max(peak_linear, 1e-10)))
 
+    # True peak via 4x oversampling (EBU R128 compliant)
+    true_peak_dbtp = _true_peak_dbtp(data, sr)
+
     # RMS dBFS
     rms_linear = float(np.sqrt(np.mean(data ** 2)))
     rms_dbfs = float(20.0 * np.log10(max(rms_linear, 1e-10)))
 
     # Crest factor
-    crest_factor_db = sample_peak_dbfs - rms_dbfs
+    crest_factor_db = true_peak_dbtp - rms_dbfs
 
     # Short-term LUFS (3s window, 1s hop) — also used for LRA
     window_samples = int(sr * 3.0)
@@ -162,6 +184,7 @@ def compute_loudness(file_path: str, detail: str = "summary") -> dict[str, Any]:
 
     result: dict[str, Any] = {
         "integrated_lufs": round(integrated_lufs, 2),
+        "true_peak_dbtp": round(true_peak_dbtp, 2),
         "sample_peak_dbfs": round(sample_peak_dbfs, 2),
         "rms_dbfs": round(rms_dbfs, 2),
         "crest_factor_db": round(crest_factor_db, 2),

package/mcp_server/tools/_theory_engine.py

@@ -35,19 +35,20 @@ PHRYGIAN_PROFILE   = MAJOR_PROFILE[4:] + MAJOR_PROFILE[:4]
 LYDIAN_PROFILE     = MAJOR_PROFILE[5:] + MAJOR_PROFILE[:5]
 MIXOLYDIAN_PROFILE = MAJOR_PROFILE[7:] + MAJOR_PROFILE[:7]
 LOCRIAN_PROFILE    = MAJOR_PROFILE[11:] + MAJOR_PROFILE[:11]
+PHRYGIAN_DOMINANT_PROFILE = [6.35, 4.75, 1.75, 1.95, 4.9, 3.9, 1.8, 5.2, 3.6, 1.7, 3.4, 1.6]
 
 MODE_PROFILES = {
     'major': MAJOR_PROFILE, 'minor': MINOR_PROFILE,
     'dorian': DORIAN_PROFILE, 'phrygian': PHRYGIAN_PROFILE,
     'lydian': LYDIAN_PROFILE, 'mixolydian': MIXOLYDIAN_PROFILE,
-    'locrian': LOCRIAN_PROFILE,
+    'locrian': LOCRIAN_PROFILE, 'phrygian_dominant': PHRYGIAN_DOMINANT_PROFILE,
 }
 
 SCALES = {
     'major': [0, 2, 4, 5, 7, 9, 11], 'minor': [0, 2, 3, 5, 7, 8, 10],
     'dorian': [0, 2, 3, 5, 7, 9, 10], 'phrygian': [0, 1, 3, 5, 7, 8, 10],
     'lydian': [0, 2, 4, 6, 7, 9, 11], 'mixolydian': [0, 2, 4, 5, 7, 9, 10],
-    'locrian': [0, 1, 3, 5, 6, 8, 10],
+    'locrian': [0, 1, 3, 5, 6, 8, 10], 'phrygian_dominant': [0, 1, 4, 5, 7, 8, 10],
 }
 
 TRIAD_QUALITIES = {
@@ -58,6 +59,25 @@ TRIAD_QUALITIES = {
     'lydian':     ['major', 'major', 'minor', 'diminished', 'major', 'minor', 'minor'],
     'mixolydian': ['major', 'minor', 'diminished', 'major', 'minor', 'minor', 'major'],
     'locrian':    ['diminished', 'major', 'minor', 'minor', 'major', 'major', 'minor'],
+    'phrygian_dominant': ['major', 'major', 'diminished', 'minor', 'diminished', 'augmented', 'minor'],
+}
+
+MODE_ALIASES = {
+    'major': 'major',
+    'ionian': 'major',
+    'maj': 'major',
+    'minor': 'minor',
+    'aeolian': 'minor',
+    'min': 'minor',
+    'dorian': 'dorian',
+    'phrygian': 'phrygian',
+    'lydian': 'lydian',
+    'mixolydian': 'mixolydian',
+    'locrian': 'locrian',
+    'phrygian dominant': 'phrygian_dominant',
+    'phrygian_dominant': 'phrygian_dominant',
+    'phrygian-dominant': 'phrygian_dominant',
+    'hijaz': 'phrygian_dominant',
 }
 
 CHORD_PATTERNS = {
@@ -81,6 +101,15 @@ def pitch_name(midi: int) -> str:
     return NOTE_NAMES[midi % 12] + str(midi // 12 - 1)
 
 
+def _normalize_mode_name(mode: str) -> str:
+    """Normalize user-facing mode names into canonical scale ids."""
+    normalized = " ".join(mode.strip().lower().replace("_", " ").replace("-", " ").split())
+    canonical = MODE_ALIASES.get(normalized, normalized.replace(" ", "_"))
+    if canonical not in SCALES:
+        raise ValueError(f"Unknown mode: {mode}")
+    return canonical
+
+
 def parse_key(key_str: str) -> dict:
     """Parse key string -> {tonic: 0-11, tonic_name: str, mode: str}.
 
@@ -100,7 +129,8 @@ def parse_key(key_str: str) -> dict:
 
     parts = s.split()
     raw_tonic = parts[0]
-    mode = parts[1].lower() if len(parts) > 1 else 'major'
+    raw_mode = " ".join(parts[1:]) if len(parts) > 1 else 'major'
+    mode = _normalize_mode_name(raw_mode)
 
     # Normalize tonic: capitalize first letter
     tonic_name = raw_tonic[0].upper() + raw_tonic[1:]
@@ -117,17 +147,18 @@ def parse_key(key_str: str) -> dict:
 
 def get_scale_pitches(tonic: int, mode: str) -> list[int]:
     """Return pitch classes (0-11) for the scale."""
-    intervals = SCALES.get(mode, SCALES['major'])
+    intervals = SCALES[_normalize_mode_name(mode)]
     return [(tonic + iv) % 12 for iv in intervals]
 
 
 def build_chord(degree: int, tonic: int, mode: str) -> dict:
     """Build triad from scale degree (0-indexed)."""
+    mode = _normalize_mode_name(mode)
     scale = get_scale_pitches(tonic, mode)
     root = scale[degree % 7]
     third = scale[(degree + 2) % 7]
     fifth = scale[(degree + 4) % 7]
-    quality = TRIAD_QUALITIES.get(mode, TRIAD_QUALITIES['major'])[degree % 7]
+    quality = TRIAD_QUALITIES[mode][degree % 7]
     return {
         "root_pc": root,
         "pitch_classes": [root, third, fifth],

package/mcp_server/tools/analyzer.py

@@ -10,7 +10,7 @@ import os
 
 from fastmcp import Context
 
-from ..server import mcp
+from ..server import mcp, _identify_port_holder
 
 CAPTURE_DIR = os.path.expanduser("~/Documents/LivePilot/captures")
 
@@ -19,7 +19,10 @@ def _get_spectral(ctx: Context):
     """Get SpectralCache from lifespan context."""
     cache = ctx.lifespan_context.get("spectral")
     if not cache:
-        raise RuntimeError("Spectral cache not initialized")
+        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
 
 
@@ -27,13 +30,46 @@ def _get_m4l(ctx: Context):
     """Get M4LBridge from lifespan context."""
     bridge = ctx.lifespan_context.get("m4l")
     if not bridge:
-        raise RuntimeError("M4L bridge not initialized")
+        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:
+            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 "
@@ -140,7 +176,7 @@ async def get_hidden_parameters(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_hidden_params", track_index, device_index)
+    return await bridge.send_command("get_hidden_params", track_index, device_index, timeout=15.0)
 
 
 @mcp.tool()
@@ -161,7 +197,7 @@ async def get_automation_state(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_auto_state", track_index, device_index)
+    return await bridge.send_command("get_auto_state", track_index, device_index, timeout=10.0)
 
 
 @mcp.tool()
@@ -267,25 +303,34 @@ async def load_sample_to_simpler(
 
     # Step 1: Load a sample from the browser to create Simpler with content
     ableton = ctx.lifespan_context["ableton"]
-    search = ableton.send_command("search_browser", {
-        "path": "samples",
-        "name_filter": "kick",
-        "loadable_only": True,
-        "max_results": 1,
-    })
+    try:
+        search = ableton.send_command("search_browser", {
+            "path": "samples",
+            "name_filter": "kick",
+            "loadable_only": True,
+            "max_results": 1,
+        })
+    except Exception as exc:
+        return {"error": f"Browser search failed: {exc}"}
     results = search.get("results", [])
     if not results:
         return {"error": "No samples found in browser to bootstrap Simpler"}
 
     # Load the dummy sample — Ableton auto-creates Simpler
     uri = results[0]["uri"]
-    ableton.send_command("load_browser_item", {
-        "track_index": track_index,
-        "uri": uri,
-    })
+    try:
+        ableton.send_command("load_browser_item", {
+            "track_index": track_index,
+            "uri": uri,
+        })
+    except Exception as exc:
+        return {"error": f"Failed to load bootstrap sample: {exc}"}
 
     # Step 2: Find the newly created device (it's at the end of the chain)
-    track_info = ableton.send_command("get_track_info", {"track_index": track_index})
+    try:
+        track_info = ableton.send_command("get_track_info", {"track_index": track_index})
+    except Exception as exc:
+        return {"error": f"Failed to read track after loading sample: {exc}"}
     actual_device_index = len(track_info.get("devices", [])) - 1
     if actual_device_index < 0:
         actual_device_index = 0
@@ -515,7 +560,7 @@ async def get_display_values(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_display_values", track_index, device_index)
+    return await bridge.send_command("get_display_values", track_index, device_index, timeout=15.0)
 
 
 # ── Phase 3: Audio Capture ─────────────────────────────────────────────

package/mcp_server/tools/automation.py

@@ -22,7 +22,10 @@ def _get_ableton(ctx: Context):
 def _ensure_list(v: Any) -> list:
     if isinstance(v, str):
         import json
-        return json.loads(v)
+        try:
+            return json.loads(v)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     if isinstance(v, list):
         return v
     return [v]