MidiIn

MIDI devices (e.g., a MIDI guitar, keyboard, or control surface) generate MIDI messages when played.  If you connect them to your computer (via cable), you can use a MidiIn object to read these messages into your program.

First, you need to import the MIDI library:

from midi import *

Then, you can create a MidiIn object using this function:

Function Description
MidiIn() Creates a new MidiIn object to connect to an input MIDI device.  When called, it shows a GUI display to select one from the available input MIDI devices.

For example,

m = MidiIn()

creates a MidiIn object called m.  When executed, a display will open up to select an input MIDI device.

MidiIn objects may also be created with a specific device in mind:

Function Description
MidiIn( device ) Creates a new MidiIn object to connect to device (a string). If device is not available, a display will appear to select one from the available input MIDI devices.

For example,

m = MidiIn("AKAI MPKmini2")

creates a connection to an AKAI MPKmini2 MIDI controller directly (i.e., no selection display is shown – faster, if you already know the name of the device).

Once m has been created, the following functions are available:

Function Description
m.onNoteOn( function ) When a note is played on the MIDI device connected to m, a NOTE_ON message is sent.

This allows you to specify a function to be called every time a NOTE_ON message arrives. This function should expect four parameters, eventType, channel, data1, data2.

For NOTE_ON events, eventType is always 144, channel ranges from 0 to 15, data1 is the note pitch (0-127), and data2 is the volume of the note (0-127).
m.onNoteOff( function ) When a playing note is stopped on the MIDI device connected to m, a NOTE_OFF message is sent.

This allows you to specify a function to be called every time a NOTE_OFF message arrives. This function should expect four parameters, eventType, channel, data1, data2.

For NOTE_OFF events, eventType is always 128, channel ranges from 0 to 15, data1 is the note pitch (0-127), and data2 is ignored.
m.onSetInstrument( function ) When a SET_INSTRUMENT (also known as CHANGE_PROGRAM) event happens on the m device (i.e., the user selects a different timbre), the system calls the provided function.

This function should expect four parameters, eventType, channel, data1, data2.

For SET_INSTRUMENT events, eventType is always 192, channel ranges from 0 to 15, data1 is the new MIDI instrument (0-127), and data2 is ignored.
m.onInput( eventType, function ) Associates an incoming eventType with a callback function.  When the specified eventType event happens on the m device, the system calls the provided function.

This function should expect four parameters, eventType, channel, data1, data2.

Can be used repeatedly to associate different event types (128-224) with different callback functions (one function per event type).

If eventType is ALL_EVENTS, then function will be called for all incoming events that have not yet been assigned callback functions.
m.showMessages() Prints out incoming MIDI messages. This is the default. Used to explore what MIDI messages are generated by the m device, so that they can be associated with callback functions.
m.hideMessages() Stops printing out incoming MIDI messages.