Loom

Loom is a measurement-based production system for Ableton Live by Şenol Şahan / SubverseLab: a local MCP server that reads your own .als projects and library, answers with counts instead of guesses, and writes MIDI, device chains, automation and arrangement markers into a running Live session, verifying every write by reading it back.

Canonical home: https://subverselab.com/loom · Cite: CITATION.cff · Licence: AGPL-3.0-or-later · Attribution: NOTICE.

Why it exists

Ask a general-purpose model what belongs on a kick drum and it answers with confidence, having never heard a record you made. Loom replaces that guess with evidence from three places: your own project archive (which devices you actually chain, which samples you actually reach for), real released records (genre evidence measured from audio, not described from memory), and the Live set that is open right now. Where the evidence runs out, a tool returns nothing and says so. Nothing is emulated, nothing is retried on an uncertain outcome, and every write is a dry run until you approve it.

There is one connection to Live: the Loom extension, an Ableton Extension running inside Live 12.4 beta. No Control Surface, no automatic fallback, no second writer path.

What is inside

No layer produces a guess: with no evidence there is no suggestion, what the SDK cannot do is not emulated, and every writing tool is a dry run by default.

Architecture, the canonical call flow and the bridge protocol: Docs/ARCHITECTURE.md.

Install (one path)

python3 install.py            # installs
python3 install.py --check    # changes nothing, reports state

install.py:

1. Registers Loom with every MCP client it finds (Claude Desktop, Claude Code, Antigravity), backing up each config; it is safe to re-run.
2. Prepares the extension package (extension/dist/loom.ablx, built if the toolchain is present) and compares the version and bridge protocol of the extension installed in Live with this checkout. Live shows it as Loom, id subverselab.loom. An installed legacy package (loom.sensei-midi-writer) is reported: the MCP never sends it a mutation (LEGACY_EXTENSION).
3. Builds the catalogs from your own stock Ableton library.

Live's own step is a single one: add the .ablx in Live 12.4 beta's Extensions settings and restart Live. The extension opens a file bridge in its own storage directory; the MCP locates that bridge on every call.

The same server is packaged as an MCP bundle on the release page (loom-<version>.mcpb, described by server.json).

Versions are three different things: the package version is written once, in extension/manifest.json (package.json must match; the build verifies it); the bridge protocol is loom.bridge/3; the SDK API is 1.0.0.

Connection diagnosis (one path)

The MCP tool live_bridge_status reports which bridge it is talking to and why, the age of the state, the session id, the capabilities the extension publishes, mutations_allowed, the protocol verdict (OK / UPGRADE_REQUIRED / PROTOCOL_MISMATCH / STALE_STATE / NO_STATE), the journal's condition and what is queued or in flight. python3 install.py --check prints the same in a terminal.

An old extension (0.1.0 / 0.2.0, publishing no protocol) is read but never written: every mutation is refused with UPGRADE_REQUIRED before a request file is written. A package installed under the legacy id is treated the same (LEGACY_EXTENSION); once the new one is installed and the old one removed from Live, the old journal is carried over with live_command op=journal_import (nothing forgotten, nothing deleted). More than one Loom bridge in sight is AMBIGUOUS_BRIDGE. LOOM_BRIDGE_ROOT exists for tests only.

Supported MCP tools

The extension's single in-Live user command, "Loom: Generate" (right-click, Session slot), goes through the same write_clip implementation and the same ownership ledger: a clip Loom did not write is never overwritten.

Kits and presets

The SDK does not load presets (.adg / .adv). Loom does not call this "impossible"; it separates the paths:

• A named kit: project_build(kit="Boom Bap Kit") or a path to an .adg. The kit is read from the preset's own XML (pads, notes, names, sample files; Sensei's .adg reader), the files are resolved on this machine, and the pads are rebuilt in the extension as chain + Simpler + sample. The answer states what was carried over and what was not: per-pad effects, macros, choke groups, Simpler parameters, return chains. This is not loading the preset as is, and it is never presented as such.
• A kit from samples: live_command op=build_drum_kit pads=[{note, sample}].
• An instrument preset (bass / chord): the SDK cannot load it. Either a native device through device_map (Operator, Electric, Wavetable, …), or you load the preset in Live yourself and re-run the same plan; the channel is adopted and its device read from state. The answer lists both routes under needs_preset.
• Drum notes onto the kit's pads: Sensei's drum evidence is in GM pad layout; on a kit such as 77–92 the notes are mapped by pad role (kick / snare / hat, pad_mapping: by_role), unmappable roles are dropped and reported, and with no notes left no clip is written (no_notes_for_pads).
• Simplification is explicit: with tracks=[...] and device_map the answer's simplification block says which channels were dropped and why, and which device stands in for which preset. Empty channels from the template are left alone.
• The file path (B): writers that work on the .als (automation_write, drumbuss_build, chain_apply) change the set on disk; the open set is not touched and must be reopened. Preset XML is never hand-converted into a set; that is Live's job.

