Class Reference¶

class midiutil.MidiFile.MIDIFile(numTracks=1, removeDuplicates=True, deinterleave=True, adjust_origin=None)¶

A class that encapsulates a full, well-formed MIDI file object.

This is a container object that contains a header (MIDIHeader), one or more tracks (class:MIDITrack), and the data associated with a proper and well-formed MIDI file.

addControllerEvent(track, channel, time, controller_number, parameter)¶

addControllerEvent(self, track, channel, time, controller_number, parameter)

Add a channel control event

Parameters:	track – The track to which the event is added. channel – the MIDI channel to assign to the event. [Integer, 0-15] time – The time (in beats) at which the event is placed [Float]. controller_number – The controller ID of the event. parameter – The event’s parameter, the meaning of which varies by event type.

addNote(track, channel, pitch, time, duration, volume, annotation=None)¶

addNote(self, track, channel, pitch, time, duration, volume, annotation=None)

Add notes to the MIDIFile object

Parameters:

track – The track to which the note is added.
channel – the MIDI channel to assign to the note. [Integer, 0-15]
pitch – the MIDI pitch number [Integer, 0-127].
time – the time (in beats) at which the note sounds [Float].
duration – the duration of the note (in beats) [Float].
volume – the volume (velocity) of the note. [Integer, 0-127].
annotation – Arbitrary data to attach to the note.

The annotation parameter attaches arbitrary data to the note. This is not used in the code, but can be useful anyway. As an example, I have created a project that uses MIDIFile to write csound orchestra files directly from the class EventList.

addProgramChange(track, channel, time, program)¶

addProgramChange(self, track, channel, time, program)

Add a MIDI program change event.

Parameters:	track – The track to which program change event is added. channel – the MIDI channel to assign to the event. [Integer, 0-15] time – The time (in beats) at which the program change event is placed [Float]. annotation – Arbitrary data to attach to the note. program – the program number. [Integer, 0-127].

addSysEx(track, time, manID, payload)¶

addSysEx(self, track, time, manID, payload)

Add a System Exclusive event.

Parameters:	track – The track to which the event should be written time – The time of the event. manID – The manufacturer ID for the event payload – The payload for the event. This should be a binary-packed value, and will vary for each type and function.

Note: This is a low-level MIDI function, so care must be used in constructing the payload. It is recommended that higher-level helper functions be written to wrap this function and construct the payload if a developer finds him or herself using the function heavily.

addTempo(track, time, tempo)¶

addTempo(self, track, time, tempo)

Add notes to the MIDIFile object

Parameters:	track – The track to which the tempo event is added. time – The time (in beats) at which tempo event is placed tempo – The tempo, in Beats per Minute. [Integer]

addTrackName(track, time, trackName)¶

addTrackName(self, track, time, trackName)

Name a track.

Parameters:	track – The track to which the name is assigned. time – The time (in beats) at which the track name event is placed. In general this should probably be time 0 (the beginning of the track). trackName – The name to assign to the track [String]

addUniversalSysEx(track, time, code, subcode, payload, sysExChannel=127, realTime=False)¶

addUniversalSysEx(self, track, time, code, subcode, payload, sysExChannel=0x7F, realTime=False)

Add a Univeral System Exclusive event.

Parameters:

track – The track to which the event should be written
time – The time of the event, in beats.
code – The event code. [Integer]
subcode – The event sub-code [Integer]
payload – The payload for the event. This should be a binary-packed value, and will vary for each type and function.
sysExChannel – The SysEx channel.
realTime – Sets the real-time flag. Defaults to non-real-time.
manID – The manufacturer ID for the event

Note: This is a low-level MIDI function, so care must be used in constructing the payload. It is recommended that higher-level helper functions be written to wrap this function and construct the payload if a developer finds him or herself using the function heavily. As an example of such a helper function, see the changeNoteTuning() function, which uses the event to create a real-time note tuning update.

