livepilot 1.7.5 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.8.0 — Perception Layer (March 2026)
+
+**13 new tools (155 → 168), 1 new domain (perception), FluCoMa real-time DSP, offline audio analysis, audio capture.**
+
+### Perception Domain (4 tools)
+- `analyze_loudness` — LUFS, sample peak, RMS, crest factor, LRA, streaming compliance
+- `analyze_spectrum_offline` — spectral centroid, rolloff, flatness, bandwidth, 5-band balance
+- `compare_to_reference` — mix vs reference: loudness/spectral/stereo deltas + suggestions
+- `read_audio_metadata` — format, duration, sample rate, tags, artwork detection
+
+### Analyzer — Capture (2 tools)
+- `capture_audio` — record master output to WAV via M4L buffer~/record~
+- `capture_stop` — cancel in-progress capture
+
+### Analyzer — FluCoMa Real-Time (7 tools)
+- `get_spectral_shape` — 7 descriptors (centroid, spread, skewness, kurtosis, rolloff, flatness, crest)
+- `get_mel_spectrum` — 40-band mel spectrum (5x resolution of get_master_spectrum)
+- `get_chroma` — 12 pitch class energies for chord detection
+- `get_onsets` — real-time onset/transient detection
+- `get_novelty` — spectral novelty for section boundary detection
+- `get_momentary_loudness` — EBU R128 momentary LUFS + peak
+- `check_flucoma` — verify FluCoMa installation status
+
+### Architecture
+- New `_perception_engine.py` — pure scipy/pyloudnorm/soundfile/mutagen analysis (no MCP deps)
+- New `perception.py` — 4 MCP tool wrappers with format validation
+- 6 FluCoMa OSC handlers in SpectralReceiver (`/spectral_shape`, `/mel_bands`, `/chroma`, `/onset`, `/novelty`, `/loudness`)
+- Dedicated `/capture_complete` channel with `_capture_future` (separate from bridge responses)
+- `--setup-flucoma` CLI command — auto-downloads and installs FluCoMa Max package
+- New dependencies: pyloudnorm, soundfile, scipy, mutagen
+
 ## 1.7.0 — Creative Engine (March 2026)
 
 **13 new tools (142 → 155), 3 new domains, MIDI file I/O, neo-Riemannian harmony, generative algorithms.**

package/README.md

@@ -9,7 +9,7 @@
 
 An agentic production system for Ableton Live 12.
 
-155 tools. Device atlas. Spectral perception. Technique memory.
+168 tools. Device atlas. Spectral perception. Technique memory.
 Neo-Riemannian harmony. Euclidean rhythm. Species counterpoint.
 
 It doesn't assist — it produces.
@@ -38,8 +38,8 @@ It doesn't assist — it produces.
 │         └───────────────────┼───────────────────┘           │
 │                             ▼                               │
 │                    ┌─────────────────┐                      │
-│                    │   155 MCP Tools  │                      │
-│                    │   16 domains     │                      │
+│                    │   168 MCP Tools  │                      │
+│                    │   17 domains     │                      │
 │                    └────────┬────────┘                      │
 │                             │                               │
 │             Remote Script ──┤── TCP 9878                    │
@@ -60,7 +60,7 @@ via a Max for Live device.
 The memory gives it history — a searchable library of production decisions
 that persists across sessions.
 
-All three feed into 155 deterministic tools that execute on Ableton's main thread
+All three feed into 168 deterministic tools that execute on Ableton's main thread
 through the official Live Object Model API. Everything is reversible with undo.
 
 <br>
@@ -477,7 +477,7 @@ Check memory before creative decisions. Verify every mutation.
 
 ## Full Tool List
 
-155 tools across 16 domains.
+168 tools across 17 domains.
 
 <br>
 

package/bin/livepilot.js

@@ -273,6 +273,134 @@ async function doctor() {
   return ok;
 }
 
