Audio Unit MIDI Controllers

Header file: AudioToolbox/AUMIDIController.h


Contents
 Overview
  For Audio Units
  For MusicDevices and Music Effects
 Reference
Functions
 AUMIDIControllerCreate Create an AUMIDIController.
 AUMIDIControllerDispose Dispose an AUMIDIController.
 AUMIDIControllerMapChannelToAU Map one or all MIDI channels to control an Audio Unit.
 AUMIDIControllerMapEventToParameter Map a MIDI event to a single Audio Unit parameter.
 AUMIDIControllerHandleMIDI Manually route MIDI to an AUMIDIController.
 AUMIDIControllerConnectSource Connect a CoreMIDI source directly to an AUMIDIController.
 AUMIDIControllerDisconnectSource Disconnect a CoreMIDI source from an AUMIDIController.
 AUMIDIControllerExportXMLNames Export an AUMIDIController's configuration as an XML file.
Defined Types
 AUMIDIControllerRef

Overview

AUMIDIController is an object that routes MIDI messages to one or more Audio Units (including the MusicEffect and MusicDevice types of units).

The AUMIDIController may, at the client's discretion, create a CoreMIDI virtual destination for itself. The client may also connect and disconnect MIDI sources to and from a CoreMIDI input port associated with the AUMIDIController.

See the CoreMIDI headers and documentation for information about some of the data types and objects used in these services.

For Audio Units

The AUMIDIController will map a 7 or 14-bit MIDI control or NRPN (non-registered parameter, see the MIDI specification) to an AudioUnitParameterID/AudioUnitScope/AudioUnitElement, map the integer MIDI control value to the parameter value range, and call AudioUnitSetParameter.

To provide MIDI control for Audio Units written to previous versions of the Audio Unit API, the AUMIDIController provides a default mapping of controls and NRPNs to parameters, but only for Audio Units, not MusicDevices, which are assumed by default to do their own control parsing when receiving MIDI events:

If the Audio Unit has 31 or fewer parameters in the global scope, all with parameterID's less than 31, then they are mapped from 14-bit MIDI controls as follows:

	    control     parameterID (in global scope)
	    0-5         0-5
	    7-31        6-30

