adafruit_midi

A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.

  • Author(s): Limor Fried, Kevin J. Walters

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_midi.MIDI(midi_in=None, midi_out=None, *, in_channel=None, out_channel=0, in_buf_size=30, debug=False)

MIDI helper class. midi_in or midi_out must be set or both together.

Parameters:

  • midi_in – an object which implements read(length), set to usb_midi.ports[0] for USB MIDI, default None.

  • midi_out – an object which implements write(buffer, length), set to usb_midi.ports[1] for USB MIDI, default None.

  • in_channel – The input channel(s). This is used by receive to filter data. This can either be an int for the wire protocol channel number (0-15) a tuple of int to listen for multiple channels. Defaults to all channels.

  • out_channel (int) – The wire protocol output channel number (0-15) used by send if no channel is specified, defaults to 0 (MIDI Channel 1).

  • in_buf_size (int) – Maximum size of input buffer in bytes, default 30.

  • debug (bool) – Debug mode, default False.

property in_channel

The incoming MIDI channel. Must be 0-15. Correlates to MIDI channels 1-16, e.g. in_channel = 3 will listen on MIDI channel 4. Can also listen on multiple channels, e.g. in_channel  = (0,1,2) will listen on MIDI channels 1-3. Default is all channels.

property out_channel

The outgoing MIDI channel. Must be 0-15. Correlates to MIDI channels 1-16, e.g. out_channel = 3 will send to MIDI channel 4. Default is 0 (MIDI channel 1).

receive()

Read messages from MIDI port, store them in internal read buffer, then parse that data and return the first MIDI message (event). This maintains the blocking characteristics of the midi_in port.

Returns MIDIMessage object:

Returns object or None for nothing.

send(msg, channel=None)

Sends a MIDI message.

Parameters:

  • msg – Either a MIDIMessage object or a sequence (list) of MIDIMessage objects. The channel property will be updated as a side-effect of sending message(s).

  • channel (int) – Channel number, if not set the out_channel will be used.

adafruit_midi.channel_pressure

Channel Pressure MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.channel_pressure.ChannelPressure(pressure, *, channel=None)

Channel Pressure MIDI message.

Parameters:

pressure (int) – The pressure, 0-127.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

adafruit_midi.control_change

Control Change MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.control_change.ControlChange(control, value, *, channel=None)

Control Change MIDI message.

Parameters:

  • control (int) – The control number, 0-127.

  • value (int) – The 7bit value of the control, 0-127.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

adafruit_midi.control_change_values

Definition for standard MIDI control change values.

  • Author(s): Mark Komus

Implementation Notes

adafruit_midi.midi_continue

Continue MIDI message.

  • Author(s): Mark Komus

Implementation Notes

class adafruit_midi.midi_continue.Continue(*, channel=None)

Continue MIDI message.

adafruit_midi.midi_message

An abstract class for objects which represent MIDI messages (events). When individual messages are imported they register themselves with :func:register_message_type which makes them recognised by the parser, :func:from_message_bytes.

Large messages like :class:SystemExclusive can only be parsed if they fit within the input buffer in :class:MIDI.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.midi_message.MIDIBadEvent(msg_bytes, exception)

A bad MIDI message, one that could not be parsed/constructed.

Parameters:

  • msg_bytes (list) – The MIDI status including any embedded channel number and associated subsequent data bytes.

  • exception (Exception) – The exception used to store the repr() text representation.

This could be due to status bytes appearing where data bytes are expected. The channel property will not be set.

class adafruit_midi.midi_message.MIDIMessage(*, channel=None)

The parent class for MIDI messages.

Class variables:

  • _STATUS - extracted from status byte with channel replaced by 0s (high bit is always set by convention).

  • _STATUSMASK - mask used to compared a status byte with _STATUS value.

  • LENGTH - length for a fixed size message including status or -1 for variable length.

  • CHANNELMASK - mask used to apply a (wire protocol) channel number.

  • ENDSTATUS - the end of message status byte, only set for variable length.

This is an abstract class.

property channel

The channel number of the MIDI message where appropriate. This is updated by MIDI.send() method.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

classmethod from_message_bytes(midibytes, channel_in)

Create an appropriate object of the correct class for the first message found in some MIDI bytes filtered by channel_in.

Returns (messageobject, endplusone, skipped) or for no messages, partial messages or messages for other channels (None, endplusone, skipped).

classmethod register_message_type()

Register a new message by its status value and mask. This is called automagically at import time for each message.

class adafruit_midi.midi_message.MIDIUnknownEvent(status)

