Again, there is very little here that is not easily derived from the documentation within the modules themselves, so if this stuff is unclear refer to that. I am really only adding things that derive from my experience of actually using these modules to compose music...
I prefer to work with MIDI Note Numbers, since it's fairly easy to describe the relationships between notes using mathematics and fairly difficult to translate note name to math and/or vice-versa. Nonetheless, MIDI::Simple does parse note names and octaves. In other words, you can call notes by common names: n E, V90, d64;, and if ye be stout of heart, ye can even alter the module hashes themselves to recognise note names in your native tongue, or some weird set of idiosyncratic nicknames of your own devising...
But how then is the octave determined? Well, you can set an abolute octave using the o flag: n E, o5;. Octaves span from 0 to 10 (though the last octave is incomplete: G10 is the highest note). Or you can call the note with the octave number appended: n As3, g3, d2;. Octaves can also be set in a relative way - even when using MIDI note numbers, the octave is constantly set and reset behind the scenes, so if you input n 60; n E;, the first call sets the current octave to '5', so the second call plays E in the 5th octave. To change octaves relative to the last octave, append _u or _d to the note name, then the number of octaves to change: n C, o5; n D_d1; n E_u3;.
Again, I don't really use this. It would make sense if you had a set piece of music you were just trying to turn into a MIDI file, but leaving the information in math form is way easier for me to think about. But for all I know, there may be someone out there doing fantastic things using note names this way...
I prefer to set velocity as a straight 0-127 number as well. But once again, MIDI::Simple allows for more traditional notation to be used. From the module code:
%Volume = ( # I've simply made up these values from more or less nowhere.
# You no like? Change 'em at runtime, or just use "V64" or whatever,
# to specify the volume as a number 1-127.
'ppp' => 1, # pianississimo
'pp' => 12, # pianissimo
'p' => 24, # piano
'mp' => 48, # mezzopiano
'm' => 64, # mezzo / medio / meta` / middle / whatever
'mezzo' => 64,
'mf' => 80, # mezzoforte
'f' => 96, # forte
'ff' => 112, # fortissimo
'fff' => 127, # fortississimo
);
Of course, another option is to go ahead and change this hash in the module code itself, if ye be stout of heart and courageous of, um, whatever, etc.
A note about the volume flag: you'll notice that all of the flags and all of the calls are lower-case? EXCEPT V. Seems when you include a bare, lower-case v in your code, it messes with Perl's perly-pearly perl-guts somewhere. So you have to use the flag in upper case: "V127,"; or single-quoted: " 'v'.127,".
OF COURSE there's a plaintext way to call note durations:
%Length = ( # this list should be rather uncontroversial.
# The numbers here are multiples of a quarter note's length
# The abbreviations are:
# qn for "quarter note",
# dqn for "dotted quarter note",
# ddqn for "double-dotten quarter note",
# tqn for "triplet quarter note"
'wn' => 4, 'dwn' => 6, 'ddwn' => 7, 'twn' => (8/3),
'hn' => 2, 'dhn' => 3, 'ddhn' => 3.5, 'thn' => (4/3),
'qn' => 1, 'dqn' => 1.5, 'ddqn' => 1.75, 'tqn' => (2/3),
'en' => .5, 'den' => .75, 'dden' => .75, 'ten' => (1/3),
'sn' => .25, 'dsn' => .375, 'ddsn' => .4375, 'tsn' => (1/6),
# Yes, these fractions could lead to round-off errors, I suppose.
# But note that 96 * all of these == a WHOLE NUMBER!!!!!
# Dangit, tsn for "thirty-second note" clashes with pre-existing tsn for
# "triplet sixteenth note"
#For 32nd notes, tha values'd be:
# .125 .1875 .21875 (1/12)
#But hell, just access 'em as:
# d12 d18 d21 d8
#(assuming Tempo = 96)
);
and he's right: you CAN end up with rounding errors. I'll cover dealing with those at the bottom of this page. Here as elsewhere I prefer to use number durations, mostly because I don't leave Tempo = 96.
Tempo defaults to 120 beats per minute (and that's tempo, as in set_tempo; 'Tempo' is a very different thing altogether - I address that in the last section).
Time signature defaults to 4/4. No surprise there.
But if you want to change them, here's how:
set_tempo tempo;
tempo being expressed as microseconds per quarter note. What the heck does that mean? WHO CARES! There's an easy way to convert actual ideas that real, live hyoomons use to this wacky comyootar-speak: $microseconds_per_midi_tick = 60000000 / $beats_per_minute. No reason to care beyond that unless you want to do wacky things with unusual rhythms and the Tempo parameter like I do, and I will expound upon that at the bottom of this page. And really there's no reason to care about it even then unless you're interfacing with an actual piece of MIDI hardware, like, from the 80's, as I'll explain in a couple paragraphs.
time_signature numerator, denominator, cc, bb;
time_signature gets pretty crazy. The numerator value is exactly what you expect it to be (though it DOES expect a 2-digit value): if you're in 4/4 time it's '04', if you're in 3/4 time it's '03'. Denominator is exactly not what you expect it to be: it wants the power of 2 that results in the denominator you want (WTF); 2^2 = 4, so 4/4 is set_tempo 04, 02, 24, 08;, 2^4 is 16, so 15/16 time would be set_tempo 15, 04, 24, 08;. What's up with those other 2 parameters? FOR THE LOVE OF GOD, MAN, LEAVE THEM BE - to do otherwise is to fail a savings-throw against Lovecraftian horror which will leave you unwashed, leaning against a 7-11, shouting at passers-by in a language that has no vowels. With a broken MIDI file. Anyway, it all has to do with MIDI ticks per metronome click (metronome click????) and the number of 32nd notes in a quarter note. Leave those as '24' and '08', respectively. Even if you successfully battled these parameters to some end, it would all be for naught BECAUSE:
I have noticed in my travels that there are virtually NO commercial computer music applications that pay any attention whatsoever to tempo or time signature data coming from a MIDI file. Some of the older ones will load the initial tempo, but changing these parameters in the midst of a file and expecting the software to care is not going to make happy fun times for you. (Ableton Live is particularly hilarious in that it asks whether you wish to accept tempo and time signature data from a MIDI clip at load time, then ignores it when you say yes...) If you're making MIDI files to be loaded on a floppy disc and played on your old Ensoniq keyboard workstation, knock yourself out; if (like me) you're making files to load into some software sequencer, you will need another approach. Mine is to have the code spit out that information to a separate text file, which I can then hand-code into whatever software I'm using.
Pretty straightforward, if you know what you're looking for and how your MIDI device or application counts
control_change channel[0-15], control number[0-127], value[0-127];
patch_change channel[0-15], patch[0-127];
channel_after_touch channel[0-15], velocity[0-127];
key_after_touch channel[0-15], note[0-127], velocity[0-127];
pitch_wheel_change channel[0-15], value[0-127];
Note that all of these accept unflagged, ordered values only...
The MIDI spec is of course chock-full of other stuff, too, and MIDI-Simple is more than happy to provide a way to access it. This stuff isn't neccessarily uncommon, but I've not really found any reason to put any of it in a script. If you have any idea how to use this stuff, then GO TO. Note that if I don't specify what a parameter is, I have no idea and you will need to do your own research to figure out what kinds of number are expected by that parameter...
smpte_offset hours, minutes, seconds, frames, sub-frames;
key_signature sf, mi; (sharps/flats? minor?)
text_event text;
copyright_text_event text;
track_name text;
instrument_name text;
lyric text;
set_sequence_number text;
marker text;
cue_point text;
sequencer_specific raw;
sysex_f0 raw;
sysex_f7 raw;
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]I
song_position starttime;
song_select song_number;
tune_request start_time;
raw_data raw;
end_track start_time;
Remember that all of this code is a wrapper to translate the concepts you use in your brain as a musician into a series of commands your MIDI application can use, and that there is only so much overlap between the points of brain, code, and output. It is not particularly easy to parse music ideas into MIDI::Simple syntax, and if you stroll through the code of the MIDI-Perl modules, you will note that it is clearly not easy to translate MIDI::Simple syntax into an actual MIDI file.
So, what is the end result? A MIDI file is just a series of timed events:
time event parameters
what's so hard about that? Well, to start with all the values are expressed in hex (00000000 - FFFFFFFF). But beyond that, the whole time idea is a little catywumpus: it is not a matter of "event happens at time", it is "wait time before executing event." This is referred to as 'delta-time', and it is not measured in clock time. MIDI's standard time measurement is the tick.
The MIDI tick is the heartbeat of the format; tempo is set by defining a quarter note in relation to a clock time (microseconds), and then the quarter note is subdivided into ticks. Left to its own devices, MIDI::Simple will spit out files with 96 ticks per quarter note, and that is fine for regular, every-date applications. 96 is divisible by 3, and by many multiples of 2, and can thus be used to express all of the most common note durations you can think of. It is only at the extreme reaches of notes - triplet triplets, fractions of 32nd notes, etc - where you will start to run into fractions of a tick and start to get into trouble, syncronization-wise.
Now for me, subdivisions of 5 are not uncommon. Certainly not as common as a subdivision of 4 or 3, but not unheard of. And, you will notice, 96 is not divisible by 5: if I want to do a quintuplet I'll have a tick left over that I will need to bury in one of the 5 notes, or else all events from this point on will happen a tick too soon. Fortunately it's fairly easy to randomly extend one of your quintuplets by a single tick, and even at a slow tempo you are not going to notice that one note is a tiny bit longer than the others.
But I also avoid this issue by increasing the resolution - the number of ticks per quarter note. This is what the Tempo command is for. (It's unfortunate that it shares namespace with a fairly basic concept that it has very little to do with, but what are you gonna do? Just remember that Tempo has nothing to do with set_tempo and you'll do fine.) If you multiply 96 * 5, you get 480, a number that has all advantages of 96, and is also divisible by 5; and if you DO wind up in a remainder situation, any leftover ticks you redistribute between your notes constitute a positively miniscule time difference. To set it, use: Tempo(480); right after you create the score.
Now, SURE, you can set Tempo to any arbitrary value you wish - so long as it can be expressed within a byte of hex - but bear in mind that something has to read it. It's all well and good to go 2x2x3x5x7x11x13x17 = Tempo(1021020);, but it's likely that whatever you load THAT into will fail spectacularly in a way that feels like it's laughing at you...