Ableton For Ai

面向 AI 的 Ableton

重要

面向 AI Agent： 开始使用本项目之前，请阅读 AGENTS.md，了解详细的技术背景和协议规范。

面向 AI 的 Ableton 是 DAW 与 AI 模型之间的桥梁。它通过实现 Model Context Protocol (MCP) 并导出详细的项目数据，让 AI 模型能够听到并看到 Ableton 项目。

它能做什么？

将 Ableton Live 直接连接到支持 MCP 的 AI 客户端（例如 Claude Desktop、Cursor 或 Cline）。AI 可以实时检查、分析，甚至修改你的项目。

内置工具：

• get_overview：会话发现。提供速度、定位标记，以及包含当前混音器状态（音量、声像等）的所有音轨列表。
• get_track：音轨检查。提供单条音轨的全面数据：元数据、完整的设备链，以及所有设备参数（包含便于 UI 阅读的字符串）。
• get_tracks：批量音轨检查。通过一次并行调用，查询指定范围内音轨的完整数据。
• analyze_stems：深度音频分析。触发生成所有音轨的音频摘要（.summary.json）和频谱图（.spectrogram.webp）。
• set_track_volume / set_track_panning：混音器控制。远程调整音轨推子和声像。
• set_device_parameter：远程控制。精确调整项目中任意设备的任意参数。

内置资源：

• ableton://stems/{track_name}/summary：音频摘要。精简的分析数据（JSON），包含 LUFS、峰值、RMS、10 ms 帧、检测到的瞬态，以及一个 legend 字段。
• ableton://stems/{track_name}/spectrogram：视觉分析。对数频率频谱图像（WebP），用于视觉检查频率。
• ableton://stems/available/summaries：发现资源，列出所有可用音频摘要的音轨。
• ableton://stems/available/spectrograms：发现资源，列出所有可用频谱图的音轨。

---

如何开始？

1. 准备环境

安装 AbletonOSC

本项目依赖 AbletonOSC 与 Ableton Live 通信。

• 下载并安装 AbletonOSC。
• 按照其中的说明，在 Ableton Live 的 Link/Tempo/MIDI 设置中将其添加为 Control Surface。

安装 ableton-for-ai

选项 A：uv（推荐）

uv 可让你直接运行服务，无需进行全局安装：

brew install uv          # macOS (Homebrew)
# or: curl -LsSf https://astral.sh/uv/install.sh | sh   (macOS/Linux)
# or: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  (Windows)

选项 B：pip

需要 Python 3.11+（python.org 或 brew install python）：

pip install ableton-for-ai

2. 连接到聊天机器人（MCP 客户端）

将服务添加到 MCP 客户端配置中（例如 Claude Desktop、Cursor 或 Cline）。

使用 uvx（如果已安装 uv）

{
  "mcpServers": {
    "ableton-for-ai": {
      "command": "uvx",
      "args": ["ableton-for-ai"],
      "env": {
        "STEMS_SOURCE_DIR": "/path/to/your/exported/stems"
      }
    }
  }
}

使用 pip（如果通过 pip 安装）

{
  "mcpServers": {
    "ableton-for-ai": {
      "command": "ableton-for-ai",
      "env": {
        "STEMS_SOURCE_DIR": "/path/to/your/exported/stems"
      }
    }
  }
}

说明

STEMS_SOURCE_DIR 必须指向导出音频分轨所在的文件夹。你需要在 Ableton Live 中手动导出分轨（例如，选择各个音轨后使用“Export Audio/Video”），因为目前没有可用于触发导出的 OSC API。音频分析工具（analyze_stems）会在此目录中查找文件。

配置文件应放在哪里

• Claude Desktop（macOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop（Windows）： %APPDATA%\Claude\claude_desktop_config.json
• Cursor / Cline： 请参阅各自的 MCP 文档。

保存配置后，重启 MCP 客户端。

3. 使用

连接后，你可以向 AI 询问项目状态。AI 会使用包含的工具和资源，直接从 Ableton 获取数据。

音频分析： 请先从 Ableton Live 导出分轨（例如，通过 File → Export Audio/Video 并选中单独的音轨），保存到你配置的 STEMS_SOURCE_DIR。此步骤必须手动完成，因为没有可用于触发导出的 API。

复杂任务（例如，混音反馈）： 向聊天机器人提供项目背景。一个不错的起始提示词应包含曲风、目标，以及导出分轨的起始位置（节拍或定位标记）。请参阅 agent-templates/mix-engineer.md，其中有现成的提示词模板。

提示词示例：

• “当前速度是多少？我有多少条音轨？”
• “检查我的 Lead Synth 音轨上的 EQ 设置。”
• “展示混音器状态概览。”
• “分析这些分轨，告诉我是否存在频率冲突。”
• “显示 ‘Kick’ 音轨的频谱图。”

---

⚙️ 配置

你可以通过设置环境变量或编辑 config.py（从源代码运行时）来自定义服务行为。

变量	默认值	描述
LOG_LEVEL	"INFO"	日志详细程度（INFO 或 DEBUG）。
BASE_OUT_DIR	auto	分析输出的存储位置。如果设置了分轨目录，默认为 {STEMS_SOURCE_DIR}/ableton-for-ai-out；否则默认为 ~/.ableton-for-ai/out。可使用绝对路径覆盖。
STEMS_SOURCE_DIR	"./stems"	导出分轨所在路径。
PREFERRED_AUDIO_FORMAT	"mp3"	要分析的音频格式（mp3 或 wav）。
SPECTROGRAM_QUALITY	90	WebP 频谱图质量（1-100）。
RELEVANT_DEVICE_CLASSES	{"Eq8", "Compressor", ...}	要纳入提取的 Ableton 设备类列表。
RELEVANT_DEVICE_NAMES	{"Pro-Q 4"}	要纳入的特定插件名称列表。

