Waveform MCP

Tracktion Waveform을 LLM 에이전트가 제어할 수 있게 해주는 MCP 서버입니다. Claude에게 곡을 쓰거나, 믹스를 밸런싱하거나, MP3로 렌더링하도록 요청하고 Waveform이 실행되는 모습을 지켜보세요.

MCP 도구 호출을 통해 작곡된 64마디 신스웨이브 연주곡 — 드럼, 베이스, 두 개의 패드, 카운터, 아르페지오, 리드. 섹션 마커, 템포 자동화, 사이드체인 펌프, 플레이트 리버브, 클립 레벨 페이드, 전체 마스터 체인.

제공 기능

• 107개의 MCP 도구: 편집 수명 주기, 트랙, MIDI, 오디오 클립, 플러그인, 자동화, 음악 이론, 믹스 밸런스, 렌더링, 루프 라이브러리, VST 탐색, 스키마 캡처 및 Waveform UI 제어

• 두 개의 엔드 투 엔드 작곡가 — compose_lofi_track 및 compose_synthwave_track — 완전히 편곡, 믹싱 및 렌더링된 곡을 작성

• 하나의 앰비언트 작곡가 — compose_rainstorm — 비 + 바람 + 천둥 사운드스케이프용

• 음악 이론 지식 계층 — 스케일, 코드 진행, 종지, 곡 형식, 성부 진행 규칙, 장르별 믹스 밸런스 기준 레벨

• 메모리 내 모델과 Waveform의 .tracktionedit XML 간의 검증된 왕복(Round-trip)

• 클립 레벨 페이드, 게인, 오프셋, 자동화 곡선 — LLM이 음악적으로 반복 작업할 수 있는 검증된 기본 요소

• 안정적인 워크플로우 루프 — 작곡 → 쓰기 → 파일로 다시 로드 → 저장된 상태로 되돌리기 → 듣기 → 조정

상태

Windows + Waveform 13에서 엔드 투 엔드로 작동합니다. 콘텐츠 탐색(프리셋, 루프 라이브러리, VST 목록)을 위한 macOS/Linux 경로가 존재하지만, 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 (샘플러 기반, 패드당 하나의 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개 섹션 형식(인트로/벌스/코러스/벌스/코러스/브릿지/빌드업/코러스파이널/아웃트로); 섹션별 베이스 느낌(하프 타임 / 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, ...
}

작곡가는 트랙당 한 번씩 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과 일치).