Meta Message Types

Supported Messages

sequence_number (0x00)

Attribute Values Default
number 0..65535 0

Sequence number in type 0 and 1 MIDI files; pattern number in type 2 MIDI files.

text (0x01)

Attribute Values Default
text string ‘’

General “Text” Meta Message. Can be used for any text based data.

track_name (0x03)

Attribute Values Default
name string ‘’

Stores a MIDI track’s name.

instrument_name (0x04)

Attribute Values Default
name string ‘’

Stores an instrument’s name.

lyrics (0x05)

Attribute Values Default
text string ‘’

Stores the lyrics of a song. Typically one syllable per Meta Message.

marker (0x06)

Attribute Values Default
text string ‘’

Marks a point of interest in a MIDI file. Can be used as the marker for the beginning of a verse, solo, etc.

cue_marker (0x07)

Attribute Values Default
text string ‘’

Marks a cue. IE: ‘Cue performer 1’, etc

device_name (0x09)

Attribute Values Default
name string ‘’

Gives the name of the device.

channel_prefix (0x20)

Attribute Values Default
channel 0..255 0

Gives the prefix for the channel on which events are played.

midi_port (0x21)

Attribute Values Default
port 0..255 0

Gives the MIDI Port on which events are played.

end_of_track (0x2f)

Attribute Values Default
n/a n/a n/a

An empty Meta Message that marks the end of a track.

set_tempo (0x51)

Attribute Values Default
tempo 0..16777215 500000

Tempo is in microseconds per beat (quarter note). You can use bpm2tempo() and tempo2bpm() to convert to and from beats per minute. Note that tempo2bpm() may return a floating point number.

smpte_offset (0x54)

Attribute Values Default
frame_rate 24, 25, 29.97, 30 24
hours 0..255 0
minutes 0..59 0
seconds 0..59 0
frames 0..255 0
sub_frames 0..99 0

time_signature (0x58)

Attribute Values Default
numerator 0..255 4
denominator 1..2**255 4
clocks_per_click 0..255 24
notated_32nd_notes_per_beat 0..255 8

Time signature of:

4/4 : MetaMessage(‘time_signature’, numerator=4, denominator=4)

3/8 : MetaMessage(‘time_signature’, numerator=3, denominator=8)

Note

From 1.2.9 time signature message have the correct default value of 4/4. In earlier versions the default value was 2/4 due to a typo in the code.

key_signature (0x59)

Attribute Values Default
key ‘C’, ‘F#m’, … ‘C’

Valid values: A A#m Ab Abm Am B Bb Bbm Bm C C# C#m Cb Cm D D#m Db Dm E Eb Ebm Em F F# F#m Fm G G#m Gb Gm

Note: the mode attribute was removed in 1.1.5. Instead, an ‘m’ is appended to minor keys.

sequencer_specific (0x7f)

Attribute Values Default
data [..] []

An unprocessed sequencer specific message containing raw data.

Unknown Meta Messages

Unknown meta messages will be returned as UnknownMetaMessage objects, with type set to unknown_meta. The messages are saved back to the file exactly as they came out.

Code that depends on UnknownMetaMessage may break if the message in question is ever implemented, so it’s best to only use these to learn about the format of the new message and then implement it as described below.

UnknownMetaMessage have two attributes:

``type_byte`` - a byte which uniquely identifies this message type
``data`` - the message data as a list of bytes

These are also visible in the repr() string:

UnknownMetaMessage(type_byte=251, data=(1, 2, 3), time=0>

Implementing New Meta Messages

If you come across a meta message which is not implemented, or you want to use a custom meta message, you can add it by writing a new meta message spec:

from mido.midifiles.meta import MetaSpec, add_meta_spec

class MetaSpec_light_color(MetaSpec):
    type_byte = 0xf0
    attributes = ['r', 'g', 'b']
    defaults = [0, 0, 0]

def decode(self, message, data):
    # Interpret the data bytes and assign them to attributes.
    (message.r, message.g, message.b) = data

def encode(self, message):
    # Encode attributes to data bytes and
    # return them as a list of ints.
    return [message.r, message.g, message.b]

def check(self, name, value):
    # (Optional)
    # This is called when the user assigns
    # to an attribute. You can use this for
    # type and value checking. (Name checking
    # is already done.
    #
    # If this method is left out, no type and
    # value checking will be done.

    if not isinstance(value, int):
        raise TypeError('{} must be an integer'.format(name))

    if not 0 <= value <= 255:
        raise TypeError('{} must be in range 0..255'.format(name))

Then you can add your new message type with:

add_meta_spec(MetaSpec_light_color)

and create messages in the usual way:

>>> from mido import MetaMessage
>>> MetaMessage('light_color', r=120, g=60, b=10)
MetaMessage('light_color', r=120, g=60, b=10, time=0)

and the new message type will now work when reading and writing MIDI files.

Some additional functions are available:

encode_string(unicode_string)
decode_string(byte_list)

These convert between a Unicode string and a list of bytes using the current character set in the file.

If your message contains only one string with the attribute name text or name, you can subclass from one of the existing messages with these attributes, for example:

class MetaSpec_copyright(MetaSpec_text):
    type_byte = 0x02

class MetaSpec_instrument_name(MetaSpec_track_name):
    type_byte = 0x04

This allows you to skip everything but type_byte, since the rest is inherited.

See the existing MetaSpec classes for further examples.