Singing Pitch Tracker

pitch-mcp

リアルタイムの音高検出と楽譜上の位置合わせを行う MCP サーバーです。マイクを通じて歌声を聞き取り、楽譜上の現在位置と、音程が合っているかどうかを報告します。

機能

次の3つの目標に対応します。

• 目標 4 — 歌唱中の小節／拍の現在位置を表示します
• 目標 5 — 音程の正確さ（高すぎる／低すぎる／合っている）を報告します
• 目標 6 — ハミングまたは歌唱したフレーズから、楽譜上の位置を特定します

録音済み音声のオフライン分析と、マイク入力によるリアルタイム分析の両方に対応しています。

ツール

ツール	説明
analyze_recording	オフライン：WAV ファイルを参照用の MusicXML 楽譜と照合して分析し、音符ごとの正確さと highlights（「E5 が第12〜14小節で平均 -35 セント低い」など）を返します
start_practice	1回の呼び出しで楽譜を読み込み、マイクを起動します。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 をご覧ください。クライアント用の設定例（Claude Desktop、Cursor、Windsurf、Continue、Zed）は examples/ にあります。問題が発生した場合は、TROUBLESHOOTING.md をご確認ください。

実行

uv run pitch-mcp

設定

変数	デフォルト	説明
PITCH_BACKEND	librosa	音高検出アルゴリズム：librosa または crepe
PITCH_SESSION_IDLE_MINUTES	10	アイドル状態がこの分数続くと、練習セッション（およびそのマイク）を終了します。0 の場合は終了しません。セッションが終了した後も、1時間以内であれば 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件。実際のマイクを使ったセッションのライフサイクル全体）としてマークされており、通常の pytest tests/ の実行では tests/conftest.py によって除外されます。-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/）を使った -m integration テスト 4 件
フェーズ B — リアルタイムモニタリング	完了。位置の追跡は音声駆動です（経過時間だけでなく、検出された音高と一致します）；tempo_bpm による上書きをサポートしています。sounddevice をモックしたユニットテストでカバーされています。実際のマイクで検証するためのライフサイクル全体を対象とする -m manual テストもありますが、実行には実機のハードウェアが必要です