1 {!
2 @file AudioUnitProperties.h
3 @framework AudioToolbox.framework
4 @copyright (c) 2000-2015 Apple, Inc. All rights reserved.
5 @abstract Property ID's and accompanying structs used by Apple audio units.
6
7 @discussion
8
9 Properties form the basis of much of the audio unit API. You use them with
10 these AudioUnit.framework API functions declared in AUComponent.h:
11
12 AudioUnitGetPropertyInfo
13 AudioUnitGetProperty
14 AudioUnitSetProperty
15
16 This file first lists generic audio unit properties (those that are potentially applicable to
17 any audio unit), followed by properties specific to Apple audio units.
18
19 Apple reserves property IDs from 0 -> 63999. Developers are free to use property IDs above this
20 range.
21
22 All property values are passed by reference. When a property's value type is listed below,
23 that value type is always passed by reference. For example, CFStringRef is passed as
24 &myCFString.
25
26 Properties are described below using a general form:
27 Scope: The audio unit scope that the property applies to. For example, Global,
28 Input, Output, etc. For an explanation of audio unit scopes, see the
29 Audio Unit Programming Guide in the ADC Reference Library.
30 Value Type: The data type used to hold the value associated with the property. For
31 example, CFStringRef or UInt32
32 Access: How a host application can access the property in a hosted audio unit:
33 read only, write only, or read/write.
34 Description: A description of the property's role.
35
36 The descriptions in this file apply to typical or recommended usage. Audio unit developers can
37 vary the way each property is used. For example, a property may be described as applying to both
38 input and output scopes, but a given audio unit may implement the property on the input scope
39 only. As another example, a property may be described here as having read/write access, but an
40 audio unit may implement the property as read only.
41
42 The properties are divided into two primary sections:
43 (1) Core/Embedded Implementation
44 - these properties are available on all platforms where audio units are available
45
46 (2) OS X
47 - these properties are available on only available on OS X
48 }
49 { Pascal Translation: Gorazd Krosl <gorazd_1957@yahoo.ca>, October 2009 }
50 { Pascal Translation Update: Jonas Maebe <jonas@freepascal.org>, October 2012 }
51 { Pascal Translation Update: Jonas Maebe <jonas@freepascal.org>, October 2010 }
52
53 {
54 Modified for use with Free Pascal
55 Version 308
56 Please report any bugs to <gpc@microbizz.nl>
57 }
58
59 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
60 {$mode macpas}
61 {$modeswitch cblocks}
62 {$packenum 1}
63 {$macro on}
64 {$inline on}
65 {$calling mwpascal}
66
67 unit AudioUnitProperties;
68 interface
69 {$setc UNIVERSAL_INTERFACES_VERSION := $0400}
70 {$setc GAP_INTERFACES_VERSION := $0308}
71
72 {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
73 {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
74 {$endc}
75
76 {$ifc defined CPUPOWERPC and defined CPUI386}
77 {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
78 {$endc}
79 {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
80 {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
81 {$endc}
82
83 {$ifc not defined __ppc__ and defined CPUPOWERPC32}
84 {$setc __ppc__ := 1}
85 {$elsec}
86 {$setc __ppc__ := 0}
87 {$endc}
88 {$ifc not defined __ppc64__ and defined CPUPOWERPC64}
89 {$setc __ppc64__ := 1}
90 {$elsec}
91 {$setc __ppc64__ := 0}
92 {$endc}
93 {$ifc not defined __i386__ and defined CPUI386}
94 {$setc __i386__ := 1}
95 {$elsec}
96 {$setc __i386__ := 0}
97 {$endc}
98 {$ifc not defined __x86_64__ and defined CPUX86_64}
99 {$setc __x86_64__ := 1}
100 {$elsec}
101 {$setc __x86_64__ := 0}
102 {$endc}
103 {$ifc not defined __arm__ and defined CPUARM}
104 {$setc __arm__ := 1}
105 {$elsec}
106 {$setc __arm__ := 0}
107 {$endc}
108 {$ifc not defined __arm64__ and defined CPUAARCH64}
109 {$setc __arm64__ := 1}
110 {$elsec}
111 {$setc __arm64__ := 0}
112 {$endc}
113
114 {$ifc defined cpu64}
115 {$setc __LP64__ := 1}
116 {$elsec}
117 {$setc __LP64__ := 0}
118 {$endc}
119
120
121 {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
122 {$error Conflicting definitions for __ppc__ and __i386__}
123 {$endc}
124
125 {$ifc defined __ppc__ and __ppc__}
126 {$setc TARGET_CPU_PPC := TRUE}
127 {$setc TARGET_CPU_PPC64 := FALSE}
128 {$setc TARGET_CPU_X86 := FALSE}
129 {$setc TARGET_CPU_X86_64 := FALSE}
130 {$setc TARGET_CPU_ARM := FALSE}
131 {$setc TARGET_CPU_ARM64 := FALSE}
132 {$setc TARGET_OS_MAC := TRUE}
133 {$setc TARGET_OS_IPHONE := FALSE}
134 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
135 {$setc TARGET_OS_EMBEDDED := FALSE}
136 {$elifc defined __ppc64__ and __ppc64__}
137 {$setc TARGET_CPU_PPC := FALSE}
138 {$setc TARGET_CPU_PPC64 := TRUE}
139 {$setc TARGET_CPU_X86 := FALSE}
140 {$setc TARGET_CPU_X86_64 := FALSE}
141 {$setc TARGET_CPU_ARM := FALSE}
142 {$setc TARGET_CPU_ARM64 := FALSE}
143 {$setc TARGET_OS_MAC := TRUE}
144 {$setc TARGET_OS_IPHONE := FALSE}
145 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
146 {$setc TARGET_OS_EMBEDDED := FALSE}
147 {$elifc defined __i386__ and __i386__}
148 {$setc TARGET_CPU_PPC := FALSE}
149 {$setc TARGET_CPU_PPC64 := FALSE}
150 {$setc TARGET_CPU_X86 := TRUE}
151 {$setc TARGET_CPU_X86_64 := FALSE}
152 {$setc TARGET_CPU_ARM := FALSE}
153 {$setc TARGET_CPU_ARM64 := FALSE}
154 {$ifc defined iphonesim}
155 {$setc TARGET_OS_MAC := FALSE}
156 {$setc TARGET_OS_IPHONE := TRUE}
157 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
158 {$elsec}
159 {$setc TARGET_OS_MAC := TRUE}
160 {$setc TARGET_OS_IPHONE := FALSE}
161 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
162 {$endc}
163 {$setc TARGET_OS_EMBEDDED := FALSE}
164 {$elifc defined __x86_64__ and __x86_64__}
165 {$setc TARGET_CPU_PPC := FALSE}
166 {$setc TARGET_CPU_PPC64 := FALSE}
167 {$setc TARGET_CPU_X86 := FALSE}
168 {$setc TARGET_CPU_X86_64 := TRUE}
169 {$setc TARGET_CPU_ARM := FALSE}
170 {$setc TARGET_CPU_ARM64 := FALSE}
171 {$ifc defined iphonesim}
172 {$setc TARGET_OS_MAC := FALSE}
173 {$setc TARGET_OS_IPHONE := TRUE}
174 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
175 {$elsec}
176 {$setc TARGET_OS_MAC := TRUE}
177 {$setc TARGET_OS_IPHONE := FALSE}
178 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
179 {$endc}
180 {$setc TARGET_OS_EMBEDDED := FALSE}
181 {$elifc defined __arm__ and __arm__}
182 {$setc TARGET_CPU_PPC := FALSE}
183 {$setc TARGET_CPU_PPC64 := FALSE}
184 {$setc TARGET_CPU_X86 := FALSE}
185 {$setc TARGET_CPU_X86_64 := FALSE}
186 {$setc TARGET_CPU_ARM := TRUE}
187 {$setc TARGET_CPU_ARM64 := FALSE}
188 {$setc TARGET_OS_MAC := FALSE}
189 {$setc TARGET_OS_IPHONE := TRUE}
190 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
191 {$setc TARGET_OS_EMBEDDED := TRUE}
192 {$elifc defined __arm64__ and __arm64__}
193 {$setc TARGET_CPU_PPC := FALSE}
194 {$setc TARGET_CPU_PPC64 := FALSE}
195 {$setc TARGET_CPU_X86 := FALSE}
196 {$setc TARGET_CPU_X86_64 := FALSE}
197 {$setc TARGET_CPU_ARM := FALSE}
198 {$setc TARGET_CPU_ARM64 := TRUE}
199 {$ifc defined ios}
200 {$setc TARGET_OS_MAC := FALSE}
201 {$setc TARGET_OS_IPHONE := TRUE}
202 {$setc TARGET_OS_EMBEDDED := TRUE}
203 {$elsec}
204 {$setc TARGET_OS_MAC := TRUE}
205 {$setc TARGET_OS_IPHONE := FALSE}
206 {$setc TARGET_OS_EMBEDDED := FALSE}
207 {$endc}
208 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
209 {$elsec}
210 {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ nor __arm64__ is defined.}
211 {$endc}
212
213 {$ifc defined __LP64__ and __LP64__ }
214 {$setc TARGET_CPU_64 := TRUE}
215 {$elsec}
216 {$setc TARGET_CPU_64 := FALSE}
217 {$endc}
218
219 {$ifc defined FPC_BIG_ENDIAN}
220 {$setc TARGET_RT_BIG_ENDIAN := TRUE}
221 {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
222 {$elifc defined FPC_LITTLE_ENDIAN}
223 {$setc TARGET_RT_BIG_ENDIAN := FALSE}
224 {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
225 {$elsec}
226 {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
227 {$endc}
228 {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
229 {$setc CALL_NOT_IN_CARBON := FALSE}
230 {$setc OLDROUTINENAMES := FALSE}
231 {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
232 {$setc OPAQUE_UPP_TYPES := TRUE}
233 {$setc OTCARBONAPPLICATION := TRUE}
234 {$setc OTKERNEL := FALSE}
235 {$setc PM_USE_SESSION_APIS := TRUE}
236 {$setc TARGET_API_MAC_CARBON := TRUE}
237 {$setc TARGET_API_MAC_OS8 := FALSE}
238 {$setc TARGET_API_MAC_OSX := TRUE}
239 {$setc TARGET_CARBON := TRUE}
240 {$setc TARGET_CPU_68K := FALSE}
241 {$setc TARGET_CPU_MIPS := FALSE}
242 {$setc TARGET_CPU_SPARC := FALSE}
243 {$setc TARGET_OS_UNIX := FALSE}
244 {$setc TARGET_OS_WIN32 := FALSE}
245 {$setc TARGET_RT_MAC_68881 := FALSE}
246 {$setc TARGET_RT_MAC_CFM := FALSE}
247 {$setc TARGET_RT_MAC_MACHO := TRUE}
248 {$setc TYPED_FUNCTION_POINTERS := TRUE}
249 {$setc TYPE_BOOL := FALSE}
250 {$setc TYPE_EXTENDED := FALSE}
251 {$setc TYPE_LONGLONG := TRUE}
252 uses MacTypes,AUComponent,AudioFile,CoreAudioTypes,MIDIServices,CFBase,CFURL;
253 {$endc} {not MACOSALLINCLUDE}
254
255 {$ALIGN POWER}
256
257
258 //=====================================================================================================================
259 //#pragma mark Overview
260
261 //#pragma mark -
262 //#pragma mark Core Implementation
263 //#pragma mark -
264 {!
265 @enum Audio Unit scope types
266 @abstract The scope IDs for audio units define basic roles and contexts for an audio unit's state.
267 @discussion Each scope is a discrete context. Apple reserves scope IDs from 0 through 1024.
268
269 @constant kAudioUnitScope_Global The context for audio unit characteristics that apply to the audio unit as a
270 whole
271 @constant kAudioUnitScope_Input The context for audio data coming into an audio unit
272 @constant kAudioUnitScope_Output The context for audio data leaving an audio unit
273 @constant kAudioUnitScope_Group A context specific to the control scope of parameters (for instance,
274 MIDI Channels is an example of this scope)
275 @constant kAudioUnitScope_Part A distinct rendering context. For instance a single timbre in a multi-timbral
276 instrument, a single loop in a multi looping capable looper unit, etc.
277 @constant kAudioUnitScope_Note A scope that can be used to apply changes to an individual note. The
278 elementID used with this scope is the unique note ID returned from
279 a started note (see MusicDeviceStartNote)
280 @constant kAudioUnitScope_Layer A context which functions as a layer within a part and allows
281 grouped control of LayerItem-scope parameters.
282 An example is the percussive attack layer for an electric organ instrument
283 @constant kAudioUnitScope_LayerItem A scope which represents an individual element within a particular Layer scope.
284 The individual sample zones, envelope generators, and filters within a synth are
285 examples of this.
286 }
287 const
288 kAudioUnitScope_Global = 0;
289 kAudioUnitScope_Input = 1;
290 kAudioUnitScope_Output = 2;
291 kAudioUnitScope_Group = 3;
292 kAudioUnitScope_Part = 4;
293 kAudioUnitScope_Note = 5;
294 kAudioUnitScope_Layer = 6;
295 kAudioUnitScope_LayerItem = 7;
296
297
298 //=====================================================================================================================
299 //#pragma mark Audio Unit Properties
300
301 {!
302 @enum Generic Property IDs
303 @abstract Properties that can apply to any audio unit.
304
305 @constant kAudioUnitProperty_ClassInfo
306 Scope: Global (or Part for a part scope preset)
307 Value Type: CFDictionaryRef
308 Access: Read / Write
309
310 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
311 that apply to individual parts.
312
313 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
314 views, etc, can update their state). Something like the following code should be used:
315
316 <code>
317
318 AudioUnitParameter changedUnit;
319 changedUnit.mAudioUnit = theChangedAU;
320 changedUnit.mParameterID = kAUParameterListener_AnyParameter;
321 AUParameterListenerNotify (NULL, NULL, &changedUnit);
322 </code>
323
324
325 @constant kAudioUnitProperty_MakeConnection
326 Scope: Input
327 Value Type: AudioUnitConnection
328 Access: Write
329
330 @constant kAudioUnitProperty_SampleRate
331 Scope: Input / Output
332 Value Type: Float64
333 Access: Read / Write
334
335 @constant kAudioUnitProperty_ParameterList
336 Scope: Any
337 Value Type: AudioUnitParameterID
338 Access: Read
339
340 The list of parameter IDs on the specified scope
341
342 @constant kAudioUnitProperty_ParameterInfo
343 Scope: Any
344 Element: AudioUnitParameterID of the parameter being queried
345 Value Type: AudioUnitParameterInfo
346 Access: Read
347
348 The info struct describes the general characteristics of an individual parameterID
349
350 @constant kAudioUnitProperty_FastDispatch
351 Scope: Global
352 Value Type: void* (function pointer)
353 Access: Read
354
355 The caller provides the selector for a given audio unit API, and retrieves a function pointer for that selector. For instance,
356 this enables the caller to retrieve the function pointer for the AudioUnitRender call, so that call can be made directly
357 through to the audio unit to avoid the overhead of the ComponentMgr's dispatch.
358
359 @constant kAudioUnitProperty_CPULoad
360 Scope: Global
361 Value Type: Float64
362 Access: Read
363
364 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.
365
366 @constant kAudioUnitProperty_StreamFormat
367 Scope: Input / Output
368 Value Type: AudioStreamBasicDescription
369 Access: Read / Write
370
371 An AudioStreamBasicDescription is used to specify the basic format for an audio data path. For instance, 2 channels, 44.1KHz, Float32 linear pcm.
372 The value can be both set and retrieve from an I/O element (bus)
373
374 @constant kAudioUnitProperty_ElementCount
375 Scope: Any (though Global scope will always have an element count of 1)
376 Value Type: UInt32
377 Access: Read / Write
378
379 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).
380 Some audio units possess the capability to add or remove elements, so in that case this property will be writable.
381
382 @constant kAudioUnitProperty_Latency
383 Scope: Global
384 Value Type: Float64
385 Access: Read
386
387 The processing latency (the time it takes an audio unit to represent an input in its audio output) specified in seconds
388
389 @constant kAudioUnitProperty_SupportedNumChannels
390 Scope: Global
391 Value Type: AUChannelInfo array
392 Access: Read
393
394 The size of this property will represent the number of AUChannelInfo structs that an audio unit provides. Each entry describes a particular number of
395 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
396 of 2 channels on an input and 2 channels on an output.
397
398 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.
399 (-1, -2) means any number of channels on input or output buses
400
401 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
402 particular bus.
403
404 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.
405
406 @constant kAudioUnitProperty_MaximumFramesPerSlice
407 Scope: Global
408 Value Type: UInt32
409 Access: Read / Write
410
411 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.
412
413 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,
414 it should "break up" its input pulls).
415
416 @constant kAudioUnitProperty_SetExternalBuffer
417 Scope: Global
418 Value Type: AudioUnitExternalBuffer
419 Access: Write
420
421 This is used to provide to an audio unit a buffer that it can use with its input render callback's audio buffer list
422
423 @constant kAudioUnitProperty_ParameterValueStrings
424 Scope: Any
425 Element: AudioUnitParameterID of the parameter being queried
426 Value Type: CFArrayRef
427 Access: Read
428
429 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
430 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.
431 The array's strings can then be used to build a menu for that parameter.
432
433 @constant kAudioUnitProperty_GetUIComponentList
434 Scope: Any
435 Value Type: AudioComponentDescription array
436 Access: Read
437
438 Presents an array of AudioComponentDescription that are of type 'auvw' (AudioUnitCarbonView). These are the carbon based custom views for that audio unit.
439
440 @constant kAudioUnitProperty_AudioChannelLayout
441 Scope: Input/Output
442 Value Type: struct AudioChannelLayout
443 Access: read/write
444
445 Description:
446 Describes for a given scope/element the order of channels within a given stream.
447 The number of channels it describes must match the number of channels set for that
448 scope/element. Each input and output bus in an audio unit can have one instance of
449 this property.
450
451 Some audio units require this property. For example, the 3DMixer unit must
452 implement this property on its output bus. If a host application attempts to
453 clear the value of this property on a bus that requires a valid value, the
454 audio unit will return a kAudioUnitErr_InvalidPropertyValue error.
455
456 Input and output buses can be in one of three states in regard to Audio
457 channel layout:
458
459 1. implemented and set
460 2. implemented but not set
461 3. unimplemented
462
463 Requesting the value of this property when it is implemented but not set
464 results in a kAudioUnitErr_PropertyNotInUse error.
465
466 Use the kAudioUnitProperty_AudioChannelLayout property whenever channel
467 layout is relevant. By comparison, the kAudioUnitProperty_StreamFormat
468 property cannot specify channel layout or purpose.
469
470 See also: kAudioUnitProperty_SupportedChannelLayoutTags,
471 kAudioUnitProperty_StreamFormat.
472
473 @constant kAudioUnitProperty_TailTime
474 Scope: Global
475 Value Type: Float64
476 Access: Read
477
478 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
479 decay time of a reverb or a delay. In general this will be a conservative estimate.
480
481 @constant kAudioUnitProperty_BypassEffect
482 Scope: Global
483 Value Type: UInt32
484 Access: Read / Write
485
486 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
487
488 @constant kAudioUnitProperty_LastRenderError
489 Scope: Global
490 Value Type: OSStatus
491 Access: Read
492
493 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
494 those listeners can then use this property ID to retrieve that error.
495
496 @constant kAudioUnitProperty_SetRenderCallback
497 Scope: Input
498 Value Type: AURenderCallbackStruct
499 Access: Write
500
501 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
502 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
503 and the audio unit will return an error from AudioUnitRender.
504
505 @constant kAudioUnitProperty_FactoryPresets
506 Scope: Global
507 Value Type: CFArray of AUPreset structures
508 Access: Read
509
510 An array of preset structures that provide a name and number for each preset. A factory preset is then chosen using the PresentPreset property.
511
512 @constant kAudioUnitProperty_ContextName
513 Scope: Global
514 Value Type: CFString
515 Access: Read / Write
516
517 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
518 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.
519
520 @constant kAudioUnitProperty_RenderQuality
521 Scope: Global
522 Value Type: UInt32
523 Access: Read / Write
524
525 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
526 if CPU usage is a concern a lesser quality can be set to trade off render quality.
527
528 @constant kAudioUnitProperty_HostCallbacks
529 Scope: Global
530 Value Type: HostCallbackInfo
531 Access: Write
532
533 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
534 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.
535 For example, what is the current beat of the host, is the transport running, and so forth.
536
537 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.
538 The exception is that the unit must always specify the HostUserData which was be supplied to the unit when the property was set.
539
540 If the host is unable to provide the requested information then it can return the kAudioUnitErr_CannotDoInCurrentContext error code
541
542 @constant kAudioUnitProperty_InPlaceProcessing
543 Scope: Global
544 Value Type: UInt32
545 Access: Read / Write
546
547 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
548 has a particular buffer management strategy and such an operation would defeat that.
549
550 @constant kAudioUnitProperty_ElementName
551 Scope: any
552 Value Type: CFStringRef
553 Access: read/write
554 Description:
555 The name of the specified element. The Host owns a reference to this property value
556 (as with all other CF properties), and should release the string retrieved or used when setting.
557
558 @constant kAudioUnitProperty_CocoaUI
559 Scope: Global
560 Value Type: struct AudioUnitCocoaViewInfo
561 Access: read
562
563 Publishes the audio unit's custom Cocoa NSViews. The Host can determine how big this structure is by
564 querying the size of the property (i.e., How many alternate UI classes there are for the unit)
565 Typically, most audio units will provide 1 UI class per unit
566
567 @constant kAudioUnitProperty_SupportedChannelLayoutTags
568 Scope: Input/Output
569 Value Type: AudioChannelLayoutTags[ variable number of elements ]
570 Access: read only
571
572 Used with GetProperty to ascertain what an audio unit understands about
573 laying out of channel orders. This will normally return one or more of the specified layout tags.
574
575 When a specific set of layouts are returned, the client then uses the
576 kAudioUnitProperty_AudioChannelLayout property (with one of those layout tags specified) to set
577 the unit to use that layout. In this case the client (and the audio unit when reporting its
578 AudioChannelLayout) is only expected to have set an AudioChannelLayout which only sets the
579 layout tag as the valid field.
580
581 Custom Channel Maps:
582 Some audio units may return the tag:
583 kAudioChannelLayoutTag_UseChannelDescriptions
584
585 In this case, the host then can look at supported number of channels on that scope
586 (using the kAudioUnitProperty_SupportedNumChannels), and supply an AudioChannelLayout with the
587 kAudioUnitProperty_AudioChannelLayout property to specify the layout, number of channels
588 and location of each of those channels. This custom channel map MUST have a channel valence
589 that is supported by the Audio Unit.
590
591 The UseChannelBitmap field is NOT used within the context of the AudioUnit.
592
593 @constant kAudioUnitProperty_ParameterIDName
594 Scope: any
595 Element: AudioUnitParameterID of the parameter being queried
596 Value Type: AudioUnitParameterIDName
597 Access: read
598
599 An audio unit returns the full parameter name in the GetParameterInfo struct/property.
600 In some display situations however, there may only be room for a few characters, and
601 truncating this full name may give a less than optimal name for the user. Thus,
602 this property can be used to ask the audio unit whether it can supply a truncated name, with
603 the host suggesting a length (number of characters). If the unit returns a longer
604 name than the host requests, that name may be truncated to the requested characters in display.
605 The unit could return a shorter name than requested as well. The unit returns a CFString
606 that should be released by the host. When using this property, the host asks for
607 the name in the same scope and element as the unit publishes the parameter.
608
609 @constant kAudioUnitProperty_ParameterClumpName
610 Scope: any
611 Value Type: AudioUnitParameterIDName
612 Access: read
613
614 This works in a similar manner to the ParameterIDName property, except that the inID
615 value is one of the clumpID's that are returned with the audio unit's ParameterInfo
616 structure.
617
618 @constant kAudioUnitProperty_PresentPreset
619 Scope: Global/Part
620 Value Type: AUPreset
621 Access: read/write
622
623 This property replaces the deprecated CurrentPreset property, due to the ambiguity of
624 ownership of the CFString of the preset name in the older CurrentPreset property.
625 With PresentPreset the client of the audio unit owns the CFString when it retrieves the
626 preset with PresentPreset and is expected to release this (as with ALL properties
627 that retrieve a CF object from an audio unit).
628
629 @constant kAudioUnitProperty_OfflineRender
630 Scope: Global
631 Value Type: UInt32
632 Access: Read / Write
633
634 This is used by the host to indicate when an audio unit (that normally operates within a general real-time calling model) is
635 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
636 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
637
638 @constant kAudioUnitProperty_ParameterStringFromValue
639 Scope: any
640 Value Type: AudioUnitParameterStringFromValue
641 Access: read
642
643 This property is used with parameters that are marked with the
644 kAudioUnitParameterFlag_HasName parameter info flag. This indicates that some
645 (or all) of the values represented by the parameter can and should be
646 represented by a special display string.
647
648 This is NOT to be confused with kAudioUnitProperty_ParameterValueStrings. That property
649 is used with parameters that are indexed and is typically used for instance to build
650 a menu item of choices for one of several parameter values.
651
652 kAudioUnitProperty_ParameterStringFromValue can have a continuous range, and merely states
653 to the host that if it is displaying those parameter's values, they should request
654 a name any time any value of the parameter is set when displaying that parameter.
655
656 For instance (a trivial example), a unit may present a gain parameter in a dB scale,
657 and wish to display its minimum value as "negative infinity". In this case, the audio unit
658 will not return names for any parameter value greater than its minimum value - so the host
659 will then just display the parameter value as is. For values less than or equal to the
660 minimum value, the audio unit will return a string for "negative infinity" which the host can
661 use to display appropriately.
662
663 A less trivial example might be a parameter that presents its values as seconds. However,
664 in some situations this value should be better displayed in a SMPTE style of display:
665 HH:MM:SS:FF
666 In this case, the audio unit would return a name for any value of the parameter.
667
668 The GetProperty call is used in the same scope and element as the inParamID
669 that is declared in the struct passed in to this property.
670
671 If the *inValue member is NULL, then the audio unit should take the current value
672 of the specified parameter. If the *inValue member is NOT NULL, then the audio unit should
673 return the name used for the specified value.
674
675 On exit, the outName may point to a CFStringRef (which if so must be released by the caller).
676 If the parameter has no special name that should be applied to that parameter value,
677 then outName will be NULL, and the host should display the parameter value as
678 appropriate.
679
680
681 @constant kAudioUnitProperty_ParameterValueFromString
682 Scope: any
683 Value Type: AudioUnitParameterValueFromString
684 Access: read
685
686 This property returns the value of a parameter from its string representation. See kAudioUnitProperty_ParameterStringFromValue.
687
688 @constant kAudioUnitProperty_IconLocation
689 Scope: Global
690 Value Type: CFURLRef
691 Access: Read
692
693 A URL that will specify the location of an icon file that can be used when presenting UI for this audio unit.
694
695 @constant kAudioUnitProperty_PresentationLatency
696 Scope: Input/Output
697 Value Type: Float64
698 Access: write
699
700 This property is set by a host to describe to the audio unit the presentation latency of both
701 any of its input and/or output audio data.
702 It describes this latency in seconds. A value of zero means either no latency
703 or an unknown latency.
704
705 This is a write only property because the host is telling the audio unit the latency of both the
706 data it provides it for input and the latency from getting the data from the unit until it is
707 presented.
708
709 The property is should be set on each active input and output bus (Scope/Element pair).
710 For example, an audio unit with multiple outputs will have the output data it produces processed
711 by different audio units, etc before it is mixed and presented. Thus, in this case, each output
712 element could have a different presentation latency.
713
714 This should not be confused with the Latency property, where the audio unit describes to the host
715 any processing latency it introduces between its input and its output.
716
717 For input:
718 Describes how long ago the audio given to an audio unit was acquired. For instance, when
719 reading from a file to the first audio unit, then its input presentation latency will be zero.
720 When processing audio input from a device, then this initial input latency will be the
721 presentation latency of the device itself, the device's safety offset and latency.
722
723 The next audio unit's (connected to that first unit) input presentation latency will be the
724 input presentation latency of the first unit, plus the processing latency (as expressed by
725 kAudioUnitProperty_Latency) of the first unit.
726
727 For output:
728 Describes how long before the output audio of an audio unit is to be presented. For instance,
729 when writing to a file, then the last audio unit's output presentation latency will be zero.
730 When the audio from that audio unit is to be played to an AudioDevice, then that initial
731 presentation latency will be the latency of the device itself - which is the I/O buffer size,
732 and the device's safety offset and latency
733
734 The previous audio unit's (connected to this last unit) output presentation latency will be that
735 initial presentation latency plus the processing latency (as expressed by
736 kAudioUnitProperty_Latency) of the last unit.
737
738 So, for a given audio unit anywhere within a mixing graph, the input and output presentation
739 latencies describe to that unit how long from the moment of generation it will take for its
740 input to arrive, and how long it will take for its output to be presented.
741
742 You can use this property, for example, to provide metering for an audio unit that
743 is generating output to be presented to the user at a future time.
744
745 @constant kAudioUnitProperty_DependentParameters
746 Scope: any
747 Value Type: array of AUDependentParameter
748 Access: read
749
750 This property is used for parameters with the kAudioUnitParameterFlag_IsGlobalMeta
751 or kAudioUnitParameterFlag_IsElementMeta flags set. Hosts applications (and the
752 AudioUnitParameterListener mechanism) can interrogate this property to determine which parameters
753 are dependent on a
754 meta-parameter.
755
756 For parameters marked with kAudioUnitParameterFlag_IsGlobalMeta, any non-global
757 dependent parameters are assumed to be dependent in every element of their scope.
758
759 For parameters marked with kAudioUnitParameterFlag_IsElementMeta, then its dependent
760 parameters must all be the same scope, and are assumed to apply only within a single element,
761 not to other instances of the same parameter in other elements.
762
763 @constant kAudioUnitProperty_AUHostIdentifier
764 Scope: Global
765 Value Type: AUHostVersionIdentifier
766 Access: write
767
768 Determine which application (and which version) an audio unit is being hosted by.
769 This is made more complex through the intervention of audio units such as Kore, that are hosting
770 other audio units (in this case of course, the real host of the audio unit is the hosting unit,
771 not the host application, so the previous mechanism of getting the main bundle ID is no longer
772 correct).
773
774 There are also inconsistencies in the way that bundle identifiers are applied (with apps changing
775 these from version to version), and we'd prefer to see a more consistent identifier used with
776 this property. This is in spirit similar to the string returned by CFBundle API, except that we
777 require this host string be consistent and reliable through different revisions of the host.
778
779 The audio unit is responsible for retaining the hostName string if it needs to use it past the
780 duration of the actual call. The host should set this property as early as possible within the
781 lifetime of the unit in a session.
782
783 This API used to take a NumVersion struct. It is redefined to take an AUHostVersionIdentifier struct
784 which is binary compatible with the existing usage, but not source compatible.
785
786 @constant kAudioUnitProperty_MIDIOutputCallbackInfo
787 Scope: Global
788 Value Type: CFArrayRef
789 Access: read
790
791 Used to determine how many MIDI output streams the audio unit can generate (and the name for
792 each of these outputs). Each MIDI output is a complete MIDI data stream, such as embodied by a
793 MIDIEndpointRef in CoreMIDI.
794
795 The host can retrieve an array of CFStringRefs published by the audio unit, where :
796 - the size of the array is the number of MIDI Outputs the audio unit supports
797 - each item in the array is the name for that output at that index
798
799 The host should release the array when it is finished with it.
800
801 Once the host has determined that the audio unit supports this feature, it can then provide a
802 callback, through which the audio unit can send the MIDI data.
803 See the documentation for the kAudioUnitProperty_MIDIOutputCallback property.
804
805 @constant kAudioUnitProperty_MIDIOutputCallback
806 Scope: Global
807 Value Type: AUMIDIOutputCallbackStruct
808 Access: write
809
810 The host sets this property on the audio unit with the callback (and its user data) set
811 appropriately.
812
813 Operational Parameters:
814 In the render call, just as is the expected usage of the AUHostCallbacks, the audio unit can
815 call the provided callback to provide MIDI data to the host that it will associate with the
816 current AudioUnitRender call in process.
817
818 The audio unit in the callback provides:
819 - the user data provided by the host when the callback was established
820 - the AudioTimeStamp that was provided to the audio unit for this particular call of
821 AudioUnitRender
822 - the output number to associate this MIDI data with
823 - a MIDI Packet List containing MIDI data. The time stamp values contained within the
824 MIDIPackets in this list are **sample offsets*** from the AudioTimeStamp provided.
825 This allows MIDI data to be time-stamped with a sample offset that is directly associated
826 with the audio data it is generating in the current call to the AudioUnitRender function
827
828 There is no implied or expected association between the number (or position) of an audio unit's
829 audio or MIDI outputs.
830
831 @constant kAudioUnitProperty_InputSamplesInOutput
832 Scope: Global
833 Value Type: struct AUInputSamplesInOutputCallbackStruct
834 Access: read/write
835
836 An audio unit calls this callback at the end of its render call. The audio unit supplies the
837 following information:
838
839 outputTime - The timestamp passed in to the audio unit's render call. This timestamp
840 represents the time of the first output sample.
841 inputSample - The sample number of the first input sample that is present in the output
842 audio.
843 numInputSamples - The number of input samples that were used and are present in the output
844 audio.
845
846 This property allows a host application to determine which input samples correspond to a sample
847 in the output buffer. It is useful only for audio units that do time-stretching, such as the
848 AUVarispeed and AUTimePitch units, where the relationship between input and output samples is
849 non-trivial. For these units, the range of input samples that correspond to an output buffer
850 typically differs from the range of input samples that were pulled for that render call.
851 This difference arises because of internal buffering, processing latency, and other factors.
852
853 @constant kAudioUnitProperty_ClassInfoFromDocument
854 Scope: Global
855 Value Type: CFDictionary
856 Access: read/write
857
858 If the audio unit implements this property then it is going to do different actions establishing
859 its state from a document rather than from a user preset. Thus, a host app should use this property
860 first (instead of kAudioUnitProperty_ClassInfo) when restoring the state of an audio unit when
861 opening a document. If the audio unit returns an error (or doesn't implement this property) then
862 the host should use the same preset with the kAudioUnitProperty_ClassInfo.
863
864
865 @constant kAudioUnitProperty_ShouldAllocateBuffer
866 Scope: input/output elements (settable per element)
867 Value Type: UInt32
868 Access: read/write
869
870 By default this value is true. This affects the allocations of the buffers for I/O (the mData field
871 of the AudioBufferList used with AudioUnitRender, callbacks and connections)
872
873 If true, the element will create a buffer for rendering into.
874
875 If false, the element will not create a buffer for rendering.
876
877 For example, if the audio unit is only ever going to have a connection as its input and never a callback, then
878 it should not need to create a buffer (the API contract expects an audio unit to provide a buffer for
879 callbacks, but no buffer for connections).
880
881 If the audio unit is always going to be pulled for audio with the client providing audio data buffers to
882 the AudioUnitRender call, then it will never need to create an audio buffer on the output side.
883
884 So, this property can be used to control the default allocation strategy of an audio unit. If the audio unit
885 needs a buffer, but one hasn't been allocated, then an error will be thrown from that call to AudioUnitRender.
886
887 This property cannot be set on Initialised audio units as it may end up reallocating memory.
888
889
890 @constant kAudioUnitProperty_FrequencyResponse
891 Scope: input/output elements (settable per element)
892 Value Type: AudioUnitFrequencyResponseBin
893 Access: read
894
895 The property provides a way for a user interface view to get points for drawing a graph of the frequency
896 response of the AU.
897
898 An array of AudioUnitFrequencyResponseBin are passed in to kAudioUnitProperty_FrequencyResponse
899 with the mFrequency field filled in. The array is returned with the mMagnitude fields filled in.
900 If fewer than kNumberOfResponseFrequencies are needed, then the first unused bin should be marked with
901 a negative frequency.
902
903 @constant kAudioUnitProperty_ParameterHistoryInfo
904 Scope: Global
905 Value Type: AudioUnitParameterHistoryInfo
906 Access: read
907
908 For parameters which have kAudioUnitParameterFlag_PlotHistory set, getting this property fills out the
909 AudioUnitParameterHistoryInfo struct containing the recommended update rate and history duration.
910
911 @constant kAudioUnitProperty_NickName
912 Scope: Global
913 Value Type: CFStringRef
914 Access: read/write
915
916 Provides a way for a host to set a custom name on an AU.
917
918 An example of when this is useful is when a host is managing a processing chain that contains multiple AU
919 instances of the same subtype (and type and manufacturer). The host uses this property to assign a
920 unique name to each AU instance indicating what that particular instance's function is in the processing
921 chain and can later query the property to distinguish between AU instances with the same type/subtype/manu
922 tuple. It is the host's responsibility to keep the names unique if uniqueness is required.
923
924 When getting this property, ownership follows Core Foundation's 'Copy Rule'. This property may return NULL
925 which indicates that no name has been set on the AU.
926
927 @constant kAudioUnitProperty_RequestViewController
928 Scope: Global
929 Value Type: block: void (^)(AUViewControllerBase *)
930 Access: write
931
932 If the audio unit is implemented using the version 3 API, it may provide a
933 view controller, returned via this property. As with any other CoreFoundation
934 or Foundation object returned by AudioUnitGetProperty, the caller must
935 release the returned reference (i.e. the Copy rule is used).
936
937 @constant kAudioUnitProperty_ParametersForOverview
938 Scope: Global
939 Value Type: variably-sized array of struct AudioUnitParameter
940 Access: read
941
942 A host may query an audio unit for a list of its N most important
943 parameters, via this property. The size of the array passed to
944 AudioUnitGetProperty controls the number of AudioUnitParameter values
945 returned.
946 @constant kAudioUnitProperty_SupportsMPE
947 Scope: Global
948 Value Type: UInt32
949 Access: read
950
951 Indicates whether an audio unit supports Multi-dimensional Polyphonic Expression.
952 }
953 const
954 // range (0 -> 999)
955 kAudioUnitProperty_ClassInfo = 0;
956 kAudioUnitProperty_MakeConnection = 1;
957 kAudioUnitProperty_SampleRate = 2;
958 kAudioUnitProperty_ParameterList = 3;
959 kAudioUnitProperty_ParameterInfo = 4;
960 kAudioUnitProperty_CPULoad = 6;
961 kAudioUnitProperty_StreamFormat = 8;
962 kAudioUnitProperty_ElementCount = 11;
963 kAudioUnitProperty_Latency = 12;
964 kAudioUnitProperty_SupportedNumChannels = 13;
965 kAudioUnitProperty_MaximumFramesPerSlice = 14;
966 kAudioUnitProperty_ParameterValueStrings = 16;
967 kAudioUnitProperty_AudioChannelLayout = 19;
968 kAudioUnitProperty_TailTime = 20;
969 kAudioUnitProperty_BypassEffect = 21;
970 kAudioUnitProperty_LastRenderError = 22;
971 kAudioUnitProperty_SetRenderCallback = 23;
972 kAudioUnitProperty_FactoryPresets = 24;
973 kAudioUnitProperty_RenderQuality = 26;
974 kAudioUnitProperty_HostCallbacks = 27;
975 kAudioUnitProperty_InPlaceProcessing = 29;
976 kAudioUnitProperty_ElementName = 30;
977 kAudioUnitProperty_SupportedChannelLayoutTags = 32;
978 kAudioUnitProperty_PresentPreset = 36;
979 kAudioUnitProperty_DependentParameters = 45;
980 kAudioUnitProperty_InputSamplesInOutput = 49;
981 kAudioUnitProperty_ShouldAllocateBuffer = 51;
982 kAudioUnitProperty_FrequencyResponse = 52;
983 kAudioUnitProperty_ParameterHistoryInfo = 53;
984 kAudioUnitProperty_NickName = 54;
985 kAudioUnitProperty_OfflineRender = 37;
986 kAudioUnitProperty_ParameterIDName = 34;
987 kAudioUnitProperty_ParameterStringFromValue = 33;
988 kAudioUnitProperty_ParameterClumpName = 35;
989 kAudioUnitProperty_ParameterValueFromString = 38;
990 kAudioUnitProperty_ContextName = 25;
991 kAudioUnitProperty_PresentationLatency = 40;
992 kAudioUnitProperty_ClassInfoFromDocument = 50;
993 kAudioUnitProperty_RequestViewController = 56;
994 kAudioUnitProperty_ParametersForOverview = 57;
995 kAudioUnitProperty_SupportsMPE = 58;
996 kAudioUnitProperty_FastDispatch = 5;
997 kAudioUnitProperty_SetExternalBuffer = 15;
998 kAudioUnitProperty_GetUIComponentList = 18;
999 kAudioUnitProperty_CocoaUI = 31;
1000 kAudioUnitProperty_IconLocation = 39;
1001 kAudioUnitProperty_AUHostIdentifier = 46;
1002 kAudioUnitProperty_MIDIOutputCallbackInfo = 47;
1003 kAudioUnitProperty_MIDIOutputCallback = 48;
1004
1005
1006 {!
1007 @abstract Keys contains in an audio unit preset (ClassInfo) dictionary
1008 @discussion These strings are used as keys in the AUPreset-"classInfo" dictionary
1009 The actual keys are CFStrings to use these keys you define the key as:
1010 static const CFStringRef kMyVersionString = CFSTR(kAUPresetVersionKey);
1011 }
1012 const
1013 kAUPresetVersionKey = 'version';
1014 const
1015 kAUPresetTypeKey = 'type';
1016 const
1017 kAUPresetSubtypeKey = 'subtype';
1018 const
1019 kAUPresetManufacturerKey = 'manufacturer';
1020 const
1021 kAUPresetDataKey = 'data';
1022 const
1023 kAUPresetNameKey = 'name';
1024 const
1025 kAUPresetRenderQualityKey = 'render-quality';
1026 const
1027 kAUPresetCPULoadKey = 'cpu-load';
1028 const
1029 kAUPresetElementNameKey = 'element-name';
1030 const
1031 kAUPresetExternalFileRefs = 'file-references';
1032
1033 //#if !TARGET_OS_IPHONE
1034 {$ifc not TARGET_OS_IPHONE}
1035 // these are keys to use when a preset contains data from other plugin formats
1036 // vstdata is used to signify VST state from a vst "bank"
1037 const kAUPresetVSTDataKey = 'vstdata';
1038 // vstpreset is used to signify VST state from a vst "preset"
1039 const kAUPresetVSTPresetKey = 'vstpreset';
1040 const kAUPresetMASDataKey = 'masdata';
1041 //#endif
1042 {$endc}
1043
1044 {!
1045 @define kAUPresetPartKey
1046 @discussion This key if present, distinguishes a global preset that is set
1047 on the global scope with a part-based preset that is set on the part scope.
1048 The value of this key is audio unit defined
1049 }
1050 const
1051 kAUPresetPartKey = 'part';
1052
1053
1054 {!
1055 @struct AudioUnitConnection
1056 @abstract This structure contains the information needed to make a connection between a source
1057 and destination audio unit.
1058 @discussion The structure is set on the destination audio unit's input element
1059 @field sourceAudioUnit
1060 The audio unit that is the source for the connection
1061 @field sourceOutputNumber
1062 The source audio unit's output element to be used in the connection
1063 @field destInputNumber
1064 The destination audio unit's input element to be used in the connection
1065 }
1066 type
1067 AudioUnitConnection = record
1068 sourceAudioUnit: AudioUnit {__nullable};
1069 sourceOutputNumber: UInt32;
1070 destInputNumber: UInt32;
1071 end;
1072 AudioUnitConnectionPtr = ^AudioUnitConnection;
1073
1074 {!
1075 @struct AUChannelInfo
1076 @abstract Define an audio unit's channel handling capabilities
1077 }
1078 type
1079 AUChannelInfo = record
1080 inChannels: SInt16;
1081 outChannels: SInt16;
1082 end;
1083 AUChannelInfoPtr = ^AUChannelInfo;
1084
1085 {!
1086 @struct AudioUnitExternalBuffer
1087 @abstract Allow a host to tell an audio unit to use the provided memory for its input callback
1088 }
1089 type
1090 AudioUnitExternalBuffer = record
1091 buffer: BytePtr;
1092 size: UInt32;
1093 end;
1094 AudioUnitExternalBufferPtr = ^AudioUnitExternalBuffer;
1095
1096 {!
1097 @struct AURenderCallbackStruct
1098 @abstract Used by a host when registering a callback with the audio unit to provide input
1099 }
1100 type
1101 AURenderCallbackStruct = record
1102 inputProc: AURenderCallback {__nullable};
1103 inputProcRefCon: UnivPtr {__nullable};
1104 end;
1105 AURenderCallbackStructPtr = ^AURenderCallbackStruct;
1106
1107 {!
1108 @struct AUPreset
1109 @abstract Used to publish and set factory presets on an audio unit
1110 @field presetNumber
1111 If < 0, then preset is a user preset
1112 If >= 0, then this field is used to select the factory preset
1113 @field presetName
1114 If a factory preset, the name of the specified factory preset
1115 }
1116 type
1117 AUPreset = record
1118 presetNumber: SInt32;
1119 presetName: CFStringRef {__nullable};
1120 end;
1121 AUPresetPtr = ^AUPreset;
1122
1123 {!
1124 @enum RenderQuality
1125 @abstract Used to get/set a render quality setting on an audio unit
1126 @discussion Typically, this property is used to trade-off between CPU usage, latency
1127 and the quality of the audio unit's processing/output.
1128 }
1129 const
1130 kRenderQuality_Max = $7F;
1131 kRenderQuality_High = $60;
1132 kRenderQuality_Medium = $40;
1133 kRenderQuality_Low = $20;
1134 kRenderQuality_Min = 0;
1135
1136
1137 {!
1138 @enum kNumberOfResponseFrequencies
1139 @abstract The maximum number of frequency response bins for kAudioUnitProperty_FrequencyResponse.
1140 @discussion An array of AudioUnitFrequencyResponseBin are passed in to kAudioUnitProperty_FrequencyResponse
1141 with the mFrequency field filled in. The array is returned with the mMagnitude fields filled in.
1142 If fewer than kNumberOfResponseFrequencies are needed, then the first unused bin should be marked with
1143 a negative frequency.
1144 }
1145 const
1146 kNumberOfResponseFrequencies = 1024;
1147
1148 {!
1149 @struct AudioUnitFrequencyResponseBin
1150 @abstract Structure used to get the magnitude of the frequency response at a particular frequency via kAudioUnitProperty_FrequencyResponse.
1151 @discussion An array of AudioUnitFrequencyResponseBin are passed in to kAudioUnitProperty_FrequencyResponse
1152 with the mFrequency field filled in. The array is returned with the mMagnitude fields filled in.
1153 If fewer than kNumberOfResponseFrequencies are needed, then the first unused bin should be marked with
1154 a negative frequency.
1155 }
1156 type
1157 AudioUnitFrequencyResponseBin = record
1158 mFrequency: Float64;
1159 mMagnitude: Float64;
1160 end;
1161 AudioUnitFrequencyResponseBinPtr = ^AudioUnitFrequencyResponseBin;
1162
1163 {!
1164 @typedef HostCallback_GetBeatAndTempo
1165 @abstract Retrieve information about the current beat and/or tempo
1166 @discussion
1167 If the host app has set this callback, then the audio unit can use this to get the current
1168 beat and tempo as they relate to the first sample in the render buffer. The audio unit can
1169 call this callback only from within the audio unit render call (otherwise the host is unable
1170 to provide information accurately to the audio unit as the information obtained is relate to
1171 the current AudioUnitRender call). If the host cannot provide the requested information, it
1172 will return kAudioUnitErr_CannotDoInCurrentContext.
1173
1174 The AudioUnit can provide NULL for any of the requested parameters (except for
1175 inHostUserData) if it is not interested in that particular piece of information
1176
1177 @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
1178 @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.
1179 @param outCurrentTempo The current tempo
1180 }
1181 type
inHostUserDatanull1182 HostCallback_GetBeatAndTempo = function( inHostUserData: UnivPtr {__nullable}; outCurrentBeat: Float64Ptr {__nullable}; outCurrentTempo: Float64Ptr {__nullable}): OSStatus;
1183
1184 {!
1185 @typedef HostCallback_GetMusicalTimeLocation
1186 @abstract Retrieve information about the musical time state of the host
1187 @discussion
1188 If the host app has set this callback, then the audio unit can use this to obtain
1189 information about the state of musical time in the host. The audio unit can call this
1190 callback only from within the audio unit render call (otherwise the host is unable to
1191 provide information accurately to the audio unit as the information obtained is relate to
1192 the current AudioUnitRender call). If the host cannot provide the requested information, it
1193 will return kAudioUnitErr_CannotDoInCurrentContext.
1194
1195 The AudioUnit can provide NULL for any of the requested parameters (except for
1196 inHostUserData) if it is not interested in that particular piece of information
1197
1198 @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
1199 @param outDeltaSampleOffsetToNextBeat The number of samples until the next whole beat from the start sample of the current rendering buffer
1200 @param outTimeSig_Numerator The Numerator of the current time signature
1201 @param outTimeSig_Denominator The Denominator of the current time signature (4 is a quarter note, etc)
1202 @param outCurrentMeasureDownBeat The beat that corresponds to the downbeat (first beat) of the current measure that is being rendered
1203
1204 }
1205 type
inHostUserDatanull1206 HostCallback_GetMusicalTimeLocation = function( inHostUserData: UnivPtr {__nullable}; outDeltaSampleOffsetToNextBeat: UInt32Ptr; outTimeSig_Numerator: Float32Ptr; outTimeSig_Denominator: UInt32Ptr; outCurrentMeasureDownBeat: Float64Ptr ): OSStatus;
1207
1208 {!
1209 @typedef HostCallback_GetTransportState
1210 @abstract Retrieve information about the time line's (or transport) state of the host.
1211 @discussion
1212 If the host app has set this callback, then the audio unit can use this to obtain
1213 information about the transport state of the host's time line. The audio unit can call this
1214 callback only from within the audio unit render call (otherwise the host is unable to
1215 provide information accurately to the audio unit as the information obtained is relate to
1216 the current AudioUnitRender call. If the host cannot provide the requested information, it
1217 will return kAudioUnitErr_CannotDoInCurrentContext.
1218
1219 The AudioUnit can provide NULL for any of the requested parameters (except for
1220 inHostUserData) if it is not interested in that particular piece of information
1221
1222 @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
1223 @param outIsPlaying Returns true if the host's transport is currently playing, false if stopped
1224 @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).
1225 @param outCurrentSampleInTimeLine Returns the current sample count in the time line of the host's transport time.
1226 @param outIsCycling Returns true if the host's transport is currently cycling or looping
1227 @param outCycleStartBeat If cycling is true, the start beat of the cycle or loop point in the host's transport
1228 @param outCycleEndBeat If cycling is true, the end beat of the cycle or loop point in the host's transport
1229
1230 }
1231 type
inHostUserDatanull1232 HostCallback_GetTransportState = function( inHostUserData: UnivPtr {__nullable}; outIsPlaying: BooleanPtr; outTransportStateChanged: BooleanPtr; outCurrentSampleInTimeLine: Float64Ptr; outIsCycling: BooleanPtr; outCycleStartBeat: Float64Ptr; outCycleEndBeat: Float64Ptr ): OSStatus;
1233
1234 {!
1235 @typedef HostCallback_GetTransportState2
1236 @abstract Retrieve information about the time line's (or transport) state of the host.
1237 @discussion
1238 If the host app has set this callback, then the audio unit can use this to obtain
1239 information about the transport state of the host's time line. The audio unit can call this
1240 callback only from within the audio unit render call (otherwise the host is unable to
1241 provide information accurately to the audio unit as the information obtained is relate to
1242 the current AudioUnitRender call. If the host cannot provide the requested information, it
1243 will return kAudioUnitErr_CannotDoInCurrentContext.
1244
1245 The AudioUnit can provide NULL for any of the requested parameters (except for
1246 inHostUserData) if it is not interested in that particular piece of information
1247
1248 @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
1249 @param outIsPlaying Returns true if the host's transport is currently playing, false if stopped
1250 @param outIsRecording Returns true if the host is currently record-enabled, otherwise false.
1251 @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).
1252 @param outCurrentSampleInTimeLine Returns the current sample count in the time line of the host's transport time.
1253 @param outIsCycling Returns true if the host's transport is currently cycling or looping
1254 @param outCycleStartBeat If cycling is true, the start beat of the cycle or loop point in the host's transport
1255 @param outCycleEndBeat If cycling is true, the end beat of the cycle or loop point in the host's transport
1256
1257 }
1258 type
inHostUserDatanull1259 HostCallback_GetTransportState2 = function( inHostUserData: UnivPtr {__nullable}; outIsPlaying: BooleanPtr; outIsRecording: BooleanPtr; outTransportStateChanged: BooleanPtr; outCurrentSampleInTimeLine: Float64Ptr; outIsCycling: BooleanPtr; outCycleStartBeat: Float64Ptr; outCycleEndBeat: Float64Ptr ): OSStatus;
1260
1261 {!
1262 @struct HostCallbackInfo
1263 @abstract Contains the various callbacks for an audio unit to call
1264 @discussion
1265 Any callback can be NULL.
1266 }
1267 type
1268 HostCallbackInfo = record
1269 hostUserData: UnivPtr {__nullable};
1270 beatAndTempoProc: HostCallback_GetBeatAndTempo {__nullable};
1271 musicalTimeLocationProc: HostCallback_GetMusicalTimeLocation {__nullable};
1272 transportStateProc: HostCallback_GetTransportState {__nullable};
1273 transportStateProc2: HostCallback_GetTransportState2 {__nullable};
1274 end;
1275 HostCallbackInfoPtr = ^HostCallbackInfo;
1276 {!
1277 @struct AUDependentParameter
1278 @abstract Used to represent a dependent parameter that can change as a result of its parent meta-parameter
1279 changing
1280 }
1281 type
1282 AUDependentParameter = record
1283 mScope: AudioUnitScope;
1284 mParameterID: AudioUnitParameterID;
1285 end;
1286 AUDependentParameterPtr = ^AUDependentParameter;
1287
1288
1289 {!
1290 @struct AudioUnitCocoaViewInfo
1291 @abstract The location and class name of one or more view factory objects an Audio Unit publishes
1292 @field mCocoaAUViewBundleLocation
1293 Contains the location of the bundle which the host app can then use to locate the bundle
1294 @field mCocoaAUViewClass
1295 Contains the names of the classes that implements the required protocol (AUCocoaUIBase). This class is a view factory that creates the NSView object that is the AudioUnit view.
1296 }
1297 type
1298 AudioUnitCocoaViewInfo = record
1299 mCocoaAUViewBundleLocation: CFURLRef;
1300 mCocoaAUViewClass: array[0..0] of CFStringRef;
1301 end;
1302 AudioUnitCocoaViewInfoPtr = ^AudioUnitCocoaViewInfo;
1303
1304 {!
1305 @struct AUHostVersionIdentifier
1306 @abstract Used to describe the name and version of the audio unit's host
1307 }
1308 type
1309 AUHostVersionIdentifier = record
1310 hostName: CFStringRef;
1311 hostVersion: UInt32;
1312 end;
1313 AUHostVersionIdentifierPtr = ^AUHostVersionIdentifier;
1314
1315 {$ifc TARGET_OS_MAC}
1316 {
1317 @typedef AUMIDIOutputCallback
1318 @abstract A callback used by an audio unit to provide MIDI data to a host application
1319 }
1320 type
userDatanull1321 AUMIDIOutputCallback = function( userData: UnivPtr {__nullable}; const (*var*) timeStamp: AudioTimeStamp; midiOutNum: UInt32; {const} pktlist: MIDIPacketListPtr ): OSStatus;
1322
1323 {!
1324 @struct AUMIDIOutputCallbackStruct
1325 @abstract Set by host application to provide the callback and user data for an audio
1326 unit that provides MIDI output
1327 }
1328 type
1329 AUMIDIOutputCallbackStruct = record
1330 midiOutputCallback: AUMIDIOutputCallback;
1331 userData: UnivPtr {__nullable};
1332 end;
1333 AUMIDIOutputCallbackStructPtr = ^AUMIDIOutputCallbackStruct;
1334 {$endc TARGET_OS_MAC}
1335
1336 {!
1337 @struct AUInputSamplesInOutputCallbackStruct
1338 @abstract Used by a host when registering a callback with an audio unit, to provide
1339 input-to-output samples mapping
1340 }
1341 type
1342 AUInputSamplesInOutputCallbackStruct = record
1343 inputToOutputCallback: AUInputSamplesInOutputCallback;
1344 userData: UnivPtr {__nullable};
1345 end;
1346 AUInputSamplesInOutputCallbackStructPtr = ^AUInputSamplesInOutputCallbackStruct;
1347
1348 {!
1349 @struct AudioUnitParameterHistoryInfo
1350 @abstract This structure contains the suggested update rate and history duration for parameters which have the kAudioUnitParameterFlag_PlotHistory flag set.
1351 The structure is filled out by getting kAudioUnitProperty_ParameterHistoryInfo.
1352 @field updatesPerSecond
1353 This is the number of times per second that it is suggested that the host get the value of this parameter.
1354 @field historyDurationInSeconds
1355 This is the duration in seconds of history that should be plotted.
1356 }
1357 type
1358 AudioUnitParameterHistoryInfo = record
1359 updatesPerSecond: Float32;
1360 historyDurationInSeconds: Float32;
1361 end;
1362 AudioUnitParameterHistoryInfoPtr = ^AudioUnitParameterHistoryInfo;
1363
1364 //=====================================================================================================================
1365 //#pragma mark - Parameter Definitions
1366
1367 // assume kAudioUnitParameterUnit_Generic if not found in this enum
1368 {!
1369 @enum AudioUnitParameterUnit
1370 @constant kAudioUnitParameterUnit_Generic
1371 untyped value generally between 0.0 and 1.0
1372 @constant kAudioUnitParameterUnit_Indexed
1373 takes an integer value (good for menu selections)
1374 @constant kAudioUnitParameterUnit_Boolean
1375 0.0 means FALSE, non-zero means TRUE
1376 @constant kAudioUnitParameterUnit_Percent
1377 usually from 0 -> 100, sometimes -50 -> +50
1378 @constant kAudioUnitParameterUnit_Seconds
1379 absolute or relative time
1380 @constant kAudioUnitParameterUnit_SampleFrames
1381 one sample frame equals (1.0/sampleRate) seconds
1382 @constant kAudioUnitParameterUnit_Phase
1383 -180 to 180 degrees
1384 @constant kAudioUnitParameterUnit_Rate
1385 rate multiplier, for playback speed, etc. (e.g. 2.0 == twice as fast)
1386 @constant kAudioUnitParameterUnit_Hertz
1387 absolute frequency/pitch in cycles/second
1388 @constant kAudioUnitParameterUnit_Cents
1389 unit of relative pitch
1390 @constant kAudioUnitParameterUnit_RelativeSemiTones
1391 useful for coarse detuning
1392 @constant kAudioUnitParameterUnit_MIDINoteNumber
1393 absolute pitch as defined in the MIDI spec (exact freq may depend on tuning table)
1394 @constant kAudioUnitParameterUnit_MIDIController
1395 a generic MIDI controller value from 0 -> 127
1396 @constant kAudioUnitParameterUnit_Decibels
1397 logarithmic relative gain
1398 @constant kAudioUnitParameterUnit_LinearGain
1399 linear relative gain
1400 @constant kAudioUnitParameterUnit_Degrees
1401 -180 to 180 degrees, similar to phase but more general (good for 3D coord system)
1402 @constant kAudioUnitParameterUnit_EqualPowerCrossfade
1403 0 -> 100, crossfade mix two sources according to sqrt(x) and sqrt(1.0 - x)
1404 @constant kAudioUnitParameterUnit_MixerFaderCurve1
1405 0.0 -> 1.0, pow(x, 3.0) -> linear gain to simulate a reasonable mixer channel fader response
1406 @constant kAudioUnitParameterUnit_Pan
1407 standard left to right mixer pan
1408 @constant kAudioUnitParameterUnit_Meters
1409 distance measured in meters
1410 @constant kAudioUnitParameterUnit_AbsoluteCents
1411 absolute frequency measurement :
1412 if f is freq in hertz then absoluteCents = 1200 * log2(f / 440) + 6900
1413 @constant kAudioUnitParameterUnit_Octaves
1414 octaves in relative pitch where a value of 1 is equal to 1200 cents
1415 @constant kAudioUnitParameterUnit_BPM
1416 beats per minute, ie tempo
1417 @constant kAudioUnitParameterUnit_Beats
1418 time relative to tempo, i.e., 1.0 at 120 BPM would equal 1/2 a second
1419 @constant kAudioUnitParameterUnit_Milliseconds
1420 parameter is expressed in milliseconds
1421 @constant kAudioUnitParameterUnit_Ratio
1422 for compression, expansion ratio, etc.
1423 @constant kAudioUnitParameterUnit_CustomUnit
1424 this is the parameter unit type for parameters that present a custom unit name
1425 }
1426 type
1427 AudioUnitParameterUnit = UInt32;
1428 AudioUnitParameterUnitPtr = ^AudioUnitParameterUnit;
1429 const
1430 kAudioUnitParameterUnit_Generic = 0;
1431 kAudioUnitParameterUnit_Indexed = 1;
1432 kAudioUnitParameterUnit_Boolean = 2;
1433 kAudioUnitParameterUnit_Percent = 3;
1434 kAudioUnitParameterUnit_Seconds = 4;
1435 kAudioUnitParameterUnit_SampleFrames = 5;
1436 kAudioUnitParameterUnit_Phase = 6;
1437 kAudioUnitParameterUnit_Rate = 7;
1438 kAudioUnitParameterUnit_Hertz = 8;
1439 kAudioUnitParameterUnit_Cents = 9;
1440 kAudioUnitParameterUnit_RelativeSemiTones = 10;
1441 kAudioUnitParameterUnit_MIDINoteNumber = 11;
1442 kAudioUnitParameterUnit_MIDIController = 12;
1443 kAudioUnitParameterUnit_Decibels = 13;
1444 kAudioUnitParameterUnit_LinearGain = 14;
1445 kAudioUnitParameterUnit_Degrees = 15;
1446 kAudioUnitParameterUnit_EqualPowerCrossfade = 16;
1447 kAudioUnitParameterUnit_MixerFaderCurve1 = 17;
1448 kAudioUnitParameterUnit_Pan = 18;
1449 kAudioUnitParameterUnit_Meters = 19;
1450 kAudioUnitParameterUnit_AbsoluteCents = 20;
1451 kAudioUnitParameterUnit_Octaves = 21;
1452 kAudioUnitParameterUnit_BPM = 22;
1453 kAudioUnitParameterUnit_Beats = 23;
1454 kAudioUnitParameterUnit_Milliseconds = 24;
1455 kAudioUnitParameterUnit_Ratio = 25;
1456 kAudioUnitParameterUnit_CustomUnit = 26;
1457 {!
1458 @enum AudioUnitParameterOptions
1459 @discussion Bit positions 18, 17, and 16 are set aside for display scales. Bit 19 is reserved.
1460 @constant kAudioUnitParameterFlag_CFNameRelease
1461 @constant kAudioUnitParameterFlag_PlotHistory
1462 @constant kAudioUnitParameterFlag_MeterReadOnly
1463 @constant kAudioUnitParameterFlag_DisplayMask
1464 @constant kAudioUnitParameterFlag_DisplaySquareRoot
1465 @constant kAudioUnitParameterFlag_DisplaySquared
1466 @constant kAudioUnitParameterFlag_DisplayCubed
1467 @constant kAudioUnitParameterFlag_DisplayCubeRoot
1468 @constant kAudioUnitParameterFlag_DisplayExponential
1469 @constant kAudioUnitParameterFlag_HasClump
1470 @constant kAudioUnitParameterFlag_ValuesHaveStrings
1471 @constant kAudioUnitParameterFlag_DisplayLogarithmic
1472 @constant kAudioUnitParameterFlag_IsHighResolution
1473 @constant kAudioUnitParameterFlag_NonRealTime
1474 @constant kAudioUnitParameterFlag_CanRamp
1475 @constant kAudioUnitParameterFlag_ExpertMode
1476 @constant kAudioUnitParameterFlag_HasCFNameString
1477 @constant kAudioUnitParameterFlag_IsGlobalMeta
1478 @constant kAudioUnitParameterFlag_IsElementMeta
1479 @constant kAudioUnitParameterFlag_IsReadable
1480 @constant kAudioUnitParameterFlag_IsWritable
1481 }
1482 type
1483 AudioUnitParameterOptions = UInt32;
1484 AudioUnitParameterOptionsPtr = ^AudioUnitParameterOptions;
1485 const
1486 kAudioUnitParameterFlag_CFNameRelease = 1 shl 4;
1487 kAudioUnitParameterFlag_OmitFromPresets = 1 shl 13;
1488 kAudioUnitParameterFlag_PlotHistory = 1 shl 14;
1489 kAudioUnitParameterFlag_MeterReadOnly = 1 shl 15;
1490
1491 // bit positions 18,17,16 are set aside for display scales. bit 19 is reserved.
1492 kAudioUnitParameterFlag_DisplayMask = (7 shl 16) or (1 shl 22);
1493 kAudioUnitParameterFlag_DisplaySquareRoot = 1 shl 16;
1494 kAudioUnitParameterFlag_DisplaySquared = 2 shl 16;
1495 kAudioUnitParameterFlag_DisplayCubed = 3 shl 16;
1496 kAudioUnitParameterFlag_DisplayCubeRoot = 4 shl 16;
1497 kAudioUnitParameterFlag_DisplayExponential = 5 shl 16;
1498 kAudioUnitParameterFlag_HasClump = 1 shl 20;
1499 kAudioUnitParameterFlag_ValuesHaveStrings = 1 shl 21;
1500 kAudioUnitParameterFlag_DisplayLogarithmic = 1 shl 22;
1501 kAudioUnitParameterFlag_IsHighResolution = 1 shl 23;
1502 kAudioUnitParameterFlag_NonRealTime = 1 shl 24;
1503 kAudioUnitParameterFlag_CanRamp = 1 shl 25;
1504 kAudioUnitParameterFlag_ExpertMode = 1 shl 26;
1505 kAudioUnitParameterFlag_HasCFNameString = 1 shl 27;
1506 kAudioUnitParameterFlag_IsGlobalMeta = 1 shl 28;
1507 kAudioUnitParameterFlag_IsElementMeta = 1 shl 29;
1508 kAudioUnitParameterFlag_IsReadable = 1 shl 30;
1509 kAudioUnitParameterFlag_IsWritable = 1 shl 31;
1510
1511 {!
1512 @struct AudioUnitParameterInfo
1513 @field name
1514 UNUSED - set to zero - UTF8 encoded C string (originally).
1515 @field unitName
1516 only valid if kAudioUnitParameterUnit_CustomUnit is set. If kAudioUnitParameterUnit_CustomUnit
1517 is set, this field must contain a valid CFString.
1518 @field clumpID
1519 only valid if kAudioUnitParameterFlag_HasClump
1520 @field cfNameString
1521 only valid if kAudioUnitParameterFlag_HasCFNameString
1522 @field unit
1523 if the "unit" field contains a value not in the enum above, then assume
1524 kAudioUnitParameterUnit_Generic
1525 @field minValue
1526 @field maxValue
1527 @field defaultValue
1528 @field flags
1529 Due to some vagaries about the ways in which Parameter's CFNames have been described, it was
1530 necessary to add a flag: kAudioUnitParameterFlag_CFNameRelease
1531 In normal usage a parameter name is essentially a static object, but sometimes an audio unit will
1532 generate parameter names dynamically.. As these are expected to be CFStrings, in that case
1533 the host should release those names when it is finished with them, but there was no way
1534 to communicate this distinction in behavior.
1535 Thus, if an audio unit will (or could) generate a name dynamically, it should set this flag in
1536 the parameter's info. The host should check for this flag, and if present, release the parameter
1537 name when it is finished with it.
1538 }
1539 type
1540 AudioUnitParameterInfo = record
1541 name : packed array [0..51] of char;
1542 unitName: CFStringRef {__nullable};
1543 clumpID: UInt32;
1544 cfNameString: CFStringRef {__nullable};
1545 unt: AudioUnitParameterUnit;
1546 minValue: AudioUnitParameterValue;
1547 maxValue: AudioUnitParameterValue;
1548 defaultValue: AudioUnitParameterValue;
1549 flags: AudioUnitParameterOptions;
1550 end;
1551 AudioUnitParameterInfoPtr = ^AudioUnitParameterInfo;
1552
1553 {!
1554 @enum Audio Unit Clump ID
1555 @discussion Audio unit developers should not use a clump ID of 0. This value is reserved for system use.
1556 }
1557 const
1558 kAudioUnitClumpID_System = 0;
GetAudioUnitParameterDisplayTypenull1559 function GetAudioUnitParameterDisplayType(flags : UInt32) : UInt32; inline;
AudioUnitDisplayTypeIsLogarithmicnull1560 function AudioUnitDisplayTypeIsLogarithmic(flags : UInt32) : Boolean; inline;
AudioUnitDisplayTypeIsSquareRootnull1561 function AudioUnitDisplayTypeIsSquareRoot(flags : UInt32) : Boolean; inline;
AudioUnitDisplayTypeIsSquarednull1562 function AudioUnitDisplayTypeIsSquared(flags : UInt32) : Boolean; inline;
AudioUnitDisplayTypeIsCubednull1563 function AudioUnitDisplayTypeIsCubed(flags : UInt32) : Boolean; inline;
AudioUnitDisplayTypeIsCubeRootnull1564 function AudioUnitDisplayTypeIsCubeRoot(flags : UInt32) : Boolean; inline;
AudioUnitDisplayTypeIsExponentialnull1565 function AudioUnitDisplayTypeIsExponential(flags : UInt32) : Boolean; inline;
1566 procedure SetAudioUnitParameterDisplayType(var flags : UInt32; displayType : UInt32); inline;
1567
1568
1569 {
1570 The following properties are used with display names
1571 }
1572
1573 {!
1574 @enum Audio Unit Parameter Full Name
1575 @discussion Used with the AudioUnitParameterIDName.inDesiredLength field to indicate the full name
1576 of the requested parameter.
1577 }
1578 const
1579 kAudioUnitParameterName_Full = -1;
1580
1581 {!
1582 @struct AudioUnitParameterIDName
1583 @abstract Used to provide shorter names for a specified parameter
1584 }
1585 type
1586 AudioUnitParameterNameInfo = record
1587 inID: AudioUnitParameterID;
1588 inDesiredLength: SInt32;
1589 outName: CFStringRef {__nullable};
1590 end;
1591 AudioUnitParameterNameInfoPtr = ^AudioUnitParameterNameInfo;
1592
1593 {!
1594 @struct AudioUnitParameterStringFromValue
1595 @abstract Provide a string representation of a parameter's value
1596 }
1597 type
1598 AudioUnitParameterStringFromValue = record
1599 inParamID: AudioUnitParameterID;
1600 inValue: { const } AudioUnitParameterValuePtr;
1601 outString: CFStringRef {__nullable};
1602 end;
1603 AudioUnitParameterStringFromValuePtr = ^AudioUnitParameterStringFromValue;
1604
1605 {!
1606 @struct AudioUnitParameterValueFromString
1607 @abstract Provide the parameter's value for a given string representation of it
1608 }
1609 type
1610 AudioUnitParameterValueFromString = record
1611 inParamID: AudioUnitParameterID;
1612 inString: CFStringRef;
1613 outValue: AudioUnitParameterValue;
1614 end;
1615 AudioUnitParameterValueFromStringPtr = ^AudioUnitParameterValueFromString;
1616
1617
1618 //=====================================================================================================================
1619 //#pragma mark - Configuration Info Keys
1620
1621 // These strings are used as keys to the dictionary of configuration info returned by
1622 // AudioComponentGetConfigurationInfo(). Information about them is presented inline with the
1623 // declaration.
1624
1625 {!
1626 @define kAudioUnitConfigurationInfo_HasCustomView
1627 @discussion This is a boolean value that indicates whether or not the AU has a custom view
1628 }
1629 const
1630 kAudioUnitConfigurationInfo_HasCustomView = 'HasCustomView';
1631
1632 {!
1633 @define kAudioUnitConfigurationInfo_ChannelConfigurations
1634 @discussion This is an array of pairs of values where each item in the array is an array of two
1635 numbers and is the equivalent of an AUChannelInfo. If the AudioUnit is an effect and
1636 it doesn't implement kAudioUnitProperty_SupportedNumChannels, the array will contain
1637 only the single entry, ( -1, -1). If the AudioUnit is an instrument or a generator
1638 and doesn't implement kAudioUnitProperty_SupportedNumChannels, the array will be
1639 empty and means that the AU's initial state is all that is supported.
1640 }
1641 const
1642 kAudioUnitConfigurationInfo_ChannelConfigurations = 'ChannelConfigurations';
1643
1644 {!
1645 @define kAudioUnitConfigurationInfo_InitialInputs
1646 @discussion An array of numbers whose size is equal to the number of input buses posessed by the
1647 AU. Each number in the array represents the number of channels for the corresponding
1648 bus.
1649 }
1650 const
1651 kAudioUnitConfigurationInfo_InitialInputs = 'InitialInputs';
1652
1653 {!
1654 @define kAudioUnitConfigurationInfo_InitialOutputs
1655 @discussion An array of numbers whose size is equal to the number of output buses posessed by
1656 the AU. Each number in the array represents the number of channels for the
1657 corresponding bus.
1658 }
1659 const
1660 kAudioUnitConfigurationInfo_InitialOutputs = 'InitialOutputs';
1661
1662 {!
1663 @define kAudioUnitConfigurationInfo_IconURL
1664 @discussion A CFURLRef value that indicates the location of an icon of the audio unit.
1665 }
1666 const
1667 kAudioUnitConfigurationInfo_IconURL = 'IconURL';
1668
1669 {!
1670 @define kAudioUnitConfigurationInfo_BusCountWritable
1671 @discussion An array of booleans whose size is three representing Global, Input and Output scope
1672 in the order it is defined in CoreAudioTypes.h. Each value represents whether the bus
1673 count is writable for the specified scope.
1674 }
1675 const
1676 kAudioUnitConfigurationInfo_BusCountWritable = 'BusCountWritable';
1677
1678 {!
1679 @define kAudioUnitConfigurationInfo_SupportedChannelLayoutTags
1680 @discussion A dictionary that contains two arrays one for input scope and output scope. Each array
1681 of numbers whose size is equal to number of supported channel layout tags supported for the scope
1682 by the AU. Each number in the array represents the channel layout tag.
1683 }
1684
1685 const
1686 kAudioUnitConfigurationInfo_SupportedChannelLayoutTags = 'SupportedChannelLayoutTags';
1687
1688 //=====================================================================================================================
1689 //#pragma mark - Output Unit
1690 {!
1691 @enum Output Unit Properties
1692 @abstract The collection of properties for output units
1693 @constant kAudioOutputUnitProperty_IsRunning
1694 @discussion Scope:
1695 Value Type:
1696 Access:
1697 }
1698 const
1699 // range (2000 -> 2999)
1700 kAudioOutputUnitProperty_IsRunning = 2001;
1701
1702 //#pragma mark -
1703 //#pragma mark OS X Availability
1704
1705 {$ifc TARGET_OS_MAC}
1706
1707 //=====================================================================================================================
1708 //#pragma mark - Music Effects and Instruments
1709 {!
1710 @enum Music Effect and Instrument Unit (MusicDevice) Properties
1711 @abstract The collection of Music Effects and Instrument Unit Property IDs
1712 @discussion
1713 These properties are used to:
1714 Describe a current set of mappings between MIDI messages and Parameter value setting
1715 Create a mapping between a parameter and a MIDI message through either:
1716 - explicitly adding (or removing) the mapping
1717 - telling the audio unit to hot-map the next MIDI message to a specified Parameter
1718 The same MIDI Message can map to one or more parameters
1719
1720 These properties normally apply only to the two types of audio units that implement
1721 the MIDI API, instrument units ('aumu') and music effects ('aumf').
1722
1723 These properties are used in the Global scope. The scope and element members of the structure describe
1724 the scope and element of the parameter. In all usages, mScope, mElement and mParameterID must be
1725 correctly specified.
1726
1727
1728 * The AUParameterMIDIMapping Structure
1729
1730 Command mStatus mData1
1731 Note Off 0x8n Note Num
1732 Note On 0x9n Note Num
1733 Key Pressure 0xAn Note Num
1734 Control Change 0xBn ControllerID
1735 Patch Change 0xCn Patch Num
1736 Channel Pressure DxDn 0 (Unused)
1737 Pitch Bend 0xEn 0 (Unused)
1738
1739 (where n is 0-0xF to correspond to MIDI channels 1-16)
1740
1741 Details:
1742
1743 In general MIDI Commands can be mapped to either a specific channel as specified in the mStatus bit.
1744 If the kAUParameterMIDIMapping_AnyChannelFlag bit is set mStatus is a MIDI channel message, then the
1745 MIDI channel number in the status byte is ignored; the mapping is from the specified MIDI message on ANY channel.
1746
1747 For note commands (note on, note off, key pressure), the MIDI message can trigger either with just a specific
1748 note number, or any note number if the kAUParameterMIDIMapping_AnyNoteFlag bit is set. In these instances, the
1749 note number is used as the trigger value (for instance, a note message could be used to set the
1750 cut off frequency of a filter).
1751
1752 When the parameter mapping list changes through addition/replace, removal, the implementation should
1753 fire a notification on the kAudioUnitProperty_AllParameterMIDIMappings property. The host can then
1754 retrieve the full set of mappings for the audio unit.
1755
1756 When a hot mapping is made, the notification should just be delivered for the HotMap property. The host can
1757 retrieve the last current hot mapping made through getting the value of that property.
1758
1759 @constant kAudioUnitProperty_AllParameterMIDIMappings
1760 @discussion Scope: any
1761 Value Type: array of AUParameterMIDIMapping
1762 Access: read/write
1763
1764 This property allows setting and retrieving the current mapping state between
1765 (some/many/all of) an audio unit's parameters and MIDI messages. When set, it should replace
1766 any previous mapped settings the audio unit had.
1767
1768 If this property is implemented by a non-MIDI capable audio unit (such as an 'aufx' type),
1769 then the property is read only and should recommend a suggested set of mappings for the host
1770 to perform. In this case, it is the host's responsibility to map MIDI message to the audio
1771 unit parameters.
1772
1773 This property's size varies depending on the number of mappings currently in effect. A host
1774 application should always get the size of this property before retrieving it. The audio
1775 unit should return an error if the host doesn't provide enough space to return all of the
1776 current mappings.
1777
1778 @constant kAudioUnitProperty_AddParameterMIDIMapping
1779 @discussion Scope: any
1780 Value Type: array of AUParameterMIDIMapping
1781 Access: write
1782
1783 Use this property to add parameter-to-MIDI mappings to an audio unit's existing set of
1784 mappings. There can be only one mapping per parameter. When you set a mapping for a parameter,
1785 it replaces the previous mapping.
1786
1787 @constant kAudioUnitProperty_RemoveParameterMIDIMapping
1788 @discussion Scope: any
1789 Value Type: array of AUParameterMIDIMapping
1790 Access: write
1791
1792 Use this property to remove mappings from an audio unit. If a mapping is specified that
1793 does not currently exist in an audio unit, then the audio unit should ignore the request.
1794 The Scope/Element/ParameterID is used to find the mapping to remove.
1795
1796 @constant kAudioUnitProperty_HotMapParameterMIDIMapping
1797 @discussion Scope: any
1798 Value Type: AUParameterMIDIMapping
1799 Access: read/write
1800
1801 This property can be used in two ways, determined by the value supplied by the host
1802 application.
1803
1804 (1) If a mapping structure is provided, then that structure provides all the information
1805 that the audio unit should use to map the parameter, except for the MIDI message. The audio
1806 unit should then listen for the next MIDI message and associate that MIDI message with the
1807 supplied parameter mapping. When this MIDI message is received and the mapping made, the
1808 audio unit should also issue a notification on this property to indicate to the host that
1809 the mapping has been made. The host can then retrieve the mapping that was made by getting the
1810 value of this property.
1811
1812 To avoid possible confusion, it is recommended that once the host has retrieved this mapping
1813 (if it is presenting a user interface to describe the mappings, for example), that the host
1814 should then clear the mapping state, as described in (2).
1815
1816 The only time this property will return a valid value is when an audio unit has implemented the
1817 requested mapping. If the audio unit's mapping state has been cleared (or if it has not been
1818 asked to make a mapping), then the audio unit should return a kAudioUnitErr_InvalidPropertyValue
1819 error when the host tries to read this property's value.
1820
1821 (2) If the value passed in this property is NULL, and if the audio unit had a parameter that
1822 it was in the process of mapping, the audio unit should disregard the parameter mapping request
1823 and discard the partially mapped structure. If the value is NULL and the audio unit is not in
1824 the process of mapping, the audio unit can just ignore the request.
1825
1826 At all times, the _AllMappings property will completely describe the current known state of an
1827 audio unit's mappings of MIDI messages to parameters.
1828 }
1829 const
1830 kAudioUnitProperty_AllParameterMIDIMappings = 41;
1831 kAudioUnitProperty_AddParameterMIDIMapping = 42;
1832 kAudioUnitProperty_RemoveParameterMIDIMapping = 43;
1833 kAudioUnitProperty_HotMapParameterMIDIMapping = 44;
1834
1835 {!
1836 @enum ParameterMIDIMappings
1837 @abstract General defined values to customize the behavior of parameter-to-MIDI mappings
1838
1839 @constant kAUParameterMIDIMapping_AnyChannelFlag
1840 @discussion If this flag is set and the value of the mStatus field is a MIDI channel message, then
1841 the MIDI channel number in the status byte is ignored; the mapping is from the specified
1842 MIDI message on any channel.
1843
1844 @constant kAUParameterMIDIMapping_AnyNoteFlag
1845 @discussion If this flag is set and the value of the mStatus field is a Note On, Note Off, or
1846 Polyphonic Pressure message, the message's note number is ignored. The mapping is from
1847 any note number.
1848
1849 @constant kAUParameterMIDIMapping_SubRange
1850 @discussion Set this flag if the MIDI control should map only to a sub-range of the parameter's value.
1851 Then specify that range in the mSubRangeMin and mSubRangeMax member fields.
1852
1853 @constant kAUParameterMIDIMapping_Toggle
1854 @discussion Intended for Boolean typed parameters. When this property is set, it means that the
1855 parameter's value should be toggled when the mapped MIDI message is received. For example,
1856 if the parameter's value is currently TRUE, when the mapped MIDI message is received
1857 the value changes to FALSE.
1858
1859 @constant kAUParameterMIDIMapping_Bipolar
1860 @discussion This property is useful when mapping a parameter to a MIDI Controller. When set, it
1861 indicates that the parameter can assume only two values: on or off. For this reason, a
1862 parameter associated with this property is typically Boolean. For example, if this
1863 property is set for a parameter mapped to a sustain pedal MIDI controller, controller
1864 values from 0 to 64 result in the parameter switched to its "off" state; controller
1865 values from 65 to 127 result in the parameter switched to its "on" state.
1866
1867 This property works in connection with the kAUParameterMIDIMapping_Bipolar_On property.
1868 The value of the kAUParameterMIDIMapping_Bipolar_On property
1869
1870 @constant kAUParameterMIDIMapping_Bipolar_On
1871 @discussion Determines whether the "on" state of a parameter is mapped to the "on" or "off" state
1872 of the associated MIDI controller. Only valid if the kAUParameterMIDIMapping_Bipolar
1873 property is set.
1874 }
1875 type
1876 AUParameterMIDIMappingFlags = UInt32;
1877 AUParameterMIDIMappingFlagsPtr = ^AUParameterMIDIMappingFlags;
1878 const
1879 kAUParameterMIDIMapping_AnyChannelFlag = 1 shl 0;
1880 kAUParameterMIDIMapping_AnyNoteFlag = 1 shl 1;
1881 kAUParameterMIDIMapping_SubRange = 1 shl 2;
1882 kAUParameterMIDIMapping_Toggle = 1 shl 3;
1883 kAUParameterMIDIMapping_Bipolar = 1 shl 4;
1884 kAUParameterMIDIMapping_Bipolar_On = 1 shl 5;
1885
1886 {!
1887 @struct AUParameterMIDIMapping
1888 @abstract Represents a mapping between a MIDI message and an audio unit's parameter.
1889 @discussion The reserved fields in this structure are for future use. In the current implementation,
1890 they help align the structure to 64 bit size. Do not use the names of these fields in a
1891 host application. They are subject to change.
1892 }
1893 type
1894 AUParameterMIDIMapping = record
1895 mScope: AudioUnitScope;
1896 mElement: AudioUnitElement;
1897 mParameterID: AudioUnitParameterID;
1898 mFlags: AUParameterMIDIMappingFlags;
1899 mSubRangeMin: AudioUnitParameterValue;
1900 mSubRangeMax: AudioUnitParameterValue;
1901 mStatus: UInt8;
1902 mData1: UInt8;
1903 reserved1: UInt8; // MUST be set to zero
1904 reserved2: UInt8; // MUST be set to zero
1905 reserved3: UInt32; // MUST be set to zero
1906 end;
1907 AUParameterMIDIMappingPtr = ^AUParameterMIDIMapping;
1908
1909 //=====================================================================================================================
1910 //#pragma mark - Music Device
1911 {!
1912 @enum Instrument Unit (MusicDevice) Properties
1913 @abstract The collection of Instrument Unit Property IDs
1914
1915 @constant kMusicDeviceProperty_MIDIXMLNames
1916 @discussion Scope:
1917 Value Type:
1918 Access:
1919
1920 @constant kMusicDeviceProperty_PartGroup
1921 @discussion Scope: Part
1922 Value Type: AudioUnitElement
1923 Access: read/write
1924
1925 This property's value specifies the group ID (the Group scope's element)
1926 that the part is (or should be) assigned to. The property is used in the Part scope,
1927 where the element ID is the part that is being queried (or assigned).
1928
1929 This property may be implemented in an audio unit as read only, as writeable only if the
1930 audio unit is uninitialized, or as read/write. Apple recommends that it should be
1931 writable at any time.
1932
1933 The effect of assigning a new group to a part is undefined. Typically, however, it can be
1934 expected that all existing notes would be turned off before the re-assignment is made by
1935 the audio unit.
1936
1937 @constant kMusicDeviceProperty_DualSchedulingMode
1938 @discussion Scope: Global
1939 Value Type: UInt32
1940 Access: write
1941
1942 Some instrument units need to distinguish realtime note and control events (such as from
1943 incoming MIDI) from sequenced or pre-scheduled events. To support this, a host application
1944 may set this property to 1. If the instrument unit returns a value of noErr, it supports
1945 an alternate interpretation of the inOffsetSampleFrame parameter for the following
1946 functions:
1947
1948 MusicDeviceMIDIEvent
1949 MusicDeviceStartNote
1950 MusicDeviceStopNote
1951 AudioUnitSetParameter
1952
1953 Once the host sets this property to 1 and the instrument unit returns noErr, the
1954 inOffsetSampleFrame field becomes a bitfield:
1955
1956 kMusicDeviceSampleFrameMask_SampleOffset = 0xFFFFFF // AND with this to obtain sample offset
1957 kMusicDeviceSampleFrameMask_IsScheduled = 0x01000000
1958
1959 The IsScheduled bit should be set on events which are being scheduled ahead of time from
1960 a prerecorded track. The IsScheduled bit should be clear on events which are being sent
1961 to the instrument unit in response to realtime events, such as incoming MIDI or control
1962 changes in a view.
1963
1964 @constant kMusicDeviceProperty_SupportsStartStopNote
1965 @discussion Scope: Global
1966 Value Type: UInt32
1967 Access: read
1968
1969 The MusicDeviceStartNote and MusicDeviceStopNote APIs have been available since Mac OS X v10.0.
1970 However, many third-party audio units do not implement these calls. This property can
1971 be used to determine if an audio unit does provide a compliant implementation. A compliant
1972 audio unit will both implement the property and return !0 as the value for the property.
1973 Apple's DLSMusicDevice unit has implemented MusicDeviceStartNote and MusicDeviceStopNote
1974 since Mac OS X v10.0. The kMusicDeviceProperty_SupportsStartStopNote property was introduced
1975 with Mac OS X v10.5, so the DLSMusicDevice unit will not return an appropriate value for
1976 this property on a pre-10.5 system.
1977
1978 }
1979 const
1980 // range (1000 -> 1999)
1981 kMusicDeviceProperty_MIDIXMLNames = 1006;
1982 kMusicDeviceProperty_PartGroup = 1010;
1983 kMusicDeviceProperty_DualSchedulingMode = 1013;
1984 kMusicDeviceProperty_SupportsStartStopNote = 1014;
1985
1986 {!
1987 @enum DualSchedulingMode
1988 }
1989 const
1990 kMusicDeviceSampleFrameMask_SampleOffset = $FFFFFF; // AND with this to obtain the sample offset
1991 kMusicDeviceSampleFrameMask_IsScheduled = $01000000;
1992
1993
1994 //=====================================================================================================================
1995 //#pragma mark - Offline Unit
1996 {!
1997 @enum Offline Unit Properties
1998 @abstract The collection of properties for offline units
1999 @constant kAudioUnitOfflineProperty_InputSize
2000 @discussion Scope: Global
2001 Value Type: UInt64
2002 Access: read/write
2003
2004 Once this property is set, an audio unit will assume that its input samples
2005 have been reset to a new region. Setting this property will also cause the
2006 audio unit's internal DSP state to be reset. That is, the audio unit calls
2007 the AudioUnitReset function on itself.
2008
2009 This property tells the offline unit how many samples to process. Once it
2010 knows this number it will then request from 0 to (nSamples-1) in its input
2011 callback. The host of the audio unit is then required to provide the samples
2012 specified in the sample count field of that Input's callback.
2013
2014 @constant kAudioUnitOfflineProperty_OutputSize
2015 @discussion Scope: Global
2016 Value Type: UInt64
2017 Access: read
2018
2019 The host can use this property to estimate how many output samples an audio
2020 unit will produce for the specified input samples. The property value
2021 is invalid if InputSize is not set.
2022
2023 The host cannot assume that the value returned is exact.
2024 It is a guide only, so is suitable for use in a progress bar, for instance.
2025
2026 Termination of processing is solely determined by the setting of the
2027 kAudioUnitStatus_OfflineRenderComplete property in the
2028 ioRenderActionFlags from the AudioUnitRender function.
2029
2030 @constant kAudioUnitOfflineProperty_StartOffset
2031 @discussion Scope: Global
2032 Value Type: UInt64
2033 Access: read/write
2034
2035 The host sets this property to tell an audio unit that the start offset of
2036 the data it is processing has been changed. This should be set along with
2037 the InputSize property, so that the unit knows its input data has been set
2038 or changed.
2039
2040 @constant kAudioUnitOfflineProperty_PreflightRequirements
2041 @discussion Scope: Global
2042 Value Type: UInt32
2043 Access: read
2044
2045 Returns one of the kOfflinePreflight_ results (see the Offline Preflight
2046 enumeration).
2047
2048 @constant kAudioUnitOfflineProperty_PreflightName
2049 @discussion Scope: Global
2050 Value Type: CFStringRef
2051 Access: read
2052
2053 For an audio unit that allows or requires preflighting, this property lets
2054 the unit give its host application a name to describe the preflight
2055 operations.
2056 }
2057 const
2058 // range (3020->3040)
2059 kAudioUnitOfflineProperty_InputSize = 3020;
2060 kAudioUnitOfflineProperty_OutputSize = 3021;
2061 kAudioUnitOfflineProperty_StartOffset = 3022;
2062 kAudioUnitOfflineProperty_PreflightRequirements = 3023;
2063 kAudioUnitOfflineProperty_PreflightName = 3024;
2064
2065 {!
2066 @enum Offline Preflight Flags
2067 @abstract Used to indicate an Offline Unit's preflight requirements
2068 @constant kOfflinePreflight_NotRequired
2069 @discussion Offline unit does not require preflight
2070 @constant kOfflinePreflight_Optional
2071 @discussion Offline unit will generally behave better if it is preflighted, but it is not
2072 required to be preflighted.
2073 @constant kOfflinePreflight_Required
2074 @discussion Offline unit requires preflighting or it cannot do its work
2075
2076 }
2077 const
2078 kOfflinePreflight_NotRequired = 0;
2079 kOfflinePreflight_Optional = 1;
2080 kOfflinePreflight_Required = 2;
2081
2082 //=====================================================================================================================
2083 //#pragma mark - Panner Unit
2084 {!
2085 @enum Panner Unit Properties
2086 @abstract The collection of properties for panner units
2087 @constant kAudioUnitProperty_DistanceAttenuationData
2088 @discussion This property is deprecated.
2089 Scope: Global
2090 Value Type: AUDistanceAttenuationData
2091 Access: Read
2092 }
2093 const
2094 // range (3060->3999)
2095 kAudioUnitProperty_DistanceAttenuationData = 3600;
2096 (* API_DEPRECATED("no longer supported", macos(10.5, 10.11)) API_UNAVAILABLE(ios, watchos, tvos) *)
2097
2098
2099 {!
2100 @struct AUDistanceAttenuationData
2101 }
2102 type
2103 AUDistanceAttenuationDataPairsRec = record
2104 inDistance: Float32; // 0-1000
2105 outGain: Float32; // 0-1
2106 end;
2107 AUDistanceAttenuationDataPairsRecPtr = ^AUDistanceAttenuationDataPairsRec;
2108
2109 AUDistanceAttenuationData = record
2110 inNumberOfPairs: UInt32;
2111 pairs: array[0..0] of AUDistanceAttenuationDataPairsRec; // this is a variable length array of inNumberOfPairs elements
2112 end;
2113 AUDistanceAttenuationDataPtr = ^AUDistanceAttenuationData;
2114 (* API_DEPRECATED("no longer supported", macos(10.5, 10.11)) API_UNAVAILABLE(ios, watchos, tvos); *)
2115
2116 //=====================================================================================================================
2117 //#pragma mark - Translation Service
2118 {!
2119 @enum Translation Properties
2120 @abstract The collection of properties for migrating data from other audio plug-ins to the
2121 Audio Unit architecture
2122 @discussion While this is a general service, there are two formats that are explicitly defined:
2123 MAS and VST. An audio unit may have MAS settings given to it in one of two ways:
2124
2125 (1) The settings may have a single setting. This may be set multiple times with
2126 different settings each time. In this case, numberOfSettings will be 1.
2127
2128 (2) The settings may be set in one hit, providing all SettingData at once.
2129 In this case, numberOfSettings may be more than 1, and will be the number of
2130 settings the host has from the MAS plugin.
2131
2132 AU-VST - the CFDataRef data contains VST chunk data with no additional information.
2133
2134 In addition, this can be used to migrate settings from an older audio unit; this allows manufacturers
2135 to deprecate older audio units and replace them with new ones. The data for the older audio unit is
2136 the audio unit preset CFDictionary that that unit generated.
2137
2138 @constant kAudioUnitMigrateProperty_FromPlugin
2139 @discussion Scope:
2140 Value Type:
2141 Access:
2142
2143 @constant kAudioUnitMigrateProperty_OldAutomation
2144 @discussion Scope:
2145 Value Type:
2146 Access:
2147 }
2148 const
2149 // range (4000->4020)
2150 kAudioUnitMigrateProperty_FromPlugin = 4000;
2151 kAudioUnitMigrateProperty_OldAutomation = 4001;
2152
2153 {!
2154 @enum Other Plug-in Formats
2155 }
2156 const
2157 kOtherPluginFormat_Undefined = 0; //reserving this value for future use
2158 kOtherPluginFormat_kMAS = 1;
2159 kOtherPluginFormat_kVST = 2;
2160 kOtherPluginFormat_AU = 3;
2161
2162 {!
2163 @struct AudioUnitOtherPluginDesc
2164 @discussion
2165
2166 @field format
2167 @discussion One of the OtherPluginFormat values
2168
2169 @field plugin
2170 @discussion struct AudioClassDescription (
2171 OSType mType;
2172 OSType mSubType;
2173 OSType mManufacturer;
2174 );
2175 is defined in <CoreAudio/CoreAudioTypes.h>
2176
2177 mType specifies a generic, plug-in format defined descriptor
2178 mSubType is usually left to the manufacturer to use at their discretion
2179 mManufacturer is a registered code to identify all plugins from the same manufacturer
2180
2181 }
2182 type
2183 AudioUnitOtherPluginDesc = record
2184 format: UInt32;
2185 plugin: AudioClassDescription;
2186 end;
2187 AudioUnitOtherPluginDescPtr = ^AudioUnitOtherPluginDesc;
2188
2189 {!
2190 @struct AudioUnitParameterValueTranslation
2191 @abstract Used to translate another plug-in's parameter values to audio unit parameter
2192 values
2193 }
2194 type
2195 AudioUnitParameterValueTranslation = record
2196 otherDesc: AudioUnitOtherPluginDesc;
2197 otherParamID: UInt32;
2198 otherValue: Float32;
2199 auParamID: AudioUnitParameterID;
2200 auValue: AudioUnitParameterValue;
2201 end;
2202 AudioUnitParameterValueTranslationPtr = ^AudioUnitParameterValueTranslation;
2203
2204 {!
2205 @struct AudioUnitPresetMAS_SettingData
2206 @discussion AU-MAS specific structs for the data contained in the "masdata" key of an audio
2207 unit preset dictionary
2208 }
2209 type
2210 AudioUnitPresetMAS_SettingData = record
2211 isStockSetting: UInt32; // zero or 1 i.e., "long bool"
2212 settingID: UInt32;
2213 dataLen: UInt32; //length of following data
2214 data: array[0..0] of UInt8;
2215 end;
2216 AudioUnitPresetMAS_SettingDataPtr = ^AudioUnitPresetMAS_SettingData;
2217
2218 {!
2219 @struct AudioUnitPresetMAS_Settings
2220 @discussion See MAS documentation
2221 }
2222 type
2223 AudioUnitPresetMAS_Settings = record
2224 manufacturerID: UInt32;
2225 effectID: UInt32;
2226 variantID: UInt32;
2227 settingsVersion: UInt32;
2228 numberOfSettings: UInt32;
2229 settings: array[0..0] of AudioUnitPresetMAS_SettingData;
2230 end;
2231
2232 {$endc} { TARGET_OS_MAC }
2233
2234 //=====================================================================================================================
2235 //#pragma mark -
2236 //#pragma mark Apple Specific Properties
2237
2238 //=====================================================================================================================
2239 //#pragma mark - AUConverter
2240 {!
2241 @enum Apple AUConverter Property IDs
2242 @abstract The collection of property IDs for Apple AUConverter
2243
2244 @constant kAudioUnitProperty_SampleRateConverterComplexity
2245 @discussion Scope: Global
2246 Value Type: UInt32
2247 Access: read/write
2248 }
2249 const
2250 kAudioUnitProperty_SampleRateConverterComplexity = 3014;
2251
2252 {!
2253 @enum Audio Unit Sample Rate Converter Complexity
2254 @discussion The lowest quality of the Mastering algorithm is higher than the highest quality of the Normal algorithm.
2255 @constant kAudioUnitSampleRateConverterComplexity_Normal
2256 @discussion Normal quality sample rate conversion.
2257 @constant kAudioUnitSampleRateConverterComplexity_Mastering
2258 @discussion Mastering quality sample rate conversion. More expensive.
2259 }
2260 const
2261 kAudioUnitSampleRateConverterComplexity_Linear = FourCharCode('line'); // linear interpolation
2262 kAudioUnitSampleRateConverterComplexity_Normal = FourCharCode('norm'); // the default
2263 kAudioUnitSampleRateConverterComplexity_Mastering = FourCharCode('bats'); // higher quality, more expensive
2264
2265 //=====================================================================================================================
2266 //#pragma mark - AUHAL and device units
2267 {!
2268 @enum Apple Output Property IDs
2269 @abstract The collection of property IDs for Apple output units
2270
2271 @constant kAudioOutputUnitProperty_CurrentDevice
2272 @discussion Scope: Global
2273 Value Type: AudioObjectID
2274 Access: read/write
2275
2276 The audio device being used (or to be used) by and output device unit
2277
2278 @constant kAudioOutputUnitProperty_ChannelMap
2279 @discussion Scope: Input/Output
2280 Value Type: Array of SInt32
2281 Access: Read / Write
2282
2283 This will also work with AUConverter. This property is used to map input channels from an input (source) to a destination.
2284 The number of channels represented in the channel map is the number of channels of the destination. The channel map entries
2285 contain a channel number of the source that should be mapped to that destination channel. If -1 is specified, then that
2286 destination channel will not contain any channel from the source (so it will be silent)
2287
2288 @constant kAudioOutputUnitProperty_EnableIO
2289 @discussion Scope: ( scope output, element 0 = output ) ( scope input, element 1 = input )
2290 Value Type: UInt32
2291 Access: read/write
2292 Output units default to output-only operation. Host applications may disable
2293 output or enable input operation using this property, if the output unit
2294 supports it. 0=disabled, 1=enabled using I/O proc.
2295
2296 @constant kAudioOutputUnitProperty_StartTime
2297 @discussion Scope: Global
2298 Value Type: AudioOutputUnitStartAtTimeParams
2299 Access: write only
2300 When this property is set on an output unit, it will cause the next Start request
2301 (but no subsequent Starts) to use AudioDeviceStartAtTime, using the specified
2302 timestamp, passing false for inRequestedStartTimeIsInput.
2303
2304 @constant kAudioOutputUnitProperty_SetInputCallback
2305 @discussion Scope: Global
2306 Value Type: AURenderCallbackStruct
2307 Access: read/write
2308 When an output unit has been enabled for input operation, this callback can be
2309 used to provide a single callback to the host application from the input
2310 I/O proc, in order to notify the host that input is available and may be
2311 obtained by calling the AudioUnitRender function.
2312
2313 Note that the inputProc will always receive a NULL AudioBufferList in ioData.
2314 You must call AudioUnitRender in order to obtain the audio.
2315
2316 @constant kAudioOutputUnitProperty_HasIO
2317 @discussion Scope: ( scope output, element 0 = output ) ( scope input, element 1 = input )
2318 Value Type: UInt32
2319 Access:
2320 See kAudioOutputUnitProperty_EnableIO
2321 Property value is 1 if input or output is enabled on the specified element.
2322
2323 @constant kAudioOutputUnitProperty_StartTimestampsAtZero
2324 @discussion Scope: Global
2325 Value Type: UInt32
2326 Access: read/write
2327
2328 Apple output units typically begin their stream of timestamps presented to their
2329 inputs at sample time 0. Some applications may wish to receive the HAL's timestamps
2330 directly instead. When this property is set to false, the output unit's sample times
2331 will be direct reflections of the HAL's -- except when a sample rate conversion
2332 makes this impossible.
2333
2334 This property also applies to AUConverter. Its value defaults to 1 for AUHAL;
2335 1 for other AUs.
2336 }
2337 const
2338 kAudioOutputUnitProperty_CurrentDevice = 2000;
2339 kAudioOutputUnitProperty_ChannelMap = 2002; // this will also work with AUConverter
2340 kAudioOutputUnitProperty_EnableIO = 2003;
2341 kAudioOutputUnitProperty_StartTime = 2004;
2342 kAudioOutputUnitProperty_SetInputCallback = 2005;
2343 kAudioOutputUnitProperty_HasIO = 2006;
2344 kAudioOutputUnitProperty_StartTimestampsAtZero = 2007; // this will also work with AUConverter
2345
2346
2347 {!
2348 @struct AudioOutputUnitStartAtTimeParams
2349 }
2350 type
2351 AudioOutputUnitStartAtTimeParams = record
2352 // see AudioDeviceStartAtTime
2353 mTimestamp: AudioTimeStamp;
2354 mFlags: UInt32;
2355 end;
2356 AudioOutputUnitStartAtTimeParamsPtr = ^AudioOutputUnitStartAtTimeParams;
2357
2358 //=====================================================================================================================
2359 //#pragma mark - AUVoiceProcessing unit
2360 {!
2361 @enum Apple Voice Processing Property IDs for OS X and iOS
2362 @abstract The collection of property IDs for Apple voice processing units.
2363
2364 @constant kAUVoiceIOProperty_BypassVoiceProcessing
2365 @discussion Scope: Global
2366 Value Type: UInt32
2367 Access: read/write
2368 Bypass all processing done by the voice processing unit. When set to 0
2369 (default), the processing is activated otherwise it is disabled.
2370
2371 @constant kAUVoiceIOProperty_VoiceProcessingEnableAGC
2372 @discussion Scope: Global
2373 Value Type: UInt32
2374 Access: read/write
2375 Enable automatic gain control on the processed microphone/uplink
2376 signal. On by default.
2377
2378 @constant kAUVoiceIOProperty_MuteOutput
2379 @discussion Scope: Global
2380 Value Type: UInt32
2381 Access: read/write
2382 Mutes the output of the voice processing unit.
2383 0 (default) = muting off. 1 = mute output.
2384 }
2385 const
2386 kAUVoiceIOProperty_BypassVoiceProcessing = 2100;
2387 kAUVoiceIOProperty_VoiceProcessingEnableAGC = 2101;
2388 kAUVoiceIOProperty_MuteOutput = 2104;
2389
2390
2391 //#pragma mark - AUVoiceProcessing unit deprecated properties
2392
2393
2394 {!
2395 @enum Apple Voice Processing Property IDs that are being deprecated
2396 @constant kAUVoiceIOProperty_VoiceProcessingQuality
2397 @discussion Scope: Global
2398 Value Type: UInt32
2399 Access: read/write
2400 DEPRECATED. Sets the quality of the voice processing unit. Quality values
2401 are comprised between 0 (lowest) and 127 (highest).
2402 }
2403 const
2404 kAUVoiceIOProperty_VoiceProcessingQuality = 2103;
2405 (* __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_3_0, __IPHONE_7_0) *)
2406
2407
2408 //=====================================================================================================================
2409 //#pragma mark - AUNBandEQ unit
2410 {!
2411 @enum Apple N-Band EQ Audio Unit Property IDs
2412 @abstract The collection of property IDs for the Apple N-Band EQ Audio Unit.
2413
2414 @constant kAUNBandEQProperty_NumberOfBands
2415 @discussion Scope: Global
2416 Value Type: UInt32
2417 Access: read/write
2418 Specifies the number of equalizer bands. If more than kAUNBandEQProperty_MaxNumberOfBands
2419 are specified, an error is returned.
2420 Can only be set if the unit is uninitialized.
2421
2422 @constant kAUNBandEQProperty_MaxNumberOfBands
2423 @discussion Scope: Global
2424 Value Type: UInt32
2425 Access: read-only
2426 Returns the maximum number of equalizer bands.
2427
2428 @constant kAUNBandEQProperty_BiquadCoefficients
2429 @discussion Scope: Global
2430 Value Type: array of Float64
2431 Access: read-only
2432 Returns an array of Float64 values, 5 per band.
2433 }
2434 const
2435 kAUNBandEQProperty_NumberOfBands = 2200;
2436 kAUNBandEQProperty_MaxNumberOfBands = 2201;
2437 kAUNBandEQProperty_BiquadCoefficients = 2203;
2438
2439
2440 {!
2441 @enum Apple Voice Processing AudioUnit Error IDs
2442 @abstract These are the various error IDs returned by Voice Processing audio unit.
2443
2444 @constant kAUVoiceIOErr_UnexpectedNumberOfInputChannels
2445 This error indicates that an unexpected number of input channels was encountered during initialization of voice processing audio unit
2446
2447 }
2448 const
2449 kAUVoiceIOErr_UnexpectedNumberOfInputChannels = -66784;
2450
2451
2452 //=====================================================================================================================
2453 //#pragma mark - Mixers
2454 {!
2455 @enum Apple Mixer Property IDs
2456 @abstract The collection of property IDs for Apple mixers
2457
2458 @constant kAudioUnitProperty_MeteringMode
2459 @discussion Scope: ( scope / element )
2460 Value Type: UInt32
2461 Access: read/write
2462
2463 Enable or disable metering on a particular scope/element
2464
2465 @constant kAudioUnitProperty_MatrixLevels
2466 @discussion This property can be used for both the AUMatrixMixer and AUMultiChannelMixer.
2467
2468 AUMatrixMixer
2469 Scope: Global
2470 Value Type: Float32 array
2471 Access: read/write
2472
2473 This property is used to retrieve the entire state of a matrix mixer. The size required is
2474 the number of (input channels + 1) * (output channels + 1) - see _MatrixDimensions
2475
2476 So a matrix mixer that has 2 input channels and 2 output channels, will need a 3 x 3 array of Float32
2477
2478 Global volume is stored at volumes[2][2]
2479 Input volumes are stored in the last column (volumes[0][2] for the first input channel, volumes[1][2] for the second)
2480 Output volumes are stored in the last row (volumes [2][0] and [2][1])
2481 Cross point volumes are stored at their expected locations ([0][1], etc)
2482
2483 AUMultiChannelMixer
2484 Scope: Input
2485 Value Type: Float32 array
2486 Access: read/write
2487
2488 Gets/sets the matrix levels for one input element. This allows arbitrary mixing configurations
2489 from all input channels to all output channels.
2490 The size required is the number of (input channels) * (output channels).
2491 The matrix stores only the crosspoint gains, there are no overall input or output channel gains.
2492
2493 @constant kAudioUnitProperty_MatrixDimensions
2494 @discussion Scope: Global
2495 Value Type: 2 x UInt32
2496 Access: Read only
2497
2498 Returns the total number of channels for input and output of a given matrix mixer
2499
2500 @constant kAudioUnitProperty_MeterClipping
2501 @discussion Scope: Global
2502 Value Type: AudioUnitMeterClipping
2503 Access: Read
2504
2505 A mixer returns an AudioUnitMeterClipping structure.
2506
2507
2508 @constant kAudioUnitProperty_InputAnchorTimeStamp
2509 @discussion Scope: Input
2510 Value Type: AudioTimeStamp
2511 Access: Read / Write
2512
2513 There are situations, for example moving an input between mixers, where the
2514 input's sample time timeline needs to be made continuous. This facilitates
2515 the operation: after disconnecting the input, fetch its anchor time stamp,
2516 then before reconnecting it, set the same anchor time stamp. The input's
2517 sequence of sample times will be maintained.
2518
2519 This property cannot be accessed while the input is rendering.
2520 }
2521 const
2522 // General mixers
2523 kAudioUnitProperty_MeteringMode = 3007;
2524
2525 // Matrix Mixer
2526 kAudioUnitProperty_MatrixLevels = 3006;
2527 kAudioUnitProperty_MatrixDimensions = 3009;
2528 kAudioUnitProperty_MeterClipping = 3011;
2529
2530 // Multichannel Mixer
2531 kAudioUnitProperty_InputAnchorTimeStamp = 3016;
2532
2533 {!
2534 @struct AudioUnitMeterClipping
2535
2536 @field peakValueSinceLastCall;
2537 @discussion The maximum value seen on the channel since the last time the property was retrieved.
2538 @field sawInfinity;
2539 @discussion TRUE if there was an infinite value on this channel.
2540 @field sawNotANumber
2541 @discussion TRUE if there was a floating point Not-A-Number value on this channel.
2542 }
2543 type
2544 AudioUnitMeterClipping = record
2545 peakValueSinceLastCall: Float32;
2546 sawInfinity: Boolean;
2547 sawNotANumber: Boolean;
2548 end;
2549 AudioUnitMeterClippingPtr = ^AudioUnitMeterClipping;
2550
2551 //=====================================================================================================================
2552 //#pragma mark - _SpatialMixer
2553 {!
2554 @enum Apple Mixer Property IDs
2555 @abstract The collection of property IDs for AUSpatialMixer
2556
2557 @constant kAudioUnitProperty_ReverbRoomType
2558 @discussion Scope: Global
2559 Value Type: UInt32
2560 Access: Read / Write
2561
2562 @constant kAudioUnitProperty_UsesInternalReverb
2563 @discussion Scope: Global
2564 Value Type: UInt32
2565 Access: Read / Write
2566
2567 @constant kAudioUnitProperty_SpatializationAlgorithm
2568 @discussion Scope: Input
2569 Value Type: UInt32
2570 Access: Read / Write
2571
2572 Used to set the spatialisation algorithm used by an input of AUSpatialMixer. See kSpatializationAlgorithm_
2573
2574 @constant kAudioUnitProperty_SpatialMixerRenderingFlags
2575 @discussion Scope: Input
2576 Value Type: UInt32
2577 Access: Read / Write
2578
2579 Used to enable various rendering operations on a given input for the 3DMixer. See k3DMixerRenderingFlags_
2580
2581 @constant kAudioUnitProperty_SpatialMixerAttenuationCurve
2582 @discussion Scope: Input
2583 Value Type: UInt32
2584 Access: Read / Write
2585
2586 @constant kAudioUnitProperty_SpatialMixerDistanceParams
2587 @discussion Scope: Input
2588 Value Type: MixerDistanceParams
2589 Access: Read / Write
2590 }
2591 const
2592 kAudioUnitProperty_ReverbRoomType = 10;
2593 kAudioUnitProperty_UsesInternalReverb = 1005;
2594 kAudioUnitProperty_SpatializationAlgorithm = 3000;
2595 kAudioUnitProperty_SpatialMixerDistanceParams = 3010;
2596 kAudioUnitProperty_SpatialMixerAttenuationCurve = 3013;
2597 kAudioUnitProperty_SpatialMixerRenderingFlags = 3003;
2598
2599 {!
2600 @enum Spatialization Algorithms
2601 }
2602 type
2603 AUSpatializationAlgorithm = UInt32;
2604 const
2605 kSpatializationAlgorithm_EqualPowerPanning = 0;
2606 kSpatializationAlgorithm_SphericalHead = 1;
2607 kSpatializationAlgorithm_HRTF = 2;
2608 kSpatializationAlgorithm_SoundField = 3;
2609 kSpatializationAlgorithm_VectorBasedPanning = 4;
2610 kSpatializationAlgorithm_StereoPassThrough = 5;
2611 kSpatializationAlgorithm_HRTFHQ = 6;
2612
2613 {!
2614 @enum Reverb Room Types
2615 @discussion Used to specify room type (as identified by a factory preset number) on Apple audio
2616 units that use internal reverb.
2617 }
2618 type
2619 AUReverbRoomType = UInt32;
2620 const
2621 kReverbRoomType_SmallRoom = 0;
2622 kReverbRoomType_MediumRoom = 1;
2623 kReverbRoomType_LargeRoom = 2;
2624 kReverbRoomType_MediumHall = 3;
2625 kReverbRoomType_LargeHall = 4;
2626 kReverbRoomType_Plate = 5;
2627 kReverbRoomType_MediumChamber = 6;
2628 kReverbRoomType_LargeChamber = 7;
2629 kReverbRoomType_Cathedral = 8;
2630 kReverbRoomType_LargeRoom2 = 9;
2631 kReverbRoomType_MediumHall2 = 10;
2632 kReverbRoomType_MediumHall3 = 11;
2633 kReverbRoomType_LargeHall2 = 12;
2634
2635 {!
2636 @enum AUSpatialMixer Attenuation Curves
2637 }
2638 type
2639 AUSpatialMixerAttenuationCurve = UInt32;
2640 const
2641 kSpatialMixerAttenuationCurve_Power = 0;
2642 kSpatialMixerAttenuationCurve_Exponential = 1;
2643 kSpatialMixerAttenuationCurve_Inverse = 2;
2644 kSpatialMixerAttenuationCurve_Linear = 3;
2645
2646 {!
2647 @struct MixerDistanceParams
2648 }
2649 type
2650 MixerDistanceParams = record
2651 mReferenceDistance: Float32;
2652 mMaxDistance: Float32;
2653 mMaxAttenuation: Float32; // in decibels
2654 end;
2655 MixerDistanceParamsPtr = ^MixerDistanceParams;
2656
2657 {!
2658 @enum AUSpatial Mixer Rendering Flags
2659 }
2660 type
2661 AUSpatialMixerRenderingFlags = UInt32;
2662 const
2663 kSpatialMixerRenderingFlags_InterAuralDelay = 1 shl 0;
2664 kSpatialMixerRenderingFlags_DistanceAttenuation = 1 shl 2;
2665
2666 //=====================================================================================================================
2667 //#pragma mark - _3DMixer (Deprecated)
2668 {!
2669 // AUMixer3D is deprecated. Use AUSpatialMixer instead.
2670
2671 @enum Apple Mixer Property IDs
2672 @abstract The collection of property IDs for Apple mixers
2673
2674 @constant kAudioUnitProperty_MeteringMode
2675 @discussion Scope: ( scope / element )
2676 Value Type: UInt32
2677 Access: read/write
2678
2679 Enable or disable metering on a particular scope/element
2680
2681 @constant kAudioUnitProperty_DopplerShift
2682 @discussion Scope: Input
2683 Value Type: UInt32
2684 Access: Write
2685
2686 Use a boolean true/false value to enable doppler shift for any specified input
2687
2688 @constant kAudioUnitProperty_3DMixerRenderingFlags
2689 @discussion Scope: Input
2690 Value Type: UInt32
2691 Access: Read / Write
2692
2693 Used to enable various rendering operations on a given input for the 3DMixer. See k3DMixerRenderingFlags_
2694
2695 @constant kAudioUnitProperty_3DMixerDistanceAtten
2696 @discussion Scope:
2697 Value Type:
2698 Access:
2699
2700 @constant kAudioUnitProperty_3DMixerDistanceParams
2701 @discussion Scope:
2702 Value Type:
2703 Access:
2704
2705 @constant kAudioUnitProperty_ReverbPreset
2706 @discussion Scope:
2707 Value Type:
2708 Access:
2709
2710 @constant kAudioUnitProperty_3DMixerAttenuationCurve
2711 @discussion Scope:
2712 Value Type:
2713 Access:
2714 }
2715 const
2716 kAudioUnitProperty_3DMixerDistanceParams = 3010;
2717 kAudioUnitProperty_3DMixerAttenuationCurve = 3013;
2718 kAudioUnitProperty_DopplerShift = 3002;
2719 kAudioUnitProperty_3DMixerRenderingFlags = 3003;
2720 kAudioUnitProperty_3DMixerDistanceAtten = 3004;
2721 kAudioUnitProperty_ReverbPreset = 3012;
2722 (* __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_11, __IPHONE_3_0, __IPHONE_9_0) *)
2723
2724
2725 {!
2726 @enum 3D Mixer Rendering Flags
2727 }
2728 type
2729 AU3DMixerRenderingFlags = UInt32;
2730 AU3DMixerRenderingFlagsPtr = ^AU3DMixerRenderingFlags;
2731 const
2732 k3DMixerRenderingFlags_InterAuralDelay = 1 shl 0;
2733 k3DMixerRenderingFlags_DopplerShift = 1 shl 1;
2734 k3DMixerRenderingFlags_DistanceAttenuation = 1 shl 2;
2735 k3DMixerRenderingFlags_DistanceFilter = 1 shl 3;
2736 k3DMixerRenderingFlags_DistanceDiffusion = 1 shl 4;
2737 k3DMixerRenderingFlags_LinearDistanceAttenuation = 1 shl 5;
2738 k3DMixerRenderingFlags_ConstantReverbBlend = 1 shl 6;
2739
2740 {!
2741 @enum 3D Mixer Attenuation Curves
2742 }
2743 type
2744 AU3DMixerAttenuationCurve = UInt32;
2745 AU3DMixerAttenuationCurvePtr = ^AU3DMixerAttenuationCurve;
2746 const
2747 k3DMixerAttenuationCurve_Power = 0;
2748 k3DMixerAttenuationCurve_Exponential = 1;
2749 k3DMixerAttenuationCurve_Inverse = 2;
2750 k3DMixerAttenuationCurve_Linear = 3;
2751
2752 //=====================================================================================================================
2753 //#pragma mark - AUScheduledSoundPlayer
2754 {!
2755 @enum Apple AUScheduledSoundPlayer Property IDs
2756 @abstract The collection of property IDs for the Apple AUScheduledSoundPlayer audio unit.
2757
2758 @discussion The AUScheduledSoundPlayer audio unit lets a client schedule audio buffers for
2759 future playback, with sample-accurate timing.
2760
2761
2762 Elements and Formats
2763
2764 This unit has one output element and no input elements. The output's format
2765 should be a canonical audio unit stream format (native Float32, deinterleaved).
2766
2767
2768 Scheduling
2769
2770 To schedule slices of audio for future playback, set the
2771 kAudioUnitProperty_ScheduleAudioSlice property, with a ScheduledAudioSlice
2772 structure as the property value. The slice's mTimeStamp.mSampleTime field
2773 determines when the slice will be played. This sample number is relative to
2774 the unit's start time, which you must set using the
2775 kAudioUnitProperty_ScheduleStartTimeStamp property before playback will
2776 begin.
2777
2778 You must retain, unmodified, the ScheduledAudioSlice structure, including
2779 its mBufferList and the buffers to which it points, until the slice has been
2780 completely played, or until you stop playback by uninitializing or resetting
2781 the unit. The format of the slice's buffer list must match the unit's output
2782 stream format.
2783
2784 As of OS X 10.10 and iOS 8.0, you can use an invalid time stamp (no flags set
2785 in mFlags) to indicate that the slice should be played immediately following the
2786 previous slice (or immediately, if there are no slices playing).
2787
2788 (The fields other than mSampleTime and mFlags in the mTimestamp structure are
2789 currently ignored.)
2790
2791
2792 Completion
2793
2794 To receive a callback when the slice has been played, store a pointer to a
2795 callback function in the mCompletionProc field. This function will be called
2796 (from the audio unit's rendering thread) when the slice has been completely
2797 played -- or when the slice is determined to be unplayable due to an error.
2798 As an alternative, you may also poll the slice's
2799 (mFlags & kScheduledAudioSliceFlag_Complete).
2800
2801 Upon completion, you can test (mFlags & kScheduledAudioSliceFlag_BeganToRenderLate)
2802 to determine whether some portion of the slice was not played due to its having
2803 been scheduled too late relative to the current playback time.
2804
2805
2806 Start Time
2807
2808 The audio unit will not play any slices following initialization or reset, until
2809 its start time has been set. The start time establishes the beginning of a
2810 timeline: the timestamps of all slices in the schedule are relative to the
2811 start time.
2812
2813 Set a start time by setting the kAudioUnitProperty_ScheduleStartTimeStamp
2814 property with an AudioTimeStamp structure. If the timestamp contains a valid
2815 sample time (timestamp.mFlags & kAudioTimeStampSampleTimeValid), then playback
2816 begins when the timestamp passed to the AudioUnitRender function reaches the
2817 specified sample time. If the specified sample time is -1, playback begins on
2818 the next render cycle.
2819
2820 If the start timestamp does not contain a valid sample time, but does contain a
2821 valid host time (timestamp.mFlags & kAudioTimeStampHostTimeValid), then the
2822 specified host time is translated to the sample time at which playback will
2823 begin. A host time of 0 means "start on the next render cycle."
2824
2825 The kAudioUnitProperty_ScheduleStartTimeStamp property may be queried to obtain
2826 the time at which playback began. If the start time has not yet been reached,
2827 the timestamp returned will be whatever the host application last set.
2828
2829
2830 Current play time
2831
2832 The kAudioUnitProperty_CurrentPlayTime property may be queried to determine the
2833 audio unit's current time offset from its start time. This is useful, for
2834 example, to monitor playback progress.
2835
2836
2837 Unscheduling events
2838
2839 To clear an audio unit's play schedule, call the AudioUnitReset function. The
2840 completion proc (if any) for each slice in the schedule will called. Playback
2841 will not resume until a new start time has been set. This also happens when
2842 the audio unit is uninitialized.
2843
2844 @constant kAudioUnitProperty_ScheduleAudioSlice
2845 @discussion Scope:
2846 Value Type: ScheduledAudioSlice
2847 Access:
2848
2849 @constant kAudioUnitProperty_ScheduleStartTimeStamp
2850 @discussion Scope:
2851 Value Type: AudioTimeStamp
2852 Access:
2853 Sample time or host time valid. Sample time takes precedence,
2854 -1 means "now". Host time of 0 means "now."
2855
2856 @constant kAudioUnitProperty_CurrentPlayTime
2857 @discussion Scope:
2858 Value Type: AudioTimeStamp
2859 Access:
2860 AudioTimeStamp, relative to start time, sample time of -1 if not yet started.
2861 }
2862 const
2863 kAudioUnitProperty_ScheduleAudioSlice = 3300;
2864 kAudioUnitProperty_ScheduleStartTimeStamp = 3301;
2865 kAudioUnitProperty_CurrentPlayTime = 3302;
2866
2867 {!
2868 @enum ScheduledAudioSlice
2869 @abstract bits in ScheduledAudioSlice.mFlags
2870
2871 @constant kScheduledAudioSliceFlag_Complete
2872 @abstract Set if the unit is done with this slice
2873 @constant kScheduledAudioSliceFlag_BeganToRender
2874 @abstract Set if any portion of the buffer has been played
2875 @constant kScheduledAudioSliceFlag_BeganToRenderLate
2876 @abstract Set if any portion of the buffer was not played because it was scheduled late
2877 @constant kScheduledAudioSliceFlag_Loop
2878 @abstract specifies that the buffer should loop indefinitely
2879 @constant kScheduledAudioSliceFlag_Interrupt
2880 @abstract specifies that the buffer should interrupt any previously scheduled buffer
2881 (by default, buffers following a playing buffer are not played until the
2882 playing buffer has completed).
2883 @constant kScheduledAudioSliceFlag_InterruptAtLoop
2884 @abstract specifies that the buffer should interrupt any previously scheduled buffer,
2885 but only at a loop point in that buffer.
2886
2887 }
2888 type
2889 AUScheduledAudioSliceFlags = UInt32;
2890 AUScheduledAudioSliceFlagsPtr = ^AUScheduledAudioSliceFlags;
2891 const
2892 kScheduledAudioSliceFlag_Complete = $01;
2893 kScheduledAudioSliceFlag_BeganToRender = $02;
2894 kScheduledAudioSliceFlag_BeganToRenderLate = $04;
2895 kScheduledAudioSliceFlag_Loop = $08; // new for OS X 10.10 and iOS 8.0
2896 kScheduledAudioSliceFlag_Interrupt = $10; // new for OS X 10.10 and iOS 8.0
2897 kScheduledAudioSliceFlag_InterruptAtLoop = $20; // new for OS X 10.10 and iOS 8.0
2898
2899 type
2900 // forward dec, see definition below
2901 ScheduledAudioSlicePtr = ^ScheduledAudioSlice;
2902 {!
2903 @typedef ScheduledAudioSliceCompletionProc
2904 }
2905
2906 ScheduledAudioSliceCompletionProc = procedure(userData : UnivPtr; bufferList : ScheduledAudioSlicePtr);
2907
2908 {
2909 @struct ScheduledAudioSlice
2910 @field mTimeStamp
2911 @field mCompletionProc
2912 May be null
2913 @field mCompletionProcUserData
2914 @field mFlags
2915 @field mReserved
2916 Must be 0
2917 @field mReserved2
2918 For internal use
2919 @field mNumberFrames
2920 Must be consistent with byte count of mBufferList
2921 @field mBufferList
2922 Must contain deinterleaved Float32
2923 }
2924 ScheduledAudioSlice = record
2925 mTimeStamp: AudioTimeStamp;
2926 mCompletionProc: ScheduledAudioSliceCompletionProc; // may be null
2927 mCompletionProcUserData: UnivPtr;
2928 mFlags: AUScheduledAudioSliceFlags;
2929 mReserved: UInt32; // must be 0
2930 mReserved2: UnivPtr; // for internal use
2931 mNumberFrames: UInt32; // must be consistent with byte count of mBufferList
2932 mBufferList: AudioBufferListPtr; // must contain deinterleaved Float32
2933 end;
2934
2935 //=====================================================================================================================
2936 //#pragma mark - AUAudioFilePlayer
2937 {!
2938 @enum Apple AUAudioFilePlayer Property IDs
2939 @abstract The collection of property IDs for Apple AUAudioFilePlayer
2940 @discussion This audio unit lets you schedule regions of audio files for future playback,
2941 with sample-accurate timing.
2942
2943 The unit is a subclass of AUScheduledSoundPlayer and inherits all of its
2944 behavior. In particular, this unit implements the kAudioUnitProperty_ScheduleStartTimeStamp
2945 and kAudioUnitProperty_CurrentPlayTime properties. Instead of scheduling
2946 slices (buffers) of audio to be played (via kAudioUnitProperty_ScheduleAudioSlice),
2947 however, you schedule regions of audio files to be played. The unit reads and
2948 converts audio file data into its own internal buffers. It performs disk I/O
2949 on a high-priority thread shared among all instances of this unit within a
2950 process. Upon completion of a disk read, the unit internally schedules
2951 buffers for playback.
2952
2953
2954 Elements and Formats
2955
2956 This unit has one output element and no input elements. The output's format
2957 should be a canonical audio unit stream format (native Float32,
2958 deinterleaved). This format should have at least as many channels are in the
2959 audio file(s) to be played (otherwise channels will be dropped). During
2960 playback, all audio file data is converted to the unit's output format.
2961
2962
2963 Audio Files
2964
2965 Before starting playback, you must first open all audio files to be played
2966 using the AudioFile API's (see AudioToolbox/AudioFile.h), and pass their
2967 AudioFileIDs to the unit by setting the kAudioUnitProperty_ScheduledFileIDs
2968 property. This property must not be set during playback. The audio files must
2969 be kept open for the duration of playback.
2970
2971
2972 Scheduling Regions
2973
2974 To schedule the playback of a region of an audio file, set the
2975 kAudioUnitProperty_ScheduledFileRegion property. This is a
2976 ScheduledAudioFileRegion structure. mTimeStamp.mSampleTime must be valid and
2977 is interpreted relative to the unit's start time -- the start time semantics
2978 (using kAudioUnitProperty_ScheduleStartTimeStamp) are identical to those of
2979 AUScheduledSoundPlayer. Unlike the ScheduledAudioSlice structures, the unit
2980 makes copies of ScheduledAudioFileRegions, so you may create them on the
2981 stack or otherwise reuse/dispose of them immediately after scheduling them.
2982
2983
2984 Priming
2985
2986 You should set kAudioUnitProperty_ScheduledFilePrime after scheduling
2987 initial file regions to be played and before starting playback. This SetProperty call
2988 will begin reading the audio files and not return until the number of frames
2989 specified by the property value have been read.
2990
2991
2992 Completion Callbacks
2993
2994 A region's completion callback (mCompletionProc) is called when it has been
2995 completely scheduled for reading from disk. This callback is issued on the disk
2996 read thread. If the region is not read from disk in time to play at its
2997 scheduled time, mCompletionProc is called a second time with an error code,
2998 also from the read thread. Note that the region passed to the callback will not
2999 be the same memory object as was passed by the client (since the unit copies the region).
3000
3001
3002 Start Time and Current Time
3003
3004 These properties work identically as in AUScheduledSoundPlayer.
3005
3006
3007 Unscheduling regions
3008
3009 To clear the unit's play schedule, call the AudioUnitReset function. The completion proc
3010 (if any) for each file region in the schedule will be called. Playback will
3011 not resume until a new start time has been set. This also happens when the
3012 unit is uninitialized.
3013
3014
3015 Customization
3016
3017 The size and number of the player's disk read buffers default to "sensible"
3018 values, but may be configured with the properties:
3019 kAudioUnitProperty_ScheduledFileBufferSizeFrames
3020 kAudioUnitProperty_ScheduledFileNumberBuffers
3021
3022
3023 Bugs
3024
3025 kAudioUnitProperty_ScheduledFileBufferSizeFrames
3026 kAudioUnitProperty_ScheduledFileNumberBuffers
3027 are currently unimplemented
3028
3029 An option to make the unit not perform conversion from the audio file sample
3030 rate to the unit's output rate may be desirable.
3031
3032 @constant kAudioUnitProperty_ScheduledFileIDs
3033 @discussion Scope:
3034 Value Type: Array of AudioFileIDs
3035 Access:
3036 Must set this property on scheduled file player for all files to be played
3037
3038 @constant kAudioUnitProperty_ScheduledFileRegion
3039 @discussion Scope:
3040 Value Type: ScheduledAudioFileRegion
3041 Access:
3042
3043 @constant kAudioUnitProperty_ScheduledFilePrime
3044 @discussion Scope:
3045 Value Type: UInt32
3046 Access:
3047 The number of frames to read from disk before returning, or 0 to specify use
3048 of a default value
3049
3050 @constant kAudioUnitProperty_ScheduledFileBufferSizeFrames
3051 @discussion Scope:
3052 Value Type: UInt32
3053 Access:
3054
3055 @constant kAudioUnitProperty_ScheduledFileNumberBuffers
3056 @discussion Scope:
3057 Value Type: UInt32
3058 Access:
3059 }
3060 const
3061 kAudioUnitProperty_ScheduledFileIDs = 3310;
3062 kAudioUnitProperty_ScheduledFileRegion = 3311;
3063 kAudioUnitProperty_ScheduledFilePrime = 3312;
3064 kAudioUnitProperty_ScheduledFileBufferSizeFrames = 3313;
3065 kAudioUnitProperty_ScheduledFileNumberBuffers = 3314;
3066
3067 type
3068 ScheduledAudioFileRegionPtr = ^ScheduledAudioFileRegion; //forward declaraion, see definition below
3069 {!
3070 @typedef ScheduledAudioFileRegionCompletionProc
3071 }
3072 ScheduledAudioFileRegionCompletionProc = procedure(userData : UnivPtr; fileRegion : ScheduledAudioFileRegionPtr; aResult : OSStatus);
3073
3074 {!
3075 @struct ScheduledAudioFileRegion
3076 @field mTimeStamp
3077 @field mCompletionProc
3078 may be NULL
3079 @field mCompletionProcUserData
3080 @field mAudioFile
3081 must be a valid and open AudioFileID
3082 defined in AudioToolbox/AudioFile.h: typedef struct OpaqueAudioFileID *AudioFileID;
3083 @field mLoopCount
3084 0 = don't loop
3085 @field mStartFrame
3086 offset into file
3087 @field mFramesToPlay
3088 number of frames to play
3089
3090 }
3091
3092 ScheduledAudioFileRegion = record
3093 mTimeStamp: AudioTimeStamp;
3094 mCompletionProc: ScheduledAudioFileRegionCompletionProc {__nullable};
3095 mCompletionProcUserData: UnivPtr {__nullable};
3096 mAudioFile: AudioFileID;
3097 mLoopCount: UInt32;
3098 mStartFrame: SInt64;
3099 mFramesToPlay: UInt32;
3100 end;
3101
3102 //=====================================================================================================================
3103 //#pragma mark - OS X-specific Music Device Properties used by DLSMusicDevice
3104
3105 {$ifc TARGET_OS_MAC}
3106
3107 {!
3108 @enum Property IDs
3109 @abstract OS X-only audio unit property IDs used by the DLSMusicDevice
3110
3111 @constant kMusicDeviceProperty_SoundBankData
3112 @discussion Scope:
3113 Value Type:
3114 Access:
3115
3116 @constant kMusicDeviceProperty_StreamFromDisk
3117 @discussion Scope:
3118 Value Type:
3119 Access:
3120
3121 @constant kMusicDeviceProperty_SoundBankFSRef
3122 @discussion Scope:
3123 Value Type:
3124 Access:
3125
3126 }
3127 const
3128 kMusicDeviceProperty_UsesInternalReverb = kAudioUnitProperty_UsesInternalReverb;
3129 kMusicDeviceProperty_SoundBankData = 1008;
3130 kMusicDeviceProperty_StreamFromDisk = 1011;
3131 kMusicDeviceProperty_SoundBankFSRef = 1012;
3132
3133
3134 //=====================================================================================================================
3135 //#pragma mark - Music Device Properties used by DLSMusicDevice
3136
3137 {!
3138 @enum Generic Property IDs
3139 @abstract Audio unit property IDs used by DLSMusicDevice (OSX)
3140
3141 @constant kMusicDeviceProperty_InstrumentName
3142 @discussion Scope: Global
3143 Value Type: CFURLRef
3144 Access: Read
3145
3146 @constant kMusicDeviceProperty_InstrumentNumber
3147 @discussion Scope: Global
3148 Value Type: UInt32
3149 Access: Read
3150 }
3151 const
3152 kMusicDeviceProperty_InstrumentName = 1001;
3153 kMusicDeviceProperty_InstrumentNumber = 1004;
3154
3155 //=====================================================================================================================
3156 //#pragma mark - Music Device Properties used by DLSMusicDevice and AUMIDISynth
3157
3158 {!
3159 @enum Generic Property IDs
3160 @abstract Audio unit property IDs used by AUMIDISynth (iOS) and DLSMusicDevice (OSX)
3161
3162 @constant kMusicDeviceProperty_InstrumentCount
3163 @discussion Scope: Global
3164 Value Type: UInt32
3165 Access: Read
3166
3167 For a mono-timbral music instrument, this property should return 0 (it should be implemented).
3168
3169 For a multi-timbral music instrument, this property can return the number of independent patches that
3170 are available to be chosen as an active patch for the instrument. For instance, for Apple's DLS Music Device
3171 and AUMIDISynth, this value returns the number of patches that are found in a given DLS or SoundFont file when loaded.
3172
3173 @constant kMusicDeviceProperty_BankName
3174 @discussion Scope: Global
3175 Value Type: CFStringRef
3176 Access: Read
3177
3178 @constant kMusicDeviceProperty_SoundBankURL
3179 @discussion Scope: Global
3180 Value Type: CFURLRef
3181 Access: Read (Read/Write for AUMIDISynth)
3182
3183 For DLSMusicDevice, this is a read-only property to return the URL for the currently-loaded bank file.
3184 For AUMIDISynth it is also writeable, and is used to specify the URL for the sound bank to load and use
3185 for playback.
3186 }
3187 const
3188 kMusicDeviceProperty_InstrumentCount = 1000;
3189 kMusicDeviceProperty_BankName = 1007;
3190 kMusicDeviceProperty_SoundBankURL = 1100;
3191
3192 //=====================================================================================================================
3193 //#pragma mark - AUMIDISynth
3194
3195 {!
3196 @enum Apple AUMIDISynth Property IDs
3197 @abstract The collection of property IDs for the Apple Midi Synth audio unit.
3198
3199 @discussion The AUMIDISynth audio unit lets a client create fully GM-compatible Midi Synth.
3200
3201 @constant kAUMIDISynthProperty_EnablePreload
3202 @discussion Scope: Global
3203 Value Type: UInt32
3204 Access: Write
3205
3206 Setting this property to 1 puts the MIDISynth in a mode where it will attempt to load
3207 instruments from the bank or file when it receives a program change message. This
3208 is used internally by the MusicSequence. It should only be used prior to MIDI playback,
3209 and must be set back to 0 before attempting to start playback.
3210 }
3211 const
3212 kAUMIDISynthProperty_EnablePreload = 4119;
3213
3214 //=====================================================================================================================
3215 //#pragma mark - AUSampler
3216
3217 {!
3218 @enum Apple AUSampler Property IDs
3219 @abstract The collection of property IDs for the Apple Sampler audio unit.
3220
3221 @discussion The AUSampler audio unit lets a client create an editable, interactive
3222 sampler synthesizer instrument.
3223
3224 @constant kAUSamplerProperty_LoadInstrument
3225 @discussion Scope: Global
3226 Value Type: AUSamplerInstrumentData
3227 Access: Write
3228 Load an instrument from an external DLS or Soundfont2 bank file, or from other file formats.
3229
3230 @constant kAUSamplerProperty_LoadAudioFiles
3231 @discussion Scope: Global
3232 Value Type: CFArrayRef
3233 Access: Write
3234 Create a new preset from a list of audio file paths. The CFArray should contain a set
3235 of CFURLRefs, one per file. The previous preset will be completely cleared.
3236 }
3237 const
3238 // range (4100->4999)
3239 kAUSamplerProperty_LoadInstrument = 4102;
3240 kAUSamplerProperty_LoadAudioFiles = 4101;
3241
3242 {
3243 @struct AUSamplerInstrumentData
3244 @abstract Used for loading an instrument from either an external bank file (i.e. DLS or SoundFont), an Apple
3245 .aupreset, a Logic or GarageBand EXS24 sampler instrument, or creating a new default instrument from
3246 a single audio file. The path to the bank or instrument file is specified in the fileURL field.
3247 The instrumentType field distinguishes between the instrument types. The remaining fields of this
3248 struct are used only for the kInstrumentType_DLSPreset and kInstrumentType_SF2Preset types to
3249 identify the particular bank and preset IDs for the instrument you wish to load from the bank.
3250 They represent values for MIDI controllers 0 and 32 and the MIDI present change message that would be
3251 sent to a GM2-compatible synth for program changes. Use the provided constants
3252 (kAUSampler_DefaultMelodicBankMSB, kAUSampler_DefaultPercussionBankMSB) to designate melodic or
3253 percussion banks per the GM2 specification (GM-compatible DLS or Soundfont banks). For custom
3254 non-GM-compatible DLS and Soundfont banks, use the actual MSB/LSB values associated with the desired preset.
3255
3256 @field fileURL
3257 The URL of the path to the bank or instrument file. Caller is responsible for releasing the
3258 provided CFURLRef.
3259 @field instrumentType
3260 The type of instrument being loaded or created. For example, use kInstrumentType_DLSPreset to load an
3261 instrument from a DLS bank file.
3262 @field bankMSB
3263 For the preset instruments, the most significant byte value for a particular bank variation within that
3264 file. Range is 0 to 127. Use kAUSampler_DefaultMelodicBankMSB by default.
3265 @field bankLSB
3266 For the preset instruments, the least significant byte value for a particular bank variation within that
3267 file. Range is 0 to 127. Use kAUSampler_DefaultBankLSB by default.
3268 @field presetID
3269 For the preset instruments, the numeric ID of a particular preset within that bank to load.
3270 Range is 0 to 127.
3271 }
3272
3273 type
3274 AUSamplerInstrumentData = record
3275 fileURL: CFURLRef;
3276 instrumentType: UInt8;
3277 bankMSB: UInt8;
3278 bankLSB: UInt8;
3279 presetID: UInt8;
3280 end;
3281 AUSamplerInstrumentDataPtr = ^AUSamplerInstrumentData;
3282
3283 {
3284 @enum InstrumentTypes
3285 @abstract Values to specify the type of instrument being loaded.
3286
3287 @constant kInstrumentType_DLSPreset
3288 @discussion A preset from a DLS bank file. Bank MSB, LSB and preset ID must be specified.
3289
3290 @constant kInstrumentType_SF2Preset
3291 @discussion A preset from a SoundFont2 bank file. Bank MSB, LSB and preset ID must be specified.
3292
3293 @constant kInstrumentType_AUPreset
3294 @discussion A native Apple .aupreset file created using the AUSampler's custom view.
3295
3296 @constant kInstrumentType_Audiofile
3297 @discussion An audio file which will be used to create a default instrument with that file as its sole sample.
3298
3299 @constant kInstrumentType_EXS24
3300 @discussion A Logic or GarageBand sampler instrument.
3301
3302 }
3303
3304 const
3305 kInstrumentType_DLSPreset = 1;
3306 kInstrumentType_SF2Preset = kInstrumentType_DLSPreset;
3307 kInstrumentType_AUPreset = 2;
3308 kInstrumentType_Audiofile = 3;
3309 kInstrumentType_EXS24 = 4;
3310
3311 const
3312 kAUSampler_DefaultPercussionBankMSB = $78;
3313 kAUSampler_DefaultMelodicBankMSB = $79;
3314 kAUSampler_DefaultBankLSB = $00;
3315
3316
3317 //=====================================================================================================================
3318 //#pragma mark - AUDeferredRenderer
3319 {!
3320 @enum AUDeferredRenderer
3321 @discussion This audio unit has one input element and one output element. They must both have
3322 the same format, which must be canonical (Float32 deinterleaved) and must have
3323 the same number of channels.
3324
3325 The AUDeferredRenderer unit creates a high-priority producer thread, on which
3326 calls by this AU for input are performed at a constant buffer size. This buffer size may be
3327 set with the kAudioUnitProperty_DeferredRendererPullSize property. The deferred
3328 renderer may be asked to render at different buffer sizes by a downstream unit or
3329 host application, but it always pulls upstream at its constant buffer size.
3330 The upstream pull size MUST be greater than or equal to the downstream pull
3331 size.
3332
3333 The upstream producer thread runs in advance of calls to its Render
3334 function, with respect to the timestamps being passed to Render and
3335 PullInput. The difference between these timestamps is the unit's "latency",
3336 which is always at least one upstream pull buffer. The client may specify
3337 additional latency with the property
3338 kAudioUnitProperty_DeferredRendererExtraLatency, which is a number of sample
3339 frames.
3340
3341 It is possible, at Render time, for the producer thread to have not yet
3342 finished rendering the necessary data. This generates an error. In order to
3343 give the producer a small amount of extra time to finish rendering, the
3344 client may set the unit's property
3345 kAudioUnitProperty_DeferredRendererWaitFrames. If this property is non-zero,
3346 then when Render finds that insufficient data has been produced, it will
3347 sleep for the amount of realtime corresponding to the number of wait frames.
3348 It will then check again to see if the required amount of data has been
3349 produced, and fail if it hasn't.
3350
3351 @constant kAudioUnitProperty_DeferredRendererPullSize
3352 @discussion Scope:
3353 Value Type: UInt32
3354 Access:
3355
3356 @constant kAudioUnitProperty_DeferredRendererExtraLatency
3357 @discussion Scope:
3358 Value Type: UInt32
3359 Access:
3360
3361 @constant kAudioUnitProperty_DeferredRendererWaitFrames
3362 @discussion Scope:
3363 Value Type: UInt32
3364 Access:
3365 }
3366 const
3367 kAudioUnitProperty_DeferredRendererPullSize = 3320;
3368 kAudioUnitProperty_DeferredRendererExtraLatency = 3321;
3369 kAudioUnitProperty_DeferredRendererWaitFrames = 3322;
3370
3371 //=====================================================================================================================
3372 //#pragma mark - AUNetReceive
3373 {!
3374 @enum AUNetReceive
3375 @constant kAUNetReceiveProperty_Hostname
3376 @discussion Scope: Global
3377 Value Type: CFStringRef
3378 Access:
3379 The hostname from which you wish to receive audio.
3380 For GetProperty, the returned CFStringRef is a copy and therefore must be released by the caller.
3381 The UI view for AUNetReceive does the resolution of Bonjour service names to hostnames.
3382 Clients who are using this AU programmatically using Bonjour will have to do this resolution themselves.
3383 It is not done by the AU.
3384
3385 @constant kAUNetReceiveProperty_Password
3386 @discussion Scope: Global
3387 Value Type: CFStringRef
3388 Access: Read / Write
3389 The password to send to the sender. Leave unset or set to the empty string for no password.
3390 For GetProperty, the returned CFStringRef is a copy and therefore must be released by the caller.
3391 }
3392 const
3393 kAUNetReceiveProperty_Hostname = 3511;
3394 kAUNetReceiveProperty_Password = 3512;
3395
3396 //=====================================================================================================================
3397 //#pragma mark - AUNetSend
3398 {!
3399 @enum AUNetSend
3400 @constant kAUNetSendProperty_PortNum
3401 @discussion Scope: Global
3402 Value Type: UInt32
3403 Access: Read / Write
3404 The network port number on which to send.
3405
3406 @constant kAUNetSendProperty_TransmissionFormat
3407 @discussion Scope: Global
3408 Value Type: AudioStreamBasicDescription
3409 Access: Read / Write
3410 Get or set an arbitrary format that will be used to transmit the audio.
3411 For compressed formats, it is recommended to use kAUNetSendProperty_TransmissionFormatIndex instead of this property,
3412 since there is no way to specify a bit rate with this property.
3413
3414 @constant kAUNetSendProperty_TransmissionFormatIndex
3415 @discussion Scope: Global
3416 Value Type: UInt32
3417 Access: Read / Write
3418 Get or set the index of the preset format that will be used to transmit the audio.
3419 The format indices can be found in the NetSendPresetFormat enum.
3420
3421 @constant kAUNetSendProperty_ServiceName
3422 @discussion Scope: Global
3423 Value Type: CFStringRef
3424 Access: Read / Write
3425 The name you want to publish for this network service.
3426 For GetProperty, the returned CFStringRef is a copy and therefore must be released by the caller.
3427
3428 @constant kAUNetSendProperty_Disconnect
3429 @discussion Scope: Global
3430 Value Type: UInt32
3431 Access: Read / Write
3432 In order to disconnect, call this with a non-zero value.
3433 In order to connect, call this with a zero value.
3434 For GetProperty, the returned value the last value set by the caller.
3435 To get the current connection status, get the value of the parameter kAUNetReceiveParam_Status.
3436
3437 @constant kAUNetSendProperty_Password
3438 @discussion Scope: Global
3439 Value Type: CFStringRef
3440 Access: Read / Write
3441 The password that must be used by the receiver. Leave unset or set to the empty string for no password.
3442 For GetProperty, the returned CFStringRef is a copy and therefore must be released by the caller.
3443
3444 }
3445 const
3446 kAUNetSendProperty_PortNum = 3513;
3447 kAUNetSendProperty_TransmissionFormat = 3514;
3448 kAUNetSendProperty_TransmissionFormatIndex = 3515;
3449 kAUNetSendProperty_ServiceName = 3516;
3450 kAUNetSendProperty_Disconnect = 3517;
3451 kAUNetSendProperty_Password = 3518;
3452
3453 {!
3454 @enum NetSendPresetFormat
3455 @constant kAUNetSendPresetFormat_PCMFloat32
3456 @discussion 1411 kilobits per second per channel @ 44100KHz (kilo == 1000 not 1024)
3457 @constant kAUNetSendPresetFormat_PCMInt24
3458 @discussion 1058 kilobits per second per channel @ 44100KHz
3459 @constant kAUNetSendPresetFormat_PCMInt16
3460 @discussion 706 kilobits per second per channel @ 44100KHz
3461 @constant kAUNetSendPresetFormat_Lossless24
3462 @discussion 650 kilobits per second per channel @ 44100KHz
3463 @constant kAUNetSendPresetFormat_Lossless16
3464 @discussion 350 kilobits per second per channel @ 44100KHz
3465 @constant kAUNetSendPresetFormat_ULaw
3466 @discussion 353 kilobits per second per channel @ 44100KHz
3467 @constant kAUNetSendPresetFormat_IMA4
3468 @discussion 176 kilobits per second per channel @ 44100KHz
3469 @constant kAUNetSendPresetFormat_AAC_128kbpspc
3470 @discussion 128 kilobits per second per channel
3471 @constant kAUNetSendPresetFormat_AAC_96kbpspc
3472 @discussion 96 kilobits per second per channel
3473 @constant kAUNetSendPresetFormat_AAC_80kbpspc
3474 @discussion 80 kilobits per second per channel
3475 @constant kAUNetSendPresetFormat_AAC_64kbpspc
3476 @discussion 64 kilobits per second per channel
3477 @constant kAUNetSendPresetFormat_AAC_48kbpspc
3478 @discussion 48 kilobits per second per channel
3479 @constant kAUNetSendPresetFormat_AAC_40kbpspc
3480 @discussion 40 kilobits per second per channel
3481 @constant kAUNetSendPresetFormat_AAC_32kbpspc
3482 @discussion 32 kilobits per second per channel
3483 @constant kAUNetSendNumPresetFormats = 14
3484 }
3485 const
3486 kAUNetSendPresetFormat_PCMFloat32 = 0;
3487 kAUNetSendPresetFormat_PCMInt24 = 1;
3488 kAUNetSendPresetFormat_PCMInt16 = 2;
3489 kAUNetSendPresetFormat_Lossless24 = 3;
3490 kAUNetSendPresetFormat_Lossless16 = 4;
3491 kAUNetSendPresetFormat_ULaw = 5;
3492 kAUNetSendPresetFormat_IMA4 = 6;
3493 kAUNetSendPresetFormat_AAC_128kbpspc = 7;
3494 kAUNetSendPresetFormat_AAC_96kbpspc = 8;
3495 kAUNetSendPresetFormat_AAC_80kbpspc = 9;
3496 kAUNetSendPresetFormat_AAC_64kbpspc = 10;
3497 kAUNetSendPresetFormat_AAC_48kbpspc = 11;
3498 kAUNetSendPresetFormat_AAC_40kbpspc = 12;
3499 kAUNetSendPresetFormat_AAC_32kbpspc = 13;
3500 kAUNetSendPresetFormat_AAC_LD_64kbpspc = 14;
3501 kAUNetSendPresetFormat_AAC_LD_48kbpspc = 15;
3502 kAUNetSendPresetFormat_AAC_LD_40kbpspc = 16;
3503 kAUNetSendPresetFormat_AAC_LD_32kbpspc = 17;
3504 kAUNetSendNumPresetFormats = 18;
3505
3506 {$endc} { TARGET_OS_MAC }
3507
3508 //=====================================================================================================================
3509 //#pragma mark -
3510 //#pragma mark Deprecated Properties
3511
3512 {$ifc TARGET_OS_MAC}
3513
3514 // NumVersion is no longer used (originally from MacTypes.h)
3515 type
3516 //#if TARGET_RT_BIG_ENDIAN
3517 {$ifc TARGET_RT_BIG_ENDIAN}
3518
3519 AUNumVersion = record
3520 { Numeric version part of 'vers' resource }
3521 majorRev: UInt8; {1st part of version number in BCD}
3522 minorAndBugRev: UInt8; {2nd & 3rd part of version number share a byte}
3523 stage: UInt8; {stage code: dev, alpha, beta, final}
3524 nonRelRev: UInt8; {revision level of non-released version}
3525 end;
3526 {$elsec} { TARGET_RT_BIG_ENDIAN }
3527
3528 AUNumVersion = record
3529 { Numeric version part of 'vers' resource accessible in little endian format }
3530 nonRelRev: UInt8; {revision level of non-released version}
3531 stage: UInt8; {stage code: dev, alpha, beta, final}
3532 minorAndBugRev: UInt8; {2nd & 3rd part of version number share a byte}
3533 majorRev: UInt8; {1st part of version number in BCD}
3534 end;
3535 {$endc} { TARGET_RT_BIG_ENDIAN }
3536 AUNumVersionPtr = ^AUNumVersion;
3537 AUNumVersionHandle = ^AUNumVersionPtr;
3538
3539 {!
3540 @struct AUHostIdentifier
3541 @abstract Used to describe the name and version of the audio unit's host
3542 }
3543 type
3544 AUHostIdentifier = record
3545 hostName: CFStringRef;
3546 hostVersion: AUNumVersion;
3547 end;
3548
3549 //=====================================================================================================================
3550 // GENERIC
3551 const
3552 kAudioUnitParameterFlag_Global = 1 shl 0; // parameter scope is global
3553 kAudioUnitParameterFlag_Input = 1 shl 1; // parameter scope is input
3554 kAudioUnitParameterFlag_Output = 1 shl 2; // parameter scope is output
3555 kAudioUnitParameterFlag_Group = 1 shl 3; // parameter scope is group
3556
3557 const
3558 kAudioUnitParameterFlag_HasName = kAudioUnitParameterFlag_ValuesHaveStrings;
3559
3560 const
3561 //kAudioUnitProperty_SetInputCallback = 7 -> deprecated
3562 kAudioUnitProperty_SRCAlgorithm = 9; // see kAudioUnitProperty_SampleRateConverterComplexity
3563 kAudioUnitProperty_MIDIControlMapping = 17; // see ParameterMIDIMapping Properties
3564 kAudioUnitProperty_CurrentPreset = 28; // see PresentPreset
3565
3566 kAudioUnitProperty_ParameterValueName = kAudioUnitProperty_ParameterStringFromValue;
3567 kAudioUnitProperty_BusCount = kAudioUnitProperty_ElementCount;
3568 kAudioOfflineUnitProperty_InputSize = kAudioUnitOfflineProperty_InputSize;
3569 kAudioOfflineUnitProperty_OutputSize = kAudioUnitOfflineProperty_OutputSize;
3570
3571 const
3572 kAudioUnitSRCAlgorithm_Polyphase = FourCharCode('poly'); // same as kAudioUnitSampleRateConverterComplexity_Normal
3573 kAudioUnitSRCAlgorithm_MediumQuality = FourCharCode('csrc'); // same as kAudioUnitSampleRateConverterComplexity_Normal
3574
3575
3576 // Deprecated in Mac OS X v10.2. See AUParameterMIDIMapping.
3577 type
3578 AudioUnitMIDIControlMapping = record
3579 midiNRPN: UInt16;
3580 midiControl: UInt8;
3581 scope: UInt8;
3582 element: AudioUnitElement;
3583 parameter: AudioUnitParameterID;
3584 end;
3585
3586 // Deprecated. See AudioUnitParameterStringFromValue for equivalent structure, but with clearer field names
3587 type
3588 AudioUnitParameterValueName = record
3589 inParamID: AudioUnitParameterID;
3590 inValue: {const} Float32Ptr; // may be NULL if should translate current parameter value
3591 outName: CFStringRef; // see comments for kAudioUnitProperty_ParameterStringFromValue
3592 end;
3593
3594
3595 //=====================================================================================================================
3596 // Deprecated. These properties are Apple specific.
3597 const
3598 kMusicDeviceProperty_GroupOutputBus = 1002;
3599 kMusicDeviceProperty_SoundBankFSSpec = 1003;
3600 kAudioUnitProperty_PannerMode = 3008;
3601 const
3602 kAudioUnitProperty_SpeakerConfiguration = 3001;
3603
3604 // Deprecated in favor of the newer AudioChannelLayout
3605 // structure and its supporting property.
3606 const
3607 kSpeakerConfiguration_HeadPhones = 0;
3608 kSpeakerConfiguration_Stereo = 1;
3609 kSpeakerConfiguration_Quad = 2;
3610 kSpeakerConfiguration_5_0 = 3;
3611 kSpeakerConfiguration_5_1 = kSpeakerConfiguration_5_0;
3612
3613
3614 // Deprecated in favor of the newer AUSamplerInstrumentData
3615 // structure and its supporting property.
3616
3617 type
3618 AUSamplerBankPresetData = record
3619 bankURL: CFURLRef;
3620 bankMSB: UInt8;
3621 bankLSB: UInt8;
3622 presetID: UInt8;
3623 reserved: UInt8;
3624 end;
3625 AUSamplerBankPresetDataPtr = ^AUSamplerBankPresetData;
3626
3627 const
3628 kAUSamplerProperty_LoadPresetFromBank = 4100;
3629 kAUSamplerProperty_BankAndPreset = kAUSamplerProperty_LoadPresetFromBank;
3630
3631 {$endc} { TARGET_OS_MAC }
3632
3633 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
3634 implementation
3635
3636
GetAudioUnitParameterDisplayTypenull3637 function GetAudioUnitParameterDisplayType(flags : UInt32) : UInt32; inline;
3638 begin
3639 GetAudioUnitParameterDisplayType := flags and kAudioUnitParameterFlag_DisplayMask
3640 end;
3641
AudioUnitDisplayTypeIsLogarithmicnull3642 function AudioUnitDisplayTypeIsLogarithmic(flags : UInt32) : Boolean; inline;
3643 begin
3644 AudioUnitDisplayTypeIsLogarithmic := GetAudioUnitParameterDisplayType(flags) = kAudioUnitParameterFlag_DisplayLogarithmic
3645 end;
3646
AudioUnitDisplayTypeIsSquareRootnull3647 function AudioUnitDisplayTypeIsSquareRoot(flags : UInt32) : Boolean; inline;
3648 begin
3649 AudioUnitDisplayTypeIsSquareRoot := GetAudioUnitParameterDisplayType(flags) = kAudioUnitParameterFlag_DisplaySquareRoot
3650 end;
3651
AudioUnitDisplayTypeIsSquarednull3652 function AudioUnitDisplayTypeIsSquared(flags : UInt32) : Boolean; inline;
3653 begin
3654 AudioUnitDisplayTypeIsSquared := GetAudioUnitParameterDisplayType(flags) = kAudioUnitParameterFlag_DisplaySquared
3655 end;
3656
AudioUnitDisplayTypeIsCubednull3657 function AudioUnitDisplayTypeIsCubed(flags : UInt32) : Boolean; inline;
3658 begin
3659 AudioUnitDisplayTypeIsCubed := GetAudioUnitParameterDisplayType(flags) = kAudioUnitParameterFlag_DisplayCubed
3660 end;
3661
AudioUnitDisplayTypeIsCubeRootnull3662 function AudioUnitDisplayTypeIsCubeRoot(flags : UInt32) : Boolean; inline;
3663 begin
3664 AudioUnitDisplayTypeIsCubeRoot := GetAudioUnitParameterDisplayType(flags) = kAudioUnitParameterFlag_DisplayCubeRoot
3665 end;
3666
AudioUnitDisplayTypeIsExponentialnull3667 function AudioUnitDisplayTypeIsExponential(flags : UInt32) : Boolean; inline;
3668 begin
3669 AudioUnitDisplayTypeIsExponential := GetAudioUnitParameterDisplayType(flags) = kAudioUnitParameterFlag_DisplayExponential
3670 end;
3671
3672 procedure SetAudioUnitParameterDisplayType(var flags : UInt32; displayType : UInt32); inline;
3673 begin
3674 flags := (flags and (not kAudioUnitParameterFlag_DisplayMask)) or displayType
3675 end;
3676
3677 end.
3678
3679 {$endc} {not MACOSALLINCLUDE}
3680