Concepts

One MIDI data stream is a unidirectional stream of MIDI messages, as could be carried over one MIDI cable in the MIDI 1.0 specification. Many MIDI messages carry a four-bit channel number, creating up to 16 MIDI channels within a single MIDI stream. There may be multiple consumers of a MIDI stream, each configured to react only to messages on specific channels; the sets of channels different consumers react to need not be disjoint. Many modern devices such as multitimbral keyboards and tone generators listen on all 16 channels, or may be viewed as collections of 16 independent consumers each listening on one channel. MIDI defines some messages that take no channel number, and apply to all consumers of the stream on which they are sent. For an inbound stream, midi is a promiscuous receiver, capturing all messages regardless of channel number. For an outbound stream, the writer can specify a channel number per message; there is no notion of binding the stream to one destination channel in advance.

A single midi device instance is the endpoint of one outbound stream, one inbound stream, or one of each. In the third case, the write and read sides are independent MIDI streams. For example, a soundcard driver may map its MIDI OUT and MIDI IN jacks to the write and read sides of a single device instance, but those jacks can be cabled to completely different pieces of gear. Information from dmesg(8), and a diagram of any external MIDI cabling, will help clarify the mapping.

Underlying drivers and MIDI protocol

Drivers midi can attach include soundcard drivers, many of which support a UART resembling Roland's MPU401 and handled by mpu(4), USB MIDI devices via umidi(4), and on-board devices that can make sounds, whether a lowly PC speaker or a Yamaha OPL. Serial port and IEEE1394 connections are currently science fiction.

The MIDI protocol permits some forms of message compression such as running status and hidden note-off. Received messages on inbound streams are always canonicalized by midi before presentation to higher layers. Messages for transmission are accepted by midi in any valid form.

Device access

Access to midi device instances can be through the raw device nodes, /dev/rmidiN, or through the sequencer, /dev/music.

Raw MIDI access

A /dev/rmidiN device supports read(2), write(2), ioctl(2), select(2)/poll(2) and the corresponding kevent(2) filters, and may be opened only when it is not already open. It may be opened in O_RDONLY, O_WRONLY, or O_RDWR mode, but a later read(2) or write(2) will return -1 if the device has no associated input or output stream, respectively.

Bytes written are passed as quickly as possible to the underlying driver as complete MIDI messages; a maximum of two bytes at the end of a write(2) may remain buffered if they do not complete a message, until completed by a following write(2).

A read(2) will not block or return EWOULDBLOCK when it could immediately return any nonzero count, and MIDI messages received are available to read(2) as soon as they are complete, with a maximum of two received bytes remaining buffered if they do not complete a message.

As all MIDI messages are three bytes or fewer except for System Exclusive, which can have arbitrary length, these rules imply that System Exclusive messages are the only ones of which some bytes can be delivered before all are available.

System Realtime messages are passed with minimum delay in either direction, ahead of any possible buffered incomplete message. As a result, they will never interrupt any MIDI message except possibly System Exclusive.

A read(2) with a buffer large enough to accommodate the first complete message available will be satisfied with as many complete messages as will fit. A buffer too small for the first complete message will be filled to capacity. Therefore, an application that reads from an rmidi device with buffers of three bytes or larger need never parse across read boundaries to assemble a received message, except possibly in the case of a System Exclusive message. However, if the application reads through a buffering layer such as fread(3), this property will not be preserved.

The midi driver itself supports the ioctl(2) operations FIOASYNC, FIONBIO, and FIONREAD. Underlying devices may support others. The value returned for FIONREAD reflects the size in bytes of complete messages (or System Exclusive chunks) ready to read. If the ioctl(2) returns n and a read(2) of size n is issued, n bytes will be read, but if a read(2) of size m < n is issued, fewer than m bytes may be read if m does not fall on a message/chunk boundary.

Raw MIDI access can be used to receive bulk dumps from synthesizers, download bulk data to them, and so on. Simple patching of one device to another can be done at the command line, as with

$ cat -u 0<>/dev/rmidi0 1>&0

which will loop all messages received on the input stream of rmidi0 input stream back to its output stream in real time. However, an attempt to record and play back music with

$ cat /dev/rmidiN >foo; cat foo >/dev/rmidiN

will be disappointing. The file foo will contain all of the notes that were played, but because MIDI messages carry no explicit timing, the ‘playback’ will reproduce them all at once, as fast as they can be transmitted. To preserve timing information, the sequencer device can be used.

Active Sensing

