Audio Unit

Detailed Description

ARA support for Audio Units is mostly based on private Audio Unit properties. The input/output pattern for the associated property data structs is similar to struct AudioUnitParameterStringFromValue in the Audio Unit API. To be able to detect potential collisions if some host or Audio Unit uses the same private property for non-ARA communication, the actual ARA data is embedded into a property data struct that also contains an ARA magic number. For this magic number to work properly for all host/plug-in combinations, it's crucial that hosts set it on input and check it after output, and that plug-ins check it before writing to the property struct.

Classes

struct  ARAAudioUnitFactory
 Property data for kAudioUnitProperty_ARAFactory. More...
 
struct  ARAAudioUnitPlugInExtensionBinding
 Property data for kAudioUnitProperty_ARAPlugInExtensionBindingWithRoles. More...
 

Macros

#define kARAAudioComponentTag   "ARA"
 Integration with the system-wide Audio Unit cache. Since the introduction of the Audio Component APIs in macOS 10.10 Yosemite, a system-wide cache of all installed Audio Units allows hosts to defer opening any Audio Unit until the user explicitly requests this. To support this optimization also when ARA is used, plug-ins must be marked as ARA-compatible at the Audio Component level by including the tag "ARA" in their Info.plist file, like in this example: More...
 

Class Documentation

◆ ARAAudioUnitFactory

struct ARAAudioUnitFactory

Property data for kAudioUnitProperty_ARAFactory.

Public Attributes

OSType inOutMagicNumber
 Input/output: token to identify the property is actually used for ARA.
 
const ARAFactory * outFactory
 Output: pointer to the factory associated with the Audio Unit.
 

◆ ARAAudioUnitPlugInExtensionBinding

struct ARAAudioUnitPlugInExtensionBinding

Property data for kAudioUnitProperty_ARAPlugInExtensionBindingWithRoles.

Public Attributes

OSType inOutMagicNumber
 Input/output: token to identify the property is actually used for ARA.
 
ARADocumentControllerRef inDocumentControllerRef
 Input: document controller of the model graph that the Audio Unit shall be bound to.
 
const ARAPlugInExtensionInstance * outPlugInExtension
 Output: the entry point for the plug-in.
 
ARAPlugInInstanceRoleFlags knownRoles
 Input: all roles that the host considered in its implementation and will explicitly assign to some plug-in instance(s). Being an ARA 2.0 addition, this field is only available if kAudioUnitProperty_ARAPlugInExtensionBindingWithRoles is used.
 
ARAPlugInInstanceRoleFlags assignedRoles
 Input: roles assigned to this specific plug-in instance. Being an ARA 2.0 addition, this field is only available if kAudioUnitProperty_ARAPlugInExtensionBindingWithRoles is used.
 

Macro Definition Documentation

◆ kARAAudioComponentTag

#define kARAAudioComponentTag   "ARA"

Integration with the system-wide Audio Unit cache. Since the introduction of the Audio Component APIs in macOS 10.10 Yosemite, a system-wide cache of all installed Audio Units allows hosts to defer opening any Audio Unit until the user explicitly requests this. To support this optimization also when ARA is used, plug-ins must be marked as ARA-compatible at the Audio Component level by including the tag "ARA" in their Info.plist file, like in this example:

<key>AudioComponents</key>
<array>
<dict>
...
<key>manufacturer</key>
<string>Demo</string>
<key>subtype</key>
<string>Test</string>
<key>type</key>
<string>aufx</string>
...
<key>tags</key>
<array>
<string>Effect</string>
...
<string>ARA</string>
</array>
</dict>
</array>

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
kARAAudioUnitMagic 

This value must be placed in the magicNumber fields of the ARA properties.

◆ anonymous enum

anonymous enum
Enumerator
kAudioUnitProperty_ARAFactory 

kAudioUnitScope_Global, read-only, property data is ARAAudioUnitFactory: query the ARA factory associated with the given plug-in.

◆ anonymous enum

anonymous enum
Enumerator
kAudioUnitProperty_ARAPlugInExtensionBinding 

kAudioUnitScope_Global, read-only, property data is ARAAudioUnitPlugInExtensionBinding: bind the Audio Unit instance to an ARA document controller, switching it from "normal" operation to ARA mode, and exposing the ARA plug-in extension. Note that since ARA 2.0, this property has been deprecated and replaced with kAudioUnitProperty_ARAPlugInExtensionBindingWithRoles. This deprecated call is equivalent to the new call with no known roles set, however all ARA 1.x hosts are in fact using all instances with playback renderer, edit renderer and editor view role enabled, so plug-ins implementing ARA 1 backwards compatibility can safely assume those three roles to be enabled if this call was made. Same call order rules as kAudioUnitProperty_ARAPlugInExtensionBindingWithRoles apply.

◆ anonymous enum

anonymous enum
Enumerator
kAudioUnitProperty_ARAPlugInExtensionBindingWithRoles 

ARA 2 extended version of kAudioUnitProperty_ARAPlugInExtensionBinding: kAudioUnitScope_Global, read-only, property data is ARAAudioUnitPlugInExtensionBinding: bind the Audio Unit instance to an ARA document controller, switching it from "normal" operation to ARA mode with the assigned roles, and exposing the ARA plug-in extension. This may be done only once during the lifetime of the Audio Unit, before initializing it via kAudioUnitInitializeSelect or setting its state via the properties ClassInfo, PresentPreset or CurrentPreset or before creating any of the custom views for Audio Unit. The ARA document controller must remain valid as long as the plug-in is in use - rendering, showing its UI, etc. However, when tearing down the plug-in, the actual order for deleting the Audio Unit and for deleting ARA document controller is undefined. Plug-ins must handle both potential destruction orders to allow for a simpler reference counting implementation on the host side.