CLI Arguments

The command line interface consists in a sequence of arguments.

Any argument starting with the '@' character is interpreted as referring to a file, whose content is expanded in line. Such file is expected to contain one argument per line.

The general syntax of the arguments sequence is:

Options arguments -- Inputs arguments

Options

We start this description with the -help option which introduces all the other ones. We then review the other options using alphabetical order.

-help

Launching Audiveris with a -help argument will just display something like:

Audiveris Version:
   5.1.0

Syntax:
    audiveris [OPTIONS] [--] [INPUT_FILES]

@file:
    Content of file to be extended in line

Options:
 -annotate                              : (advanced) Annotate book symbols
 -batch                                 : Run with no graphic user interface
 -export                                : Export MusicXML
 -force                                 : Force step/transcribe re-processing
 -help                                  : Display general help then stop
 -option key=value                      : Define an application constant
 -output <output-folder>                : Define base output folder
 -print                                 : Print out book
 -run <qualified-class-name>            : (advanced) Run provided class on valid sheets
 -sample                                : (advanced) Sample all book symbols
 -save                                  : Save book on every successful batch step
 -sheets int[]                          : Select specific sheets numbers and ranges (like 2-5)
 -step [LOAD | BINARY | SCALE | GRID |  : Define a specific target step
 HEADERS | STEM_SEEDS | BEAMS |
 LEDGERS | HEADS | STEMS | REDUCTION |
 CUE_BEAMS | TEXTS | MEASURES | CHORDS
 | CURVES | SYMBOLS | LINKS | RHYTHMS
 | PAGE]
 -transcribe                            : Transcribe whole book

Input file extensions:
    .omr        : book file  (input/output)
    [any other] : image file (input)

Sheet steps are in order:
    LOAD       : Load the sheet (gray) picture
    BINARY     : Binarize the sheet picture
    SCALE      : Compute sheet line thickness, interline, beam thickness
    GRID       : Retrieve staff lines, barlines, systems & parts
    HEADERS    : Retrieve Clef-Key-Time systems headers
    STEM_SEEDS : Retrieve stem thickness & seeds for stems
    BEAMS      : Retrieve beams
    LEDGERS    : Retrieve ledgers
    HEADS      : Retrieve note heads & whole notes
    STEMS      : Build stems connected to heads & beams
    REDUCTION  : Reduce conflicts in heads, stems & beams
    CUE_BEAMS  : Retrieve cue beams
    TEXTS      : Call OCR on textual items
    MEASURES   : Retrieve raw measures from groups of bar lines
    CHORDS     : Gather notes heads into chords
    CURVES     : Retrieve slurs, wedges & endings
    SYMBOLS    : Retrieve fixed-shape symbols
    LINKS      : Link and reduce symbols
    RHYTHMS    : Handle rhythms within measures
    PAGE       : Connect systems within page

-batch

Runs the application in batch mode, that is with no GUI.

Processing is then fully determined by the CLI arguments (and by application constants).

-export

Exports the book using MusicXML 3.0 format into one or several ".mxl" files in the book folder.

When a book contains several movements, each movement is considered as a separate "Score" (in MusicXML parlance) and thus corresponds to a separate MusicXML file.

Remark: -export option implies -transcribe option implicitly.

-force

Forces the OMR processing (until the step specified by the -step option or the -transcribe option), whatever the current step of the sheet at hand.

This allows the OMR engine to re-process a sheet from its BINARY step.

-option

Must be followed by an argument formatted as key=value.

This defines an application constant.

For example

org.audiveris.omr.sheet.BookManager.useSeparateBookFolders=false

will prevent Audiveris to use separate folders, one for each book, and will thus mix the outputs of all books into a single folder.

See the Tools | Options menu to review (and possibly modify) all application constants.

NOTA: In batch mode, a constant assignment is valid only for the current application run. In interactive mode, a constant assignment is also persisted for subsequent application runs.

-output

Specifies Audiveris output base folder.

By default, this output base folder is chosen as the output sub-folder located in user Audiveris data folder (which depends on OS).

For a given input file, all its output items are put in a dedicated folder forged by the input file name without extension. We call this folder the "book folder".

For example, the OMR book (project) of say "myScore.pdf" image input will be saved as:

<user-Audiveris-data-folder>/output/myScore/myScore.omr

and the MusicXML export will result in:

<user-Audiveris-data-folder>/output/myScore/myScore.mxl

The -output option allows to define a base different from <user-Audiveris-data-folder>/output/

NOTA: If the input file is actually an OMR book (project) file (a ".omr" file), then this file is already an output and it implicitly defines the output target folder: any other output for this book will be put as a sibling file of the .omr file.

-print

Prints out the book content as a "-print.pdf" file in the book folder.

-run

Must be followed by an argument giving the fully qualified name of a Java class to be run on each valid sheet.

This option is meant for advanced users only.

-sample

Saves all recognized symbols of the book as training samples in the book folder.

These are meant to train the current (5.x) classifiers.

-save

Saves every successful batch step into the".omr" book file in the book folder.

This option is effective only in batch mode.

-sheets

Must be followed by one or several arguments, each argument being either a sheet number, or a range of sheet numbers.

This defines which precise sheets must be processed in the input file.

If there is no -sheets argument, of if it is followed by no number, all (valid) sheets will be processed in each input file.

Example:

-sheets 2 6-10 25

will result in the processing of sheets #2, #6, #7, #8, #9, #10, #25

-step

Specifies which OMR step should be reached (for each of the selected sheets).

If a sheet has already reached this desired step, then no OMR processing will be done on it, unless the -force option is present.

NOTA: The -transcribe option implies an implicit PAGE step, hence a -step option is not compatible with the -transcribe option (unless its value is PAGE).

-transcribe

Specifies to process all valid sheets of the book (or just the valid sheets specified explicitly) until the PAGE step and then reduce the book score(s).

As for the -step option, if the -forceoption is present, the sheets will be re-processed from their BINARY state.

NOTA: -transcribe is incompatible with any -step option (unless step value is PAGE).

--

This "--" argument is optional. It serves as a place-holder in the command line to end the options and begin the inputs.

Inputs

The command line can contain the names of zero, one or several input files. Input files are recognized and processed according to their file extension.

A .omr extension indicates a book file.

Any other extension is considered as an image(s) file.

Book input

Providing a .omr file as input allows to resume processing at the point it was saved, and to perform any additional task.

Image input

All major image formats (.pdf, .tif, .png, .jpg, etc) are recognized.

Each input file will give birth to a corresponding book file. A .pdf or .tif file may contain several images, leading to one book with several sheets.