The MIDI protocol includes a keepalive function called Active Sensing. In any receiver that has not received at least one Active Sense MIDI message, the feature is suppressed and no timeout applies. If at least one such message has been received, the lapse of any subsequent 300 ms interval without receipt of any message reflects loss of communication, and the receiver should silence any currently sounding notes and return to non-Active-Sensing behavior. A sender using Active Sensing generally avoids 300 ms gaps in transmission by sending Active Sense messages (which have no other effect) as needed when there is no other traffic to send in the interval. This feature can be important for MIDI, which relies on separate Note On and Note Off messages, to avoid notes stuck on indefinitely if communication is interrupted before a Note Off message arrives.

This protocol is supported in midi. An outbound stream will be kept alive by sending Active Sense messages as needed, beginning after any real traffic is sent on the stream, and continuing until the stream is closed. On an inbound stream, if any Active Sense has been received, then a process reading an rmidi device will see an end-of-file indication if the input timeout elapses. The stream remains open, the driver reverts to enforcing no timeout, and the process may continue to read for more input. Subsequent receipt of an Active Sense message will re-arm the timeout. As received Active Sense messages are handled by midi, they are not included among messages read from the /dev/rmidiN device.

These rules support end-to-end Active Sensing behavior in simple cases without special action in an application. For example, in

$ cat -u /dev/rmidi0 >/dev/rmidi1

if the input stream to rmidi0 is lost, the cat(1) command exits; on the close(2) of rmidi1, midi ceases to send Active Sense messages, and the receiving device will detect the loss and silence any outstanding notes.

Access through the sequencer

To play music using the raw MIDI API would require an application to issue many small writes with very precise timing. The sequencer device, /dev/music, can manage the timing of MIDI data in the kernel, to avoid such demanding real-time constraints on a user process.

The /dev/music device can be opened only when it is not already open. When opened, the sequencer internally opens all MIDI instances existing in the system that are not already open at their raw nodes; any attempts to open them at their raw nodes while the sequencer is open will fail. All access to the corresponding MIDI streams will then be through the sequencer.

Reads and writes of /dev/music pass eight-byte event structures defined in <sys/midiio.h> (which see for their documentation and examples of use). Some events correspond to MIDI messages, and carry an integer device field to identify one of the MIDI devices opened by the sequencer. Other events carry timing information interpreted or generated by the sequencer itself.

A message received on an input stream is wrapped in a sequencer event along with the device index of the stream it arrived on, and queued for the reader of /dev/music. If a measurable time interval passed since the last preceding message, a timing event that represents a delay for that interval is queued ahead of the received event. The sequencer handles output events by interpreting any timing event, and routing any MIDI message event at the proper time to an underlying output stream according to its device index. Therefore

$ cat /dev/music >foo; cat foo >/dev/music

can be expected to capture and reproduce an input performance including timing.

The process of playing back a complex MIDI file is illustrated below. The file may contain several tracks—four, in this example—of MIDI events, each marked with a device index and a time stamp, that may overlap in time. In the example, a, b, and c are device indices of the three output MIDI streams; the left-hand digit in each input event represents a MIDI channel on the selected stream, and the right-hand digit represents a time for the event's occurrence. As illustrated, the input tracks are not firmly associated with output streams; any track may contain events for any stream.

     |      |     a2|4     | 
   a0|3     |     c1|3   c0|3 
     |    b0|2    b1|2     | 
     |    b1|1      |    c0|1 
   a0|0     |     b0|0     | 
     v      v       v      v 
  +---------------------------+ 
  | merge to 1 ordered stream | 
  | user code, eg midiplay(1) | 
  +---------------------------+ 
              b1|2 
              b0|2 
              c0|1 
              b1|1 
              b0|0 
              a0|0 
                v 
  _______+-------------+_______user 
         | /dev/music  |     kernel 
         | (sequencer) | 
         +-------------+ 
           |    1    0 
     +-----'    |    '-----. 
     0          0          | 
     v          v          v 
  +-------+ +--------+ +---------+ 
  |midi(4)| |midi(4) | |midi(4)  | 
  |rmidia | |rmidib  | |rmidic   | 
  +-------+ +--------+ +---------+ 
  | mpu(4)| |umidi(4)| |midisyn  | 
  +-------+ +--------+ +---------+ 
  |  HW   |     |      | opl(4)  | 
  | MIDI  |     U      +---------+ 
  | UART  |      S     | internal| 
  +-------+       B    |   tone  | 
      |           |    |generator| 
      v           |    +---------+ 
   external       v 
  MIDI device  external 
              MIDI device

A user process must merge the tracks into a single stream of sequencer MIDI and timing events in order by desired timing. The sequencer obeys the timing events and distributes the MIDI events to the three destinations, in this case two external devices connected to a sound card UART and a USB interface, and an OPL tone generator on a sound card.