Singing Pitch Tracker

pitch-mcp

MCP server for real-time pitch detection and score alignment. Listens to a singer via microphone and reports their current position in a score and whether they are singing in tune.

What it does

Covers three goals:

• Goal 4 — Show the current measure/beat position while singing
• Goal 5 — Report pitch accuracy (too high / too low / on pitch)
• Goal 6 — Identify where in the score a singer is based on a hummed or sung phrase

Supports both offline analysis of pre-recorded audio and real-time microphone input.

Tools

Tool	Description
analyze_recording	Offline: analyse a WAV file against a reference MusicXML score; returns per-note accuracy and highlights ("flat on E5 in m.12–14 (-35 cents avg)")
start_practice	Load a score and open the microphone in one call; returns a session_id
load_score	Load a MusicXML score into a named session; returns a session_id
describe_score	Summarize a score cheaply: title, key, tempo, parts with IDs and ranges
start_monitoring	Open the microphone and begin real-time pitch detection
get_current_position	Poll the current score position and pitch accuracy
stop_monitoring	Stop the microphone and return a session summary with highlights
list_sessions	List open practice sessions with their part, state (loaded / monitoring) and idle time
list_capabilities	Return server metadata: pitch backend, microphone availability
health_check	Check that runtime dependencies (librosa, sounddevice/portaudio) are available

Scores are given as musicxml_path (a .musicxml, .xml or .mxl file, preferred) or as inline musicxml text, never both. Paths must lie inside the output root (SHEET_MUSIC_OUTPUT_ROOT, default the working directory), the client's MCP roots or a folder in SHEET_MUSIC_INPUT_ROOTS.

analyze_recording, load_score and start_practice take an optional measures: [start, end] (printed bar numbers, inclusive; a pickup is 0) to practise or analyse only those bars. Reported measures keep their printed numbers.

Installation

cd pitch-mcp
uv sync

For real-time monitoring (start_monitoring), PortAudio is required:

# Ubuntu / Debian
sudo apt install libportaudio2

Quick install: on Ubuntu/Debian/Linux Mint, bash install.sh handles uv and the optional libportaudio2 install for you — see SETUP.md for the full non-technical walkthrough. Ready-made client configs (Claude Desktop, Cursor, Windsurf, Continue, Zed) are in examples/. If something goes wrong, check TROUBLESHOOTING.md.

Running

uv run pitch-mcp

Configuration

Variable	Default	Description
PITCH_BACKEND	librosa	Pitch detection algorithm: librosa or crepe
PITCH_SESSION_IDLE_MINUTES	10	Close a practice session (and its microphone) after this many idle minutes; 0 never closes. stop_monitoring still returns the summary of a closed session for an hour, with "timed_out": true.

crepe requires a manual TensorFlow install (~500 MB) and downloads ~50 MB of model weights on first use. The default librosa backend (pYIN algorithm) works well for singing voice with no extra setup.

Usage examples

// 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)"

Audio must be 16-bit PCM WAV. MP3 and FLAC are not supported.

Testing

# 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

294 of the 300 total tests are unit tests (292 run, 2 skipped), run against mocks and synthetic (in-memory) WAV data — none require real audio hardware or pre-recorded fixtures. The other 6 are marked integration (4 — offline analysis against the committed tests/fixtures/ pair) or manual (2 — full real-microphone session lifecycle) and are excluded from a plain pytest tests/ run by tests/conftest.py; select them explicitly with -m integration / -m manual.

Dependencies

• librosa — pYIN pitch detection (primary backend, pure Python)
• music21 — score parsing and pitch calculations
• sounddevice — real-time microphone input
• numpy, scipy — numerics
• mcp — MCP protocol

System requirements

• Python 3.12+
• libportaudio2 — required for real-time microphone input (start_monitoring)
• No system libraries required for offline analysis

Phase status

Phase	Status
Phase A — offline analysis	Complete. DTW-based alignment (dtaidistance); 292 unit tests plus 4 -m integration tests against a committed fixture pair (tests/fixtures/)
Phase B — real-time monitoring	Complete. Position tracking is audio-driven (matches detected pitch, not just elapsed time); tempo_bpm override supported. Covered by unit tests with mocked sounddevice; full-lifecycle -m manual tests exist for real-microphone verification but require real hardware to run