Session organization

The organizer gives an Ableton Live Set a consistent visual vocabulary in one pass. It classifies every regular track, can add stable category prefixes to track names, applies category colors, and can normalize clip names and colors. The plan is deterministic, so you can preview it before making changes and safely run it again later.

What “sort” means here: the organizer does not move or reorder tracks. The numeric prefixes make categories easy to scan and provide a convention that can be sorted manually, but track positions remain unchanged.

Tools at a glance

Tool	Changes the Live Set?	Purpose
`preview_session_sort`	No	Return the complete proposed organization plan as JSON.
`sort_session`	Yes	Build and apply the same plan, normally as one Ableton Undo step.

Both tools accept the same optional parameters:

Parameter	Type	Default	Behavior
`rename_tracks`	boolean	`true`	Add the category prefix to each track name. When `false`, existing track names are retained.
`recolor_tracks`	boolean	`true`	Apply the category color to each track. When `false`, each track retains its current color.
`normalize_clips`	boolean	`true`	Build clip operations: normalize generic names where applicable and set clip colors to the category color. When `false`, clips are not changed at all.

The MCP context argument is supplied by the server and is not part of a client tool call.

Categories and conventions

The organizer uses seven fixed categories. Every track in the snapshot receives exactly one category.

Category	Track prefix	Rank	Color	Typical evidence
Drums	`10 DRM -`	10	`#E2675A`	kick, snare, clap, hats, drums, percussion, toms, cymbals, shakers, breakbeats, Drum Rack
Bass	`20 BAS -`	20	`#8B5CF6`	bass, sub, low end, 808
Music	`30 MUS -`	30	`#4F8DD6`	leads, pads, chords, keys, piano, synths, guitars, strings, plucks, arps, melody, organ, brass, mallets
Vocals	`40 VOX -`	40	`#E88AC4`	vocal, vox, voice, acapella, choir, spoken
FX	`50 FX -`	50	`#38B2AC`	FX/SFX, risers, impacts, sweeps, noise, foley, atmosphere
Reference	`60 REF -`	60	`#A0AEC0`	reference, ref, master print, rough mix, premaster
Utility	`70 AUX -`	70	`#D6A84F`	fallback for unclassified non-MIDI tracks

For example, Kick Main becomes 10 DRM - Kick Main, while Sub 808 becomes 20 BAS - Sub 808. The rank is a category rank, not a per-track sequence number: every drum track starts with 10 DRM, for example.

How classification works

Classification considers:

the track name;
its parent group name, when grouped;
the names and Live class names of devices on the track;
whether the track accepts MIDI input; and
whether the track is itself a group.

Keyword matching is case-insensitive substring matching. A match in the track name is weighted more strongly than the same match in a group or device name. A Drum Rack is especially strong drum evidence, and explicit vocal wording is boosted so a name such as Lead Vox classifies as vocals rather than music. If categories tie, the lower category rank wins.

Group tracks are classified from their own names only; their child devices and parent-group context do not determine the group’s category. With no keyword evidence, a MIDI track defaults to music and any other track defaults to utility.

The rules are intentionally predictable rather than learned. To customize the palette or vocabulary for a studio template, edit CATEGORIES and KEYWORDS in src/better_ableton_mcp/organization.py.

Naming and clip behavior

Before adding a track prefix, the organizer removes a previous recognized organizer prefix, including an optional two-digit rank. This means names such as 10 DRM - Kick and DRM: Kick are reduced to the base name Kick before the current prefix is applied. Extra whitespace is collapsed as well.

Generic track names such as MIDI, MIDI 1, Audio 2, Track 3, or an empty name are replaced with the first device’s cleaned name when possible. If there is no device name, the base name is Track.

When normalize_clips is enabled:

Every existing Session and Arrangement clip is recolored to its track’s inferred category color.
A blank or generic Session clip name, such as Clip 3, MIDI 1, Audio 2, or a number by itself, becomes <track base> - Scene NN. NN is the one-based clip-slot number, padded to two digits.
A blank Arrangement clip name becomes <track base> - Arrangement NN. NN is the one-based position in Live’s Arrangement clip collection, padded to two digits.
Meaningful existing clip names are preserved. Arrangement names are treated as meaningful whenever they are nonblank, even if they look generic.

