Waveform MCP

MCP-сервер, который предоставляет LLM-агенту управление Tracktion Waveform. Попросите Claude написать песню, сбалансировать микс или выполнить рендер в MP3 — и наблюдайте, как Waveform делает это.

Инструментальная композиция в стиле синтвейв на 64 такта, созданная с помощью вызовов инструментов MCP — ударные, бас, два пэда, контрапункт, арпеджио, лид. Маркеры секций, автоматизация темпа, сайдчейн-памп, плейт-реверберация, фейды на уровне клипов, полная мастер-цепочка.

Что вы получаете

• 107 инструментов MCP, охватывающих жизненный цикл проекта, треки, MIDI, аудиоклипы, плагины, автоматизацию, теорию музыки, баланс микса, рендеринг, библиотеку лупов, поиск VST, захват схемы и управление интерфейсом Waveform

• Два полноценных композитора — compose_lofi_track и compose_synthwave_track — которые пишут полностью аранжированные, сведенные и отрендеренные песни

• Один эмбиент-композитор — compose_rainstorm — для создания звуковых ландшафтов с дождем, ветром и громом

• Слой знаний по теории музыки — гаммы, аккордовые прогрессии, каденции, формы песен, правила голосоведения, эталонные уровни баланса микса для каждого жанра

• Проверенная двусторонняя синхронизация между моделью в памяти и XML-файлом .tracktionedit в Waveform

• Фейды на уровне клипов, усиление, смещение, кривые автоматизации — проверенные примитивы, которые LLM может использовать для музыкальных итераций

• Надежный рабочий цикл — compose → write → reload via File → Revert to saved → listen → tweak

Статус

Работает «под ключ» на Windows + Waveform 13. Пути для macOS / Linux существуют для обнаружения контента (пресеты, библиотека лупов, список VST), но управление интерфейсом пока только для Windows через UIA / pywinauto.

Создано и протестировано в ходе ~30 часов итераций с участием человека и Claude. Оба композитора были неоднократно отрендерены в 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, а вы нажимаете «Play». Затем итерируйте: "сделай бас тише" → LLM обновляет MIX_BALANCE["synthwave"]["bass"] и перезагружает проект.

Архитектура

Четыре уровня, каждый с четким контрактом:

┌──────────────────────────────────────────────────────────────┐
│  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 │          └────────────────────┘
   └──────────────────┘

Ключевое проектное решение: Модель не является точной копией дерева значений (ValueTree) Tracktion — это структура, с которой удобно работать LLM, проецируемая на XML при сохранении и обратно при загрузке. Это упрощает инструменты (audio_clip_import(track_id, file_path, start_beats, length_beats, fade_in_beats, ...)) вместо того, чтобы заставлять LLM мыслить внутренними структурами JUCE.

Каталог инструментов

Жизненный цикл проекта (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]) — эталон «кик — это якорь, бас на 5-6 дБ тише», превращенный в вызываемую функцию.

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 (на базе сэмплера, один ЗВУК на пэд) 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>. Громкость (volume) отключена на уровне 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 и др.)

• Каденции, формы песен, секции с профилями роли/плотности/динамики

• 14 жанров с типичным BPM, тональными предпочтениями, инструментами, характерными прогрессиями

• Карты велосити / ритма (коэффициенты свинга, акценты, диапазоны гост-нот)

• 13 эвристик написания песен (правило трех, необходимость контраста, квота на неожиданность и т.д.)

• 7 приемов неожиданности (модуляция «дальнобойщика», прерванная каденция и т.д.)

• Таблица эталонного баланса микса — 7 жанров × 14 ролей, полностью аннотировано

Композиторы (composer.py)

• compose_lofi_track — 32-тактовый лоу-фай с ударными, басом, клавишными, пэдом, мелодией, контрапунктом; огибающие велосити с учетом секций; автоматизация темпа; лоу-фай мастер-цепочка

• compose_synthwave_track — 64-тактовый синтвейв с 7 треками; форма из 9 секций (интро/куплет/припев/куплет/припев/бридж/нарастание/финальный припев/аутро); басовые рисунки для каждой секции (half-time / 8th-pump / walking); арпеджио-темы, привязанные к секциям; фильтр-памп в стиле сайдчейн; маркеры секций; фейды клипов

• compose_rainstorm — эмбиент-ландшафт с дождем + ветром + приглушенным далеким громом; рандомизация усиления для каждого клипа; подрезка смещения; эффекты трека

Рендер (render.py, waveform_workflows.py)

waveform_render_export · waveform_render_to_mp3 (использует встроенный ffmpeg + libmp3lame)

Управление интерфейсом Waveform (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

Низкоуровневый интерфейс / рабочий стол (win_input.py, desktop.py)

18 примитивов для управления окнами, инспекции UIA, отправки клавиш/кликов, скриншотов.

Макет

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

Итерационный цикл, который действительно работает

После многих неудачных попыток, вот цикл, который позволяет LLM и пользователю совместно работать над треком без перезапуска Waveform на каждом этапе:

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 File → Revert to saved state: он заставляет открытый проект перезагрузиться с диска, что делает внешние изменения видимыми без закрытия/открытия проекта. waveform_revert_to_saved автоматизирует этот путь с повторными попытками.

Эталонный баланс микса

mix_apply_reference считывает данные из таблицы: «кик — якорь; бас на 5-6 дБ тише; лид как бас; пэд/арп на 6-9 дБ тише лида; эмбиент самый тихий» — выведено из учебников по жанрам, блогов по мастерингу и итераций на слух:

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, ...
}

Композиторы вызывают 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 громкости трека отключена. Плагин volume в Waveform не поддерживает нашу схему кривых и отключает звук трека. MCP отклоняет цель с четкой ошибкой и указывает на рабочие альтернативы (фейды клипов, несколько клипов с усилением на каждый, статический mix_set).

• Матрица модификаторов плагинов находится в стадии исследования. plugin_add_modifier записывает общую структуру матрицы; требуется ручная правка для подтверждения схемы каждого плагина, прежде чем LFO-модуляция будет надежно работать для 4OSC и других.

• Безголовый рендер еще не реализован. waveform_render_to_mp3 управляет экспортом через интерфейс Waveform — работает, но требует запущенного Waveform. C++ помощник, связывающий tracktion_engine, станет окончательным решением.

• Отсутствует управление интерфейсом на Linux/macOS. Обнаружение контента (пресеты, библиотека лупов, список VST) работает на всех ОС; автоматизация интерфейса — только для Windows.

Строительные блоки для следующих итераций

• Захват реального фиксатора Waveform для <AUTOMATIONCURVE paramID="volume">, чтобы можно было включить автоматизацию громкости

• C++ помощник для безголового рендеринга на базе tracktion_engine

• Реальный фиксатор для Drum Sampler / Micro Drum Sampler (сейчас используется обычный Sampler)

• Захват модификатора сайдчейна

• Поддержка Clip Launcher (v13)

• Управление интерфейсом Linux через xdotool/wmctrl, когда UIA перестанет быть единственным путем

Лицензия

GPL-3.0-or-later (соответствует tracktion_engine, если/когда C++ помощник рендеринга будет с ним связан).