Sublevel

A reference-matching mix analyst for Ableton Live, exposed over MCP, backed by a corpus of 798 analyzed electronic tracks.

Mixing low end without accurate monitoring is guessing. Everything below about 150Hz is inaudible on laptop speakers and misrepresented on consumer headphones. Sublevel replaces the ear with measurement where measurement works, and says how confident it is by placing every number against records you actually listen to.

What makes it trustworthy

There is not a single invented threshold in this repo. A mix is not "thin" because a diff crossed -3dB; it is thin because it sits below p10 of tracks in its own genre. Every claim carries its percentile so it can be checked.

sub vs body: you -3.42dB (p8), reference 3.92dB (p82), -7.34dB.
Kick has punch but no weight underneath it.

The corpus is scoped by genre, because the genres genuinely differ - House carries about 2dB less sub relative to kick body than Tech House or Minimal, and that is not a rounding artifact.

Related MCP server: Ableton Cookbook MCP

Status

Built and verified: measurement core, 798-track corpus, genre-scoped calibration, reference finding, headless Vital patch design, the diff-to-device translation layer, and the MCP server (11 tools).

Needs you, once, in Live: select AbletonMCP as a Control Surface (Preferences > Link, Tempo & MIDI; Input and Output both None) and restart Live. The Remote Script is already installed.

Setup

python3.13 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest

The MCP server is registered for this project in .mcp.json (python -m sublevel mcp). See ARCHITECTURE.md for the v2 layout and the tool contracts.

Rebuilding the calibration

python -m sublevel.corpus extract ~/Downloads/beatport_tracks_* --out calibration/corpus.json
python -m sublevel.calibration build calibration/corpus.json
python -m sublevel.calibration show calibration/thresholds.json --genre "Tech House"

Extraction is resumable and keyed by content hash, so re-running skips what is already analyzed. 798 tracks takes about 14 minutes on 5 workers.

MCP tools

The agent-facing surface (python -m sublevel mcp). Long operations return a job id; poll with job.

Sound design

.vital presets are plain JSON with human-named parameters, and pedalboard renders Vital offline, so the measurement engine doubles as a fitness function: write a patch, render a note, measure, adjust - about 200 candidates a minute, entirely headless, with only the winner going into Live. Targeting a real tech-house bass preset from Vital's init patch converges in ~25 seconds.

Corpus percentiles are deliberately not used here. They describe finished, mastered records; a solo'd bass patch judged against them would produce nonsense with a confident percentile attached.

Safety

Sublevel writes to Live through exactly one path, Engine.apply, and every write is measured before and after. A move is kept only if the objective improved without costing kick punch, crest, mono compatibility or headroom; otherwise it is put back. Every kept and reverted move is appended to calibration/changes.jsonl with device, parameter, old value, new value, the reason, the proposal it came from and the verdict. undo, revert_all and the ab bypass are always available.

Two notes on the Ableton bridge:

• The Remote Script Live runs is the upstream ableton-mcp script, patched and vendored at src/sublevel/live/remote_script/. Upstream binds to 0.0.0.0; the vendored copy binds to 127.0.0.1.

• The third-party ableton MCP server in .mcp.json has telemetry that records the originating prompt and an opt-in dataset upload. It is registered with DISABLE_TELEMETRY=1; consent is yours to give.

What it does not do

It does not judge groove, sound design, arrangement, or whether a record is good. It speaks with confidence about sub, weight, punch, width and dynamics - the parts monitoring problems hide - and reports midrange as context rather than instruction, because most midrange problems are masking and arrangement, where the fix is removing a layer and no analyzer can tell you that.

Notes on the corpus

All 798 tracks are 320kbps MP3. That is transparent in the bottom two octaves, so sub, punch, dynamics and mono correlation are trustworthy. It is not transparent at the extremes: codec reconstruction overshoots sample peaks (every track in this corpus reads above 0dBTP), and everything is lowpassed around 20kHz. true_peak_db and the high band are marked advisory wherever they surface, and are never presented as calibrated fact.