MIDI

Roles: device and host. TinyUSB has separate drivers for USB-MIDI 1.0 event packets and USB-MIDI 2.0 Universal MIDI Packets (UMP). Enable the driver that matches the data model used by the application.

MIDI 1.0 device

Enable CFG_TUD_MIDI, define CFG_TUD_MIDI_RX_BUFSIZE and CFG_TUD_MIDI_TX_BUFSIZE, and add TUD_MIDI_DESCRIPTOR.

Option

Default

What it controls

CFG_TUD_MIDI_RX_BUFSIZE / CFG_TUD_MIDI_TX_BUFSIZE

Required when enabled

Software FIFO bytes per interface. Define both, normally at least as large as the matching endpoint buffer.

CFG_TUD_MIDI_RX_EPSIZE / CFG_TUD_MIDI_TX_EPSIZE

Device bulk maximum

Endpoint transfer buffer bytes. Keep them at least the descriptor packet size, the _epsize argument of TUD_MIDI_DESCRIPTOR.

Use tud_midi_stream_read()/tud_midi_stream_write() for MIDI byte streams on the first interface (the write takes a cable number). Use tud_midi_n_* to select an interface, tud_midi_n_demux_stream_read() to separate received cables, and the *_packet_* APIs when the application already works with 4-byte USB-MIDI event packets. Drain received data in tud_midi_rx_cb().

API or callback

What it does

tud_midi_n_available() / tud_midi_n_stream_read()

Report the RX FIFO byte count plus the bytes left in a partially consumed packet, and read MIDI bytes for one interface. Both ignore cable_num: the read merges every cable.

tud_midi_n_demux_stream_read()

Reads bytes from one cable at a time, returns the byte count and writes the cable number to *p_cable_num. Do not mix it with the legacy stream reader on the same interface.

tud_midi_n_stream_write()

Packetizes a MIDI byte stream and returns the number of source bytes accepted.

tud_midi_n_packet_read_n() / tud_midi_n_packet_write_n()

Reads or writes complete 4-byte USB-MIDI event packets and returns a packet count.

tud_midi_rx_cb()

Announces received data. Drain the FIFO so later OUT transfers have room.

See MIDI Test.

MIDI 1.0 host

Set CFG_TUH_MIDI to the number of simultaneous MIDI streaming interfaces. The following options size each instance:

Option

Default

What it controls

CFG_TUH_MIDI_RX_BUFSIZE / CFG_TUH_MIDI_TX_BUFSIZE

Host bulk maximum

Software FIFO capacity for received and queued event packets.

CFG_TUH_MIDI_EP_BUFSIZE

Host bulk maximum

Endpoint transfer buffer size.

CFG_TUH_MIDI_STREAM_API

1

Enables byte-stream packetization/depacketization. Disable it to save code size when the application uses only raw 4-byte event packets.

tuh_midi_descriptor_cb() reports descriptor information before the interface is ready; begin I/O in tuh_midi_mount_cb(). Receive data in tuh_midi_rx_cb() with tuh_midi_stream_read() or tuh_midi_packet_read_n(). tuh_midi_stream_read() stops at a cable change, so call it in a loop until it returns zero; bytes left in the FIFO can block later bulk IN transfers. Writes remain buffered until an endpoint packet is ready or tuh_midi_write_flush() is called.

The RX and TX cable counts can differ. Query them with tuh_midi_get_rx_cable_count() and tuh_midi_get_tx_cable_count() before selecting a cable. See Host: MIDI Receive.

tuh_midi_read_available() reports raw FIFO bytes, while tuh_midi_stream_read() returns decoded MIDI stream bytes and a cable number. tuh_midi_packet_read_n() keeps the USB event-packet format. tuh_midi_write_flush() starts a short buffered transfer and returns the number of bytes submitted. Mount/unmount callbacks define the lifetime of the idx; RX/TX callbacks announce new input and newly available TX space.

MIDI 2.0 device

Enable CFG_TUD_MIDI2 and add TUD_MIDI2_DESCRIPTOR. The descriptor contains alternate setting 0 for USB-MIDI 1.0 fallback and alternate setting 1 for UMP, as required by the MIDI 2.0 class specification.

#define CFG_TUD_MIDI2            1
#define CFG_TUD_MIDI2_RX_BUFSIZE 256
#define CFG_TUD_MIDI2_TX_BUFSIZE 256

Option

Default

What it controls

CFG_TUD_MIDI2_RX_EPSIZE / CFG_TUD_MIDI2_TX_EPSIZE

Device bulk maximum

Endpoint transfer buffer bytes. Keep them at least the descriptor packet size, the _epsize argument of TUD_MIDI2_DESCRIPTOR.

CFG_TUD_MIDI2_RX_BUFSIZE / CFG_TUD_MIDI2_TX_BUFSIZE

Matching endpoint size

UMP FIFO bytes per interface.

CFG_TUD_MIDI2_NUM_GROUPS

1

Number of UMP groups exposed by the default Group Terminal Block.

