Waveform MCP

Tracktion WaveformをLLMエージェントが制御できるようにするMCPサーバーです。Claudeに曲の作成、ミックスのバランス調整、MP3へのレンダリングを依頼すれば、Waveformがそれを実行します。

MCPツール呼び出しによって作曲された64小節のシンセウェーブのインストゥルメンタル — ドラム、ベース、2つのパッド、カウンター、アルペジオ、リード。セクションマーカー、テンポオートメーション、サイドチェーンポンプ、プレートリバーブ、クリップレベルのフェード、フルマスターチェーン。

このツールでできること

• 107種類のMCPツール：編集ライフサイクル、トラック、MIDI、オーディオクリップ、プラグイン、オートメーション、音楽理論、ミックスバランス、レンダリング、ループライブラリ、VST検出、スキーマキャプチャ、Waveform UI制御など

• 2つのエンドツーエンド作曲ツール — compose_lofi_track および compose_synthwave_track — 完全にアレンジ、ミックス、レンダリングされた楽曲を作成

• 1つのアンビエント作曲ツール — compose_rainstorm — 雨、風、雷のサウンドスケープ用

• 音楽理論知識レイヤー — スケール、コード進行、カデンツ、楽曲形式、ボイスリーディングのルール、ジャンルごとのミックスバランス基準レベル

• メモリ内モデルとWaveformの .tracktionedit XML間の検証済みラウンドトリップ

• クリップレベルのフェード、ゲイン、オフセット、オートメーションカーブ — LLMが音楽的に反復するために使用できる実証済みのプリミティブ

• 信頼性の高いワークフローサイクル — 作曲 → 書き込み → ファイル経由で再読み込み → 保存状態へ戻す → 試聴 → 微調整

ステータス

Windows + Waveform 13でエンドツーエンドで動作します。macOS / Linuxのパスはコンテンツ検出（プリセット、ループライブラリ、VSTリスト）には存在しますが、UI制御は現時点ではUIA / pywinautoを使用したWindows専用です。

Claudeとの約30時間のヒューマン・イン・ザ・ループ反復を通じて構築およびテストされました。両方の作曲ツールでMP3へのレンダリングが複数回行われ、ユーザーが完成したトラックを確認済みです。

クイックスタート

インストール

cd "C:\path\to\waveform MCP"
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .

Claudeへの接続（Code、Desktop、または任意のMCPクライアント）

~/.claude.json またはクライアントのMCP設定:

{
  "mcpServers": {
    "waveform": {
      "command": "waveform-mcp"
    }
  }
}

試してみる

Open Waveform, then ask Claude:

  "Use compose_synthwave_track to make a synthwave song,
   save it to my Documents/Waveform folder, and reload it
   in Waveform so I can hear it."

LLMが compose_synthwave_track → waveform_revert_to_saved を呼び出し、再生ボタンを押します。その後、反復します：「ベースの音量を下げて」 → LLMが MIX_BALANCE["synthwave"]["bass"] を更新し、再読み込みします。

アーキテクチャ

4つのレイヤーがあり、それぞれ明確な契約があります：

┌──────────────────────────────────────────────────────────────┐
│  LLM (Claude / any MCP client)                               │
└────────────────────────────┬─────────────────────────────────┘
                             │ MCP stdio
┌────────────────────────────▼─────────────────────────────────┐
│  MCP server (server.py) — 107 tools                          │
└────────────────────────────┬─────────────────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
      ┌──────────────┐ ┌──────────┐ ┌──────────────┐
      │ Edit model   │ │ Knowledge│ │  Waveform    │
      │ (in-memory)  │ │  (data)  │ │  UI control  │
      ├──────────────┤ ├──────────┤ ├──────────────┤
      │ Tracks       │ │ Scales   │ │ pywinauto +  │
      │ Clips        │ │ Chords   │ │ UIA + ffmpeg │
      │ Notes        │ │ Forms    │ │              │
      │ Plugins      │ │ Mix      │ │ Menu invoke  │
      │ Automation   │ │ Velocity │ │ Revert       │
      │ Markers      │ │ Rhythm   │ │ Render→MP3   │
      └──────┬───────┘ └──────────┘ └──────┬───────┘
             │                             │
             ▼                             ▼
   ┌──────────────────┐          ┌────────────────────┐
   │ xml_writer.py    │          │ Waveform 13        │
   │ xml_reader.py    │ ◀──────▶ │ (the running app)  │
   │ ↓ .tracktionedit │          └────────────────────┘
   └──────────────────┘

