ferraus score read
Optical music recognition: sheet music to MusicXML
Quality tier: best-effort. Results are reported with a quality or confidence estimate.
Synopsis
ferraus score read <input> [options] [-o <output>]
What it does
Reads printed sheet music (PDF pages or page images) into MusicXML with per-measure confidence. The builtin engine runs oemer's segmentation networks (ferraus models pull omr/oemer omr/oemer-seg, MIT) and rebuilds staves, clefs, key and time signatures, notes, chords, rests, accidentals, and dots from them; it reads one voice per staff and skips lyrics, tuplets, ties, and dynamics. PDFs are rasterized with pdftoppm or mutool (macOS sips: first page only). --engine audiveris uses the optional Audiveris bridge (ferraus doctor --install-audiveris). --review lists measures whose durations do not add up or whose symbols were uncertain; --fix applies an edit list (measure, voice, note, set) to correct them. Notation inputs (MusicXML, MEI, ABC, LilyPond, JSON) skip recognition, so --fix and --review work on any score.
Examples
Read the first four pages and list measures to check
ferraus score read sonata.pdf --pages 1-4 -o sonata.musicxml --review
Apply corrections to a score (no recognition needed)
ferraus score read sonata.musicxml --fix edits.json -o fixed.musicxml
Use the Audiveris bridge on a scanned page
ferraus score read page.png --engine audiveris -o page.musicxml
Options
| Flag | Type | Default | Meaning |
|---|---|---|---|
--pages | text | — | Pages to read, 1-based (1-4, 2,5-6); default all |
--dpi | integer | 300 | Rasterization resolution for PDF pages in dots per inch Range: 72..1200. |
--engine | builtin | audiveris | builtin | builtin: ONNX models from the model cache; audiveris: the optional Java bridge (AGPL) |
--review | flag | — | Report per-measure duration checks, uncertain measures, and an issue list |
--fix | path | — | Apply an edit list (JSON: [{measure, voice, note, set: {pitch, duration, ...}}]) before writing |
Global options
Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Processing failed |
| 2 | Usage or parameter error |
| 3 | Input missing or unreadable |
| 4 | Unsupported format or codec |
| 5 | Model not cached and downloads disabled |
| 6 | Model download or verification failed |
| 8 | Cancelled |
| 10 | Network error |
| 70 | Internal error (bug) |
Common mistakes
- Forgetting that outputs are never overwritten: pass
--overwriteor a new-opath when re-running. - Treating best-effort output as final: check the reported quality/confidence in
--json.
For models
- MCP tool:
ferraus_score_read - Schema:
ferraus schema score read - Pipeline:
{ op: score read, args: { ... } }(flag names with_instead of-) - fx stage: no
{"command": "score read", "defaults": {"dpi": "300", "engine": "builtin"}}