Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
class	MIDI	MBS MacCF Plugin	3.1	✅ Yes	❌ No	❌ No	✅ Yes	All

A class for the global MIDI stuff on Mac OS X.

Only make one instance of this class in your application.

From Apple's documentation:

History:

Apple's MIDI Manager (ca. 1990) had a simple model of the world. There were application and driver clients, which had MIDI in/out ports, which could be interconnected in arbitrary ways. This model failed to provide a way for applications to make reasonable assumptions about how to make bi-directional connections to a MIDI device. MIDI Manager also had limitations on the number of ports per client, and became very unwieldy with the advent of large studios and multi-port MIDI interfaces such as the MIDI Time Piece and Studio 5.

Opcode's OMS (1991) addressed some of the shortcomings of MIDI Manager. There was the concept of a studio setup document, where drivers detected their devices, and the user could define the characteristics of additional devices connected to the MIDI ports. Applications could view the studio both as a collection of MIDI source and destination "nodes", but also as a collection of devices. OMS collected information about, and made available to its clients, useful characteristics of the devices in the studio, such as their system-exclusive IDs, MIDI channels on which they were listening, which were controllers (as opposed to simple tone generators), etc.

API Overview:
This design expands slightly on OMS's device/node hierarchy, inspired by the USB MIDI spec.

Drivers own and control devices, e.g. USB interfaces, PCI cards, etc. A device is defined as a physical object that would be represented by a single icon if there were a graphical view of the studio.

Devices may have multiple logically distinct sub-components, e.g. a MIDI synthesizer and a pair of MIDI ports, both addressable via a USB port. These are called Entities.

Entities have any number of Endpoints, sources and destinations of 16-channel MIDI streams. By grouping a device's endpoints into entities, the system has enough information for an application to make reasonable assumptions about how to communicate in a bi-directional manner with each entity, as is necessary in MIDI librarian applications.

Third-party services like FreeMIDI or OMS can collect and report interesting properties of a device by attaching those properties to the devices' entities -- CoreMIDI provides a central database, but no user interfaces.. It's worth noting that some device characteristics are dynamic (e.g. MIDI receive channel and system-exclusive ID's), or a matter of user preference (choice of icon, whether the device should appear in lists of possible controllers), while other properties are static and could be looked up in a database, using the device's manufacturer and model names as a key.

Persistent configurations / Device Information:
There are a number of reasons why CoreMIDI has a persistent state.

Endpoints must have persistent ID's. When a user assigns events in a sequencing application to an endpoint, the application needs a way to retain a permanent reference to the selected endpoint. A brute-force method of generating a persistent ID would be to combine the driver name, device name, entity name, and endpoint type and index into a string, but this is not very

friendly to clients even if the system provides services to generate and decode these strings.

Consider a USB MIDI interface driver, in the case where there are two instances of one model of interface present. The driver needs a way to permanently distinguish, to the system and its clients, between the two interfaces. Which is #1 and which is #2? If #1 gets unplugged, #2 should not automatically become #1; the user's documents may be referring to devices which were attached to #2.

The system needs a persistent concept of which driver's device is attached to a serial port.

Some drivers will need to store configuration information about the devices they control. For example, the driver for a standard MIDI interface on a serial port needs to remember which external clocking speed to use (this is

a simple, slightly obscure, but hardly unique example). The Alesis QS7 is capable of communicating at a variety of speeds, so its driver needs to remember the correct speed.

These needs for persistent configuration information provide a rationale for having something akin to OMS's studio setup document, a saved configuration for the system. Mobile users who work in multiple environments could select between multiple saved configurations in a Location Manager-compatible manner.

Given services with which to store driver configuration information, we then have built the groundwork for a client studio setup editor application.
Such an application can define external MIDI devices (not to be confused with the driver-owned cards/ interfaces/etc whose presence in the configuration is determined by the driver).

Moreover, since a driver knows exactly what device it is communicating with, it is capable of supplying information to the system about the

characteristics of the device, such as its system-exclusive ID, whether it

is General MIDI or DLS-compatible, etc.

But unlike OMS, the system is able to begin functioning immediately, using only the MIDI devices/endpoints detected by the drivers, without

forcing the user to go through a somewhat lengthy and confusing intial configuration process. Definition of external MIDI devices can be a completely optional step, only made possible when a client application requests that they be added to the configuration.

Implementation overview:
The client API is implemented as the CoreMIDI framework, which uses IPC to communicate with a server process, MIDIServer.

The server process loads, and manages all communication with, MIDI drivers. Most of its implementation is in the CoreMIDIServer framework, which drivers may import in order to access the API.

"Drivers" are not I/O Kit drivers. They are dynamic libraries, using CFPlugin.

Many MIDI drivers can simply be user-side I/O Kit clients (probably for serial, USB, Firewire).

PCI card drivers will need their MIDI drivers to communicate with a separate kernel extension.

If you have an old file named EmagicUSBMIDIDriver.plugin in your /Library/Audio/MIDI Drivers folder, please remove it. It makes trouble with our Midi classes.

See also macOS specific classes AVMIDIPlayerMBS and MidiPlaybackMBS for playback. For Windows see also WindowsMidiMBS class.
See also PortMidiMBS class for cross platform Midi handling.
Subclass of the MidiObjectMBS class.