File Coverage

=head1 NAME

Music::NWC2MusicXML::MusicXML - Convert an internal Score object to a MusicXML 4.0 document string.

=head1 VERSION

0.002.4

=head1 SYNOPSIS

    # --- Pattern 1: full pipeline from a .nwc file ---
    use Music::NWC2MusicXML::NWC;
    use Music::NWC2MusicXML::Parser;
    use Music::NWC2MusicXML::MusicXML;

    my $nwctxt = Music::NWC2MusicXML::NWC->read('my_score.nwc');
    my $score  = Music::NWC2MusicXML::Parser->new->parse($nwctxt);
    my $xml    = Music::NWC2MusicXML::MusicXML->new->generate($score);

    # Write raw bytes -- the string is already pure ASCII (numeric entities
    # for any non-ASCII source characters).
    open my $fh, '>:raw', 'output.musicxml' or die $!;
    print $fh $xml;
    close $fh;

    # --- Pattern 2: custom indentation ---
    my $gen = Music::NWC2MusicXML::MusicXML->new(indent => "\t");
    my $xml = $gen->generate($score);

    # --- Pattern 3: validate the output with an external tool ---
    # (run in the shell after writing the file)
    # xmllint --noout output.musicxml

    # --- Pattern 4: generate and keep in memory for further processing ---
    my $xml_string = Music::NWC2MusicXML::MusicXML->new->generate($score);
    my @lines = split /\n/, $xml_string;
    my ($part_list) = grep { /part-list/ } @lines;

=head1 DESCRIPTION

C<Music::NWC2MusicXML::MusicXML> is the last stage of the NWC-to-MusicXML
pipeline.  It takes a C<Music::NWC2MusicXML::Score> object -- the internal
representation built by C<Music::NWC2MusicXML::Parser> -- and returns a
self-contained MusicXML 4.0 document as a plain string.

The generator knows nothing about the NWCTXT or NWC binary format.  Every
musical decision (pitches, durations, articulations, dynamics, tempo, key,
clef, copyright text) was already made by the parser.  The generator only
serialises the Score object tree into valid XML.

=head2 Divisions

MusicXML requires one integer, C<< <divisions> >>, that says how many ticks
equal one quarter note.  To represent every note duration exactly -- including
unusual tuplet values -- the generator scans all note durations across all
staves, collects the denominators of their rational representations, and
computes their least common multiple (LCM).  That LCM becomes
C<< <divisions> >>.  No duration is ever rounded or truncated.

=head2 Page layout and credits

The generator emits a C<< <defaults> >> block that records the actual page
size and margin values expressed in MusicXML tenths.  Without this block a
renderer cannot interpret the absolute coordinate values used by credit
elements, so title and copyright placement would be undefined.

Page dimensions default to A4 (210 x 297 mm) with 1.27 cm margins, which
match NWC's own defaults.  If the source NWC file contained a C<PgMargins>
record the parser stores the margin values in the Score's C<page_setup>
hashref and the generator reads them from there.

Each title, subtitle, and copyright line is emitted as its own separate
C<< <credit> >> element:

=over 4

=item * Title -- C<< <credit page="1"> >>; large font; centred near the top
of page 1.

=item * Subtitle (the NWC Author field) -- C<< <credit page="1"> >>; medium
font; centred directly below the title.

=item * Each copyright line -- C<< <credit> >> with B<no page attribute>;
this instructs conforming renderers to display the line on B<every> page.
One separate C<< <credit> >> element is used per line; putting multiple
C<< <credit-words> >> inside a single C<< <credit> >> causes many renderers
to display only the last one.

=back

=head2 Articulations

NWC encodes articulations as initial-capital tokens in the C<Dur:> field
(for example C<Tenuto>, C<Staccato>, C<Accent>).  The generator groups them
into the correct MusicXML wrapper:

=over 4

=item * C<< <articulations> >> -- tenuto, staccato, accent, strong-accent,
staccatissimo.

=item * C<< <ornaments> >> -- trill-mark, mordent, turn.

=item * Direct child of C<< <notations> >> -- fermata.

