Loom by SubverseLab

Loom

Loom 是由 Şenol Şahan / SubverseLab 开发的、基于测量的 Ableton Live 生产系统：一个本地 MCP 服务，可读取你自己的 .als 项目和素材库，依据计数而非猜测作答，并将 MIDI、设备链、自动化和编排标记写入正在运行的 Live 会话，再通过读回数据验证每次写入。

规范主页：https://subverselab.com/loom · 引用：CITATION.cff · 许可证：AGPL-3.0-or-later · 署名：NOTICE。

为什么要开发它

问一个通用模型底鼓上应该放什么，它会自信地回答，尽管它从未听过你制作的任何一首唱片。Loom 用三个来源的证据取代这种猜测：你自己的项目存档（你实际串联了哪些设备、实际会选用哪些采样）、真实发行的唱片（从音频测得的流派证据，而非凭记忆描述），以及当前打开的 Live 工程。证据不足时，工具会返回空结果并明确说明。它不会模拟任何内容，不会在结果不确定时重试，并且每次写入在你批准前都是干运行。

Loom 只有一种与 Live 的连接：Loom 扩展，即在 Live 12.4 beta 中运行的 Ableton 扩展。没有 Control Surface，没有自动回退，也没有第二条写入路径。

包含内容

层	作用
Sensei	基于锁定且经过哈希验证的数据集生成 MIDI 变化（鼓组／贝斯／和弦）
ArrangementGPS	根据提示词生成项目计划：速度、调性、流派、通道、段落（Node）
AIMixMaster	.als 检查、增益分级、片段对齐、鼓组总线、自动化写入（直接写入文件）
Presetor / AISoundDesigner	根据用户自己的项目测得的设备链和声音调色板
MusicalIntelligence	从真实唱片测得的流派证据；针对项目提供的乐段建议
Mix Check / SampleAgent	根据已发行母带的配置文件测量音频；YouTube → 切片采样包；一个挖掘唱片的 Agent
Loom extension	Live 内部的 Ableton 扩展：MCP 与运行中工程的唯一连接
mcp_server	通过 stdio JSON-RPC 提供 45 个工具、资源、提示词、进度报告和取消功能

没有任何层会生成猜测：没有证据就不会提供建议；SDK 无法实现的功能不会被模拟；所有写入工具默认都是干运行。

架构、规范调用流程和桥接协议： Docs/ARCHITECTURE.md。

安装（一步完成）

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

install.py：

1. 将 Loom 注册到找到的所有 MCP 客户端（Claude Desktop、Claude Code、Antigravity），并备份每个配置；可以安全地重复运行。
2. 准备扩展包（extension/dist/loom.ablx，如果存在工具链则会构建），并将 Live 中已安装扩展的版本和桥接协议与当前检出版本进行比较。Live 中显示的名称为 Loom，ID 为 subverselab.loom。如果检测到已安装的旧版包（loom.sensei-midi-writer），会报告该情况：MCP 不会向它发送任何修改指令（LEGACY_EXTENSION）。
3. 根据你自己的 Ableton 库存库构建目录。

在 Live 中只需完成一个步骤：在 Live 12.4 beta 的“Extensions”设置中添加 .ablx，然后重启 Live。扩展会在自己的存储目录中打开文件桥接；MCP 每次调用时都会定位该桥接。

同一服务也打包为 MCP bundle，可在发布页面获取（loom-<version>.mcpb，由 server.json 描述）。

版本涉及三个不同的部分：包版本仅在 extension/manifest.json 中声明一次（package.json 必须与之匹配，构建时会进行验证）；桥接协议为 loom.bridge/3；SDK API 为 1.0.0。

连接诊断（一步完成）

MCP 工具 live_bridge_status 会报告它连接的桥接及原因、状态的时效、会话 ID、扩展公布的能力、mutations_allowed、协议判定结果（OK / UPGRADE_REQUIRED / PROTOCOL_MISMATCH / STALE_STATE / NO_STATE）、日志的状态，以及排队或正在执行的内容。运行 python3 install.py --check 可在终端中打印相同信息。

旧版扩展（0.1.0 / 0.2.0，未公布协议）可以读取，但绝不写入：每个修改请求都会在写入请求文件之前被拒绝，并返回 UPGRADE_REQUIRED。以旧版 ID 安装的包也会被同样处理（LEGACY_EXTENSION）；安装新版并从 Live 中移除旧版后，可通过 live_command op=journal_import 携带旧日志（不会遗忘任何内容，也不会删除任何内容）。如果检测到多个 Loom 桥接，则会返回 AMBIGUOUS_BRIDGE。LOOM_BRIDGE_ROOT 仅用于测试。