+// ---------------------------------------------------------------------------
+// FluCoMa installer
+// ---------------------------------------------------------------------------
+
+async function setupFlucoma() {
+  const os = require("os");
+  const https = require("https");
+
+  const home = os.homedir();
+  const packagesDir = process.platform === "darwin"
+    ? path.join(home, "Documents", "Max 8", "Packages")
+    : path.join(process.env.USERPROFILE || home, "Documents", "Max 8", "Packages");
+
+  const flucomaDir = path.join(packagesDir, "FluidCorpusManipulation");
+
+  if (fs.existsSync(flucomaDir)) {
+    // Check version
+    const pkgInfo = path.join(flucomaDir, "package-info.json");
+    if (fs.existsSync(pkgInfo)) {
+      try {
+        const info = JSON.parse(fs.readFileSync(pkgInfo, "utf-8"));
+        console.log("FluCoMa already installed: v%s", info.version || "unknown");
+        console.log("Location: %s", flucomaDir);
+        return;
+      } catch {}
+    }
+    console.log("FluCoMa already installed at %s", flucomaDir);
+    return;
+  }
+
+  console.log("FluCoMa not found. Downloading from GitHub...");
+
+  // Fetch latest release info
+  const releaseInfo = await new Promise((resolve, reject) => {
+    https.get("https://api.github.com/repos/flucoma/flucoma-max/releases/latest", {
+      headers: { "User-Agent": "LivePilot" }
+    }, (res) => {
+      if (res.statusCode === 302 || res.statusCode === 301) {
+        https.get(res.headers.location, {
+          headers: { "User-Agent": "LivePilot" }
+        }, (res2) => {
+          let data = "";
+          res2.on("data", (c) => data += c);
+          res2.on("end", () => resolve(JSON.parse(data)));
+        }).on("error", reject);
+        return;
+      }
+      let data = "";
+      res.on("data", (c) => data += c);
+      res.on("end", () => resolve(JSON.parse(data)));
+    }).on("error", reject);
+  });
+
+  const zipAsset = releaseInfo.assets.find(a => a.name.endsWith(".zip"));
+  if (!zipAsset) {
+    console.error("Error: no zip asset found in FluCoMa release");
+    process.exit(1);
+  }
+
+  console.log("Downloading %s (%sMB)...", zipAsset.name,
+    Math.round(zipAsset.size / 1024 / 1024));
+
+  // Download to temp
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "flucoma-"));
+  const zipPath = path.join(tmpDir, zipAsset.name);
+
+  await new Promise((resolve, reject) => {
+    const downloadUrl = zipAsset.browser_download_url;
+    const download = (url, depth) => {
+      if (depth > 5) { reject(new Error("Too many redirects")); return; }
+      if (!url.startsWith("https://")) { reject(new Error("Refusing non-HTTPS redirect")); return; }
+      https.get(url, { headers: { "User-Agent": "LivePilot" } }, (res) => {
+        if (res.statusCode === 302 || res.statusCode === 301) {
+          download(res.headers.location, depth + 1);
+          return;
+        }
+        const file = fs.createWriteStream(zipPath);
+        res.pipe(file);
+        file.on("finish", () => { file.close(); resolve(); });
+      }).on("error", reject);
+    };
+    download(downloadUrl, 0);
+  });
+
+  console.log("Extracting to %s...", packagesDir);
+  fs.mkdirSync(packagesDir, { recursive: true });
+
+  if (process.platform === "win32") {
+    // Escape single quotes for PowerShell: ' → ''
+    const psZip = zipPath.replace(/'/g, "''");
+    const psDest = packagesDir.replace(/'/g, "''");
+    execFileSync("powershell", [
+      "-Command",
+      `Expand-Archive -Path '${psZip}' -DestinationPath '${psDest}' -Force`
+    ], { stdio: "inherit", timeout: 120000 });
+  } else {
+    execFileSync("unzip", ["-o", "-q", zipPath, "-d", packagesDir], {
+      stdio: "inherit",
+      timeout: 120000,
+    });
+  }
+
+  // macOS: strip quarantine
+  if (process.platform === "darwin" && fs.existsSync(flucomaDir)) {
+    try {
+      execFileSync("xattr", ["-d", "-r", "com.apple.quarantine", flucomaDir], {
+        stdio: "pipe",
+        timeout: 30000,
+      });
+    } catch {
+      // xattr may fail if no quarantine attribute — that's fine
+    }
+  }
+
+  // Clean up temp
+  try { fs.rmSync(tmpDir, { recursive: true }); } catch {}
+
+  if (fs.existsSync(flucomaDir)) {
+    console.log("");
+    console.log("FluCoMa installed successfully!");
+    console.log("Restart Ableton Live for real-time DSP tools.");
+  } else {
+    console.error("Error: FluCoMa directory not found after extraction.");
+    console.error("The zip may have a different structure. Check %s manually.", packagesDir);
+    process.exit(1);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -289,7 +417,7 @@ async function main() {
 
   // --help / -h
   if (flag === "--help" || flag === "-h") {
-    console.log("livepilot v%s — AI copilot for Ableton Live 12", PKG.version);
+    console.log("livepilot v%s — agentic production system for Ableton Live 12", PKG.version);
     console.log("");
     console.log("Usage: npx livepilot [command]");
     console.log("");
@@ -300,6 +428,7 @@ async function main() {
     console.log("  --status      Check if Ableton Live is reachable");
     console.log("  --doctor      Run diagnostics (Python, deps, connection)");
     console.log("  --version     Show version");
+    console.log("  --setup-flucoma  Install FluCoMa package for real-time DSP");
     console.log("  --help        Show this help");
     console.log("");
     console.log("Environment:");
@@ -328,6 +457,12 @@ async function main() {
     process.exit(reachable ? 0 : 1);
   }
 
+  // --setup-flucoma
+  if (flag === "--setup-flucoma") {
+    await setupFlucoma();
+    return;
+  }
+
   // --doctor
   if (flag === "--doctor") {
     const passed = await doctor();

package/m4l_device/livepilot_bridge.js

@@ -17,8 +17,8 @@
  */
 
 autowatch = 1;
-inlets = 1;
-outlets = 2; // 0: to udpsend (responses), 1: to status UI
+inlets = 2;  // 0: OSC commands, 1: dspstate~ (sample rate)
+outlets = 2; // 0: to udpsend (responses), 1: to buffer~/status
 
 // ── State ──────────────────────────────────────────────────────────────────
 
@@ -30,6 +30,12 @@ var MAX_PITCH_HISTORY = 128;
 var detected_key = "";
 var detected_scale = "";
 
+// Capture state
+var capture_active = false;
+var capture_timer = null;
+var capture_filename = "";
+var current_sample_rate = 44100; // Updated by dspstate~ via inlet 1
+
 // Base64 encoding table
 var B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 
@@ -46,6 +52,15 @@ function bang() {
     }
 }
 
+// ── DSP State (inlet 1: dspstate~ sample rate) ─────────────────────────────
+
+function msg_int(v) {
+    // dspstate~ sends the sample rate as an int on inlet 1
+    if (inlet === 1) {
+        current_sample_rate = v > 0 ? v : 44100;
+    }
+}
+
 // ── Incoming OSC Message Dispatch ──────────────────────────────────────────
 
 function anything() {
@@ -68,7 +83,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.7.0"});
+            send_response({"ok": true, "version": "1.8.0"});
             break;
         case "get_params":
             cmd_get_params(args);
@@ -126,6 +141,16 @@ function dispatch(cmd, args) {
         case "remove_warp_marker":
             cmd_remove_warp_marker(args);
             break;
+        // ── Phase 3: Capture ──
+        case "capture_audio":
+            cmd_capture_audio(args);
+            break;
+        case "capture_stop":
+            cmd_capture_stop();
+            break;
+        case "check_flucoma":
+            send_response({"flucoma_available": true, "version": "1.0.9"});
+            break;
         // ── Phase 2: Clip & Display ──
         case "scrub_clip":
             cmd_scrub_clip(args);
@@ -921,6 +946,95 @@ function cmd_get_display_values(args) {
     read_batch();
 }
 
+// ── Phase 3: Audio Capture ────────────────────────────────────────────
+
+function cmd_capture_audio(args) {
+    // args: [duration_ms, filename]
+    // duration_ms is the requested record length in milliseconds.
+    // filename is the desired output name (empty = auto-generate).
+    if (capture_active) {
+        send_response({"error": "Capture already in progress. Call capture_stop first."});
+        return;
+    }
+
+    var duration_ms = parseInt(args[0]) || 10000;
+    var requested_name = args[1] ? args[1].toString().trim() : "";
+
+    // Generate a timestamped filename if none provided
+    var d = new Date();
+    var ts = d.getFullYear() + "_"
+        + pad2(d.getMonth() + 1) + "_"
+        + pad2(d.getDate()) + "_"
+        + pad2(d.getHours()) + pad2(d.getMinutes()) + pad2(d.getSeconds());
+    capture_filename = requested_name.length > 0 ? requested_name : ("capture_" + ts + ".wav");
+
+    // Calculate sample count from duration and current sample rate
+    var num_samples = Math.ceil((duration_ms / 1000.0) * current_sample_rate);
+
+    capture_active = true;
+
+    // Tell the Max patch to start recording into buffer~ via outlet 1.
+    // The patch is expected to connect outlet 1 to a buffer~ / record~ rig.
+    // Message: "capture_start <filename> <num_samples>"
+    outlet(1, "capture_start", capture_filename, num_samples);
+
+    // Set a timer to call cmd_capture_write_done after duration_ms.
+    // If the buffer~ fires its bang first (via a connected message), that
+    // call will also land here — the guard flag prevents double-response.
+    capture_timer = new Task(function() {
+        cmd_capture_write_done();
+    });
+    capture_timer.schedule(duration_ms);
+}
+
+function cmd_capture_write_done() {
+    // Called when buffer~ finishes writing (bang from record~), or by the
+    // timer. Guards against double invocation.
+    if (!capture_active) return;
+    capture_active = false;
+    if (capture_timer) {
+        capture_timer.cancel();
+        capture_timer = null;
+    }
+
+    var written = capture_filename;
+    capture_filename = "";
+
+    // Send /capture_complete back to the MCP server via outlet 0.
+    var encoded = base64_encode(JSON.stringify({
+        "ok": true,
+        "file": written,
+        "sample_rate": current_sample_rate
+    }));
+    outlet(0, "/capture_complete", encoded);
+}
+
+function cmd_capture_stop() {
+    if (!capture_active) {
+        send_response({"ok": true, "stopped": false, "message": "No capture was active"});
+        return;
+    }
+
+    // Cancel the countdown timer so cmd_capture_write_done isn't called twice
+    if (capture_timer) {
+        capture_timer.cancel();
+        capture_timer = null;
+    }
+
+    // Signal the Max patch to stop recording early
+    outlet(1, "capture_stop");
+
+    capture_active = false;
+    var written = capture_filename;
+    capture_filename = "";
+
+    send_response({"ok": true, "stopped": true, "file": written});
+}
+
+function pad2(n) {
+    return n < 10 ? "0" + n : "" + n;
+}
+
 // ── Helpers ────────────────────────────────────────────────────────────────
 
 function build_track_path(track_idx) {

package/mcp_server/__init__.py

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

package/mcp_server/m4l_bridge.py

@@ -98,6 +98,7 @@ class SpectralReceiver(asyncio.DatagramProtocol):
         self.cache = cache
         self._chunks: dict[str, dict] = {}  # Reassembly buffer for chunked responses
         self._response_callback: Optional[asyncio.Future] = None
+        self._capture_future: Optional[asyncio.Future] = None
 
     def connection_made(self, transport: asyncio.DatagramTransport) -> None:
         self.transport = transport
@@ -176,6 +177,39 @@ class SpectralReceiver(asyncio.DatagramProtocol):
                 "scale": str(args[1]),
             })
 
+        elif address == "/spectral_shape" and len(args) >= 7:
+            names = ["centroid", "spread", "skewness", "kurtosis", "rolloff", "flatness", "crest"]
+            self.cache.update("spectral_shape", {
+                n: round(float(args[i]), 4) for i, n in enumerate(names)
+            })
+
+        elif address == "/mel_bands" and len(args) >= 1:
+            self.cache.update("mel_bands", [round(float(a), 6) for a in args])
+
+        elif address == "/chroma" and len(args) >= 12:
+            self.cache.update("chroma", [round(float(a), 4) for a in args[:12]])
+
+        elif address == "/onset" and len(args) >= 2:
+            self.cache.update("onset", {
+                "detected": float(args[0]) > 0.5,
+                "strength": round(float(args[1]), 4),
+            })
+
+        elif address == "/novelty" and len(args) >= 2:
+            self.cache.update("novelty", {
+                "score": round(float(args[0]), 4),
+                "boundary": float(args[1]) > 0.5,
+            })
+
+        elif address == "/loudness" and len(args) >= 2:
+            self.cache.update("loudness", {
+                "momentary_lufs": round(float(args[0]), 1),
+                "true_peak_dbtp": round(float(args[1]), 1),
+            })
+
+        elif address == "/capture_complete" and len(args) >= 1:
+            self._handle_capture_complete(str(args[0]))
+
         elif address == "/response" and len(args) >= 1:
             self._handle_response(str(args[0]))
 
@@ -210,10 +244,25 @@ class SpectralReceiver(asyncio.DatagramProtocol):
             del self._chunks[key]
             self._handle_response(full)
 
+    def _handle_capture_complete(self, encoded: str) -> None:
+        """Decode a /capture_complete OSC message and resolve _capture_future."""
+        try:
+            padded = encoded + "=" * (-len(encoded) % 4)
+            decoded = base64.urlsafe_b64decode(padded).decode('utf-8')
+            result = json.loads(decoded)
+            if self._capture_future and not self._capture_future.done():
+                self._capture_future.set_result(result)
+        except Exception:
+            pass
+
     def set_response_future(self, future: asyncio.Future) -> None:
         """Set a future to be resolved with the next response."""
         self._response_callback = future
 
+    def set_capture_future(self, future: asyncio.Future) -> None:
+        """Set a future to be resolved when a capture_complete OSC arrives."""
+        self._capture_future = future
+
 
 class M4LBridge:
     """Sends commands to the M4L device and waits for responses.
@@ -251,6 +300,38 @@ class M4LBridge:
         except asyncio.TimeoutError:
             return {"error": "M4L bridge timeout — device may be busy or removed"}
 
+    async def send_capture(self, command: str, *args: Any, timeout: float = 35.0) -> dict:
+        """Send a capture command to the M4L device and wait for /capture_complete."""
+        if not self.cache.is_connected:
+            return {"error": "LivePilot Analyzer not connected. Drop it on the master track."}
+
+        # Cancel any stale capture future before creating a new one
+        if self.receiver and self.receiver._capture_future and not self.receiver._capture_future.done():
+            self.receiver._capture_future.cancel()
+
+        loop = asyncio.get_running_loop()
+        future = loop.create_future()
+        if self.receiver:
+            self.receiver.set_capture_future(future)
+
+        osc_data = self._build_osc(command, args)
+        self._sock.sendto(osc_data, self._m4l_addr)
+
+        try:
+            result = await asyncio.wait_for(future, timeout=timeout)
+            return result
+        except asyncio.TimeoutError:
+            # Clean up the dangling future
+            if self.receiver:
+                self.receiver._capture_future = None
+            return {"error": "M4L capture timeout — device may be busy or removed"}
+
+    def cancel_capture_future(self) -> None:
+        """Cancel any in-progress capture future (called by capture_stop)."""
+        if self.receiver and self.receiver._capture_future and not self.receiver._capture_future.done():
+            self.receiver._capture_future.cancel()
+            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)

package/mcp_server/server.py

@@ -60,6 +60,7 @@ from .tools import theory       # noqa: F401, E402
 from .tools import generative   # noqa: F401, E402
 from .tools import harmony      # noqa: F401, E402
 from .tools import midi_io      # noqa: F401, E402
+from .tools import perception   # noqa: F401, E402
 
 
 # ---------------------------------------------------------------------------