Skip to main content
Glama

Waveform MCP

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

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


제공 기능

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

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

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

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

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

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

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


Related MCP server: ableton-mind

상태

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})를 호출합니다. 테이블을 한 번만 조정하면 모든 작곡가가 다시 밸런스를 맞춥니다.

테이블의 근거가 된 출처:


알려진 제한 사항

  • 트랙 볼륨 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과 일치).

Available Tools

129 tools
arp_patternB

Generate an arpeggio over a chord. Returns notes for the given length. direction ∈ {up, down, up_down, down_up, random, octave_alternate}. rate ∈ {quarter, eighth, sixteenth, triplet}. octaves controls how many octaves the cycle spans.

Inputs: length_beats (required), chord_pitches (required), rate, octaves, +4 more.

arrangement_planA

Produce a section list for a song. genre selects characteristic form; target_length_seconds + tempo set total bars; energy_curve shapes the intensity pattern. Returns sections with bar counts, roles, and an energy 0..1 the composer can use to gate layers / set velocities.

Inputs: genre (required), tempo (required), target_length_seconds (required), energy_curve, +2 more.

audio_clip_importA

Place an audio file as a clip on a track. warp_mode controls time-stretch behavior. Optional clip-level gain (dB), fade in/out (beats), and offset_in_source (beats — skip the first N beats of the source file, useful for trimming silent intros).

Inputs: track_id (required), file_path (required), start_beats (required), length_beats (required), +6 more.

audio_compareA

Compare two audio files: returns LUFS / peak / DR diffs and a per-band spectrum diff in dB. Positive numbers mean file_a is louder/brighter than file_b in that dimension.

Inputs: file_a (required), file_b (required), bands.

audio_detect_keyA

Detect the musical key of an audio file. Returns root note + mode (major/minor) with confidence 0..1. Uses chromagram + Krumhansl-Schmuckler key profiles. Reliable on tonal pop/jazz; less reliable on percussion-heavy or atonal material.

Inputs: file_path (required).

audio_detect_tempoA

Detect the BPM of an audio file via onset autocorrelation. bpm_range bounds the search (default 60..180). Returns a single BPM with confidence 0..1. Works well on EDM/pop loops with a kick on every beat; less reliable on free-tempo or sparse music.

Inputs: file_path (required), bpm_max, bpm_min.

audio_loudness_lufsA

Measure integrated LUFS, true peak (dBTP), and dynamic range (LRA) for an audio file using ffmpeg's loudnorm filter. Reference targets: Spotify -14 LUFS, Apple -16, broadcast -23. True peak should stay under -1.0 dBTP.

Inputs: file_path (required).

audio_spectrumA

Return RMS energy per frequency band. bands defaults to a 10-band log-spaced layout (sub, low, low-mid, mid, hi-mid, presence, brilliance, air). Useful for 'compared to my reference, this song is 4 dB heavier in the low-mid region.'

Inputs: file_path (required), bands.

automation_addA

Add an automation lane to a track. target ∈ {'volume', 'pan', 'plugin/<plugin_id>/'}. points = [{beat, value, curve?}]. Replaces any existing lane on the same target.

Inputs: points (required), target (required), track_id (required).

automation_clearA

Remove all automation lanes from a track, or just the lane on a given target.

Inputs: track_id (required), target.

automation_envelopeA

Convenience: ramp a target from start_value to end_value between start_beat and end_beat. shape ∈ {'linear', 'exp_in', 'exp_out', 'sine'}. exp_in starts slow then speeds up; exp_out is the inverse; sine is a smooth S-curve. Appends to an existing lane on the same target if one exists, otherwise creates a new lane.

Inputs: target (required), end_beat (required), track_id (required), end_value (required), +4 more.

automation_listA

List automation lanes on a track (or all tracks if track_id omitted).

Inputs: track_id.

aux_return_addA

