Upload folder using huggingface_hub

README.md

@@ -1,13 +1,104 @@
 ---
 title: Second Ear
-emoji: 🏢
-colorFrom: yellow
-colorTo: indigo
+emoji: 👂
+colorFrom: indigo
+colorTo: gray
 sdk: gradio
 sdk_version: 6.23.1
-python_version: '3.13'
 app_file: app.py
+python_version: "3.12"
+short_description: Realtime mix ear that writes Ableton MCP plans
+startup_duration_timeout: 30m
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Second Ear
+
+A realtime music production assistant. It listens to what you're making, tells
+you what's wrong in engineer's language, and hands your agent an executable
+Ableton Live plan to fix it.
+
+Built by [Apolithos Studios](https://apolithosstudios.com).
+
+## What it actually does
+
+**Hears.** A rolling 8-second window of whatever your browser input is carrying.
+Seven-band balance, K-weighted loudness, crest factor, stereo correlation,
+sub-band phase, tempo and key — re-metered twice a second, each band drawn
+against the target window for the genre you picked.
+
+**Judges.** A rule engine with genre profiles (dubstep, DnB, house, trap, pop,
+ambient, streaming master). It doesn't report numbers, it reports consequences:
+*"crest factor 4.8 dB — the transients are gone"*, and then the move that fixes
+it. A CLAP model adds the semantic layer, so the report can say *"gritty
+distorted reese bass, over-compressed drums"* alongside the measurements.
+
+**Acts.** Findings compile into a sequence of Ableton MCP calls —
+`load_instrument_or_effect`, `get_device_parameters`, `set_device_parameter` —
+that an agent with a local Ableton MCP server runs directly against your set.
+
+## The honest architecture
+
+This Space cannot touch your Live set. Nothing hosted on someone else's machine
+can. So the work is split:
+
+| | |
+|---|---|
+| **Second Ear** (here) | ears and judgement — measures, diagnoses, writes the plan |
+| **Ableton MCP** (your machine) | hands — executes the plan against the running set |
+
+Every endpoint here is an MCP tool, so one agent can hold both.
+
+```json
+{
+  "mcpServers": {
+    "second-ear": {
+      "command": "npx",
+      "args": ["mcp-remote",
+               "https://apolithosstudios-second-ear.hf.space/gradio_api/mcp/sse"]
+    }
+  }
+}
+```
+
+| Tool | Does |
+|---|---|
+| `analyse_file` | full report: measurements, findings, critique, Ableton plan |
+| `measure` | raw metrics as JSON, no opinions |
+| `ableton_plan` | just the Ableton MCP call sequence |
+
+## Feeding it live audio
+
+The Live tab hears your browser's input device. To point it at your master bus:
+
+1. Install a loopback driver — [BlackHole](https://existential.audio/blackhole/)
+   (free) or Loopback.
+2. Route Live's output, or a dedicated send, to that device.
+3. Select it when the browser asks for microphone permission.
+
+**Caveat worth stating plainly:** browsers apply echo cancellation, noise
+suppression and auto gain to captured audio. That's fine for *direction* — the
+sub creeping up, the drop losing punch, the low mids filling in — and it is not
+fine for absolute numbers. For measurement-grade LUFS and true peak, bounce a
+file and use the Bounce tab. Live is the ear on your shoulder; Bounce is the
+meter.
+
+## Configuration
+
+| Variable | Effect |
+|---|---|
+| `HF_TOKEN` | *(secret)* enables the written critique via Inference Providers. Without it the rule engine runs alone and the UI says so. |
+| `EAR_LLM_MODEL` | override the narration model (default `Qwen/Qwen3-235B-A22B-Instruct-2507`) |
+
+## Measurement notes
+
+- Loudness is ITU-R BS.1770-4: K-weighted, 400 ms blocks, absolute gate at
+  -70 LUFS and a -10 LU relative gate.
+- True peak is 4× oversampled.
+- Everything resamples to 48 kHz on the way in, so the K-weighting biquads stay
+  valid and metrics are comparable across sources.
+- Band judgements fire on *ratios* between bands, not absolute fractions —
+  absolute band energy drifts with arrangement density, ratios survive it.
+- Key is Krumhansl-Schmuckler over an FFT chroma; tempo is autocorrelation of a
+  spectral-flux onset envelope with octave correction. Both are estimates and
+  the UI reports them as such.

app.py

@@ -0,0 +1,412 @@
+"""Second Ear — a realtime music production assistant.
+
+Three surfaces over one analysis engine:
+
+  Live       a rolling window of whatever the browser is hearing, metered
+             against genre targets, with findings that fire as they happen.
+  Bounce     measurement-grade pass on a rendered file, plus the semantic
+             layer, the written critique, and an Ableton action plan.
+  Bridge     how to wire the plan into a real Live set through MCP.
+
+Every analysis endpoint is also an MCP tool, so an agent that already has
+Ableton MCP connected can use this Space as its ears and its own Ableton
+connection as its hands.
+"""
+
+from __future__ import annotations
+
+import json
+
+import gradio as gr
+import numpy as np
+import soundfile as sf
+
+from ear import ableton, dsp, knowledge, llm, render, semantic
+
+LIVE_WINDOW_S = 8.0        # what the meters describe
+CAPTURE_S = 30.0           # how far back "analyse what just happened" reaches
+TEMPO_EVERY = 8            # ticks between tempo/key refresh (they need context)
+
+semantic.SEMANTIC.start()
+
+
+# --------------------------------------------------------------------------
+# shared helpers
+# --------------------------------------------------------------------------
+
+def _read(path: str) -> tuple[int, np.ndarray]:
+    data, sr = sf.read(path, dtype="float32", always_2d=True)
+    return sr, data
+
+
+def _blank_state() -> dict:
+    return {"buf": np.zeros((0, 2), dtype=np.float32), "tick": 0,
+            "rhythm": {"bpm": 0.0, "confidence": 0.0, "onset_rate": 0.0},
+            "key": {"key": "—", "confidence": 0.0}}
+
+
+# --------------------------------------------------------------------------
+# live loop
+# --------------------------------------------------------------------------
+
+def live_tick(chunk, state, genre, source):
+    """Fold one streamed chunk into the rolling window and re-meter."""
+    state = state or _blank_state()
+    if chunk is None:
+        return render.idle("waiting for signal…"), render.idle("no findings yet"), state
+
+    sr, data = chunk
+    incoming = dsp.to_float_stereo(sr, data)
+    if incoming.shape[0] == 0:
+        return gr.skip(), gr.skip(), state
+
+    buf = np.concatenate([state["buf"], incoming], axis=0)
+    keep = int(CAPTURE_S * dsp.SR)
+    if buf.shape[0] > keep:
+        buf = buf[-keep:]
+    state["buf"] = buf
+    state["tick"] += 1
+
+    window = buf[-int(LIVE_WINDOW_S * dsp.SR):]
+    if float(np.max(np.abs(window))) < 1e-4:
+        return render.idle("signal is silent — check the input device"), gr.skip(), state
+
+    rep = dsp.analyze(dsp.SR, window, fast=True)
+    if rep is None:
+        return gr.skip(), gr.skip(), state
+
+    # Tempo and key need a longer view than the meter window, and cost more,
+    # so they refresh on their own slower clock and are carried between ticks.
+    if state["tick"] % TEMPO_EVERY == 1 and buf.shape[0] > 12 * dsp.SR:
+        mono = buf[-int(16 * dsp.SR):].mean(axis=1)
+        flux, fps = dsp.onset_envelope(mono)
+        state["rhythm"] = dsp.tempo_from_onsets(flux, fps)
+        freqs, power = dsp.spectrum(mono)
+        state["key"] = dsp.key_estimate(freqs, power)
+    rep.rhythm, rep.key = state["rhythm"], state["key"]
+
+    diags = knowledge.diagnose(rep, genre, source)
+    verdict, tone = knowledge.headline_verdict(rep, diags)
+    held = min(buf.shape[0] / dsp.SR, CAPTURE_S)
+
+    return (
+        render.meters(rep, genre, verdict, tone,
+                      extra=f"{LIVE_WINDOW_S:.0f}s window · {held:.0f}s held"),
+        render.cards(diags, limit=4),
+        state,
+    )
+
+
+def analyse_capture(state, genre, source, intent, use_llm):
+    """Run the full pass on whatever the live loop has been holding."""
+    state = state or _blank_state()
+    buf = state.get("buf")
+    if buf is None or buf.shape[0] < dsp.SR:
+        return (render.idle("nothing captured yet — start listening first"),
+                "Not enough audio held to analyse.", "{}")
+    return _full_pass(dsp.SR, buf, genre, source, intent, use_llm)
+
+
+# --------------------------------------------------------------------------
+# full pass (shared by the bounce tab and the API)
+# --------------------------------------------------------------------------
+
+def _full_pass(sr, data, genre, source, intent, use_llm):
+    rep = dsp.analyze(sr, data)
+    if rep is None:
+        return render.idle("clip too short"), "Clip too short to analyse.", "{}"
+
+    diags = knowledge.diagnose(rep, genre, source)
+    verdict, tone = knowledge.headline_verdict(rep, diags)
+
+    mono = dsp.to_float_stereo(sr, data).mean(axis=1)
+    tags = semantic.SEMANTIC.describe(mono)
+    tag_line = semantic.tags_line(tags)
+
+    plan = ableton.build_plan(diags, genre=genre, bpm=rep.rhythm.get("bpm", 0.0))
+
+    parts = [render.meters(rep, genre, verdict, tone,
+                           extra=f"{rep.duration:.1f}s · {genre}")]
+    if tag_line:
+        parts.append(
+            f'{render.STYLE}<div class="se-wrap" style="margin-top:10px">'
+            f'<div class="se-num-k">sounds like</div>'
+            f'<div style="font-size:13px;margin-top:5px">{tag_line}</div></div>'
+        )
+    parts.append(f'<div style="margin-top:10px">{render.cards(diags)}</div>')
+
+    written = [f"### {verdict}", ""]
+    if tag_line:
+        written.append(f"*Sounds like: {tag_line}*\n")
+    if use_llm:
+        note = llm.critique(rep.to_dict(), [d.to_dict() for d in diags],
+                            tags, genre, source, intent)
+        written += [note, "", "---", ""] if note else [f"*{llm.available()[1]}*", ""]
+    written += ["## Ableton action plan", "", ableton.plan_to_markdown(plan)]
+
+    export = {"report": rep.to_dict(),
+              "findings": [d.to_dict() for d in diags],
+              "sounds_like": {g: [t for t, _ in v] for g, v in tags.items()},
+              "ableton_plan": plan}
+
+    return "".join(parts), "\n".join(written), json.dumps(export, indent=2)
+
+
+def analyse_file(audio_path: str, genre: str = "Dubstep / Riddim",
+                 source: str = "Full mix / master", intent: str = "",
+                 use_llm: bool = True):
+    """Analyse a rendered audio file and return a full production report.
+
+    Args:
+        audio_path: path to the audio file to listen to (wav, mp3, flac, aiff).
+        genre: which target window to judge against, e.g. "Dubstep / Riddim".
+        source: what the audio is — "Full mix / master", "Drum bus", "Bass / 808",
+            "Lead / synth", "Vocal" or "Pad / atmosphere".
+        intent: optional free text describing what you were going for.
+        use_llm: include the written engineer's critique (needs HF_TOKEN on the Space).
+    """
+    if not audio_path:
+        return render.idle("load a file first"), "No audio supplied.", "{}"
+    sr, data = _read(audio_path)
+    return _full_pass(sr, data, genre, source, intent, use_llm)
+
+
+def measure(audio_path: str) -> str:
+    """Measure an audio file and return the raw metrics as JSON.
+
+    Loudness (LUFS-I/S, LRA), true peak, crest factor, seven-band balance,
+    band ratios, stereo correlation and width, tempo and key. No opinions.
+
+    Args:
+        audio_path: path to the audio file to measure.
+    """
+    if not audio_path:
+        return json.dumps({"error": "no audio supplied"})
+    sr, data = _read(audio_path)
+    rep = dsp.analyze(sr, data)
+    if rep is None:
+        return json.dumps({"error": "clip too short"})
+    return json.dumps(rep.to_dict(), indent=2)
+
+
+def ableton_plan(audio_path: str, genre: str = "Dubstep / Riddim",
+                 source: str = "Full mix / master",
+                 track_index: str = "$MASTER") -> str:
+    """Return an Ableton Live action plan for an audio file, as MCP call JSON.
+
+    The plan is a sequence of Ableton MCP tool calls (load_instrument_or_effect,
+    get_device_parameters, set_device_parameter, …) that an agent with a local
+    Ableton MCP server connected can execute directly against a running set.
+
+    Args:
+        audio_path: path to the audio file to analyse.
+        genre: target window to judge against.
+        source: what the audio is (master, drum bus, bass, vocal, …).
+        track_index: which Live track the plan targets. "$MASTER" for the master.
+    """
+    if not audio_path:
+        return json.dumps({"error": "no audio supplied"})
+    sr, data = _read(audio_path)
+    rep = dsp.analyze(sr, data)
+    if rep is None:
+        return json.dumps({"error": "clip too short"})
+    diags = knowledge.diagnose(rep, genre, source)
+    plan = ableton.build_plan(diags, track_index=track_index, genre=genre,
+                              bpm=rep.rhythm.get("bpm", 0.0))
+    return json.dumps(plan, indent=2)
+
+
+# --------------------------------------------------------------------------
+# UI
+# --------------------------------------------------------------------------
+
+CSS = """
+#col-container{max-width:1180px;margin:0 auto;}
+.dark .gradio-container{color:var(--body-text-color);}
+#se-title h1{font-size:30px;letter-spacing:-0.02em;margin-bottom:2px;}
+"""
+
+GENRE_CHOICES = list(knowledge.GENRES.keys())
+
+BRIDGE = """
+## Wiring it into Live
+
+This Space listens and decides. It does not touch your set — nothing hosted on
+someone else's machine can, and a tool that pretended otherwise would be lying
+to you. The split is deliberate:
+
+| | |
+|---|---|
+| **Second Ear** (this Space) | ears + judgement — measures, diagnoses, writes the plan |
+| **Ableton MCP** (your machine) | hands — executes the plan against the live set |
+
+### 1. Point your agent at both
+
+Every endpoint here is exposed as an MCP tool. Add this Space alongside your
+existing Ableton MCP server:
+
+```json
+{
+  "mcpServers": {
+    "second-ear": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://apolithosstudios-second-ear.hf.space/gradio_api/mcp/sse"]
+    },
+    "ableton": { "command": "...your existing Ableton MCP entry..." }
+  }
+}
+```
+
+Tools you get: `analyse_file`, `measure`, `ableton_plan`.
+
+### 2. Ask for the loop
+
+> "Bounce the drop, run it through second-ear as Dubstep / Riddim, then execute
+> the plan on my master."
+
+The agent calls `ableton_plan`, gets back Ableton MCP calls, and runs them.
+Every parameter write is preceded by a `get_device_parameters` probe, because
+Live's parameter names move between versions — the plan resolves names at
+execution time instead of guessing.
+
+### 3. Feeding it live audio
+
+The Live tab listens to whatever the browser's input device is. To point it at
+your master bus instead of the room:
+
+1. Install a loopback driver — **BlackHole** (free) or **Loopback**.
+2. In Live, set the output (or a dedicated send) to that device.
+3. Pick it as the input when the browser asks for microphone permission.
+
+One honest caveat: browsers apply echo cancellation, noise suppression and auto
+gain to captured audio by default. That is fine for *direction* — balance
+drifting, sub running hot, the drop losing punch — and it is not fine for
+absolute numbers. **For measurement-grade LUFS and true peak, bounce a file and
+use the Bounce tab.** The Live tab is the ear on your shoulder; the Bounce tab
+is the meter.
+"""
+
+
+with gr.Blocks(theme=gr.themes.Citrus(), css=CSS, title="Second Ear") as demo:
+    with gr.Column(elem_id="col-container"):
+        gr.Markdown(
+            "# Second Ear\n"
+            "A realtime production assistant that listens to what you're making, "
+            "tells you what's wrong in engineer's language, and hands your agent "
+            "an Ableton plan to fix it.",
+            elem_id="se-title",
+        )
+
+        with gr.Row():
+            genre = gr.Dropdown(GENRE_CHOICES, value=GENRE_CHOICES[0],
+                                label="Target sound", scale=2)
+            source = gr.Dropdown(knowledge.SOURCES, value=knowledge.SOURCES[0],
+                                 label="Listening to", scale=2)
+
+        with gr.Tabs():
+            # ---------------------------------------------------------- live
+            with gr.Tab("Live"):
+                gr.Markdown(
+                    "Route your master through a loopback device, start the input, "
+                    "and leave it running. The meters show a rolling 8-second "
+                    "window against the target you picked; findings fire as they "
+                    "happen. The ghost block behind each bar is where that band "
+                    "should sit for this genre."
+                )
+                live_in = gr.Audio(sources=["microphone"], streaming=True,
+                                   type="numpy", label="Studio input",
+                                   show_download_button=False)
+                live_meters = gr.HTML(render.idle("waiting for signal…"))
+                live_notes = gr.HTML(render.idle("no findings yet"))
+
+                with gr.Row():
+                    capture_btn = gr.Button("Analyse the last 30 seconds",
+                                            variant="primary", scale=2)
+                    live_llm = gr.Checkbox(value=True, label="Written critique",
+                                           scale=1)
+                live_intent = gr.Textbox(
+                    label="What were you going for? (optional)",
+                    placeholder="heavier drop, needs to hit on a club rig",
+                    lines=1,
+                )
+                cap_report = gr.HTML()
+                cap_text = gr.Markdown()
+                with gr.Accordion("Raw export (JSON)", open=False):
+                    cap_json = gr.Code(language="json")
+
+                state = gr.State(_blank_state())
+                live_in.stream(
+                    live_tick,
+                    inputs=[live_in, state, genre, source],
+                    outputs=[live_meters, live_notes, state],
+                    stream_every=0.5,
+                    show_progress="hidden",
+                    concurrency_limit=None,
+                )
+                capture_btn.click(
+                    analyse_capture,
+                    inputs=[state, genre, source, live_intent, live_llm],
+                    outputs=[cap_report, cap_text, cap_json],
+                )
+
+            # -------------------------------------------------------- bounce
+            with gr.Tab("Bounce"):
+                gr.Markdown(
+                    "Measurement-grade pass on a rendered file — real LUFS, real "
+                    "true peak, the semantic layer, the written critique, and the "
+                    "Ableton plan."
+                )
+                with gr.Row():
+                    file_in = gr.Audio(sources=["upload", "microphone"],
+                                       type="filepath", label="Bounce")
+                    with gr.Column():
+                        file_intent = gr.Textbox(
+                            label="What were you going for? (optional)",
+                            placeholder="dark and heavy, has to survive a club system",
+                            lines=2,
+                        )
+                        file_llm = gr.Checkbox(value=True, label="Written critique")
+                        run_btn = gr.Button("Listen", variant="primary")
+
+                file_report = gr.HTML()
+                file_text = gr.Markdown()
+                with gr.Accordion("Raw export (JSON)", open=False):
+                    file_json = gr.Code(language="json")
+
+                run_btn.click(
+                    analyse_file,
+                    inputs=[file_in, genre, source, file_intent, file_llm],
+                    outputs=[file_report, file_text, file_json],
+                    api_name="analyse_file",
+                )
+
+                with gr.Accordion("Numbers only (no opinions)", open=False):
+                    meas_btn = gr.Button("Measure")
+                    meas_out = gr.Code(language="json", label="Metrics")
+                    meas_btn.click(measure, inputs=[file_in], outputs=meas_out,
+                                   api_name="measure")
+
+            # -------------------------------------------------------- bridge
+            with gr.Tab("Ableton bridge"):
+                gr.Markdown(BRIDGE)
+                with gr.Row():
+                    plan_audio = gr.Audio(type="filepath", label="Bounce")
+                    with gr.Column():
+                        plan_track = gr.Textbox("$MASTER", label="Target track index")
+                        plan_btn = gr.Button("Build the plan", variant="primary")
+                plan_out = gr.Code(language="json", label="Ableton MCP calls")
+                plan_btn.click(
+                    ableton_plan,
+                    inputs=[plan_audio, genre, source, plan_track],
+                    outputs=plan_out,
+                    api_name="ableton_plan",
+                )
+
+        gr.Markdown(
+            f"<sub>Semantic layer: {semantic.SEMANTIC.status()} · "
+            f"written critique: {llm.available()[1]}</sub>"
+        )
+
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=4).launch(mcp_server=True)

ear/__init__.py

@@ -0,0 +1 @@
+"""Second Ear — realtime listening + sound-design analysis engine."""

ear/ableton.py

@@ -0,0 +1,302 @@
+"""Diagnosis → executable Ableton Live moves.
+
+This Space is the ears. It has no route into your Live set, and pretending
+otherwise would be a lie. What it emits instead is a plan in the exact shape
+the Ableton MCP server expects, so an agent with that server connected
+locally can execute it verbatim.
+
+Parameter names differ between Live versions and device presets, so every
+step that sets a parameter is preceded by a `get_device_parameters` probe and
+carries a `match` hint. The executing agent resolves the real name rather
+than trusting a hardcoded string.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .knowledge import Diagnosis
+
+# Browser paths as they appear in Live's own device tree. `load_instrument_or_effect`
+# wants a browser URI, which the agent resolves with `get_browser_items_at_path`.
+DEVICE_PATHS = {
+    "EQ Eight": "Audio Effects/EQ Eight",
+    "EQ Three": "Audio Effects/EQ Three",
+    "Utility": "Audio Effects/Utility",
+    "Glue Compressor": "Audio Effects/Glue Compressor",
+    "Compressor": "Audio Effects/Compressor",
+    "Multiband Dynamics": "Audio Effects/Multiband Dynamics",
+    "Limiter": "Audio Effects/Limiter",
+    "Saturator": "Audio Effects/Saturator",
+    "Drum Buss": "Audio Effects/Drum Buss",
+    "Roar": "Audio Effects/Roar",
+    "Dynamic Tube": "Audio Effects/Dynamic Tube",
+    "Auto Filter": "Audio Effects/Auto Filter",
+    "Hybrid Reverb": "Audio Effects/Hybrid Reverb",
+    "Spectrum": "Audio Effects/Spectrum",
+    "Operator": "Instruments/Operator",
+}
+
+
+def _load(track: Any, device: str, note: str = "") -> dict:
+    return {
+        "tool": "load_instrument_or_effect",
+        "args": {"track_index": track, "uri": DEVICE_PATHS.get(device, device)},
+        "device": device,
+        "resolve": "call get_browser_tree / get_browser_items_at_path to turn "
+                   "this path into a concrete browser URI",
+        "skip_if": f"{device} already exists on this track",
+        "note": note,
+    }
+
+
+def _probe(track: Any, device: str) -> dict:
+    return {
+        "tool": "get_device_parameters",
+        "args": {"track_index": track, "device_index": "$LAST"},
+        "purpose": f"resolve the real parameter names for {device} in this Live version",
+    }
+
+
+def _set(track: Any, match: str, value: Any, why: str) -> dict:
+    return {
+        "tool": "set_device_parameter",
+        "args": {"track_index": track, "device_index": "$LAST",
+                 "parameter_name": match, "value": value},
+        "match": match,
+        "why": why,
+    }
+
+
+# --------------------------------------------------------------------------
+# per-diagnosis recipes
+# --------------------------------------------------------------------------
+
+def _recipe(d: Diagnosis, track: Any) -> list[dict] | None:
+    if d.id in ("clipping", "no_headroom"):
+        return [
+            _load(track, "Limiter", "master chain, last in the signal path"),
+            _probe(track, "Limiter"),
+            _set(track, "Ceiling", -1.0, "true peak target of -1.0 dBTP survives lossy encoding"),
+            _set(track, "Release", 200.0, "slow enough not to pump on sustained low end"),
+        ]
+
+    if d.id == "too_loud":
+        return [
+            _probe(track, "Limiter"),
+            _set(track, "Gain", round(-d.amount, 1),
+                 f"back off {d.amount:.1f} dB of limiter drive"),
+            _load(track, "Saturator", "recover density without more ceiling"),
+            _probe(track, "Saturator"),
+            _set(track, "Drive", 3.0, "harmonic weight instead of gain"),
+            _set(track, "Dry/Wet", 35.0, "parallel amount"),
+        ]
+
+    if d.id == "over_limited":
+        return [
+            _probe(track, "Limiter"),
+            _set(track, "Gain", -2.5, "give the transients back 2.5 dB"),
+            _load(track, "Glue Compressor", "parallel glue on the drum bus, not the master"),
+            _probe(track, "Glue Compressor"),
+            _set(track, "Ratio", 4.0, "parallel crush setting"),
+            _set(track, "Attack", 30.0, "let the stick through before gain reduction"),
+            _set(track, "Release", 0.4, "follows the groove"),
+            _set(track, "Dry/Wet", 30.0, "parallel, keeps the original transient"),
+        ]
+
+    if d.id in ("mud", "hollow"):
+        gain = -abs(d.amount) if d.id == "mud" else 2.0
+        return [
+            _load(track, "EQ Eight", f"surgical work at {d.freq:.0f} Hz"),
+            _probe(track, "EQ Eight"),
+            _set(track, "2 Filter Type A", "Bell", "band 2 as a bell"),
+            _set(track, "2 Frequency A", round(d.freq, 1), f"centre on the problem at {d.freq:.0f} Hz"),
+            _set(track, "2 Gain A", round(gain, 1), d.headline),
+            _set(track, "2 Resonance A", 1.4 if d.id == "mud" else 0.7,
+                 "narrow to cut, wide to add"),
+        ]
+
+    if d.id == "harsh":
+        return [
+            _load(track, "Multiband Dynamics", "dynamic control at 3 kHz, not a static cut"),
+            _probe(track, "Multiband Dynamics"),
+            _set(track, "Low Crossover", 1500.0, "isolate 1.5–4k as the mid band"),
+            _set(track, "High Crossover", 4000.0, "isolate 1.5–4k as the mid band"),
+            _set(track, "Above Threshold (Mid)", -18.0, "engage only on peaks"),
+            _set(track, "Above Ratio (Mid)", 3.0, f"{d.amount:.1f} dB of movement at the top"),
+        ]
+
+    if d.id in ("dull", "brittle"):
+        gain = 2.0 if d.id == "dull" else -2.0
+        return [
+            _load(track, "EQ Eight", "high shelf"),
+            _probe(track, "EQ Eight"),
+            _set(track, "8 Filter Type A", "High Shelf", "band 8 as a shelf"),
+            _set(track, "8 Frequency A", round(d.freq, 1), f"shelf from {d.freq/1000:.0f} kHz up"),
+            _set(track, "8 Gain A", gain, d.headline),
+        ]
+
+    if d.id in ("stereo_sub", "out_of_phase"):
+        return [
+            _load(track, "Utility", "before the limiter, after everything else"),
+            _probe(track, "Utility"),
+            _set(track, "Bass Mono", 1, "collapse the low end to mono"),
+            _set(track, "Bass Mono Frequency", 120.0, "everything under 120 Hz centred"),
+        ]
+
+    if d.id == "sub_heavy":
+        return [
+            _load(track, "EQ Eight", "control the shelf under 60 Hz"),
+            _probe(track, "EQ Eight"),
+            _set(track, "1 Filter Type A", "High Pass 48", "steep high-pass"),
+            _set(track, "1 Frequency A", 29.0, "kill infrasonic energy the system cannot use"),
+            _set(track, "2 Filter Type A", "Low Shelf", "tame the remaining sub"),
+            _set(track, "2 Frequency A", 60.0, "shelf at the sub/bass boundary"),
+            _set(track, "2 Gain A", round(-abs(d.amount), 1), d.headline),
+        ]
+
+    if d.id == "no_sub":
+        return [
+            {"tool": "create_midi_track", "args": {"index": -1},
+             "why": "dedicated sub track — layering it on the bass channel means "
+                    "the sub inherits the bass processing, which is what killed it"},
+            _load("$NEW", "Operator", "single sine partial"),
+            _probe("$NEW", "Operator"),
+            _set("$NEW", "Oscillator A Coarse", 1, "fundamental only"),
+            _load("$NEW", "Utility", "force mono"),
+            _set("$NEW", "Width", 0.0, "sub is mono, always"),
+        ]
+
+    if d.id == "over_wide":
+        return [
+            _load(track, "Utility", "pull the image back in"),
+            _probe(track, "Utility"),
+            _set(track, "Width", 110.0, "down from whatever the widener is doing"),
+            _set(track, "Bass Mono", 1, "and keep the low end centred regardless"),
+        ]
+
+    if d.id == "narrow":
+        return [
+            _load(track, "Utility", "apply to reverb returns and pads, NOT bass or kick"),
+            _probe(track, "Utility"),
+            _set(track, "Width", 130.0, "widen only the elements that can afford it"),
+        ]
+
+    if d.id == "flat_drums":
+        return [
+            _load(track, "Drum Buss", "transient shaping plus drive in one device"),
+            _probe(track, "Drum Buss"),
+            _set(track, "Transients", 35.0, "bring the attack back"),
+            _set(track, "Drive", 15.0, "density without the limiter"),
+            _set(track, "Crunch", 10.0, "top-end bite"),
+        ]
+
+    if d.id == "sibilance":
+        return [
+            _load(track, "Multiband Dynamics", "de-ess band"),
+            _probe(track, "Multiband Dynamics"),
+            _set(track, "High Crossover", 6500.0, "isolate the sibilant band"),
+            _set(track, "Above Threshold (High)", -22.0, "catch only the esses"),
+            _set(track, "Above Ratio (High)", 4.0, "3 dB of range on peaks"),
+        ]
+
+    if d.id == "loud_range":
+        return [
+            _load(track, "Glue Compressor", "slow master glue"),
+            _probe(track, "Glue Compressor"),
+            _set(track, "Ratio", 2.0, "gentle"),
+            _set(track, "Attack", 30.0, "let transients through"),
+            _set(track, "Release", 0.6, "follows sections, not hits"),
+            _set(track, "Threshold", -14.0, "aim for 1–2 dB of gain reduction"),
+        ]
+
+    return None
+
+
+# --------------------------------------------------------------------------
+# plan assembly
+# --------------------------------------------------------------------------
+
+def build_plan(
+    diags: list[Diagnosis],
+    *,
+    track_index: Any = "$MASTER",
+    genre: str = "",
+    bpm: float = 0.0,
+    max_steps: int = 4,
+) -> dict:
+    """Turn the top diagnoses into an Ableton MCP call sequence."""
+    steps = []
+    for d in diags:
+        if d.severity == "good":
+            continue
+        calls = _recipe(d, track_index)
+        if not calls:
+            continue
+        steps.append({
+            "step": len(steps) + 1,
+            "severity": d.severity,
+            "intent": d.headline,
+            "evidence": d.evidence,
+            "expected_result": d.move,
+            "calls": calls,
+        })
+        if len(steps) >= max_steps:
+            break
+
+    preflight = [
+        {"tool": "get_session_info", "args": {},
+         "purpose": "confirm the set is reachable and read the track count"},
+        {"tool": "get_track_info", "args": {"track_index": track_index},
+         "purpose": "read the existing device chain so steps can be skipped "
+                    "when the device is already there"},
+    ]
+    if bpm > 0:
+        preflight.append({
+            "tool": "set_tempo", "args": {"tempo": round(bpm)},
+            "purpose": f"detected {bpm:.1f} BPM in the incoming audio",
+            "confirm_first": True,
+        })
+
+    return {
+        "target": {"track_index": track_index, "genre": genre},
+        "contract": (
+            "Execute against a locally connected Ableton MCP server. "
+            "$MASTER = the master track index, $LAST = the device index returned "
+            "by the preceding load call, $NEW = the track index returned by the "
+            "preceding create call. Run every get_device_parameters probe and "
+            "match parameter names by substring before calling "
+            "set_device_parameter — names differ across Live versions."
+        ),
+        "preflight": preflight,
+        "steps": steps,
+        "rollback": "Every step is additive. To undo, delete_device on the "
+                    "devices added by this plan, newest first.",
+    }
+
+
+def plan_to_markdown(plan: dict) -> str:
+    if not plan.get("steps"):
+        return "No corrective moves needed — nothing measurable is wrong."
+
+    lines = ["**Preflight**", ""]
+    for c in plan["preflight"]:
+        lines.append(f"- `{c['tool']}({json.dumps(c['args'])})` — {c['purpose']}")
+    lines.append("")
+
+    for step in plan["steps"]:
+        badge = {"critical": "🔴", "warn": "🟠", "note": "🔵"}.get(step["severity"], "·")
+        lines.append(f"**{badge} Step {step['step']} — {step['intent']}**")
+        lines.append("")
+        lines.append(f"> {step['evidence']}")
+        lines.append("")
+        for c in step["calls"]:
+            args = json.dumps(c["args"], ensure_ascii=False)
+            reason = c.get("why") or c.get("purpose") or c.get("note") or ""
+            lines.append(f"- `{c['tool']}({args})`" + (f" — {reason}" if reason else ""))
+        lines.append("")
+        lines.append(f"*What you should hear:* {step['expected_result']}")
+        lines.append("")
+
+    return "\n".join(lines)

ear/dsp.py

@@ -0,0 +1,435 @@
+"""Measurement layer.
+
+Pure numpy/scipy. No librosa — import cost and CPU headroom matter on a
+2-vCPU Space where this runs several times a second on a live stream.
+
+Everything is measured at 48 kHz. Input at any rate is resampled once on
+the way in, so the K-weighting biquads (which are rate-specific) stay valid
+and every metric is comparable across sources.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+
+import numpy as np
+from scipy.signal import lfilter, resample_poly, get_window
+
+SR = 48_000
+
+# Band edges in Hz. Seven bands, chosen to match how engineers actually talk
+# about a mix rather than to divide the spectrum evenly.
+BANDS: dict[str, tuple[float, float]] = {
+    "sub": (20.0, 60.0),
+    "bass": (60.0, 120.0),
+    "lowmid": (120.0, 350.0),
+    "mid": (350.0, 1500.0),
+    "himid": (1500.0, 4000.0),
+    "presence": (4000.0, 8000.0),
+    "air": (8000.0, 16000.0),
+}
+BAND_ORDER = list(BANDS.keys())
+
+BAND_LABELS = {
+    "sub": "Sub 20–60",
+    "bass": "Bass 60–120",
+    "lowmid": "Low mid 120–350",
+    "mid": "Mid 350–1.5k",
+    "himid": "Hi mid 1.5–4k",
+    "presence": "Presence 4–8k",
+    "air": "Air 8–16k",
+}
+
+# ITU-R BS.1770-4 K-weighting, 48 kHz.
+_K1_B = np.array([1.53512485958697, -2.69169618940638, 1.19839281085285])
+_K1_A = np.array([1.0, -1.69065929318241, 0.73248077421585])
+_K2_B = np.array([1.0, -2.0, 1.0])
+_K2_A = np.array([1.0, -1.99004745483398, 0.99007225036621])
+
+_KRUMHANSL_MAJOR = np.array(
+    [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88]
+)
+_KRUMHANSL_MINOR = np.array(
+    [6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17]
+)
+_NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+
+_EPS = 1e-12
+
+
+def _db(x: float) -> float:
+    return 20.0 * math.log10(max(float(x), _EPS))
+
+
+def _pdb(p: float) -> float:
+    """Power (already squared) to dB."""
+    return 10.0 * math.log10(max(float(p), _EPS))
+
+
+# --------------------------------------------------------------------------
+# input conditioning
+# --------------------------------------------------------------------------
+
+def to_float_stereo(sr: int, data: np.ndarray) -> np.ndarray:
+    """Normalise any Gradio audio payload to float32 (n, 2) at 48 kHz."""
+    x = np.asarray(data)
+    if x.dtype.kind in "iu":
+        info = np.iinfo(x.dtype)
+        x = x.astype(np.float32) / max(abs(info.min), info.max)
+    else:
+        x = x.astype(np.float32, copy=False)
+
+    if x.ndim == 1:
+        x = x[:, None]
+    if x.shape[1] > 2:  # some capture paths hand back (channels, n)
+        if x.shape[0] <= 2:
+            x = x.T
+        else:
+            x = x[:, :2]
+    if x.shape[1] == 1:
+        x = np.repeat(x, 2, axis=1)
+
+    if sr != SR and x.shape[0] > 0:
+        g = math.gcd(int(sr), SR)
+        x = resample_poly(x, SR // g, int(sr) // g, axis=0).astype(np.float32)
+
+    return np.nan_to_num(x, nan=0.0, posinf=0.0, neginf=0.0)
+
+
+# --------------------------------------------------------------------------
+# loudness
+# --------------------------------------------------------------------------
+
+def _k_weight(x: np.ndarray) -> np.ndarray:
+    y = lfilter(_K1_B, _K1_A, x, axis=0)
+    return lfilter(_K2_B, _K2_A, y, axis=0)
+
+
+def _block_loudness(xk: np.ndarray, win: int, hop: int) -> np.ndarray:
+    """Per-block BS.1770 loudness in LKFS for a K-weighted signal."""
+    n = xk.shape[0]
+    if n < win:
+        if n == 0:
+            return np.array([])
+        mean_sq = np.mean(xk**2, axis=0).sum()
+        return np.array([-0.691 + _pdb(mean_sq)])
+    starts = np.arange(0, n - win + 1, hop)
+    out = np.empty(len(starts), dtype=np.float64)
+    for i, s in enumerate(starts):
+        blk = xk[s : s + win]
+        out[i] = -0.691 + _pdb(np.mean(blk**2, axis=0).sum())
+    return out
+
+
+def loudness(x: np.ndarray) -> dict:
+    """Integrated / short-term / range loudness, gated per BS.1770-4."""
+    xk = _k_weight(x)
+    blocks = _block_loudness(xk, int(0.400 * SR), int(0.100 * SR))
+    short = _block_loudness(xk, int(3.0 * SR), int(1.0 * SR))
+
+    lufs_i = float("-inf")
+    if blocks.size:
+        above_abs = blocks[blocks > -70.0]
+        if above_abs.size:
+            mean_pow = np.mean(10 ** (above_abs / 10.0))
+            rel_gate = 10.0 * math.log10(max(mean_pow, _EPS)) - 10.0
+            kept = above_abs[above_abs > rel_gate]
+            pool = kept if kept.size else above_abs
+            lufs_i = float(10.0 * math.log10(max(np.mean(10 ** (pool / 10.0)), _EPS)))
+
+    lra = 0.0
+    if short.size >= 3:
+        valid = short[short > -70.0]
+        if valid.size >= 3:
+            lra = float(np.percentile(valid, 95) - np.percentile(valid, 10))
+
+    return {
+        "lufs_i": lufs_i,
+        "lufs_s": float(short[-1]) if short.size else float("-inf"),
+        "lra": lra,
+        "short_term": short,
+    }
+
+
+def true_peak_db(x: np.ndarray) -> float:
+    """dBTP via 4x oversampling (BS.1770 minimum)."""
+    if x.shape[0] < 8:
+        return _db(np.max(np.abs(x)) if x.size else 0.0)
+    up = resample_poly(x, 4, 1, axis=0)
+    return _db(float(np.max(np.abs(up))))
+
+
+# --------------------------------------------------------------------------
+# spectrum
+# --------------------------------------------------------------------------
+
+def spectrum(mono: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Averaged power spectrum via Welch-style overlapping Hann frames."""
+    n = mono.shape[0]
+    nfft = 8192 if n >= 8192 else 1 << max(8, int(math.log2(max(n, 256))))
+    if n < nfft:
+        mono = np.pad(mono, (0, nfft - n))
+        n = nfft
+    win = get_window("hann", nfft, fftbins=True)
+    hop = nfft // 2
+    acc = np.zeros(nfft // 2 + 1)
+    count = 0
+    for s in range(0, n - nfft + 1, hop):
+        frame = mono[s : s + nfft] * win
+        acc += np.abs(np.fft.rfft(frame)) ** 2
+        count += 1
+    if count:
+        acc /= count
+    freqs = np.fft.rfftfreq(nfft, 1.0 / SR)
+    return freqs, acc
+
+
+def band_energies(freqs: np.ndarray, power: np.ndarray) -> dict[str, float]:
+    """Band power as dB relative to total 20 Hz–20 kHz power."""
+    full = (freqs >= 20.0) & (freqs <= 20000.0)
+    total = float(power[full].sum())
+    out = {}
+    for name, (lo, hi) in BANDS.items():
+        sel = (freqs >= lo) & (freqs < hi)
+        out[name] = _pdb(float(power[sel].sum()) / max(total, _EPS))
+    return out
+
+
+def spectral_shape(freqs: np.ndarray, power: np.ndarray) -> dict:
+    sel = (freqs >= 40.0) & (freqs <= 16000.0)
+    f, p = freqs[sel], power[sel]
+    if not f.size or p.sum() <= _EPS:
+        return {"centroid": 0.0, "tilt": 0.0, "rolloff85": 0.0, "flatness": 0.0}
+
+    centroid = float((f * p).sum() / p.sum())
+
+    # dB/octave tilt: least-squares fit of level against log2(frequency).
+    logf = np.log2(f)
+    logp = 10.0 * np.log10(np.maximum(p, _EPS))
+    tilt = float(np.polyfit(logf, logp, 1)[0])
+
+    csum = np.cumsum(p)
+    rolloff = float(f[min(int(np.searchsorted(csum, 0.85 * csum[-1])), f.size - 1)])
+
+    gmean = float(np.exp(np.mean(np.log(np.maximum(p, _EPS)))))
+    flatness = gmean / float(np.mean(p) + _EPS)
+
+    return {
+        "centroid": centroid,
+        "tilt": tilt,
+        "rolloff85": rolloff,
+        "flatness": float(flatness),
+    }
+
+
+# --------------------------------------------------------------------------
+# stereo
+# --------------------------------------------------------------------------
+
+def stereo_image(x: np.ndarray) -> dict:
+    left, right = x[:, 0], x[:, 1]
+    denom = math.sqrt(float(np.mean(left**2)) * float(np.mean(right**2))) + _EPS
+    corr = float(np.mean(left * right) / denom)
+
+    mid = (left + right) * 0.5
+    side = (left - right) * 0.5
+    mid_p = float(np.mean(mid**2))
+    side_p = float(np.mean(side**2))
+    width = _pdb(side_p / max(mid_p, _EPS))
+
+    # Mono-fold penalty: how much level is lost summing to mono.
+    stereo_p = float(np.mean(x**2))
+    mono_loss = _pdb(mid_p / max(stereo_p, _EPS))
+
+    # Low-frequency correlation is the one that actually costs you on a
+    # club system, so it gets measured separately.
+    sub_corr = corr
+    if x.shape[0] > 4096:
+        nfft = 4096
+        w = get_window("hann", nfft)
+        bins = np.fft.rfftfreq(nfft, 1.0 / SR)
+        m = (bins >= 20) & (bins < 120)
+        limit = min(x.shape[0] - nfft, 24 * nfft)
+        acc_l = acc_r = acc_lr = 0.0
+        for s in range(0, max(limit, 1), nfft // 2):
+            fl = np.fft.rfft(left[s : s + nfft] * w)
+            fr = np.fft.rfft(right[s : s + nfft] * w)
+            acc_l += float(np.sum(np.abs(fl[m]) ** 2))
+            acc_r += float(np.sum(np.abs(fr[m]) ** 2))
+            acc_lr += float(np.real(np.sum(fl[m] * np.conj(fr[m]))))
+        d = math.sqrt(acc_l * acc_r) + _EPS
+        sub_corr = float(acc_lr / d)
+
+    return {
+        "correlation": corr,
+        "sub_correlation": sub_corr,
+        "width_db": width,
+        "mono_loss_db": mono_loss,
+    }
+
+
+# --------------------------------------------------------------------------
+# rhythm + pitch
+# --------------------------------------------------------------------------
+
+def onset_envelope(mono: np.ndarray) -> tuple[np.ndarray, float]:
+    nfft, hop = 2048, 512
+    if mono.shape[0] < nfft * 4:
+        return np.zeros(0), SR / hop
+    win = get_window("hann", nfft)
+    n_frames = 1 + (mono.shape[0] - nfft) // hop
+    mags = np.empty((n_frames, nfft // 2 + 1), dtype=np.float32)
+    for i in range(n_frames):
+        s = i * hop
+        mags[i] = np.abs(np.fft.rfft(mono[s : s + nfft] * win))
+    logm = np.log1p(mags * 100.0)
+    flux = np.maximum(np.diff(logm, axis=0), 0.0).sum(axis=1)
+    if flux.size and flux.max() > 0:
+        flux = flux / flux.max()
+    return flux, SR / hop
+
+
+def tempo_from_onsets(flux: np.ndarray, fps: float) -> dict:
+    if flux.size < 64:
+        return {"bpm": 0.0, "confidence": 0.0, "onset_rate": 0.0}
+
+    env = flux - flux.mean()
+    ac = np.correlate(env, env, mode="full")[env.size - 1 :]
+    if ac[0] > 0:
+        ac = ac / ac[0]
+
+    lag_min = max(int(fps * 60.0 / 200.0), 2)
+    lag_max = min(int(fps * 60.0 / 60.0), ac.size - 1)
+    if lag_max <= lag_min:
+        return {"bpm": 0.0, "confidence": 0.0, "onset_rate": 0.0}
+
+    window = ac[lag_min:lag_max]
+    best = int(np.argmax(window)) + lag_min
+    conf = float(max(window.max(), 0.0))
+    bpm = 60.0 * fps / best
+
+    # Octave correction — autocorrelation happily locks onto half or double.
+    while bpm < 70.0:
+        bpm *= 2.0
+    while bpm > 190.0:
+        bpm /= 2.0
+
+    thresh = flux.mean() + flux.std()
+    peaks = (flux[1:-1] > thresh) & (flux[1:-1] > flux[:-2]) & (flux[1:-1] >= flux[2:])
+    onset_rate = int(np.sum(peaks)) / (flux.size / fps) if flux.size else 0.0
+
+    return {"bpm": float(bpm), "confidence": conf, "onset_rate": float(onset_rate)}
+
+
+def key_estimate(freqs: np.ndarray, power: np.ndarray) -> dict:
+    sel = (freqs >= 55.0) & (freqs <= 2200.0)
+    f, p = freqs[sel], power[sel]
+    if not f.size or p.sum() <= _EPS:
+        return {"key": "—", "confidence": 0.0}
+
+    midi = 69.0 + 12.0 * np.log2(f / 440.0)
+    pc = np.mod(np.round(midi).astype(int), 12)
+    chroma = np.zeros(12)
+    np.add.at(chroma, pc, np.sqrt(p))
+    if chroma.sum() <= _EPS:
+        return {"key": "—", "confidence": 0.0}
+    chroma = chroma / chroma.sum()
+
+    scored: list[tuple[float, str]] = []
+    for root in range(12):
+        rotated = np.roll(chroma, -root)
+        for profile, quality in ((_KRUMHANSL_MAJOR, ""), (_KRUMHANSL_MINOR, "m")):
+            prof = profile / profile.sum()
+            if np.std(rotated) < _EPS:
+                continue
+            score = float(np.corrcoef(rotated, prof)[0, 1])
+            scored.append((score, f"{_NOTE_NAMES[root]}{quality}"))
+
+    if not scored:
+        return {"key": "—", "confidence": 0.0}
+    scored.sort(reverse=True)
+    margin = scored[0][0] - (scored[1][0] if len(scored) > 1 else 0.0)
+    return {"key": scored[0][1], "confidence": float(max(0.0, margin))}
+
+
+# --------------------------------------------------------------------------
+# top-level report
+# --------------------------------------------------------------------------
+
+@dataclass
+class Report:
+    duration: float = 0.0
+    lufs_i: float = float("-inf")
+    lufs_s: float = float("-inf")
+    lra: float = 0.0
+    true_peak: float = -120.0
+    sample_peak: float = -120.0
+    rms: float = -120.0
+    crest: float = 0.0
+    psr: float = 0.0
+    bands: dict = field(default_factory=dict)
+    ratios: dict = field(default_factory=dict)
+    shape: dict = field(default_factory=dict)
+    stereo: dict = field(default_factory=dict)
+    rhythm: dict = field(default_factory=dict)
+    key: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        for k, v in list(d.items()):
+            if isinstance(v, float) and math.isinf(v):
+                d[k] = -120.0
+        return d
+
+
+def analyze(sr: int, data: np.ndarray, *, fast: bool = False) -> Optional[Report]:
+    """Full measurement pass. `fast=True` skips tempo/key for the live loop."""
+    x = to_float_stereo(sr, data)
+    if x.shape[0] < SR // 20:
+        return None
+
+    mono = x.mean(axis=1)
+    rms = float(np.sqrt(np.mean(mono**2)))
+    sample_peak = float(np.max(np.abs(x)))
+
+    loud = loudness(x)
+    freqs, power = spectrum(mono)
+    bands = band_energies(freqs, power)
+
+    rep = Report(
+        duration=x.shape[0] / SR,
+        lufs_i=loud["lufs_i"],
+        lufs_s=loud["lufs_s"],
+        lra=loud["lra"],
+        true_peak=true_peak_db(x) if not fast else _db(sample_peak),
+        sample_peak=_db(sample_peak),
+        rms=_db(rms),
+        crest=_db(sample_peak) - _db(rms),
+        bands=bands,
+        shape=spectral_shape(freqs, power),
+        stereo=stereo_image(x),
+    )
+
+    # Peak-to-short-term-loudness ratio: the "is it still punchy" number.
+    if loud["short_term"].size and math.isfinite(rep.true_peak):
+        rep.psr = float(rep.true_peak - float(loud["short_term"][-1]))
+
+    rep.ratios = {
+        "sub_vs_bass": bands["sub"] - bands["bass"],
+        "mud": bands["lowmid"] - bands["mid"],
+        "harsh": bands["himid"] - bands["mid"],
+        "air": bands["air"] - bands["mid"],
+        "tilt_low_high": (bands["sub"] + bands["bass"]) - (bands["presence"] + bands["air"]),
+    }
+
+    if not fast:
+        flux, fps = onset_envelope(mono)
+        rep.rhythm = tempo_from_onsets(flux, fps)
+        rep.key = key_estimate(freqs, power)
+    else:
+        rep.rhythm = {"bpm": 0.0, "confidence": 0.0, "onset_rate": 0.0}
+        rep.key = {"key": "—", "confidence": 0.0}
+
+    return rep

ear/knowledge.py

@@ -0,0 +1,486 @@
+"""The opinionated part.
+
+Measurements are neutral; this module is where the taste lives. Each rule
+turns a number into a diagnosis with a *reason* and a *move*, scoped to what
+the material is supposed to be (a master behaves nothing like a solo'd sub).
+
+Targets are expressed as ratios between bands wherever possible. Absolute
+band fractions drift with arrangement density; ratios like "low mid against
+mid" survive it and are closer to how an engineer actually judges a balance.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict, field
+
+from . import dsp
+
+# --------------------------------------------------------------------------
+# context profiles
+# --------------------------------------------------------------------------
+
+@dataclass
+class Profile:
+    name: str
+    lufs: tuple[float, float]
+    crest: tuple[float, float]
+    sub_vs_bass: tuple[float, float]
+    mud: tuple[float, float]
+    harsh: tuple[float, float]
+    air: tuple[float, float]
+    tilt: tuple[float, float]
+    width: tuple[float, float]
+    bpm_hint: str
+    voice: str
+
+
+GENRES: dict[str, Profile] = {
+    "Dubstep / Riddim": Profile(
+        "Dubstep / Riddim",
+        lufs=(-9.0, -5.0), crest=(6.0, 11.0),
+        sub_vs_bass=(-4.0, 2.0), mud=(-5.0, 0.0), harsh=(-6.0, -1.0),
+        air=(-14.0, -6.0), tilt=(2.0, 14.0), width=(-14.0, -4.0),
+        bpm_hint="140 / 150 (half-time feel at 70–75)",
+        voice="Sub weight and mid aggression are the product. Protect the "
+              "20–60 Hz shelf, keep it mono, and make room at 200–400 Hz so "
+              "the growls read as bite instead of mud.",
+    ),
+    "Melodic Dubstep / Future Bass": Profile(
+        "Melodic Dubstep / Future Bass",
+        lufs=(-10.0, -6.0), crest=(7.0, 12.0),
+        sub_vs_bass=(-5.0, 1.0), mud=(-6.0, -1.0), harsh=(-5.0, 0.0),
+        air=(-11.0, -4.0), tilt=(-1.0, 9.0), width=(-11.0, -2.0),
+        bpm_hint="140–150",
+        voice="Wide, bright and emotional — but the chord stack is the usual "
+              "mud source. Keep supersaws high-passed and let the sub own "
+              "everything under 80 Hz alone.",
+    ),
+    "Drum & Bass": Profile(
+        "Drum & Bass",
+        lufs=(-9.0, -5.0), crest=(7.0, 12.0),
+        sub_vs_bass=(-3.0, 3.0), mud=(-6.0, -1.0), harsh=(-5.0, 0.0),
+        air=(-12.0, -5.0), tilt=(1.0, 12.0), width=(-13.0, -4.0),
+        bpm_hint="172–176",
+        voice="Breaks need transient survival. Watch crest — if it drops "
+              "under 7 dB the drums stop moving air even though the meter "
+              "says loud.",
+    ),
+    "House / Techno": Profile(
+        "House / Techno",
+        lufs=(-10.0, -6.0), crest=(7.0, 12.0),
+        sub_vs_bass=(-6.0, 0.0), mud=(-6.0, -1.0), harsh=(-6.0, -1.0),
+        air=(-12.0, -5.0), tilt=(0.0, 10.0), width=(-13.0, -4.0),
+        bpm_hint="120–135",
+        voice="The kick is the anchor. Everything else earns its place around "
+              "it; sidechain depth matters more than EQ here.",
+    ),
+    "Trap / Hip-Hop": Profile(
+        "Trap / Hip-Hop",
+        lufs=(-10.0, -6.0), crest=(7.0, 13.0),
+        sub_vs_bass=(-2.0, 5.0), mud=(-6.0, -1.0), harsh=(-6.0, -1.0),
+        air=(-13.0, -5.0), tilt=(3.0, 15.0), width=(-16.0, -5.0),
+        bpm_hint="130–150 (half-time 65–75)",
+        voice="808 and vocal are the two things that must never fight. If "
+              "they share 100–250 Hz, one of them has to move.",
+    ),
+    "Pop / Vocal-led": Profile(
+        "Pop / Vocal-led",
+        lufs=(-11.0, -7.0), crest=(8.0, 13.0),
+        sub_vs_bass=(-8.0, -1.0), mud=(-7.0, -2.0), harsh=(-4.0, 1.0),
+        air=(-10.0, -3.0), tilt=(-4.0, 6.0), width=(-12.0, -3.0),
+        bpm_hint="90–130",
+        voice="The vocal is the mix. Every decision is 'does this help the "
+              "voice sit forward without getting harsh at 3 kHz'.",
+    ),
+    "Ambient / Cinematic": Profile(
+        "Ambient / Cinematic",
+        lufs=(-20.0, -13.0), crest=(11.0, 22.0),
+        sub_vs_bass=(-8.0, 2.0), mud=(-6.0, 0.0), harsh=(-8.0, -2.0),
+        air=(-12.0, -3.0), tilt=(-4.0, 8.0), width=(-9.0, 0.0),
+        bpm_hint="free / rubato",
+        voice="Dynamic range is the point. Loudness rules invert here — a "
+              "high LRA is a feature, not a fault.",
+    ),
+    "Reference master (streaming)": Profile(
+        "Reference master (streaming)",
+        lufs=(-15.0, -12.0), crest=(8.0, 14.0),
+        sub_vs_bass=(-7.0, 0.0), mud=(-6.0, -1.0), harsh=(-5.0, 0.0),
+        air=(-12.0, -4.0), tilt=(-2.0, 8.0), width=(-12.0, -3.0),
+        bpm_hint="—",
+        voice="Targets Spotify/Apple normalisation. Anything louder than "
+              "-12 LUFS just gets turned down with the transients already "
+              "spent.",
+    ),
+}
+
+# What is being listened to. Changes which rules are even allowed to fire.
+SOURCES = [
+    "Full mix / master",
+    "Drum bus",
+    "Bass / 808",
+    "Lead / synth",
+    "Vocal",
+    "Pad / atmosphere",
+]
+
+_SEVERITY_RANK = {"critical": 0, "warn": 1, "note": 2, "good": 3}
+
+
+@dataclass
+class Diagnosis:
+    id: str
+    severity: str          # critical | warn | note | good
+    headline: str
+    evidence: str
+    why: str
+    move: str
+    band: str = ""
+    freq: float = 0.0
+    amount: float = 0.0
+    tags: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _below(value: float, window: tuple[float, float]) -> float:
+    return window[0] - value
+
+
+def _above(value: float, window: tuple[float, float]) -> float:
+    return value - window[1]
+
+
+# --------------------------------------------------------------------------
+# rules
+# --------------------------------------------------------------------------
+
+def diagnose(rep: dsp.Report, genre: str, source: str) -> list[Diagnosis]:
+    p = GENRES.get(genre, GENRES["Dubstep / Riddim"])
+    out: list[Diagnosis] = []
+    is_master = source == "Full mix / master"
+    r = rep.ratios
+    st = rep.stereo
+
+    # -- headroom -----------------------------------------------------------
+    if rep.true_peak > 0.0:
+        out.append(Diagnosis(
+            "clipping", "critical",
+            f"Clipping at {rep.true_peak:+.1f} dBTP",
+            f"True peak {rep.true_peak:+.2f} dBTP, sample peak {rep.sample_peak:+.2f} dBFS",
+            "Inter-sample peaks above 0 dBTP distort in every lossy encoder even "
+            "when the file itself looks clean. Spotify and YouTube both "
+            "reconstruct those peaks and clip them.",
+            "Pull the master output down until true peak lands at -1.0 dBTP. If "
+            "that costs you loudness, take it out of the limiter's ceiling, not "
+            "the mix gain.",
+            tags=["headroom"],
+        ))
+    elif rep.true_peak > -0.3:
+        out.append(Diagnosis(
+            "no_headroom", "warn",
+            f"Only {abs(rep.true_peak):.1f} dB of true-peak headroom",
+            f"True peak {rep.true_peak:+.2f} dBTP",
+            "Anything above -1 dBTP is a coin flip after MP3/AAC encoding.",
+            "Set the limiter ceiling to -1.0 dBTP and leave it there.",
+            tags=["headroom"],
+        ))
+
+    # -- loudness -----------------------------------------------------------
+    if rep.lufs_i > -60.0 and rep.duration > 3.0:
+        over = _above(rep.lufs_i, p.lufs)
+        under = _below(rep.lufs_i, p.lufs)
+        if over > 1.5 and is_master:
+            out.append(Diagnosis(
+                "too_loud", "warn",
+                f"Pushed {over:.1f} LU past the {p.name} window",
+                f"Integrated {rep.lufs_i:.1f} LUFS vs target {p.lufs[0]:.0f}…{p.lufs[1]:.0f}",
+                "Streaming platforms normalise down to roughly -14 LUFS. Loudness "
+                "above the target does not get louder on playback — it only "
+                "arrives with less transient left.",
+                f"Back the limiter off by {over:.1f} dB and recover the "
+                "perceived weight with saturation on the low mids instead.",
+                amount=over, tags=["loudness"],
+            ))
+        elif under > 3.0 and is_master:
+            out.append(Diagnosis(
+                "too_quiet", "note",
+                f"{under:.1f} LU under the {p.name} window",
+                f"Integrated {rep.lufs_i:.1f} LUFS vs target {p.lufs[0]:.0f}…{p.lufs[1]:.0f}",
+                "Not a problem in itself, but it will feel small next to "
+                "references in a playlist.",
+                "Add gain into the limiter in 1 dB steps and stop the moment "
+                "crest factor drops below the genre floor.",
+                amount=under, tags=["loudness"],
+            ))
+
+    # -- dynamics -----------------------------------------------------------
+    if rep.duration > 2.0:
+        if rep.crest < p.crest[0] - 1.0:
+            out.append(Diagnosis(
+                "over_limited", "critical" if rep.crest < p.crest[0] - 3 else "warn",
+                f"Crest factor {rep.crest:.1f} dB — the transients are gone",
+                f"Peak-to-RMS {rep.crest:.1f} dB, PSR {rep.psr:.1f} dB, "
+                f"target {p.crest[0]:.0f}…{p.crest[1]:.0f} dB",
+                "Under roughly 6 dB of crest the drums stop reading as hits and "
+                "start reading as level. This is the single most common way a "
+                "loud master ends up sounding smaller than a quiet one.",
+                "Take 2–3 dB off the limiter, then reclaim density with parallel "
+                "compression on the drum bus rather than more ceiling.",
+                amount=p.crest[0] - rep.crest, tags=["dynamics"],
+            ))
+        elif rep.crest > p.crest[1] + 3.0 and is_master:
+            out.append(Diagnosis(
+                "uncontrolled", "note",
+                f"Crest factor {rep.crest:.1f} dB — peaks are running free",
+                f"Peak-to-RMS {rep.crest:.1f} dB vs target {p.crest[0]:.0f}…{p.crest[1]:.0f}",
+                "A few isolated peaks are eating all the headroom, so the body "
+                "of the track sits far lower than it could.",
+                "Clip or soft-limit the worst transients before the bus "
+                "compressor so the compressor stops chasing them.",
+                tags=["dynamics"],
+            ))
+
+        if rep.lra > 12.0 and is_master and genre != "Ambient / Cinematic":
+            out.append(Diagnosis(
+                "loud_range", "note",
+                f"Loudness range {rep.lra:.1f} LU — sections are uneven",
+                f"LRA {rep.lra:.1f} LU",
+                "Large section-to-section swings make club or car playback "
+                "feel like it keeps changing volume.",
+                "Automate section gain before the bus, or set a slow 1.5:1 "
+                "compressor across the master to glue the arrangement.",
+                tags=["dynamics"],
+            ))
+
+    # -- low end ------------------------------------------------------------
+    sub_vs_bass = r.get("sub_vs_bass", 0.0)
+    if _above(sub_vs_bass, p.sub_vs_bass) > 2.0:
+        amt = _above(sub_vs_bass, p.sub_vs_bass)
+        out.append(Diagnosis(
+            "sub_heavy", "warn",
+            f"Sub is {amt:.1f} dB hotter than it should be",
+            f"20–60 Hz sits {sub_vs_bass:+.1f} dB against 60–120 Hz "
+            f"(target {p.sub_vs_bass[0]:+.0f}…{p.sub_vs_bass[1]:+.0f})",
+            "Energy this low is felt, not heard. On laptop and phone speakers "
+            "it vanishes entirely, so the track reads thin there while eating "
+            "all the limiter's work on a big system.",
+            f"High-pass the sub at 28–30 Hz and shelve 20–60 Hz down {amt:.1f} dB. "
+            "Check it on a phone speaker before trusting the change.",
+            band="sub", freq=45.0, amount=amt, tags=["lowend"],
+        ))
+    elif _below(sub_vs_bass, p.sub_vs_bass) > 3.0 and is_master:
+        out.append(Diagnosis(
+            "no_sub", "warn",
+            "No real sub under the track",
+            f"20–60 Hz sits {sub_vs_bass:+.1f} dB against 60–120 Hz "
+            f"(target {p.sub_vs_bass[0]:+.0f}…{p.sub_vs_bass[1]:+.0f})",
+            "The weight you are hearing is all upper bass. It will feel "
+            "adequate on monitors and completely gutless on a club rig.",
+            "Layer a clean sine sub an octave under the bass, mono, and "
+            "sidechain it hard to the kick.",
+            band="sub", freq=45.0, tags=["lowend"],
+        ))
+
+    # -- mud / boxiness -----------------------------------------------------
+    mud = r.get("mud", 0.0)
+    mud_over = _above(mud, p.mud)
+    if mud_over > 1.0:
+        sev = "critical" if mud_over > 4.0 else "warn"
+        out.append(Diagnosis(
+            "mud", sev,
+            f"Low mids are {mud_over:.1f} dB thick",
+            f"120–350 Hz sits {mud:+.1f} dB against 350 Hz–1.5 kHz "
+            f"(target {p.mud[0]:+.0f}…{p.mud[1]:+.0f})",
+            "This is the band every instrument has energy in and nobody needs. "
+            "It builds up silently across a layered arrangement and eats the "
+            "clarity of everything above it.",
+            f"Narrow bell cut of {min(mud_over, 5.0):.1f} dB at 250 Hz "
+            "(Q ≈ 1.4) on the offending bus. If the cut makes the track thin, "
+            "the problem is the arrangement, not the EQ — mute layers until "
+            "you find which one owns 250 Hz.",
+            band="lowmid", freq=250.0, amount=min(mud_over, 5.0),
+            tags=["mud", "clarity"],
+        ))
+    elif _below(mud, p.mud) > 3.0:
+        out.append(Diagnosis(
+            "hollow", "note",
+            "Scooped low mids — sounds hi-fi, plays thin",
+            f"120–350 Hz sits {mud:+.1f} dB against the mids "
+            f"(target {p.mud[0]:+.0f}…{p.mud[1]:+.0f})",
+            "Over-cutting 200–400 Hz is the classic overcorrection. It sounds "
+            "clean in isolation and disappears in a mix or a playlist.",
+            "Give 2 dB back with a wide bell at 220 Hz (Q ≈ 0.7).",
+            band="lowmid", freq=220.0, tags=["clarity"],
+        ))
+
+    # -- harshness / dullness ----------------------------------------------
+    harsh = r.get("harsh", 0.0)
+    if _above(harsh, p.harsh) > 1.5:
+        amt = min(_above(harsh, p.harsh), 4.0)
+        out.append(Diagnosis(
+            "harsh", "warn",
+            f"Upper mids {_above(harsh, p.harsh):.1f} dB hot — this will fatigue",
+            f"1.5–4 kHz sits {harsh:+.1f} dB against the mids "
+            f"(target {p.harsh[0]:+.0f}…{p.harsh[1]:+.0f})",
+            "The ear is most sensitive right here. Excess reads as 'loud and "
+            "exciting' for thirty seconds and as 'painful' for three minutes.",
+            f"Dynamic EQ at 3 kHz, {amt:.1f} dB of downward movement, only when "
+            "it crosses threshold — a static cut here kills presence.",
+            band="himid", freq=3000.0, amount=amt, tags=["harsh", "tone"],
+        ))
+
+    air = r.get("air", 0.0)
+    if _below(air, p.air) > 3.0:
+        out.append(Diagnosis(
+            "dull", "note",
+            "Top end is closed in",
+            f"8–16 kHz sits {air:+.1f} dB against the mids "
+            f"(target {p.air[0]:+.0f}…{p.air[1]:+.0f})",
+            "Nothing above 8 kHz means no sense of air or space, which usually "
+            "reads to listeners as 'demo' rather than 'dark'.",
+            "High shelf +2 dB at 10 kHz. If it turns harsh instead of open, "
+            "the top end is distortion artefacts, not content — fix the source.",
+            band="air", freq=10000.0, tags=["tone"],
+        ))
+    elif _above(air, p.air) > 3.0:
+        out.append(Diagnosis(
+            "brittle", "warn",
+            "Top end is brittle",
+            f"8–16 kHz sits {air:+.1f} dB against the mids "
+            f"(target {p.air[0]:+.0f}…{p.air[1]:+.0f})",
+            "Usually the fingerprint of an exciter or aggressive limiting "
+            "rather than real content.",
+            "High shelf -2 dB at 9 kHz and back off whatever is generating it.",
+            band="air", freq=9000.0, tags=["tone"],
+        ))
+
+    # -- stereo -------------------------------------------------------------
+    corr = st.get("correlation", 1.0)
+    sub_corr = st.get("sub_correlation", 1.0)
+    if corr < -0.1:
+        out.append(Diagnosis(
+            "out_of_phase", "critical",
+            f"Phase correlation {corr:+.2f} — this cancels in mono",
+            f"L/R correlation {corr:+.2f}, mono fold loses "
+            f"{abs(st.get('mono_loss_db', 0.0)):.1f} dB",
+            "Negative correlation means the channels fight each other. Any mono "
+            "playback — club sub, phone, most PA systems — loses that material.",
+            "Find the widener or the inverted duplicate causing it. Check every "
+            "stereo effect's phase before reaching for a corrector.",
+            tags=["stereo", "phase"],
+        ))
+    if sub_corr < 0.85:
+        out.append(Diagnosis(
+            "stereo_sub", "critical" if sub_corr < 0.6 else "warn",
+            f"Low end is not mono (correlation {sub_corr:+.2f} below 120 Hz)",
+            f"20–120 Hz correlation {sub_corr:+.2f}",
+            "Stereo information below 120 Hz cancels unpredictably on club "
+            "systems and wastes cutter headroom on vinyl. There is no upside.",
+            "Utility with Bass Mono engaged at 120 Hz, before the limiter.",
+            band="sub", freq=120.0, tags=["stereo", "phase", "lowend"],
+        ))
+    width = st.get("width_db", -12.0)
+    if _below(width, p.width) > 4.0 and is_master:
+        out.append(Diagnosis(
+            "narrow", "note",
+            "Image is narrow",
+            f"Side/mid ratio {width:+.1f} dB (target {p.width[0]:+.0f}…{p.width[1]:+.0f})",
+            "Almost everything is centred, so the mix has no depth to move "
+            "into when the drop hits.",
+            "Widen the elements that can afford it — reverb returns, pads, hat "
+            "layers — not the bass and not the kick.",
+            tags=["stereo"],
+        ))
+    elif _above(width, p.width) > 4.0:
+        out.append(Diagnosis(
+            "over_wide", "warn",
+            "Over-widened",
+            f"Side/mid ratio {width:+.1f} dB (target {p.width[0]:+.0f}…{p.width[1]:+.0f})",
+            "More side energy than mid means the centre is hollow and the mono "
+            "fold will be a different mix entirely.",
+            "Pull the widener back and check the mono fold before committing.",
+            tags=["stereo"],
+        ))
+
+    # -- source-specific ----------------------------------------------------
+    if source == "Bass / 808" and rep.bands.get("air", -99.0) > -12.0:
+        out.append(Diagnosis(
+            "bass_top", "note",
+            "Bass is carrying a lot of top end",
+            f"8–16 kHz at {rep.bands['air']:.1f} dB relative",
+            "Fine if it is intentional grit; a problem if it is aliasing from "
+            "distortion or a resampled sample.",
+            "Low-pass at 12 kHz and A/B. If nothing is lost, it was noise.",
+            tags=["bass"],
+        ))
+    if source == "Vocal" and _above(r.get("harsh", 0.0), (-6.0, 0.0)) > 1.0:
+        out.append(Diagnosis(
+            "sibilance", "warn",
+            "Sibilance range is hot",
+            f"1.5–4 kHz {r.get('harsh', 0.0):+.1f} dB against the mids",
+            "Reads as 'ess' and 'tuh' jumping out of the line.",
+            "De-esser at 6–8 kHz, 3 dB of range, then a dynamic bell at 3 kHz "
+            "for the hardness underneath it.",
+            band="himid", freq=6500.0, tags=["vocal"],
+        ))
+    if source == "Drum bus" and rep.crest < 8.0 and rep.duration > 2.0:
+        out.append(Diagnosis(
+            "flat_drums", "warn",
+            f"Drum bus crest is only {rep.crest:.1f} dB",
+            f"Peak-to-RMS {rep.crest:.1f} dB",
+            "Drums are the one bus where crest is the whole point.",
+            "Slower attack on the bus compressor (30 ms) so the hits get "
+            "through before gain reduction starts.",
+            tags=["drums", "dynamics"],
+        ))
+
+    if not out:
+        out.append(Diagnosis(
+            "clean", "good",
+            "Nothing is fighting you",
+            f"Balance, dynamics and phase all inside the {p.name} window",
+            "The measurable problems are absent, which means the remaining "
+            "decisions are taste, not repair.",
+            "Move on to arrangement and sound selection.",
+            tags=["ok"],
+        ))
+
+    out.sort(key=lambda d: (_SEVERITY_RANK.get(d.severity, 9), -abs(d.amount)))
+    return out
+
+
+def headline_verdict(rep: dsp.Report, diags: list[Diagnosis]) -> tuple[str, str]:
+    """One-line status for the live meter strip."""
+    if not diags:
+        return "listening", "ok"
+    worst = diags[0]
+    if worst.severity == "critical":
+        return worst.headline, "critical"
+    if worst.severity == "warn":
+        return worst.headline, "warn"
+    if worst.severity == "good":
+        return "Balance is holding", "ok"
+    return worst.headline, "note"
+
+
+def profile_for(genre: str) -> Profile:
+    return GENRES.get(genre, GENRES["Dubstep / Riddim"])
+
+
+def band_target_windows(genre: str) -> dict[str, tuple[float, float]]:
+    """Approximate absolute band windows, for the ghost range behind each bar.
+
+    Drawing only — the rules themselves never fire on these numbers.
+    """
+    p = profile_for(genre)
+    a = -6.5  # nominal mid-band anchor for a full-range balance
+    return {
+        "sub": (a + p.sub_vs_bass[0] - 1.0, a + p.sub_vs_bass[1] + 2.0),
+        "bass": (a - 4.0, a + 2.0),
+        "lowmid": (a + p.mud[0], a + p.mud[1]),
+        "mid": (a - 2.5, a + 2.5),
+        "himid": (a + p.harsh[0], a + p.harsh[1]),
+        "presence": (a + p.harsh[0] - 4.0, a + p.harsh[1] - 2.0),
+        "air": (a + p.air[0], a + p.air[1]),
+    }

ear/llm.py

@@ -0,0 +1,98 @@
+"""Optional narration layer.
+
+The rule engine already produces the diagnosis and the move. This turns that
+into the way a good engineer would actually say it in the room, and catches
+interactions between findings that per-rule logic cannot see.
+
+Entirely optional: with no token configured the Space runs on the rule engine
+alone and says so, rather than degrading silently.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+DEFAULT_MODEL = os.environ.get("EAR_LLM_MODEL", "Qwen/Qwen3-235B-A22B-Instruct-2507")
+
+SYSTEM = """You are a senior sound designer and mix engineer sitting in on a session.
+You have been handed measurements and a rule-based diagnosis of a piece of audio.
+
+How you talk:
+- Like an engineer in the room, not a manual. Short sentences. No hedging.
+- Never repeat a number without saying what it means for the listener.
+- Name the move, the device, and the value. "Cut 3 dB at 250" beats "consider EQ".
+- If the measurements disagree with each other, say which one you trust and why.
+- If nothing is wrong, say so in one line and talk about what to do next instead
+  of inventing problems.
+- Never mention that you were given JSON or that you are an AI.
+
+Structure your answer as exactly three short sections:
+**What I'm hearing** — two or three sentences, the sound not the stats.
+**The one thing to fix first** — a single highest-leverage move, with the reason.
+**Then** — at most three more moves as a tight bulleted list.
+"""
+
+
+def _token() -> str | None:
+    return os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+
+
+def available() -> tuple[bool, str]:
+    if not _token():
+        return False, "no HF_TOKEN set — running on the rule engine only"
+    return True, f"ready ({DEFAULT_MODEL})"
+
+
+def critique(
+    report: dict,
+    diagnoses: list[dict],
+    semantic_tags: dict,
+    genre: str,
+    source: str,
+    intent: str = "",
+) -> str:
+    ok, _ = available()
+    if not ok:
+        return ""
+
+    from huggingface_hub import InferenceClient
+
+    payload = {
+        "genre": genre,
+        "listening_to": source,
+        "producer_intent": intent or "(not stated)",
+        "measurements": {
+            "lufs_integrated": round(report.get("lufs_i", -120), 1),
+            "true_peak_dbtp": round(report.get("true_peak", -120), 2),
+            "crest_db": round(report.get("crest", 0), 1),
+            "loudness_range_lu": round(report.get("lra", 0), 1),
+            "band_balance_db": {k: round(v, 1) for k, v in report.get("bands", {}).items()},
+            "ratios_db": {k: round(v, 1) for k, v in report.get("ratios", {}).items()},
+            "stereo": {k: round(v, 2) for k, v in report.get("stereo", {}).items()},
+            "tempo_bpm": round(report.get("rhythm", {}).get("bpm", 0), 1),
+            "key": report.get("key", {}).get("key", "—"),
+        },
+        "rule_findings": [
+            {"severity": d["severity"], "headline": d["headline"],
+             "evidence": d["evidence"], "suggested_move": d["move"]}
+            for d in diagnoses[:6]
+        ],
+        "sounds_like": {g: [t for t, _ in v] for g, v in (semantic_tags or {}).items()},
+    }
+
+    try:
+        client = InferenceClient(api_key=_token(), provider="auto")
+        resp = client.chat_completion(
+            model=DEFAULT_MODEL,
+            messages=[
+                {"role": "system", "content": SYSTEM},
+                {"role": "user", "content": json.dumps(payload, ensure_ascii=False)},
+            ],
+            max_tokens=700,
+            temperature=0.6,
+        )
+        return (resp.choices[0].message.content or "").strip()
+    except Exception as exc:  # noqa: BLE001 - narration is optional by design
+        return (f"_Narration unavailable ({type(exc).__name__}: {exc}). "
+                f"The analysis above stands on its own._")

ear/render.py

@@ -0,0 +1,153 @@
+"""HTML rendering for the live meter strip and the finding cards.
+
+Gradio's stock components can show a number. They cannot show a number
+*against the window it is supposed to sit in*, which is the whole point of a
+mix meter — so the bars are hand-rolled with the target range drawn as a
+ghost behind the fill.
+"""
+
+from __future__ import annotations
+
+import html
+
+from . import dsp, knowledge
+
+STYLE = """
+<style>
+.se-wrap{--se-bg:#101215;--se-panel:#171a1f;--se-line:#252a31;--se-dim:#7c8794;
+ --se-text:#e6eaef;--se-ok:#4ec9a0;--se-note:#5aa7e0;--se-warn:#e0a44a;--se-crit:#e0574a;
+ font-family:ui-monospace,SFMono-Regular,"SF Mono",Menlo,monospace;
+ background:var(--se-bg);border:1px solid var(--se-line);border-radius:10px;
+ padding:16px 18px;color:var(--se-text);}
+.se-verdict{display:flex;align-items:baseline;gap:12px;margin-bottom:14px;
+ padding-bottom:12px;border-bottom:1px solid var(--se-line);}
+.se-dot{width:9px;height:9px;border-radius:50%;flex:none;box-shadow:0 0 12px currentColor;}
+.se-verdict-text{font-size:15px;letter-spacing:-0.01em;line-height:1.3;}
+.se-verdict-sub{margin-left:auto;font-size:11px;color:var(--se-dim);white-space:nowrap;}
+.se-nums{display:grid;grid-template-columns:repeat(auto-fit,minmax(88px,1fr));
+ gap:1px;background:var(--se-line);border:1px solid var(--se-line);border-radius:6px;
+ overflow:hidden;margin-bottom:16px;}
+.se-num{background:var(--se-panel);padding:9px 11px;}
+.se-num-k{font-size:9px;letter-spacing:0.09em;text-transform:uppercase;color:var(--se-dim);}
+.se-num-v{font-size:17px;margin-top:3px;font-variant-numeric:tabular-nums;}
+.se-bars{display:flex;flex-direction:column;gap:6px;}
+.se-bar-row{display:grid;grid-template-columns:118px 1fr 54px;align-items:center;gap:10px;}
+.se-bar-label{font-size:10px;color:var(--se-dim);letter-spacing:0.03em;}
+.se-track{position:relative;height:16px;background:#0b0d10;border-radius:3px;overflow:hidden;}
+.se-target{position:absolute;top:0;bottom:0;background:rgba(255,255,255,.07);
+ border-left:1px solid rgba(255,255,255,.16);border-right:1px solid rgba(255,255,255,.16);}
+.se-fill{position:absolute;top:3px;bottom:3px;left:0;border-radius:2px;
+ transition:width 120ms linear;}
+.se-bar-val{font-size:11px;text-align:right;font-variant-numeric:tabular-nums;color:var(--se-dim);}
+.se-cards{display:flex;flex-direction:column;gap:9px;}
+.se-card{background:var(--se-panel);border:1px solid var(--se-line);border-left-width:3px;
+ border-radius:7px;padding:12px 14px;}
+.se-card h4{margin:0 0 5px;font-size:13.5px;font-weight:600;letter-spacing:-0.01em;}
+.se-card .ev{font-size:10.5px;color:var(--se-dim);margin-bottom:8px;
+ font-variant-numeric:tabular-nums;}
+.se-card p{margin:0 0 7px;font-size:12.5px;line-height:1.55;
+ font-family:ui-sans-serif,system-ui,-apple-system,sans-serif;color:#c3cbd4;}
+.se-card .move{font-size:12.5px;line-height:1.55;
+ font-family:ui-sans-serif,system-ui,-apple-system,sans-serif;color:var(--se-text);
+ border-top:1px dashed var(--se-line);padding-top:7px;}
+.se-idle{color:var(--se-dim);font-size:12.5px;padding:26px 0;text-align:center;}
+</style>
+"""
+
+_TONE = {"ok": "var(--se-ok)", "note": "var(--se-note)",
+         "warn": "var(--se-warn)", "critical": "var(--se-crit)"}
+
+
+def _pct(value: float, lo: float = -30.0, hi: float = 0.0) -> float:
+    return max(0.0, min(100.0, (value - lo) / (hi - lo) * 100.0))
+
+
+def _fmt(v: float, unit: str = "", digits: int = 1) -> str:
+    if v is None or v != v or v <= -119:
+        return "—"
+    return f"{v:.{digits}f}{unit}"
+
+
+def idle(message: str) -> str:
+    return f'{STYLE}<div class="se-wrap"><div class="se-idle">{html.escape(message)}</div></div>'
+
+
+def meters(rep: dsp.Report | None, genre: str, verdict: str, tone: str,
+           extra: str = "") -> str:
+    if rep is None:
+        return idle("waiting for signal…")
+
+    colour = _TONE.get(tone, "var(--se-dim)")
+    windows = knowledge.band_target_windows(genre)
+
+    nums = [
+        ("LUFS-S", _fmt(rep.lufs_s)),
+        ("True peak", _fmt(rep.true_peak, " dB", 2)),
+        ("Crest", _fmt(rep.crest, " dB")),
+        ("Corr", f"{rep.stereo.get('correlation', 0):+.2f}"),
+        ("Sub corr", f"{rep.stereo.get('sub_correlation', 0):+.2f}"),
+        ("Width", _fmt(rep.stereo.get("width_db", -99), " dB")),
+    ]
+    bpm = rep.rhythm.get("bpm", 0.0)
+    if bpm > 0:
+        nums.append(("Tempo", f"{bpm:.0f}"))
+    key = rep.key.get("key", "—")
+    if key and key != "—":
+        nums.append(("Key", key))
+
+    num_html = "".join(
+        f'<div class="se-num"><div class="se-num-k">{html.escape(k)}</div>'
+        f'<div class="se-num-v">{html.escape(v)}</div></div>'
+        for k, v in nums
+    )
+
+    rows = []
+    for band in dsp.BAND_ORDER:
+        val = rep.bands.get(band, -60.0)
+        lo, hi = windows.get(band, (-20.0, -4.0))
+        inside = lo <= val <= hi
+        fill = "var(--se-ok)" if inside else (
+            "var(--se-warn)" if val > hi else "var(--se-note)")
+        t_left, t_right = _pct(lo), _pct(hi)
+        rows.append(
+            f'<div class="se-bar-row">'
+            f'<div class="se-bar-label">{html.escape(dsp.BAND_LABELS[band])}</div>'
+            f'<div class="se-track">'
+            f'<div class="se-target" style="left:{t_left:.1f}%;width:{max(t_right - t_left, 1):.1f}%"></div>'
+            f'<div class="se-fill" style="width:{_pct(val):.1f}%;background:{fill}"></div>'
+            f'</div>'
+            f'<div class="se-bar-val">{val:+.1f}</div>'
+            f'</div>'
+        )
+
+    sub = html.escape(extra) if extra else f"{rep.duration:.1f}s window · {html.escape(genre)}"
+
+    return (
+        f'{STYLE}<div class="se-wrap">'
+        f'<div class="se-verdict">'
+        f'<span class="se-dot" style="background:{colour};color:{colour}"></span>'
+        f'<span class="se-verdict-text">{html.escape(verdict)}</span>'
+        f'<span class="se-verdict-sub">{sub}</span>'
+        f'</div>'
+        f'<div class="se-nums">{num_html}</div>'
+        f'<div class="se-bars">{"".join(rows)}</div>'
+        f'</div>'
+    )
+
+
+def cards(diags: list[knowledge.Diagnosis], limit: int = 6) -> str:
+    if not diags:
+        return idle("no findings yet")
+    out = []
+    for d in diags[:limit]:
+        colour = _TONE.get(d.severity, "var(--se-dim)")
+        out.append(
+            f'<div class="se-card" style="border-left-color:{colour}">'
+            f'<h4 style="color:{colour}">{html.escape(d.headline)}</h4>'
+            f'<div class="ev">{html.escape(d.evidence)}</div>'
+            f'<p>{html.escape(d.why)}</p>'
+            f'<div class="move"><b>Move:</b> {html.escape(d.move)}</div>'
+            f'</div>'
+        )
+    return (f'{STYLE}<div class="se-wrap" style="background:transparent;border:none;padding:0">'
+            f'<div class="se-cards">{"".join(out)}</div></div>')

ear/semantic.py

@@ -0,0 +1,161 @@
+"""Zero-shot semantic listening with CLAP.
+
+The DSP layer knows a band is 4 dB hot. It does not know the sound is a
+reese. CLAP scores the audio against a bank of sound-design descriptors, so
+the report can say "gritty distorted reese bass, over-compressed drums"
+instead of only quoting numbers.
+
+Loads in a background thread so the Space boots immediately, and fails soft:
+if the model never arrives, everything else still works.
+"""
+
+from __future__ import annotations
+
+import threading
+
+import numpy as np
+
+MODEL_ID = "laion/clap-htsat-unfused"
+CLAP_SR = 48_000
+
+# Grouped so the report can show one line per axis rather than a flat top-k.
+BANK: dict[str, list[str]] = {
+    "character": [
+        "a gritty distorted reese bass",
+        "a clean deep sine sub bass",
+        "a metallic screaming growl bass",
+        "an aggressive detuned saw lead",
+        "a warm analog pad",
+        "a plucky short synth stab",
+        "a bright supersaw chord stack",
+        "a wobbling filtered bass",
+        "a soft mellow electric piano",
+        "an acoustic guitar",
+        "a male vocal",
+        "a female vocal",
+    ],
+    "drums": [
+        "a punchy tight kick drum",
+        "a boomy undamped kick drum",
+        "a sharp cracking snare",
+        "a boxy resonant snare",
+        "crisp hi hats",
+        "a heavily compressed drum break",
+        "a loose live drum kit",
+    ],
+    "problem": [
+        "a muddy boomy cluttered mix",
+        "a harsh sibilant painful mix",
+        "an over-compressed lifeless mix",
+        "a thin tinny weak mix",
+        "a clipping distorted overloaded mix",
+        "a clean balanced professional mix",
+        "a hissy noisy recording",
+        "a phasey hollow comb-filtered sound",
+    ],
+    "space": [
+        "a dry close-miked sound with no reverb",
+        "a tight small room reverb",
+        "a huge cavernous hall reverb",
+        "a long washed-out ambient reverb tail",
+        "a slapback delay",
+    ],
+    "energy": [
+        "a quiet sparse intro section",
+        "a building tense riser",
+        "a full loud drop section",
+        "a calm breakdown section",
+    ],
+}
+
+_FLAT: list[tuple[str, str]] = [(g, t) for g, items in BANK.items() for t in items]
+
+
+class _Semantic:
+    def __init__(self) -> None:
+        self.ready = False
+        self.error: str | None = None
+        self._model = None
+        self._processor = None
+        self._text_emb = None
+        self._lock = threading.Lock()
+
+    def start(self) -> None:
+        threading.Thread(target=self._load, daemon=True).start()
+
+    def _load(self) -> None:
+        try:
+            import torch
+            from transformers import ClapModel, ClapProcessor
+
+            torch.set_num_threads(2)
+            model = ClapModel.from_pretrained(MODEL_ID)
+            model.eval()
+            processor = ClapProcessor.from_pretrained(MODEL_ID)
+
+            texts = [t for _, t in _FLAT]
+            with torch.no_grad():
+                inputs = processor(text=texts, return_tensors="pt", padding=True)
+                emb = model.get_text_features(**inputs)
+                emb = emb / emb.norm(dim=-1, keepdim=True)
+
+            self._model, self._processor, self._text_emb = model, processor, emb
+            self.ready = True
+        except Exception as exc:  # noqa: BLE001 - fail soft, the app still works
+            self.error = f"{type(exc).__name__}: {exc}"
+
+    def status(self) -> str:
+        if self.ready:
+            return "ready"
+        if self.error:
+            return f"unavailable ({self.error})"
+        return "warming up"
+
+    def describe(self, mono48: np.ndarray, top_k: int = 2) -> dict[str, list[tuple[str, float]]]:
+        """Score the clip against every descriptor, grouped by axis."""
+        if not self.ready or mono48.size < CLAP_SR // 2:
+            return {}
+
+        import torch
+
+        # CLAP was trained on 10 s windows; take the loudest one.
+        want = CLAP_SR * 10
+        if mono48.size > want:
+            hop = CLAP_SR
+            best_s, best_e = 0, -1.0
+            for s in range(0, mono48.size - want + 1, hop):
+                e = float(np.mean(mono48[s : s + want] ** 2))
+                if e > best_e:
+                    best_e, best_s = e, s
+            mono48 = mono48[best_s : best_s + want]
+
+        with self._lock, torch.no_grad():
+            inputs = self._processor(
+                audios=mono48.astype(np.float32),
+                sampling_rate=CLAP_SR,
+                return_tensors="pt",
+            )
+            audio_emb = self._model.get_audio_features(**inputs)
+            audio_emb = audio_emb / audio_emb.norm(dim=-1, keepdim=True)
+            sims = (audio_emb @ self._text_emb.T).squeeze(0).cpu().numpy()
+
+        grouped: dict[str, list[tuple[str, float]]] = {}
+        for group in BANK:
+            idx = [i for i, (g, _) in enumerate(_FLAT) if g == group]
+            local = sims[idx]
+            # Softmax within the group — cross-group absolute scores are not
+            # comparable, ranking inside a group is.
+            e = np.exp((local - local.max()) * 20.0)
+            probs = e / e.sum()
+            order = np.argsort(-probs)[:top_k]
+            grouped[group] = [(_FLAT[idx[o]][1], float(probs[o])) for o in order]
+        return grouped
+
+
+SEMANTIC = _Semantic()
+
+
+def tags_line(grouped: dict[str, list[tuple[str, float]]], min_conf: float = 0.30) -> str:
+    """Flatten the grouped scores into one readable sentence."""
+    picks = [items[0][0] for items in grouped.values() if items and items[0][1] >= min_conf]
+    return ", ".join(picks) if picks else ""

packages.txt

@@ -0,0 +1,2 @@
+libsndfile1
+ffmpeg

requirements.txt

@@ -0,0 +1,9 @@
+# CPU torch only — nothing here needs a GPU, and the CUDA wheel is 10x the size.
+--extra-index-url https://download.pytorch.org/whl/cpu
+
+numpy
+scipy
+soundfile
+torch==2.6.0+cpu
+# ClapProcessor's audio kwarg was renamed in the 5.x line; pin to the 4.x API.
+transformers>=4.44,<5