.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MIDI::Score 3"
.TH MIDI::Score 3 "2002-11-16" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
MIDI::Score \- MIDI scores
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  # it's a long story; see below
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides functions to do with with \s-1MIDI\s0 scores.
It is used as the basis for all the functions in MIDI::Simple.
(Incidentally, MIDI::Opus's \fIdraw()\fR method also uses some of the
functions in here.)
.PP
Whereas the events in a \s-1MIDI\s0 event structure are items whose timing
is expressed in delta\-times, the timing of items in a score is
expressed as an absolute number of ticks from the track's start time.
Moreover, pairs of 'note_on' and 'note_off' events in an event structure
are abstracted into a single 'note' item in a score structure.
.PP
\&'note' takes the following form:
.PP
.Vb 1
\& ('note_on', I<start_time>, I<duration>, I<channel>, I<note>, I<velocity>)
.Ve
.PP
The problem that score structures are meant to solve is that 1)
people definitely don't think in delta-times \*(-- they think in absolute
times or in structures based on that (like 'time from start of measure');
2) people think in notes, not note_on and note_off events.
.PP
So, given this event structure:
.PP
.Vb 36
\& ['text_event', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],
\& ['text_event', 0, 'Lord through this hour/ be Thou our guide'],
\& ['text_event', 0, 'so, by Thy power/ no foot shall slide'],
\& ['patch_change', 0, 1, 8],
\& ['note_on', 0, 1, 25, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 29, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 27, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 20, 96],
\& ['note_off', 192, 0, 1, 0],
\& ['note_on', 0, 1, 25, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 27, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 29, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 25, 96],
\& ['note_off', 192, 0, 1, 0],
\& ['note_on', 0, 1, 29, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 25, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 27, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 20, 96],
\& ['note_off', 192, 0, 1, 0],
\& ['note_on', 0, 1, 20, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 27, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 29, 96],
\& ['note_off', 96, 0, 1, 0],
\& ['note_on', 0, 1, 25, 96],
\& ['note_off', 192, 0, 1, 0],
.Ve
.PP
here is the corresponding score sctructure:
.PP
.Vb 20
\& ['text_event', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'],
\& ['text_event', 0, 'Lord through this hour/ be Thou our guide'],
\& ['text_event', 0, 'so, by Thy power/ no foot shall slide'],
\& ['patch_change', 0, 1, 8],
\& ['note', 0, 96, 1, 25, 96],
\& ['note', 96, 96, 1, 29, 96],
\& ['note', 192, 96, 1, 27, 96],
\& ['note', 288, 192, 1, 20, 96],
\& ['note', 480, 96, 1, 25, 96],
\& ['note', 576, 96, 1, 27, 96],
\& ['note', 672, 96, 1, 29, 96],
\& ['note', 768, 192, 1, 25, 96],
\& ['note', 960, 96, 1, 29, 96],
\& ['note', 1056, 96, 1, 25, 96],
\& ['note', 1152, 96, 1, 27, 96],
\& ['note', 1248, 192, 1, 20, 96],
\& ['note', 1440, 96, 1, 20, 96],
\& ['note', 1536, 96, 1, 27, 96],
\& ['note', 1632, 96, 1, 29, 96],
\& ['note', 1728, 192, 1, 25, 96]
.Ve
.PP
Note also that scores aren't crucially ordered.  So this:
.PP
.Vb 3
\& ['note', 768, 192, 1, 25, 96],
\& ['note', 960, 96, 1, 29, 96],
\& ['note', 1056, 96, 1, 25, 96],
.Ve
.PP
means the same thing as:
.PP
.Vb 3
\& ['note', 960, 96, 1, 29, 96],
\& ['note', 768, 192, 1, 25, 96],
\& ['note', 1056, 96, 1, 25, 96],
.Ve
.PP
The only exception to this is in the case of things like:
.PP
.Vb 2
\& ['patch_change', 200,     2, 15],
\& ['note',         200, 96, 2, 25, 96],
.Ve
.PP
where two (or more) score items happen \fIat the same time\fR and where one
affects the meaning of the other.
.SH "WHAT CAN BE IN A SCORE"
.IX Header "WHAT CAN BE IN A SCORE"
Besides the new score structure item \f(CW\*(C`note\*(C'\fR (covered above),
the possible contents of a score structure can be summarized thus:
Whatever can appear in an event structure can appear in a score
structure, save that its second parameter denotes not a
delta-time in ticks, but instead denotes the absolute number of ticks
from the start of the track.
.PP
To avoid the long periphrase \*(L"items in a score structure\*(R", I will
occasionally refer to items in a score structure as \*(L"notes\*(R", whether or
not they are actually \f(CW\*(C`note\*(C'\fR commands.  This leaves \*(L"event\*(R" to
unambiguously denote items in an event structure.
.PP
These, below, are all the items that can appear in a score.
This is basically just a repetition of the table in
MIDI::Event, with starttime substituting for dtime \*(--
so refer to MIDI::Event for an explanation of what the data types
(like \*(L"velocity\*(R" or \*(L"pitch_wheel\*(R").
As far as order, the first items are generally the most important:
.IP "('note', \fIstarttime\fR, \fIduration\fR, \fIchannel\fR, \fInote\fR, \fIvelocity\fR)" 4
.IX Item "('note', starttime, duration, channel, note, velocity)"
.PD 0
.IP "('key_after_touch', \fIstarttime\fR, \fIchannel\fR, \fInote\fR, \fIvelocity\fR)" 4
.IX Item "('key_after_touch', starttime, channel, note, velocity)"
.IP "('control_change', \fIstarttime\fR, \fIchannel\fR, \fIcontroller(0\-127)\fR, \fIvalue(0\-127)\fR)" 4
.IX Item "('control_change', starttime, channel, controller(0-127), value(0-127))"
.IP "('patch_change', \fIstarttime\fR, \fIchannel\fR, \fIpatch\fR)" 4
.IX Item "('patch_change', starttime, channel, patch)"
.IP "('channel_after_touch', \fIstarttime\fR, \fIchannel\fR, \fIvelocity\fR)" 4
.IX Item "('channel_after_touch', starttime, channel, velocity)"
.IP "('pitch_wheel_change', \fIstarttime\fR, \fIchannel\fR, \fIpitch_wheel\fR)" 4
.IX Item "('pitch_wheel_change', starttime, channel, pitch_wheel)"
.IP "('set_sequence_number', \fIstarttime\fR, \fIsequence\fR)" 4
.IX Item "('set_sequence_number', starttime, sequence)"
.IP "('text_event', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event', starttime, text)"
.IP "('copyright_text_event', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('copyright_text_event', starttime, text)"
.IP "('track_name', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('track_name', starttime, text)"
.IP "('instrument_name', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('instrument_name', starttime, text)"
.IP "('lyric', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('lyric', starttime, text)"
.IP "('marker', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('marker', starttime, text)"
.IP "('cue_point', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('cue_point', starttime, text)"
.IP "('text_event_08', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event_08', starttime, text)"
.IP "('text_event_09', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event_09', starttime, text)"
.IP "('text_event_0a', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event_0a', starttime, text)"
.IP "('text_event_0b', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event_0b', starttime, text)"
.IP "('text_event_0c', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event_0c', starttime, text)"
.IP "('text_event_0d', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event_0d', starttime, text)"
.IP "('text_event_0e', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event_0e', starttime, text)"
.IP "('text_event_0f', \fIstarttime\fR, \fItext\fR)" 4
.IX Item "('text_event_0f', starttime, text)"
.IP "('end_track', \fIstarttime\fR)" 4
.IX Item "('end_track', starttime)"
.IP "('set_tempo', \fIstarttime\fR, \fItempo\fR)" 4
.IX Item "('set_tempo', starttime, tempo)"
.IP "('smpte_offset', \fIstarttime\fR, \fIhr\fR, \fImn\fR, \fIse\fR, \fIfr\fR, \fIff\fR)" 4
.IX Item "('smpte_offset', starttime, hr, mn, se, fr, ff)"
.IP "('time_signature', \fIstarttime\fR, \fInn\fR, \fIdd\fR, \fIcc\fR, \fIbb\fR)" 4
.IX Item "('time_signature', starttime, nn, dd, cc, bb)"
.IP "('key_signature', \fIstarttime\fR, \fIsf\fR, \fImi\fR)" 4
.IX Item "('key_signature', starttime, sf, mi)"
.IP "('sequencer_specific', \fIstarttime\fR, \fIraw\fR)" 4
.IX Item "('sequencer_specific', starttime, raw)"
.IP "('raw_meta_event', \fIstarttime\fR, \fIcommand\fR(0\-255), \fIraw\fR)" 4
.IX Item "('raw_meta_event', starttime, command(0-255), raw)"
.IP "('sysex_f0', \fIstarttime\fR, \fIraw\fR)" 4
.IX Item "('sysex_f0', starttime, raw)"
.IP "('sysex_f7', \fIstarttime\fR, \fIraw\fR)" 4
.IX Item "('sysex_f7', starttime, raw)"
.IP "('song_position', \fIstarttime\fR)" 4
.IX Item "('song_position', starttime)"
.IP "('song_select', \fIstarttime\fR, \fIsong_number\fR)" 4
.IX Item "('song_select', starttime, song_number)"
.IP "('tune_request', \fIstarttime\fR)" 4
.IX Item "('tune_request', starttime)"
.IP "('raw_data', \fIstarttime\fR, \fIraw\fR)" 4
.IX Item "('raw_data', starttime, raw)"
.PD
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
This module provides these functions:
.IP "$score2_r = MIDI::Score::copy_structure($score_r)" 4
.IX Item "$score2_r = MIDI::Score::copy_structure($score_r)"
This takes a \fIreference\fR to a score structure, and returns a
\&\fIreference\fR to a copy of it. Example usage:
.Sp
.Vb 1
\&          @new_score = @{ MIDI::Score::copy_structure( \e@old_score ) };
.Ve
.ie n .IP "$events_r = MIDI::Score::score_r_to_events_r( $score_r )" 4
.el .IP "$events_r = MIDI::Score::score_r_to_events_r( \f(CW$score_r\fR )" 4
.IX Item "$events_r = MIDI::Score::score_r_to_events_r( $score_r )"
.PD 0
.ie n .IP "($events_r, $ticks\fR) = MIDI::Score::score_r_to_events_r( \f(CW$score_r )" 4
.el .IP "($events_r, \f(CW$ticks\fR) = MIDI::Score::score_r_to_events_r( \f(CW$score_r\fR )" 4
.IX Item "($events_r, $ticks) = MIDI::Score::score_r_to_events_r( $score_r )"
.PD
This takes a \fIreference\fR to a score structure, and converts it to an
event structure, which it returns a \fIreference\fR to.  In list context,
also returns a second value, a count of the number of ticks that
structure takes to play (i.e., the end-time of the temporally last
item).
.ie n .IP "$score2_r = MIDI::Score::sort_score_r( $score_r)" 4
.el .IP "$score2_r = MIDI::Score::sort_score_r( \f(CW$score_r\fR)" 4
.IX Item "$score2_r = MIDI::Score::sort_score_r( $score_r)"
This takes a \fIreference\fR to a score structure, and returns a
\&\fIreference\fR to a sorted (by time) copy of it. Example usage:
.Sp
.Vb 1
\&          @sorted_score = @{ MIDI::Score::sort_score_r( \e@old_score ) };
.Ve
.ie n .IP "$score_r = MIDI::Score::events_r_to_score_r( $events_r )" 4
.el .IP "$score_r = MIDI::Score::events_r_to_score_r( \f(CW$events_r\fR )" 4
.IX Item "$score_r = MIDI::Score::events_r_to_score_r( $events_r )"
.PD 0
.ie n .IP "($score_r, $ticks\fR) = MIDI::Score::events_r_to_score_r( \f(CW$events_r )" 4
.el .IP "($score_r, \f(CW$ticks\fR) = MIDI::Score::events_r_to_score_r( \f(CW$events_r\fR )" 4
.IX Item "($score_r, $ticks) = MIDI::Score::events_r_to_score_r( $events_r )"
.PD
This takes a \fIreference\fR to an event structure, converts it to a
score structure, which it returns a \fIreference\fR to.  If called in
list context, also returns a count of the number of ticks that
structure takes to play (i.e., the end-time of the temporally last
item).
.ie n .IP "$ticks = MIDI::Score::score_r_time( $score_r )" 4
.el .IP "$ticks = MIDI::Score::score_r_time( \f(CW$score_r\fR )" 4
.IX Item "$ticks = MIDI::Score::score_r_time( $score_r )"
This takes a \fIreference\fR to a score structure, and returns 
a count of the number of ticks that structure takes to play
(i.e., the end-time of the temporally last item).
.ie n .IP "MIDI::Score::dump_score( $score_r )" 4
.el .IP "MIDI::Score::dump_score( \f(CW$score_r\fR )" 4
.IX Item "MIDI::Score::dump_score( $score_r )"
This dumps (via \f(CW\*(C`print\*(C'\fR) a text representation of the contents of
the event structure you pass a reference to.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1998\-2002 Sean M. Burke. All rights reserved.
.PP
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR