Illustration by Lia Avant

PMIDI

The Musical Instrument Digital Interface (MIDI) is a standard in the music industry for controlling audio devices such as keyboard synthesizers and computer sound cards. A client to a MIDI device can format, sequence, and stream MIDI commands in order to generate synthesized music and sound effects. Dealing with the low-level details of command structure, ordering, and timing can be difficult, which makes a layer of abstraction essential to ease the burden of controlling MIDI devices from software.

The PMIDI library for Python and Windows hides many of the details of controlling MIDI devices. In this article, we first present a programmer's view of MIDI. We next introduce PMIDI by explaining its purpose and its design. We then provide three examples of increasing complexity to demonstrate the features and use of PMIDI. Finally, we conclude with a discussion of the current limitations of the library, as well as possible improvements.

In most modern operating systems, a programmer does not have to be concerned with many of the details of communicating with a MIDI device. From the programmer's point of view, the operating system (OS) provides a "conduit" for communication with any MIDI synthesizer attached to the computer — a sound card, a keyboard attached through a sound card, a keyboard attached to a dedicated MIDI I/O card, etc. Each device, in turn, supports a number of channels (typically sixteen) that can be configured independently and controlled by means of commands. A program generates these commands to indicate what sound should be synthesized on a particular channel, how it should be synthesized, and when it should be played.

Commands for a MIDI device are fixed-length packets with bits representing the type of command, the target channel, and the data payload. To play a note, a program sends a 'note on' command to a channel on a MIDI device with a data payload indicating which pitch should be played and how loudly it should be played. To end a playing note, a program sends a 'note off' command with the same data payload after the desired duration of the note has elapsed. Commands are also available for selecting instruments, bending note pitch, adding key aftertouch, and setting channel panning, to name a few of the possible operations that can be programmed.

While MIDI provides an effective, standardized way of interacting with synthesizers, it presents a couple of difficulties for programmers who just want to "make some noise." First, the process of building proper commands and sending them to a MIDI device can be tedious and error-prone. Dealing with bit fields is not something a programmer wants to do often. Second, sending 'note on' and 'note off' commands at proper intervals can be challenging for an application that is busy doing other work. Passing a buffer to another party for proper playback is more desirable. Both of these obstacles can be hidden with proper encapsulation.

The PMIDI library wraps the low-level details of the MIDI standard with high-level programming abstractions. Instead of creating command messages containing information about channel, voice, pitch, and duration, programmers work with Python objects representing songs, instruments, measures, and notes. When sound needs to be synthesized, the PMIDI library automatically converts these objects into the appropriate MIDI commands and sequences them correctly. Once sequenced, the commands are executed asynchronously by the Microsoft Windows MIDI Streams API. This API manages all of the timing and communication details with the target MIDI device, allowing a programmer to "play and forget" a particular sequence.

The original purpose of the PMIDI library was to provide a way for the author to create earcons (short snippets of music that encode information, for example, that a new email has been received) in his assistive technology research. The design of the library directly reflects this purpose. PMIDI makes it easy for a programmer to generate and play back MIDI sequences on-the-fly in Python code. The MIDI sequence might be representative of some software event (as mentioned above, that a new email has been received) or creatively encode some more detailed information (e.g., the length of the new email or if it is likely to be spam). On the other hand, PMIDI does not help in playing long MIDI songs or in loading and saving MIDI files to and from disk. These features are absent from the library at the current time.

The PMIDI library consists of five first-class objects a programmer deals with directly — Sequencer, Song, Instrument, Measure, and Note. The only object the programmer directly instantiates is Sequencer; it is then used to create a new Song. The Song object can then be used to create new Instruments representing the different voices in the composition. An Instrument object can be used to create Measures, which in turn can be used to organize and create Notes.

Consider the following example code segment which creates and plays a new MIDI sequence consisting of one instrument playing two notes.

Every time a new object is created, its creator maintains a reference and hands back a reference. For instance, when a new Measure is created by calling NewMeasure on an Instrument object, a reference to the Measure object is maintained within the Instrument object and another is handed back to the programmer. This approach allows the programmer to work with the Measure object by adding new notes, and also allows the Instrument to keep track of the Measure and its Notes for later sequencing. The final Play method call works properly because the Sequencer still holds a reference to the last 'song' it created.

