ALSA project - the C library reference
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.
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.
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).
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.
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.
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'.
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.
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.
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).
The full featured examples with cross-links:
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.