Drum Rack Cartographer

Stop hand-translating drum MIDI. Analyze, label, preview, and remap your drum grooves for Ableton Drum Rack.

Drum Rack Cartographer is an Ableton Live Extension (Extensions SDK 1.0.0-beta.0) that turns messy drum MIDI into a readable, playable Drum Rack map. Right-click any MIDI clip → Drum Rack Cartographer: Scan & Map… and it will:

1. Inventory every pitch in the clip — hit counts, velocity stats, common beat positions, density.
2. Infer drum roles (kick, snare, hats, toms, cymbals, clap, rim, shaker, percussion) with a deterministic, rule-based scorer — General MIDI pitch knowledge × rhythmic behavior. Every guess comes with a confidence score and human-readable reasons.
3. Detect the source layout — General MIDI, already-Drum-Rack-shaped, MPC-style pad block, or unknown.
4. Preview a remap plan onto the standard Ableton Drum Rack layout (kick→C1/36, snare→D1/38, closed hat→F#1/42, …) with collision detection and a safety verdict. Override any role or target manually; the plan recomputes live.
5. Apply — only after preview, only when the plan is safe:
   • To a new clip (default for Session clips): the remapped notes are written into a new clip in an empty slot on the same track. The original clip is never touched.
   • In place: one single undo step, gated behind an explicit confirmation checkbox, with a JSON backup of the original notes written first.
6. Report — generate a Markdown cartography report (copy to clipboard or save to disk).

No AI, no cloud, no telemetry, no internet. Pure local analysis.

The safety contract

• Writes change only note pitch. Start time, duration, velocity, mute, probability, velocity deviation and release velocity pass through untouched.
• Note count out always equals note count in. Nothing is ever deleted, quantized, or humanized.
• Applying is blocked while the plan has critical collisions (e.g. two confident kicks merging), more than one low-confidence core voice, busy unidentified notes, or no recognizable kick/snare (overridable in Settings for hat/percussion-only clips).
• Low-confidence guesses are left alone (manual review), not remapped.
• In-place remaps are one undo step (Cmd+Z restores everything) and backed up as JSON.

A drum map that refuses unsafe changes is better than a clever tool that mangles your groove.

Requirements

• Ableton Live 12 with the Extensions feature (currently the Live 12 beta program) and Settings → Extensions → Developer Mode enabled for the dev workflow.
• Node.js ≥ 24.14.1 and npm.
• macOS or Windows (the dialog uses the platform webview; developed/tested on macOS).

The Extensions SDK beta (extensions-sdk-1.0.0-beta.0/) is vendored in this repository and installed from local tarballs — no network needed at runtime.

Install / run / build

npm install              # one-time setup

npm test                 # 62 unit + integration tests, no Live required
npm run demo             # full mock-mode analysis + Markdown report in your terminal
npm run build            # typecheck + production bundle → dist/extension.js
npm run package          # → Drum-Rack-Cartographer-0.1.1.ablx

npm start                # dev loop: build + launch Live's Extension Host

For npm start, set EXTENSION_HOST_PATH in .env to your Live install (e.g. /Applications/Ableton Live 12 Beta.app) and enable Developer Mode in Live's Extensions settings.

Install the packaged extension (.ablx) — no npm, no Developer Mode

End users never touch npm or the dev loop — hand them the .ablx from npm run package:

1. In Live, open Settings → Extensions.
2. Click Choose file (or drag the .ablx onto Drag and drop to install) and pick Drum-Rack-Cartographer-<version>.ablx.
3. When prompted, restart Live.

Live copies the extension into its managed extensions folder (~/Library/Application Support/Ableton/Extensions/ on macOS) and loads it automatically on every launch, with Developer Mode off. Confirm it under Settings → Extensions → Installed Extensions, where an Uninstall button removes it. Verified on Ableton Live 12 beta.

npm run build also emits dist/preview.html — open it in any browser to explore the full dialog UI against built-in demo data (read-only, no Live needed).

Using it in Live

1. Right-click a MIDI clip (Session or Arrangement) → Extensions → Drum Rack Cartographer: Scan & Map Drums…
2. Read the header: source-layout guess, capability chip, safety verdict.
3. Check the Mapping tab. Fix any role the scanner got wrong via the override dropdowns — the plan, collisions, and safety verdict update live. Roles you override can be remembered for future scans (Settings).
4. Optionally open Note Inventory (the raw evidence) and Report (copy or save).
5. Pick an apply mode and hit Apply remap. For in-place mode, tick the confirmation box first.
6. A summary dialog confirms what changed; the remapped clip is named <original> - Drum Rack Mapped.

Interpreting confidence

Band	Range	Meaning
high	0.85–1.00	Pitch and rhythm agree. Remapped automatically.
medium	0.60–0.84	Reasonable guess; evidence is partial or ambiguous. Remapped, but read the reasons.
low	< 0.60	Left for manual review — never remapped without your override.

The threshold is adjustable in Settings (0.30–0.95).

Known limitations (honest list)

• No clip duplication API in SDK 1.0.0-beta.0 — "to a new clip" creates a fresh clip and copies notes/name/color/loop-flag; clip envelopes and grooves are not carried over. Arrangement clips support in-place mode only.
• Loop brackets can't be set via the SDK, so a remapped copy loops from beat 0 (you'll be warned when the source loop starts elsewhere).
• Modal dialog only — the SDK has no persistent panels, so Cartographer is a focused scan-review-apply dialog rather than a docked view.
• Rhythm heuristics assume a regular meter (default 4/4, configurable beats-per-bar) and work best on groove-like clips. One-shot/sparse clips lean on pitch evidence alone.
• Reports/backups are saved inside the extension's sandboxed storage directory (the SDK restricts file access to it); the summary dialog shows the exact path.
• Targets pitches, not pad samples — the remap moves notes to standard Drum Rack pitches and does not inspect pad contents. In custom/non-GM kits a pad's sample may not match its role (Live's 909 Flavour Kit has a snare on pitch 41, the tom_low slot); the Pad ● only means a pad exists at the target. See docs/target-mappings.md.

See docs/sdk-capability-audit.md for the full audit with evidence.

SDK beta disclaimer

Built against Ableton Extensions SDK 1.0.0-beta.0. Beta APIs can change; the capability audit documents exactly which API surface this extension relies on. Items listed as unclear in the audit are wrapped defensively and degrade gracefully.

Privacy

Everything runs locally inside Live's Extension Host. No network requests, no telemetry, no analytics, no cloud APIs, no AI services. The only files written are preferences, reports and note backups inside the extension's own storage directory.

Docs

• Product spec
• SDK capability audit
• Development guide
• Inference rules
• Target mappings
• Safety model
• Roadmap