Add an auxreturn plugin to a track so it receives audio from the given bus number (0..15). Pair with send_add(bus_num=N) on source tracks for parallel routing — e.g. drum tracks all send to bus 0, aux-return track applies a single reverb.

Inputs: track_id (required), bus_num.

bassline_generateB

Generate a bassline under a chord progression. feel ∈ {pump, walking, half_time, sub, octave_jumps, dub}. Each chord lasts chord_duration_beats. Roots are the chord-root MIDI pitches (typically octave 2-3).

Inputs: roots (required), chord_duration_beats (required), feel, start_beats, +1 more.

bus_createC

Create a submix / aux track other tracks can route to. kind ∈ {submix, folder}.

Inputs: name (required), kind.

bus_routeA

Route a track's output to a bus instead of master. Stack drums onto a 'Drum Bus' for one comp/EQ.

Inputs: dest_bus_id (required), src_track_id (required).

clip_duplicateA

Clone a clip onto the same track at start_beats + offset_beats. Returns the new clip_id. Notes are deep-copied for MIDI clips.

Inputs: clip_id (required), offset_beats (required).

clip_listA

List clips on a track (or all tracks). Returns id, kind, name, start, length, plus per-clip gain/fade/offset for audio clips.

Inputs: track_id.

clip_moveA

Shorthand: change a clip's start_beats. Length unchanged.

Inputs: clip_id (required), new_start_beats (required).

clip_removeB

Delete a clip by id.

Inputs: clip_id (required).

clip_resizeA

Change a clip's length. anchor='start' (default) keeps start_beats fixed and moves the right edge. anchor='end' keeps the right edge fixed and moves start_beats so total duration changes from the left.

Inputs: clip_id (required), new_length_beats (required), anchor.

clip_setB

Modify any field on an existing clip. Pass only fields you want changed. For AudioClip: name, start_beats, length_beats, gain_db, fade_in_beats, fade_out_beats, offset_in_source_beats, warp_mode. For MidiClip: name, start_beats, length_beats, gain_db.

Inputs: clip_id (required), name, gain_db, warp_mode, +5 more.

compose_and_reloadB

Dispatch one of jazz/synthwave/lofi generative composers AND revert in Waveform with one call. Avoids the compose-then-manually-revert dance during iteration.

Inputs: composer (required), out_path (required), seed, tempo, +3 more.

compose_djent_realA

Djent track using REAL VST3 instruments + amp/cab simulators (sforzando + Karoryfer Emilyguitar SFZ → The Anvil drive → Mercuriall Metal Area amp → TSC cab) instead of synthetic 4OSC. Returns a manual_step_required note explaining you must load the SFZ in sforzando once after opening the project — sforzando state isn't preserved in our .tracktionedit writer yet.

Inputs: out_path (required), seed, tempo.

compose_djent_trackB

Generate a progressive metal / djent instrumental in B minor. Form: intro → riffA → riffB → breakdown → riffA2 → buildup → solo (8 bars) → riffFinal → outro. Tracks: drums (polyrhythmic 3-3-2 kicks), bass, dual rhythm guitars panned hard L/R for the wall, lead solo over solo section, atmospheric pad. ~140 seconds at 110 BPM.

Inputs: out_path (required), seed, tempo.

compose_from_primitivesB

Build a song bottom-up from composition primitives — the recipe demonstrating arrangement_plan + progression_generate + voice_lead + drum_pattern + bassline_generate + arp_pattern + melody_generate + motif_develop wired together. Genre selects drum patterns, bass feels, and mix-balance reference. energy_curve drives velocity scaling per section.

Inputs: out_path (required), mode, root, seed, +4 more.

compose_jazz_generativeA

Generate a jazz/jaunty track with authentic walking bass (7-pattern Paul Chambers vocabulary), Charleston-rhythm Rhodes comping, and Salamander Grand Piano lead treated like a vocal (call/response motifs, vocal range, dynamic phrasing). Drums comp for the soloist (ghost rim shots on piano off-beats, phrase-end fills, sparse ride on solo phrases). Section-wide ensemble dynamics and per-section bass feels (two-feel for heads, walking for blowing, anticipations into the bridge).

