Extending the Library¶
The choice of MIDI event types included in the library is somewhat idiosyncratic; I included the events I needed for another software project I was wrote. You may find that you need additional events in your work. For this reason I am including some instructions on extending the library. The process isn’t too hard (provided you have a working knowledge of Python and the MIDI standard), so the task shouldn’t present a competent coder too much difficulty. Alternately (if, for example, you don’t have a working knowledge of MIDI and don’t desire to gain it), you can submit new feature requests to me, and I will include them into the development branch of the code, subject to the constraints of time.
To illustrate the process I show below how the MIDI tempo event is incorporated into the code. This is a relatively simple event, so while it may not illustrate some of the subtleties of MIDI programing, it provides a good, illustrative case.
Create a New Event Type¶
The first order of business is to create a new subclass of the GnericEvent object of the MIDIFile module. This subclass initializes any specific instance data that is needed for the MIDI event to be written. In the case of the tempo event, it is the actual tempo (which is defined in the MIDI standard to be 60000000 divided by the tempo in beats per minute). This class should also call the superclass’ initializer with the event time, ordinal, and insertion order, and set the event type (a unique string used internally by the software). In the case of the tempo event:
class Tempo(GenericEvent):
'''A class that encapsulates a tempo meta-event
'''
def __init__(self,time,tempo, ordinal=3, insertion_order=0):
self.tempo = int(60000000 / tempo)
super(Tempo, self).__init__('tempo', time, ordinal, insertion_order)
Any class that you define should include a type, time, ordinal (see below), and an insertion order.
self.ord
and self.insertion_order
are used to order the events
in the MIDI stream. Events are first ordered in time. Events at the
same time are then ordered by self.ord
, with lower numbers appearing
in the stream first. The extant classes in the code all allow the user
to specify an ordinal for the object, but they include default values
that are meant to be reasonable.
Lastly events are sorted on the self.insertion_order
member. This
makes it possible to, say, create a Registered Parameter Number call
from a collection of Control Change events. Since all the CC events will
have the same time and class (and therefore default ordinal), you can control
the order of the events by the order to such you add them to the MIDIFile.
Next, if you want the code to be able to de-duplicate events with may
lay over top of one another, the parent class, GenericEvent
, has a
member function called __eq__()
. If two events do not coincide in
time or type they are not equal, but it they do the __eq__
function
must be modified to show equality. In the case of the Tempo
class,
two tempo events are considered equivalent if they are the same tempo.
In other words, if there are two tempo events at the same time and
the same tempo, one will be removed in the de-duplication process
(which is the default behavious for MIDIFile
, but it can be
turned off). From GenericEvent.__eq__()
:
if self.type == 'tempo':
if self.tempo != other.tempo:
return False
If events are equivalent, the code should return False. If they are not equivalent no return should be called.
Create an Accessor Function¶
Next, an accessor function should be added to MIDITrack to create an event of this type. Continuing the example of the tempo event:
def addTempo(self,time,tempo, insertion_order=0):
'''
Add a tempo change (or set) event.
'''
self.eventList.append(Tempo(time,tempo, insertion_order = insertion_order))
(Most/many MIDI events require a channel specification, but the tempo event does not.)
The public accessor function is via the MIDIFile object, and must include
the track number to which the event is written. So in MIDIFile
:
def addTempo(self,track, time,tempo):
self.tracks[track].addTempo(time,tempo, insertion_order = self.event_counter)
self.event_counter = self.event_counter + 1
Note that a track has been added (which is zero-origined and needs to be
constrained by the number of tracks that the MIDIFile
was created with),
and insertion_order
is taken from the class event_counter
data member. This should be followed in each function you add.
This is the function you will use in your code to create an event of the desired type.
Modify processEventList()¶
Next, the logic pertaining to the new event type should be added to
processEventList()
function of the MIDITrack
class. In general this code
will create a MIDIEvent object and set its type, time, ordinality, and
any specific information that is needed for the event type. This object
is then added to the MIDIEventList.
The relevant section for the tempo event is:
elif thing.type == 'tempo':
event = MIDIEvent("Tempo", thing.time * TICKSPERBEAT, thing.ord, thing.insertion_order)
event.tempo = thing.tempo
self.MIDIEventList.append(event)
THe MIDIEvent
class is expected to have a type
, time
(which should be converted from beats to ticks as above), ordinal, and an
insertion order, which are similar to the values in the GenericEvent
class.
You are free, of course, to add any other data items that need to be specified.
In the case of Tempo
this is the tempo to be written.
Write the Event Data to the MIDI Stream¶
The last step is to modify the MIDIFile.writeEventsToStream()
function;
here is where some understanding of the MIDI standard is necessary. The
following code shows the creation of a MIDI tempo event:
elif event.type == "Tempo":
code = 0xFF
subcode = 0x51
fourbite = struct.pack('>L', event.tempo)
threebite = fourbite[1:4] # Just discard the MSB
varTime = writeVarLength(event.time)
for timeByte in varTime:
self.MIDIdata = self.MIDIdata + struct.pack('>B',timeByte)
self.MIDIdata = self.MIDIdata + struct.pack('>B',code)
self.MIDIdata = self.MIDIdata + struct.pack('>B',subcode)
self.MIDIdata = self.MIDIdata + struct.pack('>B', 0x03)
self.MIDIdata = self.MIDIdata + threebite
The event.type string (“Tempo”) was the one chosen in the processEventList logic.
The code and sub-code are binary values that come from the MIDI specification.
Next the data is packed into a three byte structure (or a four byte structure, discarding the most significant byte). Again, the MIDI specification determines the number of bytes used in the data payload.
All MIDI events begin with a time, which is stored in a slightly bizarre
variable-length format. This time should be converted to MIDI variable-length
data with the writeVarLength()
function before writing to the stream.
In the MIDI standard’s variable length data only seven bits of a word are
used to store data; the eighth bit signifies if more bytes encoding the
value follow. The total length may be 1 to 3 bytes, depending upon the size of
the value encoded. The writeVarLength()
function takes care of this
conversion for you.
Now the data is written to the binary object self.MIDIdata
, which is
the actual MIDI-encoded data stream. As per the MIDI standard, first we
write our variable-length time value. Next we add the event type code and
sub-code. Then we write the length of the data payload, which in the case
of the tempo event is three bytes. Lastly, we write the actual payload,
which has been packed into the variable threebite
.
The reason that there are separate classes for GenericEvent
and MIDIEvent
is that there need not be a one-to-one correspondance. For example, the
code defines a Note
object, but when this is processed in
processEventList()
two MIDIEvent
objects are created, one for
the note on
event, one for the note off
event.
if thing.type == 'note':
event = MIDIEvent("NoteOn", thing.time * TICKSPERBEAT,
thing.ord, thing.insertion_order)
event.pitch = thing.pitch
event.volume = thing.volume
event.channel = thing.channel
self.MIDIEventList.append(event)
event = MIDIEvent("NoteOff", (thing.time+ thing.duration) * TICKSPERBEAT,
thing.ord -0.1,
thing.insertion_order)
event.pitch = thing.pitch
event.volume = thing.volume
event.channel = thing.channel
self.MIDIEventList.append(event)
Note that the NoteOff
event is created with a slightly lower ordinality
than the NoteOn
event. This is so that at any given time the note off
events will be processed before the note on events.
Write Some Tests¶
Yea, it’s a hassle, but you know it’s the right thing to do!