/ 
Music-NWC2MusicXML-0.001.0
/ Music::NWC2MusicXML::Staff

NAME

Music::NWC2MusicXML::Staff - Internal representation of a single NWC staff.

VERSION

0.001.0

SYNOPSIS

use Music::NWC2MusicXML::Staff;

my $staff = Music::NWC2MusicXML::Staff->new(
    name       => 'Violin I',
    group      => 'Standard',
    instrument => { name => 'String Ensemble 1', patch => 48 },
);

$staff->add_event($note_event);
my $events = $staff->events;

DESCRIPTION

Music::NWC2MusicXML::Staff holds all information about one NWC staff: its properties (name, visibility, number of lines), instrument data, and the ordered sequence of Music::NWC2MusicXML::Event objects that constitute its musical content.

The event list is in parse order. MusicXML generation iterates over it to produce <measure> elements.

name

Return the staff name string.

group

Return the group name string.

lines

Return the number of staff lines (usually 5).

visible

Return 1 if the staff is visible, 0 otherwise.

instrument

Return the instrument information hashref.

Keys: name (string), patch (MIDI patch number 0-127).

initial_clef

Return the initial clef string (e.g. Treble), or undef if none recorded.

set_initial_clef

Set the initial clef.

initial_key

Return the initial key hashref (signature, tonic, mode), or undef.

set_initial_key

Set the initial key.

initial_timesig

Return the initial time-signature hashref (beats, beat_type), or undef.

set_initial_timesig

Set the initial time signature.

add_event

Append a Music::NWC2MusicXML::Event to this staff's event list.

Purpose

Used by the parser to build the ordered event sequence as it processes NWCTXT records belonging to this staff.

Arguments

$event -- a blessed Music::NWC2MusicXML::Event object (required).

Returns

$self (for chaining).

Side Effects

Appends to _events array.

Usage Example

$staff->add_event(
    Music::NWC2MusicXML::Event->new(type => 'Note', ...)
);

API SPECIFICATION

Input

$event : Music::NWC2MusicXML::Event (required)

Output

$self (Music::NWC2MusicXML::Staff)

MESSAGES

| Code | Meaning | Resolution | |----------------|----------------------------------------|---------------------------------| | error_bad_event| Argument is not a Music::NWC2MusicXML::Event | Construct event before adding |

FORMAL SPECIFICATION

[AddEvent]
  DeltaStaff
  event? : Event
  ---------
  events' = events ^ <event?>

(placeholder)

events

Return an arrayref of all Music::NWC2MusicXML::Event objects in parse order.

Returns

Arrayref of Music::NWC2MusicXML::Event.

API SPECIFICATION

Input

(none)

Output

ARRAYREF of Music::NWC2MusicXML::Event

musical_events

Return an arrayref containing only the events where is_musical_event is true. Metadata records are excluded.

event_count

Return the total number of events (musical + metadata).

has_notes

Return true if any note, rest, chord, or bar event has been added to this staff. Used by the parser to distinguish staff-header records (before any sounding content) from mid-staff change records.

DIAGNOSTICS

MESSAGES

| Code | Meaning | Resolution | |-----------------|---------------------------|----------------------------------| | error_bad_event | Non-Event passed to add | Construct a proper Event first |

LIMITATIONS

  • Multi-voice detection (simultaneous events on different voices within one staff) is performed by the MusicXML generator, not by this class.

  • The event list is unstructured; measure boundaries are deduced from Bar events during generation.

AUTHOR

Nigel Horne <nigel.horne@gmail.com>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.