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.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 in which you add them to the MIDIFile.
Next, if you want the code to be able to de-duplicate events which 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
must be modified to show equality. In the case of the
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
if self.type == 'tempo': if self.tempo != other.tempo: return False
If events are not equivalent, the code should return
False. If they are, the
code can be allowed to fall through to its default return of
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
def addTempo(self,track, time,tempo): if self.header.numeric_format == 1: track = 0 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),
insertion_order is taken from the class
data member. This should be followed in each function you add. Also note that
the tempo event is handled differently in format 1 files and format 2 files.
This function ensures that the tempo event is written to the first track
(track 0) for a format 1 file, otherwise it writes it to the track specified.
In most of the public functions a check it done on format, and the track is
incremented by one for format 1 files so that the event is not written to the
tempo track (but preserving the zero-origined convention for all tracks in
This is the function you will use in your code to create an event of the desired type.
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)
MIDIEvent class is expected to have a
(which should be converted from beats to ticks as above), ordinal, and an
insertion order, which are similar to the values in the
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
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
converssion 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
The reason that there are separate classes for
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
MIDIEvent objects are created, one for
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
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!