=back

The C<Slur> token is never emitted as an articulation; it is handled by the
slur-annotation pre-pass (see L</Slurs and ties> below).

=head2 Slurs and ties

A single pre-pass over all events in a staff (C<_annotate_events>) detects
slur arcs and tie pairs before the events are grouped into measures.  This
means arcs that cross a bar line are handled correctly.  Each event is
annotated with flags that the measure emitter reads when writing
C<< <slur> >> and C<< <tied> >> elements.

Tie detection uses the raw NWC position string as a key.  A C<^> suffix on a
position string (e.g. C<Pos:-7^>) means the note is tied forward; the
generator strips the suffix to match the tied-to note.

=head2 Dynamic variance (text markings)

NWC C<DynVariance> (also exported as C<DynamicVariance> by some NWC versions)
records represent written-out dynamic variance text — not hairpins.
C<Style:Crescendo> produces C<< <words font-style="italic">cresc.</words> >>;
C<Style:Diminuendo> produces C<< <words font-style="italic">dim.</words> >>;
C<Style:crescOff> (the end-of-phrase marker for an extended text cresc.) emits
nothing, since MusicXML text directions require no explicit stop element.

Do not confuse these with hairpin crescendo/diminuendo wedges: those come from
C<Opts:Crescendo> / C<Opts:Diminuendo> attached to individual note or rest
events (see L</Hairpins (wedges)> below).

=head2 Hairpins (wedges)

NWC does not use standalone records for in-staff hairpins.  Instead it
attaches C<Opts:Crescendo> or C<Opts:Diminuendo> to every note and rest that
sits under the arc.  A second pre-pass (C<_annotate_wedges>) detects the
start and end of each arc by watching for transitions: the first event
carrying a hairpin flag starts the arc; the first event that drops the flag
closes it.  The wedge stop is emitted as a C<crescOff> direction immediately
after the last note of the arc.

=head2 Tempo marks

A C<Tempo> event carries three data keys: C<bpm> (integer BPM), C<base> (NWC
beat-unit string such as C<'Quarter'> or C<'Dotted Half'>), and C<text>
(optional free-text string from the NWC C<Text:> field, e.g.
C<'With Expression'>; empty string when absent).

When C<text> is non-empty, C<_emit_tempo> emits it as a
C<< <words font-style="italic"> >> C<< <direction-type> >> block before the
C<< <metronome> >> block, both within the same C<< <direction> >> element.
The metronome element uses C<parentheses="yes"> in this case so renderers
display the marking as e.g. I<With Expression (crotchet = 92)>.  When C<text>
is empty only the metronome block is emitted and C<parentheses="no"> is used.

=head2 Tempo variance

Markings such as C<Accelerando>, C<Ritardando>, C<Ritenuto>, C<Rallentando>,
and C<RitardandoToTempo> (rendered as "a tempo") are stored as
C<TempoVariance> events by the parser.  The generator converts them to italic
C<< <words> >> direction elements using the C<%TEMPO_VARIANCE_TEXT> table.
Both C<Ritardando> and C<Ritenuto> abbreviate to "rit.".

The C<Style:Fermata> value is a special case: it is not a tempo-change
direction but a symbol placed over the note or rest that immediately follows
the C<TempoVariance> record.  C<_annotate_fermatas> detects these records in
a pre-pass and marks the following sounding event so that C<_emit_note_event>
and C<_emit_rest_event> emit C<< <notations><fermata/></notations> >> on it.
The C<TempoVariance:Fermata> event itself is then skipped during measure
emission and never produces a C<< <direction> >> element.

=head2 Part name resolution

Display names for each staff are resolved in three steps:

=over 4

=item 1. Use the NWC staff name, if it is not a generic default such as
C<Staff> or C<Staff-2>.

=item 2. Fall back to the MIDI instrument name.

=item 3. Fall back to the positional name C<Staff-N> (1-based).

=back

After all candidates are found, any name that appears on more than one staff
is replaced with C<Staff-N> to guarantee unique C<< <part-name> >> values.

=head1 COMMON PITFALLS