recolor_tracks controls track colors only. Clip color matching is part of normalize_clips; therefore, calling with recolor_tracks: false and normalize_clips: true leaves track colors alone but still applies category colors to clips.

`preview_session_sort`

Use this read-only tool before organizing an important Set or when you want to inspect ambiguous classifications.

{
  "rename_tracks": true,
  "recolor_tracks": true,
  "normalize_clips": true
}

The result is a JSON object containing:

operations: one proposed operation per regular track, in current track order;
summary: counts of tracks by inferred category.

Each track operation includes track_index, old_name, proposed name, proposed color, category, and a clips list. Each clip operation identifies its view (session or arrangement), zero-based index, proposed name, and proposed color.

Example excerpt:

{
  "operations": [
    {
      "track_index": 0,
      "old_name": "Kick",
      "name": "10 DRM - Kick",
      "color": 14837594,
      "category": "drums",
      "clips": [
        {
          "view": "session",
          "index": 2,
          "name": "Kick - Scene 03",
          "color": 14837594
        }
      ]
    }
  ],
  "summary": { "drums": 1 }
}

The numeric colors in JSON are Ableton’s integer color values; the category table above shows their hexadecimal equivalents.

Previewing obtains a fresh snapshot but does not reserve it. If tracks or clips are inserted, removed, or moved before sort_session runs, preview again—the apply step uses current zero-based indices.

`sort_session`

This tool takes a fresh organization snapshot, builds the deterministic plan, and immediately applies it.

Organize everything with the defaults:

{}

Color tracks only, leaving names and clips untouched:

{
  "rename_tracks": false,
  "recolor_tracks": true,
  "normalize_clips": false
}

Normalize clip names and colors while preserving existing track names and colors:

{
  "rename_tracks": false,
  "recolor_tracks": false,
  "normalize_clips": true
}

A successful result looks like:

{
  "status": "organized",
  "changed": {
    "changed_tracks": 12,
    "changed_clips": 37
  },
  "categories": {
    "drums": 4,
    "bass": 1,
    "music": 5,
    "vocals": 1,
    "fx": 1
  }
}

The changed_tracks and changed_clips fields count operations applied, not value-level differences. They may therefore be nonzero even when a repeated run writes the same names and colors.

Idempotency and Undo

Track naming is idempotent: recognized old prefixes are stripped before the current prefix is added, so repeated runs do not produce names such as 10 DRM - 10 DRM - Kick. Generated clip names cease to be generic after the first run, and all chosen colors are stable. Repeating the same call against an unchanged Set produces the same plan.

The Remote Script groups the apply operation with Live’s begin_undo_step/end_undo_step API when that API is available. In supported Live versions, one Undo restores all track and clip edits from the call. Save or preview first when working in a critical Set. On a Live version that does not expose the undo-step API, the edits can still be applied but the one-step Undo guarantee does not apply.

Scope, errors, and caveats

The organizer processes song.tracks: normal audio tracks, MIDI tracks, and group tracks. Return tracks and the Master track are not included.
It changes names and colors only. It does not move tracks, create groups, reorder clips, alter routing, modify devices, or edit MIDI/audio content.
Classification uses metadata available in the snapshot; it does not listen to or analyze audio.
All indices are zero-based. An invalid track index during apply raises an error. A Session clip that disappeared or an out-of-range clip index is skipped; the same is true for an Arrangement clip that can no longer be resolved.
Because application is sequential, an error after earlier operations may leave earlier edits applied. Where supported, the encompassing Ableton Undo step can restore them.
Connection, timeout, Remote Script, and Live API failures are returned as plain strings beginning with Error previewing session sort: or Error sorting session: rather than as the normal JSON result.
The classification summary contains only categories represented in the current Set; zero-count categories are omitted.

Recommended workflow

Save the Live Set.
Call preview_session_sort with the options you intend to use.
Inspect any tracks whose names or device roles are ambiguous; rename them more specifically if needed.
Call sort_session with the same options.
If the result is not what you wanted, use Undo once when your Live version supports grouped undo.