Audiveris reads the relationships between the notes

A tiny dot can change how long a note lasts. For software reading a scanned score, finding that dot is only the beginning: it must also decide what the dot belongs to. Audiveris, an open-source optical music recognition application, approaches this problem through a sequence of image-processing steps and a graph of musical interpretations. Following that structure explains both how a paper score becomes editable music and why a human correction can matter far beyond the mark being repaired.[1][2][5]

The project combines recognition with an interactive editor and exports MusicXML for use in notation programs. Its documented scope is printed Common Western Music Notation; handwriting is outside that scope. This account follows the 5.11 handbook and, where implementation detail matters, the 5.11.0 source code.[1][8]

Close photograph of aged sheet music from Maple Leaf Rag, with densely printed piano notes, beams, and curved ties across the staves. — A passage from a first edition of Scott Joplin's *Maple Leaf Rag*, held by the Library of Congress Music Division. The notation's small marks and overlapping relationships are the material an optical music reader must interpret. Photograph: Shawn Miller, Library of Congress.[12]

The page arrives before the music

Opening a PDF creates an Audiveris Book, with a sheet placeholder for each image. The engine can process sheets independently; gathering their results happens at book level. Each sheet passes through successive steps, and the user can ask the pipeline to advance to a particular stage.[2]

The input still matters. Audiveris recommends grayscale scanning, generally around 300 DPI for an ordinary A4 or US Letter page, with roughly 20 pixels between adjacent staff lines as a more useful target. Too little detail can erase meaningful marks; excessive resolution consumes resources without necessarily helping recognition. The software uses detected staff lines as local references even when they are distorted, rather than automatically straightening the image.[3]

That makes the staff a measuring instrument. A note's position has meaning relative to nearby lines, so a recognition system needs the page's geometry before it can reliably interpret the marks placed on it. For a musician preparing an old printed part for editing, a cleaner scan can therefore improve the evidence available to every later stage.

A patch of ink can have several explanations

Audiveris calls a collection of foreground pixels a Glyph. At this level, the collection has no assigned musical shape and does not even belong to a staff or system. An Inter, short for interpretation, adds a proposed identity and contextual placement. Several interpretations can initially compete for the same glyph.[4]

The distinction is useful precisely when the picture is ambiguous. A small mark near a note may make more sense once nearby symbols have been recognized. Audiveris can postpone the choice, carrying candidates forward until it has more context. Each interpretation has an intrinsic grade based on its own evidence; supporting relationships can later contribute to a contextual grade.[4]

The architecture preserves a difference between what the page contains and what the engine thinks it means. That difference gives the editor something concrete to repair: the interpretation, while the original pixels remain visible behind it.[6]

Notes gain credibility from their neighbors

The Symbol Interpretation Graph, or SIG, connects interpretations within each musical system—the group of staves read together across a line. Its vertices are Inter objects; its edges are relationships. A plausible notehead and nearby stem can support one another through a HeadStemRelation. Mutually incompatible interpretations are connected by an exclusion relationship. Neutral relationships can describe membership, such as a chord containing several heads.[5]

At the REDUCTION and LINKS stages, the graph is reduced to resolve exclusions and remove interpretations with weak contextual support. A symbol consequently survives partly because it fits its neighbors. Recognizing isolated shapes is one contribution to the result; assembling a compatible musical configuration is another.[5]

This also explains the editor's design. It works directly with interpretations and relationships, while allowing changes to parts of the containing structure, such as systems and measures. The person correcting a page is operating on the same model that the recognition engine builds.[6]

A misplaced dot can become a timing problem

The rhythm stage makes those dependencies tangible. In the 5.11.0 implementation, RhythmsStep processes timing through PageRhythm. Its edit-impact handling distinguishes changes affecting a measure stack—the vertically aligned measures across parts—from changes requiring a whole page to be reconsidered. Augmentation dots belong to the former group; time-signature objects belong to the latter.[8]

The practical documentation supplies a musician-sized example. When a measure still fails the rhythm check after obvious problems have been fixed, it advises inspecting missing or incorrectly identified augmentation dots. A visually tiny mistake can leave a measure with the wrong duration. The same guide warns that a grace note mistaken for an ordinary note participates incorrectly in rhythm construction.[7]

These examples suggest a useful debugging order: inspect the musical evidence behind a timing failure before treating the failure as an export problem. They also explain why adding a replacement interpretation carelessly can cause trouble. The guide recommends removing the incorrect interpretation first; slightly different pixel selections can otherwise leave competing readings in the output.[7]

Save the work as well as the result

Audiveris produces two files with different responsibilities. The .omr project preserves the book and sheet recognition state. Internally it is a ZIP archive containing XML and sheet images, with book-level information separated from details that can be loaded as needed. This organization supports saving, resuming, and working through larger books without holding every sheet's full detail in memory.[9]

The .mxl export is compressed MusicXML for another application to read. By default, exporting a book produces a separate file for each detected movement. The project also supports an opus export, but its documentation cautions that editor support is limited.[10]

Keeping the input scan, .omr project, and exported score together is therefore a practical consequence of the design. The scan supplies the original evidence, the project preserves the correction work, and MusicXML carries the resulting notation onward. If a later rehearsal reveals a suspicious passage, those files support different kinds of investigation.

A playable file still needs a reader

Independent research helps explain why export success is an incomplete test. A 2024 evaluation study by Pau Torras, Sanket Biswas, and Alicia Fornés used Audiveris 5.3.1 to exercise a proposed representation and evaluation framework. Of 52,884 ground-truth measures, 40,622 could be matched with predicted measures: 76.9% coverage. The authors attributed missing predictions to failures to produce output on some pages.[11]

That figure describes one older version, dataset, and matching procedure. It is neither a current accuracy claim nor the percentage of notes a musician should expect to be correct. Its useful lesson is methodological: inspecting the surviving output alone can overlook material that never made it into the comparison.

For a solo arranger or small ensemble, the architecture supports a manageable experiment: process a representative passage, inspect its rhythms and voices against the scan, and judge the correction effort before taking on the entire score. A larger archive needs an explicit accounting of omitted pages and measures as well as transcription errors. Audiveris makes the intermediate reading accessible; a convincing finished score still depends on someone checking that the music on the page survived the journey.

cronfeed.work