Quick start

One file, one command, then open the result. Everything after that is about doing it to a folder instead of a file.

1. Convert one file

nwc2musicxml Pilgrim.nwc

With a single argument the output goes beside the input, with the extension replaced: Pilgrim.musicxml. When the conversion is clean the command prints nothing at all, which makes it safe to put in a Makefile.

2. Read the exit status

nwc2musicxml Pilgrim.nwc
echo $?

0 is a clean conversion, 1 means it converted but warned about something, 2 means the input was missing, unreadable or not an NWC file, 3 is an output failure and 4 is an internal error. A warning does not stop the file being written — it says part of the score was not understood, so the output is worth opening before it is trusted.

3. Open it

In MuseScore, File → Open and choose the .musicxml file; Finale, Sibelius and Dorico import the same format. If a program refuses it, check first that the file is well-formed XML, before suspecting the notes:

xmllint --noout Pilgrim.musicxml

4. Say where the output goes

nwc2musicxml Pilgrim.nwc /tmp/Pilgrim.musicxml

Two positional arguments are read as input then output, but only when the first ends in .nwc and the second does not. That rule exists so that nwc2musicxml a.nwc b.nwc stays what it looks like: two files to convert, not one file written over another.

5. Convert a folder

nwc2musicxml --output-dir musicxml scores/

A directory argument collects the .nwc files directly inside it. Add --recursive and the tree is walked instead, with the folder structure kept underneath the output directory:

nwc2musicxml --recursive --output-dir musicxml scores/

musicxml/suite-1/prelude.musicxml
musicxml/suite-1/fugue.musicxml
musicxml/suite-2/allemande.musicxml

6. Re-run it

Existing output files are skipped by default, so a second run only converts what is new. That is the useful behaviour when a folder of scores is being converted a few at a time — and the surprising one the day an edited score seems to have been ignored. --overwrite replaces what is there.

nwc2musicxml --recursive --overwrite --output-dir musicxml scores/

7. Collect the warnings

nwc2musicxml --recursive --warnings conversions.log --output-dir musicxml scores/

Warnings still go to standard error; --warnings writes a second copy to a UTF-8 file, which is how a batch of a hundred scores gets sorted out afterwards. --verbose adds a line per file as it goes, and --debug traces the pipeline itself — noisy, but it says which record of which staff produced the complaint.

8. Ask for the checks

nwc2musicxml --validate Pilgrim.nwc

--validate turns on the internal consistency checks: pitches in range, ties that are opened and closed, slurs that are closed, each measure's duration against the active time signature, and staves that never sound. It is not a schema validation — for that, run an XSD-aware validator over the output, or let a notation program import it.

9. Do it from Perl

use Music::NWC2MusicXML;

my $converter = Music::NWC2MusicXML->new(log_level => 'quiet');

my $counts = $converter->batch_convert(
        inputs     => [ glob('scores/**/*.nwc') ],
        output_dir => 'musicxml',
        recursive  => 1,
        base_dir   => 'scores',
        overwrite  => 1,
);

printf "%d converted, %d warned, %d failed\n",
        $counts->{successful}, $counts->{warnings}, $counts->{failed};

One bad score does not stop the batch: failures are caught, counted and reported, and the rest of the list is converted. The Perl API page has the arguments and the return values in full.