.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MIDI::Score 3pm"
.TH MIDI::Score 3pm "2023-10-28" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MIDI::Score \- MIDI scores
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  # it\*(Aqs a long story; see below
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides functions to do with \s-1MIDI\s0 scores.
It is used as the basis for all the functions in MIDI::Simple.
(Incidentally, MIDI::Opus's \fBdraw()\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
\& (\*(Aqnote_on\*(Aq, start_time, duration, channel, note, 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 10
\& [\*(Aqtext_event\*(Aq, 0, \*(Aqwww.ely.anglican.org/parishes/camgsm/chimes.html\*(Aq],
\& [\*(Aqtext_event\*(Aq, 0, \*(AqLord through this hour/ be Thou our guide\*(Aq],
\& [\*(Aqtext_event\*(Aq, 0, \*(Aqso, by Thy power/ no foot shall slide\*(Aq],
\& [\*(Aqpatch_change\*(Aq, 0, 1, 8],
\& [\*(Aqnote_on\*(Aq, 0, 1, 25, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 29, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 27, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 20, 96],
\& [\*(Aqnote_off\*(Aq, 192, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 25, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 27, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 29, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 25, 96],
\& [\*(Aqnote_off\*(Aq, 192, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 29, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 25, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 27, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 20, 96],
\& [\*(Aqnote_off\*(Aq, 192, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 20, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 27, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 29, 96],
\& [\*(Aqnote_off\*(Aq, 96, 0, 1, 0],
\& [\*(Aqnote_on\*(Aq, 0, 1, 25, 96],
\& [\*(Aqnote_off\*(Aq, 192, 0, 1, 0],
.Ve
.PP
here is the corresponding score structure:
.PP
.Vb 10
\& [\*(Aqtext_event\*(Aq, 0, \*(Aqwww.ely.anglican.org/parishes/camgsm/chimes.html\*(Aq],
\& [\*(Aqtext_event\*(Aq, 0, \*(AqLord through this hour/ be Thou our guide\*(Aq],
\& [\*(Aqtext_event\*(Aq, 0, \*(Aqso, by Thy power/ no foot shall slide\*(Aq],
\& [\*(Aqpatch_change\*(Aq, 0, 1, 8],
\& [\*(Aqnote\*(Aq, 0, 96, 1, 25, 96],
\& [\*(Aqnote\*(Aq, 96, 96, 1, 29, 96],
\& [\*(Aqnote\*(Aq, 192, 96, 1, 27, 96],
\& [\*(Aqnote\*(Aq, 288, 192, 1, 20, 96],
\& [\*(Aqnote\*(Aq, 480, 96, 1, 25, 96],
\& [\*(Aqnote\*(Aq, 576, 96, 1, 27, 96],
\& [\*(Aqnote\*(Aq, 672, 96, 1, 29, 96],
\& [\*(Aqnote\*(Aq, 768, 192, 1, 25, 96],
\& [\*(Aqnote\*(Aq, 960, 96, 1, 29, 96],
\& [\*(Aqnote\*(Aq, 1056, 96, 1, 25, 96],
\& [\*(Aqnote\*(Aq, 1152, 96, 1, 27, 96],
\& [\*(Aqnote\*(Aq, 1248, 192, 1, 20, 96],
\& [\*(Aqnote\*(Aq, 1440, 96, 1, 20, 96],
\& [\*(Aqnote\*(Aq, 1536, 96, 1, 27, 96],
\& [\*(Aqnote\*(Aq, 1632, 96, 1, 29, 96],
\& [\*(Aqnote\*(Aq, 1728, 192, 1, 25, 96]
.Ve
.PP
Note also that scores aren't crucially ordered.  So this:
.PP
.Vb 3
\& [\*(Aqnote\*(Aq, 768, 192, 1, 25, 96],
\& [\*(Aqnote\*(Aq, 960, 96, 1, 29, 96],
\& [\*(Aqnote\*(Aq, 1056, 96, 1, 25, 96],
.Ve
.PP
means the same thing as:
.PP
.Vb 3
\& [\*(Aqnote\*(Aq, 960, 96, 1, 29, 96],
\& [\*(Aqnote\*(Aq, 768, 192, 1, 25, 96],
\& [\*(Aqnote\*(Aq, 1056, 96, 1, 25, 96],
.Ve
.PP
The only exception to this is in the case of things like:
.PP
.Vb 2
\& [\*(Aqpatch_change\*(Aq, 200,     2, 15],
\& [\*(Aqnote\*(Aq,         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:
.ie n .IP "$score2_r = MIDI::Score::copy_structure($score_r)" 4
.el .IP "\f(CW$score2_r\fR = 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 "\f(CW$events_r\fR = 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) = MIDI::Score::score_r_to_events_r( $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 "\f(CW$score2_r\fR = 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 "\f(CW$score_r\fR = 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) = MIDI::Score::events_r_to_score_r( $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 "\f(CW$ticks\fR = 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.
.ie n .IP "MIDI::Score::quantize( $score_r )" 4
.el .IP "MIDI::Score::quantize( \f(CW$score_r\fR )" 4
.IX Item "MIDI::Score::quantize( $score_r )"
This takes a \fIreference\fR to a score structure, performs a grid
quantize on all events, returning a new score reference with new
quantized events.  Two parameters to the method are: 'grid': the
quantization grid, and 'durations': whether or not to also quantize
event durations (default off).
.Sp
When durations of note events are quantized, they can get 0 duration.
These events are \fInot dropped\fR from the returned score, and it is the
responsibility of the caller to deal with them.
.ie n .IP "MIDI::Score::skyline( $score_r )" 4
.el .IP "MIDI::Score::skyline( \f(CW$score_r\fR )" 4
.IX Item "MIDI::Score::skyline( $score_r )"
This takes a \fIreference\fR to a score structure, performs skyline
(create a monophonic track by extracting the event with highest pitch
at unique onset times) on the score, returning a new score reference.
The parameters to the method is: 'clip': whether durations of events
are preserved or possibly clipped and modified.
.Sp
To explain this, consider the following (from Bach 2 part invention
no.6 in E major):
.Sp
.Vb 2
\&     |\-\-\-\-\-\-e\-\-\-\-\-\-|\-\-\-\-\-\-\-ds\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-d\-\-\-\-\-\-|...
\&|****\-\-E\-\-\-\-\-|\-\-\-\-\-\-\-Fs\-\-\-\-\-\-\-|\-\-\-\-\-\-Gs\-\-\-\-\-|...
.Ve
.Sp
Without duration cliping, the skyline is E, Fs, Gs...
.Sp
With duration clipping, the skyline is E, e, ds, d..., where the
duration of E is clipped to just the * portion above
.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 "AUTHORS"
.IX Header "AUTHORS"
Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR (until 2010)
.PP
Darrell Conklin \f(CW\*(C`conklin@cpan.org\*(C'\fR (from 2010)