重要な設計上の選択: モデルはTracktion ValueTreeの1:1のコピーではありません。LLMが操作したい形状であり、保存時にXMLに投影され、読み込み時に戻されます。これにより、LLMにJUCEの内部構造を考えさせるのではなく、ツールをシンプルに保つことができます（audio_clip_import(track_id, file_path, start_beats, length_beats, fade_in_beats, ...)など）。

ツールカタログ

編集ライフサイクル (edit.py)

edit_create · edit_open · edit_save · flush · edit_summary · edit_inspect · undo · narrate

トラック + ミックス (tracks.py)

track_add · track_remove · mix_set · mix_apply_reference · send_add · marker_add · tempo_set · key_set

mix_apply_reference(track_id, genre, role) は、キュレーションされたミックスバランス表（MIX_BALANCE[genre][role]）からdBターゲットを検索します。「キックがアンカー、ベースはその5-6dB下」といったリファレンスを呼び出し可能な形式に凝縮しています。

MIDI (midi.py)

midi_clip_add · midi_notes_add · midi_notes_clear · midi_clip_quantize

オーディオクリップ (audio.py, clips.py)

audio_clip_import ( gain_db, fade_in_beats, fade_out_beats, offset_in_source_beats を含む) clip_list · clip_set · clip_move · clip_resize · clip_duplicate · clip_remove

プラグイン (plugins.py, preset_library.py)

plugin_list · plugin_add · plugin_set_param · plugin_remove plugin_add_reverb (適切なデフォルト設定を持つプレート / ナチュラル / 非線形) plugin_add_drum_kit (サンプラーベース、パッドごとに1つのSOUND) plugin_add_modifier (LFO / エンベロープ / サイドチェーン — Waveformの完全サポート時にスキーマを決定) plugin_discover (knownPluginList64.settings を解析してインストール済みVSTをリストアップ) waveform_preset_list · waveform_preset_read · waveform_plugin_types

オートメーション (automation.py)

automation_add · automation_envelope · automation_clear · automation_list

ターゲット: pan および plugin/<plugin_id>/<param>。ボリュームターゲットはAPIレベルで無効になっています。Waveformのボリュームプラグインは <AUTOMATIONCURVE> スキーマを尊重せず、トラックを無音にしてしまうためです。静的なレベルには mix_set/mix_apply_reference を、フェードには clip_set(fade_in_beats|fade_out_beats) を使用してください。（MCPは target="volume" を拒否し、代替案を示す明確なエラーを返します。）

音楽理論知識 (music_theory.py, music_theory_data.py)

17のクエリツール: theory_scale · theory_modes · theory_diatonic_chords · theory_chord_progression · theory_cadences · theory_song_form · theory_section · theory_genre · theory_arrangement_layers · theory_velocity · theory_rhythm · theory_voice_leading_rules · theory_heuristics · theory_surprise_devices · theory_borrowed_chords · theory_mix_balance · theory_search

これらを支えるデータ:

• 13のスケール（メジャーモード、ハーモニックマイナー、ペンタトニック、ブルースなど）

• 25以上のコード進行（axis_pop, ii_V_I, andalusian, lament_bassなど）

• カデンツ、楽曲形式、役割/密度/ダイナミックプロファイルを持つセクション

• 一般的なBPM、キーの傾向、楽器、特徴的な進行を持つ14のジャンル

• ベロシティ / リズムマップ（スウィング比、アクセントの強弱、ゴーストノートの範囲）

• 13の作曲ヒューリスティック（3の法則、コントラストの必要性、サプライズの割り当てなど）

• 7つのサプライズデバイス（トラックドライバー変調、偽終止など）

• ミックスバランスリファレンステーブル — 7ジャンル × 14役割、完全に注釈付き

作曲ツール (composer.py)

• compose_lofi_track — ドラム、ベース、キーボード、パッド、メロディ、カウンターを備えた32小節のローファイ。セクションを意識したベロシティエンベロープ、テンポオートメーション、ローファイマスターチェーン

• compose_synthwave_track — 7トラックを備えた64小節のシンセウェーブ。9セクション形式（イントロ/Aメロ/サビ/Aメロ/サビ/ブリッジ/ビルドアップ/大サビ/アウトロ）、セクションごとのベースのフィーリング（ハーフタイム / 8分ポンプ / ウォーキング）、セクションごとのアルペジオテーマ、サイドチェーンスタイルのフィルターポンプ、セクションマーカー、クリップフェード

• compose_rainstorm — 雨 + 風 + ローパスされた遠くの雷鳴を備えたアンビエントサウンドスケープ。クリップごとのゲインランダム化、オフセットトリム、トラックFX

レンダリング (render.py, waveform_workflows.py)

waveform_render_export · waveform_render_to_mp3 (バンドルされたffmpeg + libmp3lameを使用)

Waveform UI制御 (waveform_workflows.py)

waveform_new_project · waveform_save · waveform_revert_to_saved (反復ループの鍵) · waveform_close_active_tab · waveform_active_tab · waveform_project_loaded · waveform_menu_invoke · waveform_add_track · waveform_select_track · waveform_insert_clip_on_track · waveform_build_skeleton

アプリライフサイクル (waveform_app.py)

waveform_locate · waveform_status · waveform_launch · waveform_focus · waveform_quit · waveform_settings_dir

ループライブラリ (loops.py)

loop_search (テンポ / 小節数 / 名前で検索) · loop_drop (自動長さ調整、テンポへのフィット)

スキーマキャプチャ (schema_capture.py)

schema_snapshot_current_edit · schema_diff_snapshots · schema_list_snapshots

低レベルUI / デスクトップ (win_input.py, desktop.py)

ウィンドウ管理、UIA検査、キー/クリック送信、スクリーンショットのための18のプリミティブ。

レイアウト

waveform-mcp/
├── src/waveform_mcp/
│   ├── server.py                  MCP server entry (stdio)
│   ├── model.py                   Edit / Track / Clip / Note / AutomationLane dataclasses
│   ├── xml_writer.py              Edit → .tracktionedit
│   ├── xml_reader.py              .tracktionedit → Edit
│   ├── audio_convert.py           ffmpeg-backed MP3→WAV cache for Sampler sources
│   ├── music_theory_data.py       SCALES, PROGRESSIONS, GENRES, MIX_BALANCE, ...
│   ├── events.py                  event bus + JSONL log
│   ├── diff.py                    Edit-diff for change events
│   ├── tools/
│   │   ├── edit.py                Edit lifecycle
│   │   ├── tracks.py              Tracks + mix balance
│   │   ├── midi.py                MIDI clips/notes
│   │   ├── audio.py               Audio clip import
│   │   ├── clips.py               Clip mutators (move, resize, duplicate, set)
│   │   ├── plugins.py             Plugin add + reverb / drum kit / modifier helpers
│   │   ├── automation.py          Automation lanes (pan + plugin params)
│   │   ├── preset_library.py      Factory preset browser
│   │   ├── loops.py               Loop library search + drop
│   │   ├── render.py              Render stubs
│   │   ├── waveform_app.py        App lifecycle
│   │   ├── waveform_workflows.py  UI workflows (revert, render-to-mp3, etc.)
│   │   ├── desktop.py             Generic desktop primitives
│   │   ├── win_input.py           Windows UIA + keystroke primitives
│   │   ├── schema_capture.py      Hand-fixture capture for schema reverse-engineering
│   │   ├── music_theory.py        Theory query tools
│   │   ├── composer.py            compose_lofi_track, compose_synthwave_track, compose_rainstorm
│   │   └── common.py              @op decorator (apply + diff + event)
│   └── preview/
│       ├── app.py                 FastAPI + websocket
│       └── static/                HTML / JS piano-roll
├── tests/
├── docs/
│   ├── img/synthwave_arrangement.png
│   ├── ARCHITECTURE.md
│   ├── EVENT_SCHEMA.md
│   └── EDIT_MODEL.md
├── pyproject.toml
└── README.md