支持的 MCP 工具

类型	工具	验证依据
通过 Live（扩展）	live_state、live_bridge_status、live_command（set_tempo、set_mixer、set_device_parameter、list_device_parameters、create_locator、create_midi_track、import_audio_clip、render_pre_fx、drum_pads、build_drum_kit、journal_import、delete_track、delete_locator）、midi_write_arrangement、midi_write_to_live（会话片段）、crate_to_live、mix_from_live、project_build、midi_generate（auto_write）	mcp_server/tests/test_bridge_consumer_real.py（真实的 bridge.ts）、test_extension_path.py、extension/tests/bridge.test.ts
不依赖 Live 的引擎	project_*、automation_*、drumbuss_*、chain_*、render_*、palette_read、library_search、genre_evidence、part_suggest、plan_create、plan_verify、projects_arrangement_shapes、mix_measure/analyze/profiles、crate_fetch/read/spots/chop/agent、setup_scan、gap_record	mcp_server/tests/test_mcp_tools.py（通过 stdio 测试的 45 个工具）以及各引擎自己的 pytest 测试套件
按需使用操作系统级功能	live_project（打开 / 关闭 Live，以及查看其状态；已通过 Live 自身的日志验证；更改工程会重启扩展宿主）	test_live_project.py
绑定具体机器	mix_capture（method="tap"：通过 LaunchServices 启动为 LiveTap.app 的 Core Audio 进程监听器；macOS 会将“屏幕与系统音频录制”权限授予 LiveTap 条目，而不是运行 MCP 的应用；2026-09-06 对正在播放的 Live 进行测量）	仅在真实机器上

扩展在 Live 内提供的唯一用户命令 “Loom: Generate”（右键点击会话槽位）会调用相同的 write_clip 实现和所有权账本：Loom 未写入的片段绝不会被覆盖。

套件与预设

SDK 不会加载预设（.adg / .adv）。Loom 不会将其称为“做不到”，而是将处理路径分开：

• 命名套件：project_build(kit="Boom Bap Kit")，或指定 .adg 文件的路径。套件会从预设自身的 XML 中读取（鼓垫、音符、名称、采样文件；使用 Sensei 的 .adg 读取器），在这台机器上解析文件路径，并在扩展中将鼓垫重建为链 + Simpler + 采样。回复会说明保留了哪些内容，以及未保留哪些内容：每个鼓垫的效果、宏、闭音组、Simpler 参数、返回链。这并非原样加载预设，也绝不会被描述成原样加载。
• 从采样创建套件：live_command op=build_drum_kit pads=[{note, sample}]。
• 乐器预设（低音 / 和弦）：SDK 无法加载。可以通过 device_map 使用原生设备（Operator、Electric、Wavetable 等），也可以由你在 Live 中加载预设，然后重新运行相同的计划；系统会接管该通道，并从状态中读取其设备。回复会在 needs_preset 下列出这两种路径。
• 将鼓音符写入套件的鼓垫：Sensei 的鼓点证据采用 GM 鼓垫布局；对于 77–92 之类的套件，音符会按鼓垫角色（底鼓 / 军鼓 / 踩镲，pad_mapping: by_role）进行映射。无法映射的角色会被丢弃并报告；如果没有剩余音符，则不会写入片段（no_notes_for_pads）。
• 明确说明简化内容：使用 tracks=[...] 和 device_map 时，回复中的 simplification 区块会说明哪些通道被移除及原因，以及哪个设备替代了哪个预设。模板中的空通道会保持不变。
• 文件路径（B）：直接处理 .als 的写入器（automation_write、drumbuss_build、chain_apply）会更改磁盘上的工程；不会触碰已打开的工程，必须重新打开。绝不会手动将预设 XML 转换成工程；这是 Live 的工作。

SDK 不支持的功能

Extensions SDK 1.0.0-beta.1 不提供以下功能。Loom 不会 模拟这些功能；在写入任何请求文件之前，它会使用缺失功能的名称返回 UNSUPPORTED_BY_SDK：

