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 |
|---|---|---|
|
Required when enabled |
Software FIFO bytes per interface. Define both, normally at least as large as the matching endpoint buffer. |
|
Device bulk maximum |
Endpoint transfer buffer bytes. Keep them at least the descriptor
packet size, the |
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 |
|---|---|
|
Report the RX FIFO byte count plus the bytes left in a partially
consumed packet, and read MIDI bytes for one interface. Both ignore
|
|
Reads bytes from one cable at a time, returns the byte count and writes
the cable number to |
|
Packetizes a MIDI byte stream and returns the number of source bytes accepted. |
|
Reads or writes complete 4-byte USB-MIDI event packets and returns a packet count. |
|
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 |
|---|---|---|
|
Host bulk maximum |
Software FIFO capacity for received and queued event packets. |
|
Host bulk maximum |
Endpoint transfer buffer size. |
|
|
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 |
|---|---|---|
|
Device bulk maximum |
Endpoint transfer buffer bytes. Keep them at least the descriptor
packet size, the |
|
Matching endpoint size |
UMP FIFO bytes per interface. |
|
|
Number of UMP groups exposed by the default Group Terminal Block. |
|
TinyUSB strings |
Default endpoint name and product identifier returned by UMP discovery.
Override |
|
|
MIDI-CI version and SysEx8 stream count reported in Function Block Info. |
|
|
Optional string-descriptor index ( |
|
|
Default |
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.