CVS リポジトリの参照
Contents of /perldocjp/docs/modules/MIDI-Perl-0.8/MIDI/Score.pod
Parent Directory
| Revision Log
| Revision Graph
Revision 1.1 -
( show annotations)
( download)
Tue May 13 15:22:22 2003 UTC
(21 years ago)
by makamaka
Branch: MAIN
original version
1 |
=head1 NAME |
2 |
|
3 |
MIDI::Score - MIDI scores |
4 |
|
5 |
=head1 SYNOPSIS |
6 |
|
7 |
# it's a long story; see below |
8 |
|
9 |
=head1 DESCRIPTION |
10 |
|
11 |
This module provides functions to do with with MIDI scores. |
12 |
It is used as the basis for all the functions in MIDI::Simple. |
13 |
(Incidentally, MIDI::Opus's draw() method also uses some of the |
14 |
functions in here.) |
15 |
|
16 |
Whereas the events in a MIDI event structure are items whose timing |
17 |
is expressed in delta-times, the timing of items in a score is |
18 |
expressed as an absolute number of ticks from the track's start time. |
19 |
Moreover, pairs of 'note_on' and 'note_off' events in an event structure |
20 |
are abstracted into a single 'note' item in a score structure. |
21 |
|
22 |
'note' takes the following form: |
23 |
|
24 |
('note_on', I<start_time>, I<duration>, I<channel>, I<note>, I<velocity>) |
25 |
|
26 |
The problem that score structures are meant to solve is that 1) |
27 |
people definitely don't think in delta-times -- they think in absolute |
28 |
times or in structures based on that (like 'time from start of measure'); |
29 |
2) people think in notes, not note_on and note_off events. |
30 |
|
31 |
So, given this event structure: |
32 |
|
33 |
['text_event', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'], |
34 |
['text_event', 0, 'Lord through this hour/ be Thou our guide'], |
35 |
['text_event', 0, 'so, by Thy power/ no foot shall slide'], |
36 |
['patch_change', 0, 1, 8], |
37 |
['note_on', 0, 1, 25, 96], |
38 |
['note_off', 96, 0, 1, 0], |
39 |
['note_on', 0, 1, 29, 96], |
40 |
['note_off', 96, 0, 1, 0], |
41 |
['note_on', 0, 1, 27, 96], |
42 |
['note_off', 96, 0, 1, 0], |
43 |
['note_on', 0, 1, 20, 96], |
44 |
['note_off', 192, 0, 1, 0], |
45 |
['note_on', 0, 1, 25, 96], |
46 |
['note_off', 96, 0, 1, 0], |
47 |
['note_on', 0, 1, 27, 96], |
48 |
['note_off', 96, 0, 1, 0], |
49 |
['note_on', 0, 1, 29, 96], |
50 |
['note_off', 96, 0, 1, 0], |
51 |
['note_on', 0, 1, 25, 96], |
52 |
['note_off', 192, 0, 1, 0], |
53 |
['note_on', 0, 1, 29, 96], |
54 |
['note_off', 96, 0, 1, 0], |
55 |
['note_on', 0, 1, 25, 96], |
56 |
['note_off', 96, 0, 1, 0], |
57 |
['note_on', 0, 1, 27, 96], |
58 |
['note_off', 96, 0, 1, 0], |
59 |
['note_on', 0, 1, 20, 96], |
60 |
['note_off', 192, 0, 1, 0], |
61 |
['note_on', 0, 1, 20, 96], |
62 |
['note_off', 96, 0, 1, 0], |
63 |
['note_on', 0, 1, 27, 96], |
64 |
['note_off', 96, 0, 1, 0], |
65 |
['note_on', 0, 1, 29, 96], |
66 |
['note_off', 96, 0, 1, 0], |
67 |
['note_on', 0, 1, 25, 96], |
68 |
['note_off', 192, 0, 1, 0], |
69 |
|
70 |
here is the corresponding score sctructure: |
71 |
|
72 |
['text_event', 0, 'www.ely.anglican.org/parishes/camgsm/chimes.html'], |
73 |
['text_event', 0, 'Lord through this hour/ be Thou our guide'], |
74 |
['text_event', 0, 'so, by Thy power/ no foot shall slide'], |
75 |
['patch_change', 0, 1, 8], |
76 |
['note', 0, 96, 1, 25, 96], |
77 |
['note', 96, 96, 1, 29, 96], |
78 |
['note', 192, 96, 1, 27, 96], |
79 |
['note', 288, 192, 1, 20, 96], |
80 |
['note', 480, 96, 1, 25, 96], |
81 |
['note', 576, 96, 1, 27, 96], |
82 |
['note', 672, 96, 1, 29, 96], |
83 |
['note', 768, 192, 1, 25, 96], |
84 |
['note', 960, 96, 1, 29, 96], |
85 |
['note', 1056, 96, 1, 25, 96], |
86 |
['note', 1152, 96, 1, 27, 96], |
87 |
['note', 1248, 192, 1, 20, 96], |
88 |
['note', 1440, 96, 1, 20, 96], |
89 |
['note', 1536, 96, 1, 27, 96], |
90 |
['note', 1632, 96, 1, 29, 96], |
91 |
['note', 1728, 192, 1, 25, 96] |
92 |
|
93 |
Note also that scores aren't crucially ordered. So this: |
94 |
|
95 |
['note', 768, 192, 1, 25, 96], |
96 |
['note', 960, 96, 1, 29, 96], |
97 |
['note', 1056, 96, 1, 25, 96], |
98 |
|
99 |
means the same thing as: |
100 |
|
101 |
['note', 960, 96, 1, 29, 96], |
102 |
['note', 768, 192, 1, 25, 96], |
103 |
['note', 1056, 96, 1, 25, 96], |
104 |
|
105 |
The only exception to this is in the case of things like: |
106 |
|
107 |
['patch_change', 200, 2, 15], |
108 |
['note', 200, 96, 2, 25, 96], |
109 |
|
110 |
where two (or more) score items happen I<at the same time> and where one |
111 |
affects the meaning of the other. |
112 |
|
113 |
=head1 WHAT CAN BE IN A SCORE |
114 |
|
115 |
Besides the new score structure item C<note> (covered above), |
116 |
the possible contents of a score structure can be summarized thus: |
117 |
Whatever can appear in an event structure can appear in a score |
118 |
structure, save that its second parameter denotes not a |
119 |
delta-time in ticks, but instead denotes the absolute number of ticks |
120 |
from the start of the track. |
121 |
|
122 |
To avoid the long periphrase "items in a score structure", I will |
123 |
occasionally refer to items in a score structure as "notes", whether or |
124 |
not they are actually C<note> commands. This leaves "event" to |
125 |
unambiguously denote items in an event structure. |
126 |
|
127 |
These, below, are all the items that can appear in a score. |
128 |
This is basically just a repetition of the table in |
129 |
L<MIDI::Event>, with starttime substituting for dtime -- |
130 |
so refer to L<MIDI::Event> for an explanation of what the data types |
131 |
(like "velocity" or "pitch_wheel"). |
132 |
As far as order, the first items are generally the most important: |
133 |
|
134 |
=over |
135 |
|
136 |
=item ('note', I<starttime>, I<duration>, I<channel>, I<note>, I<velocity>) |
137 |
|
138 |
=item ('key_after_touch', I<starttime>, I<channel>, I<note>, I<velocity>) |
139 |
|
140 |
=item ('control_change', I<starttime>, I<channel>, I<controller(0-127)>, I<value(0-127)>) |
141 |
|
142 |
=item ('patch_change', I<starttime>, I<channel>, I<patch>) |
143 |
|
144 |
=item ('channel_after_touch', I<starttime>, I<channel>, I<velocity>) |
145 |
|
146 |
=item ('pitch_wheel_change', I<starttime>, I<channel>, I<pitch_wheel>) |
147 |
|
148 |
=item ('set_sequence_number', I<starttime>, I<sequence>) |
149 |
|
150 |
=item ('text_event', I<starttime>, I<text>) |
151 |
|
152 |
=item ('copyright_text_event', I<starttime>, I<text>) |
153 |
|
154 |
=item ('track_name', I<starttime>, I<text>) |
155 |
|
156 |
=item ('instrument_name', I<starttime>, I<text>) |
157 |
|
158 |
=item ('lyric', I<starttime>, I<text>) |
159 |
|
160 |
=item ('marker', I<starttime>, I<text>) |
161 |
|
162 |
=item ('cue_point', I<starttime>, I<text>) |
163 |
|
164 |
=item ('text_event_08', I<starttime>, I<text>) |
165 |
|
166 |
=item ('text_event_09', I<starttime>, I<text>) |
167 |
|
168 |
=item ('text_event_0a', I<starttime>, I<text>) |
169 |
|
170 |
=item ('text_event_0b', I<starttime>, I<text>) |
171 |
|
172 |
=item ('text_event_0c', I<starttime>, I<text>) |
173 |
|
174 |
=item ('text_event_0d', I<starttime>, I<text>) |
175 |
|
176 |
=item ('text_event_0e', I<starttime>, I<text>) |
177 |
|
178 |
=item ('text_event_0f', I<starttime>, I<text>) |
179 |
|
180 |
=item ('end_track', I<starttime>) |
181 |
|
182 |
=item ('set_tempo', I<starttime>, I<tempo>) |
183 |
|
184 |
=item ('smpte_offset', I<starttime>, I<hr>, I<mn>, I<se>, I<fr>, I<ff>) |
185 |
|
186 |
=item ('time_signature', I<starttime>, I<nn>, I<dd>, I<cc>, I<bb>) |
187 |
|
188 |
=item ('key_signature', I<starttime>, I<sf>, I<mi>) |
189 |
|
190 |
=item ('sequencer_specific', I<starttime>, I<raw>) |
191 |
|
192 |
=item ('raw_meta_event', I<starttime>, I<command>(0-255), I<raw>) |
193 |
|
194 |
=item ('sysex_f0', I<starttime>, I<raw>) |
195 |
|
196 |
=item ('sysex_f7', I<starttime>, I<raw>) |
197 |
|
198 |
=item ('song_position', I<starttime>) |
199 |
|
200 |
=item ('song_select', I<starttime>, I<song_number>) |
201 |
|
202 |
=item ('tune_request', I<starttime>) |
203 |
|
204 |
=item ('raw_data', I<starttime>, I<raw>) |
205 |
|
206 |
=back |
207 |
|
208 |
|
209 |
=head1 FUNCTIONS |
210 |
|
211 |
This module provides these functions: |
212 |
|
213 |
=over |
214 |
|
215 |
=item $score2_r = MIDI::Score::copy_structure($score_r) |
216 |
|
217 |
This takes a I<reference> to a score structure, and returns a |
218 |
I<reference> to a copy of it. Example usage: |
219 |
|
220 |
@new_score = @{ MIDI::Score::copy_structure( \@old_score ) }; |
221 |
|
222 |
=item $events_r = MIDI::Score::score_r_to_events_r( $score_r ) |
223 |
|
224 |
=item ($events_r, $ticks) = MIDI::Score::score_r_to_events_r( $score_r ) |
225 |
|
226 |
This takes a I<reference> to a score structure, and converts it to an |
227 |
event structure, which it returns a I<reference> to. In list context, |
228 |
also returns a second value, a count of the number of ticks that |
229 |
structure takes to play (i.e., the end-time of the temporally last |
230 |
item). |
231 |
|
232 |
=item $score2_r = MIDI::Score::sort_score_r( $score_r) |
233 |
|
234 |
This takes a I<reference> to a score structure, and returns a |
235 |
I<reference> to a sorted (by time) copy of it. Example usage: |
236 |
|
237 |
@sorted_score = @{ MIDI::Score::sort_score_r( \@old_score ) }; |
238 |
|
239 |
=item $score_r = MIDI::Score::events_r_to_score_r( $events_r ) |
240 |
|
241 |
=item ($score_r, $ticks) = MIDI::Score::events_r_to_score_r( $events_r ) |
242 |
|
243 |
This takes a I<reference> to an event structure, converts it to a |
244 |
score structure, which it returns a I<reference> to. If called in |
245 |
list context, also returns a count of the number of ticks that |
246 |
structure takes to play (i.e., the end-time of the temporally last |
247 |
item). |
248 |
|
249 |
=item $ticks = MIDI::Score::score_r_time( $score_r ) |
250 |
|
251 |
This takes a I<reference> to a score structure, and returns |
252 |
a count of the number of ticks that structure takes to play |
253 |
(i.e., the end-time of the temporally last item). |
254 |
|
255 |
=item MIDI::Score::dump_score( $score_r ) |
256 |
|
257 |
This dumps (via C<print>) a text representation of the contents of |
258 |
the event structure you pass a reference to. |
259 |
|
260 |
=back |
261 |
|
262 |
=head1 COPYRIGHT |
263 |
|
264 |
Copyright (c) 1998-2002 Sean M. Burke. All rights reserved. |
265 |
|
266 |
This library is free software; you can redistribute it and/or |
267 |
modify it under the same terms as Perl itself. |
268 |
|
269 |
=head1 AUTHOR |
270 |
|
271 |
Sean M. Burke C<sburke@cpan.org> |
272 |
|
| |