Singing Pitch Tracker

pitch-mcp

用于实时音高检测和乐谱对齐的 MCP 服务。通过麦克风监听歌唱者，并报告其在乐谱中的当前位置，以及演唱是否准确。

功能

涵盖三个目标：

• 目标 4 — 演唱时显示当前小节／拍位置
• 目标 5 — 报告音高准确度（偏高／偏低／准确）
• 目标 6 — 根据哼唱或演唱的乐句，识别歌唱者在乐谱中的位置

既支持对预录音频进行离线分析，也支持实时麦克风输入。

工具

工具	描述
analyze_recording	离线：根据参考 MusicXML 乐谱分析 WAV 文件；返回每个音符的准确度和 highlights（“E5 偏低，位于第 12–14 小节（平均低 35 音分）”）
start_practice	一次调用即可加载乐谱并开启麦克风；返回 session_id
load_score	将 MusicXML 乐谱加载到命名会话中；返回 session_id
describe_score	以较低开销概述乐谱：标题、调性、速度、声部的 ID 和音域
start_monitoring	开启麦克风并开始实时音高检测
get_current_position	查询当前乐谱位置和音高准确度
stop_monitoring	停止麦克风并返回包含 highlights 的会话摘要
list_sessions	列出已打开的练习会话及其声部、状态（loaded／monitoring）和空闲时间
list_capabilities	返回服务元数据：音高检测后端、麦克风可用性
health_check	检查运行时依赖（librosa、sounddevice/portaudio）是否可用

乐谱可通过 musicxml_path（.musicxml、.xml 或 .mxl 文件，首选）或内联的 musicxml 文本提供，不能同时提供两者。路径必须位于输出根目录（SHEET_MUSIC_OUTPUT_ROOT，默认为工作目录）、客户端的 MCP 根目录或 SHEET_MUSIC_INPUT_ROOTS 中的文件夹内。

analyze_recording、load_score 和 start_practice 可选用 measures: [start, end]（乐谱上标注的小节编号，包含首尾；弱起小节编号为 0），仅练习或分析指定小节。报告中的小节编号保留乐谱上的原编号。

安装

cd pitch-mcp
uv sync

实时监控（start_monitoring）需要 PortAudio：

# Ubuntu / Debian
sudo apt install libportaudio2

**快速安装：**在 Ubuntu/Debian/Linux Mint 上，运行 bash install.sh 即可自动处理 uv 和可选的 libportaudio2 安装；完整的非技术人员操作指南请参阅 SETUP.md。 examples/ 中提供了现成的客户端配置（Claude Desktop、Cursor、Windsurf、Continue、Zed）。如果遇到问题，请查看 TROUBLESHOOTING.md。

运行

uv run pitch-mcp

配置

变量	默认值	描述
PITCH_BACKEND	librosa	音高检测算法：librosa 或 crepe
PITCH_SESSION_IDLE_MINUTES	10	空闲达到指定分钟数后关闭练习会话（及其麦克风）；0 表示永不关闭。会话关闭后的一小时内，stop_monitoring 仍会返回其摘要，并附带 "timed_out": true。

crepe 需要手动安装 TensorFlow（约 500 MB），并会在首次使用时下载约 50 MB 的模型权重。默认的 librosa 后端（pYIN 算法）无需额外设置，即可很好地处理歌声。

使用示例

// Offline analysis of a recording
{
  "tool": "analyze_recording",
  "arguments": {
    "audio_path": "/path/to/recording.wav",
    "musicxml_path": "/path/to/score.mxl",
    "part": "Soprano"
  }
}

// Real-time session
{"tool": "describe_score", "arguments": {"musicxml_path": "/path/to/score.mxl"}}
// → returns parts with IDs ("P1" …), names and ranges

{"tool": "start_practice", "arguments": {"musicxml_path": "/path/to/score.mxl", "part": "Alto", "measures": [17, 24]}}
// → returns {"session_id": "abc123", "measure_count": 8, ..., "status": "started"}
// (the same as load_score followed by start_monitoring)

{"tool": "get_current_position", "arguments": {"session_id": "abc123"}}
// → returns measure, beat, expected pitch, detected pitch, accuracy

{"tool": "stop_monitoring", "arguments": {"session_id": "abc123"}}
// → summary with accuracy_histogram and highlights, e.g. "flat in m.19–21 (-32 cents avg over 5 notes)"

音频必须为 16 位 PCM WAV 格式。不支持 MP3 和 FLAC。

测试

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

# Integration tests (offline analysis against a committed fixture pair)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v -m integration

# Manual tests (real microphone required — skip in CI)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v -m manual

总计 300 项测试中有 294 项是单元测试（运行 292 项，跳过 2 项），使用模拟对象和合成的（内存中）WAV 数据运行——不需要真实音频硬件或预录制的测试样本。其余 6 项标记为 integration（4 项——使用已提交的 tests/fixtures/ 文件对进行离线分析）或 manual（2 项——完整的真实麦克风会话生命周期测试）；这些测试由 tests/conftest.py 从普通的 pytest tests/ 运行中排除。使用 -m integration／-m manual 显式选择运行。

依赖项

• librosa — pYIN 音高检测（主要后端，纯 Python）
• music21 — 乐谱解析和音高计算
• sounddevice — 实时麦克风输入
• numpy、scipy — 数值计算
• mcp — MCP 协议

系统要求

• Python 3.12+
• libportaudio2 — 实时麦克风输入（start_monitoring）所需
• 离线分析无需系统库

阶段状态

阶段	状态
阶段 A — 离线分析	已完成。基于 DTW 的对齐（dtaidistance）；292 个单元测试，以及针对已提交样例对（tests/fixtures/）的 4 个 -m integration 测试
阶段 B — 实时监控	已完成。位置跟踪由音频驱动（匹配检测到的音高，而非仅依赖经过的时间）；支持 tempo_bpm 覆盖。通过使用模拟 sounddevice 的单元测试验证；另有完整生命周期的 -m manual 测试用于验证真实麦克风，但运行这些测试需要真实硬件