=over 4

=item B<Opening the output file in text mode>

The output string is pure ASCII (all non-ASCII characters are escaped as
numeric XML entities).  Opening the output file with C<< '>:encoding(UTF-8)' >>
is harmless but unnecessary; opening it with C<< '>:encoding(Latin-1)' >> or
a similar 8-bit encoding and then printing a string that contains non-ASCII
bytes would corrupt the file.  The safest choice is C<< '>:raw' >>.

=item B<Multiple copyright lines in one credit element>

If you call C<_emit_credits> and place two C<< <credit-words> >> children
inside a single C<< <credit> >> element, most renderers (including MuseScore
and Finale) display only the B<last> C<< <credit-words> >> and silently
discard the rest.  This module uses one C<< <credit> >> per copyright line to
avoid this.

=item B<Missing defaults section>

The absolute coordinates in C<< <credit> >> elements (C<default-x>,
C<default-y>) are measured in MusicXML "tenths" from the bottom-left corner
of the page.  They are meaningless to a renderer unless a C<< <defaults> >>
block defines the page size and the tenths-per-mm scaling factor.  This module
always emits C<< <defaults> >> before any C<< <credit> >> elements.

=item B<Two separate rights elements in identification>

C<< <identification> >> accepts only one C<< <rights> >> child in practice;
a second one shadows the first.  This module joins multiple copyright lines
with a newline character inside a single C<< <rights> >> element.

=item B<Slur token treated as an articulation>

NWC encodes slurs as C<Slur> in the same token list as articulations.  Do not
add C<Slur> to C<%ARTICULATION_MAP>; the slur-annotation pre-pass handles it.
If C<Slur> were also emitted as an articulation element the output XML would be
invalid.

=item B<Score with no staves>

Calling C<generate> on a C<Score> object that has no staves will C<croak>
immediately.  Always check that the parser produced at least one staff before
calling the generator.

=back

=head1 ENCODING

=over 4

=item B<Input (Score metadata fields)>

Metadata strings (Title, Author, Copyright1, Copyright2, etc.) may contain any
Unicode characters, including non-ASCII letters, accented characters, and the
copyright symbol (U+00A9).  The NWC binary decoder may deliver these as Latin-1
bytes; once stored in Perl scalars they are handled correctly as long as they
pass through C<_xml_escape> before being written to the output.

=item B<Output (the generated XML string)>

