Enter your search terms Submit search form   Web www.opensound.com manuals.opensound.com developer.opensound.com

Open Sound System OSS 4.x Programmer's Guide

OSS MIDI Programming

Under construction.

The MIDI programming section of this manual is currently under construction because there is no MIDI support in OSS 4.0. This section will be completed after MIDI support becomes available.

There are two noticeable changes since earlier OSS versions. The first one is the MTC input mode (SNDCTL_MIDI_MTCINPUT). The second addition is the loopback MIDI device that permits implementing applications such as user space MIDI synthesizers easily. The loopback devices don't actually differ from the ordinary "physical" MIDI ports in any way so there is nothing special in using them. However real time software synthesizers may need to use the MTC input timing mode to avoid timing jitter in the audio output.

The third change in OSS 4.0 is that the development of the previous sequencer (/dev/sequencer and /dev/music) API has been halted. Instead the same functionality will be provided based on the MIDI "port" interface. The main reason is that the sequencer approach resulted in a huge number of different messages that were already defined in the MIDI specifications. This prevented applications from using new MIDI features before the sequencer API was updated. Another reason is that the MIDI port interface is extremely simple and well defined approach.

To make it possible to implement user land software synthesizer applications we have added a new "MIDI loopback" device driver to OSS. We have created a very simple sample program (softsynth.c) that demonstrates how simple and robust this new MIDI interface is.

What is MIDI?

MIDI is a serial communication protocol developed for communication between musical instruments. It's defined in the specifications published by MIDI Manufactur's Assiciation (MMA). To get the specifications you can order them for example using MMA's web site . Some unofficial information is available from the internet for free.

This document doesn't explain the MIDI protocol because that information is available elsewhere.

How MIDI works in OSS

The MIDI port devices of OSS work like serial ports. The application that wants to use MIDI simply opens the MIDI device file using the open system call. After that it simply writes MIDI bytes to the device and they will be sent out from the physical device as quickly as possible. If data is written faster than the MIDI line can transfer then the bytes will be buffered by the OSS driver until they can be transmitted. Recording MIDI data works in the identical way.

The MIDI ports are often called as MPU-401 or UART-401 devices because Roland MPU-401 was the most common MIDI port device long time ago. OSS supports UART-401 (MPU-401 "UART MODE") compatible devices as well as many other native MIDI interfaces of various sound cards.

There may be several MIDI devices in the system. The available devices are numbered between 0 and N. The /dev/midi00 device file matches the first MIDI port (number 0). /dev/midi01 is the second and so on. The /dev/midi device file is the "default" MIDI device that can be assigned by the user to point any of the available devices.

There are actually several kinds of MIDI devices.

• MIDI UART ports are just like any serial devices (such as the serial (COM) ports of a PC computer. They don't produce any sound themselves but they can be used to connect the computer to many kind of external devices such ase keyboards, MIDI sound generators and samplers.
• Built in synthesizer chips of some sound cards (such as SB Live!/Audigy). The drivers for such devices will interpret the MIDI messages written by the application and play them.
• Loopback devices are "virtual" MIDI devices that route MIDI messages between two applications at the ends of the pipe. For example a software synthesizer application may listen to the MIDI input at the "server" side and convert the MIDI messages sent by the "client" application to audio data.

The way how the particular MIDI port works doesn't matter since all cases will look like the same to the applications. Only the applications working as real-time software synthesizers may need to behave in slightly different way than "ordinary" MIDI applications.

MIDI device files

There are two kinds of MIDI related device files available in OSS.

• Direct devices (/dev/midi00, /dev/midi01 and so on) make it possible to the application to select the device directly. By using the SNDCTL_MIDIINFO ioctl the application can give the user a chance to select the device to be used. Note that for historic reasons the device number included in the /dev/midiNN device names is always at least two digits.
• The /dev/midi device is the default device file which should be used when the application doesn't support configurable MIDI devices. OSS will bind this device file to one of the /dev/midiNN device. The exact selection policy is implementation dependent and applications should not depend on any particular algorithm. Applications cannot change the way how this binding operation is performed. If there is any need to do this then it's probably better to open one of the /dev/midiNN devices directly.

There are several ways how /dev/midi could be bound to the /dev/midiNN devices. Some implementations of OSS may simply connect to the first available device. Other implementations may have sophisticated MIDI patch bay systems. All the details have been intentionally hidden from the applications.

When using the /dev/midi device the application should open the device when it starts and then keep it opened until the program terminates. This makes it easier to route MIDI data between devices and applications. If necessary the application can open several instances of /dev/midi. In such case each of them will be bound to a different MIDI port.

Remember to use the right access mode (O_RDONLY, O_WRONLY or O_RDWR) when opening the MIDI device. Using O_RDWR unnecessarily may prevent some other applications from accessing the same device in different mode. With /dev/midi the access mode determines which devices can be bound to the application. Applications requesting input/output access cannot be bound to a device that can not do both input and output. It's recommended to open two instances of /dev/midi with O_RDONLY and O_WRONLY instead of opening /dev/midi once with O_RDWR.

Interface modes

The MIDI interface can be used in two different modes. In the traditional mode (default) the device behaves much like a tty serial port. The timed mode interface permits sophisticated features such as precise timing based on internal or external timing sources.

Traditional mode

The midi.c sample program explains how MIDI output can be used in applications. With the current OSS version the application needs to take care of the timing itself by using usleep() or some other system services. However in the near future the OSS driver will support timing handled at the driver level.

The midiin.c program is another example of MIDI program that does input.

Things will get bit more difficult if the application does both input and output at the same time or if it needs to handle video, audio or keyboard input too. However handling this kind of issues is very trivial with the select system call.

Timed mode

The timed mode supercedes the /dev/sequencer interface that was used in the earlier OSS versions. It permits the same functionality but in a way that is fully compatible with the official MIDI specifications.

The timed mode and it's features are explained in the Using the timed mode MIDI interface section.

The MIDI related ioctl calls

There just very few ioctl calls related with the MIDI interface. In addition the SNDCTL_MIDIINFO call is related with MIDI devices.