RawMidi interface

RawMidi Interface is designed to write or read raw (unchanged) MIDI data over the MIDI line without any timestamps defined in interface. MIDI stands Musical Instrument Digital Interface and more information about this standard can be found at http://www.midi.org.

General overview

The rawmidi implementation uses ring buffers to store outgoing and incoming MIDI stream. The buffer size is tunable and drivers report underruns for incoming stream as well.

Open handling

RawMidi devices are opened exclusively for a selected direction. While more than one process may not open a given MIDI device in the same direction simultaneously, separate processes may open a single MIDI device in different directions (i.e. process one opens a MIDI device in write direction and process two opens the same device in read direction).

Nonblocking open (flag)

Using SND_RAWMIDI_NONBLOCK flag for snd_rawmidi_open() or snd_rawmidi_open_lconf() instruct device driver to return the -EBUSY error when device is already occupied with another application. This flag also changes behaviour of snd_rawmidi_write() and snd_rawmidi_read() returning -EAGAIN when no more bytes can be processed.

Note: In opposite (default) behaviour, application is blocked until device resources are free.

Append open (flag)

Using SND_RAWMIDI_APPEND flag (output only) instruct device driver to append contents of written buffer - passed by snd_rawmidi_write() - atomically to output ring buffer in the kernel space. This flag also means that device is not opened exclusively, so more applications can share given rawmidi device. Note that applications must send the whole MIDI message including the running status, because another writing application might break the MIDI message in the output buffer.

Sync open (flag)

Using SND_RAWMIDI_SYNC flag (output only) assures that the contents of output buffer specified using snd_rawmidi_write() is always drained before the function exits. This behaviour is same like 'snd_rawmidi_write() followed by snd_rawmidi_drain() immediately'.

I/O handling

There is only standard read/write access to device internal ring buffer. Use snd_rawmidi_read() and snd_rawmidi_write() functions to obtain / write MIDI bytes.

RawMidi naming conventions

The ALSA library uses a generic string representation for names of devices. The devices might be virtual, physical or a mix of both. The generic string is passed to ::snd_rawmidi_open() or ::snd_rawmidi_open_lconf(). It contains two parts: device name and arguments. Devices and arguments are described in configuration files. The usual place for default definitions is at /usr/share/alsa/alsa.conf.

rawmidi_dev_names_default

The default device is equal to hw device. The defaults are used:

defaults.rawmidi.card 0 defaults.rawmidi.device 0 defaults.rawmidi.subdevice -1

These defaults can be freely overwritten in local configuration files.

Example:

default

HW device

The hw device description uses the hw plugin. The three arguments (in order: CARD,DEV,SUBDEV) specify card number or identifier, device number and subdevice number (-1 means any).

Example:

hw
hw:0
hw:0,0
hw:supersonic,1
hw:soundwave,1,2
hw:DEV=1,CARD=soundwave,SUBDEV=2

Read mode

Optionally, incoming rawmidi bytes can be marked with timestamps. The library hides the kernel implementation (linux kernel 5.14+) and exports the ::snd_rawmidi_tread() function which returns the midi bytes marked with the identical timestamp in one iteration.

The timestamping is available only on input streams.

Examples

The full featured examples with cross-links:

Simple input/output test program

example code

This example shows open and read/write rawmidi operations.

Virtual RawMidi interface

The "virtual" plugin creates a virtual RawMidi instance on the ALSA sequencer, which can be accessed through the connection of the sequencer ports. There is no connection established as default.

For creating a virtual RawMidi instance, pass "virtual" as its name at creation.

Example:

snd_rawmidi_open(&read_handle, &write_handle, "virtual", 0);