livepilot 1.14.1 → 1.16.0

package/mcp_server/tools/analyzer.py

@@ -11,6 +11,7 @@ important for BUG-C1's refactor.
 
 from __future__ import annotations
 
+import asyncio
 import logging
 import os
 from typing import Optional
@@ -64,6 +65,112 @@ def _enrich_slice_response(response: Optional[dict]) -> Optional[dict]:
     return enriched
 
 
+def _live_caps(ctx, *, force_refresh: bool = False):
+    """Read (or lazily compute + cache) LiveVersionCapabilities on the context.
+
+    On first successful probe, caches the result in
+    ``ctx.lifespan_context["_live_caps"]``. Subsequent calls short-circuit
+    to the cache unless ``force_refresh=True``.
+
+    If Ableton is unreachable OR returns no ``live_version`` field,
+    returns a conservative (12, 0, 0) fallback BUT does NOT cache it.
+    Caching the fallback pins the whole session to the oldest capability
+    tier even after Live finishes initializing — mirrors the pattern in
+    remote_script/LivePilot/version_detect.py::get_live_version, where
+    the same bug was fixed on the Remote Script side.
+    """
+    from mcp_server.runtime.live_version import LiveVersionCapabilities
+
+    lsc = ctx.lifespan_context
+    if not force_refresh:
+        cached = lsc.get("_live_caps")
+        if cached is not None:
+            return cached
+
+    ableton = lsc.get("ableton")
+    if ableton is None:
+        logger.debug("_live_caps: no ableton in lifespan — returning 12.0.0 fallback (uncached)")
+        return LiveVersionCapabilities.from_version_string("12.0.0")
+
+    try:
+        info = ableton.send_command("get_session_info") or {}
+    except Exception as exc:
+        logger.debug("_live_caps: get_session_info raised %s — returning 12.0.0 fallback (uncached)", exc)
+        return LiveVersionCapabilities.from_version_string("12.0.0")
+
+    version_str = info.get("live_version")
+    if not version_str:
+        logger.debug("_live_caps: get_session_info returned no live_version — returning 12.0.0 fallback (uncached)")
+        return LiveVersionCapabilities.from_version_string("12.0.0")
+
+    caps = LiveVersionCapabilities.from_version_string(version_str)
+    lsc["_live_caps"] = caps
+    logger.debug("_live_caps: cached %s (tier=%s)", version_str, caps.capability_tier)
+    return caps
+
+
+async def _try_native_replace_sample(
+    ctx,
+    track_index: int,
+    device_index: int,
+    file_path: str,
+    chain_index: Optional[int] = None,
+    nested_device_index: Optional[int] = None,
+):
+    """Attempt the Live 12.4+ native SimplerDevice.replace_sample path.
+
+    Returns the remote-script response dict on success, or None if the
+    native path is unavailable (pre-12.4) or failed (caller should fall
+    back to the M4L-bridge path).
+
+    When `chain_index` is provided, the remote script walks into
+    `track.devices[device_index].chains[chain_index].devices[
+    nested_device_index or 0]` — this is how Drum Rack pad-by-pad
+    construction is unblocked (BUG-#1 in docs/2026-04-22-bugs-discovered.md).
+
+    A native "failure" is any of: gate closed, dispatch exception, non-dict
+    response, error field present, or missing sample_loaded flag. Each
+    failure path records a skip reason on ``ctx.lifespan_context[
+    "_native_replace_skip_reason"]`` so callers can surface it in the
+    bridge-path response and logs at INFO for live debugging.
+    """
+    def _record_skip(reason: str) -> None:
+        ctx.lifespan_context["_native_replace_skip_reason"] = reason
+        logger.info("native replace_sample skipped — %s", reason)
+
+    ctx.lifespan_context.pop("_native_replace_skip_reason", None)
+
+    caps = _live_caps(ctx)
+    if not caps.has_replace_sample_native:
+        _record_skip("gate_closed: tier=%s (need collaborative/12.4+)" % caps.capability_tier)
+        return None
+    ableton = ctx.lifespan_context["ableton"]
+    params = {
+        "track_index": track_index,
+        "device_index": device_index,
+        "file_path": file_path,
+    }
+    if chain_index is not None:
+        params["chain_index"] = int(chain_index)
+    if nested_device_index is not None:
+        params["nested_device_index"] = int(nested_device_index)
+    try:
+        resp = ableton.send_command("replace_sample_native", params)
+    except Exception as exc:
+        _record_skip("dispatch_raised: %s: %s" % (type(exc).__name__, exc))
+        return None
+    if not isinstance(resp, dict):
+        _record_skip("non_dict_response: type=%s" % type(resp).__name__)
+        return None
+    if "error" in resp:
+        _record_skip("remote_error: code=%s msg=%s" % (resp.get("code"), resp.get("error")))
+        return None
+    if not resp.get("sample_loaded"):
+        _record_skip("missing_sample_loaded: resp=%s" % resp)
+        return None
+    return resp
+
+
 @mcp.tool()
 async def reconnect_bridge(ctx: Context) -> dict:
     """Attempt to reconnect the M4L UDP bridge (port 9880).
@@ -101,7 +208,11 @@ async def reconnect_bridge(ctx: Context) -> dict:
 
 
 @mcp.tool()
-def get_master_spectrum(ctx: Context) -> dict:
+async def get_master_spectrum(
+    ctx: Context,
+    window_ms: int = 0,
+    samples: int = 0,
+) -> dict:
     """Get 8-band frequency analysis of the master bus.
 
     Returns band energies: sub (20-60Hz), low (60-200Hz), low_mid (200-500Hz),
