Setting up Audiveris

Copy Markdown View Source

mix mx.scan reads the music on a scanned page with Audiveris, an open source optical music recognition program under the AGPL v3. mx runs it as a separate program and ships none of its code, so it is installed apart from mx. This runbook sets up Audiveris 5.11.0 on macOS on Apple silicon, the setup the tests and the example were made with.

Install Audiveris

Download the installer from the releases page, https://github.com/Audiveris/audiveris/releases, which also holds installers for Linux and Windows:

curl -L -o audiveris.dmg https://github.com/Audiveris/audiveris/releases/download/5.11.0/Audiveris-5.11.0-macosx-arm64.dmg

The disk image asks you to accept the AGPL before it mounts, so pipe yes into it from a terminal, or open it in Finder and click Agree:

mkdir audiveris-mnt
yes | hdiutil attach -nobrowse -quiet -mountpoint ./audiveris-mnt audiveris.dmg
cp -R audiveris-mnt/Audiveris.app /Applications/
hdiutil detach -quiet audiveris-mnt

The app carries its own Java runtime, so no Java needs installing.

Check that mx finds it

mx looks for Audiveris in this order:

  • the program named in the AUDIVERIS environment variable;
  • audiveris on the path;
  • /Applications/Audiveris.app/Contents/MacOS/Audiveris, where the macOS installer puts it.

Run it once from the terminal; it prints its command line options:

/Applications/Audiveris.app/Contents/MacOS/Audiveris -help

On Linux or Windows, or with the app somewhere else, set AUDIVERIS to the program, such as export AUDIVERIS=/path/to/Audiveris.

Install the OCR languages

Audiveris reads part names, lyrics and tempo words with Tesseract, and ships no languages for it. Without them it logs "No installed OCR languages", reads lyrics as dynamics, and names every part "Voice". Download the languages your scores use, here English, German and Italian, into Audiveris's tessdata folder:

dir="$HOME/Library/Application Support/AudiverisLtd/audiveris/tessdata"
mkdir -p "$dir"
for lang in eng deu ita; do
  curl -L -o "$dir/$lang.traineddata" "https://github.com/tesseract-ocr/tessdata/raw/main/$lang.traineddata"
done

Audiveris logs "Installed OCR languages: deu,eng,ita" when it starts, which mix mx.scan keeps in audiveris.log beside the pages. TESSDATA_PREFIX names another folder, if the languages live elsewhere.

Install poppler, for PDFs

mix mx.scan renders PDF pages with poppler's pdftoppm and counts them with its pdfinfo:

brew install poppler

Pages given as PNG, JPEG or TIFF images need no poppler. The image work itself is done with Vix, which mx installs as a Hex dependency with a prebuilt libvips.

Run the tests

The tests that run Audiveris are tagged audiveris and left out of a plain mix test. They take two to three minutes:

mix test --only audiveris

When a scan goes wrong

mix mx.scan score.pdf leaves a folder score-pages beside score.mxl, holding each page as Audiveris was given it, the .omr book Audiveris made of it, and Audiveris's logs.

  • "mix mx.scan needs Audiveris": mx found no program in the three places above.
  • "No installed OCR languages" in the log: install the languages above.
  • "No target duration for measures ... please check time signatures" in the log: Audiveris missed the time signature, and the rhythms on that page are unreliable.
  • A page named as having no music: Audiveris found no staff lines, as on a page of text, or the scan is too faint or too small; look at its image in the pages folder.
  • Wrong notes in one part: Audiveris often misses the key signature after an old C clef, such as a soprano clef, so that part plays naturals for sharps or flats; compare the part's notes with the page.
  • Handwritten scores, such as Bach's autographs, are not read at all.

To correct a page by hand, open its .omr book in Audiveris, fix the notes, export it as MusicXML, and import that with mix mx.import.

Sources