Building from sources (Windows, macOS, Linux, ArchLinux)

For GitHub users:

  • Audiveris “master” branch is updated only when a new release is published.
  • Instead, Audiveris development happens continuously in the “development” branch, so pull and checkout this development branch to get and build the latest version.
  • See workflow details in the dedicated Wiki article.

Table of contents

  1. Tools needed
  2. Clone, build and run
  3. Alternative run

Tools needed

  • Git: version control system.

  • Gradle: build tool.

  • Java Development Kit (JDK): version 21 (higher numbers may work, to be confirmed).
    This is the Java version needed for the master branch. The development branch may require a higher version, please check on the Audiveris project site.
    Audiveris 5.4 runs only on 64-bit architectures.

  • FreeType library: Unix-like platforms (including macOS) need FreeType in our $PATH to handle those specific PDFs that contain vector graphics.
    Fortunately, every known Unix-like OS distribution already contains a package for FreeType.

  • Tesseract OCR: The Tesseract libraries are automatically pulled as Gradle dependencies, but we will need some Tesseract language files for this OCR to work properly.
    Please check the OCR languages section.

Clone, build and run

To clone the Audiveris project, we can use the following command in a directory of our choice:

git clone https://github.com/Audiveris/audiveris.git

This will create a sub-directory named “audiveris” in our current directory and populate it with project material (notably source code and build procedure).

Now we move to this “audiveris” project directory:

cd audiveris

Once in this audiveris project directory, we can select the branch we want.
By default, we are on master branch.
To use the development branch with its latest features, we can use:

git checkout development

# And to make sure we grab even the latest updates:
git pull --all

We can build the software via the command:

# (Linux & Mac, or Cygwin terminal under Windows)
./gradlew build

# (Windows terminal)
gradlew.bat build

We can run the software, with its graphical interface, via the command:

# (Linux & Mac, or Cygwin terminal under Windows)
./gradlew run

# (Windows terminal)
gradlew.bat run

Please note that all these commands use the gradle wrapper (gradlew) which, behind the scenes, takes care of getting and launching the proper gradle version.

Alternative run

The gradle-based run, as described above, makes sure that all our potential modifications are compiled before the application is launched. This is the preferred approach for a developer.

However, if we don’t modify the code and merely want to launch the application we don’t need to go through gradle for each and every run.

Because, once we have built the software with the gradle build command as stated above, we now have a build/distributions folder in the repository root with tarred/zipped libraries (Audiveris.tar and Audiveris.zip).

We can simply extract either one of the archives:

# Either extract the .tar archive
tar -xf build/distributions/Audiveris.tar

# Or extract the .zip archive
unzip build/distributions/Audiveris.zip

Then, we can repeatedly run audiveris from those files:

# Run audiveris (append arguments if so needed):
java -cp "Audiveris/lib/*" Audiveris