Inputs: no named parameters.

compose_lofi_generativeA

Generate a UNIQUE lofi track on every call. Unlike the old compose_lofi_track which hardcoded everything, this one uses progression_generate, arrangement_plan, drum_pattern, melody_generate, and bassline_generate primitives. Each seed produces a meaningfully different song: different chords, section layout, drum density, melody contour, bass feel, and tempo (within lofi range).

Inputs: no named parameters.

compose_lofi_trackB

Generate a complete lofi track .tracktionedit file: 4 tracks (drums, bass, keys, pad), Fmaj7-Am7-Dm7-Cmaj7 progression, real 808 drum samples, master FX bus. Bass / keys / pad presets are configurable so you can A/B sounds without editing the composer. Saves to the given path.

Inputs: out_path (required), bars, seed, tempo, +4 more.

compose_rainstormA

Generate a rainstorm ambient .tracktionedit: continuous rain bed, tiled wind/breeze layer, occasional distant-muffled thunder rumbles (lowpass + EQ + low gain). 60 BPM (1 beat = 1 second). No music.

Inputs: out_path (required), seed, length_seconds.

compose_synthwave_generativeA

Generate a UNIQUE synthwave track on every call. Drives progression_generate / arrangement_plan / drum_pattern / melody_generate primitives with seed-driven variation across tempo (100-128 BPM), key, form, chord progression, drum density, melody contour, and bass feel. Different seeds = meaningfully different songs.

Inputs: no named parameters.

compose_synthwave_trackC

Generate a 64-bar synthwave instrumental .tracktionedit at 110 BPM in A minor. Properly developed song form: intro → verseA → chorus → verseB (variation) → chorus2 (with counter) → bridge (new chord set + walking bass + descending arp) → chorusFinal (peak) → outro (progressive instrument drop with pad chord ring-out). Per-section chord progressions, bass feels (verse=half-time, chorus=8th pump, bridge=walking), and arp themes (verse / verseB syncopated / chorus pump / bridge descending). Showcases the full MCP toolset.

Inputs: out_path (required), seed, tempo.

compose_variationsA

Run a composer N times with different seeds, saving each output to a numbered file. Returns the list of paths so you can render all and pick the best.

Inputs: count (required), composer_name (required), out_path_prefix (required), extra_args.

compress_glueB

Gentle bus 'glue' compressor. amount 0..1 (0=barely-there, 1=noticeable).

Inputs: track_id (required), amount.

compress_smashC

Aggressive parallel-style compressor for drum-bus / NY-style smash. No params — preset values.

Inputs: track_id (required).

desktop_clickA

Click at screen coordinates. Use desktop_screenshot first to know what's where. button ∈ {left, right, middle}.

Inputs: x (required), y (required), button, clicks.

desktop_keyA

Press a single key or chord. Examples: 'enter', 'esc', 'ctrl+s', 'ctrl+shift+n', 'f5'. Sent to whatever window currently has focus.

Inputs: keys (required), presses, interval.

desktop_moveA

Move the mouse to (x, y) without clicking.

Inputs: x (required), y (required), duration.

desktop_screenshotA

Capture the current screen (or a region) to a PNG file under state/screenshots/. Returns the path. Use this to verify that a UI action had the expected effect before sending the next.

Inputs: name, region.

desktop_screen_sizeA

Return current screen resolution.

Inputs: no named parameters.

desktop_typeC

Type a string of text into the focused window.

Inputs: text (required), interval.

desktop_waitA

Sleep for seconds seconds. Use sparingly; prefer screenshot-then-act.

Inputs: seconds (required).

drum_patternA

Generate drum notes for a section. (genre, role) selects from a library of 50+ named patterns. role ∈ {verse, chorus, fill, intro, breakdown, outro, buildup}. density 0..1 scales note count (0.5 drops half the hats; 1.0 is the full pattern). length_bars tiles the pattern. Returns notes ready to drop on a Sampler track.

