内容
# 波形MCP
[](LICENSE)
[](https://www.python.org/)
一个 [MCP](https://modelcontextprotocol.io/) 服务器，给予LLM代理对 [Tracktion Waveform](https://www.tracktion.com/products/waveform-pro) 的控制权。要求Claude编写一首歌曲，平衡混音，或渲染为MP3，并观看Waveform执行。
*一个64小节的Synthwave乐器曲目，通过MCP工具调用构建 - 鼓声，低音，两个垫，计数器，arp，引导。章节标记，速度自动化，侧链泵，盘式混响，剪辑级渐变，全主链。*
---
## 简介
- **150+ MCP工具**，涵盖作曲，MIDI，音频剪辑，插件，自动化，混音，掌握，渲染和Waveform UI控制
- **六个作曲家**（Synthwave，Lofi，Lofi-Generative，Djent，Djent-Real with VST amp模拟器，Rainstorm）以及`compose_from_reference`和`compose_variations`
- **音乐理论 + 混音知识**内置 - 音阶，进程，语音引导，按类型划分的参考级别，插件感知的推杆校准
- **验证的XML往返**，在内存模型和Waveform的`.tracktionedit`格式之间，具有250个回归测试来保护每个修复
---
## 这为您提供
- **150+ MCP工具**，涵盖编辑生命周期，轨道/总线，MIDI，音频剪辑，插件，自动化，音乐理论，混音平衡，**作曲基元**，**鼓模式库**，**进程生成器**，**语音引导**，**安排规划器**，**音频分析（LUFS / 速度 / 关键检测）**，**参考歌曲数据库**，**掌握链模板**，**MIDI导出**，**和弦图表导出**，**A/B快照**，**工具调用历史**，渲染，循环库，VST发现，模式捕获和Waveform UI控制
- **六个作曲家** - `compose_lofi_track`，`compose_synthwave_track`，`compose_djent_track`，`compose_djent_real`（使用VST amp模拟器），`compose_lofi_generative`（每个种子 = 一首不同的歌曲），`compose_rainstorm`
- **基于参考的作曲管道** - 指向任何音频文件（`compose_from_reference`），MCP分析它，构建一个`CompositionSpec`，包括其速度/关键/章节/和弦进程/乐器， Optionally转录多声部内容（BasicPitch），检测混响尾和侧链泵送，然后编写一个Waveform编辑，以它为模型
- **插件感知的推杆校准** - `mix_apply_reference`知道一个强制反馈SFZ大约比一个样本基础的鼓套件在相同的推杆上静音16 dB，因此角色目标dB查找落在*可听见*的水平，而不是字面上的推杆值
- **`compose_variations`**，从任何作曲家生成N个种子变体
- **音乐理论知识层** - 音阶，和弦进程，终止式，歌曲形式，语音引导规则，按类型划分的混音参考级别，参考歌曲数据库
- **状态感知的Waveform启动** - `waveform_launch`检测文件是否已经加载，Waveform在哪个视图中，是否有模态对话框阻塞，然后选择正确的路径（冷启动，聚焦+从磁盘恢复，或从资源管理器实时OLE拖放）
- **验证的往返**，在内存模型和Waveform的`.tracktionedit` XML之间
- **剪辑级渐变，增益，偏移，自动化曲线** - 经过验证的基本元素，LLM可以用来迭代音乐
- **可靠的工作流程循环** - `compose → write → reload via File → Revert to saved → listen → tweak`
- **250个测试通过** - 每个修复都有一个回归测试守护
---
## 状态
在**Windows + Waveform 13**上运行端到端。macOS / Linux路径存在于内容发现（预设，循环库，VST列表），但目前仅限于Windows的UI控制通过UIA / pywinauto。
通过与Claude进行约30小时的人机协作迭代构建和测试。两个作曲家都已多次渲染为MP3，用户已确认生成的曲目。
---
## 快速入门
### 安装
```powershell
cd "C:\path\to\waveform MCP"
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .
```
### 连接到Claude（代码，桌面或任何MCP客户端）
`~/.claude.json` 或您的客户端的MCP配置：
```json
{
"mcpServers": {
"waveform": {
"command": "waveform-mcp"
}
}
}
```
### 试用
```
打开Waveform，然后问Claude：
"使用compose_synthwave_track制作一个Synthwave歌曲，
保存到我的Documents/Waveform文件夹，并重新加载
到Waveform中让我听听。"
```
LLM调用`compose_synthwave_track` → `waveform_revert_to_saved`，您按下播放。然后迭代： *"降低低音"* → LLM更新`MIX_BALANCE["synthwave"]["bass"]`并重新加载。
---
## 架构
四层，每层都有明确的契约：
```
┌──────────────────────────────────────────────────────────────────┐
│ LLM（Claude / 任意MCP客户端） │
└────────────────────────────┬─────────────────────────────────────┘
│ MCP stdio
┌────────────────────────────▼─────────────────────────────────────┐
│ MCP服务器（server.py）— 150+工具 │
└────────────────────────────┬─────────────────────────────────────┘
│
┌──────────────┼─────────────────────┬──────────────┐
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌─────────────────────┐ ┌──────────────┐
│ 编辑模型 │ │ 知识 │ │ 参考管道 │ │ Waveform │
│ （内存） │ │ （数据） │ │ （音频文件→歌曲） │ │ UI控制 │
├──────────────┤ ├──────────┤ ├─────────────────────┤ ├──────────────┤
│ 轨道 │ │ 音阶 │ │ music-analyzer │ │ pywinauto + │
│ 剪辑 │ │ 和弦 │ │ reference_adapter │ │ UIA + ffmpeg │
│ 笔记 │ │ 表格 │ │ poly_transcribe（BP）│ │ 拖放 │
│ 插件 │ │ 混音 │ │ production_analysis │ │ 菜单调用 │
│ 自动化 │ │ 速度 │ │ → CompositionSpec │ │ 渲染→MP3 │
└──────┬───────┘ └──────────┘ └──────┬──────────────┘ └──────┬───────┘
│ │ │
│ ┌─────────────────┘ │
▼ ▼ ▼
┌────────────────────────┐ ┌────────────────────┐
│ compose_from_spec │ │ Waveform 13 │
│ + mix_calibration │ │ （运行中的应用） │
│ ↓ xml_writer.py │ └────────────────────┘
│ ↓ .tracktionedit │ ◀──────────── 状态感知启动 ──────────┘
└────────────────────────┘
```
**关键设计选择：** 模型*不是* Tracktion ValueTree的1：1 - 它是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` · `bus_create` · `bus_route`
`mix_apply_reference(track_id, genre, role)` 从精选的混音平衡表中查找dB目标（`MIX_BALANCE[genre][role]`）- “kick是锚点，低音5-6 dB以下”精炼成可调用的函数。
`bus_create("Drum Bus")` + `bus_route(kick_track, drum_bus)` 允许您将轨道堆叠到子混音中以共享压缩/均衡。
### 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` （Sampler支持，一个声音每个垫）
`plugin_add_modifier` （LFO / envelope / sidechain - 待定完整的Waveform支持）
`plugin_discover` （解析`knownPluginList64.settings`以列出已安装的VST）
**均衡 + 压缩助手：** `eq_high_pass` · `eq_low_pass` · `eq_tilt` · `compress_glue` · `compress_smash`
`waveform_preset_list` · `waveform_preset_read` · `waveform_plugin_types`
### 作曲基元（`melody.py`，`drum_patterns.py`，`composition.py`）
`melody_generate(scale, contour, density)` - 基于规则的轮廓形状的旋律（拱形/下降/波浪/问题答案/静态）
`arp_pattern(chord, rate, direction, octaves)` - 和弦上的琶音（向上/向下/上下/随机/八度交替）
`bassline_generate(roots, feel)` - 进展中的低音线（泵送/行走/半时/下/八度跳跃/ Dub）
`motif_develop(notes, transformation)` - 变化：转调/逆转/逆行/增强/减弱/序列向上/序列向下
`drum_pattern(genre, role, density, length_bars)` - 50+命名为（类型，角色）的grooves; 合成波，lofi，嘻哈音乐，edm，house，techno，trap，dnb，rock，pop，ambient
`drum_pattern_list` - 显示目录
`progression_generate(root, mode, length, end_cadence, style)` - 发明和弦进程; 风格：流行/爵士/模态/合成波/悲伤/振奋人心
`voice_lead(prev_voicing, next_chord)` - 最小运动语音引导
`arrangement_plan(genre, target_seconds, energy_curve)` - 生成一个章节列表，带有条目和角色以及能量0..1; 曲线：slow_burn / immediate_hook / build_drop_build / call_response
### 音频分析（`audio_analysis.py`，`audio_detect.py`）
`audio_loudness_lufs(file)` - 集成LUFS，真实峰值，LRA通过ffmpeg ebur128
`audio_spectrum(file, bands=10)` - 对数间距的RMS每频段频率平衡
`audio_compare(a, b)` - 差异LUFS /峰值/每频段频谱之间的两个文件
`audio_detect_tempo(file)` - BPM通过起始点自相关（~1%准确率在清晰的循环）
`audio_detect_key(file)` - 根+模式通过Krumhansl-Schmuck尔色谱
### 参考歌曲（`reference_songs.py`）
`reference_song_lookup(name)` / `reference_song_list` - 11个参考数据库，涵盖synthwave / pop / house / ambient / lofi（Drive（Kavinsky），Midnight City（M83），Sweet Dreams，Africa，In the Air Tonight，Strobe，Miami，Hide and Seek，Still Alive，generic chillhop，generic outrun）BPM，key，表单提示，能量曲线，签名元素。
### 掌握/混音工作流程（`workflow.py`）
`master_chain_apply(template)` - 插入链：clean_pop / loud_edm / lofi_warm / cinematic_dynamic / podcast_voice / no_processing
`snapshot_save(name)` / `snapshot_recall(name)` / `snapshot_list` - A/B比较版本的编辑
`edit_transpose(semitones)` - 改变所有MIDI音符
`edit_set_tempo(bpm)` - 更改项目速度
`compose_variations(composer_name, prefix, count)` - 生成N个种子变体作曲家
`tool_history(last_n)` - 列出最近调用的工具（自动记录在`@op`装饰器）
`edit_save_stem(track_names, out_path)` - 保存一个带有命名轨道的干混音副本
`edit_export_chord_chart(out_path, format)` - 文本和弦图表从标记+键
`render_and_audit(mp3_path, revert_first?)` - 渲染→mp3→分析→返回路径+平衡/节奏摘要在一个调用中。替换手动的revert→render→analyze链，这是最重复的调用迭代。
`compose_and_reload(composer, out_path, ...)` - 调度爵士乐/synthwave/lofi作曲器和`waveform_revert_to_saved`在一个调用中。避免作曲然后手动恢复的舞蹈。
### MIDI导出（`midi_export.py`)
`edit_export_midi(out_path)` - 标准MIDI文件（格式1）每个编辑MIDI轨道，以及轨道0中的速度和时间签名。
### 自动化（`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`) - 13个音阶（大调，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和，调和
### 基于引用的创作（`composition_spec.py`、`reference_adapter.py`、`tools/compose_from_spec.py`、`tools/import_song.py`）
- `analyze_to_spec(audio_path)` — 对任意音频文件运行音乐分析器，返回一个 `CompositionSpec` 字典（包括 tempo、key、sections、和弦进程、乐器配置），无需写入任何编辑记录。可用于检查或手动编辑规格后进行创作。
- `compose_from_reference(audio_path, out_path)` — 完整的处理流程：分析 → 适配 → 可选地使用 BasicPitch 进行转录 → 可选地通过 `production_analysis` 检测混响 / 侧链 → 构建 `.tracktionedit`。返回保真度注意事项，列出精确复制和近似的内容。
- `compose_from_spec_json(spec | spec_path, out_path)` — 从内联或手动编辑的 `CompositionSpec` JSON 构建编辑记录。适用于检查分析规格后希望在构建前进行调整。
- `compose_from_spec(spec, out_path)` — 所有上述方法内部使用的构建器；驱动现有的基本操作（`track_add`、`plugin_add`、`midi_clip_add`、`mix_apply_reference`），因此输出是校准感知的。
### 渲染（`render.py`、`waveform_workflows.py`）
`waveform_render_export` · `waveform_render_to_mp3`（使用捆绑的 ffmpeg + libmp3lame）
### 波形 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_focus` · `waveform_quit` · `waveform_settings_dir`
`waveform_launch(file_path)` 是**状态感知的** — 它在决定执行操作之前会检查 Waveform 的 UI：
| 检测状态 | 操作 |
|---|---|
| 应用程序未运行 | 冷启动并将文件作为命令行参数 |
| 文件已加载为标签页 | 聚焦标签页并从磁盘恢复 |
| 模态对话框阻止输入 | 退出并显示明确的 `stage: modal_dialog_blocking` 错误 |
| 应用程序在欢迎 / 项目 / 设置（无编辑视图） | 自动切换到现有的编辑标签页，以便有目标进行拖放 |
| 应用程序在编辑时间轴上，文件未加载 | **真正的 OLE 拖放操作**（Waveform 的 JUCE `IDropTarget` 实际支持的唯一机制，用于 `.tracktionedit` 文件在运行实例中） |
拖放操作通过 `explorer.exe /select,<file>` 实现，以在文件资源管理器中预选文件，通过 UIA 查找其屏幕矩形，然后通过 SendInput 级别的鼠标拖放操作发送到 Waveform 窗口 — 与 JUCE 从真实用户拖放操作看到的相同代码路径。
### 循环库（`loops.py`）
`loop_search`（按 tempo / 小节 / 名称）· `loop_drop`（自动长度，适应 tempo）
### 架构捕获（`schema_capture.py`）
`schema_snapshot_current_edit` · `schema_diff_snapshots` · `schema_list_snapshots`
### 低级 UI / 桌面（`win_input.py`、`desktop.py`）
18 个用于窗口管理、UI 自动化、键 / 点击发送、截图的基元。
---
## 布局
```
waveform-mcp/
├── src/waveform_mcp/
│ ├── server.py MCP 服务器入口（标准输入/输出）
│ ├── model.py 编辑 / 跟踪 / 剪辑 / 笔记 / 自动化通道数据类
│ ├── xml_writer.py 编辑 → .tracktionedit
│ ├── xml_reader.py .tracktionedit → 编辑
│ ├── audio_convert.py ffmpeg 支持的 MP3→WAV 缓存，用于采样器源
│ ├── music_theory_data.py 音阶、进程、类型、混音平衡等
│ ├── events.py 事件总线 + JSONL 日志
│ ├── diff.py 编辑记录变更，用于事件变更
│ ├── mix_calibration.py 插件感知的推子校准（偏移表 + 查询）
│ ├── composition_spec.py 分析驱动的创作的纯数据类架构
│ ├── reference_adapter.py 分析器 JSON → CompositionSpec（和弦 / 分段 / 时机助手）
│ ├── poly_transcribe.py Spotify BasicPitch 包装器 — 多声部音频 → MIDI
│ ├── production_analysis.py 从渲染音频中检测 RT60 / 侧链
│ ├── automation_from_features.py 音频特征 → 自动化断点（声像 / 截断 / 音量骑行）
│ ├── tools/
│ │ ├── edit.py 编辑生命周期
│ │ ├── tracks.py 跟踪 + 混音平衡（校准感知）
│ │ ├── midi.py MIDI 剪辑 / 笔记
│ │ ├── audio.py 音频剪辑导入
│ │ ├── clips.py 剪辑变异器（移动、调整大小、复制、设置）
│ │ ├── plugins.py 插件添加 + 自动鼓套件加载 + 混响 / EQ / 压缩器助手
│ │ ├── automation.py 自动化通道（声像 + 插件参数）
│ │ ├── preset_library.py 工厂预设浏览器
│ │ ├── loops.py 循环库搜索 + 拖放
│ │ ├── render.py 渲染存根
│ │ ├── waveform_app.py 应用程序生命周期 + 状态感知启动（冷启动 / 恢复 / 拖放）
│ │ ├── waveform_workflows.py UI 工作流程（恢复、渲染为 mp3 等）
│ │ ├── desktop.py 通用桌面基元
│ │ ├── win_input.py Windows UIA + 键击基元
│ │ ├── schema_capture.py 手动装置捕获，用于架构逆向工程
│ │ ├── music_theory.py 理论查询工具
│ │ ├── composition.py 进程生成 / 声部引导 / 排列计划
│ │ ├── melody.py 旋律生成 / 琶音模式 / 低音线生成 / 主题开发
│ │ ├── drum_patterns.py 50+ 个命名鼓模式，按（类型，角色）索引
│ │ ├── audio_analysis.py LUFS / 光谱 / 通过 ffmpeg 比较
│ │ ├── audio_detect.py BPM + 音键检测从音频
│ │ ├── reference_songs.py 精选的参考歌曲数据库
│ │ ├── workflow.py 主链模板 / 快照 / 变化 / 和弦图表导出
│ │ ├── midi_export.py .mid 导出
│ │ ├── composer.py compose_lofi_track, compose_synthwave_track, compose_djent_*, compose_rainstorm
│ │ ├── lofi_generative.py compose_lofi_generative（每个种子 = 不同歌曲）
│ │ ├── compose_from_spec.py 通用规格 → .tracktionedit 构建器
│ │ ├── import_song.py analyze_to_spec / compose_from_reference / compose_from_spec_json
│ │ └── common.py @op 装饰器（应用 + 差异 + 事件）
│ └── preview/
│ ├── app.py FastAPI + websocket
│ └── static/ HTML / JS 钢琴卷帘
├── tests/ 覆盖基元、合成器、校准、适配器、构建器、审计回归测试的 250 个测试
├── scripts/
│ ├── lofi_from_ecstasy.py 演示：构建一个受另一首歌的和弦调色板启发的 lofi 曲目
│ └── run_analyzer.py 在渲染文件上运行音乐分析器 + 测量茎
├── docs/
│ ├── img/synthwave_arrangement.png
│ ├── ARCHITECTURE.md
│ ├── EVENT_SCHEMA.md
│ └── EDIT_MODEL.md
├── pyproject.toml
└── README.md
```
---
## 实际工作的迭代循环
在多次尝试失败后，以下是允许 LLM 和用户在不重启 Waveform 的情况下协作曲目的循环：
```
1. 创作 / 变异 → composer.compose_* 或 clip_set / mix_apply_reference
2. 保存到磁盘 → edit_save / flush （写入 .trackionedit）
3. 在 Waveform 中重新加载 → waveform_revert_to_saved
（文件 → 恢复到保存状态，自动确认弹出窗口）
4. 用户聆听 → "turn the arp up"
5. 更新 MIX_BALANCE 或运行剪辑变异器
6. → 转到 2
```
关键的改变是发现 Waveform 的 **文件 → 恢复到保存状态** 菜单项：它强制打开的编辑记录从磁盘重新加载，这使得外部变异可见，无需关闭 / 重新打开项目。`waveform_revert_to_saved` 自动化了此路径，并带有重试功能。
---
## 混音平衡参考
`mix_apply_reference` 从一个精选的表格中读取“kick 是锚点；bass 低于 5-6 dB；lead 类似于 bass；pad/arp 低于 lead 6-9 dB；ambience 最深” — 跨类型教程、掌握博客和通过耳调迭代：
```python
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})` 每个曲目一次。根据表格进行微调。
信息来源：
- [掌握混音 - 如何平衡低音和鼓](https://www.masteringthemix.com/blogs/learn/118131269-how-to-balance-kick-and-bass-in-a-mix)
- [掌握混音 - 如何混音低音合成器](https://www.masteringthemix.com/blogs/learn/how-to-mix-bass-synth)
- [eMastered - 平衡所有元素](https://emastered.com/blog/balancing-levels)
---
## 插件感知的推子校准
`MIX_BALANCE[genre][role]` 表示“rhythm guitar at -8 dB” — 但一个基于样本的鼓套件以统一的推子级别大约比一个 sforzando 驱动的 SFZ 高 *16 dB*。因此，将鼓设置为 -5 dB，将节奏吉他设置为 -8 dB 会产生一种混音，其中鼓大约高 13 dB，而不是 3。
`mix_calibration.py` 解决了这个问题。每个插件链都有一个已知的输出偏移量，相对于“基于样本的鼓采样器 = 0 dB”的参考：
```python
PLUGIN_CHAIN_OFFSETS_DB = {
("sampler",): 0.0, # reference
("4osc",): -8.0,
("sforzando",): -16.0, # bare sforzando + typical SFZ
("sforzando", "anvil", "mt-a", "tsc 1.1"): 0.0, # full guitar chain ≈ unity
("808 kit",): 0.0, # named alias for sampler
("lofi bass",): 0.0, # multi-sample bass guitar
...
}
```
该表格在**注册构建时批量种子** - 乐器注册表中已知的每个预设（94 个条目：Salamander Grand 变体，所有 VSCO 乐器，所有 4OSC 预设）都会获得一个有意义的默认链偏移量，以便校准器停止发出“no match → -10 dB default”警告。手动输入的表格优先；批量种子仅填充空白。运行时装备的新预设也会自动注册。
`mix_apply_reference(track_id, genre, role)` 现在使用：
```
fader_db = role_target_db − chain_offset_db(track.plugins) + extra_offset_db
```
因此，“rhythm guitar at -8 dB” 落在正确的**可听** -8 dB 处，无论链条是单个 4OSC 补丁还是 `sforzando→Anvil→MT-A→TSC` — 推子值会自动补偿。
**鲁棒性：** 查询永远不会引发。未知链条会回落到一个保守的 -10 dB 偏移量，并在日志中显示一个`chain_offset_db: ... → no match` 警告，以便任何发送新插件链的合成器都立即知道注册偏移量。最终的推子值被限制在 `[-32, +8]` dB范围内。相同的输入始终产生相同的输出。
---
## 基于引用的创作
指向任何音频文件，MCP 都可以生成一个建模的新 `.trackionedit` 文件 — 使用其 tempo、key、结构、和弦进程和（可选地）转录的旋律内容。
```
audio file → music-analyzer → analyzer JSON → reference_adapter
→ CompositionSpec → compose_from_spec → .trackionedit
```
### 阶段 A - 精确复制的内容
- **Tempo + key + time-sig** — 直接从分析器中提取
- **分段时间线** — intro / verse / chorus / breakdown / etc. 每个分段都有密度和亮度，以小节边界为快照，因此鼓循环与分段开始对齐
- **和弦进程** — 每个检测到的和弦都放置在和弦轨道上，节拍对齐。低音根自动跟随。
- **表单保真度** — 来自分析器的重叠或无序的分段会解析为干净的单调时间线
- **插件感知的混音校准** 在结尾处，以便封面输出平衡
### 阶段 B - 保真度升级（可选，所有功能都优雅地降级，如果依赖项缺失）
- **`poly_transcribe.py`（Spotify BasicPitch）** - 当安装时，将音频转录为 MIDI 笔记（任何多音部），并根据音高范围将它们路由到正确的轨道（低音 / 主音 / 键）。音符被量化到 16 分之一音符网格，相同音高的微型碰撞被合并。
- **`production_analysis.py`** - Schroeder 集成 RT60 估计每个干（自动应用于 plate reverb 插件参数），侧链泵检测（信封相关性与鼓开始，应用于踢鼓触发的 Ducking 压缩器）。
- **`automation_from_features.py`** - 从立体声平衡时间序列中提取声像，从 RMS 包络中提取音量骑行，从光谱质心轨迹中提取滤波器截止曲线。
### 没有复制的内容
- **人声作为人声** - 没有合成人声层。人声线条要么通过到 Lead 轨道作为合成器，要么被跳过。
- **确切的多音符笔记** - BasicPitch 是 SOTA 开放转录器，但在密集的混音中仍然 ~70-90% F1 覆盖。封面将处于相同的调式，具有类似的形状，而不是精确的音符。
### 公共工具
```python
analyze_to_spec({"audio_path": "...wav"})
# → {"ok": True, "spec": {...}, "summary": {tempo, key, sections, ...},
# "fidelity_caveats": [...], "transcription": {used, note_count, ...},
compose_from_reference({"audio_path": "...wav", "out_path": "...trackionedit"})
# 完整的管道：分析 + 适配 + 转录 + 构建 + 保存
compose_from_spec_json({"spec": {...}, "out_path": "...trackionedit"})
# 从手动编辑或保存的 CompositionSpec 构建
```
要获取 B 阶段的升级：
```powershell
<music-analyzer-venv>\Scripts\pip install basic-pitch onnxruntime
```
MCP 检测安装的依赖项，并在可用时使用它们；如果没有它们，管道仍然会产生一个结构上忠实的封面，只是和弦音符占位符代替实际转录的音符。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器