Commands
One program, nwc2musicxml. What it is given decides whether
it converts a single file or a batch, and whether it does the work itself
or hands it to the batch path.
Synopsis
nwc2musicxml [options] input.nwc [output.musicxml]
nwc2musicxml [options] file1.nwc file2.nwc ...
nwc2musicxml [options] --output-dir DIR file-or-dir ...
nwc2musicxml [options] --recursive --output-dir DIR directory
What counts as input
- A file whose name ends in
.nwc, in any case. - A directory, which contributes the
.nwcfiles directly inside it; other file types are ignored rather than reported. - A directory with
--recursive, which contributes every.nwcfile below it. - Two positional arguments are read as input and output only when the first ends in
.nwc, the second does not, and no--output-dirwas given. Otherwise every argument is an input.
Options
| Option | Effect |
|---|---|
--output-dir DIRalso -o |
Write every output file into this directory. It is created if it does not exist. |
--recursivealso -r |
Descend into subdirectories of a directory argument, keeping the relative structure underneath --output-dir. |
--overwrite |
Replace output files that already exist. Without it an existing output is left alone, which makes a second run convert only what is new. |
--validate |
Run the internal consistency checks: pitch validity, tie and slur pairing, measure durations against the time signature, empty staves. Problems are reported as warnings. |
--format FORMAT |
Output format. Only musicxml, the default, is implemented; anything else is refused rather than silently ignored. |
--warnings FILE |
Write warnings to this UTF-8 file as well as to standard error. |
--verbosealso -v |
One line per file as it is converted. |
--quietalso -q |
Suppress all output that is not an error. Warnings are not suppressed; --warnings and the exit status still report them. |
--debug |
Trace the pipeline itself: records as they are dispatched, staff headers, annotation decisions. For diagnosing one score, not for a batch. |
--helpalso -h |
Print the usage text and exit 1. |
--versionalso -V |
Print the program name and version and exit 0. |
Short options can be bundled — -rv is
--recursive --verbose — and case matters, so
-V is the version while -v is verbose.
Exit codes
| Code | Meaning | What to do |
|---|---|---|
0 | Converted, no warnings. | Nothing. |
1 | Converted, with warnings. | Read the warnings: part of the score was not understood, and the output should be checked. |
2 | Invalid or unsupported input. | The file is missing, unreadable, or not an NWC 2.x container. |
3 | Output error. | The output file or directory could not be written: permissions, or a full disc. |
4 | Internal error. | A bug. Report it with the file and the --debug trace. |
A batch reports 1 when any file warned, and a per-file
failure is counted and reported without stopping the batch. A script that
wants to distinguish "some files failed" from "some files warned" should
use the Perl API, where the counts are returned separately.
Examples
# beside the input
nwc2musicxml Pilgrim.nwc
# an explicit output path
nwc2musicxml Pilgrim.nwc out/Pilgrim.musicxml
# every score in a folder, into one output folder
nwc2musicxml --output-dir musicxml *.nwc
# a tree, keeping its shape, replacing what is already there
nwc2musicxml -r --overwrite -o musicxml scores/
# check a score and keep a log of what was said about it
nwc2musicxml --validate --warnings conv.log Pilgrim.nwc
Batch output
A batch prints a summary when it finishes: how many files were processed, how many converted, how many warned, and how many failed. The summary goes to standard error, so standard output stays free for whatever the calling script is doing with it.
The same work in Perl
Everything the command does is a method call. --output-dir is
output_dir, --recursive is
recursive, and the progress messages are
log_level. The Perl API page has the
signatures.
perldoc nwc2musicxml prints the same options and examples
from the installed distribution, which is the version to trust if this
page and your installation ever disagree.