ableton-tools

Give Claude Code a set of Ableton Live tools it can run for you: check whether a folder of stems really sums back to a master, find a project's true tempo and drift, transcribe an audio part to MIDI, and edit .als files safely (repoint samples, grid-lock warps, import stems in sync). Everything runs through one ableton dispatcher backed by a local, uv-managed Python engine.

It started as a pile of one-off scripts for a single problem: exported stems that drifted out of phase against their master. It grew into a small toolkit for the fiddly, error-prone parts of working with .als projects, wrapped so Claude can drive it in plain language.

Requires uv (the engine runs under it) and ffmpeg/ffprobe on PATH for audio decoding.

Status

The mainstay is stem alignment: let Ableton auto-warp a master (a Suno render, say), then have als import-stems clone that warped master onto each stem so they all line up with it. That, plus .als re-linking and stem verification, is the solid core, and it complements Ableton rather than replacing it.

midi-transcribe and the tempo/grid-warp features (tempo-drift, als-warp) are experimental: they overlap with Ableton's own audio-to-MIDI and auto-warp, have not been benchmarked against those built-ins, and are not verified to do better. Treat their output as a starting point to check by ear or eye, not a replacement.

Install

This repo is its own plugin marketplace. Add it, then install at user scope:

claude plugin marketplace add madisonrickert/ableton-tools
claude plugin install ableton-tools@ableton-tools

Verify with /plugin (it should list ableton-tools) or by asking Claude to run ableton manifest --json, which lists every subcommand.

In practice

You work in Claude Code, not the terminal. Ask in plain language and the right skill runs the engine for you:

• "I auto-warped the Suno master in Ableton; align the matching stems to it, color-coded." runs als import-stems: one clone of the warped master per stem, samples repointed, only the master kept as tempo leader.
• "Do these stems sum back to master.wav?" runs stem-verify: windowed cancellation depth, correlation, and a sibling verdict.
• "This project points at the old sample folder; repoint it to Samples/Imported." dry-runs the als rename diff, then commits with an automatic backup.

Every .als edit is previewed before anything is written. Close Ableton while committing one.

Skills

Each row is a skill Claude invokes for you; the command is what it runs under the hood.

Safety

.als files are your projects, so the engine treats them carefully.

• Nothing is written without a preview. Every mutating als command is dry-run by default and only writes with --commit. On commit it first saves a backup to <project>/Backup/<basename> [YYYY-MM-DD HHMMSS].als (Ableton's own auto-backup convention, so it appears in Live's rollback UI), then re-verifies every sample reference and auto-restores from the backup if any break.
• Edits preserve your file's formatting. Mutations patch the decompressed XML in place with targeted regex rather than re-serializing through a DOM, so diffs stay small and Ableton's own version history is not disturbed.
• It runs locally, with no API keys. Analysis commands emit raw numbers and threshold bands (worst_db, chroma_cosine, drift stats); reading them and stating a verdict is the skill's job, not an external service's.
• Failures are legible. Usage problems exit nonzero with {"error": "...", "hint": "..."}; a traceback means a bug, not a mistake you made.
• The heavy transcription dependency is opt-in. Only ableton midi transcribe pulls in basic-pitch/TensorFlow, added on demand so the default environment stays light.

Stem import

als import-stems refuses to run (structured error, no partial writes) unless every stem's frame count and sample rate exactly match the master's: the clones inherit the master's warp markers verbatim, which is only valid when the audio timelines are identical. Suno stems satisfy this by construction; other sources may not. Track coloring follows a default per-stem convention (override with --colors); the full XML mechanics (SampleRef fields, EffectiveName derivation, color table) live in engine/references/als-format.md.

Development

From the repo root:

uv run --project engine --group dev pytest
uvx ruff check engine
uvx pyright --project engine engine/src

The --project engine on pyright is required so it resolves engine/.venv (engine/CLAUDE.md explains why). Run claude plugin validate . before committing, and bump version in .claude-plugin/plugin.json when behavior changes so the plugin cache refreshes.

More Ableton tools

Other Ableton Live extensions I've built (native panels on the Live Extensions SDK, separate from this Claude Code plugin):

• AbleVSEP: Separate any audio clip into stems with any of MVSEP's 100+ models, right inside Ableton Live. It mirrors Live's built-in Stem Separation, but exposes MVSEP's full model catalog instead of one fixed algorithm.
• AbleTab: View any MIDI clip in Ableton Live as stringed-instrument tablature. Pick an instrument preset or dial in a custom tuning, then export PDF or ASCII tab.
• Ableton Sheet Music Extension: View any MIDI clip in Ableton Live as readable sheet music. Transpose it for any instrument and export MusicXML, PDF, or PNG.