Inputs: role (required), genre (required), length_bars (required), seed, +4 more.

drum_pattern_listA

List all available (genre, role) patterns in the library.

Inputs: no named parameters.

edit_createA

Create a new empty Edit (song). Sets tempo, time signature, and key. Replaces the in-memory Edit; does not write to disk until edit_save or flush.

Inputs: name, tempo, key_mode, key_root, +3 more.

edit_export_chord_chartA

Export a chord-chart text file from the markers + tempo of the current Edit. format ∈ {lead_sheet, nashville}. Markers should be named with section labels (e.g. 'verse', 'chorus').

Inputs: out_path (required), format.

edit_export_midiB

Export all MIDI clips in the current Edit to a Standard MIDI File (.mid). One MIDI track per Edit MIDI track. Format-1 SMF with the Edit's tempo + time signature in track 0. Drop into any DAW for editing/printing/learning.

Inputs: out_path (required).

edit_inspectA

Detailed structural dump of the current Edit. Heavier than edit_summary — includes every plugin's params, clip gain/fade/offset, automation lane counts, master chain. Use after edit_open to understand a song before mutating it.

Inputs: no named parameters.

edit_openB

Load an existing .tracktionedit file from disk into the model.

Inputs: path (required).

edit_saveA

Serialize the current Edit to a .tracktionedit file. Sets the flush target.

Inputs: path (required).

edit_save_stemA

Save a stem-mix copy of the current Edit: only named tracks audible, all others muted. Pass track_ids or track_names (list). Use in a loop to produce per-track stems for rendering.

Inputs: out_path (required), track_ids, track_names.

edit_set_tempoB