CFG_TUD_MIDI2_EP_NAME / CFG_TUD_MIDI2_PRODUCT_ID

TinyUSB strings

Default endpoint name and product identifier returned by UMP discovery. Override tud_midi2_ep_name_cb() / tud_midi2_product_id_cb() for per-interface values.

CFG_TUD_MIDI2_FB_CI_VERSION / CFG_TUD_MIDI2_FB_SYSEX8_STREAMS

0

MIDI-CI version and SysEx8 stream count reported in Function Block Info.

CFG_TUD_MIDI2_BLOCK_STRIDX

0

Optional string-descriptor index (iBlockItem) for the default Group Terminal Block; zero means no string.

CFG_TUD_MIDI2_GTB_PROTOCOL

MIDI2_GTB_PROTOCOL_MIDI2

Default bMIDIProtocol for the built-in Group Terminal Block and TUD_MIDI2_GTB_BLOCK entries; TUD_MIDI2_GTB_BLOCK_PROTOCOL entries set their own.

On alternate setting 1, read and write arrays of 32-bit words with tud_midi2_ump_read() and tud_midi2_ump_write(). On alternate setting 0, use tud_midi2_packet_read() and tud_midi2_packet_write() for 4-byte USB-MIDI 1.0 event packets. Query tud_midi2_alt_setting(), tud_midi2_negotiated() and tud_midi2_protocol() when choosing the format to send; tud_midi2_mounted() reports whether the endpoints are open. tud_midi2_set_itf_cb() announces the active alternate setting so the application can switch its parser and producer.

tud_midi2_ump_read() returns only whole UMP messages: it stops before a message that does not fit in max_words or has not fully arrived, and returns zero on alternate setting 0. Pass at least 4 words, the largest UMP message, or a long message at the head of the FIFO is never read. Drain the RX FIFO completely in the callback:

void tud_midi2_rx_cb(uint8_t itf) {
  uint32_t count;
  if (tud_midi2_n_alt_setting(itf) == 1) {
    uint32_t words[16];
    while ((count = tud_midi2_n_ump_read(itf, words, 16)) != 0) {
      process_ump(words, count); // Track message size from each MT field.
    }
  } else {
    uint8_t packets[16 * 4];
    while ((count = tud_midi2_n_packet_read(itf, packets, 16)) != 0) {
      process_midi1(packets, count);
    }
  }
}

The driver handles standard UMP Stream discovery and protocol negotiation. At interface open and on selecting alternate setting 1, the protocol is initialized from the first Group Terminal Block: MIDI 1.0 for its MIDI1 values, otherwise MIDI 2.0. Stream negotiation may change it later. Override tud_midi2_gtb_desc_cb() to describe a custom Group Terminal Block topology, tud_midi2_fb_name_cb() for Function Block names and tud_midi2_device_identity_cb() to send a Device Identity Notification. Use tud_midi2_stream_msg_cb() only when the application must override a built-in Stream response.

tud_midi2_n_available(), tud_midi2_n_ump_read() and tud_midi2_n_ump_write() return 32-bit word counts. The packet APIs return counts of 4-byte MIDI 1.0 event packets.

See MIDI 2.0 Song Sender for alternate-setting and protocol fallback.

MIDI 2.0 host

Set CFG_TUH_MIDI2 to the required interface count. The host driver detects both alternate settings, selects the highest available protocol, and completes SET_INTERFACE before reporting the mount.

CFG_TUH_MIDI2_RX_BUFSIZE and CFG_TUH_MIDI2_TX_BUFSIZE default to the host bulk maximum and allocate FIFO storage per instance. Increase them when the application can be delayed for several USB transfers; keep UMP data 32-bit aligned in application buffers.

Callback order is important:

protocol/alternate selection -> descriptor callback -> mount callback
-> RX/TX callbacks -> unmount callback

tuh_midi2_descriptor_cb() is informational; the interface is not yet ready. Start I/O only after tuh_midi2_mount_cb(). In tuh_midi2_rx_cb(), call tuh_midi2_ump_read() in a loop until it returns zero. Queue output with tuh_midi2_ump_write() and use tuh_midi2_write_flush() when latency matters.

Use tuh_midi2_mounted(), tuh_midi2_get_protocol_version(), tuh_midi2_get_alt_setting_active() and tuh_midi2_get_cable_count() to inspect the selected transport. The Host: MIDI 2.0 example parses the UMP Message Type field to determine whether each message occupies 1, 2, 3, or 4 words.

tuh_midi2_ump_write() returns the number of words accepted and tuh_midi2_write_flush() returns the number of bytes submitted. Preserve unaccepted words and retry after tuh_midi2_tx_cb(). Treat the data supplied to tuh_midi2_descriptor_cb() as informational only; the interface becomes usable at tuh_midi2_mount_cb() and invalid at tuh_midi2_umount_cb().

Specification used: USB Device Class Definition for MIDI Devices, Release 2.0. It defines the MIDI 1.0-compatible alternate setting, the native UMP alternate setting, Group Terminal Blocks, and discovery behavior.