MusicXML Synthesizer

synth-mcp

可将 MusicXML 合成为音频的 MCP 服务。支持选择声部（女高音、女中音、男高音、男低音）和控制速度。

功能

接收 MusicXML 乐谱，可选择筛选一个或多个声部，并使用 FluidSynth 渲染为 WAV 音频文件。适合想练习特定声部的合唱团成员。

工具

工具	描述
get_parts	列出乐谱中的所有声部——返回声部名称、ID 和小节数
synthesize	将乐谱（或选定的声部）渲染为 WAV 文件，并可调整速度和练习选项（小节、重复次数、预备拍、节拍器、音色、声部音量）
starting_pitches	以文本形式显示各声部的第一个音符（"S: D5, A: A4, T: F#4, B: D3"），并提供一段简短的钢琴音频
describe_score	以较低成本概述乐谱：标题、调号、拍号、速度、声部（ID、谱号、音域）、小节数、时长
list_capabilities	返回服务元数据：后端版本、音源状态、FluidSynth 是否可用
health_check	检查音源、FluidSynth 和 music21 是否均可用且已就绪

安装

cd synth-mcp
uv sync

需要系统库：

# Ubuntu / Debian
sudo apt install libfluidsynth-dev

# macOS
brew install fluid-synth

还需要一个音源（SF2）文件。可免费使用的选项：

音源	大小	备注
TimGM6mb	~6 MB	随 Ubuntu 提供（/usr/share/sounds/sf2/TimGM6mb.sf2）
MuseScore General	~200 MB	音质更好；从 musescore.org 下载
GeneralUser GS	~30 MB	从 schristiancollins.com 下载

快速安装

不想手动完成上述步骤？运行 ./install.sh——它会自动安装 uv、系统 libfluidsynth 软件包和音源。非技术人员可参阅 SETUP.md 了解安装步骤；遇到问题时可参阅 TROUBLESHOOTING.md。 现成的客户端配置（Claude Desktop、Cursor、Windsurf、Continue、Zed）位于 examples/。

运行

SYNTH_SOUNDFONT_PATH=/usr/share/sounds/sf2/TimGM6mb.sf2 uv run synth-mcp

配置

变量	必需	描述
SYNTH_SOUNDFONT_PATH	是	SF2 音源文件的路径
SHEET_MUSIC_OUTPUT_ROOT	否	output_path 必须位于此文件夹内；musicxml_path 也可读取此文件夹（默认：工作目录）
SHEET_MUSIC_INPUT_ROOTS	否	musicxml_path 可读取的额外文件夹（以 : 分隔；Windows 上使用 ;）

Claude Desktop 配置

{
  "mcpServers": {
    "synth": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/synth-mcp", "run", "synth-mcp"],
      "env": {
        "SYNTH_SOUNDFONT_PATH": "/absolute/path/to/soundfont.sf2"
      }
    }
  }
}

使用示例

// List parts in a score
{"tool": "get_parts", "arguments": {"musicxml": "<score-partwise>...</score-partwise>"}}

// The same, reading a file instead of copying the score into the conversation
{"tool": "get_parts", "arguments": {"musicxml_path": "scores/chorale.mxl"}}

// Synthesize the full score
{
  "tool": "synthesize",
  "arguments": {
    "musicxml": "<score-partwise>...</score-partwise>",
    "output_path": "/tmp/full.wav"
  }
}

// Synthesize Soprano part only at 80% tempo
{
  "tool": "synthesize",
  "arguments": {
    "musicxml": "<score-partwise>...</score-partwise>",
    "output_path": "/tmp/soprano.wav",
    "parts": ["Soprano"],
    "tempo_factor": 0.8
  }
}

// Practice track: Alto loud, others soft, bars 17-24 three times, one bar of count-in
{
  "tool": "synthesize",
  "arguments": {
    "musicxml_path": "scores/chorale.mxl",
    "preset": "learning",
    "focus_part": "Alto",
    "measures": [17, 24],
    "repeat": 3,
    "count_in_bars": 1
  }
}

// Starting notes before singing
{"tool": "starting_pitches", "arguments": {"musicxml_path": "scores/chorale.mxl"}}

parts 接受来自 get_parts 的部分 ID（"P1"）、部分名称（"Soprano"，不区分大小写）或声部（"S"、"Alto"、"Alt"、"A1"，用于分部）；未知部分会返回有效选项。 part_ids 仍可作为已弃用的别名使用一个次要版本。

所有接受 musicxml 的工具也接受 musicxml_path（两者必须且只能提供一个）：位于输出根目录中的 .musicxml、.xml 或压缩的 .mxl 文件，客户端作为 MCP 根目录共享的文件夹，或 SHEET_MUSIC_INPUT_ROOTS 中的文件夹。建议优先使用它，并传入其他服务返回的路径。describe_score 会报告部分 ID、音域和时长，而不返回乐谱。

tempo_factor 范围：0.25–4.0。低于 1.0 会减慢速度；高于 1.0 会加快速度。不会影响音高。

synthesize 的练习选项（均为可选；不填写则生成原始音轨）：

选项	值	效果
measures	[start, end]	仅播放这些印刷小节（弱起小节为 0）
repeat	1–20	将选段播放指定次数
count_in_bars	0–4	音乐开始前播放木鱼节拍
metronome	true / false	音乐的每一拍也播放节拍声
timbre	score、piano、choir、organ	所有部分使用的音色（score 保留乐谱中的乐器）
preset + focus_part	learning（重点声部 1.5，其他声部 0.5）、karaoke（重点声部静音）、equal	各部分的音量
part_gains	部分 → 0.0–2.0	各部分音量，会覆盖预设

starting_pitches 始终会返回文本；音频片段（单声道 16 kHz WAV，≤ 200 KB 时内嵌）需要 soundfont 和 FluidSynth。若缺少它们，结果会在 audio_unavailable 中说明原因。

测试

# Unit tests (no soundfont required)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v

# Integration tests (synthesizes real audio)
VIRTUAL_ENV= SYNTH_SOUNDFONT_PATH=/usr/share/sounds/sf2/TimGM6mb.sf2 \
  .venv/bin/pytest tests/ -v -m integration

依赖项

• music21 — 乐谱解析和 MIDI 导出
• pyfluidsynth — FluidSynth 的 Python 绑定
• mcp — MCP 协议

已知限制

• music21 的 MIDI 导出可能会丢失某些演奏法和力度标记
• 音频输出始终为 WAV；如有需要，可使用 ffmpeg -i out.wav out.mp3 转换
• 大型乐谱（100+ 小节）可能需要数秒才能合成

系统要求

• Python 3.11+
• libfluidsynth 共享库（Linux 上为 libfluidsynth.so.3）
• SF2 音色库文件