Not supported, because of the SDK

Extensions SDK 1.0.0-beta.1 does not provide the following. Loom does not emulate them; it answers UNSUPPORTED_BY_SDK with the name of the missing capability, before any request file is written:

• transport (play / stop / position) → live_command op=transport, mix_capture follow_transport
• writing the song key → live_command op=set_key; the project_build step is reported as UNSUPPORTED_BY_SDK
• loading presets / the browser → create_midi_track only adds a native device with its default preset (not_loadable_in_extension); kits are rebuilt (above), instruments go through device_map or a user step
• time signature → bar-to-beat conversion asks for an explicit beats_per_bar, reads it from the .als when given one, and otherwise says it assumed 4/4 in beats_per_bar_source
• metering, recording (record mode / resampling) → mix_capture method="resample", the capture_* ops

Reported to Ableton through Centercode on 2026-09-03.

The bridge contract (short)

Every answer from Live carries a structured outcome: {kind: applied|refused|failed|indeterminate, code, applied, verified, side_effects, next_step}. The MCP status derives from it: OK, REFUSED_IN_LIVE (Live untouched), FAILED_IN_LIVE (attempted, previous content restored), INDETERMINATE (may have applied; side effects and the safe next step are in the answer), NOT_CONSUMED, INVALID_RESULT. An uncertain outcome is never retried automatically, anywhere.

Keyed requests (build steps, idempotency_key) are journaled before the mutation: same key + same content → the stored result; different content → a conflict; another session → refused; half-finished → INDETERMINATE. With the journal missing or corrupt, keyed mutations are refused and the answer says what to do; deleting the journal is never the advice. Details in Docs/ARCHITECTURE.md.

Tests

./scripts/check_ci.sh    # needs neither Ableton nor personal data; CI runs this
./scripts/check_all.sh   # everything; needs a real Ableton install

check_ci.sh counts every suite as passed, failed or skipped; a suite with a missing dependency is never counted as passed. The extension's own queue code (bridge.ts) runs both on its own (npm run test:bridge) and as the real consumer opposite the MCP (test_bridge_consumer_real.py); the Python fake exists for speed and is not protocol proof on its own.

Tests use temporary directories and isolated fixtures; they never touch a real Live, the installed extension or user data. The Ableton Extensions SDK is not redistributable, so the hosted runner cannot typecheck the extension; that job is marked skipped, never passed.

The real-Live acceptance script is extension/tools/measure_bridge.py (it writes into the running Live's open set; run it on an empty set).

Data policy

This repository ships code and fixtures, never measurements. Presetor's device-chain evidence, AISoundDesigner's palette and Sensei's catalogs are generated from the user's own projects and Ableton installation; none of it is in the repository. On a clean clone the tests run on synthetic fixtures, and every answer names its origin in data_source: measured or synthetic_fixture.

python3 scripts/extract_device_chains.py --out Presetor/data/measured_device_chains.json
python3 scripts/extract_sound_sources.py --out AISoundDesigner/data/measured_sound_sources.json
python3 scripts/setup_scan.py --check      # catalogs: what is there, what is missing

Status and known limits

• Real-Live acceptance passed on 2026-09-07. Starting from an empty set it opened real .adg / .adv presets, resolved the pads (16/16), wrote MIDI and locators; after save and reopen everything was in place. Open edge: delete_track / delete_locator, added in extension 0.4.4 (2026-09-11), are tested headless only; their real-Live acceptance is still to come. Version and acceptance claims are updated together with extension/manifest.json.
• Rendering needs Live's audio engine; render_plan says what should come out, render_verify says whether what came out matches.
• Automation writing (on the file) covers mixer and device parameters; no clip envelopes.
• Tool timeouts are not hard (a Python thread cannot be killed); a call that timed out never writes another request to Live.
• Because the SDK cannot read a clip's automation, colour or launch settings, replace_owned only replaces the same object in place; a replacement that would need a delete is refused. No full-preservation guarantee is claimed; this narrow policy is the guarantee.
• The journal is not exactly-once: work whose application is unknown is counted neither as applied nor as not applied; reading the state is the caller's job.
• render_verify and audio measurement need soundfile / numpy; every other tool runs on macOS's own Python.

Gap log: Docs/MISSING_CONTROLS_LOG.md (its opening note separates historical entries).

Copyright and attribution

© Şenol Şahan / SubverseLab. Free software under the GNU AGPL v3 or later: use, modify and redistribute it, keep the copyright and the NOTICE file, publish the source of any modified version you distribute or run as a service, and do not strip the _source field the server puts in every answer. Canonical home: https://subverselab.com/loom . For written or academic citation, CITATION.cff.