changeNoteTuning(track, tunings, sysExChannel=127, realTime=True, tuningProgam=0)¶

changeNoteTuning(self, track, tunings, sysExChannel=0x7F, realTime=True, tuningProgam=0):

Add a real-time MIDI tuning standard update to a track.

Parameters:

track – The track to which the tuning is applied.
tunings – A list to tuples representing the tuning. See below for an explanation.
sysExChannel – The SysEx channel of the event. This is mapped to “manufacturer ID” in the event which is written. Unless there is a specific reason for changing it, it should be left at its default value.
realTime – Speicifes if the Universal SysEx event should be flagged as real-time or non-real-time. As with the sysExChannel argument, this should in general be left at it’s default value.
tuningProgram – The tuning program number.

This function specifically implements the “real time single note tuning change” (although the name is misleading, as multiple notes can be included in each event). It should be noted that not all hardware or software implements the MIDI tuning standard, and that which does often does not implement it in its entirety.

The tunings argument is a list of tuples, in (note number, frequency) format. As an example, if one wanted to change the frequency on MIDI note 69 to 500 (it is normally 440 Hz), one could do it thus:

from midiutil.MidiFile import MIDIFile
MyMIDI = MIDIFile(1)
tuning = [(69, 500)]
MyMIDI.changeNoteTuning(0, tuning, tuningProgam=0)

changeTuningBank(track, channel, time, bank)¶

changeTuningBank(self, track, channel, time, bank)

Change the tuning bank for a selected track

Parameters:	track – The track to which the data should be written channel – The channel for the events time – The time of the events bank – The tuning bank (0-127)

Note that this is a convenience function, as the same functionality is available from directly sequencing controller events.

The specified tuning should already have been written to the stream with changeNoteTuning.

changeTuningProgram(track, channel, time, program)¶

changeTuningProgram(self, track, channel, time, program)

Change the tuning program for a selected track

Parameters:	track – The track to which the data should be written channel – The channel for the events time – The time of the events program – The tuning program number (0-127)

Note that this is a convenience function, as the same functionality is available from directly sequencing controller events.

The specified tuning should already have been written to the stream with changeNoteTuning.

makeNRPNCall(track, channel, time, controller_msb, controller_lsb, data_msb, data_lsb)¶

makeNRPNCall(self, track, channel, time, controller_msb, controller_lsb, data_msb, data_lsb)

Perform a Non-Registered Parameter Number Call

Parameters:

track – The track to which this applies
channel – The channel to which this applies
time – The time of the event
controller_msb – The Most significant byte of the controller. In common usage this will usually be 0
controller_lsb – The least significant byte for the controller message. For example, for a fine-tunning change this would be 01.
data_msb – The most significant byte of the controller’s parameter.
data_lsb – The least significant byte of the controller’s parameter. If none is needed this should be set to None

makeRPNCall(track, channel, time, controller_msb, controller_lsb, data_msb, data_lsb)¶

makeRPNCall(self, track, channel, time, controller_msb, controller_lsb, data_msb, data_lsb)

Perform a Registered Parameter Number Call

Parameters:

track – The track to which this applies
channel – The channel to which this applies
time – The time of the event
controller_msb – The Most significant byte of the controller. In common usage this will usually be 0
controller_lsb – The Least significant Byte for the controller message. For example, for a fine-tuning change this would be 01.
data_msb – The Most Significant Byte of the controller’s parameter.
data_lsb – The Least Significant Byte of the controller’s parameter. If non needed this should be set to None

As an example, if one were to change a channel’s tuning program:

makeRPNCall(track, channel, time, 0, 3, 0, program)

(Note, however, that there is a convenience function, changeTuningProgram, that does this for you.)

writeFile(fileHandle)¶

writeFile(self, fileHandle)

Write the MIDI File.

Parameters:	fileHandle – A file handle that has been opened for binary writing.