Track Doctor

One-click smart rename cleanup for Ableton Live sets.

Track Doctor is an Ableton Live Extension that scans your Live Set, figures out what each track actually is (drums, bass, vocals, guitar, keys, synth, FX, returns, buses, references, empties), and suggests clean, consistent names — which you review and apply in one click, as one undoable step.

Before                    After
──────                    ─────
Audio 1                   EMPTY - Review
kick                      DRUMS - Kick
Group 4                   DRUMS - Bus
bass final final          BASS - Synth
MIDI 4                    DRUMS - Main
vox maybe                 VOCAL - Lead
vox dub                   VOCAL - Lead 2
pad serum                 SYNTH - Pad
ref track                 REF - Mix Reference

How it works

1. Right-click any audio or MIDI track → Track Doctor: Diagnose Set…
2. Track Doctor scans every track (names, devices, clip names, sample files, group structure) under a cancellable progress dialog.
3. A review dialog shows each suggestion with its category, confidence, and the exact reasons behind it. Edit any name, check or uncheck any row, switch naming presets, or grab all high-confidence suggestions at once.
4. Apply selected renames the chosen tracks — grouped into a single Live undo step, so one Cmd+Z reverts the whole cleanup.

Everything is deterministic, on-device heuristics. No network, no accounts, no ML.

Naming presets

Preset	Example
Clean Producer (default)	DRUMS - Kick, VOCAL - Lead, RETURN - Reverb
Mixer Prep	01 DRUMS - Kick, 02 BASS - Synth (numbered for stem handoff)
Minimal	Kick, Lead Vox, Drums Bus

Your preset choice is remembered between sessions.

Safety guarantees

• Never deletes tracks — empty tracks are only offered an EMPTY - Review rename, unchecked by default.
• Never touches clips, devices, routing, or colors.
• Nothing is applied without review; low/medium-confidence suggestions are unchecked by default.
• Tracks renamed by you between scan and apply are skipped, never clobbered.
• The whole apply is one undo step.

About colors

The review dialog shows a suggested color per category, but the Ableton Extensions SDK 1.0.0 does not yet expose track colors to extensions (verified in docs/API_FINDINGS.md §6). Renames work today; color application ships as soon as the SDK supports it — src/live/liveColorAdapter.ts is the prepared integration point.

Development

Requirements: Node ≥ 24.14.1, the Ableton Extensions SDK 1.0.0-beta.0 vendored at ../extensions-sdk-1.0.0-beta.0/ (see the repository root README), and a Live build with Extension Host support.

npm install

# One-time: point the CLI at Live's Extension Host module
cp .env.example .env   # then edit EXTENSION_HOST_PATH

npm start              # build (dev) + launch via npm-start dev host (Developer Mode ON)
npm test               # 65 unit tests over the pure analysis/naming engine
npm run preview        # render the review dialog in a browser, no Live needed
npm run build          # typecheck + production bundle
npm run package        # build a distributable .ablx archive
npm run install:live   # build + install into Live's Extensions dir (Developer Mode OFF)

End users install the packaged .ablx via Live → Settings → Extensions.

Two ways Live loads an extension

Live has a single Extension Host slot, and the two modes are mutually exclusive:

• Dev (npm start) — enable Developer Mode in Live → Settings → Extensions; Live yields the host to your npm start process for a live-reload loop on one extension.
• Native (npm run install:live) — keep Developer Mode OFF; Live's built-in host auto-loads every installed extension on launch (no terminal). After installing, reload the host via the Restart button on Live's "Extension Host has stopped" bar, or relaunch Live. npm run install:live -- --reload stops the running host for you so that bar appears.

Architecture

All Ableton-specific code is isolated; everything that decides anything is pure and unit-tested.

src/
  extension.ts          activate(): menu registration + the diagnose flow
  commands/             scanSet (progress dialog), applySuggestions (transaction)
  live/                 SDK boundary: scanner, color adapter (SDK gap), types
  analysis/             pure: role inference, confidence, naming, duplicates
  presets/              data: keyword rules, naming presets, color palette
  models/               TrackInfo / TrackSuggestion / CleanupReport / prefs
  ui/                   review + message dialogs (self-contained HTML), bridge
  storage/              preferences.json in the extension storage directory
  utils/                normalize/keyword matching, logger
tests/                  vitest suites incl. the brief's three reference sets
docs/                   API_FINDINGS.md (verified SDK surface), implementation plan

The inference engine scores categories with explainable, weighted evidence (name keywords, device names, clip/sample names, track type, group children) combined noisy-OR style — every suggestion carries its reasons, and confidence maps to High (≥ 0.8) / Medium (≥ 0.6) / Low.

Manual test checklist (in Live)

Items that can only be verified inside Live are tracked in docs/API_FINDINGS.md §12: group-track runtime behavior, dialog ✕-close semantics, return-track rename acceptance, large-set scan timing, and CLI log visibility.