---

🔌 使用自定义 VST / 插件

1. 注册插件名称

在 config.py 中，将插件在 Ableton 中显示的准确名称添加到 RELEVANT_DEVICE_NAMES。

2. 自动填充参数（Options.txt 技巧）

默认情况下，只有当第三方插件的参数数量阈值（_PluginAutoPopulateThreshold）低于 64（默认值）时，Ableton Live 才会公开该插件的参数，参见此处。 你可以将此值改为 128，并希望你喜欢的自定义 VST 能够显示出来。如果参数仍未显示，因为参数数量过多（例如 Fab Filter Pro Q 4）， 你必须在 ableton 中配置这些参数。

在 Options.txt 中添加 -_PluginAutoPopulateThreshold=128，强制 Ableton 自动公开参数：

• Mac： ~/Library/Preferences/Ableton/Live [Version]/Options.txt
• Windows： %AppData%\Ableton\Live [Version]\Preferences\Options.txt

Mac 终端命令

要在 Mac 上快速完成设置，可以使用以下命令（将 [Version] 替换为你实际使用的 Live 版本，例如 12.3.6）：

# 1. Navigate to the Preferences folder
cd ~/Library/Preferences/Ableton/Live\ 12.3.6/

# 2. Create the Options.txt file (if it doesn't exist)
touch Options.txt

# 3. Append the setting to the end of the file
echo "-_PluginAutoPopulateThreshold=128" >> Options.txt

或者在文本编辑器中打开该文件并手动添加设置，例如：

idea ~/Library/Preferences/Ableton/Live\ 12.3.6/Options.txt

---

📂 CLI：分析并上传（无需 MCP）

此方法非常适合不直接支持 MCP 的大模型（例如 ChatGPT 或 Claude 网页界面）。它会在本地运行相同的分析流程，并将结果导出为文件，供你上传到任何聊天机器人。

可用命令

完整音频分析（摘要 + 频谱图 + 完整分析 JSON）：

ableton-for-ai-cli analyze_stems

仅提取 Ableton 项目元数据（音轨、设备、参数）：

ableton-for-ai-cli extract_ableton_project_data

完整流程（音频分析和项目数据提取）：

ableton-for-ai-cli analyze_stems_and_extract_ableton_project_data

说明

OSC 守护进程会自动启动，无需手动启动。

输出

结果将存储在 ./out 目录中，并按子文件夹分类：

• ./out/project/：包含 Ableton 项目 JSON 文件。
• ./out/summaries/：包含经过压缩的音频分析 JSON（针对 AI 优化）。
• ./out/spectrograms/：包含每个分轨的频谱图 WebP 图片。
• ./out/analyses/：包含完整的高分辨率分析 JSON。

使用 AI 混音（手动上传）

1. 将分轨从 Ableton 导出到 STEMS_SOURCE_DIR。
2. 运行 ableton-for-ai-cli analyze_stems 生成分析文件。
3. 将 out 文件夹中的文件（频谱图 .webp + 分析 .json）拖放到聊天机器人中。
4. 使用如下提示词：

I have attached several audio analysis files (spectrograms and energy analysis).
The given files only reflect a part of the project timeline, see below in Part.

Genre: Drum and Bass
Goal: Improve the clarity of the lead synth and make sure it doesn't clash with the vocals.
Part: The *.analysis.json and *.spectrogram.webp ONLY reflect the part starting at beat 113.

Please analyze the attached files and provide concrete mixing advice.

---

🛠️ 开发与贡献

本地设置（从源代码开始）

git clone https://github.com/peterkolbe/ableton-for-ai.git
cd ableton-for-ai
uv sync

从源代码运行 MCP 服务：

{
  "mcpServers": {
    "ableton-for-ai": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ableton-for-ai",
        "run",
        "mcp_server_ableton.py"
      ],
      "env": {
        "STEMS_SOURCE_DIR": "/path/to/your/stems"
      }
    }
  }
}

从源代码运行 CLI 命令：

uv run ableton_client.py analyze_stems
uv run ableton_client.py extract_ableton_project_data
uv run ableton_client.py analyze_stems_and_extract_ableton_project_data

MCP Inspector（调试）

MCP Inspector 可用于在开发过程中测试和调试 MCP 服务。

直接通过终端启动：

npx -y @modelcontextprotocol/inspector uv '--directory /absolute/path/to/ableton-for-ai run mcp_server_ableton.py'

或者不使用预设启动 Inspector，并手动配置：

npx -y @modelcontextprotocol/inspector

然后在 Inspector UI 中输入以下内容：

• 命令： uv
• 参数： --directory /absolute/path/to/ableton-for-ai run mcp_server_ableton.py

代码检查与格式化

uv run ruff check .
uv run ruff format .

发布到 MCP Registry

如需向官方 MCP Registry发布新版本：

brew install mcp-publisher
mcp-publisher login github
mcp-publisher publish

验证发布状态：

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.peterkolbe/ableton-for-ai"

发布前，请务必更新 server.json 和 pyproject.toml 中的 version。

---

⚠️ 已知限制与故障排查

自动化跟踪

• 不支持： 导出内容不包含自动化数据。
• 技术原因： 底层的 AbletonOSC 脚本在当前版本中无法可靠地提供自动化状态或控制点。

---

📄 许可证

本项目采用 MIT 许可证。

---