• 传输控制（播放／停止／位置）→ live_command op=transport、mix_capture follow_transport
• 写入歌曲调性 → live_command op=set_key；project_build 步骤会报告为 UNSUPPORTED_BY_SDK
• 加载预设／浏览器 → create_midi_track 只会添加带默认预设的原生设备（not_loadable_in_extension）；套件会重新构建（见上文），乐器则通过 device_map 或用户步骤处理
• 拍号 → 小节到节拍的转换需要显式指定 beats_per_bar；如果提供了 .als 文件，则从中读取；否则会在 beats_per_bar_source 中说明假设拍号为 4/4
• 电平表、录音（录音模式／重新采样）→ mix_capture method="resample"、capture_* 操作

已于 2026-09-03 通过 Centercode 向 Ableton 报告。

桥接契约（简要）

Live 返回的每个答复都带有结构化的 outcome： {kind: applied|refused|failed|indeterminate, code, applied, verified, side_effects, next_step}。 MCP 状态由此派生：OK、REFUSED_IN_LIVE（未修改 Live）、 FAILED_IN_LIVE（已尝试，之前的内容已恢复）、INDETERMINATE（可能已应用；答复中包含副作用和安全的后续步骤）、 NOT_CONSUMED、INVALID_RESULT。任何不确定的结果都不会在任何地方自动重试。

带键的请求（构建步骤、idempotency_key）会在变更之前写入日志：相同的键和相同的内容 → 返回已存储的结果；不同的内容 → 冲突；来自其他会话 → 拒绝；未完成 → INDETERMINATE。如果日志缺失或损坏，则会拒绝带键的变更，并在答复中说明如何处理；绝不会建议删除日志。详情见 Docs/ARCHITECTURE.md。

测试

./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 会将每个测试套件计为通过、失败或跳过；依赖缺失的套件绝不会计为通过。扩展自身的队列代码 （bridge.ts）既会独立运行（npm run test:bridge），也会作为真实使用方与 MCP 对接运行（test_bridge_consumer_real.py）；Python 模拟程序是为提高速度而设，不能单独证明协议行为。

测试使用临时目录和隔离的测试夹具；绝不会触及真实的 Live、已安装的扩展或用户数据。Ableton Extensions SDK 不可再分发，因此托管运行器无法对扩展进行类型检查；该任务会标记为跳过，而非通过。

真实 Live 验收脚本为 extension/tools/measure_bridge.py（它会写入正在运行的 Live 中已打开的工程；请在空工程中运行）。

数据政策

此仓库仅包含代码和测试夹具，绝不包含测量数据。Presetor 的设备链证据、AISoundDesigner 的调色板和 Sensei 的目录均根据用户自己的项目和 Ableton 安装生成；这些内容都不在仓库中。克隆后首次运行时，测试使用合成测试夹具，并且每个答复都会在 data_source 中注明其来源：measured 或 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

状态与已知限制

• 已于 2026-09-07 通过真实 Live 验收。 从空白集合开始，打开真实的 .adg / .adv 预设，解析出所有 Pad（16/16），并写入 MIDI 和定位器；保存并重新打开后，一切都已就位。尚待完成： 在扩展 0.4.4（2026-09-11）中添加的 delete_track / delete_locator 目前仅通过无头测试；真实 Live 验收尚未完成。版本与验收声明会随 extension/manifest.json 一起更新。
• 渲染需要 Live 的音频引擎；render_plan 会说明应输出什么，render_verify 会判断实际输出是否符合预期。
• 自动化写入（针对文件）涵盖混音器和设备参数；不包括片段包络。
• 工具超时并非硬性超时（无法终止 Python 线程）；超时的调用绝不会再向 Live 写入请求。
• 由于 SDK 无法读取片段的自动化、颜色或启动设置，replace_owned 只能就地替换同一对象；若替换需要先删除对象，则会拒绝操作。我们不承诺全面保留；本项有限策略即为保证。
• 日志并非严格的恰好一次：应用状态未知的操作既不会计为已应用，也不会计为未应用；读取状态是调用方的责任。
• render_verify 和音频测量需要 soundfile / numpy；其他所有工具均使用 macOS 自带的 Python。

差距记录：Docs/MISSING_CONTROLS_LOG.md（开篇说明将历史条目单独列出）。

版权与署名

© Şenol Şahan / SubverseLab。依据 GNU AGPL v3 or later 提供的自由软件：可使用、修改和再分发，但须保留版权声明和 NOTICE 文件；分发修改版本或将其作为服务运行时，须公开其源代码；不得移除服务端在每个回答中添加的 _source 字段。正式主页： https://subverselab.com/loom 。书面引用或学术引用请参阅 CITATION.cff。