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 |
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.
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)
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.
OSStatus AUMIDIControllerCreate( CFStringRef inVirtualDestinationName, AUMIDIControllerRef * outController );
OSStatus AUMIDIControllerDispose( AUMIDIControllerRef inController );
OSStatus AUMIDIControllerMapChannelToAU( AUMIDIControllerRef inController, SInt32 inSourceMIDIChannel, AudioUnit inAudioUnit, SInt32 inDestMIDIChannel, Boolean inCreateDefaultControlMappings );
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.
OSStatus AUMIDIControllerMapEventToParameter( AUMIDIControllerRef inController, UInt8 inMIDIStatusByte, UInt16 inMIDIControl, const AudioUnitParameter * inParameter );
6, 38 data entry MSB, LSB 96-101 data increment, decrement, RPN, NRPN selectTo 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.
OSStatus AUMIDIControllerHandleMIDI( AUMIDIControllerRef inController, const MIDIPacketList * inMIDIPacketList );
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.
OSStatus AUMIDIControllerDisconnectSource( AUMIDIControllerRef inController, MIDIEndpointRef inSource );
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.
typedef struct OpaqueAUMIDIController *AUMIDIControllerRef;