Most of the information in this example (and in most PMIDI programs) is encoded in the NewNote method calls. The NewNote method adds a single note to the MIDI sequence given its starting tick within its parent measure, its duration in ticks, its pitch name, and its octave. The tick value is one sixty-fourth of the total duration of a measure, or a sixty-fourth note in musical terms. A note's duration may extend past the end of a measure indefinitely. The pitch name may be selected from any of the standard note names (C, C#, Db, etc.) and the octave ranges from 0 to 10 (a C in octave zero to a G ten octaves higher) on a typical MIDI device.

Notes played by a single voice may be overlapped in time. In the example code above, both the C and G notes are started and stopped simultaneously, forming an open chord. While MIDI devices may only support a small number of channels, each channel may play a number of pitches concurrently to produce polyphonic sound.

As mentioned earlier, MIDI playback is performed asynchronously by PMIDI. As a result, the execution of the script continues immediately after the Play method is called, not after the sequence has finished playing. The sleep statement at the end of the program is necessary to keep the script from quitting before the sequence ends. In a program with a message pump (e.g. a GUI program), the sleep statement is unnecessary since the program will sit idle or process other input while the sequence is playing.

The features and use of the PMIDI library can be presented clearly through a few annotated examples. The first example plays a simple scale at a specific tempo using a specific instrument. The second example plays the same scale, but with two additional parts — a bassline and a drum rhythm. The final example shows a small application of PMIDI to the sonification of real world data.

Example 1: Playing a one-voice scale

In this first example, we start by instantiating a Sequencer object. We then create a new Song, and set its tempo to 180 beats per minute (BPM). Next we create a new Voice and make it the instrument 'marimba'.. We continue by making a new Measure object for the marimba and adding all the notes of a C-major scale to it. Finally, we ask the Sequencer to play the scale.

Example 2: Extending the scale with additional voices

In this second example, we extend our simple scale with a bassline and a drum beat while folding the NewNote commands into succinct loops. We first create three Voices for the three instruments in our short 'song': a marimba, an acoustic bass, and a drumset. Since the MIDI standard reserves a special channel for the MIDI drumset, we must explicitly state that we want to use it when we create the third Voice object.

Again, we create a Measure for the marimba and fill it with an ascending C-major scale. We also create a Measure for the bass and fill it with a descending C-major scale. (N.B.: All notes are in concert pitch.) The Notes for both instruments are triggered on the same ticks in the first Measure, so they are played simultaneously. We then create two Measures for the drumset. We fill the first with hits on various instruments in the drumset using the NewHit command. In the second measure, we place a single cymbal crash on the first beat. Finally, we ask the Sequencer to play our song.

Example 3: Sonifying unread emails

In the final example, we use PMIDI to sonify quantitative information rather than to just make musical sounds. The AudioIMAP class can connect to an IMAP server, ask for the number of new emails, and play a MIDI sequence representing the number of new emails received by the IMAP server. Such an application might be useful to users who want to know how much new email has arrived without having to divert their visual attention away from their current work.

The SonifyRecentEmails class is the function of interest in our AudioIMAP class. When the method is called, it initiates an IMAP connection, gets the number of recent emails, and then disconnects. If there is no new mail, a single trombone blast is played. If x new emails have arrived, the first x notes of a C-major scale are played. If more than ten new emails have arrived, then the entire C-major scale is played followed by a note an octave higher. The number of emails (up to ten) is redundantly encoded in the number of notes played and their increasing pitch.

At the time of this writing, the current version of PMIDI (1.0) is limited in a number of ways. It would not require much work to remedy most of these limitations.

• Note attack parameters are not supported. All notes are sounded with a full attack value.
• Note effects are not supported. All notes are played without any left-right panning or additional effects.
• Master volume control is not supported. The master volume is set to the default value for all sequences.
• Event callbacks are not supported. Events cannot be injected into a song to trigger a callback in Python code.
• The library only works on the Windows platform. Other APIs supporting the same "play and forget" model as the Windows MIDI Streams API need to be supported before PMIDI can work on other platforms.
• Sequences are limited to 64 KB of data. The underlying Windows MIDI Streams API cannot buffer sequences larger than this.
• The code is not fully documented.

The latest version of PMIDI is available for download from SourceForge at http://sourceforge.net/projects/uncassist. Peter Parente, the author of PMIDI, can be contacted by email at parente@cs.unc.edu.

 Py is committed to bringing you great Python Articles.