usb_midi – MIDI over USB
The usb_midi module contains classes to transmit and receive MIDI messages over USB.
Available on these boards
- usb_midi.ports: Tuple[PortIn | PortOut, Ellipsis]
Tuple of all MIDI ports. Each item is ether
PortInorPortOut.
- usb_midi.disable() None
Disable presenting a USB MIDI device to the host. The device is normally enabled by default, but on some boards with limited endpoints including ESP32-S2 and certain STM boards, it is disabled by default. Can be called in
boot.py, before USB is connected.
- usb_midi.enable() None
Enable presenting a USB MIDI device to the host. The device is enabled by default, so you do not normally need to call this function. Can be called in
boot.py, before USB is connected.If you enable too many devices at once, you will run out of USB endpoints. The number of available endpoints varies by microcontroller. CircuitPython will go into safe mode after running boot.py to inform you if not enough endpoints are available.
- usb_midi.set_names(self, *, streaming_interface_name: str | None = None, audio_control_interface_name: str | None = None, in_jack_name: str | None = None, out_jack_name: str | None = None) None
Override the MIDI interface names in the USB Interface Descriptor.
- Parameters:
streaming_interface_name (Optional[str]) – an ASCII string (or buffer) of at most 126 characters, or
Noneto use the default name.audio_control_interface_name (Optional[str]) – an ASCII string (or buffer) of at most 126 characters, or
Noneto use the default name.in_jack_name (Optional[str]) – an ASCII string (or buffer) of at most 126 characters, or
Noneto use the default name.out_jack_name (Optional[str]) – an ASCII string (or buffer) of at most 126 characters, or
Noneto use the default name.
This method must be called in boot.py to have any effect.
Not available on boards without native USB support.
Warning
On Windows, if
audio_control_interface_nameis more than 31 characters long, Windows will not recognize the device. This issue is not present on macOS or Linux.
- class usb_midi.PortIn
Receives midi commands over USB
You cannot create an instance of
usb_midi.PortIn.PortIn objects are constructed for every corresponding entry in the USB descriptor and added to the
usb_midi.portstuple.- read(nbytes: int | None = None) bytes | None
Read characters. If
nbytesis specified then read at most that many bytes. Otherwise, read everything that arrives until the connection times out. Providing the number of bytes expected is highly recommended because it will be faster.- Returns:
Data read
- Return type:
bytes or None
- class usb_midi.PortOut
Sends midi messages to a computer over USB
You cannot create an instance of
usb_midi.PortOut.PortOut objects are constructed for every corresponding entry in the USB descriptor and added to the
usb_midi.portstuple.- write(buf: circuitpython_typing.ReadableBuffer) int | None
Write the buffer of bytes to the bus.
- Returns:
the number of bytes written
- Return type:
int or None