An unknown MIDI message.

Parameters:

status (int) – The MIDI status number.

This can either occur because there is no class representing the message or because it is not imported.

adafruit_midi.midi_message.channel_filter(channel, channel_spec)

Utility function to return True iff the given channel matches channel_spec.

adafruit_midi.midi_message.note_parser(note)

If note is a string then it will be parsed and converted to a MIDI note (key) number, e.g. “C4” will return 60, “C#4” will return 61. If note is not a string it will simply be returned.

Parameters:

note – Either 0-127 int or a str representing the note, e.g. “C#4”

adafruit_midi.mtc_quarter_frame

MIDI Time Code (MTC) Quarter Frame message.

  • Author(s): Raphaël Doursenaud

Implementation Notes

Based upon the official MMA0001 / RP004 / RP008 v4.2.1 MIDI Time Code Specification

class adafruit_midi.mtc_quarter_frame.MtcQuarterFrame(msgtype, value)

MIDI Time Code (MTC) Quarter Frame message.

Parameters:

  • msgtype –

    The quarter frame message type:

    1. Frame count LS nibble

    2. Frame count MS nibble

    3. Seconds count LS nibble

    4. Seconds count MS nibble

    5. Minutes count LS nibble

    6. Minutes count MS nibble

    7. Hours count LS nibble

    8. Hours count MS nibble and SMPTE Type

  • value – The quarter frame value for the specified type.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

adafruit_midi.note_off

Note Off Change MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.note_off.NoteOff(note, velocity=0, *, channel=None)

Note Off Change MIDI message.

Parameters:

  • note – The note (key) number either as an int (0-127) or a str which is parsed, e.g. “C4” (middle C) is 60, “A4” is 69.

  • velocity (int) – The release velocity, 0-127, defaults to 0.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

note

Key, either int (0-127) or string that will be turned off

velocity

Release velocity, int (0-127)

adafruit_midi.note_on

Note On Change MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.note_on.NoteOn(note, velocity=127, *, channel=None)

Note On Change MIDI message.

Parameters:

  • note – The note (key) number either as an int (0-127) or a str which is parsed, e.g. “C4” (middle C) is 60, “A4” is 69.

  • velocity (int) – The strike velocity, 0-127, 0 is equivalent to a Note Off, defaults to 127.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

note

Key, either int (0-127) or string that will be turned on

velocity

Strike velocity, int (0-127); 0 is equivalent to Note Off

adafruit_midi.pitch_bend

Pitch Bend Change MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.pitch_bend.PitchBend(pitch_bend, *, channel=None)

Pitch Bend Change MIDI message.

Parameters:

pitch_bend (int) – A 14bit unsigned int representing the degree of bend from 0 through 8192 (midpoint, no bend) to 16383.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

adafruit_midi.polyphonic_key_pressure

Polyphonic Key Pressure MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.polyphonic_key_pressure.PolyphonicKeyPressure(note, pressure, *, channel=None)

Polyphonic Key Pressure MIDI message.

Parameters:

  • note – The note (key) number either as an int (0-127) or a str which is parsed, e.g. “C4” (middle C) is 60, “A4” is 69.

  • pressure (int) – The pressure, 0-127.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

adafruit_midi.program_change

Program Change MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.program_change.ProgramChange(patch, *, channel=None)

Program Change MIDI message.

Parameters:

patch (int) – The new program/patch number to use, 0-127.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

adafruit_midi.start

Start MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.start.Start(*, channel=None)

Start MIDI message.

adafruit_midi.stop

Stop MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.stop.Stop(*, channel=None)

Stop MIDI message.

adafruit_midi.system_exclusive

System Exclusive MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.system_exclusive.SystemExclusive(manufacturer_id, data)

System Exclusive MIDI message.

Parameters:

  • manufacturer_id (list) – The single byte or three byte manufacturer’s id as a list or bytearray of numbers between 0-127.

  • data (list) – The 7bit data as a list or bytearray of numbers between 0-127.

This message can only be parsed if it fits within the input buffer in :class:MIDI.

classmethod from_bytes(msg_bytes)

Creates an object from the byte stream of the wire protocol representation of the MIDI message.

adafruit_midi.timing_clock

Timing Clock MIDI message.

  • Author(s): Kevin J. Walters

Implementation Notes

class adafruit_midi.timing_clock.TimingClock(*, channel=None)

Timing Clock MIDI message.

This occurs 24 times per quarter note when synchronization is in use. If this is not needed it’s best to avoid this sending this high frequency message to a CircuitPython device to reduce the amount of message processing.