Library Reference

Creating Message and Opening Ports

mido.open_input(name=None)

Open an input port.

mido.open_output(name=None)

Open an output port.

mido.open_ioport(name=None)

Open a port for input and output.

mido.get_input_names()

Return a sorted list of all input port names.

These names can be passed to Input().

mido.get_output_names()

Return a sorted list of all input port names.

These names can be passed to Output().

mido.get_ioport_names()

Return the names of all ports that allow input and output.

Parsing and Parser class

mido.parse(data)

Parse MIDI data and return the first message found.

Data after the first message is ignored. Use parse_all() to parse more than one message.

mido.parse_all(data)

Parse MIDI data and return a list of all messages found.

This is typically used to parse a little bit of data with a few messages in it. It’s best to use a Parser object for larger amounts of data. Also, tt’s often easier to use parse() if you know there is only one message in the data.

class mido.Parser

MIDI Parser

Parses a stream of bytes and produces messages.

Data can be put into the parser in the form of integers, byte arrays or byte strings.

feed(data)

Feed MIDI data to the parser.

Accepts any object that produces a sequence of integers in range 0..255, such as:

[0, 1, 2] (0, 1, 2) [for i in range(256)] (for i in range(256)] bytearray() b’’ # Will be converted to integers in Python 2.

feed_byte(byte)

Feed one MIDI byte into the parser.

The byte must be an integer in range 0..255.

get_message()

Get the first parsed message.

Returns None if there is no message yet. If you don’t want to deal with None, you can use pending() to see how many messages you can get before you get None.

pending()

Return the number of pending messages.

Message Objects

class mido.Message(type_, **parameters)

MIDI message class.

bin()

Encode message and return as a bytearray.

This can be used to write the message to a file.

bytes()

Encode message and return as a list of integers.

copy(**overrides)

Return a copy of the message.

Attributes will be overriden by the passed keyword arguments. Only message specific attributes can be overridden. The message type can not be changed.

Example:

a = Message(‘note_on’) b = a.copy(velocity=32)

hex(sep=' ')

Encode message and return as a string of hex numbers,

Each number is separated by the string sep.

String Serialization

There is not format_as_string(), but you can use str(message).

mido.parse_string(text)

Parse a string of text and return a message.

The string can span multiple lines, but must contain one full message.

Raises ValueError if the string could not be parsed.

mido.parse_string_stream(stream)

Parse a stram of messages and yield (message, error_message)

stream can be any iterable that generates text strings. If a line can be parsed, (message, None) is returned. If it can’t be parsed (None, error_message) is returned. The error message containes the line number where the error occured.

Ports

class mido.ports.BaseInput(name=None)

Base class for input port.

Override _pending() to create a new input port type. (See portmidi.py for an example of how to do this.)

close()

Close the port.

If the port is already closed, nothing will happen. The port is automatically closed when the object goes out of scope or is garbage collected.

iter_pending()

Iterate through pending messages.

pending()

Return how many messages are ready to be received.

This can be used for non-blocking receive(), for example:

for _ in range(port.pending()):

message = port.receive()

If this is called on a closed port, it will work as if the port was opened, but no new messages will be returned once the buffered ones run out.

receive()

Return the next message.

This will block until a message arrives. For non-blocking behavior, you can use pending() to see how many messages can safely be received without blocking.

NOTE: Blocking is currently implemented with polling and time.sleep(). This is inefficient, but the proper way doesn’t work yet, so it’s better than nothing.

Todo: What should happen when the port is closed? - raise exception? - return pending messages until we run out, then raise exception?

class mido.ports.BaseOutput(name=None)

Base class for output port.

Subclass and override _send() to create a new port type. (See portmidi.py for how to do this.)

close()

Close the port.

If the port is already closed, nothing will happen. The port is automatically closed when the object goes out of scope or is garbage collected.

send(message)

Send a message on the port.

The message is sent immediately.

class mido.ports.IOPort(input, output)

Input / output port.

This is a convenient wrapper around an input port and an output port which provides the functionality of both. Every method call is forwarded to the appropriate port.

close()

Close the port.

If the port is already closed, nothing will happen. The port is automatically closed when the object goes out of scope or is garbage collected.

iter_pending()

Iterate through pending messages.

pending()

Return how many messages are ready to be received.

This can be used for non-blocking receive(), for example:

for _ in range(port.pending()):

message = port.receive()

If this is called on a closed port, it will work as if the port was opened, but no new messages will be returned once the buffered ones run out.

receive()

Return the next message.

This will block until a message arrives. For non-blocking behavior, you can use pending() to see how many messages can safely be received without blocking.

NOTE: Blocking is currently implemented with polling and time.sleep(). This is inefficient, but the proper way doesn’t work yet, so it’s better than nothing.

Todo: What should happen when the port is closed? - raise exception? - return pending messages until we run out, then raise exception?

send(message)

Send a message on the port.

The message is sent immediately.

mido.ports.multi_receive(ports)

Receive messages from multiple ports.

Generates (message, port) tuples from every port in ports. The ports are polled in random order for fairness, and all messages from each port are yielded before moving on to the next port.

mido.ports.multi_iter_pending(ports)

Iterate through all pending messages in ports.

ports is an iterable of message ports to check.

Yields (message, port) tuples until there are no more pending messages. This can be used to receive messages from a set of ports in a non-blocking manner.