/ 
Music-NWC2MusicXML-0.001.1
/ README.md

NAME

Music::NWC2MusicXML - Convert NoteWorthy Composer 2 .nwc score files to MusicXML.

VERSION

0.001.1

SYNOPSIS

# Simple conversion
use Music::NWC2MusicXML;

my $converter = Music::NWC2MusicXML->new;
$converter->convert(
    input  => 'Pilgrim.nwc',
    output => 'Pilgrim.musicxml',
);

# Batch conversion
$converter->batch_convert(
    inputs     => [ glob('*.nwc') ],
    output_dir => 'musicxml',
    overwrite  => 1,
);

DESCRIPTION

Music::NWC2MusicXML is the top-level facade for the NWC-to-MusicXML conversion pipeline. It coordinates three independent stages:

Each stage is independently testable. The facade wires them together, handles batch processing, and routes all diagnostics through a single Music::NWC2MusicXML::Diagnostics instance.

PRESERVATION PRINCIPLE

The guiding principle of the conversion is:

Preserve musical meaning rather than graphical appearance.

Priority order: notes and rhythm > voices > measures > articulations > dynamics > lyrics > structural markings > instrument info > graphical layout.

new

Construct a converter.

Purpose

Creates a configured converter instance that can be reused for multiple conversions without reconstructing the pipeline components each time.

Arguments

Named parameters:

Returns

Blessed Music::NWC2MusicXML object.

Usage Example

my $c = Music::NWC2MusicXML->new(log_level => 'verbose', validate => 1);

API SPECIFICATION

Input

log_level    : SCALAR  (optional, default 'normal')
warnings_fh  : (filehandle, optional)
validate     : SCALAR  (optional, default 0)

Output

Music::NWC2MusicXML object

MESSAGES

None.

convert

Convert a single .nwc file to MusicXML.

Purpose

Main single-file conversion entry point. Chains decoder -> parser -> generator, writes the output file, and updates the internal diagnostic counters.

Arguments

Named parameters:

Returns

Scalar string -- the output file path if conversion succeeded, or undef on failure.

Side Effects

Writes the output file. Updates diagnostic counters. Croaks on fatal errors; non-fatal issues are issued as warnings.

Usage Example

my $out = $c->convert(input => 'Pilgrim.nwc', overwrite => 1);

API SPECIFICATION

Input

input     : SCALAR (path, required)
output    : SCALAR (path, optional)
overwrite : boolean (optional, default false)

Output

SCALAR (output path) or undef

MESSAGES

| Code | Meaning | Resolution | |--------------------|--------------------------------------|-------------------------------| | error_no_input | input parameter missing | Provide input path | | error_file_not_found| Input file does not exist | Check path | | error_decode | NWC decoding stage failed | See error detail | | error_parse | NWCTXT parsing stage failed | See error detail | | error_generate | MusicXML generation failed | See error detail | | error_write | Cannot write output file | Check permissions / disk space|

batch_convert

Convert multiple .nwc files, optionally into a separate output directory.

Purpose

Processes a list of input files in sequence. Failures on individual files are caught and counted; conversion continues with remaining files. A summary is printed at the end.

Arguments

Named parameters:

Returns

Hashref: { processed => N, successful => N, warnings => N, failed => N }.

Side Effects

Writes output files. Prints a summary to STDERR. Does not croak on per-file failures.

Usage Example

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

API SPECIFICATION

Input

inputs     : ARRAYREF of SCALAR paths (required)
output_dir : SCALAR (optional)
overwrite  : SCALAR bool (optional, default 0)
recursive  : SCALAR bool (optional, default 0)
base_dir   : SCALAR (optional)

Output

HASHREF { processed:int, successful:int, warnings:int, failed:int }

diagnostics

Return the Music::NWC2MusicXML::Diagnostics instance.

DIAGNOSTICS

MESSAGES

| Code | Meaning | Resolution | |----------------------|-------------------------------------|-----------------------------------| | error_no_input | input parameter missing | Provide input path | | error_file_not_found | Input file absent | Check path and permissions | | error_decode | NWC decoding stage failed | See embedded error | | error_parse | NWCTXT parsing stage failed | See embedded error | | error_generate | MusicXML generation failed | See embedded error | | error_write | Cannot write output | Check disk space and permissions | | error_mkdir | Cannot create output directory | Check parent directory permissions|

LIMITATIONS

DEPENDENCIES

Object::Configure is used to allow callers to pre-configure converter defaults at the class level (e.g. Music::NWC2MusicXML->configure(log_level => 'verbose')). This means a consuming application can set defaults once and new will honour them without repeating the arguments on each call.

SEE ALSO

FORMAL SPECIFICATION

new

[ConverterInit]
  log_level   : LogLevel
  validate    : Boolean
  diagnostics : Diagnostics
  nwc_decoder : NWCDecoder
  parser      : Parser
  generator   : Generator

(placeholder -- populate with Z calculus as implementation matures)

convert

[Convert]
  input?  : FileName
  output? : FileName
  ----------
  result! : FileName | Undef

(placeholder)

batchconvert

[BatchConvert]
  inputs?     : seq FileName
  output_dir? : DirName
  ----------
  summary!    : BatchSummary

(placeholder)

AUTHOR

Nigel Horne <njh@nigelhorne.com>

LICENSE

Copyright 2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.