ferraus score
Notation from a recording or a MIDI file
Quality tier: best-effort. Results are reported with a quality or confidence estimate.
Synopsis
ferraus score <input> [options] [-o <output>]
What it does
Turns a MIDI file (or a recording, by running separate, transcribe, analyze tempo, analyze key and analyze chords first) into readable notation: a lead sheet with chord symbols, a grand-staff piano score with a hand split, a drum score with the standard drum map, or tonic sol-fa. Notes are quantized to --quantize with triplet detection, split into at most two voices per staff, rests are filled, ties cross bar lines, pickups are detected, and accidentals are spelled for the key. MusicXML 4.0 is the main output; add --midi, --pdf, --svg, --png, --abc, --ly, --solfa-txt, or --json-out for more. Every measure carries a confidence; low ones are listed with reasons.
Examples
MIDI to a MusicXML score plus an engraved PDF
ferraus score song.mid -o song.musicxml --pdf song.pdf
Grand staff with a fixed hand split at middle C
ferraus score piano.mid --layout grand --split C4 -o piano.musicxml
Drum score with the standard drum map
ferraus score beat.mid --layout drums -o drums.musicxml
Lead sheet with guitar diagrams, transposed up three semitones, with lyrics
ferraus score melody.mid --chords diagrams --transpose 3 --lyrics words.txt -o lead.musicxml
Tonic sol-fa text only, no staff
ferraus score hymn.mid --solfa only -o hymn.txt
Notation from a recording: separate, transcribe, and notate three stems
ferraus score take.wav --parts vocals,bass,drums -o take.musicxml --midi take.mid
Options
| Flag | Type | Default | Meaning |
|---|---|---|---|
--layout | auto | lead-sheet | grand | treble | bass | drums | solfa | auto | auto: MIDI channel 10 becomes a drum score, wide-range parts a grand staff, others a lead sheet (bass clef when low); for audio, vocals → lead sheet, piano → grand staff, drums → drum score |
--chords | on | off | diagrams | on | on: chord symbols above the staff (C, Am7, G/B); diagrams: also guitar fretboard diagrams (with a capo suggestion when --transpose is used) |
--solfa | off | on | only | fixed | fixed-only | off | on: tonic sol-fa syllables (movable do) under the notes; only: write sol-fa text and no staff; fixed / fixed-only: fixed do (do = C) |
--key | text | auto | Key of the input (before --transpose) such as G, Em, Bb major; auto uses the MIDI key signature (or analyze key for audio) or a Krumhansl estimate on the notes |
--time | text | auto | Time signature such as 3/4 or 6/8; auto uses the MIDI time signature (or analyze tempo for audio) |
--tempo | text | auto | Tempo in quarter notes per minute; auto uses the MIDI tempo |
--quantize | grid | 1/16 | Quantization grid (1/8, 1/16, 1/32; 1/8T forces triplets) |
--triplets | auto | on | off | auto | Triplet detection per beat: auto picks triplets when they fit clearly better than the straight grid |
--split | text | auto | Grand-staff hand split: auto (dynamic around middle C within a hand span) or a note such as C4 (that note and above go to the right hand) |
--parts | text | auto | For audio: stems to notate, comma separated from vocals,piano,guitar,bass,drums (auto: all of them) |
--lyrics | path | — | Text file of lyrics, one syllable per melody note (hyphenate syllables: hel-lo; _ holds a syllable) |
--transpose | integer | 0 | Transpose by semitones (e.g. -2, 5) |
--title | text | — | Title |
--composer | text | — | Composer |
--pickup | on|off | on | Detect a pickup (anacrusis) bar |
--midi | path | — | Also write the MIDI performance of the notation to this path (.mid) |
--pdf | path | — | Also engrave a PDF to this path (needs the ferraus-engrave helper or LilyPond) |
--svg | path | — | Also engrave SVG pages to this path (page 2 onward as <name>-2.svg, ...) |
--png | path | — | Also engrave PNG pages to this path (page 2 onward as <name>-2.png, ...) |
--abc | path | — | Also write ABC notation to this path |
--ly | path | — | Also write LilyPond source to this path |
--mei | path | — | Also write MEI to this path |
--solfa-txt | path | — | Also write tonic sol-fa text to this path (.md writes Markdown) |
--json-out | path | — | Also write the agent-facing score JSON to this path (named json-out because --json is the global result flag) |
--engraver | auto | verovio | lilypond | native | auto | Engraving engine for SVG/PDF/PNG: auto tries the Verovio helper, then LilyPond, then (SVG only) the minimal native renderer |
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 - Schema:
ferraus schema score - Pipeline:
{ op: score, args: { ... } }(flag names with_instead of-) - fx stage: no
{"command": "score", "defaults": {"layout": "auto", "chords": "on", "solfa": "off", "key": "auto", "time": "auto", "tempo": "auto", "quantize": "1/16", "triplets": "auto", "split": "auto", "parts": "auto", "transpose": "0", "pickup": "on", "engraver": "auto"}}