Important Note: This documenation is old and outdated. I'm leaving it here to prevent broken links and because the original project hosting page at Google was shut down when code.google.com was shut down.

The code base has been moved to GitHub and is accessible here.

The current documentation can be foud at Read The Docs. (Documentation for the development version is here.)

Introduction

MIDIUtil is a pure Python library that allows one to write muti-track Musical Instrument Digital Interface (MIDI) files from within Python programs. It is object-oriented and allows one to create and write these files with a minimum of fuss.

MIDIUtil isn't a full implementation of the MIDI specification. The actual specification is a large, sprawling document which has organically grown over the course of decades. I have selectively implemented some of the more useful and common aspects of the specification. The choices have been somewhat idiosyncratic; I largely implemented what I needed. When I decided that it could be of use to other people I fleshed it out a bit, but there are still things missing. Regardless, the code is fairly easy to understand and well structured. Additions can be made to the library by anyone with a good working knowledge of the MIDI file format and a good, working knowledge of Python. Documentation for extending the library is provided.

This software was originally developed with Python 2.5.2 and it makes use of some features that were introduced in 2.5. I have used it extensively in Python 2.6.

[Note to Python 3 users: An initial port to Python 3 had been made and committed to the development branch of the code (which is available via svn). The source file is called MidiFile3.py. To use it, change your import statement to read:

from midiutil.MidiFile3 import MIDIFile

This version will also work with Python 2.6.X, but is incompatible with Python 2.5.X.]

This software is distributed under an Open Source license and you are free to use it as you see fit, provided that attribution is maintained. See License.txt in the source distribution for details.

Installation

To use the library one can either install it on one's system or copy the midiutil directory of the source distribution to your project's directory (or to any directory pointed to by the PYTHONPATH environment variable). For the Windows platforms an executable installer is provided. Alternately the source distribution can be downloaded, un-zipped (or un-tarred), and installed in the standard way:

python setup.py install

On non-Windows platforms (Linux, MacOS, etc.) the software should be installed in this way. MIDIUtil is pure Python and should work on any platform to which Python has been ported.

If you do not wish to install in on your system, just copy the src/midiutil directory to your project's directory or elsewhere on your PYTHONPATH. If you're using this software in your own projects you may want to consider distributing the library bundled with yours; the library is small and self-contained, and such bundling makes things more convenient for your users. The best way of doing this is probably to copy the midiutil directory directly to your package directory and then refer to it with a fully qualified name. This will prevent it from conflicting with any version of the software that may be installed on the target system.

Quick Start

Using the software is easy:

The package must be imported into your namespace
A MIDIFile object is created
Events (notes, tempo-changes, etc.) are added to the object
The MIDI file is written to disk.

Detailed documentation is provided; what follows is a simple example to get you going quickly. In this example we'll create a one track MIDI File, assign a name and tempo to the track, add a one beat middle-C to the track, and write it to disk.

#Import the library

from midiutil.MidiFile import MIDIFile

# Create the MIDIFile Object with 1 track

MyMIDI = MIDIFile(1)

# Tracks are numbered from zero. Times are measured in beats.

track = 0

time = 0

# Add track name and tempo.

MyMIDI.addTrackName(track,time,"Sample Track")

MyMIDI.addTempo(track,time,120)

# Add a note. addNote expects the following information:

track = 0

channel = 0

pitch = 60

time = 0

duration = 1

volume = 100

# Now add the note.

MyMIDI.addNote(track,channel,pitch,time,duration,volume)

# And write it to disk.

binfile = open("output.mid", 'wb')

MyMIDI.writeFile(binfile)

binfile.close()

There are several additional event types that can be added and there are various options available for creating the MIDIFile object, but the above is sufficient to begin using the library and creating note sequences.

Documentation

Download

The software is hosted at Google Code. A Windows installer and zipped source distributions are available. [Note: the Windows installer has not been uploaded yet.] Please visit the project home page for the packages.

If you are using Subversion you can access the development source repository directly with the following command:

svn checkout http://midiutil.googlecode.com/svn/trunk/ midiutil-read-only

Unless there is a feature in the development branch that you need, you are encouraged to use the most recent released version. While every effort is made to make sure the development branch is working and stable, errors can be introduced in development that could adversely affect the quality and stability of the code. Also note that unless I receive requests for extensions and features, the library is probably more or less "done" (insofar as software can ever be complete), so there will be little work done in the development branch.