/* File: AudioUnitProperties.h Contains: Property constants for AudioUnits Copyright: (c) 2001-2008 by Apple, Inc., all rights reserved. Bugs?: For bug reports, consult the following page on the World Wide Web: http://developer.apple.com/bugreporter/ */ #ifndef __AudioUnitProperties #define __AudioUnitProperties #if !defined(__COREAUDIO_USE_FLAT_INCLUDES__) #include #include #include #else #include #include #include #endif //===================================================================================================================== #pragma mark Overview /*! @header AudioUnitProperties This file defines a collection of property IDs and their accompanying structures that are used by audio units. Properties form the basis of much of the audio unit API. You use them with the Audio Unit framework's Get and Set property API calls declared in the AUComponent.h header file: AudioUnitGetPropertyInfo AudioUnitGetProperty AudioUnitSetProperty This file first lists generic audio unit properties (those that are potentially applicable to any audio unit), followed by properties specific to Apple audio units. Apple reserves property IDs from 0 -> 63999. Developers are free to use property IDs above this range. All property values are passed by reference. When a property's value type is listed below, that value type is always passed by reference. For example, CFStringRef is passed as &myCFString. Properties are described below using a general form: Scope: The audio unit scope that the property applies to. For example, Global, Input, Output, etc. For an explanation of audio unit scopes, see the Audio Unit Programming Guide in the ADC Reference Library. Value Type: The data type used to hold the value associated with the property. For example, CFStringRef or UInt32 Access: How a host application can access the property in a hosted audio unit: read only, write only, or read/write. Description: A description of the property's role. The descriptions in this file apply to typical or recommended usage. Audio unit developers can vary the way each property is used. For example, a property may be described as applying to both input and output scopes, but a given audio unit may implement the property on the input scope only. As another example, a property may be described here as having read/write access, but an audio unit may implement the property as read only. The properties are divided into two primary sections: (1) Core/Embedded Implementation - these properties are available on all platforms where audio units are available (2) Desktop - these properties are available on only available on desktop platforms The following file is organised into these two sections */ #pragma mark - #pragma mark Core Implementation #pragma mark - /*! @enum Audio Unit scope types @abstract The scope IDs for audio units define basic roles and contexts for an audio unit's state. @discussion Each scope is a discrete context. Apple reserves scope IDs from 0 through 1024. @constant kAudioUnitScope_Global The context for audio unit characteristics that apply to the audio unit as a whole @constant kAudioUnitScope_Input The context for audio data coming into an audio unit @constant kAudioUnitScope_Output The context for audio data leaving an audio unit @constant kAudioUnitScope_Group A context specific to the control scope of parameters (for instance, MIDI Channels is an example of this scope) @constant kAudioUnitScope_Part A distinct rendering context. For instance a single timbre in a multi-timbral instrument, a single loop in a multi looping capable looper unit, etc. @constant kAudioUnitScope_Note A scope that can be used to apply changes to an individual note. The elementID used with this scope is the unique note ID returned from a started note (see MusicDeviceStartNote) @constant kAudioUnitScope_Layer A context which functions as a layer within a part and allows grouped control of LayerItem-scope parameters. An example is the percussive attack layer for an electric organ instrument @constant kAudioUnitScope_LayerItem A scope which represents an indivual element within a particular Layer scope. The individual sample zones, envelope generators, and filters within a synth are examples of this. */ enum { kAudioUnitScope_Global = 0, kAudioUnitScope_Input = 1, kAudioUnitScope_Output = 2, kAudioUnitScope_Group = 3, kAudioUnitScope_Part = 4, kAudioUnitScope_Note = 5, kAudioUnitScope_Layer = 6, kAudioUnitScope_LayerItem = 7 }; //===================================================================================================================== #pragma mark Audio Unit Properties /*! @enum Generic Property IDs @abstract Properties that can apply to any audio unit. @constant kAudioUnitProperty_ClassInfo Scope: Global (or Part for a part scope preset) Value Type: CFDictionaryRef Access: read/write The complete state of an audio unit if on global scope. An audio unit that supports part scope, may also support presets on the part scope that apply to individual parts. After a host sets this property it needs to notify the parameter listeners that the values of the parameters of an AU may have changed (so views, etc, can update their state). Something like the following code should be used: #include AudioUnitParameter changedUnit; changedUnit.mAudioUnit = theChangedAU; changedUnit.mParameterID = kAUParameterListener_AnyParameter; AUParameterListenerNotify (NULL, NULL, &changedUnit); @constant kAudioUnitProperty_MakeConnection Scope: Input Value Type: AudioUnitConnection Access: Write @constant kAudioUnitProperty_SampleRate Scope: Input / Output Value Type: Float64 Access: read/write @constant kAudioUnitProperty_ParameterList Scope: Any Value Type: AudioUnitParameterID Access: Read The list of parameter IDs on the specified scope @constant kAudioUnitProperty_ParameterInfo Scope: Any Value Type: AudioUnitParameterInfo Access: The info struct describes the general characteristics of an individual parameterID @constant kAudioUnitProperty_FastDispatch Scope: Global Value Type: void* (function pointer) Access: Read The caller provides the selector for a given audio unit API, and retrieves a function pointer for that selector. For instance, this enables the caller to retrieve the function pointer for the AudioUnitRender call, so that call can be made directly through to the audio unit to avoid the overhead of the ComponentMgr's dispatch. @constant kAudioUnitProperty_CPULoad Scope: Global Value Type: Float64 Access: Read Can be used to retrieve the duty cycle (as a value from 0 to 1) of the render time that an audio unit is spending in its render call. @constant kAudioUnitProperty_StreamFormat Scope: Input / Output Value Type: AudioStreamBasicDescription Access: read/write An AudioStreamBasicDescription is used to specify the basic format for an audio data path. For instance, 2 channels, 44.1KHz, Float32 linear pcm. The value can be both set and retrieve from an I/O element (bus) @constant kAudioUnitProperty_ElementCount Scope: Any (though Global scope will always have and element count of 1) Value Type: UInt32 Access: read/write Most audio units will only implement the read version of this call, thus they would have a fixed bus topology (number of input and output elements/buses). Some audio units possess the capability to add or remove elements, so in that case this property will be writable. @constant kAudioUnitProperty_Latency Scope: Global Value Type: Float64 Access: Read The processing latency (the time it takes an audio unit to represent an input in its audio output) specified in seconds @constant kAudioUnitProperty_SupportedNumChannels Scope: Global Value Type: AUChannelInfo array Access: Read The size of this property will represent the number of AUChannelInfo structs that an audio unit provides. Each entry describes a particular number of channels on any input, matched to a particular number of channels on any output. Thus an entry {2, 2} says the audio unit will support a channel configuration of 2 channels on an input and 2 channels on an output. Negative numbers (-1, -2) are used to indicate *any* number of channels. So {-1, -1} means any number of channels on input and output as long as they are the same. {1, -2} means any number of channels on input or output buses A negative number less than -2 is used to indicate a total number of channels across every bus on that scope, regardless of how many channels are set on any particular bus. Zero on any side (typically only input) means that the audio unit doesn't have any input elements, and is expressing the capability of configuring its output channels. @constant kAudioUnitProperty_MaximumFramesPerSlice Scope: Global Value Type: UInt32 Access: read/write This property is used to describe to an audio unit the maximum number of samples it will be asked to produce on any single given call to audio unit render. If an audio unit can require more or less input data than its output request, then it should limit any given request for input to this number of frames (that is, it should "break up" its input pulls). @constant kAudioUnitProperty_SetExternalBuffer Scope: Global Value Type: AudioUnitExternalBuffer Access: Write This is used to provide to an audio unit a buffer that it can use with its input render callback's audio buffer list @constant kAudioUnitProperty_ParameterValueStrings Scope: Any Value Type: CFArrayRef Access: Read Some audio unit parameters that are of an index type, can also provide names for each value of the parameter. This property returns an array containing CFStrings, where each element in the array is the name that should be used for that parameter value. The size of the array should be the same as the range between the parameters min and max values. The array's strings can then be used to build a menu for that parameter. @constant kAudioUnitProperty_GetUIComponentList Scope: Any Value Type: AudioComponentDescription array Access: Read Presents an array of AudioComponentDescription that are of type 'auvw' (AudioUnitCarbonView). These are the carbon based custom views for that audio unit. @constant kAudioUnitProperty_AudioChannelLayout Scope: Input/Output Value Type: struct AudioChannelLayout Access: read/write Description: Describes for a given scope/element the order of channels within a given stream. The number of channels it describes must match the number of channels set for that scope/element. Each input and output bus in an audio unit can have one instance of this property. Some audio units require this property. For example, the 3DMixer unit must implement this property on its output bus. If a host application attempts to clear the value of this property on a bus that requires a valid value, the audio unit will return a kAudioUnitErr_InvalidPropertyValue error. Input and output buses can be in one of three states in regard to Audio channel layout: 1. implemented and set 2. implemented but not set 3. unimplemented Requesting the value of this property when it is implemented but not set results in a kAudioUnitErr_PropertyNotInUse error. Use the kAudioUnitProperty_AudioChannelLayout property whenever channel layout is relevant. By comparison, the kAudioUnitProperty_StreamFormat property cannot specify channel layout or purpose. See also: kAudioUnitProperty_SupportedChannelLayoutTags, kAudioUnitProperty_StreamFormat. @constant kAudioUnitProperty_TailTime Scope: Global Value Type: Float64 Access: Read The time in seconds that will remain after the last valid input of any audio unit has been processed before the output is silent. For example, this could be the total decay time of a reverb or a delay. In general this will be a conservative estimate. @constant kAudioUnitProperty_BypassEffect Scope: Global Value Type: UInt32 Access: read/write A boolean value that can be used to bypass the processing in an effect unit, so that the input is passed unchanged through to the output @constant kAudioUnitProperty_LastRenderError Scope: Global Value Type: OSStatus Access: Read This property is set if there is an error in AudioUnitRender. The AU will then fire a property changed notification to any listeners on this property and those listeners can then use this property ID to retrieve that error. @constant kAudioUnitProperty_SetRenderCallback Scope: Input Value Type: AURenderCallbackStruct Access: Write This is used to provide the audio unit with input on the specified element (input bus) with audio data from the provided callback. The callback is delivered a buffer list which it must fill in with audio data. If no data is available, it should set the audio data to 0 (silence). In the normal case, f an error is returned, the audio is not processed and the audio unit will return an error from AudioUnitRender. @constant kAudioUnitProperty_FactoryPresets Scope: Global Value Type: CFArray of AUPreset structures Access: Read An array of preset structures that provide a name and number for each preset. A factory preset is then chosen using the PresentPreset property. @constant kAudioUnitProperty_ContextName Scope: Global Value Type: CFString Access: read/write The host can set this as information to the audio unit to describe something about the context within which the audio unit is instantiated. For instance, "track 3" could be set as the context, so that the audio unit's view could then display "My audio unit on track 3" as information to the user of the particular context for any audio unit. @constant kAudioUnitProperty_RenderQuality Scope: Global Value Type: UInt32 Access: read/write A value (0 - 127) that can be used to control the quality (complexity) of the rendering operation. A typical usage is to set render quality to maximum for best quality, but if CPU usage is a concern a lesser quality can be set to trade off render quality. @constant kAudioUnitProperty_HostCallbacks Scope: Global Value Type: HostCallbackInfo Access: Write The audio unit should only call the host callbacks while it is in its render function. The audio unit must provide the client info when calling the callbacks as provided by the host. They are provided as a means for an audio unit to gain information from the host about parameters that may affect its rendering operation. For example, what is the current beat of the host, is the transport running, and so forth. Any of the parameters of the callback function, when called by the audio unit, can be NULL. This indicates that the unit doesn't want to know that particular information. The exception is that the unit must always specify the HostUserData which was be supplied to the unit when the property was set. If the host is unable to provide the requested information then it can return the kAudioUnitErr_CannotDoInCurrentContext error code @constant kAudioUnitProperty_InPlaceProcessing Scope: Global Value Type: UInt32 Access: read/write A property that can be used to determine if the audio unit can process input data on the same data as is provided to it, and if so this can be turned off if the host has a particular buffer management strategy and such an operation would defeat that. @constant kAudioUnitProperty_ElementName Scope: any Value Type: CFStringRef Access: read/write Description: The name of the specified element. The Host owns a reference to this property value (as with all other CF properties), and should release the string retrieved or used when setting. @constant kAudioUnitProperty_CocoaUI Scope: Global Value Type: struct AudioUnitCocoaViewInfo Access: read Publishes the audio unit's custom Cocoa NSViews. The Host can determine how big this structure is by querying the size of the property (i.e., How many alternate UI classes there are for the unit) Typically, most audio units will provide 1 UI class per unit @constant kAudioUnitProperty_SupportedChannelLayoutTags Scope: Input/Output Value Type: AudioChannelLayoutTags[ variable number of elements ] Access: read only Used with GetProperty to ascertain what an audio unit understands about laying out of channel orders. This will normally return one or more of the specified layout tags. When a specific set of layouts are returned, the client then uses the kAudioUnitProperty_AudioChannelLayout property (with one of those layout tags specified) to set the unit to use that layout. In this case the client (and the audio unit when reporting its AudioChannelLayout) is only expected to have set an AudioChannelLayout which only sets the layout tag as the valid field. Custom Channel Maps: Some audio units may return the tag: kAudioChannelLayoutTag_UseChannelDescriptions In this case, the host then can look at supported number of channels on that scope (using the kAudioUnitProperty_SupportedNumChannels), and supply an AudioChannelLayout with the kAudioUnitProperty_AudioChannelLayout property to specify the layout, number of channels and location of each of those channels. This custom channel map MUST have a channel valence that is supported by the Audio Unit. The UseChannelBitmap field is NOT used within the context of the AudioUnit. @constant kAudioUnitProperty_ParameterIDName Scope: any Value Type: AudioUnitParameterNameInfo Access: read An audio unit returns the full parameter name in the GetParameterInfo struct/property. In some display situations however, there may only be room for a few characters, and truncating this full name may give a less than optimal name for the user. Thus, this property can be used to ask the audio unit whether it can supply a truncated name, with the host suggesting a length (number of characters). If the unit returns a longer name than the host requests, that name maybe truncated to the requested characters in display. The unit could return a shorter name than requested as well. The unit returns a CFString that should be released by the host. When using this property, the host asks for the name in the same scope and element as the unit publishes the parameter. @constant kAudioUnitProperty_ParameterClumpName Scope: any Value Type: AudioUnitParameterNameInfo Access: read This works in a similar manner to the ParameterIDName property, except that the inID value is one of the clumpID's that are returned with the audio unit's ParameterInfo structure. @constant kAudioUnitProperty_PresentPreset Scope: Global/Part Value Type: AUPreset Access: read/write This property replaces the deprecated CurrentPreset property, due to the ambiguity of ownership of the CFString of the preset name in the older CurrentPreset property. With PresentPreset the client of the audio unit owns the CFString when it retrieves the preset with PresentPreset and is expected to release this (as with ALL properties that retrieve a CF object from an audio unit). @constant kAudioUnitProperty_OfflineRender Scope: Global Value Type: UInt32 Access: read/write This is used by the host to indicate when an audio unit (that normally operates within a general real-time calling model) is rendering in an offline context. A typical usage of this is to set this to true when the rendering operation an audio unit is being used within is going to write out the results to a file. The value defaults to false, as the common usage of audio units is for real-time processing @constant kAudioUnitProperty_ParameterStringFromValue Scope: any Value Type: AudioUnitParameterStringFromValue Access: read This property is used with parameters that are marked with the kAudioUnitParameterFlag_HasName parameter info flag. This indicates that some (or all) of the values represented by the parameter can and should be represented by a special display string. This is NOT to be confused with kAudioUnitProperty_ParameterValueStrings. That property is used with parameters that are indexed and is typically used for instance to build a menu item of choices for one of several parameter values. kAudioUnitProperty_ParameterStringFromValue can have a continuous range, and merely states to the host that if it is displaying those parameter's values, they should request a name any time any value of the parameter is set when displaying that parameter. For instance (a trivial example), a unit may present a gain parameter in a dB scale, and wish to display its minimum value as "negative infinity". In this case, the audio unit will not return names for any parameter value greater than its minimum value - so the host will then just display the parameter value as is. For values less than or equal to the minimum value, the audio unit will return a string for "negative infinity" which the host can use to display appropriately. A less trivial example might be a parameter that presents its values as seconds. However, in some situations this value should be better displayed in a SMPTE style of display: HH:MM:SS:FF In this case, the audio unit would return a name for any value of the parameter. The GetProperty call is used in the same scope and element as the inParamID that is declared in the struct passed in to this property. If the *inValue member is NULL, then the audio unit should take the current value of the specified parameter. If the *inValue member is NOT NULL, then the audio unit should return the name used for the specified value. On exit, the outName may point to a CFStringRef (which if so must be released by the caller). If the parameter has no special name that should be applied to that parameter value, then outName will be NULL, and the host should display the parameter value as appropriate. @constant kAudioUnitProperty_ParameterValueFromString Scope: any Value Type: AudioUnitParameterValueFromString Access: read This property returns the value of a parameter from its string representation. See kAudioUnitProperty_ParameterStringFromValue. @constant kAudioUnitProperty_IconLocation Scope: Global Value Type: CFURLRef Access: Read A URL that will specify the location of an icon file that can be used when presenting UI for this audio unit. @constant kAudioUnitProperty_PresentationLatency Scope: Input/Output Value Type: Float64 Access: write This property is set by a host to describe to the audio unit the presentation latency of both any of its input and/or output audio data. It describes this latency in seconds. A value of zero means either no latency or an unknown latency. This is a write only property because the host is telling the audio unit the latency of both the data it provides it for input and the latency from getting the data from the unit until it is presented. The property is should be set on each active input and output bus (Scope/Element pair). For example, an audio unit with multiple outputs will have the output data it produces processed by different audio units, etc before it is mixed and presented. Thus, in this case, each output element could have a different presentation latency. This should not be confused with the Latency property, where the audio unit describes to the host any processing latency it introduces between its input and its output. For input: Describes how long ago the audio given to an audio unit was acquired. For instance, when reading from a file to the first audio unit, then its input presentation latency will be zero. When processing audio input from a device, then this initial input latency will be the presentation latency of the device itself, the device's safety offset and latency. The next audio unit's (connected to that first unit) input presentation latency will be the input presentation latency of the first unit, plus the processing latency (as expressed by kAudioUnitProperty_Latency) of the first unit. For output: Describes how long before the output audio of an audio unit is to be presented. For instance, when writing to a file, then the last audio unit's output presentation latency will be zero. When the audio from that audio unit is to be played to an AudioDevice, then that initial presentation latency will be the latency of the device itself - which is the I/O buffer size, and the device's safety offset and latency The previous audio unit's (connected to this last unit) output presentation latency will be that initial presentation latency plus the processing latency (as expressed by kAudioUnitProperty_Latency) of the last unit. So, for a given audio unit anywhere within a mixing graph, the input and output presentation latencies describe to that unit how long from the moment of generation it will take for its input to arrive, and how long it will take for its output to be presented. You can use this property, for example, to provide metering for for an audio unit that is generating output to be presented to the user at a future time. @constant kAudioUnitProperty_DependentParameters Scope: any Value Type: array of AUDependentParameter Access: read This property is used for parameters with the kAudioUnitParameterFlag_IsGlobalMeta or kAudioUnitParameterFlag_IsElementMeta flags set. Hosts applications (and the AudioUnitParameterListener mechanism) can interrogate this property to determine which parameters are dependent on a meta-parameter. For parameters marked with kAudioUnitParameterFlag_IsGlobalMeta, any non-global dependent parameters are assumed to be dependent in every element of their scope. For parameters marked with kAudioUnitParameterFlag_IsElementMeta, then its dependent parameters must all be the same scope, and are assumed to apply only within a single element, not to other instances of the same parameter in other elements. @constant kAudioUnitProperty_AUHostIdentifier Scope: Global Value Type: AUHostVersionIdentifier Access: write Determine which application (and which version) an audio unit is being hosted by. This is made more complex through the intervention of audio units such as Kore, that are hosting other audio units (in this case of course, the real host of the audio unit is the hosting unit, not the host application, so the previous mechanism of getting the main bundle ID is no longer correct). There are also inconsistencies in the way that bundle identifiers are applied (with apps changing these from version to version), and we'd prefer to see a more consistent identifier used with this property. This is in spirit similar to the string returned by CFBundle API, except that we require this host string be consistent and reliable through different revisions of the host. The audio unit is responsible for retaining the hostName string if it needs to use it past the duration of the actual call. The host should set this property as early as possible within the lifetime of the unit in a session. This API used to take a NumVersion struct. It is redefined to take an AUHostVersionIdentifier struct which is binary compatible with the existing usage, but not source compatible. @constant kAudioUnitProperty_MIDIOutputCallbackInfo Scope: Global Value Type: CFArrayRef Access: read The host will also need to determine how many MIDI output streams the audio unit can generate (and the name for each of these outputs). Each MIDI output is a complete MIDI data stream, such as embodied by a MIDIEndpointRef in CoreMIDI. To do, the host uses this property and retrieves an array of CFStringRefs: - the size of the array is the number of MIDI Outputs the audio unit supports - each item in the array is the name for that output at that index The host should release the array when it is finished with it. Once the host has determined the audio unit supports this feature, it then instantiates a callback with the unit that the unit will call with MIDI data (see kAudioUnitProperty_MIDIOutputCallback). @constant kAudioUnitProperty_MIDIOutputCallback Scope: Global Value Type: AUMIDIOutputCallbackStruct Access: write The host sets this property on the audio unit with the callback (and its user data) set appropriately. Operational Parameters: In the render call, just as is the expected usage of the AUHostCallbacks, the audio unit can call the provided callback to provide MIDI data to the host that it will associate with the current AudioUnitRender call in process. The audio unit in the callback provides: - the user data provided by the host when the callback was established - the AudioTimeStamp that was provided to the audio unit for this particular call of AudioUnitRender - the output number to associate this MIDI data with - a MIDI Packet List containing MIDI data. The time stamp values contained within the MIDIPackets in this list are **sample offsets*** from the AudioTimeStamp provided. This allows MIDI data to be time-stamped with a sample offset that is directly associated with the audio data it is generating in the current call to the AudioUnitRender function There is no implied or expected association between the number (or position) of an audio unit's audio or MIDI outputs. @constant kAudioUnitProperty_InputSamplesInOutput Scope: Global Value Type: struct AUInputSamplesInOutputCallbackStruct Access: read/write An audio unit calls this callback at the end of its render call. The audio unit supplies the following information: outputTime - The timestamp passed in to the audio unit's render call. This timestamp represents the time of the first output sample. inputSample - The sample number of the first input sample that is present in the output audio. numInputSamples - The number of input samples that were used and are present in the output audio. This property allows a host application to determine which input samples correspond to a sample in the output buffer. It is useful only for audio units that do time-stretching, such as the AUVarispeed and AUTimePitch units, where the relationship between input and output samples is non-trivial. For these units, the range of input samples that correspond to an output buffer typically differs from the range of input samples that were pulled for that render call. This difference arises because of internal buffering, processing latency, and other factors. @constant kAudioUnitProperty_ClassInfoFromDocument Scope: Global Value Type: CFDictionary Access: read/write If the audio unit implements this property then it is going to do different actions establishing its state from a document rather than from a user preset. Thus, a host app should use this property first (instead of kAudioUnitProperty_ClassInfo) when restoring the state of an audio unit when opening a document. If the audio unit returns an error (or doesn't implement this property) then the host should use the same preset with the kAudioUnitProperty_ClassInfo. @constant kAudioUnitProperty_ShouldAllocateBuffer Scope: input/output elements (settable per element) Value Type: UInt32 Access: read/write By default this value is true. This affects the allocations of the buffers for I/O (the mData field of the AudioBufferList used with AudioUnitRender, callbacks and connections) If true, the element will create a buffer for rendering into. If false, the element will not create a buffer for rendering. For example, if the audio unit is only ever going to have a connection as its input and never a callback, then it should not need to create a buffer (the API contract expects an audio unit to provide a buffer for callbacks, but no buffer for connections). If the audio unit is always going to be pulled for audio with the client providing audio data buffers to the AudioUnitRender call, then it will never need to create an audio buffer on the output side. So, this property can be used to control the default allocation strategy of an audio unit. If the audio unit needs a buffer, but one hasn't been allocated, then an error will be thrown from that call to AudioUnitRender. This property cannot be set on Initialised audio units as it may end up reallocating memory. @constant kAudioUnitProperty_FrequencyResponse Scope: input/output elements (settable per element) Value Type: AudioUnitFrequencyResponseBin Access: read The property provides a way for a user interface view to get points for drawing a graph of the frequency response of the AU. An array of AudioUnitFrequencyResponseBin are passed in to kAudioUnitProperty_FrequencyResponse with the mFrequency field filled in. The array is returned with the mMagnitude fields filled in. If fewer than kNumberOfResponseFrequencies are needed, then the first unused bin should be marked with a negative frequency. @constant kAudioUnitProperty_ParameterHistoryInfo Scope: Global Value Type: AudioUnitParameterHistoryInfo Access: read For parameters which have kAudioUnitParameterFlag_PlotHistory set, getting this property fills out the AudioUnitParameterHistoryInfo struct containing the recommended update rate and history duration. */ enum { // range (0 -> 999) kAudioUnitProperty_ClassInfo = 0, kAudioUnitProperty_MakeConnection = 1, kAudioUnitProperty_SampleRate = 2, kAudioUnitProperty_ParameterList = 3, kAudioUnitProperty_ParameterInfo = 4, kAudioUnitProperty_CPULoad = 6, kAudioUnitProperty_StreamFormat = 8, kAudioUnitProperty_ElementCount = 11, kAudioUnitProperty_Latency = 12, kAudioUnitProperty_SupportedNumChannels = 13, kAudioUnitProperty_MaximumFramesPerSlice = 14, kAudioUnitProperty_ParameterValueStrings = 16, kAudioUnitProperty_AudioChannelLayout = 19, kAudioUnitProperty_TailTime = 20, kAudioUnitProperty_BypassEffect = 21, kAudioUnitProperty_LastRenderError = 22, kAudioUnitProperty_SetRenderCallback = 23, kAudioUnitProperty_FactoryPresets = 24, kAudioUnitProperty_RenderQuality = 26, kAudioUnitProperty_InPlaceProcessing = 29, kAudioUnitProperty_ElementName = 30, kAudioUnitProperty_SupportedChannelLayoutTags = 32, kAudioUnitProperty_PresentPreset = 36, kAudioUnitProperty_ShouldAllocateBuffer = 51, kAudioUnitProperty_ParameterHistoryInfo = 53 #if !TARGET_OS_IPHONE , kAudioUnitProperty_FastDispatch = 5, kAudioUnitProperty_SetExternalBuffer = 15, kAudioUnitProperty_GetUIComponentList = 18, kAudioUnitProperty_ContextName = 25, kAudioUnitProperty_HostCallbacks = 27, kAudioUnitProperty_CocoaUI = 31, kAudioUnitProperty_ParameterIDName = 34, kAudioUnitProperty_ParameterClumpName = 35, kAudioUnitProperty_ParameterStringFromValue = 33, kAudioUnitProperty_OfflineRender = 37, kAudioUnitProperty_ParameterValueFromString = 38, kAudioUnitProperty_IconLocation = 39, kAudioUnitProperty_PresentationLatency = 40, kAudioUnitProperty_DependentParameters = 45, kAudioUnitProperty_AUHostIdentifier = 46, kAudioUnitProperty_MIDIOutputCallbackInfo = 47, kAudioUnitProperty_MIDIOutputCallback = 48, kAudioUnitProperty_InputSamplesInOutput = 49, kAudioUnitProperty_ClassInfoFromDocument = 50, kAudioUnitProperty_FrequencyResponse = 52 #endif }; /*! @abstract Keys contains in an audio unit preset (ClassInfo) dictionary @discussion These strings are used as keys in the AUPreset-"classInfo" dictionary The actual keys are CFStrings to use these keys you define the key as: static const CFStringRef kMyVersionString = CFSTR(kAUPresetVersionKey); */ #define kAUPresetVersionKey "version" #define kAUPresetTypeKey "type" #define kAUPresetSubtypeKey "subtype" #define kAUPresetManufacturerKey "manufacturer" #define kAUPresetDataKey "data" #define kAUPresetNameKey "name" #define kAUPresetRenderQualityKey "render-quality" #define kAUPresetCPULoadKey "cpu-load" #define kAUPresetElementNameKey "element-name" #define kAUPresetExternalFileRefs "file-references" #if !TARGET_OS_IPHONE // these are keys to use when a preset contains data from other plugin formats // vstdata is used to signify VST state from a vst "bank" #define kAUPresetVSTDataKey "vstdata" // vstpreset is used to signify VST state from a vst "preset" #define kAUPresetVSTPresetKey "vstpreset" #define kAUPresetMASDataKey "masdata" #endif /*! @defined kAUPresetPartKey @discussion This key if present, distinguishes a global preset that is set on the global scope with a part-based preset that is set on the part scope. The value of this key is audio unit defined */ #define kAUPresetPartKey "part" /*! @struct AudioUnitConnection @abstract This structure contains the information needed to make a connection between a source and destination audio unit. @discussion The structure is set on the destination audio unit's input element @field sourceAudioUnit The audio unit that is the source for the connection @field sourceOutputNumber The source audio unit's output element to be used in the connection @field destInputNumber The destination audio unit's input element to be used in the connection */ typedef struct AudioUnitConnection { AudioUnit sourceAudioUnit; UInt32 sourceOutputNumber; UInt32 destInputNumber; } AudioUnitConnection; /*! @struct AUChannelInfo @abstract Define an audio unit's channel handling capabilities */ typedef struct AUChannelInfo { SInt16 inChannels; SInt16 outChannels; } AUChannelInfo; /*! @struct AudioUnitExternalBuffer @abstract Allow a host to tell an audio unit to use the provided memory for its input callback */ typedef struct AudioUnitExternalBuffer { Byte * buffer; UInt32 size; } AudioUnitExternalBuffer; /*! @struct AURenderCallbackStruct @abstract Used by a host when registering a callback with the audio unit to provide input */ typedef struct AURenderCallbackStruct { AURenderCallback inputProc; void * inputProcRefCon; } AURenderCallbackStruct; /*! @struct AUPreset @abstract Used to publish and set factory presets on an audio unit @field presetNumber If < 0, then preset is a user preset If >= 0, then this field is used to select the factory preset @field presetName If a factory preset, the name of the specified factory preset */ typedef struct AUPreset { SInt32 presetNumber; CFStringRef presetName; } AUPreset; /*! @enum RenderQuality @abstract Used to get/set a render quality setting on an audio unit @discussion Typically, this property is used to trade-off between CPU usage, latency and the quality of the audio unit's processing/output. */ enum { kRenderQuality_Max = 0x7F, kRenderQuality_High = 0x60, kRenderQuality_Medium = 0x40, kRenderQuality_Low = 0x20, kRenderQuality_Min = 0 }; #if !TARGET_OS_IPHONE /*! @enum kNumberOfResponseFrequencies @abstract The maximum number of frequency response bins for kAudioUnitProperty_FrequencyResponse. @discussion An array of AudioUnitFrequencyResponseBin are passed in to kAudioUnitProperty_FrequencyResponse with the mFrequency field filled in. The array is returned with the mMagnitude fields filled in. If fewer than kNumberOfResponseFrequencies are needed, then the first unused bin should be marked with a negative frequency. */ enum { kNumberOfResponseFrequencies = 1024 }; /*! @struct AudioUnitFrequencyResponseBin @abstract Structure used to get the magnitude of the frequency response at a particular frequency via kAudioUnitProperty_FrequencyResponse. @discussion An array of AudioUnitFrequencyResponseBin are passed in to kAudioUnitProperty_FrequencyResponse with the mFrequency field filled in. The array is returned with the mMagnitude fields filled in. If fewer than kNumberOfResponseFrequencies are needed, then the first unused bin should be marked with a negative frequency. */ typedef struct AudioUnitFrequencyResponseBin { Float64 mFrequency; Float64 mMagnitude; } AudioUnitFrequencyResponseBin; /*! @typedef HostCallback_GetBeatAndTempo @abstract Retrieve information about the current beat and/or tempo @discussion If the host app has set this callback, then the audio unit can use this to get the current beat and tempo as they relate to the first sample in the render buffer. The audio unit can call this callback only from within the audio unit render call (otherwise the host is unable to provide information accurately to the audio unit as the information obtained is relate to the current AudioUnitRender call). If the host cannot provide the requested information, it will return kAudioUnitErr_CannotDoInCurrentContext. The AudioUnit can provide NULL for any of the requested parameters (except for inHostUserData) if it is not interested in that particular piece of information @param inHostUserData Must be provided by the audio unit when it makes this call. It is the client data provided by the host when it set the HostCallbacks property @param outCurrentBeat The current beat, where 0 is the first beat. Tempo is defined as the number of whole-number (integer) beat values (as indicated by the outCurrentBeat field) per minute. @param outCurrentTempo The current tempo */ typedef OSStatus (*HostCallback_GetBeatAndTempo) (void *inHostUserData, Float64 *outCurrentBeat, Float64 *outCurrentTempo); /*! @typedef HostCallback_GetMusicalTimeLocation @abstract Retrieve information about the musical time state of the host @discussion If the host app has set this callback, then the audio unit can use this to obtain information about the state of musical time in the host. The audio unit can call this callback only from within the audio unit render call (otherwise the host is unable to provide information accurately to the audio unit as the information obtained is relate to the current AudioUnitRender call). If the host cannot provide the requested information, it will return kAudioUnitErr_CannotDoInCurrentContext. The AudioUnit can provide NULL for any of the requested parameters (except for inHostUserData) if it is not interested in that particular piece of information @param inHostUserData Must be provided by the audio unit when it makes this call. It is the client data provided by the host when it set the HostCallbacks property @param outDeltaSampleOffsetToNextBeat The number of samples until the next whole beat from the start sample of the current rendering buffer @param outTimeSig_Numerator The Numerator of the current time signature @param outTimeSig_Denominator The Denominator of the current time signature (4 is a quarter note, etc) @param outCurrentMeasureDownBeat The beat that corresponds to the downbeat (first beat) of the current measure that is being rendered */ typedef OSStatus (*HostCallback_GetMusicalTimeLocation) (void *inHostUserData, UInt32 *outDeltaSampleOffsetToNextBeat, Float32 *outTimeSig_Numerator, UInt32 *outTimeSig_Denominator, Float64 *outCurrentMeasureDownBeat); /*! @typedef HostCallback_GetTransportState @abstract Retrieve information about the time line's (or transport) state of the host. @discussion If the host app has set this callback, then the audio unit can use this to obtain information about the transport state of the host's time line. The audio unit can call this callback only from within the audio unit render call (otherwise the host is unable to provide information accurately to the audio unit as the information obtained is relate to the current AudioUnitRender call. If the host cannot provide the requested information, it will return kAudioUnitErr_CannotDoInCurrentContext. The AudioUnit can provide NULL for any of the requested parameters (except for inHostUserData) if it is not interested in that particular piece of information @param inHostUserData Must be provided by the audio unit when it makes this call. It is the client data provided by the host when it set the HostCallbacks property @param outIsPlaying Returns true if the host's transport is currently playing, false if stopped @param outTransportStateChanged Returns true if there was a change to the state of, or discontinuities in, the host's transport (generally since the callback was last called). Can indicate such state changes as start/top, time moves (jump from one time line to another). @param outCurrentSampleInTimeLine Returns the current sample count in the time line of the host's transport time. @param outIsCycling Returns true if the host's transport is currently cycling or looping @param outCycleStartBeat If cycling is true, the start beat of the cycle or loop point in the host's transport @param outCycleEndBeat If cycling is true, the end beat of the cycle or loop point in the host's transport */ typedef OSStatus (*HostCallback_GetTransportState) (void *inHostUserData, Boolean *outIsPlaying, Boolean *outTransportStateChanged, Float64 *outCurrentSampleInTimeLine, Boolean *outIsCycling, Float64 *outCycleStartBeat, Float64 *outCycleEndBeat); /*! @struct HostCallbackInfo @abstract Contains the various callbacks (or NULL) for an audio unit to call */ typedef struct HostCallbackInfo { void * hostUserData; HostCallback_GetBeatAndTempo beatAndTempoProc; HostCallback_GetMusicalTimeLocation musicalTimeLocationProc; HostCallback_GetTransportState transportStateProc; } HostCallbackInfo; /*! @struct AudioUnitCocoaViewInfo @abstract The name and how many, NSView objects an audio unit publishes as a custom Cocoa view. @field mCocoaAUViewBundleLocation Contains the location of the bundle which the host app can then use to locate the bundle @field mCocoaAUViewClass Contains the names of the classes that implements the required protocol for an AUView */ typedef struct AudioUnitCocoaViewInfo { CFURLRef mCocoaAUViewBundleLocation; CFStringRef mCocoaAUViewClass[1]; } AudioUnitCocoaViewInfo; /*! @struct AUDependentParameter @abstract Used to represent a dependent parameter that can change as a result of its parent meta-parameter changing */ typedef struct AUDependentParameter { AudioUnitScope mScope; AudioUnitParameterID mParameterID; } AUDependentParameter; /*! @struct AUHostVersionIdentifier @abstract Used to describe the name and version of the audio unit's host */ typedef struct AUHostVersionIdentifier { CFStringRef hostName; UInt32 hostVersion; } AUHostVersionIdentifier; /*! @struct MIDIPacketList @abstract Forward declaration of MIDIPacketList found in */ struct MIDIPacketList; /* @typedef AUMIDIOutputCallback @abstract A callback used by an audio unit to provide MIDI data to a host application */ typedef OSStatus (*AUMIDIOutputCallback)(void * userData, const AudioTimeStamp * timeStamp, UInt32 midiOutNum, const struct MIDIPacketList * pktlist); /*! @struct AUMIDIOutputCallbackStruct @abstract Set by host application to provide the callback and user data for an audio unit that provides MIDI output */ typedef struct AUMIDIOutputCallbackStruct { AUMIDIOutputCallback midiOutputCallback; void* userData; } AUMIDIOutputCallbackStruct; /*! @struct AUInputSamplesInOutputCallbackStruct @abstract Used by a host when registering a callback with an audio unit, to provide input-to-output samples mapping */ typedef struct AUInputSamplesInOutputCallbackStruct { AUInputSamplesInOutputCallback inputToOutputCallback; void * userData; } AUInputSamplesInOutputCallbackStruct; #endif //!TARGET_OS_IPHONE /*! @struct AudioUnitParameterHistoryInfo @abstract This structure contains the suggested update rate and history duration for parameters which have the kAudioUnitParameterFlag_PlotHistory flag set. The structure is filled out by getting kAudioUnitProperty_ParameterHistoryInfo. @field updatesPerSecond This is the number of times per second that it is suggested that the host get the value of this parameter. @field historyDurationInSeconds This is the duration in seconds of history that should be plotted. */ typedef struct AudioUnitParameterHistoryInfo { Float32 updatesPerSecond; Float32 historyDurationInSeconds; } AudioUnitParameterHistoryInfo; //===================================================================================================================== #pragma mark - Parameter Definitions // assume kAudioUnitParameterUnit_Generic if not found in this enum /*! @enum AudioUnitParameterUnit @constant kAudioUnitParameterUnit_Generic untyped value generally between 0.0 and 1.0 @constant kAudioUnitParameterUnit_Indexed takes an integer value (good for menu selections) @constant kAudioUnitParameterUnit_Boolean 0.0 means FALSE, non-zero means TRUE @constant kAudioUnitParameterUnit_Percent usually from 0 -> 100, sometimes -50 -> +50 @constant kAudioUnitParameterUnit_Seconds absolute or relative time @constant kAudioUnitParameterUnit_SampleFrames one sample frame equals (1.0/sampleRate) seconds @constant kAudioUnitParameterUnit_Phase -180 to 180 degrees @constant kAudioUnitParameterUnit_Rate rate multiplier, for playback speed, etc. (e.g. 2.0 == twice as fast) @constant kAudioUnitParameterUnit_Hertz absolute frequency/pitch in cycles/second @constant kAudioUnitParameterUnit_Cents unit of relative pitch @constant kAudioUnitParameterUnit_RelativeSemiTones useful for coarse detuning @constant kAudioUnitParameterUnit_MIDINoteNumber absolute pitch as defined in the MIDI spec (exact freq may depend on tuning table) @constant kAudioUnitParameterUnit_MIDIController a generic MIDI controller value from 0 -> 127 @constant kAudioUnitParameterUnit_Decibels logarithmic relative gain @constant kAudioUnitParameterUnit_LinearGain linear relative gain @constant kAudioUnitParameterUnit_Degrees -180 to 180 degrees, similar to phase but more general (good for 3D coord system) @constant kAudioUnitParameterUnit_EqualPowerCrossfade 0 -> 100, crossfade mix two sources according to sqrt(x) and sqrt(1.0 - x) @constant kAudioUnitParameterUnit_MixerFaderCurve1 0.0 -> 1.0, pow(x, 3.0) -> linear gain to simulate a reasonable mixer channel fader response @constant kAudioUnitParameterUnit_Pan standard left to right mixer pan @constant kAudioUnitParameterUnit_Meters distance measured in meters @constant kAudioUnitParameterUnit_AbsoluteCents absolute frequency measurement : if f is freq in hertz then absoluteCents = 1200 * log2(f / 440) + 6900 @constant kAudioUnitParameterUnit_Octaves octaves in relative pitch where a value of 1 is equal to 1200 cents @constant kAudioUnitParameterUnit_BPM beats per minute, ie tempo @constant kAudioUnitParameterUnit_Beats time relative to tempo, i.e., 1.0 at 120 BPM would equal 1/2 a second @constant kAudioUnitParameterUnit_Milliseconds parameter is expressed in milliseconds @constant kAudioUnitParameterUnit_Ratio for compression, expansion ratio, etc. @constant kAudioUnitParameterUnit_CustomUnit this is the parameter unit type for parameters that present a custom unit name */ enum { kAudioUnitParameterUnit_Generic = 0, kAudioUnitParameterUnit_Indexed = 1, kAudioUnitParameterUnit_Boolean = 2, kAudioUnitParameterUnit_Percent = 3, kAudioUnitParameterUnit_Seconds = 4, kAudioUnitParameterUnit_SampleFrames = 5, kAudioUnitParameterUnit_Phase = 6, kAudioUnitParameterUnit_Rate = 7, kAudioUnitParameterUnit_Hertz = 8, kAudioUnitParameterUnit_Cents = 9, kAudioUnitParameterUnit_RelativeSemiTones = 10, kAudioUnitParameterUnit_MIDINoteNumber = 11, kAudioUnitParameterUnit_MIDIController = 12, kAudioUnitParameterUnit_Decibels = 13, kAudioUnitParameterUnit_LinearGain = 14, kAudioUnitParameterUnit_Degrees = 15, kAudioUnitParameterUnit_EqualPowerCrossfade = 16, kAudioUnitParameterUnit_MixerFaderCurve1 = 17, kAudioUnitParameterUnit_Pan = 18, kAudioUnitParameterUnit_Meters = 19, kAudioUnitParameterUnit_AbsoluteCents = 20, kAudioUnitParameterUnit_Octaves = 21, kAudioUnitParameterUnit_BPM = 22, kAudioUnitParameterUnit_Beats = 23, kAudioUnitParameterUnit_Milliseconds = 24, kAudioUnitParameterUnit_Ratio = 25, kAudioUnitParameterUnit_CustomUnit = 26 }; /*! @typedef AudioUnitParameterUnit */ typedef UInt32 AudioUnitParameterUnit; /*! @struct AudioUnitParameterInfo @field name UNUSED - set to zero - UTF8 encoded C string (originally). @field unitName only valid if kAudioUnitParameterUnit_CustomUnit is set. If kAudioUnitParameterUnit_CustomUnit is set, this field must contain a valid CFString. @field clumpID only valid if kAudioUnitParameterFlag_HasClump @field cfNameString only valid if kAudioUnitParameterFlag_HasCFNameString @field unit if the "unit" field contains a value not in the enum above, then assume kAudioUnitParameterUnit_Generic @field minValue @field maxValue @field defaultValue @field flags Due to some vagaries about the ways in which Parameter's CFNames have been described, it was necessary to add a flag: kAudioUnitParameterFlag_CFNameRelease In normal usage a parameter name is essentially a static object, but sometimes an audio unit will generate parameter names dynamically.. As these are expected to be CFStrings, in that case the host should release those names when it is finished with them, but there was no way to communicate this distinction in behavior. Thus, if an audio unit will (or could) generate a name dynamically, it should set this flag in the parameter's info. The host should check for this flag, and if present, release the parameter name when it is finished with it. */ typedef struct AudioUnitParameterInfo { char name[52]; CFStringRef unitName; UInt32 clumpID; CFStringRef cfNameString; AudioUnitParameterUnit unit; AudioUnitParameterValue minValue; AudioUnitParameterValue maxValue; AudioUnitParameterValue defaultValue; UInt32 flags; } AudioUnitParameterInfo; /*! @enum Audio Unit Parameter Flags @discussion Bit positions 18, 17, and 16 are set aside for display scales. Bit 19 is reserved. @constant kAudioUnitParameterFlag_CFNameRelease @constant kAudioUnitParameterFlag_PlotHistory @constant kAudioUnitParameterFlag_MeterReadOnly @constant kAudioUnitParameterFlag_DisplayMask @constant kAudioUnitParameterFlag_DisplaySquareRoot @constant kAudioUnitParameterFlag_DisplaySquared @constant kAudioUnitParameterFlag_DisplayCubed @constant kAudioUnitParameterFlag_DisplayCubeRoot @constant kAudioUnitParameterFlag_DisplayExponential @constant kAudioUnitParameterFlag_HasClump @constant kAudioUnitParameterFlag_ValuesHaveStrings @constant kAudioUnitParameterFlag_DisplayLogarithmic @constant kAudioUnitParameterFlag_IsHighResolution @constant kAudioUnitParameterFlag_NonRealTime @constant kAudioUnitParameterFlag_CanRamp @constant kAudioUnitParameterFlag_ExpertMode @constant kAudioUnitParameterFlag_HasCFNameString @constant kAudioUnitParameterFlag_IsGlobalMeta @constant kAudioUnitParameterFlag_IsElementMeta @constant kAudioUnitParameterFlag_IsReadable @constant kAudioUnitParameterFlag_IsWritable */ enum { kAudioUnitParameterFlag_CFNameRelease = (1L << 4), kAudioUnitParameterFlag_PlotHistory = (1L << 14), kAudioUnitParameterFlag_MeterReadOnly = (1L << 15), // bit positions 18,17,16 are set aside for display scales. bit 19 is reserved. kAudioUnitParameterFlag_DisplayMask = (7L << 16) | (1L << 22), kAudioUnitParameterFlag_DisplaySquareRoot = (1L << 16), kAudioUnitParameterFlag_DisplaySquared = (2L << 16), kAudioUnitParameterFlag_DisplayCubed = (3L << 16), kAudioUnitParameterFlag_DisplayCubeRoot = (4L << 16), kAudioUnitParameterFlag_DisplayExponential = (5L << 16), kAudioUnitParameterFlag_HasClump = (1L << 20), kAudioUnitParameterFlag_ValuesHaveStrings = (1L << 21), kAudioUnitParameterFlag_DisplayLogarithmic = (1L << 22), kAudioUnitParameterFlag_IsHighResolution = (1L << 23), kAudioUnitParameterFlag_NonRealTime = (1L << 24), kAudioUnitParameterFlag_CanRamp = (1L << 25), kAudioUnitParameterFlag_ExpertMode = (1L << 26), kAudioUnitParameterFlag_HasCFNameString = (1L << 27), kAudioUnitParameterFlag_IsGlobalMeta = (1L << 28), kAudioUnitParameterFlag_IsElementMeta = (1L << 29), kAudioUnitParameterFlag_IsReadable = (1L << 30), kAudioUnitParameterFlag_IsWritable = (1L << 31) }; /*! @enum Audio Unit Clump ID @discussion Audio unit developers should not use a clump ID of 0. This value is reserved for system use. */ enum { kAudioUnitClumpID_System = 0 }; /*! @define GetAudioUnitParameterDisplayType */ #define GetAudioUnitParameterDisplayType(flags) \ ((flags) & kAudioUnitParameterFlag_DisplayMask) /*! @define AudioUnitDisplayTypeIsLogarithmic */ #define AudioUnitDisplayTypeIsLogarithmic(flags) \ (GetAudioUnitParameterDisplayType(flags) == kAudioUnitParameterFlag_DisplayLogarithmic) /*! @define AudioUnitDisplayTypeIsSquareRoot */ #define AudioUnitDisplayTypeIsSquareRoot(flags) \ (GetAudioUnitParameterDisplayType(flags) == kAudioUnitParameterFlag_DisplaySquareRoot) /*! @define AudioUnitDisplayTypeIsSquared */ #define AudioUnitDisplayTypeIsSquared(flags) \ (GetAudioUnitParameterDisplayType(flags) == kAudioUnitParameterFlag_DisplaySquared) /*! @define AudioUnitDisplayTypeIsCubed */ #define AudioUnitDisplayTypeIsCubed(flags) \ (GetAudioUnitParameterDisplayType(flags) == kAudioUnitParameterFlag_DisplayCubed) /*! @define AudioUnitDisplayTypeIsCubeRoot */ #define AudioUnitDisplayTypeIsCubeRoot(flags) \ (GetAudioUnitParameterDisplayType(flags) == kAudioUnitParameterFlag_DisplayCubeRoot) /*! @define AudioUnitDisplayTypeIsExponential */ #define AudioUnitDisplayTypeIsExponential(flags) \ (GetAudioUnitParameterDisplayType(flags) == kAudioUnitParameterFlag_DisplayExponential) /*! @define SetAudioUnitParameterDisplayType */ #define SetAudioUnitParameterDisplayType(flags, displayType) \ (((flags) & ~kAudioUnitParameterFlag_DisplayMask) | (displayType)) #if !TARGET_OS_IPHONE /* The following properties are used with display names and are only available in the full desktop environment */ /*! @enum Audio Unit Parameter Full Name @discussion Used with the AudioUnitParameterNameInfo.inDesiredLength field to indicate the full name of the requested parameter. */ enum { kAudioUnitParameterName_Full = -1 }; /*! @struct AudioUnitParameterNameInfo @abstract Used to provide shorter names for a specified parameter */ typedef struct AudioUnitParameterNameInfo { AudioUnitParameterID inID; SInt32 inDesiredLength; CFStringRef outName; } AudioUnitParameterIDName; /*! @struct AudioUnitParameterStringFromValue @abstract Provide a string representation of a parameter's value */ typedef struct AudioUnitParameterStringFromValue { AudioUnitParameterID inParamID; const AudioUnitParameterValue * inValue; CFStringRef outString; } AudioUnitParameterStringFromValue; /*! @struct AudioUnitParameterValueFromString @abstract Provide the parameter's value for a given string representation of it */ typedef struct AudioUnitParameterValueFromString { AudioUnitParameterID inParamID; CFStringRef inString; AudioUnitParameterValue outValue; } AudioUnitParameterValueFromString; #endif //!TARGET_OS_IPHONE //===================================================================================================================== #pragma mark - Configuration Info Keys // These strings are used as keys to the dictionary of configuration info returned by // AudioComponentGetConfiguationInfo(). Informaton about them is presented inline with the // declaration. /*! @define kAudioUnitConfigurationInfo_HasCustomView @discussion This is a boolean value that indicates whether or not the AU has a custom view */ #define kAudioUnitConfigurationInfo_HasCustomView "HasCustomView" /*! @define kAudioUnitConfigurationInfo_ChannelConfigurations @discussion This is an array of pairs of values where each item in the array is an array of two numbers and is the equivalent of an AUChannelInfo. If the AudioUnit is an effect and it doesn't implement kAudioUnitProperty_SupportedNumChannels, the array will contain only the single entry, { -1, -1}. If the AudioUnit is an instrument or a generator and doesn't implement kAudioUnitProperty_SupportedNumChannels, the array will be empty and means that the AU's initial state is all that is supported. */ #define kAudioUnitConfigurationInfo_ChannelConfigurations "ChannelConfigurations" /*! @define kAudioUnitConfigurationInfo_InitialInputs @discussion An array of numbers whose size is equal to the number of input buses posessed by the AU. Each number in the array represents the number of channels for the corresponding bus. */ #define kAudioUnitConfigurationInfo_InitialInputs "InitialInputs" /*! @define kAudioUnitConfigurationInfo_InitialOutputs @discussion An array of numbers whose size is equal to the number of output buses posessed by the AU. Each number in the array represents the number of channels for the corresponding bus. */ #define kAudioUnitConfigurationInfo_InitialOutputs "InitialOutputs" //===================================================================================================================== #pragma mark - Output Unit /*! @enum Output Unit Properties @abstract The collection of properties for output units @constant kAudioOutputUnitProperty_IsRunning @discussion Scope: Value Type: Access: */ enum { // range (2000 -> 2999) kAudioOutputUnitProperty_IsRunning = 2001 }; #pragma mark - #pragma mark Desktop Availability #if !TARGET_OS_IPHONE //===================================================================================================================== #pragma mark - Music Effects and Instruments /*! @enum Music Effect and Instrument Unit (MusicDevice) Properties @abstract The collection of Music Effects and Instrument Unit Property IDs @discussion These properties are used to: Describe a current set of mappings between MIDI messages and Parameter value setting Create a mapping between a parameter and a MIDI message through either: - explicitly adding (or removing) the mapping - telling the audio unit to hot-map the next MIDI message to a specified Parameter The same MIDI Message can map to one or more parameters These properties normally apply only to the two types of audio units that implement the MIDI API, instrument units ('aumu') and music effects ('aumf'). These properties are used in the Global scope. The scope and element members of the structure describe the scope and element of the parameter. In all usages, mScope, mElement and mParameterID must be correctly specified. * The AUParameterMIDIMapping Structure Command mStatus mData1 Note Off 0x8n Note Num Note On 0x9n Note Num Key Pressure 0xAn Note Num Control Change 0xBn ControllerID Patch Change 0xCn Patch Num Channel Pressure DxDn 0 (Unused) Pitch Bend 0xEn 0 (Unused) (where n is 0-0xF to correspond to MIDI channels 1-16) Details: In general MIDI Commands can be mapped to either a specific channel as specified in the mStatus bit. If the kAUParameterMIDIMapping_AnyChannelFlag bit is set mStatus is a MIDI channel message, then the MIDI channel number in the status byte is ignored; the mapping is from the specified MIDI message on ANY channel. For note commands (note on, note off, key pressure), the MIDI message can trigger either with just a specific note number, or any note number if the kAUParameterMIDIMapping_AnyNoteFlag bit is set. In these instances, the note number is used as the trigger value (for instance, a note message could be used to set the cut off frequency of a filter). When the parameter mapping list changes through addition/replace, removal, the implementation should fire a notification on the kAudioUnitProperty_AllParameterMIDIMappings property. The host can then retrieve the full set of mappings for the audio unit. When a hot mapping is made, the notification should just be delivered for the HotMap property. The host can retrieve the last current hot mapping made through getting the value of that property. @constant kAudioUnitProperty_AllParameterMIDIMappings @discussion Scope: any Value Type: array of AUParameterMIDIMapping Access: read/write This property allows setting and retrieving the current mapping state between (some/many/all of) an audio unit's parameters and MIDI messages. When set, it should replace any previous mapped settings the audio unit had. If this property is implemented by a non-MIDI capable audio unit (such as an 'aufx' type), then the property is read only and should recommend a suggested set of mappings for the host to perform. In this case, it is the host's responsibility to map MIDI message to the audio unit parameters. This property's size varies depending on the number of mappings currently in effect. A host application should always get the size of this property before retrieving it. The audio unit should return an error if the host doesn't provide enough space to return all of the current mappings. @constant kAudioUnitProperty_AddParameterMIDIMapping @discussion Scope: any Value Type: array of AUParameterMIDIMapping Access: write Use this property to add parameter-to-MIDI mappings to an audio unit's existing set of mappings. There can be only one mapping per parameter. When you set a mapping for a parameter, it replaces the previous mapping. @constant kAudioUnitProperty_RemoveParameterMIDIMapping @discussion Scope: any Value Type: array of AUParameterMIDIMapping Access: write Use this property to remove mappings from an audio unit. If a mapping is specified that does not currently exist in an audio unit, then the audio unit should ignore the request. The Scope/Element/ParameterID is used to find the mapping to remove. @constant kAudioUnitProperty_HotMapParameterMIDIMapping @discussion Scope: any Value Type: AUParameterMIDIMapping Access: read/write This property can be used in two ways, determined by the value supplied by the host application. (1) If a mapping structure is provided, then that structure provides all the information that the audio unit should use to map the parameter, except for the MIDI message. The audio unit should then listen for the next MIDI message and associate that MIDI message with the supplied parameter mapping. When this MIDI message is received and the mapping made, the audio unit should also issue a notification on this property to indicate to the host that the mapping has been made. The host can then retrieve the mapping that was made by getting the value of this property. To avoid possible confusion, it is recommended that once the host has retrieved this mapping (if it is presenting a user interface to describe the mappings, for example), that the host should then clear the mapping state, as described in (2). The only time this property will return a valid value is when an audio unit has implemented the requested mapping. If the audio unit's mapping state has been cleared (or if it has not been asked to make a mapping), then the audio unit should return a kAudioUnitErr_InvalidPropertyValue error when the host tries to read this property's value. (2) If the value passed in this property is NULL, and if the audio unit had a parameter that it was in the process of mapping, the audio unit should disregard the parameter mapping request and discard the partially mapped structure. If the value is NULL and the audio unit is not in the process of mapping, the audio unit can just ignore the request. At all times, the _AllMappings property will completely describe the current known state of an audio unit's mappings of MIDI messages to parameters. */ enum { kAudioUnitProperty_AllParameterMIDIMappings = 41, kAudioUnitProperty_AddParameterMIDIMapping = 42, kAudioUnitProperty_RemoveParameterMIDIMapping = 43, kAudioUnitProperty_HotMapParameterMIDIMapping = 44 }; /*! @enum ParameterMIDIMappings @abstract General defined values to customize the behavior of parameter-to-MIDI mappings @constant kAUParameterMIDIMapping_AnyChannelFlag @discussion If this flag is set and the value of the mStatus field is a MIDI channel message, then the MIDI channel number in the status byte is ignored; the mapping is from the specified MIDI message on any channel. @constant kAUParameterMIDIMapping_AnyNoteFlag @discussion If this flag is set and the value of the mStatus field is a Note On, Note Off, or Polyphonic Pressure message, the message's note number is ignored. The mapping is from any note number. @constant kAUParameterMIDIMapping_SubRange @discussion Set this flag if the MIDI control should map only to a sub-range of the parameter's value. Then specify that range in the mSubRangeMin and mSubRangeMax member fields. @constant kAUParameterMIDIMapping_Toggle @discussion Intended for Boolean typed parameters. When this property is set, it means that the parameter's value should be toggled when the mapped MIDI message is received. For example, if the parameter's value is currently TRUE, when the mapped MIDI message is received the value changes to FALSE. @constant kAUParameterMIDIMapping_Bipolar @discussion This property is useful when mapping a parameter to a MIDI Controller. When set, it indicates that the parameter can assume only two values: on or off. For this reason, a parameter associated with this property is typically Boolean. For example, if this property is set for a parameter mapped to a sustain pedal MIDI controller, controller values from 0 to 64 result in the parameter switched to its "off" state; controller values from 65 to 127 result in the parameter switched to its "on" state. This property works in connection with the kAUParameterMIDIMapping_Bipolar_On property. The value of the kAUParameterMIDIMapping_Bipolar_On property @constant kAUParameterMIDIMapping_Bipolar_On @discussion Determines whether the "on" state of a parameter is mapped to the "on" or "off" state of the associated MIDI controller. Only valid if the kAUParameterMIDIMapping_Bipolar property is set. */ enum { kAUParameterMIDIMapping_AnyChannelFlag = (1L << 0), kAUParameterMIDIMapping_AnyNoteFlag = (1L << 1), kAUParameterMIDIMapping_SubRange = (1L << 2), kAUParameterMIDIMapping_Toggle = (1L << 3), kAUParameterMIDIMapping_Bipolar = (1L << 4), kAUParameterMIDIMapping_Bipolar_On = (1L << 5) }; /*! @struct AUParameterMIDIMapping @abstract Represents a mapping between a MIDI message and an audio unit's parameter. @discussion The reserved fields in this structure are for future use. In the current implementation, they help align the structure to 64 bit size. Do not use the names of these fields in a host application. They are subject to change. */ typedef struct AUParameterMIDIMapping { AudioUnitScope mScope; AudioUnitElement mElement; AudioUnitParameterID mParameterID; UInt32 mFlags; AudioUnitParameterValue mSubRangeMin; AudioUnitParameterValue mSubRangeMax; UInt8 mStatus; UInt8 mData1; UInt8 reserved1; // MUST be set to zero UInt8 reserved2; // MUST be set to zero UInt32 reserved3; // MUST be set to zero } AUParameterMIDIMapping; //===================================================================================================================== #pragma mark - Music Device /*! @enum Instrument Unit (MusicDevice) Properties @abstract The collection of Instrument Unit Property IDs @constant kMusicDeviceProperty_InstrumentCount @discussion Scope: Global Value Type: UInt32 Access: read For a mono-timbral music instrument, this property should return 0 (it should be implemented). For a multi-timbral music instrument, this property can return the number of independent patches that are available to be chosen as an active patch for the instrument. For instance, for Apple's DLS Music Device this value returns the number of patches that are found in a given DLS or SoundFont file when loaded. @constant kMusicDeviceProperty_MIDIXMLNames @discussion Scope: Value Type: Access: @constant kMusicDeviceProperty_PartGroup @discussion Scope: Part Value Type: AudioUnitElement Access: read/write This property's value specifies the group ID (the Group scope's element) that the part is (or should be) assigned to. The property is used in the Part scope, where the element ID is the part that is being queried (or assigned). This property may be implemented in an audio unit as read only, as writeable only if the audio unit is uninitialized, or as read/write. Apple recommends that it should be writable at any time. The effect of assigning a new group to a part is undefined. Typically, however, it can be expected that all existing notes would be turned off before the re-assignment is made by the audio unit. @constant kMusicDeviceProperty_DualSchedulingMode @discussion Scope: Global Value Type: UInt32 Access: write Some instrument units need to distinguish realtime note and control events (such as from incoming MIDI) from sequenced or pre-scheduled events. To support this, a host application may set this property to 1. If the instrument unit returns a value of noErr, it supports an alternate interpretation of the inOffsetSampleFrame parameter for the following functions: MusicDeviceMIDIEvent MusicDeviceStartNote MusicDeviceStopNote AudioUnitSetParameter Once the host sets this property to 1 and the instrument unit returns noErr, the inOffsetSampleFrame field becomes a bitfield: kMusicDeviceSampleFrameMask_SampleOffset = 0xFFFFFF // AND with this to obtain sample offset kMusicDeviceSampleFrameMask_IsScheduled = 0x01000000 The IsScheduled bit should be set on events which are being scheduled ahead of time from a prerecorded track. The IsScheduled bit should be clear on events which are being sent to the instrument unit in response to realtime events, such as incoming MIDI or control changes in a view. @constant kMusicDeviceProperty_SupportsStartStopNote @discussion Scope: Global Value Type: UInt32 Access: read The MusicDeviceStartNote and MusicDeviceStopNote APIs have been available since Mac OS X v10.0. However, many third-party audio units do not implement these calls. This property can be used to determine if an audio unit does provide a compliant implementation. A compliant audio unit will both implement the property and return !0 as the value for the property. Apple's DLSMusicDevice unit has implemented MusicDeviceStartNote and MusicDeviceStopNote since Mac OS X v10.0. The kMusicDeviceProperty_SupportsStartStopNote property was introduced with Mac OS X v10.5, so the DLSMusicDevice unit will not return an appropriate value for this property on a pre-10.5 system. */ enum { // range (1000 -> 1999) kMusicDeviceProperty_InstrumentCount = 1000, kMusicDeviceProperty_MIDIXMLNames = 1006, kMusicDeviceProperty_PartGroup = 1010, kMusicDeviceProperty_DualSchedulingMode = 1013, kMusicDeviceProperty_SupportsStartStopNote = 1014 }; /*! @enum DualSchedulingMode */ enum { kMusicDeviceSampleFrameMask_SampleOffset = 0xFFFFFF, // AND with this to obtain the sample offset kMusicDeviceSampleFrameMask_IsScheduled = 0x01000000 }; //===================================================================================================================== #pragma mark - Offline Unit /*! @enum Offline Unit Properties @abstract The collection of properties for offline units @constant kAudioUnitOfflineProperty_InputSize @discussion Scope: Global Value Type: UInt64 Access: read/write Once this property is set, an audio unit will assume that its input samples have been reset to a new region. Setting this property will also cause the audio unit's internal DSP state to be reset. That is, the audio unit calls the AudioUnitReset function on itself. This property tells the offline unit how many samples to process. Once it knows this number it will then request from 0 to (nSamples-1) in its input callback. The host of the audio unit is then required to provide the samples specified in the sample count field of that Input's callback. @constant kAudioUnitOfflineProperty_OutputSize @discussion Scope: Global Value Type: UInt64 Access: read The host can use this property to estimate how many output samples an audio unit will produce for the specified input samples. The property value is invalid if InputSize is not set. The host cannot assume that the value returned is exact. It is a guide only, so is suitable for use in a progress bar, for instance. Termination of processing is solely determined by the setting of the kAudioUnitStatus_OfflineRenderComplete property in the ioRenderActionFlags from the AudioUnitRender function. @constant kAudioUnitOfflineProperty_StartOffset @discussion Scope: Global Value Type: UInt64 Access: read/write The host sets this property to tell an audio unit that the start offset of the data it is processing has been changed. This should be set along with the InputSize property, so that the unit knows its input data has been set or changed. @constant kAudioUnitOfflineProperty_PreflightRequirements @discussion Scope: Global Value Type: UInt32 Access: read Returns one of the kOfflinePreflight_ results (see the Offline Preflight enumeration). @constant kAudioUnitOfflineProperty_PreflightName @discussion Scope: Global Value Type: CFStringRef Access: read For an audio unit that allows or requires preflighting, this property lets the unit give its host application a name to describe the preflight operations. */ enum { // range (3020->3040) kAudioUnitOfflineProperty_InputSize = 3020, kAudioUnitOfflineProperty_OutputSize = 3021, kAudioUnitOfflineProperty_StartOffset = 3022, kAudioUnitOfflineProperty_PreflightRequirements = 3023, kAudioUnitOfflineProperty_PreflightName = 3024 }; /*! @enum Offline Preflight Flags @abstract Used to indicate an Offline Unit's preflight requirements @constant kOfflinePreflight_NotRequired @discussion Offline unit does not require preflight @constant kOfflinePreflight_Optional @discussion Offline unit will generally behave better if it is preflighted, but it is not required to be preflighted. @constant kOfflinePreflight_Required @discussion Offline unit requires preflighting or it cannot do its work */ enum { kOfflinePreflight_NotRequired = 0, kOfflinePreflight_Optional = 1, kOfflinePreflight_Required = 2 }; //===================================================================================================================== #pragma mark - Panner Unit /*! @enum Panner Unit Properties @abstract The collection of properties for panner units @constant kAudioUnitProperty_DistanceAttenuationData @discussion Scope: Global Value Type: AUDistanceAttenuationData Access: Read */ enum { // range (3060->3999) kAudioUnitProperty_DistanceAttenuationData = 3600 }; /*! @struct AUDistanceAttenuationData */ typedef struct AUDistanceAttenuationData { UInt32 inNumberOfPairs; struct { Float32 inDistance; // 0-1000 Float32 outGain; // 0-1 } pairs[1]; // this is a variable length array of inNumberOfPairs elements } AUDistanceAttenuationData; //===================================================================================================================== #pragma mark - Translation Service /*! @enum Translation Properties @abstract The collection of properties for migrating data from other audio plug-ins to the Audio Unit architecture @discussion While this is a general service, there are two formats that are explicitly defined: MAS and VST. An audio unit may have MAS settings given to it in one of two ways: (1) The settings may have a single setting. This may be set multiple times with different settings each time. In this case, numberOfSettings will be 1. (2) The settings may be set in one hit, providing all SettingData at once. In this case, numberOfSettings may be more than 1, and will be the number of settings the host has from the MAS plugin. AU-VST - the CFDataRef data contains VST chunk data with no additional information. In addition, this can be used to migrate settings from an older audio unit; this allows manufacturers to deprecate older audio units and replace them with new ones. The data for the older audio unit is the audio unit preset CFDictionary that that unit generated. @constant kAudioUnitMigrateProperty_FromPlugin @discussion Scope: Value Type: Access: @constant kAudioUnitMigrateProperty_OldAutomation @discussion Scope: Value Type: Access: */ enum { // range (4000->4020) kAudioUnitMigrateProperty_FromPlugin = 4000, kAudioUnitMigrateProperty_OldAutomation = 4001 }; /*! @enum Other Plug-in Formats */ enum { kOtherPluginFormat_Undefined = 0, //reserving this value for future use kOtherPluginFormat_kMAS = 1, kOtherPluginFormat_kVST = 2, kOtherPluginFormat_AU = 3 }; /*! @struct AudioUnitOtherPluginDesc @discussion @field format @discussion One of the OtherPluginFormat values @field plugin @discussion struct AudioClassDescription { OSType mType; OSType mSubType; OSType mManufacturer; }; is defined in mType specifies a generic, plug-in format defined descriptor mSubType is usually left to the manufacturer to use at their discretion mManufacturer is a registered code to identify all plugins from the same manufacturer */ typedef struct AudioUnitOtherPluginDesc { UInt32 format; AudioClassDescription plugin; } AudioUnitOtherPluginDesc; /*! @struct AudioUnitParameterValueTranslation @abstract Used to translate another plug-in's parameter values to audio unit parameter values */ typedef struct AudioUnitParameterValueTranslation { AudioUnitOtherPluginDesc otherDesc; UInt32 otherParamID; Float32 otherValue; AudioUnitParameterID auParamID; AudioUnitParameterValue auValue; } AudioUnitParameterValueTranslation; /*! @struct AudioUnitPresetMAS_SettingData @discussion AU-MAS specific structs for the data contained in the "masdata" key of an audio unit preset dictionary */ typedef struct AudioUnitPresetMAS_SettingData { UInt32 isStockSetting; // zero or 1 i.e., "long bool" UInt32 settingID; UInt32 dataLen; //length of following data UInt8 data[1]; } AudioUnitPresetMAS_SettingData; /*! @struct AudioUnitPresetMAS_Settings @discussion See MAS documentation */ typedef struct AudioUnitPresetMAS_Settings { UInt32 manufacturerID; UInt32 effectID; UInt32 variantID; UInt32 settingsVersion; UInt32 numberOfSettings; AudioUnitPresetMAS_SettingData settings[1]; } AudioUnitPresetMAS_Settings; #endif // !TARGET_OS_IPHONE //===================================================================================================================== #pragma mark - #pragma mark Apple Specific Properties //===================================================================================================================== #pragma mark - AUConverter /*! @enum Apple AUConverter Property IDs @abstract The collection of property IDs for Apple AUConverter @constant kAudioUnitProperty_SampleRateConverterComplexity @discussion Scope: Global Value Type: UInt32 Access: read/write */ enum { kAudioUnitProperty_SampleRateConverterComplexity = 3014 }; /*! @enum Audio Unit Sample Rate Converter Complexity @discussion The lowest quality of the Mastering algorithm is higher than the highest quality of the Normal algorithm. @constant kAudioUnitSampleRateConverterComplexity_Normal @discussion Normal quality sample rate conversion. @constant kAudioUnitSampleRateConverterComplexity_Mastering @discussion Mastering quality sample rate conversion. More expensive. */ enum { kAudioUnitSampleRateConverterComplexity_Linear = 'line', // linear interpolation kAudioUnitSampleRateConverterComplexity_Normal = 'norm', // the default kAudioUnitSampleRateConverterComplexity_Mastering = 'bats' // higher quality, more expensive }; //===================================================================================================================== #pragma mark - AUHAL and device units /*! @enum Apple Output Property IDs @abstract The collection of property IDs for Apple output units @constant kAudioOutputUnitProperty_CurrentDevice @discussion Scope: Global Value Type: AudioDeviceID Access: read/write The audio device being used (or to be used) by and output device unit @constant kAudioOutputUnitProperty_ChannelMap @discussion Scope: Input/Output Value Type: Array of UInt32 Access: read/write This will also work with AUConverter. This property is used to map input channels from an input (source) to a destination. The number of channels represented in the channel map is the number of channels of the destination. The channel map entries contain a channel number of the source that should be mapped to that destination channel. If -1 is specified, than that destination channel will not contain any channel from the source (so it will be silent) @constant kAudioOutputUnitProperty_EnableIO @discussion Scope: { scope output, element 0 = output } { scope input, element 1 = input } Value Type: UInt32 Access: read/write Output units default to output-only operation. Host applications may disable output or enable input operation using this property, if the output unit supports it. 0=disabled, 1=enabled using I/O proc. @constant kAudioOutputUnitProperty_StartTime @discussion Scope: Global Value Type: AudioOutputUnitStartAtTimeParams Access: write only When this property is set on an output unit, it will cause the next Start request (but no subsequent Starts) to use AudioDeviceStartAtTime, using the specified timestamp, passing false for inRequestedStartTimeIsInput. @constant kAudioOutputUnitProperty_SetInputCallback @discussion Scope: Global Value Type: AURenderCallbackStruct Access: read/write When an output unit has been enabled for input operation, this callback can be used to provide a single callback to the host application from the input I/O proc, in order to notify the host that input is available and may be obtained by calling the AudioUnitRender function. Note that the inputProc will always receive a NULL AudioBufferList in ioData. You must call AudioUnitRender in order to obtain the audio. @constant kAudioOutputUnitProperty_HasIO @discussion Scope: { scope output, element 0 = output } { scope input, element 1 = input } Value Type: UInt32 Access: See kAudioOutputUnitProperty_EnableIO Property value is 1 if input or output is enabled on the specified element. @constant kAudioOutputUnitProperty_StartTimestampsAtZero @discussion Scope: Global Value Type: UInt32 Access: read/write Apple output units typically begin their stream of timestamps presented to their inputs at sample time 0. Some applications may wish to receive the HAL's timestamps directly instead. When this property is set to false, the output unit's sample times will be direct reflections of the HAL's -- except when a sample rate conversion makes this impossible. This property also applies to AUConverter. Its value defaults to 1 for AUHAL; 1 for other AUs. */ enum { kAudioOutputUnitProperty_CurrentDevice = 2000, kAudioOutputUnitProperty_ChannelMap = 2002, // this will also work with AUConverter kAudioOutputUnitProperty_EnableIO = 2003, kAudioOutputUnitProperty_StartTime = 2004, kAudioOutputUnitProperty_SetInputCallback = 2005, kAudioOutputUnitProperty_HasIO = 2006, kAudioOutputUnitProperty_StartTimestampsAtZero = 2007 // this will also work with AUConverter }; /*! @struct AudioOutputUnitStartAtTimeParams */ typedef struct AudioOutputUnitStartAtTimeParams { // see AudioDeviceStartAtTime AudioTimeStamp mTimestamp; UInt32 mFlags; } AudioOutputUnitStartAtTimeParams; //===================================================================================================================== #pragma mark - AUVoiceProcessing unit /*! @enum Apple Voice Processing Property IDs @abstract The collection of property IDs for Apple voice processing units. @constant kAUVoiceIOProperty_BypassVoiceProcessing @discussion Scope: Global Value Type: UInt32 Access: read/write Bypass all processing done by the voice processing unit. When set to 0 (default), the processing is activated otherwise it is disabled. @constant kAUVoiceIOProperty_VoiceProcessingEnableAGC @discussion Scope: Global Value Type: UInt32 Access: read/write Enable automatic gain control on the processed microphone/uplink signal. On by default. @constant kAUVoiceIOProperty_MuteOutput @discussion Scope: Global Value Type: UInt32 Access: read/write Mutes the output of the voice processing unit. 0 (default) = muting off. 1 = mute output. */ enum { kAUVoiceIOProperty_BypassVoiceProcessing = 2100, kAUVoiceIOProperty_VoiceProcessingEnableAGC = 2101, kAUVoiceIOProperty_MuteOutput = 2104 }; #pragma mark - AUVoiceProcessing unit deprecated properties /*! @enum Apple Voice Processing Property IDs that are being deprecated @abstract The collection of property IDs for Apple voice processing units that are being deprecated. @constant kAUVoiceIOProperty_VoiceProcessingQuality @discussion Scope: Global Value Type: UInt32 Access: read/write DEPRECATED. Sets the quality of the voice processing unit. Quality values are comprised between 0 (lowest) and 127 (highest). */ enum { kAUVoiceIOProperty_VoiceProcessingQuality = 2103, // deprecated }; /*! @enum Apple Voice Processing AudioUnit Error IDs @abstract These are the various error IDs returned by Voice Processing audio unit. @constant kAUVoiceIOErr_UnexpectedNumberOfInputChannels This error indicates that an unexpected number of input channels was encountered during initialization of voice processing audio unit */ enum { kAUVoiceIOErr_UnexpectedNumberOfInputChannels = -66784, }; //===================================================================================================================== #pragma mark - Mixers /*! @enum Apple Mixer Property IDs @abstract The collection of property IDs for Apple mixers @constant kAudioUnitProperty_MeteringMode @discussion Scope: { scope / element } Value Type: UInt32 Access: read/write Enable or disable metering on a particular scope/element @constant kAudioUnitProperty_MatrixLevels @discussion This property can be used for both the AUMatrixMixer and AUMultiChannelMixer. AUMatrixMixer Scope: Global Value Type: Float32 array Access: read/write This property is used to retrieve the entire state of a matrix mixer. The size required is the number of (input channels + 1) * (output channels + 1) - see _MatrixDimensions So a matrix mixer that has 2 input channels and 2 output channels, will need a 3 x 3 array of Float32 Global volume is stored at volumes[2][2] Input volumes are stored in the last column (volumes[0][2] for the first input channel, volumes[1][2] for the second) Output volumes are stored in the last row (volumes [2][0] and [2][1]) Cross point volumes are stored at their expected locations ([0][1], etc) AUMultiChannelMixer Scope: Input Value Type: Float32 array Access: read/write Gets/sets the matrix levels for one input element. This allows arbitrary mixing configurations from all input channels to all output channels. The size required is the number of (input channels) * (output channels). The matrix stores only the crosspoint gains, there are no overall input or output channel gains. @constant kAudioUnitProperty_MatrixDimensions @discussion Scope: Global Value Type: 2 x UInt32 Access: Read only Returns the total number of channels for input and output of a given matrix mixer @constant kAudioUnitProperty_MeterClipping @discussion Scope: Global Value Type: AudioUnitMeterClipping Access: Read A mixer returns an AudioUnitMeterClipping structure. */ enum { // General mixers kAudioUnitProperty_MeteringMode = 3007, // Matrix Mixer kAudioUnitProperty_MatrixLevels = 3006, kAudioUnitProperty_MatrixDimensions = 3009, kAudioUnitProperty_MeterClipping = 3011 }; /*! @struct AudioUnitMeterClipping @field peakValueSinceLastCall; @discussion The maximum value seen on the channel since the last time the property was retrieved. @field sawInfinity; @discussion TRUE if there was an infinite value on this channel. @field sawNotANumber @discussion TRUE if there was a floating point Not-A-Number value on this channel. */ typedef struct AudioUnitMeterClipping { Float32 peakValueSinceLastCall; Boolean sawInfinity; Boolean sawNotANumber; } AudioUnitMeterClipping; //===================================================================================================================== #pragma mark - _3DMixer /*! @enum Apple Mixer Property IDs @abstract The collection of property IDs for Apple mixers @constant kAudioUnitProperty_MeteringMode @discussion Scope: { scope / element } Value Type: UInt32 Access: read/write Enable or disable metering on a particular scope/element @constant kAudioUnitProperty_SpatializationAlgorithm @discussion Scope: Input Value Type: UInt32 Access: read/write Used to set the spatialisation algorithm used by an input of the 3DMixer. See kSpatializationAlgorithm_ @constant kAudioUnitProperty_DopplerShift @discussion Scope: Input Value Type: UInt32 Access: Write Use a boolean true/false value to enable doppler shift for any specified input @constant kAudioUnitProperty_3DMixerRenderingFlags @discussion Scope: Input Value Type: UInt32 Access: read/write Used to enable various rendering operations on a given input for the 3DMixer. See k3DMixerRenderingFlags_ @constant kAudioUnitProperty_3DMixerDistanceAtten @discussion Scope: Value Type: Access: @constant kAudioUnitProperty_3DMixerDistanceParams @discussion Scope: Value Type: Access: @constant kAudioUnitProperty_ReverbPreset @discussion Scope: Value Type: Access: @constant kAudioUnitProperty_3DMixerAttenuationCurve @discussion Scope: Value Type: Access: @constant kAudioUnitProperty_MatrixLevels @discussion Scope: Value Type: Access: @constant kAudioUnitProperty_MatrixDimensions @discussion Scope: Value Type: Access: @constant kAudioUnitProperty_MeterClipping @discussion Scope: Value Type: AudioUnitMeterClipping Access: A mixer returns an AudioUnitMeterClipping structure. */ enum { kAudioUnitProperty_3DMixerDistanceParams = 3010, kAudioUnitProperty_3DMixerAttenuationCurve = 3013, kAudioUnitProperty_SpatializationAlgorithm = 3000, kAudioUnitProperty_DopplerShift = 3002, kAudioUnitProperty_3DMixerRenderingFlags = 3003, kAudioUnitProperty_3DMixerDistanceAtten = 3004, kAudioUnitProperty_ReverbPreset = 3012 }; /*! @enum 3D Mixer Attenuation Curves */ enum { k3DMixerAttenuationCurve_Power = 0, k3DMixerAttenuationCurve_Exponential = 1, k3DMixerAttenuationCurve_Inverse = 2, k3DMixerAttenuationCurve_Linear = 3 }; /*! @struct MixerDistanceParams */ typedef struct MixerDistanceParams { Float32 mReferenceDistance; Float32 mMaxDistance; Float32 mMaxAttenuation; // in decibels } MixerDistanceParams; /*! @enum Spatialization Algorithms */ enum { kSpatializationAlgorithm_EqualPowerPanning = 0, kSpatializationAlgorithm_SphericalHead = 1, kSpatializationAlgorithm_HRTF = 2, kSpatializationAlgorithm_SoundField = 3, kSpatializationAlgorithm_VectorBasedPanning = 4, kSpatializationAlgorithm_StereoPassThrough = 5 }; /*! @enum 3D Mixer Rendering Flags */ enum { k3DMixerRenderingFlags_InterAuralDelay = (1L << 0), k3DMixerRenderingFlags_DopplerShift = (1L << 1), k3DMixerRenderingFlags_DistanceAttenuation = (1L << 2), k3DMixerRenderingFlags_DistanceFilter = (1L << 3), k3DMixerRenderingFlags_DistanceDiffusion = (1L << 4), k3DMixerRenderingFlags_LinearDistanceAttenuation = (1L << 5), k3DMixerRenderingFlags_ConstantReverbBlend = (1L << 6) }; //===================================================================================================================== #pragma mark - AUScheduledSoundPlayer /*! @enum Apple AUScheduledSoundPlayer Property IDs @abstract The collection of property IDs for the Apple AUScheduledSoundPlayer audio unit. @discussion The AUScheduledSoundPlayer audio unit lets a client schedule audio buffers for future playback, with sample-accurate timing. Elements and Formats This unit has one output element and no input elements. The output's format should be a canonical audio unit stream format (native Float32, deinterleaved). Scheduling To schedule slices of audio for future playback, set the kAudioUnitProperty_ScheduleAudioSlice property, with a ScheduledAudioSlice structure as the property value. The slice's mTimeStamp.mSampleTime field determines when the slice will be played. This sample number is relative to the unit's start time, which you must set using the kAudioUnitProperty_ScheduleStartTimeStamp property before playback will begin. You must retain, unmodified, the ScheduledAudioSlice structure, including its mBufferList and the buffers to which it points, until the slice has been completely played, or until you stop playback by uninitializing or resetting the unit. The format of the slice's buffer list must match the unit's output stream format. (The fields other than mSampleTime and mFlags in the mTimestamp structure are currently ignored.) Completion To receive a callback when the slice has been played, store a pointer to a callback function in the mCompletionProc field. This function will be called (from the audio unit's rendering thread) when the slice has been completely played -- or when the slice is determined to be unplayable due to an error. As an alternative, you may also poll the slice's (mFlags & kScheduledAudioSliceFlag_Complete). Upon completion, you can test (mFlags & kScheduledAudioSliceFlag_BeganToRenderLate) to determine whether some portion of the slice was not played due to its having been scheduled too late relative to the current playback time. Start Time The audio unit will not play any slices following initialization or reset, until its start time has been set. The start time establishes the beginning of a timeline: the timestamps of all slices in the schedule are relative to the start time. Set a start time by setting the kAudioUnitProperty_ScheduleStartTimeStamp property with an AudioTimeStamp structure. If the timestamp contains a valid sample time (timestamp.mFlags & kAudioTimeStampSampleTimeValid), then playback begins when the timestamp passed to the AudioUnitRender function reaches the specified sample time. If the specified sample time is -1, playback begins on the next render cycle. If the start timestamp does not contain a valid sample time, but does contain a valid host time (timestamp.mFlags & kAudioTimeStampHostTimeValid), then the specified host time is translated to the sample time at which playback will begin. A host time of 0 means "start on the next render cycle." The kAudioUnitProperty_ScheduleStartTimeStamp property may be queried to obtain the time at which playback began. If the start time has not yet been reached, the timestamp returned will be whatever the host application last set. Current play time The kAudioUnitProperty_CurrentPlayTime property may be queried to determine the audio unit's current time offset from its start time. This is useful, for example, to monitor playback progress. Unscheduling events To clear an audio unit's play schedule, call the AudioUnitReset function. The completion proc (if any) for each slice in the schedule will called. Playback will not resume until a new start time has been set. This also happens when the audio unit is uninitialized. @constant kAudioUnitProperty_ScheduleAudioSlice @discussion Scope: Value Type: ScheduledAudioSlice Access: @constant kAudioUnitProperty_ScheduleStartTimeStamp @discussion Scope: Value Type: AudioTimeStamp Access: Sample time or host time valid. Sample time takes precedence, -1 means "now". Host time of 0 means "now." @constant kAudioUnitProperty_CurrentPlayTime @discussion Scope: Value Type: AudioTimeStamp Access: AudioTimeStamp, relative to start time, sample time of -1 if not yet started. */ enum { kAudioUnitProperty_ScheduleAudioSlice = 3300, kAudioUnitProperty_ScheduleStartTimeStamp = 3301, kAudioUnitProperty_CurrentPlayTime = 3302 }; /*! @enum ScheduledAudioSlice @abstract bits in ScheduledAudioSlice.mFlags @constant kScheduledAudioSliceFlag_Complete Set if the unit is done with this slice @constant kScheduledAudioSliceFlag_BeganToRender Set if any portion of the buffer has been played @constant kScheduledAudioSliceFlag_BeganToRenderLate Set if any portion of the buffer was not played because it was scheduled late */ enum { kScheduledAudioSliceFlag_Complete = 1, kScheduledAudioSliceFlag_BeganToRender = 2, kScheduledAudioSliceFlag_BeganToRenderLate = 4 }; typedef struct ScheduledAudioSlice ScheduledAudioSlice; // forward dec, see definition below /*! @typedef ScheduledAudioSliceCompletionProc */ typedef void (*ScheduledAudioSliceCompletionProc)(void *userData, ScheduledAudioSlice *bufferList); /* @struct ScheduledAudioSlice @field mTimeStamp; @field mCompletionProc; May be null @field mCompletionProcUserData; @field mFlags; @field mReserved; Must be 0 @field mReserved2; For internal use @field mNumberFrames; Must be consistent with byte count of mBufferList @field mBufferList; Must contain deinterleaved Float32 */ struct ScheduledAudioSlice { AudioTimeStamp mTimeStamp; ScheduledAudioSliceCompletionProc mCompletionProc; // may be null void * mCompletionProcUserData; UInt32 mFlags; UInt32 mReserved; // must be 0 void * mReserved2; // for internal use UInt32 mNumberFrames; // must be consistent with byte count of mBufferList AudioBufferList * mBufferList; // must contain deinterleaved Float32 }; //===================================================================================================================== #pragma mark - AUAudioFilePlayer /*! @enum Apple AUAudioFilePlayer Property IDs @abstract The collection of property IDs for Apple AUAudioFilePlayer @discussion This audio unit lets you schedule regions of audio files for future playback, with sample-accurate timing. The unit is a subclass of AUScheduledSoundPlayer and inherits all of its behavior. In particular, this unit implements the kAudioUnitProperty_ScheduleStartTimeStamp and kAudioUnitProperty_CurrentPlayTime properties. Instead of scheduling slices (buffers) of audio to be played (via kAudioUnitProperty_ScheduleAudioSlice), however, you schedule regions of audio files to be played. The unit reads and converts audio file data into its own internal buffers. It performs disk I/O on a high-priority thread shared among all instances of this unit within a process. Upon completion of a disk read, the unit internally schedules buffers for playback. Elements and Formats This unit has one output element and no input elements. The output's format should be a canonical audio unit stream format (native Float32, deinterleaved). This format should have at least as many channels are in the audio file(s) to be played (otherwise channels will be dropped). During playback, all audio file data is converted to the unit's output format. Audio Files Before starting playback, you must first open all audio files to be played using the AudioFile API's (see AudioToolbox/AudioFile.h), and pass their AudioFileIDs to the unit by setting the kAudioUnitProperty_ScheduledFileIDs property. This property must not be set during playback. The audio files must be kept open for the duration of playback. Scheduling Regions To schedule the playback of a region of an audio file, set the kAudioUnitProperty_ScheduledFileRegion property. This is a ScheduledAudioFileRegion structure. mTimeStamp.mSampleTime must be valid and is interpreted relative to the unit's start time -- the start time semantics (using kAudioUnitProperty_ScheduleStartTimeStamp) are identical to those of AUScheduledSoundPlayer. Unlike the ScheduledAudioSlice structures, the unit makes copies of ScheduledAudioFileRegions, so you may create them on the stack or otherwise reuse/dispose of them immediately after scheduling them. Priming You should set kAudioUnitProperty_ScheduledFilePrime after scheduling initial file regions to be played and before starting playback. This SetProperty call will begin reading the audio files and not return until the number of frames specified by the property value have been read. Completion Callbacks A region's completion callback (mCompletionProc) is called when it has been completely scheduled for reading from disk. This callback is issued on the disk read thread. If the region is not read from disk in time to play at its scheduled time, mCompletionProc is called a second time with an error code, also from the read thread. Note that the region passed to the callback will not be the same memory object as was passed by the client (since the unit copies the region). Start Time and Current Time These properties work identically as in AUScheduledSoundPlayer. Unscheduling regions To clear the unit's play schedule, call the AudioUnitReset function. The completion proc (if any) for each file region in the schedule will be called. Playback will not resume until a new start time has been set. This also happens when the unit is uninitialized. Customization The size and number of the player's disk read buffers default to "sensible" values, but may be configured with the properties: kAudioUnitProperty_ScheduledFileBufferSizeFrames kAudioUnitProperty_ScheduledFileNumberBuffers Bugs kAudioUnitProperty_ScheduledFileBufferSizeFrames kAudioUnitProperty_ScheduledFileNumberBuffers are currently unimplemented An option to make the unit not perform conversion from the audio file sample rate to the unit's output rate may be desirable. @constant kAudioUnitProperty_ScheduledFileIDs @discussion Scope: Value Type: Array of AudioFileIDs Access: Must set this property on scheduled file player for all files to be played @constant kAudioUnitProperty_ScheduledFileRegion @discussion Scope: Value Type: ScheduledAudioFileRegion Access: @constant kAudioUnitProperty_ScheduledFilePrime @discussion Scope: Value Type: UInt32 Access: The number of frames to read from disk before returning, or 0 to specify use of a default value @constant kAudioUnitProperty_ScheduledFileBufferSizeFrames @discussion Scope: Value Type: UInt32 Access: @constant kAudioUnitProperty_ScheduledFileNumberBuffers @discussion Scope: Value Type: UInt32 Access: */ enum { kAudioUnitProperty_ScheduledFileIDs = 3310, kAudioUnitProperty_ScheduledFileRegion = 3311, kAudioUnitProperty_ScheduledFilePrime = 3312, kAudioUnitProperty_ScheduledFileBufferSizeFrames = 3313, kAudioUnitProperty_ScheduledFileNumberBuffers = 3314 }; typedef struct ScheduledAudioFileRegion ScheduledAudioFileRegion; //forward declaration, see definition below /*! @typedef ScheduledAudioFileRegionCompletionProc */ typedef void (*ScheduledAudioFileRegionCompletionProc)(void *userData, ScheduledAudioFileRegion *fileRegion, OSStatus result); /*! @struct ScheduledAudioFileRegion @field mTimeStamp @field mCompletionProc may be NULL @field mCompletionProcUserData @field mAudioFile must be a valid and open AudioFileID defined in AudioToolbox/AudioFile.h: typedef struct OpaqueAudioFileID *AudioFileID; @field mLoopCount 0 = don't loop @field mStartFrame offset into file @field mFramesToPlay number of frames to play */ struct ScheduledAudioFileRegion { AudioTimeStamp mTimeStamp; ScheduledAudioFileRegionCompletionProc mCompletionProc; void * mCompletionProcUserData; struct OpaqueAudioFileID * mAudioFile; UInt32 mLoopCount; SInt64 mStartFrame; UInt32 mFramesToPlay; }; //===================================================================================================================== #pragma mark - #pragma mark Desktop Apple Specific Properties #if !TARGET_OS_IPHONE //===================================================================================================================== #pragma mark - DLSMusicDevice and Internal Reverb /*! @enum Generic Property IDs @abstract The collection of general audio unit property IDs @constant kAudioUnitProperty_ReverbRoomType @discussion Scope: Value Type: Access: @constant kAudioUnitProperty_UsesInternalReverb @discussion Scope: Value Type: Access: @constant kMusicDeviceProperty_InstrumentName @discussion Scope: Value Type: Access: @constant kMusicDeviceProperty_InstrumentNumber @discussion Scope: Value Type: Access: @constant kMusicDeviceProperty_BankName @discussion Scope: Value Type: Access: @constant kMusicDeviceProperty_SoundBankData @discussion Scope: Value Type: Access: @constant kMusicDeviceProperty_StreamFromDisk @discussion Scope: Value Type: Access: @constant kMusicDeviceProperty_SoundBankFSRef @discussion Scope: Value Type: Access: @constant kMusicDeviceProperty_SoundBankURL @discussion Scope: Value Type: Access: */ enum { kAudioUnitProperty_ReverbRoomType = 10, // 3DMixer, DLSMusicDevice kAudioUnitProperty_UsesInternalReverb = 1005, // DLS Music Device kMusicDeviceProperty_InstrumentName = 1001, kMusicDeviceProperty_InstrumentNumber = 1004, kMusicDeviceProperty_UsesInternalReverb = kAudioUnitProperty_UsesInternalReverb, kMusicDeviceProperty_BankName = 1007, kMusicDeviceProperty_SoundBankData = 1008, kMusicDeviceProperty_StreamFromDisk = 1011, kMusicDeviceProperty_SoundBankFSRef = 1012, kMusicDeviceProperty_SoundBankURL = 1100 }; /*! @enum Reverb Room Types @discussion Used to specify room type (as identified by a factory preset number) on Apple audio units that use internal reverb. */ enum { kReverbRoomType_SmallRoom = 0, kReverbRoomType_MediumRoom = 1, kReverbRoomType_LargeRoom = 2, kReverbRoomType_MediumHall = 3, kReverbRoomType_LargeHall = 4, kReverbRoomType_Plate = 5, kReverbRoomType_MediumChamber = 6, kReverbRoomType_LargeChamber = 7, kReverbRoomType_Cathedral = 8, kReverbRoomType_LargeRoom2 = 9, kReverbRoomType_MediumHall2 = 10, kReverbRoomType_MediumHall3 = 11, kReverbRoomType_LargeHall2 = 12 }; //===================================================================================================================== #pragma mark - AUSampler /*! @enum Apple AUSampler Property IDs @abstract The collection of property IDs for the Apple AUSampler audio unit. @discussion The AUSampler audio unit lets a client create an editable, interactive sampler synthesizer instrument. @constant kAUSamplerProperty_LoadInstrument @discussion Scope: Global Value Type: AUSamplerInstrumentData Access: Write Load an instrument from an external DLS or Soundfont2 bank file, or from other file formats. @constant kAUSamplerProperty_LoadAudioFiles @discussion Scope: Global Value Type: CFArrayRef Access: Write Create a new preset from a list of audio file paths. The CFArray should contain a set of CFURLRefs, one per file. The previous preset will be completely cleared. */ enum { // range (4100->4999) kAUSamplerProperty_LoadInstrument = 4102, kAUSamplerProperty_LoadAudioFiles = 4101 }; /* @struct AUSamplerInstrumentData @abstract Used for loading an instrument from either an external bank file (i.e. DLS or SoundFont), an Apple .aupreset, a Logic or GarageBand EXS24 sampler instrument, or creating a new default instrument from a single audio file. The path to the bank or instrument file is specified in the fileURL field. The instrumentType field distinguishes between the instrument types. The remaining fields of this struct are used only for the kInstrumentType_DLSPreset and kInstrumentType_SF2Preset types to identify the particular bank and preset IDs for the instrument you wish to load from the bank. They represent values for MIDI controllers 0 and 32 and the MIDI present change message that would be sent to a GM2-compatible synth for program changes. Use the provided constants (kAUSampler_DefaultMelodicBankMSB, kAUSampler_DefaultPercussionBankMSB) to designate melodic or percussion banks per the GM2 specification (GM-compatible DLS or Soundfont banks). For custom non-GM-compatible DLS and Soundfont banks, use the actual MSB/LSB values associated with the desired preset. @field fileURL The URL of the path to the bank or instrument file. Caller is responsible for releasing the provided CFURLRef. @field instrumentType The type of instrument being loaded or created. For example, use kInstrumentType_DLSPreset to load an instrument from a DLS bank file. @field bankMSB For the preset instruments, the most significant byte value for a particular bank variation within that file. Range is 0 to 127. Use kAUSampler_DefaultMelodicBankMSB by default. @field bankLSB For the preset instruments, the least significant byte value for a particular bank variation within that file. Range is 0 to 127. Use kAUSampler_DefaultBankLSB by default. @field presetID For the preset instruments, the numeric ID of a particular preset within that bank to load. Range is 0 to 127. */ typedef struct AUSamplerInstrumentData { CFURLRef fileURL; UInt8 instrumentType; UInt8 bankMSB; UInt8 bankLSB; UInt8 presetID; } AUSamplerInstrumentData; /* @enum InstrumentTypes @abstract Values to specify the type of instrument being loaded. @constant kInstrumentType_DLSPreset @discussion A preset from a DLS bank file. Bank MSB, LSB and preset ID must be specified. @constant kInstrumentType_SF2Preset @discussion A preset from a SoundFont2 bank file. Bank MSB, LSB and preset ID must be specified. @constant kInstrumentType_AUPreset @discussion A native Apple .aupreset file created using the AUSampler's custom view. @constant kInstrumentType_Audiofile @discussion An audio file which will be used to create a default instrument with that file as its sole sample. @constant kInstrumentType_EXS24 @discussion A Logic or GarageBand sampler instrument. */ enum { kInstrumentType_DLSPreset = 1, kInstrumentType_SF2Preset = kInstrumentType_DLSPreset, kInstrumentType_AUPreset = 2, kInstrumentType_Audiofile = 3, kInstrumentType_EXS24 = 4 }; enum { kAUSampler_DefaultPercussionBankMSB = 0x78, kAUSampler_DefaultMelodicBankMSB = 0x79, kAUSampler_DefaultBankLSB = 0x00 }; //===================================================================================================================== #pragma mark - AUDeferredRenderer /*! @enum AUDeferredRenderer @discussion This audio unit has one input element and one output element. They must both have the same format, which must be canonical (Float32 deinterleaved) and must have the same number of channels. The AUDeferredRenderer unit creates a high-priority producer thread, on which calls by this AU for input are performed at a constant buffer size. This buffer size may be set with the kAudioUnitProperty_DeferredRendererPullSize property. The deferred renderer may be asked to render at different buffer sizes by a downstream unit or host application, but it always pulls upstream at its constant buffer size. The upstream pull size MUST be greater than or equal to the downstream pull size. The upstream producer thread runs in advance of calls to its Render function, with respect to the timestamps being passed to Render and PullInput. The difference between these timestamps is the unit's "latency", which is always at least one upstream pull buffer. The client may specify additional latency with the property kAudioUnitProperty_DeferredRendererExtraLatency, which is a number of sample frames. It is possible, at Render time, for the producer thread to have not yet finished rendering the necessary data. This generates an error. In order to give the producer a small amount of extra time to finish rendering, the client may set the unit's property kAudioUnitProperty_DeferredRendererWaitFrames. If this property is non-zero, then when Render finds that insufficient data has been produced, it will sleep for the amount of realtime corresponding to the number of wait frames. It will then check again to see if the required amount of data has been produced, and fail if it hasn't. @constant kAudioUnitProperty_DeferredRendererPullSize @discussion Scope: Value Type: UInt32 Access: @constant kAudioUnitProperty_DeferredRendererExtraLatency @discussion Scope: Value Type: UInt32 Access: @constant kAudioUnitProperty_DeferredRendererWaitFrames @discussion Scope: Value Type: UInt32 Access: */ enum { kAudioUnitProperty_DeferredRendererPullSize = 3320, kAudioUnitProperty_DeferredRendererExtraLatency = 3321, kAudioUnitProperty_DeferredRendererWaitFrames = 3322 }; //===================================================================================================================== #pragma mark - AUNetReceive /*! @enum AUNetReceive @constant kAUNetReceiveProperty_Hostname @discussion Scope: Global Value Type: CFStringRef Access: The hostname from which you wish to receive audio. For GetProperty, the returned CFStringRef is a copy and therefore must be released by the caller. The UI view for AUNetReceive does the resolution of Bonjour service names to hostnames. Clients who are using this AU programmatically using Bonjour will have to do this resolution themselves. It is not done by the AU. @constant kAUNetReceiveProperty_Password @discussion Scope: Global Value Type: CFStringRef Access: Read / Write The password to send to the sender. Leave unset or set to the empty string for no password. For GetProperty, the returned CFStringRef is a copy and therefore must be released by the caller. */ enum { kAUNetReceiveProperty_Hostname = 3511, kAUNetReceiveProperty_Password = 3512 }; //===================================================================================================================== #pragma mark - AUNetSend /*! @enum AUNetSend @constant kAUNetSendProperty_PortNum @discussion Scope: Global Value Type: UInt32 Access: Read / Write The network port number on which to send. @constant kAUNetSendProperty_TransmissionFormat @discussion Scope: Global Value Type: AudioStreamBasicDescription Access: Read / Write Get or set an arbitrary format that will be used to transmit the audio. For compressed formats, it is recommended to use kAUNetSendProperty_TransmissionFormatIndex instead of this property, since there is no way to specify a bit rate with this property. @constant kAUNetSendProperty_TransmissionFormatIndex @discussion Scope: Global Value Type: UInt32 Access: Read / Write Get or set the index of the preset format that will be used to transmit the audio. The format indices can be found in the NetSendPresetFormat enum. @constant kAUNetSendProperty_ServiceName @discussion Scope: Global Value Type: CFStringRef Access: Read / Write The name you want to publish for this network service. For GetProperty, the returned CFStringRef is a copy and therefore must be released by the caller. @constant kAUNetSendProperty_Disconnect @discussion Scope: Global Value Type: UInt32 Access: Read / Write In order to disconnect, call this with a non-zero value. In order to connect, call this with a zero value. For GetProperty, the returned value the last value set by the caller. To get the current connection status, get the value of the parameter kAUNetReceiveParam_Status. @constant kAUNetSendProperty_Password @discussion Scope: Global Value Type: CFStringRef Access: Read / Write The password that must be used by the receiver. Leave unset or set to the empty string for no password. For GetProperty, the returned CFStringRef is a copy and therefore must be released by the caller. */ enum { kAUNetSendProperty_PortNum = 3513, kAUNetSendProperty_TransmissionFormat = 3514, kAUNetSendProperty_TransmissionFormatIndex = 3515, kAUNetSendProperty_ServiceName = 3516, kAUNetSendProperty_Disconnect = 3517, kAUNetSendProperty_Password = 3518 }; /*! @enum NetSendPresetFormat @constant kAUNetSendPresetFormat_PCMFloat32 @discussion 1411 kilobits per second per channel @ 44100KHz (kilo == 1000 not 1024) @constant kAUNetSendPresetFormat_PCMInt24 @discussion 1058 kilobits per second per channel @ 44100KHz @constant kAUNetSendPresetFormat_PCMInt16 @discussion 706 kilobits per second per channel @ 44100KHz @constant kAUNetSendPresetFormat_Lossless24 @discussion 650 kilobits per second per channel @ 44100KHz @constant kAUNetSendPresetFormat_Lossless16 @discussion 350 kilobits per second per channel @ 44100KHz @constant kAUNetSendPresetFormat_ULaw @discussion 353 kilobits per second per channel @ 44100KHz @constant kAUNetSendPresetFormat_IMA4 @discussion 176 kilobits per second per channel @ 44100KHz @constant kAUNetSendPresetFormat_AAC_128kbpspc @discussion 128 kilobits per second per channel @constant kAUNetSendPresetFormat_AAC_96kbpspc @discussion 96 kilobits per second per channel @constant kAUNetSendPresetFormat_AAC_80kbpspc @discussion 80 kilobits per second per channel @constant kAUNetSendPresetFormat_AAC_64kbpspc @discussion 64 kilobits per second per channel @constant kAUNetSendPresetFormat_AAC_48kbpspc @discussion 48 kilobits per second per channel @constant kAUNetSendPresetFormat_AAC_40kbpspc @discussion 40 kilobits per second per channel @constant kAUNetSendPresetFormat_AAC_32kbpspc @discussion 32 kilobits per second per channel @constant kAUNetSendNumPresetFormats = 14 */ enum { kAUNetSendPresetFormat_PCMFloat32 = 0, kAUNetSendPresetFormat_PCMInt24 = 1, kAUNetSendPresetFormat_PCMInt16 = 2, kAUNetSendPresetFormat_Lossless24 = 3, kAUNetSendPresetFormat_Lossless16 = 4, kAUNetSendPresetFormat_ULaw = 5, kAUNetSendPresetFormat_IMA4 = 6, kAUNetSendPresetFormat_AAC_128kbpspc = 7, kAUNetSendPresetFormat_AAC_96kbpspc = 8, kAUNetSendPresetFormat_AAC_80kbpspc = 9, kAUNetSendPresetFormat_AAC_64kbpspc = 10, kAUNetSendPresetFormat_AAC_48kbpspc = 11, kAUNetSendPresetFormat_AAC_40kbpspc = 12, kAUNetSendPresetFormat_AAC_32kbpspc = 13, kAUNetSendPresetFormat_AAC_LD_64kbpspc = 14, kAUNetSendPresetFormat_AAC_LD_48kbpspc = 15, kAUNetSendPresetFormat_AAC_LD_40kbpspc = 16, kAUNetSendPresetFormat_AAC_LD_32kbpspc = 17, kAUNetSendNumPresetFormats = 18 }; #endif // _TARGET_OS_IPHONE for Apple Specific audio units //===================================================================================================================== #pragma mark - #pragma mark Deprecated Properties #if !TARGET_OS_IPHONE // NumVersion is no longer used (originally from MacTypes.h) #if TARGET_RT_BIG_ENDIAN typedef struct AUNumVersion { /* Numeric version part of 'vers' resource */ UInt8 majorRev; /*1st part of version number in BCD*/ UInt8 minorAndBugRev; /*2nd & 3rd part of version number share a byte*/ UInt8 stage; /*stage code: dev, alpha, beta, final*/ UInt8 nonRelRev; /*revision level of non-released version*/ } AUNumVersion; #else typedef struct AUNumVersion { /* Numeric version part of 'vers' resource accessible in little endian format */ UInt8 nonRelRev; /*revision level of non-released version*/ UInt8 stage; /*stage code: dev, alpha, beta, final*/ UInt8 minorAndBugRev; /*2nd & 3rd part of version number share a byte*/ UInt8 majorRev; /*1st part of version number in BCD*/ } AUNumVersion; #endif /* TARGET_RT_BIG_ENDIAN */ /*! @struct AUHostIdentifier @abstract Used to describe the name and version of the audio unit's host */ typedef struct AUHostIdentifier { CFStringRef hostName; AUNumVersion hostVersion; } AUHostIdentifier; // $$$ THESE NEED TO BE REMOVED FROM 64bit apps //===================================================================================================================== // GENERIC enum { kAudioUnitParameterFlag_Global = (1L << 0), // parameter scope is global kAudioUnitParameterFlag_Input = (1L << 1), // parameter scope is input kAudioUnitParameterFlag_Output = (1L << 2), // parameter scope is output kAudioUnitParameterFlag_Group = (1L << 3) // parameter scope is group }; enum { kAudioUnitParameterFlag_HasName = kAudioUnitParameterFlag_ValuesHaveStrings }; enum { //kAudioUnitProperty_SetInputCallback = 7 -> deprecated kAudioUnitProperty_SRCAlgorithm = 9, // see kAudioUnitProperty_SampleRateConverterComplexity kAudioUnitProperty_MIDIControlMapping = 17, // see ParameterMIDIMapping Properties kAudioUnitProperty_CurrentPreset = 28, // see PresentPreset kAudioUnitProperty_ParameterValueName = kAudioUnitProperty_ParameterStringFromValue, kAudioUnitProperty_BusCount = kAudioUnitProperty_ElementCount, kAudioOfflineUnitProperty_InputSize = kAudioUnitOfflineProperty_InputSize, kAudioOfflineUnitProperty_OutputSize = kAudioUnitOfflineProperty_OutputSize }; enum { kAudioUnitSRCAlgorithm_Polyphase = 'poly', // same as kAudioUnitSampleRateConverterComplexity_Normal kAudioUnitSRCAlgorithm_MediumQuality = 'csrc' // same as kAudioUnitSampleRateConverterComplexity_Normal }; // Deprecated in Mac OS X v10.2. See AUParameterMIDIMapping. typedef struct AudioUnitMIDIControlMapping { UInt16 midiNRPN; UInt8 midiControl; UInt8 scope; AudioUnitElement element; AudioUnitParameterID parameter; } AudioUnitMIDIControlMapping; // Deprecated. See AudioUnitParameterStringFromValue for equivalent structure, but with clearer field names typedef struct AudioUnitParameterValueName { AudioUnitParameterID inParamID; const Float32 *inValue; // may be NULL if should translate current parameter value CFStringRef outName; // see comments for kAudioUnitProperty_ParameterStringFromValue } AudioUnitParameterValueName; //===================================================================================================================== // Deprecated. These properties are Apple specific. enum { kMusicDeviceProperty_GroupOutputBus = 1002, kMusicDeviceProperty_SoundBankFSSpec = 1003, kAudioUnitProperty_PannerMode = 3008 }; ///$$$ THESE NEED TO BE EXCLUDED FROM 64BIT $$$ enum { kAudioUnitProperty_SpeakerConfiguration = 3001 }; // Deprecated in favor of the newer AudioChannelLayout // structure and its supporting property. enum { kSpeakerConfiguration_HeadPhones = 0, kSpeakerConfiguration_Stereo = 1, kSpeakerConfiguration_Quad = 2, kSpeakerConfiguration_5_0 = 3, kSpeakerConfiguration_5_1 = kSpeakerConfiguration_5_0 }; // Deprecated in favor of the newer AUSamplerInstrumentData // structure and its supporting property. typedef struct AUSamplerBankPresetData { CFURLRef bankURL; UInt8 bankMSB; UInt8 bankLSB; UInt8 presetID; UInt8 reserved; } AUSamplerBankPresetData; enum { kAUSamplerProperty_LoadPresetFromBank = 4100, }; #endif // !TARGET_OS_IPHONE #endif // __AudioUnitProperties