Sheet Music OMR

omr-mcp

光学式楽譜認識（OMR）を使用して、楽譜画像をMusicXMLに変換するMCPサーバーです。

機能

印刷された楽譜の写真やスキャン画像を受け取り、MusicXMLドキュメントを返します。1ページの楽譜にも複数ページの楽譜にも対応しています。sheet-music-mcpパイプラインの後続処理に直接渡せます。

認識ツールでは、任意のengine引数で2つのOMRバックエンドを選択できます。

• oemer（デフォルト）— 高速で、約100 MBのモデルチェックポイント以外の追加ダウンロードは不要です。1段または2段の楽譜に最適です。複数段の合唱譜（SATB）は1パートに統合されます（下記の「既知の制限事項」を参照）。
• audiveris — 複数段のSATB楽譜を同時進行するパートに正しく分離します。300 DPI以上のソース画像と、初回使用時のより大きなダウンロード（約80 MB）が必要です。サブプロセスとして実行されます。

ツール

ツール	説明
recognize_sheet	1枚の画像（ファイルパスまたはbase64）をMusicXMLに変換します。大きな楽譜はmusicxml_pathとscore_summaryを返します（return：auto、path、inline）
recognize_sheet_to_file	1枚の画像を変換し、MusicXMLをファイルに書き込みます。パスとscore_summaryを返します
recognize_sheets	複数ページを処理し、1つのMusicXMLドキュメントに統合します（recognize_sheetと同じreturnモード）
list_capabilities	サーバーのメタデータを返します：バックエンドのバージョン、入出力形式、利用可能なツール
list_supported_formats	（非推奨 — list_capabilitiesを使用してください）対応する入出力形式を一覧表示します
health_check	すべての実行時依存関係が利用可能か確認し、人が読めるステータスの概要を返します。初回実行時に便利です

インストール

cd omr-mcp
uv sync

初回実行時に、oemerが約100 MBのモデルチェックポイントをダウンロードします。ダウンロードは一度だけ行われ、キャッシュされます。

クイックインストール： bash install.shを実行すると、すべてを1つのコマンドでセットアップし、そのまま貼り付けて使えるクライアント設定を表示します。SETUP.mdを参照してください。Claude Desktop、Cursor、Windsurf、Continue、Zed用の設定例はexamples/にあります。お困りの場合は、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

テスト用サンプル

SATBアカペラのサンプルはtest_samples/pdmx_satb_samples/にあります。

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> が作られるのではなく、複数の譜表が統合された単一の <part> として出力され、音部記号が交互に切り替わります。これは無害なモデリング上の差異ではなく、実際のデータ損失です（生成された MusicXML の確認により検証済み）。また、これは oemer 自体のアーキテクチャに起因します（リズム調整コードでは、同時に扱える譜表トラックは最大 2 つとハードアサートされています。詳しくは docs/HANDOVER.md を参照してください）。複数段の合唱譜には engine="audiveris" を使用してください。実際のフィクスチャでの検証により、声部が同時に演奏される別々のパートとして正しく分離されることを確認済みです。ソース画像には 300 DPI 以上が必要です。

パフォーマンスに関する注意事項

• 処理時間：モデルのチェックポイントをキャッシュした後の oemer は、CPU で 1 ページあたり約 90～100 秒です。テストでは、audiveris は JVM のサブプロセス起動オーバーヘッドがあるにもかかわらず、1 ページあたり約 7～15 秒でした。
• どちらのエンジンも、実行ごとに出力が多少変わることがあります。XML が完全に一致することをアサートしないでください。
• 生成された MusicXML は機能的には正しいものの、厳密なスキーマ検証には合格しない場合があります。

システム要件

• Python 3.11+
• システムライブラリは不要です（ONNX Runtime は pip 経由でバンドルされています）