@@ -110,10 +221,79 @@ def get_master_spectrum(ctx: Context) -> dict:
 
     Also returns detected key/scale if enough audio has been analyzed.
     Requires LivePilot Analyzer on master track.
+
+    BUG-2026-04-22#6 fix — windowed averaging:
+      Kick transients make single snapshots swing wildly (0.45 → 0.05 →
+      0.16 within a bar). When mixing, you want a STABLE band profile,
+      not an instantaneous frame. Pass `window_ms` to sample the cache
+      over a time window and mean-pool:
+        - window_ms=500 → sample over 500ms (common for mix reads)
+        - window_ms=2000 → sample over 2 seconds (long-tail stability)
+      When `window_ms=0` (default), returns a single instantaneous snapshot
+      — the legacy behavior. `samples` overrides the auto-computed sample
+      count (defaults to window_ms / 50, minimum 3).
+
+    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.
     """
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
 
+    if window_ms and window_ms > 0:
+        # Windowed sampling — mean-pool N readings across the window.
+        # Each cache read is ~free; we sleep between reads to let the
+        # analyzer update its internal buffer.
+        if window_ms > 10000:
+            return {"error": "window_ms must be <= 10000 (10 seconds)"}
+        n = samples if samples > 0 else max(3, window_ms // 50)
+        n = min(n, 100)
+        interval = (window_ms / 1000.0) / max(n - 1, 1)
+        bands_acc: list[dict] = []
+        for i in range(n):
+            snap = cache.get("spectrum")
+            if snap and snap.get("value"):
+                bands_acc.append(snap["value"])
+            if i < n - 1:
+                await asyncio.sleep(interval)
+        if not bands_acc:
+            return {
+                "error": "No spectrum data captured — analyzer may be stale",
+                "analyzer_hint": "Ensure LivePilot_Analyzer is active on master",
+            }
+        # Aggregate: mean / min / max / stddev per band.
+        keys = set()
+        for s in bands_acc:
+            keys.update(s.keys())
+        bands_mean = {}
+        bands_min = {}
+        bands_max = {}
+        bands_std = {}
+        for k in keys:
+            vals = [s.get(k, 0.0) for s in bands_acc]
+            mean = sum(vals) / len(vals)
+            bands_mean[k] = round(mean, 4)
+            bands_min[k] = round(min(vals), 4)
+            bands_max[k] = round(max(vals), 4)
+            if len(vals) > 1:
+                var = sum((v - mean) ** 2 for v in vals) / len(vals)
+                bands_std[k] = round(var ** 0.5, 4)
+            else:
+                bands_std[k] = 0.0
+        result = {
+            "bands": bands_mean,
+            "bands_min": bands_min,
+            "bands_max": bands_max,
+            "bands_std": bands_std,
+            "window_ms": window_ms,
+            "samples_collected": len(bands_acc),
+        }
+        key_data = cache.get("key")
+        if key_data:
+            result["detected_key"] = key_data["value"]
+        return result
+
+    # Legacy instantaneous path
     result = {}
     spectrum = cache.get("spectrum")
     if spectrum:
@@ -322,6 +502,8 @@ async def replace_simpler_sample(
     track_index: int,
     device_index: int,
     file_path: str,
+    chain_index: Optional[int] = None,
+    nested_device_index: Optional[int] = None,
 ) -> dict:
     """Load an audio file into a Simpler device by absolute file path.
 