The string returned by C<generate> is B<pure 7-bit ASCII>.  Every character
whose code point is above 127 is converted to a numeric XML character
reference (C<&#N;>), for example C<&#169;> for the copyright symbol.  The XML
declaration at the top of the document reads C<encoding="UTF-8">, which
remains correct because numeric character references are valid in any XML
encoding.

=item B<Emojis and full Unicode>

Emoji and supplementary-plane characters (code points above U+FFFF) are not
tested but will be escaped correctly by C<_xml_escape> as long as Perl has
decoded them to proper Unicode code points (i.e. C<utf8::decode> has been
applied or the string was read with a C<:utf8> layer).  Raw multi-byte UTF-8
bytes that have B<not> been decoded will be escaped byte-by-byte and will
produce incorrect numeric references.

=back

=cut

=head2 new

Create a new generator object.

=head3 Purpose

Factory constructor.  Creates a configured generator ready to call C<generate>
one or more times.  The same generator instance can be used to process
multiple Score objects; each C<generate> call is independent.

=head3 Arguments

All arguments are named (passed as a flat key/value list) and optional.

=over 4

=item C<indent>

The string used for one level of XML indentation.  Defaults to two spaces.
Pass C<"\t"> for tab indentation.  Only affects whitespace; the XML content
is identical regardless of the indent setting.

=item C<diagnostics>

A C<Music::NWC2MusicXML::Diagnostics> instance for routing warning messages.
When omitted, warnings are sent directly to C<carp>.

=back

=head3 Returns

A blessed C<Music::NWC2MusicXML::MusicXML> object.

=head3 Side Effects

None.

=head3 Usage Example

    # Default (two-space indent)
    my $gen = Music::NWC2MusicXML::MusicXML->new;

    # Tab indent
    my $gen = Music::NWC2MusicXML::MusicXML->new(indent => "\t");

=head3 API SPECIFICATION

=head4 Input

    indent      : SCALAR   (optional, default '  ')
    diagnostics : OBJECT   Music::NWC2MusicXML::Diagnostics  (optional)

=head4 Output

    Music::NWC2MusicXML::MusicXML object

=head3 MESSAGES

This method does not emit any diagnostic messages.

=cut

=head2 generate

Convert a C<Music::NWC2MusicXML::Score> object to a MusicXML 4.0 document and
return the complete document as a string.

=head3 Purpose

Top-level entry point.  Orchestrates, in order:

=over 4

=item 1. XML declaration and DOCTYPE header.

=item 2. Page layout geometry (C<< <defaults> >>).

=item 3. Work title (C<< <work> >>).

=item 4. Identification metadata: composer, lyricist, rights (C<< <identification> >>).

=item 5. Visual credits: title, subtitle, and copyright lines (C<< <credit> >> elements).

=item 6. Part list: one C<< <score-part> >> per staff (C<< <part-list> >>).

=item 7. Musical content: one C<< <part> >> per staff, each containing numbered
measures with notes, rests, dynamics, tempo, articulations, slurs, ties,
and wedge hairpins.

=back

Each staff is processed by a two-stage pipeline:

=over 4

=item Stage 1 -- annotation pre-passes.

C<_annotate_events> detects slur arcs and tie pairs across the entire staff
before measure grouping.  C<_annotate_wedges> detects hairpin (crescendo /
diminuendo) arcs stored as per-note C<Opts:> flags.  C<_annotate_fermatas>
associates C<TempoVariance:Fermata> records with the sounding event that
follows each one.  All three passes store their results in a shared C<%ann>
hash keyed by stringified event reference.

=item Stage 2 -- measure emission.

Events are gathered into measure-sized groups separated by C<Bar> events.
For each measure, C<_emit_measure> serialises notes, rests, directions, and
mid-staff attribute changes, consulting C<%ann> for slur, tie, and wedge
annotations.

=back

=head3 Arguments

=over 4

=item C<$score>

A C<Music::NWC2MusicXML::Score> object (required).  Must contain at least one
staff; otherwise the method croaks.

=back

=head3 Returns

A scalar string holding the complete MusicXML 4.0 document.  The string is
pure 7-bit ASCII: all non-ASCII source characters are replaced with numeric
XML character references (C<&#N;>).  The XML declaration at the top of the
string declares C<encoding="UTF-8">, which is correct.

The string ends with a single newline character.

=head3 Side Effects

May issue warnings via C<carp> for unsupported or unrecognised values
(unknown clef, unknown dynamic marking, unsupported articulation token,
approximate barline style).

=head3 Usage Example

    my $xml = $gen->generate($score);

    # Write to a file -- ':raw' is sufficient; the string is pure ASCII.
    open my $fh, '>:raw', 'out.musicxml' or die $!;
    print $fh $xml;
    close $fh;

=head3 API SPECIFICATION

=head4 Input

    $score : Music::NWC2MusicXML::Score  (required, must have staff_count > 0)

=head4 Output

    SCALAR  -- complete MusicXML 4.0 document, pure 7-bit ASCII, newline-terminated

=head3 MESSAGES

| Code                | Meaning                                  | Resolution                      |
|---------------------|------------------------------------------|---------------------------------|
| error_bad_score     | Argument is not a Score object           | Pass the object returned by Parser |
| error_no_staves     | Score has zero staves                    | Confirm the parser found AddStaff records |
| warn_unknown_clef   | NWC clef name not in CLEF_MAP            | Treble used as fallback         |
| warn_unknown_dynamic| Dynamic marking not in DYNAMIC_MAP       | Direction element omitted       |
| warn_unsupported_art| Articulation token not in ARTICULATION_MAP| Mark omitted; warning issued   |
| warn_approx_bar     | Barline style has no direct MusicXML map | Regular barline used            |

=cut