Ableton For Ai

AI 向け Ableton

重要

AI エージェントの方へ： このプロジェクトに取り組む前に、詳細な技術情報とプロトコル仕様について AGENTS.md をお読みください。

Ableton for AI は、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：オーディオ要約。LUFS、ピーク、RMS、10ms フレーム、検出されたトランジェント、legend フィールドを含む簡潔な分析データ（JSON）です。
• ableton://stems/{track_name}/spectrogram：視覚的な分析。周波数を視覚的に確認するための、対数周波数スペクトログラム画像（WebP）です。
• ableton://stems/available/summaries：オーディオ要約を利用できるすべてのトラックを検出するためのリソースです。
• ableton://stems/available/spectrograms：スペクトログラムを利用できるすべてのトラックを検出するためのリソースです。

---

始め方

1. 環境を準備する

AbletonOSC をインストールする

このプロジェクトは、Ableton Live との通信に AbletonOSC を使用します。

• AbletonOSC をダウンロードしてインストールします。
• Ableton Live の Link/Tempo/MIDI 設定で、コントロールサーフェスとして追加する手順に従います。

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 の RELEVANT_DEVICE_NAMES に、Ableton 上で表示されるプラグインの正確な名前を追加します。

2. パラメーターを自動入力する（Options.txt の方法）

デフォルトでは、Ableton Live はサードパーティ製プラグインのパラメーター数がパラメーター数のしきい値（_PluginAutoPopulateThreshold）を64 未満（デフォルト）にしている場合にのみ公開します。詳細はこちらを参照してください。 値を 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 を直接サポートしていない LLM（ChatGPT や Claude Web Interface など）に最適です。同じ分析パイプラインをローカルで実行し、任意のチャットボットにアップロードできるファイルとして結果を出力します。

利用可能なコマンド

オーディオの完全な分析（要約＋スペクトログラム＋完全な分析 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 ライセンスのもとでライセンスされています。

---