Change the project tempo. preserve_pitch is informational (audio clips don't get pitch-shifted by this tool).

Inputs: bpm (required), preserve_pitch.

edit_summaryA

Return a JSON summary of the current Edit (tracks, clips, markers, tempo).

Inputs: no named parameters.

edit_transposeA

Transpose every MIDI note in the Edit by semitones. Audio clips are NOT pitch-shifted.

Inputs: semitones (required).

ensemble_dynamicsA

Return per-section velocity multipliers for a sections_plan. Apply uniformly to drums, bass, keys, lead notes so the whole ensemble breathes together (quiet intro, building verses, peak chorus/bridge, soft outro).

Inputs: no named parameters.

eq_high_passA

Add a high-pass filter at freq Hz to a track. slope is dB/oct (12, 18, 24).

Inputs: track_id (required), freq, slope.

eq_low_passA

Add a lowpass filter at freq Hz to a track for darkening/muffling.

Inputs: track_id (required), q, freq.

eq_tiltB

Single-knob bright/dark EQ. brightness -1=dark, 0=neutral, +1=bright.

Inputs: track_id (required), brightness.

flushA

Write the current Edit to the previously-opened/saved .tracktionedit path. Use this between batches of mutations so Waveform (when open) sees a single, coherent update instead of mid-edit flicker.

Inputs: no named parameters.

key_setD

Set the project key.

Inputs: mode (required), root (required).

loop_dropA

Drop a loop onto a track. mode='fit' time-stretches to song tempo, 'original' uses natural tempo. start_beats defaults to end of existing clips on that track. Auto-detects file duration.

Inputs: track_id (required), loop_path (required), mode, start_beats.

marker_addB

Drop a marker (verse, chorus, drop, etc.) at a beat position.

Inputs: name (required), start_beats (required), length_beats.

master_chain_applyA

Replace the master chain with a named template. template ∈ {clean_pop, loud_edm, lofi_warm, cinematic_dynamic, podcast_voice, no_processing}. Each is an EQ + Comp + Limiter chain tuned for its target use case.

Inputs: template (required).

melody_generateB

Generate a melody from a scale and contour. Returns notes (pitch/start_beats/length_beats/velocity) ready to drop into a MIDI clip. contour ∈ {arch, descending, ascending, wave, question_answer, static}. density ∈ {sparse, medium, busy}. Notes are rhythmically diverse — quarter, eighth, dotted, with rests — humanized for natural feel.

Inputs: mode (required), root (required), length_beats (required), seed, +3 more.

midi_clip_addC

Create an empty MIDI clip on a track.

Inputs: track_id (required), start_beats (required), length_beats (required), name.

midi_clip_quantizeA

Snap note start times in a clip to the nearest grid division. Grid is in beats: 0.25 = 16th notes, 0.5 = 8ths, etc. Strength 0..1.

Inputs: clip_id (required), grid_beats (required), strength.

midi_notes_addB

Add notes to an existing MIDI clip. Pass an array of {pitch, start_beats, length_beats, velocity?, colour?}. Pitch is MIDI 0-127. Channel is per-clip, set when the clip is created (not per-note).

Inputs: notes (required), clip_id (required).

midi_notes_clearB

Remove all notes from a MIDI clip.

Inputs: clip_id (required).

mix_apply_referenceB

Set a track's volume_db (and optional pan) to the genre+role reference from the MIX_BALANCE table. Use this once per track after creating it instead of hand-tuning levels. Genres: synthwave, lofi, edm, pop, hip_hop, cinematic, ambient. Roles: drums, kick, snare, hat, bass, sub_bass, lead, pad, keys, arp, counter, melody, ambience, fx. Returns the dB value applied.

Inputs: role (required), genre (required), track_id (required), pan, +1 more.

mix_match_referenceA

Compare a rendered file against a genre's reference spectrum and return a per-band diff in dB plus a plain-English diagnosis ('low end is +4 dB hot vs synthwave reference; consider HP filter on bass'). Use after render to inform mix adjustments.

Inputs: genre (required), file_path (required).

mix_setA

Set track volume (dB), pan (-1..1), mute, solo. Pass only the fields to change.

Inputs: track_id (required), pan, mute, solo, +1 more.

motif_developB

Transform a motif (set of notes) into a variation. transformation ∈ {transpose, invert, retrograde, augment, diminish, sequence_up, sequence_down}. transpose: shift by semitones. invert: mirror around axis_pitch. retrograde: reverse note order. augment: stretch durations by factor. sequence_up/down: transpose by semitones AND repeat.

Inputs: notes (required), transformation (required), factor, semitones, +2 more.

narrateA

Tell the user (via the event stream / preview UI) what the agent is about to do, in plain English. Call this before a batch of mutations so the user can follow along.

Inputs: text (required).

plugin_addA

Add a plugin to a track's chain. For built-ins, pass the type name (e.g. '4OSC', 'Wavetable'). For external VSTs, also pass preset_path.

Inputs: type (required), track_id (required), name, preset_path.

plugin_add_drum_kitA

Add a Sampler-backed drum kit to a track. pads is a list of {midi_note, sample_path, name?, gain_db?, pan?, decay?}. Each pad becomes one SOUND mapped to a single MIDI note. Replaces the manual Sampler+sounds boilerplate in compose_lofi_track.

Inputs: pads (required), track_id (required), name.

plugin_add_macroA

Add a MacroParameter (single 0..1 knob) to a plugin. Macros are the canonical Tracktion way to expose a single control that drives multiple underlying params via assignments.

Inputs: name (required), track_id (required), plugin_id (required), value, +1 more.

plugin_add_modifierA

Add a TRACK-LEVEL modifier (LFO/envelope/random/step_lfo) and assign it to a plugin parameter. Real Tracktion schema — wires both on the track AND on the plugin. depth: 0..1 (modulation amount). rate: Hz when rate_type=0, beat multiplier when rate_type=1 (default = beat-synced). shape ∈ {sine, triangle, square, saw}.

Inputs: track_id (required), target_param (required), target_plugin_id (required), rate, +5 more.

plugin_add_reverbA

Add a built-in reverb to a track. type ∈ {plate, natural, non_linear}. All other params are normalized 0..1: size, decay, mix (wet amount), pre_delay, diffusion, definition, high_damp, low_damp, high_cut. Defaults to a tasteful 25% wet plate.

Inputs: track_id (required), mix, name, size, +8 more.

plugin_discoverA

List third-party VST/AU plugins Waveform has scanned. Optional filters: kind ('instrument'|'effect'), format ('VST3'|'VST'|'AU'), manufacturer (substring), name (substring). Use the returned uniqueId as the type arg to plugin_add for VST3 instantiation.

Inputs: kind, name, format, manufacturer.

plugin_listA

Return the curated list of built-in instruments and effects available by name.

Inputs: no named parameters.

plugin_removeB

Remove a plugin from a track's chain by id.

Inputs: track_id (required), plugin_id (required).

plugin_set_paramC

Set a named parameter on a plugin in a track's chain.

Inputs: param (required), value (required), track_id (required), plugin_id (required).

plugin_set_vst_stateA

Apply a base64 VST state blob (from plugin_state_capture) to an existing plugin in the in-memory Edit. Lets you copy one configured VST onto every other instance.

Inputs: state (required), track_id (required), plugin_id (required).

plugin_state_captureA

Read a saved .tracktionedit file and extract a VST plugin's base64 state blob by plugin_name (substring match) or unique_id. Used to copy a manually-loaded plugin's configuration (e.g. an SFZ loaded into sforzando) for re-use programmatically.

Inputs: unique_id, plugin_name, edit_file_path.

progression_generateA

Invent a chord progression in a key and mode. Returns a list of chord dicts ({roman, root_note, root_midi, chord_pitches, quality}). Constraints: end_cadence ∈ {authentic, plagal, deceptive, half}; allow_borrowed enables modal interchange (bIII/bVI/bVII in major, V/VII for minor); style ∈ {pop, jazz, modal, synthwave, sad, uplifting} biases the chord palette.

Inputs: mode (required), root (required), length_chords (required), seed, +4 more.

reference_song_listA

List all known reference songs in the curated database.

Inputs: no named parameters.

reference_song_lookupA

Look up musical hints for a song. Pass name (one of the keys in REFERENCE_SONGS) OR genre to list all references in that genre. Returns BPM, key, form, energy curve, signatures the composer can use as inputs.

Inputs: name, genre.

reference_spectrum_lookupA

Get the target spectral profile (RMS dB per log-spaced band) for a genre — a mastering-engineer-cheat-sheet target for what a well-mixed track in this genre should look like spectrally. Bands: 60 / 133 / 296 / 657 / 1460 / 3243 / 7204 / 16000 Hz.

Inputs: genre (required).

renderA

Render the current Edit to a WAV file. NOT YET IMPLEMENTED — requires the wf-engine-helper binary which is not built. Use this tool to check status; it will return ok=False with a clear message so the agent can fall back to telling the user to render from inside Waveform.

Inputs: out_path (required), bit_depth, sample_rate.

render_and_auditC

Render the active edit to MP3, run the analyzer, and return both paths plus a balance/rhythm summary in one call. Replaces the manual revert→render→analyze chain.

Inputs: bitrate, mp3_path, revert_first, trim_trailing_silence.

render_stemsB

Render per-track stems. NOT YET IMPLEMENTED.

Inputs: out_dir (required).

send_addA

Add an aux send (parallel routing) on a track. Tracktion routes via numbered buses 0..15 — pass bus_num explicitly, or pass dest_track_id to auto-pick a bus. Pair with aux_return_add on the receiving track. Emits a real element with proper slider position from amount_db.

Inputs: src_track_id (required), bus_num, pre_post, amount_db, +1 more.

snapshot_listA

List all saved snapshots in this session.

Inputs: no named parameters.

snapshot_recallC

Restore a previously-saved snapshot as the active Edit.

Inputs: name (required).

snapshot_saveA

Save the current Edit as a named snapshot for later A/B compare or recall.

Inputs: name (required).

step_clip_addB

Add a step clip (drum-machine grid) to a track. channels is a list of {midi_note, name?, velocity?} dicts — one per drum row. patterns is a list of pattern dicts: each pattern has rows parallel to channels, where each row has a pattern string of '0'/'1' steps and optional velocities list. step_length is duration of each step in beats (0.25 = 16th notes). Way cleaner than 80 individual MidiClip notes.

Inputs: channels (required), patterns (required), track_id (required), start_beats (required), +4 more.

tempo_setA

Set the project tempo in BPM (currently single global tempo; per-bar curves later).

Inputs: bpm (required).

theory_arrangement_layersA

Return arrangement layers: foundation, harmonic_glue, lead, counter_melody, atmosphere, ear_candy. Optional section returns per-section presence values for each layer (0..1) from LAYER_PRESENCE_BY_SECTION — drives the 'which layers should be active' decision.

Inputs: section.

theory_borrowed_chordsA

Return the borrowed-chord (modal interchange) palette for major keys with usage notes.

Inputs: no named parameters.

theory_cadencesB

Return cadence types — pattern, feel, and use. Optional name for one specific cadence.

Inputs: name.

theory_chord_progressionA

Look up a named chord progression. Returns the Roman-numeral sequence + tags + examples. Without args, lists all 24 named progressions.

Inputs: tag, name.

theory_diatonic_chordsB

Return the 7 diatonic chords for a key/mode. Set sevenths=true for 7th-chord qualities (Imaj7, ii7, etc.) instead of triads (I, ii, etc.). Returns Roman numerals + the actual chord pitches (MIDI) for each.

Inputs: mode (required), root (required), octave, sevenths.

theory_genreA

Return genre conventions: BPM range, time signature, key tendency, instruments, form, hallmark progressions. Without args, lists all 22 genres.

Inputs: name.

theory_heuristicsA

Return the 13 songwriting heuristics (rule_of_3, contrast_required, etc.).

Inputs: no named parameters.

theory_mix_balanceA

Return reference track-volume dB targets for a genre. Without args, returns the full table of (genre, role) → dB. With genre, returns the role→dB map for that genre. With genre AND role, returns the single dB value with a brief rationale. Roles: drums, kick, snare, hat, bass, sub_bass, lead, pad, keys, arp, counter, melody, ambience, fx. Genres: synthwave, lofi, edm, pop, hip_hop, cinematic, ambient.

Inputs: role, genre.

theory_modesB

List the 7 church modes with their characteristic degree, vibe, and typical use.

Inputs: mode.

theory_rhythmA

Return rhythm/meter info: time signatures, syncopation patterns, swing ratios. Pass time_sig for one specific time signature, syncopation for one pattern, or neither for the full reference.

Inputs: time_sig, syncopation.

theory_scaleA

Return the notes of a scale starting at a root. Returns MIDI numbers, note names, and interval pattern. mode is one of: major, natural_minor, harmonic_minor, melodic_minor_asc, ionian, dorian, phrygian, lydian, mixolydian, aeolian, locrian, major_pentatonic, minor_pentatonic, blues, whole_tone, half_whole_dim, whole_half_dim, chromatic, hungarian_minor, phrygian_dominant.

Inputs: mode (required), root (required), octave.

theory_sectionA

Return song section info: typical bar counts, role, dynamic level, valid next sections. Without args, lists all 15 section types (intro, verse, chorus, bridge, drop, etc.).

Inputs: name.

theory_song_formA

Return a macro song form layout. Without args, lists all 14 forms. With name, returns the section sequence, applicable genres, and total bar range.

Inputs: name.

theory_surprise_devicesC

Return the 7 surprise devices (truck_driver_modulation, deceptive_cadence, etc.).

Inputs: no named parameters.

theory_velocityA

Convert dynamic markings (ppp/pp/p/mp/mf/f/ff/fff) to MIDI velocity values, or look up all of them. Includes ACCENT_BUMP and GHOST_NOTE_MAX_VEL constants.

Inputs: dynamic.

theory_voice_leading_rulesA

Return the 10 codified voice-leading rules + scoring guidance.

Inputs: no named parameters.

tool_historyA

Return the last N tool calls made in this session for self-audit.

Inputs: last_n.

track_addB

Add a new track. kind ∈ {audio, midi, folder, submix, automation}.

Inputs: name (required), pan, kind, volume_db.

track_removeB

Delete a track by id.

Inputs: track_id (required).

undoB

Roll back the most recent mutation.

Inputs: no named parameters.

voice_leadA

Voice the next chord with minimal voice motion from the previous voicing. Standard SATB-style voice leading: each voice moves the smallest interval to a target chord tone. Returns the new voicing as a list of MIDI pitches (same length as prev_voicing).

Inputs: next_chord (required), prev_voicing (required).

waveform_focusA

Bring Waveform's main window to the foreground. Required before desktop_key / desktop_type send keystrokes to the app.

Inputs: no named parameters.

waveform_launchA

Launch Waveform, optionally opening a .tracktionedit file. If Waveform is already running and a file path is provided, opens the file in the existing instance via OS file association (Waveform registers itself as the handler for .tracktionedit on install).

Inputs: exe_path, file_path.

waveform_locateA

Find the installed Waveform binary on disk. Returns the path. Searches running processes first, then well-known install locations. Run this before launch/focus tools so the rest of the chain has a path to use.

Inputs: no named parameters.

waveform_plugin_typesA

Return the friendly-name → Tracktion-type-code map for built-in plugins. These codes are what the .tracktionedit XML expects in .

Inputs: no named parameters.

waveform_preset_listA

List available factory presets. Without args, returns the plugin category folders (4OSC, Compressor, etc.). With category, lists individual .trkpreset files in that category.

Inputs: category.

waveform_preset_readA

Read a .trkpreset XML and return its element contents — the type, parameters, and any nested elements. Use this to grab a known-good instrument or effect configuration to drop into a generated edit.

Inputs: path (required).

waveform_quitA

Politely close Waveform (sends WM_CLOSE to the main window).

Inputs: no named parameters.

waveform_settings_dirA

Return the path to Waveform's settings directory (where Waveform.settings, knownPluginList64.settings, Templates/, etc. live). Useful for the planned settings-file editor surface.

Inputs: no named parameters.

waveform_statusA

Is Waveform currently running? Returns pid + exe path if so.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 129 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but several near-duplicates exist (tempo_set vs edit_set_tempo, compose_lofi_track vs compose_lofi_generative, audio_clip_import vs loop_drop). Some descriptions reference flows (e.g. 'revert→render→analyze' in render_and_audit) that don't map to explicit tools, which could confuse an agent.

    Naming Consistency4/5

    The dominant snake_case verb_noun / domain_action pattern is consistent (midi_clip_add, automation_clear, waveform_launch, theory_scale). However, a few outliers break the pattern: tempo_set and key_set lack the domain prefix that edit_set_tempo has for the same concept, and verbs are mixed (list/lookup/get/add/create) without a strict rule.

    Tool Count1/5

    With 129 tools, this is far beyond the 3-15 well-scoped range and even beyond the 50+ 'extreme' threshold. The breadth spans DAW control, music theory, generation, audio analysis, and desktop automation, but the sheer count makes it unwieldy for an agent to navigate; many tools (e.g. the numerous compose_*_track variants, granular desktop_* actions) could be consolidated behind parameters.

    Completeness3/5

    Coverage is broad across edit, clip, MIDI, audio, plugin, automation, rendering, theory, generation, and analysis domains. However, notable gaps exist: there is no way to list tracks (only track_add/remove), no bus listing, no marker add/list management, no plugin chain reorder/bypass, and no way to change time signature after edit creation.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers