NAME¶
MIDI::Simple - procedural/OOP interface for MIDI composition
SYNOPSIS¶
use MIDI::Simple;
new_score;
text_event 'http://www.ely.anglican.org/parishes/camgsm/chimes.html';
text_event 'Lord through this hour/ be Thou our guide';
text_event 'so, by Thy power/ no foot shall slide';
set_tempo 500000; # 1 qn => .5 seconds (500,000 microseconds)
patch_change 1, 8; # Patch 8 = Celesta
noop c1, f, o2; # Setup
# Now play
n qn, Cs2; n F; n Ds; n hn, Gs_d1;
n qn, Cs; n Ds; n F; n hn, Cs;
n qn, F; n Cs; n Ds; n hn, Gs_d1;
n qn, Gs_d1; n Ds; n F; n hn, Cs;
write_score 'westmister_chimes.mid';
NOTE ON VERSION CHANGES¶
I consider this module a late-stage beta. Let me know if you run into any
problems, and feel free to suggest features.
This module is somewhat incompatible with the MIDI::Simple versions before .700.
I think I've settled on (i.e., basically frozen) the basic interface for this
module, and will now hopefully only add functionality.
DESCRIPTION¶
This module sits on top of all the MIDI modules -- notably MIDI::Score (so you
should skim MIDI::Score) -- and is meant to serve as a basic interface to
them, for composition. By composition, I mean composing anew; you can use this
module to add to or modify existing MIDI files, but that functionality is to
be considered expermental.
This module provides two related but distinct bits of functionality: 1) a
mini-language (implemented as procedures that can double as methods) for
composing by adding notes to a score structure; and 2) simple functions for
reading and writing scores, specifically the scores you make with the
composition language.
The fact that this module's interface is both procedural and object-oriented
makes it a definite two-headed beast. The parts of the guts of the source code
are not for the faint of heart.
OBJECT STRUCTURE
A MIDI::Simple object is a data structure with the following attributes:
- Score
- This is a list of all the notes (each a listref) that constitute this
one-track musical piece. Scores are explained in MIDI::Score. You probably
don't need to access the Score attribute directly, but be aware that this
is where all the notes you make with "n" events go.
- Time
- This is a non-negative integer expressing the start-time, in ticks from
the start-time of the MIDI piece, that the next note pushed to the Score
will have.
- Channel
- This is a number in the range [0-15] that specifies the current default
channel for note events.
- Duration
- This is a non-negative (presumably nonzero) number expressing, in ticks,
the current default length of note events, or rests.
- Octave
- This is a number in the range [0-10], expressing what the current default
octave number is. This is used for figuring out exactly what note-pitch is
meant by a relative note-pitch specification like "A".
- Notes
- This is a list (presumably non-empty) of note-pitch specifications, as
note numbers in the range [0-127].
- Volume
- This is an integer in the range [0-127] expressing the current default
volume for note events.
- Tempo
- This is an integer expressing the number of ticks a quarter note occupies.
It's currently 96, and you shouldn't alter it unless you really
know what you're doing. If you want to control the tempo of a piece, use
the "set_tempo" routine, instead.
- Cookies
- This is a hash that can be used by user-defined object-methods for storing
whatever they want.
Each package that you call the procedure "new_score" from, has a
default MIDI::Simple object associated with it, and all the above attributes
are accessible as:
@Score $Time $Channel $Duration $Octave
@Notes $Volume $Tempo %Cookies
(Although I doubt you'll use these from any package other than
"main".) If you don't know what a package is, don't worry about it.
Just consider these attributes synonymous with the above-listed variables.
Just start your programs with
use MIDI::Simple;
new_score;
and you'll be fine.
Routine/Method/Procedure
MIDI::Simple provides some pure functions (i.e., things that take input, and
give a return value, and that's all they do), but what you're mostly
interested in its routines. By "routine" I mean a subroutine that
you call, whether as a procedure or as a method, and that affects data
structures other than the return value.
Here I'm using "procedure" to mean a routine you call like this:
name(parameters...);
# or, just maybe:
name;
(In technical terms, I mean a non-method subroutine that can have side effects,
and which may not even provide a useful return value.) And I'm using
"method" to mean a routine you call like this:
$object->name(parameters);
So bear these terms in mind when you see routines below that act like one, or
the other, or both.
MAIN ROUTINES
These are the most important routines:
- new_score() or $obj = MIDI::Simple->new_score()
- As a procedure, this initializes the package's default object (Score,
etc.). As a method, this is a constructor, returning a new MIDI::Simple
object. Neither form takes any parameters.
- n(...parameters...) or $obj->n(...parameters...)
- This uses the parameters given (and/or the state variables like Volume,
Channel, Notes, etc) to add a new note to the Score -- or several notes to
the Score, if Notes has more than one element in it -- or no notes at all,
if Notes is empty list.
Then it moves Time ahead as appropriate. See the section "Parameters
For n/r/noop", below.
- r(...parameters...) or $obj->r(...parameters...)
- This is exactly like "n", except it never pushes anything to
Score, but moves ahead Time. (In other words, there is no such thing as a
rest-event; it's just a item during which there are no note-events
playing.)
- noop(...parameters...) or $obj->noop(...parameters...)
- This is exactly like "n" and "r", except it never
alters Score, and never changes Time. It is meant to be used for
setting the other state variables, i.e.: Channel, Duration, Octave,
Volume, Notes.
Parameters for n/r/noop
A parameter in an "n", "r", or "noop" call is
meant to change an attribute (AKA state variable), namely Channel, Duration,
Octave, Volume, or Notes.
Here are the kinds of parameters you can use in calls to n/r/noop:
* A numeric
volume parameter. This has the form "V" followed by
a positive integer in the range 0 (completely inaudible?) to 127 (AS LOUD AS
POSSIBLE). Example: "V90" sets Volume to 90.
* An alphanumeric
volume parameter. This is a key from the hash
%MIDI::Simple::Volume. Current legal values are "ppp",
"pp", "p", "mp", "mezzo" (or
"m"), "mf", "f", "ff", and
"fff". Example: "ff" sets Volume to 112. (Note that
"m" isn't a good bareword, so use "mezzo" instead, or just
always remember to use quotes around "m".)
* A numeric
channel parameter. This has the form "c" followed
by a positive integer 0 to 15. Example: "c2", to set Channel to 2.
* A numeric
duration parameter. This has the form "d" followed
by a positive (presumably nonzero) integer. Example: "d48", to set
Duration to 48.
* An alphabetic (or in theory, possibly alphanumeric)
duration parameter.
This is a key from the hash %MIDI::Simple::Length. Current legal values start
with "wn", "hn", "qn", "en",
"sn" for whole, half, quarter, eighth, or sixteenth notes. Add
"d" to the beginning of any of these to get "dotted..."
(e.g., "dqn" for a dotted quarter note). Add "dd" to the
beginning of any of that first list to get "double-dotted..." (e.g.,
"ddqn" for a double-dotted quarter note). Add "t" to the
beginning of any of that first list to get "triplet..." (e.g.,
"tsn" for a triplet sixteenth note -- i.e. a note such that 3 of
them add up to something as long as one eighth note). You may add to the
contents of %MIDI::Simple::Length to support whatever abbreviations you want,
as long as the parser can't mistake them for any other kind of n/r/noop
parameter.
* A numeric, absolute
octave specification. This has the form: an
"o" (lowercase oh), and then an integer in the range 0 to 10,
representing an octave 0 to 10. The Octave attribute is used only in resolving
relative note specifications, as explained further below in this section. (All
absolute note specifications also set Octave to whatever octave they occur
in.)
* A numeric, relative
octave specification. This has the form:
"o_d" ("d" for down) or "o_u" ("u" for
down), and then an integer. This increments, or decrements, Octave. E.g., if
Octave is 6, "o_d2" will decrement Octave by 2, making it 4. If this
moves Octave below 0, it is forced to 0. Or if it moves Octave above 10, it is
forced to 10. (For more information, see the section "Invalid or
Out-of-Range Parameters to n/r/noop", below.)
* A numeric, absolute
note specification. This has the form: an optional
"n", and then an integer in the range 0 to 127, representing a note
ranging from C0 to G10. The source to MIDI has a useful reference table
showing the meanings of given note numbers. Examples: "n60", or
"60", which each add a 60 to the list Notes.
Since this is a kind of absolute note specification, it sets Octave to whatever
octave the given numeric note occurs in. E.g., "n60" is
"C5", and therefore sets Octave to 5.
The setting of the Notes list is a bit special, compared to how setting the
other attributes works. If there are any note specifications in a given
parameter list for n, r, or noop, then all those specifications together are
assigned to Notes.
If there are no note specifications in the parameter list for n, r, or noop,
then Notes isn't changed. (But see the destription of "rest", at the
end of this section.)
So this:
n mf, n40, n47, n50;
sets Volume to 80, and Notes to (40, 47, 50). And it sets Octave, first to 3
(since n40 is in octave 3), then to 3 again (since n47 = B3), and then finally
to 4 (since n50 = D4).
Note that this is the same as:
n n40, n47, n50, mf;
The relative orders of parameters is
usually irrelevant; but see the
section "Order of Parameters in a Call to n/r/noop", below.
* An alphanumeric, absolute
note specification.
These have the form: a string denoting a note within the octave (as determined
by %MIDI::Simple::Note -- see below, in the description of alphanumeric,
relative note specifications), and then a number denoting the octave number
(in the range 0-10). Examples: "C3", "As4" or
"Asharp4", "Bf9" or "Bflat9".
Since this is a kind of absolute note specification, it sets Octave to whatever
octave the given numeric note occurs in. E.g., "C3" sets Octave to
3, "As4" sets Octave to 4, and "Bflat9" sets Octave to 9.
This:
n E3, B3, D4, mf;
does the same as this example of ours from before:
n n40, n47, n50, mf;
* An alphanumeric, relative
note specification.
These have the form: a string denoting a note within the octave (as determined
by %MIDI::Simple::Note), and then an optional parameter "_u[number]"
meaning "so many octaves up from the current octave" or
"_d[parameter]" meaning "so many octaves down from the current
octave".
Examples: "C", "As" or "Asharp", "Bflat"
or "Bf", "C_d3", "As_d1" or
"Asharp_d1", "Bflat_u3" or "Bf_u3".
In resolving what actual notes these kinds of specifications denote, the current
value of Octave is used.
What's a legal for the first bit (before any optional octave up/down
specification) comes from the keys to the hash %MIDI::Simple::Note. The
current acceptable values are:
C (maps to the value 0)
Cs or Df or Csharp or Dflat (maps to the value 1)
D (maps to the value 2)
Ds or Ef or Dsharp or Eflat (maps to the value 3)
E (maps to the value 4)
F (maps to the value 5)
Fs or Gf or Fsharp or Gflat (maps to the value 6)
G (maps to the value 7)
Gs or Af or Gsharp or Aflat (maps to the value 8)
A (maps to the value 9)
As or Bf or Asharp or Bflat (maps to the value 10)
B (maps to the value 11)
(Note that these are based on the English names for these notes. If you prefer
to add values to accomodate other strings denoting notes in the octave, you
may do so by adding to the hash %MIDI::Simple::Note like so:
use MIDI::Simple;
%MIDI::Simple::Note =
(%MIDI::Simple::Note, # keep all the old values
'H' => 10,
'Do' => 0,
# ...etc...
);
But the values you add must not contain any characters outside the range
[A-Za-z\x80-\xFF]; and your new values must not look like anything that could
be any other kind of specification. E.g., don't add "mf" or
"o3" to %MIDI::Simple::Note.)
Consider that these bits of code all do the same thing:
n E3, B3, D4, mf; # way 1
n E3, B, D_u1, mf; # way 2
n o3, E, B, D_u1, mf; # way 3
noop o3, mf; # way 4
n E, B, D_u1;
or even
n o3, E, B, o4, D, mf; # way 5!
n o6, E_d3, B_d3, D_d2, mf; # way 6!
If a "_d[number]" would refer to a note in an octave below 0, it is
forced into octave 0. If a "_u[number]" would refer to a note in an
octave above 10, it is forced into octave 10. E.g., if Octave is 8,
"G_u4" would resolve to the same as "G10" (not
"G12" -- as that's out of range); if Octave is 2, "G_d4"
would resolve to the same as "G0". (For more information, see the
section "Invalid or Out-of-Range Parameters to n/r/noop", below.)
* The string ""rest"" acts as a sort of note specification
-- it sets Notes to empty-list. That way you can make a call to "n"
actually make a rest:
n qn, G; # makes a G quarter-note
n hn, rest; # half-rest -- alters Notes, making it ()
n C,G; # half-note chord: simultaneous C and G
r; # half-rest -- DOESN'T alter Notes.
n qn; # quarter-note chord: simultaneous C and G
n rest; # quarter-rest
n; # another quarter-rest
(If you can follow the above code, then you understand.)
A ""rest"" that occurs in a parameter list with other note
specs (e.g., "n qn, A, rest, G") has
no effect, so don't do
that.
Order of Parameters in a Call to n/r/noop
The order of parameters in calls to n/r/noop is not important except insofar as
the parameters change the Octave parameter, which may change how some relative
note specifications are resolved. For example:
noop o4, mf;
n G, B, A3, C;
is the same as "n mf, G4, B4, A3, C3". But just move that
"C" to the start of the list:
noop o4, mf;
n C, G, B, A3;
and you something different, equivalent to "n mf, C4, G4, B4, A3".
But note that you can put the "mf" anywhere without changing anything.
But
stylistically, I strongly advise putting note parameters at the
end of the parameter list:
n mf, c10, C, B; # 1. good
n C, B, mf, c10; # 2. bad
n C, mf, c10, B; # 3. so bad!
3 is particularly bad because an uninformed/inattentive reader may get the
impression that the C may be at a different volume and on a different channel
than the B.
(Incidentally, "n C5,G5" and "n G5,C5" are the same for most
purposes, since the C and the G are played at the same time, and with the same
parameters (channel and volume); but actually they differ in which note gets
put in the Score first, and therefore which gets encoded first in the MIDI
file -- but this makes no difference at all, unless you're manipulating the
note-items in Score or the MIDI events in a track.)
Invalid or Out-of-Range Parameters to n/r/noop
If a parameter in a call to n/r/noop is uninterpretable, Perl dies with an error
message to that effect.
If a parameter in a call to n/r/noop has an out-of-range value (like
"o12" or "c19"), Perl dies with an error message to that
effect.
As somewhat of a merciful exception to this rule, if a parameter in a call to
n/r/noop is a relative specification (whether like "o_d3" or
"o_u3", or like "G_d3" or "G_u3") which happens
to resolve to an out-of-range value (like "G_d3" given an Octave
value of 2), then Perl will
not die, but instead will silently try to
bring that note back into range, by forcing it up to octave 0 (if it would
have been lower), or down into 9 or 10 (if it would have been an octave higher
than 10, or a note higher than G10), as appropriate.
(This becomes strange in that, given an Octave of 8, "G_u4" is forced
down to G10, but "A_u4" is forced down to an A9. But that boundary
has to pop up someplace -- it's just unfortunate that it's in the middle of
octave 10.)
ATTRIBUTE METHODS
The object attributes discussed above are readable and writeable with object
methods. For each attribute there is a read/write method, and a read-only
method that returns a reference to the attribute's value:
Attribute ⎪⎪ R/W-Method ⎪⎪ RO-R-Method
----------++-------------++--------------------------------------
Score ⎪⎪ Score ⎪⎪ Score_r (returns a listref)
Notes ⎪⎪ Notes ⎪⎪ Notes_r (returns a listref)
Time ⎪⎪ Time ⎪⎪ Time_r (returns a scalar ref)
Duration ⎪⎪ Duration ⎪⎪ Duration_r (returns a scalar ref)
Channel ⎪⎪ Channel ⎪⎪ Channel_r (returns a scalar ref)
Octave ⎪⎪ Octave ⎪⎪ Octave_r (returns a scalar ref)
Volume ⎪⎪ Volume ⎪⎪ Volume_r (returns a scalar ref)
Tempo ⎪⎪ Tempo ⎪⎪ Tempo_r (returns a scalar ref)
Cookies ⎪⎪ Cookies ⎪⎪ Cookies_r (returns a hashref)
To read any of the above via a R/W-method, call with no parameters, e.g.:
$notes = $obj->Notes; # same as $obj->Notes()
The above is the read-attribute ("get") form.
To set the value, call with parameters:
$obj->Notes(13,17,22);
The above is the write-attribute ("put") form. Incidentally, when used
in write-attribute form, the return value is the same as the parameters,
except for Score or Cookies. (In those two cases, I've suppressed it for
efficiency's sake.)
Alternately (and much more efficiently), you can use the read-only reference
methods to read or alter the above values;
$notes_r = $obj->Notes_r;
# to read:
@old_notes = @$notes_r;
# to write:
@$notes_r = (13,17,22);
And this is the only way to set Cookies, Notes, or Score to a (), like so:
$notes_r = $obj->Notes_r;
@$notes_r = ();
Since this:
$obj->Notes;
is just the read-format call, remember?
Like all methods in this class, all the above-named attribute methods double as
procedures that act on the default object -- in other words, you can say:
Volume 10; # same as: $Volume = 10;
@score_copy = Score; # same as: @score_copy = @Score
Score @new_score; # same as: @Score = @new_score;
$score_ref = Score_r; # same as: $score_ref = \@Score
Volume(Volume + 10) # same as: $Volume += 10
But, stylistically, I suggest not using these procedures -- just directly access
the variables instead.
MIDI EVENT ROUTINES
These routines, below, add a MIDI event to the Score, with a start-time of Time.
Example:
text_event "And now the bongos!"; # procedure use
$obj->text_event "And now the bongos!"; # method use
These are named after the MIDI events they add to the score, so see MIDI::Event
for an explanation of what the data types (like "velocity" or
"pitch_wheel") mean. I've reordered this list so that what I guess
are the most important ones are toward the top:
- patch_change channel, patch;
- key_after_touch channel, note, velocity;
- channel_after_touch channel, velocity;
- control_change channel, controller(0-127),
value(0-127);
- pitch_wheel_change channel, pitch_wheel;
- set_tempo tempo; (See the section on tempo, below.)
- smpte_offset hr, mn, se, fr, ff;
- time_signature nn, dd, cc, bb;
- key_signature sf, mi;
- text_event text;
- copyright_text_event text;
- track_name text;
- instrument_name text;
- lyric text;
- set_sequence_number sequence;
- marker text;
- cue_point text;
- sequencer_specific raw;
- sysex_f0 raw;
- sysex_f7 raw;
And here's the ones I'll be surprised if anyone ever uses:
- text_event_08 text;
- text_event_09 text;
- text_event_0a text;
- text_event_0b text;
- text_event_0c text;
- text_event_0d text;
- text_event_0e text;
- text_event_0f text;
- raw_meta_event command(0-255), raw;
- song_position starttime;
- song_select song_number;
- tune_request starttime;
- raw_data raw;
- end_track starttime;
- note duration, channel, note, velocity;
-
About Tempo
The chart above shows that tempo is set with a method/procedure that takes the
form set_tempo(
tempo), and MIDI::Event says that
tempo is
"microseconds, a value 0 to 16,777,215 (0x00FFFFFF)". But at the
same time, you see that there's an attribute of the MIDI::Simple object called
"Tempo", which I've warned you to leave at the default value of 96.
So you may wonder what the deal is.
The "Tempo" attribute (AKA "Divisions") is an integer that
specifies the number of "ticks" per MIDI quarter note. Ticks is just
the notional timing unit all MIDI events are expressed in terms of. Calling it
"Tempo" is misleading, really; what you want to change to make your
music go faster or slower isn't that parameter, but instead the mapping of
ticks to actual time -- and that is what "set_tempo" does. Its one
parameter is the number of microseconds each quarter note should get.
Suppose you wanted a tempo of 120 quarter notes per minute. In terms of
microseconds per quarter note:
set_tempo 500_000; # you can use _ like a thousands-separator comma
In other words, this says to make each quarter note take up 500,000
microseconds, namely .5 seconds. And there's 120 of those half-seconds to the
minute; so, 120 quarter notes to the minute.
If you see a "[quarter note symbol] = 160" in a piece of sheet music,
and you want to figure out what number you need for the "set_tempo",
do:
60_000_000 / 160 ... and you get: 375_000
Therefore, you should call:
set_tempo 375_000;
So in other words, this general formula:
set_tempo int(60_000_000 / $quarter_notes_per_minute);
should do you fine.
As to the Tempo/Duration parameter, leave it alone and just assume that 96
ticks-per-quarter-note is a universal constant, and you'll be happy.
(You may wonder: Why 96? As far as I've worked out, all purmutations of the
normal note lengths (whole, half, quarter, eighth, sixteenth, and even
thirty-second notes) and tripletting, dotting, or double-dotting, times 96,
all produce integers. For example, if a quarter note is 96 ticks, then a
double-dotted thirty-second note is 21 ticks (i.e., 1.75 * 1/8 * 96). But
that'd be a messy 10.5 if there were only 48 ticks to a quarter note. Now, if
you wanted a quintuplet anywhere, you'd be out of luck, since 96 isn't a
factor of five. It's actually 3 * (2 ** 5), i.e., three times two to the
fifth. If you really need quintuplets, then you have my very special
permission to mess with the Tempo attribute -- I suggest multiples of 96,
e.g., 5 * 96.)
(You may also have read in MIDI::Filespec that "time_signature" allows
you to define an arbitrary mapping of your concept of quarter note, to MIDI's
concept of quarter note. For your sanity and mine, leave them the same, at a
1:1 mapping -- i.e., with an '8' for "time_signature"'s last
parameter, for "eight notated 32nd-notes per MIDI quarter note". And
this is relevant only if you're calling "time_signature" anyway,
which is not necessarily a given.)
MORE ROUTINES
- $opus = write_score filespec
- $opus = $obj->write_score(filespec)
- Writes the score to the filespec (e.g,
"../../samples/funk2.midi", or a variable containing that
value), with the score's Ticks as its tick parameters (AKA
"divisions"). Among other things, this function calls the
function "make_opus", below, and if you capture the output of
write_score, you'll get the opus created, if you want it for anything.
(Also: you can also use a filehandle-reference instead of the filespec:
"write_score *STDOUT{IO}".)
- read_score filespec
- $obj = MIDI::Simple->read_score('foo.mid'))
- In the first case (a procedure call), does "new_score" to erase
and initialize the object attributes (Score, Octave, etc), then reads from
the file named. The file named has to be a MIDI file with exactly one
eventful track, or Perl dies. And in the second case,
"read_score" acts as a constructor method, returning a new
object read from the file.
Score, Ticks, and Time are all affected:
Score is the event form of all the MIDI events in the MIDI file. (Note:
Seriously deformed MIDI files may confuse the routine that turns
MIDI events into a Score.)
Ticks is set from the ticks setting (AKA "divisions") of the file.
Time is set to the end time of the latest event in the file.
(Also: you can also use a filehandle-reference instead of the filespec:
"read_score *STDIN{IO}".)
If ever you have to make a Score out of a single track from a
multitrack file, read the file into an $opus, and then consider
something like:
new_score;
$opus = MIDI::Opus->new({ 'from_file' => "foo2.mid" });
$track = ($opus->tracks)[2]; # get the third track
($score_r, $end_time) =
MIDI::Score::events_r_to_score_r($track->events_r);
$Ticks = $opus->ticks;
@Score = @$score_r;
$Time = $end_time;
- synch( LIST of coderefs )
- $obj->synch( LIST of coderefs )
- LIST is a list of coderefs (whether as a series of anonymous subs, or as a
list of items like "(\&foo, \&bar, \&baz)", or a
mixture of both) that "synch" calls in order to add to the given
object -- which in the first form is the package's default object, and
which in the second case is $obj. What "synch" does is:
* remember the initial value of Time, before calling any of the routines;
* for each routine given, reset Time to what it was initially, call the
routine, and then note what the value of Time is, after each call;
* then, after having called all of the routines, set Time to whatever was
the greatest (equals latest) value of Time that resulted from any of the
calls to the routines.
The coderefs are all called with one argument in @_ -- the object they are
supposed to affect. All these routines should/must therefore use method
calls instead of procedure calls. Here's an example usage of synch:
my $measure = 0;
my @phrases =(
[ Cs, F, Ds, Gs_d1 ], [Cs, Ds, F, Cs],
[ F, Cs, Ds, Gs_d1 ], [Gs_d1, Ds, F, Cs]
);
for(1 .. 20) { synch(\&count, \&lalala); }
sub count {
my $it = $_[0];
$it->r(wn); # whole rest
# not just "r(wn)" -- we want a method, not a procedure!
++$measure;
}
sub lalala {
my $it = $_[0];
$it->noop(c1,mf,o3,qn); # setup
my $phrase_number = ($measure + -1) % 4;
my @phrase = @{$phrases[$phrase_number]};
foreach my $note (@phrase) { $it->n($note); }
}
- $opus = make_opus or $opus = $obj->make_opus
- Makes an opus (a MIDI::Opus object) out of Score, setting the opus's tick
parameter (AKA "divisions") to $ticks. The opus is,
incidentally, format 0, with one track.
- dump_score or $obj->dump_score
- Dumps Score's contents, via "print" (so you can
"select()" an output handle for it). Currently this is in this
somewhat uninspiring format:
['note', 0, 96, 1, 25, 96],
['note', 96, 96, 1, 29, 96],
as it is (currently) just a call to &MIDI::Score::dump_score; but in the
future I may (should?) make it output in "n"/"r"
notation. In the meantime I assume you'll use this, if at all, only for
debugging purposes.
FUNCTIONS
These are subroutines that aren't methods and don't affect anything (i.e., don't
have "side effects") -- they just take input and/or give output.
- interval LISTREF, LIST
- This takes a reference to a list of integers, and a list of note-pitch
specifications (whether relative or absolute), and returns a list
consisting of the given note specifications transposed by that many
half-steps. E.g.,
@majors = interval [0,4,7], C, Bflat3;
which returns the list "(C,E,G,Bf3,D4,F4)".
Items in LIST which aren't note specifications are passed thru
unaltered.
- note_map { BLOCK } LIST
- This is pretty much based on (or at least inspired by) the normal Perl
"map" function, altho the syntax is a bit more restrictive
(i.e., "map" can take the form "map {BLOCK} LIST" or
"map(EXPR,LIST)" -- the latter won't work with
"note_map").
"note_map {BLOCK} (LIST)" evaluates the BLOCK for each element of
LIST (locally setting $_ to each element's note-number value) and returns
the list value composed of the results of each such evaluation. Evaluates
BLOCK in a list context, so each element of LIST may produce zero, one, or
more elements in the returned value. Moreover, besides setting $_,
"note_map" feeds BLOCK (which it sees as an anonymous
subroutine) three parameters, which BLOCK can access in @_ :
$_[0] : Same as $_. I.e., The current note-specification,
as a note number.
This is the result of having fed the original note spec
(which you can see in $_[2]) to is_note_spec.
$_[1] : The absoluteness flag for this note, from the
above-mentioned call to is_note_spec.
0 = it was relative (like 'C')
1 = it was absolute (whether as 'C4' or 'n41' or '41')
$_[2] : the actual note specification from LIST, if you want
to access it for any reason.
Incidentally, any items in LIST that aren't a note specification are passed
thru unchanged -- BLOCK isn't called on it.
So, in other words, what "note_map" does, for each item in LIST,
is:
* It calls "is_note_spec" on it to test whether it's a note
specification at all. If it isn't, just passes it thru. If it is, then
"note_map" stores the note number and the absoluteness flag that
"is_note_spec" returned, and...
* It calls BLOCK, providing the note number in $_ and $_[0], the
absoluteness flag in $_[1], and the original note specification in $_[2].
Stores the return value of calling BLOCK (in a list context of course) --
this should be a list of note numbers.
* For each element of the return value (which is actually free to be an
empty list), converts it from a note number to whatever kind of
specification the original note value was. So, for each element, if the
original was relative, "note_map" interprets the return value as
a relative note number, and calls "number_to_relative" on it; if
it was absolute, "note_map" will try to restore it to the
correspondingly formatted absolute specification type.
An example is, I hope, helpful:
This:
note_map { $_ - 3, $_ + 2 } qw(Cs3 n42 50 Bf)
returns this:
('Bf2', 'Ef3', 'n39', 'n44', '47', '52', 'G', 'C_u1')
Or, to line things up:
Cs3 n42 50 Bf
⎪ ⎪ ⎪ ⎪
/-----\ /-----\ /---\ /----\
Bf2 Ef3 n39 n44 47 52 G C_u1
Now, of course, this is the same as what this:
interval [-3, 2], qw(Cs3 n42 50 Bf)
returns. This is fitting, as "interval", internally, is basically
a simplified version of "note_map". But "interval"
only lets you do unconditional transposition, whereas "note_map"
lets you do anything at all. For example:
@note_specs = note_map { $funky_lookup_table{$_} }
C, Gf;
or
@note_specs = note_map { $_ + int(rand(2)) }
@stuff;
"note_map", like "map", can seem confusing to beginning
programmers (and many intermediate ones, too), but it is quite
powerful.
- number_to_absolute NUMBER
- This returns the absolute note specification (in the form "C5")
that the MIDI note number in NUMBER represents.
This is like looking up the note number in %MIDI::number2note -- not exactly
the same, but effectively the same. See the source for more details.
- the function number_to_relative NUMBER
- This returns the relative note specification that NUMBER represents. The
idea of a numerical representation for "relative" note
specifications was necessitated by "interval" and
"note_map" -- since without this, you couldn't meaningfully say,
for example, interval [0,2] 'F'. This should illustrate the concept:
number_to_relative(-10) => "D_d1"
number_to_relative( -3) => "A_d1"
number_to_relative( 0) => "C"
number_to_relative( 5) => "F"
number_to_relative( 10) => "Bf"
number_to_relative( 19) => "G_u1"
number_to_relative( 40) => "E_u3"
- is_note_spec STRING
- If STRING is a note specification, "is_note_spec(STRING)"
returns a list of two elements: first, a flag of whether the note
specification is absolute (flag value 1) or relative (flag value 0); and
second, a note number corresponding to that note specification. If STRING
is not a note specification, "is_note_spec(STRING)" returns an
empty list (which in a boolean context is FALSE).
Implementationally, "is_note_spec" just uses
"is_absolute_note_spec" and "is_relative_note_spec".
Example usage:
@note_details = is_note_spec($thing);
if(@note_details) {
($absoluteness_flag, $note_num) = @note_details;
...stuff...
} else {
push @other_stuff, $thing; # or whatever
}
- is_relative_note_spec STRING
- If STRING is an relative note specification, returns the note number for
that specification as a one-element list (which in a boolean context is
TRUE). Returns empty-list (which in a boolean context is FALSE) if STRING
is NOT a relative note specification.
To just get the boolean value:
print "Snorf!\n" unless is_relative_note_spec($note);
But to actually get the note value:
($note_number) = is_relative_note_spec($note);
Or consider this:
@is_rel = is_relative_note_spec($note);
if(@is_rel) {
$note_number = $is_rel[0];
} else {
print "Snorf!\n";
}
(Author's note, two years later: all this business of returning lists of
various sizes, with this and other functions in here, is basically a
workaround for the fact that there's not really any such thing as a
boolean context in Perl -- at least, not as far as user-defined functions
can see. I now think I should have done this with just returning a single
scalar value: a number (which could be 0!) if the input is a number, and
undef/emptylist ("return;") if not -- then, the user could test:
# Hypothetical --
# This fuction doesn't actually work this way:
if(defined(my $note_val = is_relative_note_spec($string))) {
...do things with $note_val...
} else {
print "Hey, that's no note!\n";
}
However, I don't anticipate users actually using these messy functions often
at all -- I basically wrote these for internal use by MIDI::Simple, then I
documented them on the off chance they might be of use to anyone
else.)
- is_absolute_note_spec STRING
- Just like "is_relative_note_spec", but for absolute note
specifications instead of relative ones.
- Self() or $obj->Self();
- Presumably the second syntax is useless -- it just returns $obj. But the
first syntax returns the current package's default object.
Suppose you write a routine, "funkify", that does
something-or-other to a given MIDI::Simple object. You could write it so
that acts on the current package's default object, which is fine -- but,
among other things, that means you can't call "funkify" from a
sub you have "synch" call, since such routines should/must use
only method calls. So let's say that, instead, you write
"funkify" so that the first argument to it is the object to act
on. If the MIDI::Simple object you want it to act on is it $sonata, you
just say
funkify($sonata)
However, if you want it to act on the current package's default MIDI::Simple
object, what to say? Simply,
$package_opus = Self;
funkify($package_opus);
COPYRIGHT¶
Copyright (c) 1998-2002 Sean M. Burke. All rights reserved.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
AUTHOR¶
Sean M. Burke "sburke@cpan.org"