Arrangement Architect

An Ableton Live Extension that turns Session View sketches into readable song blueprints. It scans your Live Set, maps your scenes and track roles, scores the arrangement's health, and generates a section-by-section plan — the map out of the loop swamp.

It is not an AI composer, not a Max for Live device, and not an audio processor. It is a finishing tool for producers who have a strong loop and no song yet.

Score: 84/100 — Strong sketch

Bar   1 ▕███░░░░░░░▏ Intro          8 bars  low    ← Intro
Bar   9 ▕██████░░░░▏ Verse 1       16 bars  medium ← Verse
Bar  33 ▕██████████▏ Chorus        16 bars  high   ← Hook idea
Bar 113 ▕███░░░░░░░▏ Outro          8 bars  low    ← (new)

What it does

• Scan the current Live Set: tempo, tracks, scenes, session clips, arrangement clips, locators.
• Scene Map — density per scene (empty/sparse/medium/dense), inferred sections from scene names (intro, verse, chorus, drop…), default-name and duplicate-name detection.
• Track Role Map — deterministic role inference from track names (drums, bass, vocals, guitar, keys, synth, fx, playback, reference) with user-extensible keywords.
• Arrangement Health — 18 deterministic rules (no intro/outro, loop swamp, no contrast between neighboring scenes, missing breakdown, all-dense, …) rolled into a 0–100 readiness score: Arranged / Strong sketch / Loop swamp / Needs structure.
• Blueprint Generator — four templates (Pop/Rock, Electronic Build/Drop, Experimental/Cinematic, Live Set Flow); your scenes are auto-mapped onto sections by name, density and order, with manual override per section.
• Markdown report — full arrangement report with scene map, roles, health findings, blueprint table, song map and next actions; copy to clipboard or export to a file.
• Safe writes (preview + confirm, never deletes anything):
  • rename scenes to blueprint section names ("01 Intro", "02 Verse 1"…),
  • create empty guide scenes for sections you don't have yet,
  • create locators at section start positions on the timeline,
  • (experimental, default off) color session clips by section.

What it can NOT do (beta SDK limits)

The Extensions SDK (1.0.0-beta.0) has no API for: scene/track colors, reading your current selection, change notifications (hence the Re-scan button), transport/playhead, moving locators, set name, or persistent panels (the UI is a modal dialog launched from right-click context menus). Details with evidence: docs/sdk-capability-audit.md.

Requirements

• Ableton Live beta with the Extensions feature (Preferences → Extensions → enable Developer Mode for development).
• Node.js ≥ 24.14.1 and npm (development only).
• macOS or Windows.

Install / run / build

npm install            # SDK + CLI are vendored in vendor/ (no registry needed for them)

# Development (Live running, .env configured — see .env.example):
npm start              # build + launch in Live's Extension Host

# Production package:
npm run package        # → Arrangement-Architect-0.1.0.ablx
# Install: drop the .ablx into Live's Preferences → Extensions page.

# Quality gates:
npm run typecheck
npm test               # 79 tests, no Ableton required

# No Live around? Run the whole pipeline on mock data:
npm run demo                         # terminal scene map + health + blueprint
npm run demo -- --fixture defaults   # the pure loop-swamp fixture
npm run ui-preview                   # → dist/ui-preview.html, open in a browser

In Live, right-click a scene, clip slot, clip or track → "Arrangement Architect…".

How it decides things

All analysis is deterministic keyword/threshold rules — documented in docs/analysis-rules.md and docs/blueprint-templates.md. No AI, no network, no telemetry, no server. Everything runs locally; the only files it writes are its own preferences and reports you export (both inside the extension's storage folder), and the only Live-Set writes are the ones you preview and confirm.

Safety model

• Every write is previewed as a diff before anything happens.
• More than 5 changes (configurable) requires an explicit confirmation tick.
• The plan is rebuilt against a fresh scan at apply time; if the set changed since the preview, nothing is written and you review again.
• Renames apply as a single undo step. Created scenes/locators are named in a second step (≤ 2 undo steps — an SDK transaction limitation).
• The extension never deletes scenes/tracks/clips, never touches clip content, MIDI, audio, devices, routing or automation.

Project layout

See docs/development.md for architecture, build pipeline, debugging (ExtensionHost.txt) and the manual in-Live test checklist. Product details: docs/product-spec.md. Roadmap: docs/roadmap.md.

Beta disclaimer

The Ableton Extensions SDK is in public beta: APIs may change, and several behaviors (clip color format, locator creation at occupied positions, dialog clipboard access) are explicitly marked unverified in the capability audit and handled defensively. Expect to rebuild against newer SDK drops.

Privacy

Local only. No telemetry, no analytics, no network access at runtime.