Sheet Music OMR

omr-mcp

可使用光学乐谱识别（OMR）将乐谱图像转换为 MusicXML 的 MCP 服务。

功能

接收印刷乐谱的照片或扫描件，并返回 MusicXML 文档。支持单页或多页乐谱。可直接接入 sheet-music-mcp 流水线的其余部分。

识别工具可通过可选的 engine 参数选择两种 OMR 后端：

• oemer（默认）——速度快，除约 100 MB 的模型检查点外，无需额外下载。最适合 单行或双行谱表；会将多行谱表（SATB）合唱乐谱合并为一个声部（请参阅下文的“已知限制”）。
• audiveris——可正确将多行谱表 SATB 乐谱拆分为同时演奏的多个声部。要求源图像分辨率至少为 300 DPI，首次使用时需下载较大的文件（约 80 MB）；以子进程方式运行。

工具

工具	描述
recognize_sheet	将单张图像（文件路径或 base64）转换为 MusicXML；大型乐谱会返回 musicxml_path 和 score_summary（return：auto、path 或 inline）
recognize_sheet_to_file	转换单张图像并将 MusicXML 写入文件；返回路径和 score_summary
recognize_sheets	处理多页乐谱并将其合并为一个 MusicXML 文档（return 模式与 recognize_sheet 相同）
list_capabilities	返回服务元数据：后端版本、输入／输出格式、可用工具
list_supported_formats	（已弃用——请使用 list_capabilities）列出支持的输入和输出格式
health_check	检查所有运行时依赖项是否可用，并返回易读的状态摘要；首次运行时很有用

安装

cd omr-mcp
uv sync

首次运行时，oemer 会下载约 100 MB 的模型检查点。此操作仅执行一次，之后会缓存。

**快速安装：**运行 bash install.sh，即可通过一条命令完成所有设置，并输出可直接粘贴的客户端配置——请参阅 SETUP.md。examples/ 中提供了适用于 Claude Desktop、Cursor、Windsurf、Continue 和 Zed 的预制配置。遇到问题？请查看 TROUBLESHOOTING.md。

运行

uv run omr-mcp

无需设置环境变量。

Claude Desktop 配置

{
  "mcpServers": {
    "omr": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/omr-mcp", "run", "omr-mcp"]
    }
  }
}

使用示例

// Recognize a single image file (default engine: oemer)
{"tool": "recognize_sheet", "arguments": {"image": "/path/to/scan.png", "format": "path"}}

// Recognize from base64-encoded image
{"tool": "recognize_sheet", "arguments": {"image": "<base64 data>", "format": "base64"}}

// Recognize a multi-staff SATB choir score with correct voice separation (300+ DPI source required)
{"tool": "recognize_sheet", "arguments": {"image": "/path/to/satb_scan.png", "engine": "audiveris"}}

// Process multiple pages into one score
{"tool": "recognize_sheets", "arguments": {"images": ["/path/page1.png", "/path/page2.png"]}}

// Always get the MusicXML text inline, however large (default "auto": a musicxml_path above 8 KB)
{"tool": "recognize_sheet", "arguments": {"image": "/path/to/scan.png", "return": "inline"}}

// Save result directly to file (output_path must lie inside SHEET_MUSIC_OUTPUT_ROOT)
{"tool": "recognize_sheet_to_file", "arguments": {"input_path": "/path/scan.png", "output_path": "score.musicxml"}}

大型结果会以 {"musicxml_path": ..., "score_summary": {...}, "metadata": ...} 的形式返回，文件位于 <SHEET_MUSIC_OUTPUT_ROOT>/scores/ 下（默认值：服务的工作目录）。将该路径作为 musicxml_path 传递给其他服务的工具，无需复制乐谱。

测试

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

# Integration tests (~10 min one-time model-checkpoint download, then ~90-100s per page on CPU)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v -m integration

测试样本

test_samples/pdmx_satb_samples/ 中提供了 SATB 无伴奏合唱样本：

pdmx_satb_samples/
├── mxl/    # MusicXML ground truth
├── pdf/    # PDF scores
└── png/    # PNG images (OMR input)

来源：PDMX 数据集——超过 25 万份公有领域乐谱。

依赖项

• oemer——默认的深度学习 OMR 引擎（UNet + SVM，ONNX Runtime）
• onnxruntime>=1.30——1.19 之后发布的版本会拒绝 oemer 的 unet_big 检查点中预置的负 ConvTranspose 填充；onnx_compat.py 会在每次识别前将其改写为等效的 output_padding（需要 onnx）。这使其支持 Python 3.11–3.14（请参阅 docs/HANDOVER.md 中的注意事项）
• opencv-python-headless==4.10.0.84——固定版本；5.x 更改了 cv2.HoughLinesP() 的返回结构，会导致 oemer 的谱线提取崩溃（请参阅 pyproject.toml 注释／docs/HANDOVER.md 中的注意事项）
• Pillow——图像加载和验证
• defusedxml——安全的 XML 解析
• mcp——MCP 协议
• Audiveris——可选的 OMR 引擎（engine="audiveris"）。它不是 Python 依赖项：这是一个独立的二进制文件（内置自己的 JRE），首次使用该引擎时会自动下载。需要使用 dpkg-deb（几乎所有 Debian／Ubuntu 系统都已预装）进行解压，无需 root 权限或安装到系统中。

已知限制

• oemer 的默认输出会丢失 SATB 声部结构。 oemer 会依次读取合唱谱的多行谱表系统，而不是同时读取，因此 4–5 个声部的 SATB 乐谱会被输出为一个合并的 <part>，谱号还会来回交替，而不是每个声部对应一个分谱——这会造成实际的数据丢失，并非无害的建模差异（通过检查生成的 MusicXML 确认）；这是 oemer 本身的架构限制（其节奏对齐代码会硬性断言同时存在的谱表轨道最多为 2 条，详见 docs/HANDOVER.md）。对于多行谱表的合唱乐谱，请使用 engine="audiveris"——它能够正确地将声部分离为同时呈现的分谱，并已通过真实样例验证。要求源图像分辨率达到 300 DPI 或更高。

性能说明

• 处理时间：CPU 上使用 oemer 时，每页约 90–100 秒（模型检查点缓存后）；测试中使用 audiveris 时，每页约 7–15 秒（尽管启动 JVM 子进程会产生额外开销）
• 两种引擎的输出在不同运行之间可能略有差异——不要断言 XML 必须完全相同
• 生成的 MusicXML 在功能上正确，但可能无法通过严格的架构验证

系统要求

• Python 3.11+
• 无需系统库（ONNX Runtime 通过 pip 捆绑）