実際に機能する反復ループ

多くの失敗を経て、Waveformを毎回再起動することなく、LLMとユーザーがトラックで共同作業できるループは以下の通りです：

1. Compose / mutate            → composer.compose_*  or clip_set / mix_apply_reference
2. Save to disk                → edit_save / flush  (writes .tracktionedit)
3. Reload in Waveform          → waveform_revert_to_saved
                                  (File → Revert to saved state, auto-confirms popup)
4. User listens                → "turn the arp up"
5. Update MIX_BALANCE or run a clip mutator
6. → goto 2

決定打となったのは、Waveformの ファイル → 保存状態へ戻す メニュー項目の発見でした。これにより、開いている編集内容がディスクから強制的に再読み込みされるため、プロジェクトを閉じたり開いたりすることなく外部からの変更を反映できます。waveform_revert_to_saved はそのパスをリトライ付きで自動化します。

ミックスバランスリファレンス

mix_apply_reference は、「キックがアンカー、ベースはその5-6dB下、リードはベースと同程度、パッド/アルペジオはリードの6-9dB下、アンビエンスは最も深く」というキュレーションされた表から読み取ります。これはジャンルのチュートリアル、マスタリングブログ、耳による調整の反復から抽出されたものです：

MIX_BALANCE["synthwave"] = {
    "drums": -7, "kick": -6, "snare": -10, "hat": -16,
    "bass": -25, "sub_bass": -28,           # background-level texture
    "lead": -15, "pad": -19, "arp": -8,     # arp-driven mix
    "counter": -14, ...
}

作曲ツールはトラックごとに1回 tracks.mix_apply_reference({track_id, genre, role}) を呼び出します。表を一度微調整すれば、すべての作曲ツールが再バランスされます。

表のソース:

• Mastering The Mix — How To Balance Kick And Bass

• Mastering The Mix — How To Mix Bass Synth

• eMastered — Balance All The Elements

既知の制限

• トラックボリュームの AUTOMATIONCURVE は無効です。 Waveformの volume プラグインは私たちのカーブスキーマを尊重せず、影響を受けるトラックを無音にします。MCPは明確なエラーでターゲットを拒否し、代替案（クリップフェード、クリップごとのゲインを持つ複数のクリップ、静的な mix_set）を提示します。

• プラグインモディファイアマトリックスは実験的です。 plugin_add_modifier は汎用的なモッドマトリックスの形状を書き込みます。4OSCなどでLFO変調を確実に機能させるには、プラグインごとのスキーマを確認するための手動編集されたフィクスチャが必要です。

• ヘッドレスレンダリングはまだ構築されていません。 waveform_render_to_mp3 はWaveformのUIエクスポートを駆動します。動作はしますが、Waveformが実行されている必要があります。tracktion_engine をリンクするC++ヘルパーが最終的な解決策となります。

• Linux/macOSのUI制御は存在しません。 コンテンツ検出（プリセット、ループライブラリ、VSTリスト）はOSを認識しますが、UI自動化はWindows専用です。

次の反復に向けたビルディングブロック

• <AUTOMATIONCURVE paramID="volume"> のための実際のWaveformフィクスチャをキャプチャし、ボリュームオートメーションを再有効化する

• tracktion_engine 上のC++ヘッドレスレンダリングヘルパー

• ドラムサンプラー / マイクロドラムサンプラーの実際のフィクスチャ（現在は通常のサンプラーにフォールバック）

• サイドチェーンモディファイアのキャプチャ

• クリップランチャー (v13) のサポート

• UIAが唯一のパスでなくなった後の xdotool/wmctrl によるLinux UI制御

ライセンス

GPL-3.0-or-later (C++レンダリングヘルパーがリンクする場合、tracktion_engine に準拠します)。