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)

New in version 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

Changed in version 1.1.5: The mode attribute was removed. 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 or Custom 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.