MIDI Services

Overview

MIDI drivers own and control MIDI devices, which include such things as USB interfaces, MIDI keyboards, and so on. 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.

A MIDI device may have multiple logically distinct sub-components. For example, one device may encompass a MIDI synthesizer and a pair of MIDI ports, both addressable via a USB port. Each such element of a device is called a MIDI entity.

A MIDI entity can have any number of MIDI endpoints, each of which is a source or destination of a 16-channel MIDI stream. By grouping a device’s endpoints into entities, the system has enough information for an application to make reasonable default assumptions about how to communicate in a bi-directional manner with each entity, as is necessary in MIDI librarian applications.

Core MIDI attaches a collection of properties to each object it manages. Some properties are dynamic characteristics of a device—such as MIDI receive channel and system-exclusive IDs. Other properties are a matter of user preference—such as choice of icon, and whether or not the device should appear in lists of possible controllers. Still other properties are static and could be looked up in a database, using the device’s manufacturer and model names as a key.

The Core MIDI framework uses IPC (interprocess communication) to communicate with a server process, the MIDI server. The server process in turn loads, and manages all communication with, the MIDI driver.

Beginning in iOS 6, apps need to have the audio key in their UIBackgroundModes in order to use CoreMIDI’s MIDISourceCreate(_:_:_:) and MIDIDestinationCreate(_:_:_:_:_:) functions. These functions return kMIDINotPermitted (-10844) if the key is not set. See Information Property List Key Reference for more information.

Topics

Using MIDI Ports

func MIDIInputPortCreate(MIDIClientRef, CFString, MIDIReadProc, UnsafeMutableRawPointer?, UnsafeMutablePointer<MIDIPortRef>) -> OSStatus

Creates an input port through which the client may receive incoming MIDI messages from any MIDI source.

func MIDIOutputPortCreate(MIDIClientRef, CFString, UnsafeMutablePointer<MIDIPortRef>) -> OSStatus

Creates an output port through which the client may send outgoing MIDI messages to any MIDI destination.

func MIDIPortConnectSource(MIDIPortRef, MIDIEndpointRef, UnsafeMutableRawPointer?) -> OSStatus

Establishes a connection from a source to a client's input port.

func MIDIPortDisconnectSource(MIDIPortRef, MIDIEndpointRef) -> OSStatus

Closes a previously-established source-to-input port connection.

Using MIDI Packet Lists

func MIDIPacketNext(UnsafePointer<MIDIPacket>) -> UnsafeMutablePointer<MIDIPacket>

Advances a MIDIPacket pointer to the MIDIPacket that immediately follows a given packet in memory, for packets that are part of a MIDIPacketList array.

Using MIDI Objects and Properties

Using MIDI I/O

func MIDIFlushOutput(MIDIEndpointRef) -> OSStatus

Unschedules previously-sent packets.

func MIDIReceived(MIDIEndpointRef, UnsafePointer<MIDIPacketList>) -> OSStatus

Distributes incoming MIDI from a source to the client input ports which are connected to that source.

func MIDIRestart() -> OSStatus

Stops and restarts MIDI I/O.

func MIDISendSysex(UnsafeMutablePointer<MIDISysexSendRequest>) -> OSStatus

Sends a single system-exclusive event, asynchronously.

Using MIDI External Devices

func MIDIGetExternalDevice(Int) -> MIDIDeviceRef

Returns one of the external devices in the system.

func MIDIGetNumberOfExternalDevices() -> Int

Returns the number of external MIDI devices in the system.

Using MIDI Entities

Using MIDI Endpoints

Using MIDI Devices

func MIDIDeviceGetEntity(MIDIDeviceRef, Int) -> MIDIEntityRef

Returns one of a given device's entities.

func MIDIDeviceGetNumberOfEntities(MIDIDeviceRef) -> Int

Returns the number of entities in a given device.

func MIDIGetDevice(Int) -> MIDIDeviceRef

Returns one of the devices in the system.

func MIDIGetNumberOfDevices() -> Int

Returns the number of devices in the system.

Callbacks

typealias MIDICompletionProc

Called when a MIDI system-exclusive event has been completely sent or has been aborted.

typealias MIDINotifyProc

Called when the MIDI state changes.

typealias MIDIReadProc

Called when the system has one or more incoming MIDI messages to deliver to your app.

Data Types

typealias MIDIClientRef

An object maintaining per-client state.

typealias MIDIDeviceRef

A MIDI device or external device, containing entities.

typealias MIDIEndpointRef

A MIDI source or destination, owned by an entity.

typealias MIDIEntityRef

A MIDI entity, owned by a device, containing endpoints.

typealias MIDIObjectRef

The base class of many CoreMIDI objects.

typealias MIDIPortRef

A MIDI connection port owned by a client.

typealias MIDITimeStamp

A host clock time.

typealias MIDIUniqueID

A unique identifier for a MIDIObjectRef.

struct MIDINotification

A message describing a system state change.

struct MIDIObjectAddRemoveNotification

A message describing the addition or removal of an object.

struct MIDIObjectPropertyChangeNotification

A message describing the addition or removal of an object.

struct MIDIIOErrorNotification

A message describing a MIDI I/O error.

struct MIDIPacket

A collection of simultaneous MIDI events.

struct MIDIPacketList

A list of MIDI events being received from, or being sent to, one endpoint.

struct MIDISysexSendRequest

A request to transmit a system-exclusive event.

Constants

Error Constants

The error constants unique to Core MIDI.

enum MIDINotificationMessageID

Signifies the type of a MIDINotification.

enum MIDIObjectType

Indicates the type of a MIDI object.

kMIDIInvalidUniqueID

Indicates that the MIDI unique ID is not valid.