livepilot 1.7.6 → 1.8.0

package/mcp_server/tools/perception.py

@@ -0,0 +1,214 @@
+"""Offline audio perception tools for LivePilot v1.8.
+
+4 MCP tools wrapping the pure-function engine in _perception_engine.py.
+These tools do NOT require an Ableton connection — they work on any local
+audio file.
+
+Tools:
+  analyze_loudness         — integrated LUFS, true peak, LRA, streaming compliance
+  analyze_spectrum_offline — spectral centroid, rolloff, flatness, 5-band balance
+  compare_to_reference     — loudness + spectral delta between mix and reference
+  read_audio_metadata      — format, sample rate, tags, artwork flag
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from ..server import mcp
+from ._perception_engine import (
+    compute_loudness,
+    compute_spectral,
+    compare_to_reference as _compare,
+    read_audio_metadata as _read_metadata,
+)
+
+
+# ---------------------------------------------------------------------------
+# Supported formats
+# ---------------------------------------------------------------------------
+
+_LOSSLESS_EXTS = {".wav", ".flac", ".ogg", ".aiff", ".aif"}
+_LOSSY_EXTS = {".mp3", ".m4a"}
+_MAX_FILE_SIZE = 500 * 1024 * 1024  # 500 MB
+
+
+def _validate_audio(file_path: str, allow_mp3: bool = False) -> Optional[dict]:
+    """Validate that a file exists, has a supported extension, and is < 500 MB.
+
+    Returns None if valid, or an error dict if invalid.
+    """
+    if not os.path.exists(file_path):
+        return {"error": f"File not found: {file_path}", "code": "INVALID_PARAM"}
+
+    ext = os.path.splitext(file_path)[1].lower()
+    allowed = _LOSSLESS_EXTS | (_LOSSY_EXTS if allow_mp3 else set())
+    if ext not in allowed:
+        return {
+            "error": (
+                f"Unsupported format '{ext}'. "
+                f"Supported: {sorted(allowed)}"
+            ),
+            "code": "INVALID_PARAM",
+        }
+
+    size = os.path.getsize(file_path)
+    if size > _MAX_FILE_SIZE:
+        mb = size / (1024 * 1024)
+        return {
+            "error": f"File too large ({mb:.1f} MB). Maximum is 500 MB.",
+            "code": "INVALID_PARAM",
+        }
+
+    return None  # valid
+
+
+# ---------------------------------------------------------------------------
+# MCP Tools
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def analyze_loudness(
+    file_path: str,
+    detail: str = "summary",
+) -> dict[str, Any]:
+    """Analyze the integrated loudness of an audio file (offline — no Ableton needed).
+
+    Computes integrated LUFS (EBU R128), true peak, RMS, crest factor,
+    loudness range (LRA), and streaming platform compliance.
+
+    Args:
+        file_path: Absolute path to the audio file (.wav, .flac, .ogg, .aiff).
+        detail: "summary" (default) or "full" — "full" includes the short_term_lufs
+                array (up to 100 points, mean-pooled).
+
+    Returns:
+        On success: dict with integrated_lufs, true_peak_dbtp, rms_dbfs,
+        crest_factor_db, lra_lu, meets_streaming {spotify, apple, youtube, tidal},
+        and optionally short_term_lufs.
+        On error: {"error": ..., "code": ...}
+    """
+    err = _validate_audio(file_path, allow_mp3=False)
+    if err:
+        return err
+
+    if detail not in ("summary", "full"):
+        return {"error": "detail must be 'summary' or 'full'", "code": "INVALID_PARAM"}
+
+    try:
+        return compute_loudness(file_path, detail=detail)
+    except FileNotFoundError as exc:
+        return {"error": str(exc), "code": "INVALID_PARAM"}
+    except Exception as exc:
+        return {"error": f"Loudness analysis failed: {exc}", "code": "INTERNAL"}
+
+
+@mcp.tool()
+def analyze_spectrum_offline(
+    file_path: str,
+    n_fft: int = 2048,
+    hop_length: int = 512,
+) -> dict[str, Any]:
+    """Analyze the frequency spectrum of an audio file (offline — no Ableton needed).
+
+    Uses scipy STFT to compute spectral centroid, rolloff, flatness, bandwidth,
+    and 5-band energy balance (sub_60hz, low_250hz, mid_2khz, high_8khz, air_16khz).
+
+    Args:
+        file_path: Absolute path to the audio file (.wav, .flac, .ogg, .aiff).
+        n_fft: FFT window size (default 2048).
+        hop_length: Hop size in samples (default 512).
+
+    Returns:
+        On success: dict with centroid_hz, rolloff_hz, spectral_flatness,
+        bandwidth_hz, band_balance.
+        On error: {"error": ..., "code": ...}
+    """
+    err = _validate_audio(file_path, allow_mp3=False)
+    if err:
+        return err
+
+    if n_fft < 64 or n_fft > 65536:
+        return {"error": "n_fft must be between 64 and 65536", "code": "INVALID_PARAM"}
+    if hop_length < 1 or hop_length > n_fft:
+        return {"error": "hop_length must be between 1 and n_fft", "code": "INVALID_PARAM"}
+
+    try:
+        return compute_spectral(file_path, n_fft=n_fft, hop_length=hop_length)
+    except FileNotFoundError as exc:
+        return {"error": str(exc), "code": "INVALID_PARAM"}
+    except Exception as exc:
+        return {"error": f"Spectral analysis failed: {exc}", "code": "INTERNAL"}
+
+
+@mcp.tool()
+def compare_to_reference(
+    mix_path: str,
+    reference_path: str,
+    normalize: bool = True,
+) -> dict[str, Any]:
+    """Compare a mix to a reference track (offline — no Ableton needed).
+
+    Computes loudness delta (LUFS), spectral centroid delta, stereo width
+    comparison, per-band energy deltas, and actionable mixing suggestions.
+
+    When normalize=True (default), both files are LUFS-normalized to -14 LUFS
+    before spectral comparison so frequency differences aren't skewed by volume.
+
+    Args:
+        mix_path: Absolute path to the mix file (.wav, .flac, .ogg, .aiff).
+        reference_path: Absolute path to the reference file.
+        normalize: LUFS-normalize before spectral comparison (default True).
+
+    Returns:
+        On success: dict with loudness_delta_lufs, mix_lufs, reference_lufs,
+        centroid_delta_hz, stereo_width_mix, stereo_width_ref, band_deltas,
+        suggestions.
+        On error: {"error": ..., "code": ...}
+    """
+    err = _validate_audio(mix_path, allow_mp3=False)
+    if err:
+        return {"error": f"mix_path: {err['error']}", "code": err["code"]}
+
+    err = _validate_audio(reference_path, allow_mp3=False)
+    if err:
+        return {"error": f"reference_path: {err['error']}", "code": err["code"]}
+
+    try:
+        return _compare(mix_path, reference_path, normalize=normalize)
+    except FileNotFoundError as exc:
+        return {"error": str(exc), "code": "INVALID_PARAM"}
+    except Exception as exc:
+        return {"error": f"Reference comparison failed: {exc}", "code": "INTERNAL"}
+
+
+@mcp.tool()
+def read_audio_metadata(
+    file_path: str,
+) -> dict[str, Any]:
+    """Read metadata from an audio file (offline — no Ableton needed).
+
+    Uses mutagen for tag reading (title, artist, album, BPM, etc.) and
+    soundfile for format information. Falls back gracefully if mutagen
+    cannot parse the file.
+
+    Args:
+        file_path: Absolute path to the audio file (.wav, .flac, .ogg, .aiff,
+                   .mp3, .m4a).
+
+    Returns:
+        On success: dict with format, duration, sample_rate, channels,
+        bitrate, tags, has_artwork, file_size.
+        On error: {"error": ..., "code": ...}
+    """
+    err = _validate_audio(file_path, allow_mp3=True)
+    if err:
+        return err
+
+    try:
+        return _read_metadata(file_path)
+    except FileNotFoundError as exc:
+        return {"error": str(exc), "code": "INVALID_PARAM"}
+    except Exception as exc:
+        return {"error": f"Metadata read failed: {exc}", "code": "INTERNAL"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.7.6",
+  "version": "1.8.0",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 155 tools, 16 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "description": "Agentic production system for Ableton Live 12 — 168 tools, 17 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": "Pilot Studio",
   "license": "MIT",
   "type": "commonjs",

package/plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "livepilot",
-  "version": "1.7.6",
-  "description": "Agentic production system for Ableton Live 12 — 155 tools, 16 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "version": "1.8.0",
+  "description": "Agentic production system for Ableton Live 12 — 168 tools, 17 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "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 LivePilot — agentic production system for Ableton Live 12. 155 tools across 16 domains. Device atlas (280+ devices), M4L analyzer (spectrum/RMS/key detection), technique memory, automation intelligence (16 curve types, 15 recipes), music theory (Krumhansl-Schmuckler, species counterpoint), generative algorithms (Euclidean rhythm, tintinnabuli, phase shift), neo-Riemannian harmony (PRL transforms, Tonnetz), MIDI file I/O. Use whenever working with Ableton Live through MCP tools.
+description: Core discipline for LivePilot — agentic production system for Ableton Live 12. 168 tools across 17 domains. Device atlas (280+ devices), M4L analyzer (spectrum/RMS/key detection), technique memory, automation intelligence (16 curve types, 15 recipes), music theory (Krumhansl-Schmuckler, species counterpoint), generative algorithms (Euclidean rhythm, tintinnabuli, phase shift), neo-Riemannian harmony (PRL transforms, Tonnetz), MIDI file I/O. Use whenever working with Ableton Live through MCP tools.
 ---
 
 # LivePilot Core — Ableton Live 12
 
-Agentic production system for Ableton Live 12. 155 tools across 16 domains, three layers:
+Agentic production system for Ableton Live 12. 168 tools across 17 domains, three layers:
 
 - **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 155 deterministic tools across 16 domains: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, and MIDI I/O.
+These layers sit on top of 168 deterministic tools across 17 domains: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, MIDI I/O, and perception.
 
 ## Golden Rules
 
@@ -32,7 +32,7 @@ These layers sit on top of 155 deterministic tools across 16 domains: transport,
 Not all tools respond instantly. Know the tiers and act accordingly.
 
 ### Instant (<1s) — Use freely, no warning needed
-All 155 core tools (transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, automation, theory, generative, harmony, midi_io) plus Layer A perception tools (spectral shape, timbral profile, mel spectrum, chroma, onsets, harmonic/percussive, novelty, momentary loudness). These are the reflex tools — call them anytime without hesitation.
+All 168 core tools (transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, automation, theory, generative, harmony, midi_io, perception) plus Layer A perception tools (spectral shape, timbral profile, mel spectrum, chroma, onsets, harmonic/percussive, novelty, momentary loudness). These are the reflex tools — call them anytime without hesitation.
 
 ### Fast (1-5s) — Use freely, barely noticeable
 `analyze_loudness` · `analyze_dynamic_range` · `compare_loudness`
@@ -117,7 +117,7 @@ Never skip levels. The user's question determines the entry point, but always st
 - MIDI track with no instrument loaded
 - Notes programmed but clip not fired
 
-## Tool Domains (155 total)
+## Tool Domains (168 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`
@@ -366,7 +366,7 @@ Deep production knowledge lives in `references/`. Consult these when making crea
 
 | File | What's inside | When to consult |
 |------|--------------|-----------------|
-| `references/overview.md` | All 155 tools mapped with params, units, ranges | Quick lookup for any tool |
+| `references/overview.md` | All 168 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 |

package/plugin/skills/livepilot-core/references/overview.md

@@ -1,6 +1,6 @@
-# LivePilot v1.7.6 — Architecture & Tool Reference
+# LivePilot v1.8.0 — Architecture & Tool Reference
 
-Agentic production system for Ableton Live 12. 155 tools across 16 domains. Device atlas (280+ devices), spectral perception (M4L analyzer), technique memory, automation intelligence (16 curve types, 15 recipes), music theory (Krumhansl-Schmuckler, species counterpoint), generative algorithms (Euclidean rhythm, tintinnabuli, phase shift, additive process), neo-Riemannian harmony (PRL transforms, Tonnetz), MIDI file I/O.
+Agentic production system for Ableton Live 12. 168 tools across 17 domains. Device atlas (280+ devices), spectral perception (M4L analyzer), technique memory, automation intelligence (16 curve types, 15 recipes), music theory (Krumhansl-Schmuckler, species counterpoint), generative algorithms (Euclidean rhythm, tintinnabuli, phase shift, additive process), neo-Riemannian harmony (PRL transforms, Tonnetz), MIDI file I/O.
 
 ## Architecture
 
@@ -32,7 +32,7 @@ A flat tool list lets the AI press buttons. LivePilot's three layers give it con
 
 This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spectrum to confirm the mud is actually reduced."
 
-## The 155 Tools — What Each One Does
+## The 168 Tools — What Each One Does
 
 ### Transport (12) — Playback, tempo, global state, diagnostics
 

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.7.6"
+__version__ = "1.8.0"
 
 from _Framework.ControlSurface import ControlSurface
 from .server import LivePilotServer
@@ -34,7 +34,7 @@ class LivePilot(ControlSurface):
         ControlSurface.__init__(self, c_instance)
         self._server = LivePilotServer(self)
         self._server.start()
-        self.log_message("LivePilot v1.7.6 initialized")
+        self.log_message("LivePilot v1.8.0 initialized")
         self.show_message("LivePilot: Listening on port 9878")
 
     def disconnect(self):

package/requirements.txt

@@ -1,5 +1,11 @@
 # LivePilot MCP Server dependencies
+numpy>=1.24.0
 fastmcp>=3.0.0,<4.0.0
 midiutil>=1.2.1
 pretty_midi>=0.2.10
 opycleid>=0.5.1
+# v1.8 Perception Layer (offline analysis)
+pyloudnorm>=0.1.0
+soundfile>=0.12.0
+scipy>=1.11.0
+mutagen>=1.47.0