README.md

---
title: Second Ear
emoji: 👂
colorFrom: indigo
colorTo: gray
sdk: gradio
sdk_version: 6.23.1
app_file: app.py
python_version: "3.12"
short_description: Realtime mix ear that writes Ableton MCP plans
startup_duration_timeout: 30m
pinned: false
---

# 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.