Objects and tools for processing MIDI data.
This module uses routines from Will Ware’s public domain midi.py from 2001 see http://groups.google.com/group/alt.sources/msg/0c5fc523e050c35e
Convert a char into its binary representation. Useful for debugging.
>>> from music21 import *
>>> midi.charToBinary('a')
'01100001'
Return the value of a string byte from and 8-bit string. Then, return the remaining string.
The length is the number of chars to read.
This will sum a length greater than 1 if desired.
>>> from music21 import *
>>> midi.getNumber('test', 0)
(0, 'test')
>>> midi.getNumber('test', 2)
(29797, 'st')
>>> midi.getNumber('test', 4)
(1952805748, '')
Translate each char into a number, return in a list. Used for reading data messages where each byte encodes a different discrete value.
>>> from music21 import *
>>> midi.getNumbersAsList('\x00\x00\x00\x03')
[0, 0, 0, 3]
Given a string of data, strip off a number that might be of variable size; after finding the appropriate termination, return the remaining string.
This necessary as Delta times are given with variable size, and thus may be if different numbers of characters.
>>> from music21 import *
>>> midi.getVariableLengthNumber('A-u')
(65, '-u')
>>> midi.getVariableLengthNumber('-u')
(45, 'u')
>>> midi.getVariableLengthNumber('u')
(117, '')
>>> midi.getVariableLengthNumber('test')
(116, 'est')
>>> midi.getVariableLengthNumber('E@-E')
(69, '@-E')
>>> midi.getVariableLengthNumber('@-E')
(64, '-E')
>>> midi.getVariableLengthNumber('-E')
(45, 'E')
>>> midi.getVariableLengthNumber('E')
(69, '')
>>> midi.getVariableLengthNumber('\xff\x7f')
(16383, '')
Convert a list of integers into a hex string, suitable for testing MIDI encoding.
>>> from music21 import *
>>> # note on, middle c, 120 velocity
>>> midi.intsToHexString([144, 60, 120])
'\x90<x'
>>> from music21 import *
>>> midi.putNumber(3, 4)
'\x00\x00\x00\x03'
>>> midi.putNumber(0, 1)
'\x00'
Translate a list of numbers into a character byte strings. Used for encoding data messages where each byte encodes a different discrete value.
>>> from music21 import *
>>> midi.putNumbersAsList([0, 0, 0, 3])
'\x00\x00\x00\x03'
>>> midi.putNumbersAsList([0, 0, 0, -3])
'\x00\x00\x00\xfd'
>>> midi.putNumbersAsList([0, 0, 0, -1])
'\x00\x00\x00\xff'
>>> from music21 import *
>>> midi.putVariableLengthNumber(4)
'\x04'
>>> midi.putVariableLengthNumber(127)
'\x7f'
>>> midi.putVariableLengthNumber(0)
'\x00'
>>> midi.putVariableLengthNumber(1024)
'\x88\x00'
>>> midi.putVariableLengthNumber(8192)
'\xc0\x00'
>>> midi.putVariableLengthNumber(16383)
'\xff\x7f'
>>> midi.putVariableLengthNumber(-1)
Traceback (most recent call last):
MidiException: cannot putVariableLengthNumber() when number is negative: -1
Inherits from: MidiEvent
Store the time change since the start or the last MidiEvent.
Pairs of DeltaTime and MidiEvent objects are the basic presentation of temporal data.
The track argument must be a MidiTrack object.
Time values are in integers, representing ticks.
The channel attribute, inherited from MidiEvent is not used.
>>> from music21 import *
>>> mt = midi.MidiTrack(1)
>>> dt = midi.DeltaTime(mt)
>>> dt.time = 380
>>> dt
<MidiEvent DeltaTime, t=380, track=1, channel=None>
DeltaTime properties
DeltaTime methods
- read(oldstr)¶
No documentation.
- write()¶
No documentation.
Methods inherited from MidiEvent: isDeltaTime(), isNoteOff(), isNoteOn(), matchedNoteOff(), setPitchBend(), updateSortOrder()
Utility object for defining binary MIDI message constants.
Enumeration methods
A model of a MIDI event, including note-on, note-off, program change, controller change, any many others.
MidiEvent objects are paired (preceded) by DeltaTime objects in the list of events in a MidiTrack object.
The track argument must be a MidiTrack object.
The type attribute is a string representation of a Midi event from the channelVoiceMessages or metaEvents definitions.
The channel attribute is an integer channel id, from 1 to 16.
The time attribute is an integer duration of the event in ticks. This value can be zero. This value is not essential, as ultimate time positioning is determined by DeltaTime objects.
The pitch attribute is only defined for note-on and note-off messages. The attribute stores an integer representation (0-127).
The velocity attribute is only defined for note-on and note-off messages. The attribute stores an integer representation (0-127).
The data attribute is used for storing other messages, such as SEQUENCE_TRACK_NAME string values.
>>> from music21 import *
>>> mt = midi.MidiTrack(1)
>>> me1 = midi.MidiEvent(mt)
>>> me1.type = "NOTE_ON"
>>> me1.channel = 1
>>> me1.time = 200
>>> me1.pitch = 60
>>> me1.velocity = 120
>>> me1
<MidiEvent NOTE_ON, t=200, track=1, channel=1, pitch=60, velocity=120>
>>> me2 = midi.MidiEvent(mt)
>>> me2.type = "SEQUENCE_TRACK_NAME"
>>> me2.time = 0
>>> me2.data = 'guitar'
>>> me2
<MidiEvent SEQUENCE_TRACK_NAME, t=0, track=1, channel=None, data='guitar'>
MidiEvent properties
MidiEvent methods
- isDeltaTime()¶
Return a boolean if this is a note-on message and velocity is not zero.
>>> from music21 import * >>> mt = midi.MidiTrack(1) >>> dt = midi.DeltaTime(mt) >>> dt.isDeltaTime() True
- isNoteOff()¶
Return a boolean if this is a note-off message, either as a note-off or as a note-on with zero velocity.
>>> from music21 import * >>> mt = midi.MidiTrack(1) >>> me1 = midi.MidiEvent(mt) >>> me1.type = "NOTE_OFF" >>> me1.isNoteOn() False >>> me1.isNoteOff() True >>> me2 = midi.MidiEvent(mt) >>> me2.type = "NOTE_ON" >>> me2.velocity = 0 >>> me2.isNoteOn() False >>> me2.isNoteOff() True
- isNoteOn()¶
Return a boolean if this is a note-on message and velocity is not zero.
>>> from music21 import * >>> mt = midi.MidiTrack(1) >>> me1 = midi.MidiEvent(mt) >>> me1.type = "NOTE_ON" >>> me1.velocity = 120 >>> me1.isNoteOn() True >>> me1.isNoteOff() False
- matchedNoteOff(other)¶
If this is a note-on, given another MIDI event, is this a matching note-off for this event, return True. Checks both pitch and channel.
>>> from music21 import * >>> mt = midi.MidiTrack(1) >>> me1 = midi.MidiEvent(mt) >>> me1.type = "NOTE_ON" >>> me1.velocity = 120 >>> me1.pitch = 60 >>> me2 = midi.MidiEvent(mt) >>> me2.type = "NOTE_ON" >>> me2.velocity = 0 >>> me2.pitch = 60>>> me1.matchedNoteOff(me2) True >>> me2.pitch = 61 >>> me1.matchedNoteOff(me2) False>>> me2.type = "NOTE_OFF" >>> me1.matchedNoteOff(me2) False >>> me2.pitch = 60 >>> me1.matchedNoteOff(me2) True
- read(time, str)¶
Read a MIDI event.
The time value is the number of ticks into the Track at which this event happens. This is derived from reading data the level of the track.
>>> # all note-on messages (144-159) can be found >>> 145 & 0xF0 # testing message type extraction 144 >>> 146 & 0xF0 # testing message type extraction 144 >>> (144 & 0x0F) + 1 # getting the channel 1 >>> (159 & 0x0F) + 1 # getting the channel 16
- setPitchBend(cents, bendRange=2)¶
Treat this event as a pitch bend value, and set the ._parameter1 and ._parameter2 fields appropriately given a specified bend value in cents.
The bendRange parameter gives the number of half steps in the bend range.
>>> from music21 import * >>> mt = midi.MidiTrack(1) >>> me1 = midi.MidiEvent(mt) >>> me1.setPitchBend(50) >>> me1._parameter1, me1._parameter2 (0, 80) >>> me1.setPitchBend(100) >>> me1._parameter1, me1._parameter2 (0, 96) >>> me1.setPitchBend(200) >>> me1._parameter1, me1._parameter2 (127, 127) >>> me1.setPitchBend(-50) >>> me1._parameter1, me1._parameter2 (0, 48) >>> me1.setPitchBend(-100) >>> me1._parameter1, me1._parameter2 (0, 32)
- updateSortOrder()¶
No documentation.
- write()¶
Write out a midi track.
Low-level MIDI file writing, emulating methods from normal Python files.
The ticksPerQuarterNote attribute must be set before writing. 1024 is a common value.
This object is returned by some properties for directly writing files of midi representations.
MidiFile attributes
Attributes without Documentation: ticksPerSecond, tracks, ticksPerQuarterNote, file, format
MidiFile methods
- close()¶
Close the file.
- open(filename, attrib='rb')¶
Open a MIDI file path for reading or writing.
For writing to a MIDI file, attrib should be “wb”.
- openFileLike(fileLike)¶
Assign a file-like object, such as those provided by StringIO, as an open file object.
>>> import StringIO >>> from music21 import * >>> fileLikeOpen = StringIO.StringIO() >>> mf = midi.MidiFile() >>> mf.openFileLike(fileLikeOpen) >>> mf.close()
- read()¶
Read and parse MIDI data stored in a file.
- readstr(str)¶
Read and parse MIDI data as a string.
- write()¶
Write MIDI data as a file.
- writestr()¶
Return MIDI data as a string.
A MIDI Track. Each track contains a list of MidiChannel objects, one for each channel.
All events are stored in the events list, in order.
An index is an integer identifier for this object.
>>> from music21 import *
>>> mt = midi.MidiTrack(0)
MidiTrack methods
- getChannels()¶
Get all channels used in this Track.
- getProgramChanges()¶
Get all unique program changes used in this Track, sorted.
- hasNotes()¶
Return True/False if this track has any note-on/note-off pairs defined.
- read(str)¶
Read as much of the string as necessary; return the remaining string for reassignment and further processing.
- setChannel(value)¶
Set the channel of all events in this Track.
- updateEvents()¶
We may attach events to this track before setting their track parameter. This method will move through all events and set their track to this track.
- write()¶
No documentation.