For parameters in non-global scopes, as well as parameters in the global scope if it has too many parameters to be mapped to standard MIDI controls, MIDI non-registered parameters (NRPN's) are mapped to Audio Unit parameters as follows:

	    MIDI   NRPN MSB    NRPN LSB
	           abcdefg     hijklmn	   (bits)

	    AU     Scope       Element     Parameter
	           ab          cdefgh      ijklmn
			
	    except: global scope is always element 0 so bits cdefghijklmn are mapped
	    to 12 bits of parameters (0-4095)

For MusicDevices and Music Effects

There is no default mapping of MIDI controls/NRPNs to AU parameters; mapping only happens for parameters which the MusicDevice explicitly publishes as being MIDI-controllable, in the parameters' AudioUnitParameterInfo.

All events not mapped to AudioUnitSetParameter are passed through to MusicDeviceMIDIEvent.


Reference

AUMIDIControllerCreate

Create an AUMIDIController.
OSStatus AUMIDIControllerCreate(
  CFStringRef            inVirtualDestinationName,
  AUMIDIControllerRef *  outController
);

Parameters

inVirtualDestinationName
If non-null, a CoreMIDI virtual destination is created with this name.
outController
On successful return, an AUMIDIControllerRef object.

AUMIDIControllerDispose

Dispose an AUMIDIController.
OSStatus AUMIDIControllerDispose(
  AUMIDIControllerRef  inController
);

Parameters

inController
The AUMIDIController to dispose.

AUMIDIControllerMapChannelToAU

Map one or all MIDI channels to control an Audio Unit.
OSStatus AUMIDIControllerMapChannelToAU(
  AUMIDIControllerRef  inController,
  SInt32               inSourceMIDIChannel,
  AudioUnit            inAudioUnit,
  SInt32               inDestMIDIChannel,
  Boolean              inCreateDefaultControlMappings
);

Parameters

inController
The AUMIDIController being configured.
inSourceMIDIChannel
0-15, corresponding to MIDI channels 1-16, or -1 to map all 16 channels to the supplied Audio Unit.
inAudioUnit
The Audio Unit to control, or 0 to remove a mapping to this unit.
inDestMIDIChannel
0-15, corresponding to MIDI channels 1-16. If inSourceMIDIChannel is -1, this parameter is ignored. Otherwise, when channel events are routed to a MusicDevice, they are rechannelized to this channel.
inCreateDefaultControlMappings
If true, the MIDI-to-parameter mappings are obtained from the Audio Unit, if it supplies them, or the default control mapping described in detail above is used. If false, no MIDI-to-parameter mappings are made.

If the Audio Unit is a MusicDevice or a MusicEffect type unit, this argument is ignored and default control mappings are NOT made; the MusicDevice must implement response to MIDI controls itself.

AUMIDIControllerMapEventToParameter

Map a MIDI event to a single Audio Unit parameter.
OSStatus AUMIDIControllerMapEventToParameter(
  AUMIDIControllerRef         inController,
  UInt8                       inMIDIStatusByte,
  UInt16                      inMIDIControl,
  const AudioUnitParameter *  inParameter
);

Parameters

inController
The AUMIDIController being configured.
inMIDIStatusByte
The event type and channel to be mapped. Only control events, status bytes 0xB0-0xBF, are currently supported.
inMIDIControl
The MIDI control number to be mapped. MIDI controls 32-63 are always parsed as the LSB's of controls 0-31, so they may not be mapped separately. Also, the following MIDI controls have special meanings and thus may not be mapped in this manner:

	    6, 38        data entry MSB, LSB
	    96-101       data increment, decrement, RPN, NRPN select
To specify a NRPN, put the 14-bit MSB/LSB of the parameter number in the low 14 bits of the UInt16, and or that with 0x8000.
inParameter
The Audio Unit parameter to control. It may be null, or its mAudioUnit member may be null, which in either case will remove a mapping.

AUMIDIControllerHandleMIDI

Manually route MIDI to an AUMIDIController.
OSStatus AUMIDIControllerHandleMIDI(
  AUMIDIControllerRef     inController,
  const MIDIPacketList *  inMIDIPacketList
);

Parameters

inController
The AUMIDIController to play the supplied MIDI events.
inMIDIPacketList
The MIDI events to be played. (The MIDIPacketList structure is defined in the CoreMIDI framework.)

AUMIDIControllerConnectSource

Connect a CoreMIDI source directly to an AUMIDIController.
OSStatus AUMIDIControllerConnectSource(
  AUMIDIControllerRef  inController,
  MIDIEndpointRef      inSource
);
This could be used to connect a keyboard to a Music Device, for example. It's possible to connect multiple sources to one AUMIDIController.

Parameters

inController
The AUMIDIController being configured.
inSource
The CoreMIDI source from which events will be routed to the AUMIDIController.

AUMIDIControllerDisconnectSource

Disconnect a CoreMIDI source from an AUMIDIController.
OSStatus AUMIDIControllerDisconnectSource(
  AUMIDIControllerRef  inController,
  MIDIEndpointRef      inSource
);

Parameters

inController
The AUMIDIController being configured.
inSource
The CoreMIDI source being disconnected.

AUMIDIControllerExportXMLNames

Export an AUMIDIController's configuration as an XML file.
OSStatus AUMIDIControllerExportXMLNames(
  AUMIDIControllerRef  inController,
  CFURLRef *           outXMLFileURL
);
Tells an AUMIDIController to generate an XML description of the control/NRPN mapping. Returns a (local file) URL to the file written. If the AUMIDIController has a virtual destination associated with it, the AUMIDIController will call MIDIObjectSetNameConfiguration to publish those names as the current ones for that destination.

AUMIDIControllerRef

typedef struct OpaqueAUMIDIController *AUMIDIControllerRef;