@@ -337,6 +519,15 @@ async def replace_simpler_sample(
     now verifies by reading back the device name and will return an error
     if the replace didn't actually take effect.
 
+    Nested addressing (Live 12.4+ only, BUG-#1 fix from 2026-04-22):
+      - When `chain_index` is provided, the device is resolved at
+        `track.devices[device_index].chains[chain_index]
+         .devices[nested_device_index or 0]`. This is how Drum Rack
+        pad-by-pad construction works — see `add_drum_rack_pad` for the
+        high-level workflow.
+      - chain_index is only honored by the native 12.4 path; the M4L
+        bridge fallback cannot resolve nested paths.
+
     Also auto-applies post-load hygiene:
       - Sets Simpler Snap=0 (required for playback after replace)
       - For warped loops (filename contains 'NNbpm'), sets S Start=0,
@@ -350,12 +541,29 @@ async def replace_simpler_sample(
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
     ableton = ctx.lifespan_context["ableton"]
+
+    # Live 12.4+: prefer the native SimplerDevice.replace_sample path.
+    native = await _try_native_replace_sample(
+        ctx, track_index, device_index, file_path,
+        chain_index=chain_index, nested_device_index=nested_device_index,
+    )
+    if native is not None:
+        hygiene = await _simpler_post_load_hygiene(
+            bridge, ableton, track_index, device_index, file_path
+        )
+        if not hygiene.get("verified"):
+            return hygiene
+        result = dict(native)
+        result.update(hygiene)
+        result["method"] = "native_12_4"  # preserved in case hygiene ever adds its own key
+        return result
+
+    # Pre-12.4 fallback: M4L bridge path (unchanged behavior).
+    skip_reason = ctx.lifespan_context.get("_native_replace_skip_reason")
     result = await bridge.send_command(
         "replace_simpler_sample", track_index, device_index, file_path
     )
 
-    # Validate the response — the bridge may report success even when the
-    # sample silently failed to load (e.g., empty Simpler, bad path)
     if "error" in result:
         return result
     if not result.get("sample_loaded"):
@@ -364,8 +572,6 @@ async def replace_simpler_sample(
             "has a sample loaded — replace_sample silently fails on empty Simplers."
         }
 
-    # Verify by reading back the device name — guards against the silent
-    # failure mode where the bridge reports success but keeps the placeholder.
     hygiene = await _simpler_post_load_hygiene(
         bridge, ableton, track_index, device_index, file_path
     )
@@ -373,6 +579,9 @@ async def replace_simpler_sample(
         return hygiene
 
     result.update(hygiene)
+    result["method"] = "bridge_m4l"
+    if skip_reason:
+        result["native_skip_reason"] = skip_reason
     return result
 
 
@@ -405,9 +614,39 @@ async def load_sample_to_simpler(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
+    ableton = ctx.lifespan_context["ableton"]
+
+    # Live 12.4+: create an empty Simpler via insert_device, then use the
+    # native replace_sample path. Skips the dummy-sample bootstrap entirely.
+    caps = _live_caps(ctx)
+    if caps.has_replace_sample_native:
+        try:
+            ins = ableton.send_command("insert_device", {
+                "track_index": track_index,
+                "device_name": "Simpler",
+            })
+        except Exception:
+            ins = None
+        if isinstance(ins, dict) and "error" not in ins:
+            actual_device_index = ins.get("device_index", device_index)
+            native = await _try_native_replace_sample(
+                ctx, track_index, actual_device_index, file_path
+            )
+            if native is not None:
+                hygiene = await _simpler_post_load_hygiene(
+                    bridge, ableton, track_index, actual_device_index, file_path
+                )
+                if not hygiene.get("verified"):
+                    return hygiene
+                result = dict(native)
+                result.update(hygiene)
+                result["method"] = "native_12_4"
+                result["device_index"] = actual_device_index
+                result["track_index"] = track_index
+                return result
+        # Fall through to the legacy bootstrap path below on any failure.
 
     # Step 1: Load a sample from the browser to create Simpler with content
-    ableton = ctx.lifespan_context["ableton"]
     try:
         search = ableton.send_command("search_browser", {
             "path": "samples",
@@ -463,6 +702,193 @@ async def load_sample_to_simpler(
     return result
 
 
+@mcp.tool()
+async def add_drum_rack_pad(
+    ctx: Context,
+    track_index: int,
+    pad_note: int,
+    file_path: str,
+    rack_device_index: Optional[int] = None,
+    chain_name: Optional[str] = None,
+) -> dict:
+    """Add a new pad (chain) to a Drum Rack and load a sample into it.
+
+    **BUG-2026-04-22#1 FIX** — this is the tool that was missing.
+    Previously `load_browser_item` replaced the existing chain on repeat
+    calls, and `load_sample_to_simpler` couldn't address nested paths.
+    This single tool does the full drum-rack pad build atomically:
+
+      1. Locates the Drum Rack on the track (auto-finds if
+         `rack_device_index` is None — searches for class_name containing
+         "DrumGroupDevice").
+      2. Inserts a new chain on the rack (`insert_rack_chain`).
+      3. Assigns the chain's trigger note (`set_drum_chain_note`).
+      4. Inserts an empty Simpler into the chain (`insert_device` with
+         `chain_index`).
+      5. Calls the native Live 12.4 `replace_sample_native` with nested
+         addressing to load the sample.
+      6. Sets Snap=0 post-load (playback hygiene).
+
+    Requires Live 12.4+ for step 5. On earlier versions returns an error
+    directing the caller to the bridge-based workaround.
+
+    track_index:       track containing the Drum Rack
+    pad_note:          MIDI note for the pad (0..127). Standard drum map:
+                       36=Kick, 38=Snare, 42=Closed HH, 46=Open HH.
+    file_path:         absolute path to the audio file
+    rack_device_index: optional device_index of the Drum Rack on the track.
+                       If None, auto-detects the first Drum Rack.
+    chain_name:        optional display name for the new chain.
+
+    Returns: {
+      "ok": bool,
+      "track_index": int,
+      "rack_device_index": int,
+      "chain_index": int,
+      "pad_note": int,
+      "nested_device_index": int,   # where the Simpler landed
+      "device_name": str,
+      "method": "native_12_4",
+    }
+    """
+    from .._analyzer_engine.sample import _simpler_post_load_hygiene  # noqa
+    ableton = ctx.lifespan_context["ableton"]
+    caps = _live_caps(ctx)
+    if not caps.has_replace_sample_native:
+        return {
+            "ok": False,
+            "error": (
+                "add_drum_rack_pad requires Live 12.4+ for native nested "
+                "sample loading. Detected tier: " + caps.capability_tier +
+                ". Upgrade to Live 12.4 or use the legacy separate-tracks "
+                "workflow described in docs/2026-04-22-bugs-discovered.md."
+            ),
+        }
+
+    if not (0 <= pad_note <= 127):
+        return {"ok": False, "error": "pad_note must be 0..127"}
+    if not file_path or not isinstance(file_path, str):
+        return {"ok": False, "error": "file_path (absolute path) is required"}
+
+    # Step 1: locate the Drum Rack if not provided.
+    if rack_device_index is None:
+        try:
+            info = ableton.send_command(
+                "get_track_info", {"track_index": track_index},
+            )
+        except Exception as exc:
+            return {"ok": False, "error": f"get_track_info failed: {exc}"}
+        devices = info.get("devices", []) if isinstance(info, dict) else []
+        found_idx = None
+        for idx, d in enumerate(devices):
+            class_name = str(d.get("class_name") or "")
+            if "DrumGroup" in class_name or class_name == "DrumGroupDevice":
+                found_idx = idx
+                break
+        if found_idx is None:
+            return {
+                "ok": False,
+                "error": (
+                    "No Drum Rack found on track. Pass `rack_device_index` "
+                    "explicitly, or use `insert_device('Drum Rack')` first."
+                ),
+            }
+        rack_device_index = found_idx
+
+    # Step 2: insert a new chain on the rack.
+    try:
+        chain_result = ableton.send_command("insert_rack_chain", {
+            "track_index": track_index,
+            "device_index": rack_device_index,
+            "position": -1,  # append to end
+        })
+    except Exception as exc:
+        return {"ok": False, "error": f"insert_rack_chain failed: {exc}"}
+    if not isinstance(chain_result, dict) or "error" in chain_result:
+        return {
+            "ok": False,
+            "error": f"insert_rack_chain returned: {chain_result}",
+        }
+    chain_index = int(chain_result.get("chain_index", chain_result.get("index", 0)))
+
+    # Step 3: assign pad note to the new chain.
+    try:
+        note_result = ableton.send_command("set_drum_chain_note", {
+            "track_index": track_index,
+            "device_index": rack_device_index,
+            "chain_index": chain_index,
+            "note": pad_note,
+        })
+    except Exception as exc:
+        return {"ok": False, "error": f"set_drum_chain_note failed: {exc}"}
+    if isinstance(note_result, dict) and "error" in note_result:
+        return {"ok": False, "error": f"set_drum_chain_note: {note_result['error']}"}
+
+    # Step 4: insert an empty Simpler into the chain.
+    try:
+        insert_result = ableton.send_command("insert_device", {
+            "track_index": track_index,
+            "device_index": rack_device_index,
+            "chain_index": chain_index,
+            "device_name": "Simpler",
+        })
+    except Exception as exc:
+        return {"ok": False, "error": f"insert_device(Simpler, chain) failed: {exc}"}
+    if not isinstance(insert_result, dict) or "error" in insert_result:
+        return {
+            "ok": False,
+            "error": f"insert_device into chain failed: {insert_result}",
+        }
+    nested_idx = int(insert_result.get("device_index", 0))
+
+    # Step 5: replace_sample_native with nested addressing.
+    native = await _try_native_replace_sample(
+        ctx,
+        track_index=track_index,
+        device_index=rack_device_index,
+        file_path=file_path,
+        chain_index=chain_index,
+        nested_device_index=nested_idx,
+    )
+    if native is None:
+        return {
+            "ok": False,
+            "error": "Native replace_sample failed — see logs for reason",
+            "track_index": track_index,
+            "rack_device_index": rack_device_index,
+            "chain_index": chain_index,
+            "nested_device_index": nested_idx,
+        }
+
+    # Step 6: apply chain name (wired to the new set_chain_name handler)
+    applied_name = None
+    if chain_name:
+        try:
+            rename_result = ableton.send_command("set_chain_name", {
+                "track_index": track_index,
+                "device_index": rack_device_index,
+                "chain_index": chain_index,
+                "name": chain_name,
+            })
+            if isinstance(rename_result, dict) and "name" in rename_result:
+                applied_name = rename_result["name"]
+        except Exception as exc:
+            logger.debug("set_chain_name skipped: %s", exc)
+
+    return {
+        "ok": True,
+        "track_index": track_index,
+        "rack_device_index": rack_device_index,
+        "chain_index": chain_index,
+        "pad_note": pad_note,
+        "nested_device_index": nested_idx,
+        "device_name": "Simpler",
+        "method": native.get("method", "native_12_4"),
+        "file_path": file_path,
+        "chain_name": applied_name,
+    }
+
+
 @mcp.tool()
 async def get_simpler_slices(
     ctx: Context,
@@ -969,6 +1395,145 @@ def get_novelty(ctx: Context) -> dict:
     return {**data["value"], "age_ms": data["age_ms"]}
 
 
+@mcp.tool()
+async def verify_device_health(
+    ctx: Context,
+    track_index: int,
+    test_midi_note: int = 60,
+    test_velocity: int = 100,
+    test_duration_ms: int = 300,
+    threshold: float = 0.005,
+) -> dict:
+    """Fire a test MIDI note at a track's instrument and check for output.
+
+    BUG-2026-04-22#19 fix — parameter_count alone can't tell you whether
+    an AU/VST is alive. Plenty of "loaded" plugins return 19 params and
+    silence. This tool does the real-world check:
+
+      1. Snapshot the track meter.
+      2. Emit a MIDI note at the specified pitch/velocity.
+      3. Sample the track meter for `test_duration_ms` (peak across samples).
+      4. Compare the peak to a threshold; report alive vs dead.
+
+    The meter readout is taken with `get_track_meters(samples=N)` so the
+    BUG-#7 "left=right=0 while level>0" artifact can't cause false negatives.
+
+    track_index:      track with the instrument to verify
+    test_midi_note:   pitch to fire (default C3 / 60 — safe for most samples)
+    test_velocity:    1-127 (default 100)
+    test_duration_ms: capture window for the meter (default 300ms)
+    threshold:        peak level below which the device is considered dead
+                      (default 0.005 — roughly -46 dBFS)
+
+    Returns: {
+      "ok": bool,
+      "alive": bool,
+      "peak_level": float,
+      "threshold": float,
+      "samples_taken": int,
+      "hint": str,     # actionable advice when dead
+    }
+
+    Requires LivePilot Analyzer on master track and a playable instrument
+    on the target track. Prefer this over trying to eyeball parameter_count.
+    """
+    ableton = ctx.lifespan_context["ableton"]
+
+    # Bound test_duration to something humane
+    if test_duration_ms < 100:
+        test_duration_ms = 100
+    if test_duration_ms > 2000:
+        test_duration_ms = 2000
+    if not 1 <= test_velocity <= 127:
+        return {"ok": False, "error": "test_velocity must be 1-127"}
+    if not 0 <= test_midi_note <= 127:
+        return {"ok": False, "error": "test_midi_note must be 0-127"}
+
+    # Fire the test note via the remote script's play_note helper. Fall back
+    # to a raw MIDI event if the helper isn't available.
+    fired = False
+    try:
+        resp = ableton.send_command("fire_test_note", {
+            "track_index": track_index,
+            "midi_note": test_midi_note,
+            "velocity": test_velocity,
+            "duration_ms": test_duration_ms,
+        })
+        if isinstance(resp, dict) and not resp.get("error"):
+            fired = True
+    except Exception as exc:
+        logger.debug("fire_test_note unavailable: %s", exc)
+
+    if not fired:
+        # Graceful degradation when the remote-script helper isn't present.
+        return {
+            "ok": False,
+            "error": (
+                "fire_test_note handler not available on this remote script. "
+                "Update LivePilot's remote script (npx livepilot --install + "
+                "reload_handlers) to enable verify_device_health."
+            ),
+            "alive": None,
+        }
+
+    # Sample the track meter over the duration of the note.
+    sample_interval_ms = 50
+    n = max(2, test_duration_ms // sample_interval_ms)
+    peak = 0.0
+    samples_taken = 0
+    for i in range(n):
+        try:
+            snap = ableton.send_command("get_track_meters", {
+                "track_index": track_index,
+            })
+        except Exception as exc:
+            logger.debug("get_track_meters snapshot failed: %s", exc)
+            continue
+        samples_taken += 1
+        if isinstance(snap, dict):
+            tracks = snap.get("tracks") or []
+            for t in tracks:
+                if not isinstance(t, dict):
+                    continue
+                level = t.get("level") or 0
+                try:
+                    peak = max(peak, float(level))
+                except (TypeError, ValueError):
+                    pass
+        if i < n - 1:
+            await asyncio.sleep(sample_interval_ms / 1000.0)
+
+    # Always clean up the scratch clip, even on errors.
+    try:
+        ableton.send_command("cleanup_test_note", {"track_index": track_index})
+    except Exception as exc:
+        logger.debug("cleanup_test_note failed: %s", exc)
+
+    alive = peak >= threshold
+    hint = ""
+    if not alive:
+        hint = (
+            "Device produced no audible output. Common causes: "
+            "(1) plugin waiting for preset/bank selection, "
+            "(2) algorithm/envelope configured for zero output, "
+            "(3) wrong MIDI channel or velocity curve, "
+            "(4) dead VST (reinstall). "
+            "Try opening the device UI and auditioning manually."
+        )
+
+    return {
+        "ok": True,
+        "alive": alive,
+        "peak_level": round(peak, 4),
+        "threshold": threshold,
+        "samples_taken": samples_taken,
+        "test_midi_note": test_midi_note,
+        "test_velocity": test_velocity,
+        "test_duration_ms": test_duration_ms,
+        "hint": hint,
+    }
+
+
 @mcp.tool()
 def get_momentary_loudness(ctx: Context) -> dict:
     """Get EBU R128 momentary LUFS + true peak from FluCoMa.
@@ -985,6 +1550,101 @@ def get_momentary_loudness(ctx: Context) -> dict:
     return {**data["value"], "age_ms": data["age_ms"]}
 
 
+@mcp.tool()
+async def analyze_loudness_live(
+    ctx: Context,
+    window_sec: float = 10.0,
+    sample_interval_ms: int = 200,
+) -> dict:
+    """Analyze the currently-playing master output's loudness over a window.
+
+    BUG-2026-04-22#8 fix — the offline `analyze_loudness` requires a
+    rendered file. This tool samples the LivePilot analyzer's realtime
+    momentary LUFS / true peak stream over `window_sec` and reports
+    integrated + max statistics. No render required.
+
+    Requires FluCoMa package in Max and playback to be running. Best
+    called while the section you want to measure is actually playing.
+
+    window_sec:         capture duration in seconds (default 10, max 120)
+    sample_interval_ms: ms between samples (default 200 ≈ 5 Hz)
+
+    Returns: {
+      "integrated_lufs": float,      # mean momentary LUFS over window
+      "max_momentary_lufs": float,   # peak momentary reading
+      "min_momentary_lufs": float,   # quietest reading
+      "range_lu": float,             # max - min (proxy for LRA)
+      "max_true_peak_dbtp": float,   # max true peak across window
+      "samples_collected": int,
+      "window_sec": float,
+      "is_playing": bool,
+    }
+    """
+    if window_sec <= 0 or window_sec > 120:
+        return {"error": "window_sec must be > 0 and <= 120"}
+    if sample_interval_ms < 50 or sample_interval_ms > 5000:
+        return {"error": "sample_interval_ms must be 50..5000"}
+
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    ableton = ctx.lifespan_context["ableton"]
+
+    # Verify FluCoMa is alive — otherwise there's no stream to sample.
+    preview = cache.get("loudness")
+    if not preview:
+        hint = _flucoma_hint(cache)
+        return {"error": f"No live loudness stream — {hint}"}
+
+    try:
+        session = ableton.send_command("get_session_info", {})
+        is_playing = bool(session.get("is_playing", False))
+    except Exception:
+        is_playing = None
+
+    interval_s = sample_interval_ms / 1000.0
+    total_samples = max(1, int(window_sec / interval_s))
+    lufs_vals: list[float] = []
+    peak_vals: list[float] = []
+
+    for i in range(total_samples):
+        snap = cache.get("loudness")
+        if snap and snap.get("value"):
+            v = snap["value"]
+            if "momentary_lufs" in v:
+                lufs_vals.append(float(v["momentary_lufs"]))
+            elif "lufs" in v:
+                lufs_vals.append(float(v["lufs"]))
+            if "true_peak_dbtp" in v:
+                peak_vals.append(float(v["true_peak_dbtp"]))
+            elif "peak_dbfs" in v:
+                peak_vals.append(float(v["peak_dbfs"]))
+        if i < total_samples - 1:
+            await asyncio.sleep(interval_s)
+
+    if not lufs_vals:
+        return {"error": "No valid loudness samples captured over the window"}
+
+    integrated = sum(lufs_vals) / len(lufs_vals)
+    result = {
+        "integrated_lufs": round(integrated, 2),
+        "max_momentary_lufs": round(max(lufs_vals), 2),
+        "min_momentary_lufs": round(min(lufs_vals), 2),
+        "range_lu": round(max(lufs_vals) - min(lufs_vals), 2),
+        "samples_collected": len(lufs_vals),
+        "window_sec": window_sec,
+        "sample_interval_ms": sample_interval_ms,
+        "is_playing": is_playing,
+    }
+    if peak_vals:
+        result["max_true_peak_dbtp"] = round(max(peak_vals), 2)
+    if is_playing is False:
+        result["warning"] = (
+            "Playback was not running — readings reflect stale cache. "
+            "Start playback and call again for accurate live analysis."
+        )
+    return result
+
+
 @mcp.tool()
 def check_flucoma(ctx: Context) -> dict:
     """Check if FluCoMa is installed and sending data."""