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:
Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
- 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
ormidi_out
must be set or both together.- Parameters:
midi_in – an object which implements
read(length)
, set tousb_midi.ports[0]
for USB MIDI, default None.midi_out – an object which implements
write(buffer, length)
, set tousb_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 anint
for the wire protocol channel number (0-15) a tuple ofint
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.
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:
- 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:
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:
Frame count LS nibble
Frame count MS nibble
Seconds count LS nibble
Seconds count MS nibble
Minutes count LS nibble
Minutes count MS nibble
Hours count LS nibble
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 astr
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 astr
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 astr
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:
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.