1 {!
2 @file AudioQueue.h
3 @framework AudioToolbox.framework
4 @copyright (c) 2006-2015 by Apple, Inc., all rights reserved.
5 @abstract API's to record and play audio buffers.
6
7 @discussion
8
9 Audio queues are software objects you use for recording or playing audio in Mac OS X. Audio
10 queues perform the following tasks:
11
12 - Connect to audio hardware
13 - Manage audio data buffers
14 - Employ codecs, as necessary, for compressed audio formats
15 - Mediate playback or recording
16
17 Audio queues can record and play audio in linear PCM, in compressed formats (such as Apple
18 Lossless, AAC, and MP3), and in other formats for which users have installed codecs. The API set
19 includes high-level support for the use of hardware recording and playback devices, and lets you
20 use sophisticated codecs without knowledge of how they work.
21
22 Additional advanced features support scheduled playback and synchronization of multiple audio
23 queues and synchronization of audio with video.
24 }
25 { Pascal Translation: Jonas Maebe <jonas@freepascal.org>, July 2019 }
26 {
27 Modified for use with Free Pascal
28 Version 308
29 Please report any bugs to <gpc@microbizz.nl>
30 }
31
32 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
33 {$mode macpas}
34 {$modeswitch cblocks}
35 {$packenum 1}
36 {$macro on}
37 {$inline on}
38 {$calling mwpascal}
39
40 unit AudioQueue;
41 interface
42 {$setc UNIVERSAL_INTERFACES_VERSION := $0400}
43 {$setc GAP_INTERFACES_VERSION := $0308}
44
45 {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
46 {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
47 {$endc}
48
49 {$ifc defined CPUPOWERPC and defined CPUI386}
50 {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
51 {$endc}
52 {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
53 {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
54 {$endc}
55
56 {$ifc not defined __ppc__ and defined CPUPOWERPC32}
57 {$setc __ppc__ := 1}
58 {$elsec}
59 {$setc __ppc__ := 0}
60 {$endc}
61 {$ifc not defined __ppc64__ and defined CPUPOWERPC64}
62 {$setc __ppc64__ := 1}
63 {$elsec}
64 {$setc __ppc64__ := 0}
65 {$endc}
66 {$ifc not defined __i386__ and defined CPUI386}
67 {$setc __i386__ := 1}
68 {$elsec}
69 {$setc __i386__ := 0}
70 {$endc}
71 {$ifc not defined __x86_64__ and defined CPUX86_64}
72 {$setc __x86_64__ := 1}
73 {$elsec}
74 {$setc __x86_64__ := 0}
75 {$endc}
76 {$ifc not defined __arm__ and defined CPUARM}
77 {$setc __arm__ := 1}
78 {$elsec}
79 {$setc __arm__ := 0}
80 {$endc}
81 {$ifc not defined __arm64__ and defined CPUAARCH64}
82 {$setc __arm64__ := 1}
83 {$elsec}
84 {$setc __arm64__ := 0}
85 {$endc}
86
87 {$ifc defined cpu64}
88 {$setc __LP64__ := 1}
89 {$elsec}
90 {$setc __LP64__ := 0}
91 {$endc}
92
93
94 {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
95 {$error Conflicting definitions for __ppc__ and __i386__}
96 {$endc}
97
98 {$ifc defined __ppc__ and __ppc__}
99 {$setc TARGET_CPU_PPC := TRUE}
100 {$setc TARGET_CPU_PPC64 := FALSE}
101 {$setc TARGET_CPU_X86 := FALSE}
102 {$setc TARGET_CPU_X86_64 := FALSE}
103 {$setc TARGET_CPU_ARM := FALSE}
104 {$setc TARGET_CPU_ARM64 := FALSE}
105 {$setc TARGET_OS_MAC := TRUE}
106 {$setc TARGET_OS_IPHONE := FALSE}
107 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
108 {$setc TARGET_OS_EMBEDDED := FALSE}
109 {$elifc defined __ppc64__ and __ppc64__}
110 {$setc TARGET_CPU_PPC := FALSE}
111 {$setc TARGET_CPU_PPC64 := TRUE}
112 {$setc TARGET_CPU_X86 := FALSE}
113 {$setc TARGET_CPU_X86_64 := FALSE}
114 {$setc TARGET_CPU_ARM := FALSE}
115 {$setc TARGET_CPU_ARM64 := FALSE}
116 {$setc TARGET_OS_MAC := TRUE}
117 {$setc TARGET_OS_IPHONE := FALSE}
118 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
119 {$setc TARGET_OS_EMBEDDED := FALSE}
120 {$elifc defined __i386__ and __i386__}
121 {$setc TARGET_CPU_PPC := FALSE}
122 {$setc TARGET_CPU_PPC64 := FALSE}
123 {$setc TARGET_CPU_X86 := TRUE}
124 {$setc TARGET_CPU_X86_64 := FALSE}
125 {$setc TARGET_CPU_ARM := FALSE}
126 {$setc TARGET_CPU_ARM64 := FALSE}
127 {$ifc defined iphonesim}
128 {$setc TARGET_OS_MAC := FALSE}
129 {$setc TARGET_OS_IPHONE := TRUE}
130 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
131 {$elsec}
132 {$setc TARGET_OS_MAC := TRUE}
133 {$setc TARGET_OS_IPHONE := FALSE}
134 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
135 {$endc}
136 {$setc TARGET_OS_EMBEDDED := FALSE}
137 {$elifc defined __x86_64__ and __x86_64__}
138 {$setc TARGET_CPU_PPC := FALSE}
139 {$setc TARGET_CPU_PPC64 := FALSE}
140 {$setc TARGET_CPU_X86 := FALSE}
141 {$setc TARGET_CPU_X86_64 := TRUE}
142 {$setc TARGET_CPU_ARM := FALSE}
143 {$setc TARGET_CPU_ARM64 := FALSE}
144 {$ifc defined iphonesim}
145 {$setc TARGET_OS_MAC := FALSE}
146 {$setc TARGET_OS_IPHONE := TRUE}
147 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
148 {$elsec}
149 {$setc TARGET_OS_MAC := TRUE}
150 {$setc TARGET_OS_IPHONE := FALSE}
151 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
152 {$endc}
153 {$setc TARGET_OS_EMBEDDED := FALSE}
154 {$elifc defined __arm__ and __arm__}
155 {$setc TARGET_CPU_PPC := FALSE}
156 {$setc TARGET_CPU_PPC64 := FALSE}
157 {$setc TARGET_CPU_X86 := FALSE}
158 {$setc TARGET_CPU_X86_64 := FALSE}
159 {$setc TARGET_CPU_ARM := TRUE}
160 {$setc TARGET_CPU_ARM64 := FALSE}
161 {$setc TARGET_OS_MAC := FALSE}
162 {$setc TARGET_OS_IPHONE := TRUE}
163 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
164 {$setc TARGET_OS_EMBEDDED := TRUE}
165 {$elifc defined __arm64__ and __arm64__}
166 {$setc TARGET_CPU_PPC := FALSE}
167 {$setc TARGET_CPU_PPC64 := FALSE}
168 {$setc TARGET_CPU_X86 := FALSE}
169 {$setc TARGET_CPU_X86_64 := FALSE}
170 {$setc TARGET_CPU_ARM := FALSE}
171 {$setc TARGET_CPU_ARM64 := TRUE}
172 {$ifc defined ios}
173 {$setc TARGET_OS_MAC := FALSE}
174 {$setc TARGET_OS_IPHONE := TRUE}
175 {$setc TARGET_OS_EMBEDDED := TRUE}
176 {$elsec}
177 {$setc TARGET_OS_MAC := TRUE}
178 {$setc TARGET_OS_IPHONE := FALSE}
179 {$setc TARGET_OS_EMBEDDED := FALSE}
180 {$endc}
181 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
182 {$elsec}
183 {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ nor __arm64__ is defined.}
184 {$endc}
185
186 {$ifc defined __LP64__ and __LP64__ }
187 {$setc TARGET_CPU_64 := TRUE}
188 {$elsec}
189 {$setc TARGET_CPU_64 := FALSE}
190 {$endc}
191
192 {$ifc defined FPC_BIG_ENDIAN}
193 {$setc TARGET_RT_BIG_ENDIAN := TRUE}
194 {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
195 {$elifc defined FPC_LITTLE_ENDIAN}
196 {$setc TARGET_RT_BIG_ENDIAN := FALSE}
197 {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
198 {$elsec}
199 {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
200 {$endc}
201 {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
202 {$setc CALL_NOT_IN_CARBON := FALSE}
203 {$setc OLDROUTINENAMES := FALSE}
204 {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
205 {$setc OPAQUE_UPP_TYPES := TRUE}
206 {$setc OTCARBONAPPLICATION := TRUE}
207 {$setc OTKERNEL := FALSE}
208 {$setc PM_USE_SESSION_APIS := TRUE}
209 {$setc TARGET_API_MAC_CARBON := TRUE}
210 {$setc TARGET_API_MAC_OS8 := FALSE}
211 {$setc TARGET_API_MAC_OSX := TRUE}
212 {$setc TARGET_CARBON := TRUE}
213 {$setc TARGET_CPU_68K := FALSE}
214 {$setc TARGET_CPU_MIPS := FALSE}
215 {$setc TARGET_CPU_SPARC := FALSE}
216 {$setc TARGET_OS_UNIX := FALSE}
217 {$setc TARGET_OS_WIN32 := FALSE}
218 {$setc TARGET_RT_MAC_68881 := FALSE}
219 {$setc TARGET_RT_MAC_CFM := FALSE}
220 {$setc TARGET_RT_MAC_MACHO := TRUE}
221 {$setc TYPED_FUNCTION_POINTERS := TRUE}
222 {$setc TYPE_BOOL := FALSE}
223 {$setc TYPE_EXTENDED := FALSE}
224 {$setc TYPE_LONGLONG := TRUE}
225 uses MacTypes,CFBase,CFRunLoop,CoreAudioTypes,CoreFoundation;
226 {$endc} {not MACOSALLINCLUDE}
227
228 {$ALIGN POWER}
229
230
231 //CF_ASSUME_NONNULL_BEGIN
232
233
234 //#pragma mark -
235 //#pragma mark Constants
236
237
238 //#pragma mark -
239 //#pragma mark Types
240 //==================================================================================================
241 // TYPES
242 //==================================================================================================
243
244 {!
245 @typedef AudioQueuePropertyID
246 @abstract A value that uniquely identifies an audio queue property.
247 }
248 type
249 AudioQueuePropertyID = UInt32;
250 AudioQueuePropertyIDPtr = ^AudioQueuePropertyID;
251
252 {!
253 @typedef AudioQueueParameterID
254 @abstract A value that uniquely identifies an audio queue parameter.
255 }
256 type
257 AudioQueueParameterID = UInt32;
258 AudioQueueParameterIDPtr = ^AudioQueueParameterID;
259
260 {!
261 @typedef AudioQueueParameterID
262 @abstract A value for an audio queue parameter.
263 }
264 type
265 AudioQueueParameterValue = Float32;
266 AudioQueueParameterValuePtr = ^AudioQueueParameterValue;
267
268 {!
269 @typedef AudioQueueRef
270 @abstract Defines an opaque data type that represents an audio queue.
271 }
272 type
273 AudioQueueRef = ^OpaqueAudioQueue; { an opaque type }
274 OpaqueAudioQueue = record end;
275
276 {!
277 @typedef AudioQueueTimelineRef
278 @abstract Defines an opaque data type that represents an audio queue timeline.
279 @discussion
280 You can use this object to observe any overloads in the audio device associated with the
281 audio queue. A timeline object receives notifications of discontinuities in the audio
282 hardware's sample timeline--for instance, a period of silence when sound was expected.
283 Causes of discontinuities include changes in the device state or processing overloads.
284 See Technical Q & A: QA 1467 for a discussion of Core Audio overload warnings. These
285 warnings indicate you are taking too long to process audio data and the system has cut
286 you off. You query a timeline object by passing it as a parameter to
287 AudioQueueGetCurrentTime, which means a discontinuity has occurred.
288 }
289 type
290 OpaqueAudioQueueTimeline = record end;
291 AudioQueueTimelineRef = ^OpaqueAudioQueueTimeline; { an opaque type }
292 AudioQueueTimelineRefPtr = ^AudioQueueTimelineRef;
293
294
295 //==================================================================================================
296 // CONSTANTS
297 //==================================================================================================
298 {!
299 @enum Result Codes
300 @abstract The OSStatus result codes returned by Audio Queue functions.
301
302 @constant kAudioQueueErr_InvalidBuffer The specified buffer does not belong to the
303 audio queue.
304 @constant kAudioQueueErr_BufferEmpty The buffer is empty (that is, the
305 mAudioDataByteSize field = 0).
306 @constant kAudioQueueErr_DisposalPending The function cannot act on the audio queue
307 because it is being asynchronously disposed of.
308 @constant kAudioQueueErr_InvalidProperty The specified property ID is invalid.
309 @constant kAudioQueueErr_InvalidPropertySize The size of the specified property is invalid.
310 @constant kAudioQueueErr_InvalidParameter The specified parameter ID is invalid.
311 @constant kAudioQueueErr_CannotStart The audio queue has encountered a problem and
312 cannot start.
313 @constant kAudioQueueErr_InvalidDevice The device assigned to the queue could not
314 be located, or is not properly configured.
315 @constant kAudioQueueErr_BufferInQueue The buffer cannot be disposed of when it is
316 enqueued.
317 @constant kAudioQueueErr_InvalidRunState The queue is running but the function can
318 only operate on the queue when it is stopped,
319 or vice versa.
320 @constant kAudioQueueErr_InvalidQueueType The queue is an input queue but the function can
321 only operate on an output queue, or vice versa.
322 @constant kAudioQueueErr_Permissions You do not have the required permissions to call
323 the function
324 @constant kAudioQueueErr_InvalidPropertyValue The specified property value is invalid.
325 @constant kAudioQueueErr_PrimeTimedOut During Prime, the queue's AudioConverter failed to
326 convert the requested number of sample frames.
327 @constant kAudioQueueErr_CodecNotFound The required audio codec was not found.
328 @constant kAudioQueueErr_InvalidCodecAccess Access to the required codec is not permitted
329 (possibly due to incompatible AudioSession
330 settings on iPhoneOS).
331 @constant kAudioQueueErr_QueueInvalidated On iPhoneOS, the audio server has exited, causing
332 this audio queue to have become invalid.
333 @constant kAudioQueueErr_TooManyTaps There can only be one processing tap per
334 audio queue.
335 @constant kAudioQueueErr_InvalidTapContext GetTapSourceAudio can only be called from the
336 tap's callback.
337 @constant kAudioQueueErr_InvalidTapType GetTapQueueTime can only be called on an output queue's
338 tap.
339 @constant kAudioQueueErr_RecordUnderrun During recording, data was lost because there
340 was no enqueued buffer into which to store it.
341 @constant kAudioQueueErr_BufferEnqueuedTwice A buffer was enqueued twice on an input queue
342 (before being returned as a result of being filled
343 or from Reset).
344 @constant kAudioQueueErr_CannotStartYet Starting the audio queue failed because an internal
345 reconfiguration (typically initiated by a hardware
346 stream format or sample rate change) was in progress.
347 Sleeping briefly and retrying is recommended.
348 @constant kAudioQueueErr_EnqueueDuringReset During Reset, Stop, or Dispose, it is not
349 permitted to enqueue buffers.
350 @constant kAudioQueueErr_InvalidOfflineMode The operation requires the queue to be in
351 offline mode but it isn't, or vice versa.
352 (Offline mode is entered and exited via
353 AudioQueueSetOfflineRenderFormat).
354 }
355 const
356 kAudioQueueErr_InvalidBuffer = -66687;
357 kAudioQueueErr_BufferEmpty = -66686;
358 kAudioQueueErr_DisposalPending = -66685;
359 kAudioQueueErr_InvalidProperty = -66684;
360 kAudioQueueErr_InvalidPropertySize = -66683;
361 kAudioQueueErr_InvalidParameter = -66682;
362 kAudioQueueErr_CannotStart = -66681;
363 kAudioQueueErr_InvalidDevice = -66680;
364 kAudioQueueErr_BufferInQueue = -66679;
365 kAudioQueueErr_InvalidRunState = -66678;
366 kAudioQueueErr_InvalidQueueType = -66677;
367 kAudioQueueErr_Permissions = -66676;
368 kAudioQueueErr_InvalidPropertyValue = -66675;
369 kAudioQueueErr_PrimeTimedOut = -66674;
370 kAudioQueueErr_CodecNotFound = -66673;
371 kAudioQueueErr_InvalidCodecAccess = -66672;
372 kAudioQueueErr_QueueInvalidated = -66671;
373 kAudioQueueErr_TooManyTaps = -66670;
374 kAudioQueueErr_InvalidTapContext = -66669;
375 kAudioQueueErr_RecordUnderrun = -66668;
376 kAudioQueueErr_InvalidTapType = -66667;
377 kAudioQueueErr_BufferEnqueuedTwice = -66666;
378 kAudioQueueErr_CannotStartYet = -66665;
379 kAudioQueueErr_EnqueueDuringReset = -66632;
380 kAudioQueueErr_InvalidOfflineMode = -66626;
381
382
383 {!
384 @enum Audio Queue Property IDs
385 @abstract Constants that identify properties for audio queues.
386 @discussion
387 @constant kAudioQueueProperty_IsRunning
388 A read-only property whose value is a UInt32 that indicates whether or not the queue is
389 running. A notification is sent when the audio device starts or stops, which is not
390 necessarily when the start or stop function is called.
391 @constant kAudioQueueDeviceProperty_SampleRate
392 A read-only property whose value is a Float64 that indicates the sampling rate of the
393 associated audio device.
394 @constant kAudioQueueDeviceProperty_NumberChannels
395 A read-only property whose value is a UInt32 that indicates the number of channels in
396 the associated audio device.
397 @constant kAudioQueueProperty_CurrentDevice
398 A read/write property whose value is a CFStringRef that contains the unique identifier
399 (UID) of the associated audio device.
400 If the audio queue is tracking the default system device and the device changes, it will
401 generate a property changed notification for this property. You can then query the HAL
402 for info on the new default system device.
403 @constant kAudioQueueProperty_MagicCookie
404 A read/write property whose value is an audio format magic cookie. If the audio format
405 requires a magic cookie, you must set this property before enqueuing any buffers.
406 @constant kAudioQueueProperty_MaximumOutputPacketSize
407 A read-only UInt32 that indicates the size in bytes of the largest single packet of
408 data in the output format. This is mostly useful for recording/encoding variable bit rate
409 compressed data.
410 @constant kAudioQueueProperty_StreamDescription
411 A read-only AudioStreamBasicDescription that indicates the queue's recording format.
412 This is useful when recording, where you may specify a sample rate of 0 during
413 construction,
414 @constant kAudioQueueProperty_ChannelLayout
415 A read/write property whose value is an audio channel layout structure that describes
416 the audio queue's channel layout. The number of channels must match the format of the
417 queue. If more than two channels (for instance, a five-channel surround sound) exist in
418 the queue, there may be a need to specify a channel layout. This layout indicates the
419 specific order in which the channels do appear, such as left, then center, then right.
420 @constant kAudioQueueProperty_EnableLevelMetering
421 A read-write property whose value is a UInt32 that indicates whether metering of
422 audio levels is enabled for the audio queue. (0=off, 1=on).
423 @constant kAudioQueueProperty_CurrentLevelMeter
424 A read-only property whose value is an array of AudioQueueLevelMeter structures, one
425 array element per audio channel. The values in the AudioQueueLevelMeters are in the
426 range 0-1.
427 @constant kAudioQueueProperty_CurrentLevelMeterDB
428 A read-only property whose value is an array of AudioQueueLevelMeter structures, one
429 array element per audio channel. The values in the AudioQueueLevelMeters are in
430 decibels.
431 @constant kAudioQueueProperty_DecodeBufferSizeFrames
432 A read/write property whose value is a UInt32 that is the size of the buffer into which
433 an output audio queue decodes buffers. A large buffer provides more reliability and
434 better long-term performance at the expense of memory and decreased responsiveness
435 in some situations.
436 @constant kAudioQueueProperty_ConverterError
437 A read-only property whose value is a UInt32 indicating the most recent error (if any)
438 encountered by the queue's internal encoding/decoding process.
439 @constant kAudioQueueProperty_EnableTimePitch
440 A read/write property whose value is a UInt32 describing whether there is a time/pitch unit
441 inserted into the queue's audio signal chain. This property may only be set while
442 the queue is stopped.
443 @constant kAudioQueueProperty_TimePitchAlgorithm
444 A read/write property whose value is a UInt32 describing the time/pitch algorithm in use.
445 This property is only valid while a time/pitch has been inserted, and may only be changed
446 when the queue is not running.
447 @constant kAudioQueueProperty_TimePitchBypass
448 A read/write property whose value is a UInt32 describing whether the time/pitch unit
449 has been bypassed (1=bypassed, 0=not bypassed).
450 }
451 const
452 kAudioQueueProperty_IsRunning = FourCharCode('aqrn'); // value is UInt32
453
454 kAudioQueueDeviceProperty_SampleRate = FourCharCode('aqsr'); // value is Float64
455 kAudioQueueDeviceProperty_NumberChannels = FourCharCode('aqdc'); // value is UInt32
456 kAudioQueueProperty_CurrentDevice = FourCharCode('aqcd'); // value is CFStringRef
457
458 kAudioQueueProperty_MagicCookie = FourCharCode('aqmc'); // value is void*
459 kAudioQueueProperty_MaximumOutputPacketSize = FourCharCode('xops'); // value is UInt32
460 kAudioQueueProperty_StreamDescription = FourCharCode('aqft'); // value is AudioStreamBasicDescription
461
462 kAudioQueueProperty_ChannelLayout = FourCharCode('aqcl'); // value is AudioChannelLayout
463 kAudioQueueProperty_EnableLevelMetering = FourCharCode('aqme'); // value is UInt32
464 kAudioQueueProperty_CurrentLevelMeter = FourCharCode('aqmv'); // value is array of AudioQueueLevelMeterState, 1 per channel
465 kAudioQueueProperty_CurrentLevelMeterDB = FourCharCode('aqmd'); // value is array of AudioQueueLevelMeterState, 1 per channel
466
467 kAudioQueueProperty_DecodeBufferSizeFrames = FourCharCode('dcbf'); // value is UInt32
468 kAudioQueueProperty_ConverterError = FourCharCode('qcve'); // value is UInt32
469
470 kAudioQueueProperty_EnableTimePitch = FourCharCode('q_tp'); // value is UInt32, 0/1
471 kAudioQueueProperty_TimePitchAlgorithm = FourCharCode('qtpa'); // value is UInt32. See values below.
472 kAudioQueueProperty_TimePitchBypass = FourCharCode('qtpb'); // value is UInt32, 1=bypassed
473
474 {!
475 @enum Time/Pitch algorithms
476 @abstract Constants that identify values of kAudioQueueProperty_TimePitchAlgorithm
477
478 @constant kAudioQueueTimePitchAlgorithm_Spectral
479 Highest quality, most computationally expensive. Suitable for music.
480 Default algorithm on OS X.
481 @constant kAudioQueueTimePitchAlgorithm_TimeDomain
482 Modest quality, less expensive. Suitable for voice.
483 @constant kAudioQueueTimePitchAlgorithm_Varispeed
484 High quality, but pitch varies with rate.
485 }
486 const
487 kAudioQueueTimePitchAlgorithm_Spectral = FourCharCode('spec');
488 kAudioQueueTimePitchAlgorithm_TimeDomain = FourCharCode('tido');
489 kAudioQueueTimePitchAlgorithm_Varispeed = FourCharCode('vspd');
490
491
492 {!
493 @enum AudioQueueParameterID
494 @abstract Constants that identify the parameters for audio queues.
495 @discussion
496 You can set a parameter in one of two ways:
497
498 <ul>
499 <li> Assign a parameter value to an audio queue to take effect immediately using
500 AudioQueueSetParameter.</li>
501 <li> Schedule a parameter to take effect when a buffer is enqueued. You supply the
502 parameter when you queue a buffer, and the new value of the parameter is applied
503 when that buffer is rendered.
504 </ul>
505
506 AudioQueueGetParameter always returns the current value of the parameter
507
508 @constant kAudioQueueParam_Volume
509 A value from 0.0 to 1.0 indicating the linearly scaled gain for the queue. A value of
510 1.0 (the default) indicates unity gain. A value of 0.0 indicates zero gain, or silence.
511 @constant kAudioQueueParam_PlayRate
512 A value from 0.5 to 2.0 indicating the rate at which the queue is to play. A value of
513 1.0 (the default) indicates that the queue should play at its normal rate. Only
514 applicable when the time/pitch processor has been enabled and on Mac OS X 10.6 and higher.
515 @constant kAudioQueueParam_Pitch
516 A value from -2400 to 2400 indicating the number of cents to pitch-shift the queue's
517 playback. (1200 cents is one octave.) Only applicable when the time/pitch processor has
518 been enabled with the spectral algorithm, and on Mac OS X 10.6 and higher.
519 @constant kAudioQueueParam_VolumeRampTime
520 A value indicating the number of seconds over which subsequent volume changes will be
521 ramped. For example, to fade out from full unity gain to silence over the course of 1
522 second, set kAudioQueueParam_VolumeRampTime to 1 then kAudioQueueParam_Volume to 0.
523 @constant kAudioQueueParam_Pan
524 A value from -1 to 1 indicating the pan position of a mono source (-1 = hard left, 0 =
525 center, 1 = hard right). For a stereo source this parameter affects left/right balance.
526 For multi-channel sources, this parameter has no effect.
527 }
528 const
529 kAudioQueueParam_Volume = 1;
530 kAudioQueueParam_PlayRate = 2;
531 kAudioQueueParam_Pitch = 3;
532 kAudioQueueParam_VolumeRampTime = 4;
533 kAudioQueueParam_Pan = 13;
534
535 {!
536 @enum AudioQueueProcessingTap flags
537 @abstract Flags used in conjunction with processing taps
538
539 @discussion
540 In the flags passed to AudioQueueProcessingTapNew, either the PreEffects
541 or PostEffects flag must be set, but not both.
542
543 @constant kAudioQueueProcessingTap_PreEffects
544 Signifies that the processing tap is inserted before any effects.
545 Passed to AudioQueueProcessingTapNew and to the callback.
546 @constant kAudioQueueProcessingTap_PostEffects
547 Signifies that the processing tap is inserted after any effects.
548 Passed to AudioQueueProcessingTapNew and to the callback.
549 @constant kAudioQueueProcessingTap_Siphon
550 Signifies that the processing tap is a siphon; it does not call
551 GetSourceAudio. The callback instead receives the source audio
552 and may not modify it. Passed to AudioQueueProcessingTapNew and to the callback.
553 @constant kAudioQueueProcessingTap_StartOfStream
554 Signifies that the source audio is the beginning of a continuous stream,
555 i.e. following the beginning or resumption of playback or recording.
556 Returned from GetSourceAudio.
557 @constant kAudioQueueProcessingTap_EndOfStream
558 Signifies that the source audio is past the end of stream. This happens when
559 the audio queue is being stopped asynchronously and has finished playing
560 all of its data. Returned from GetSourceAudio and should be propagated
561 on return from the callback.
562 }
563 type
564 AudioQueueProcessingTapFlags = UInt32;
565 AudioQueueProcessingTapFlagsPtr = ^AudioQueueProcessingTapFlags;
566 const
567 // these are flags that are passed to both the constructor and the callback
568 kAudioQueueProcessingTap_PreEffects = 1 shl 0; // 0x01
569 kAudioQueueProcessingTap_PostEffects = 1 shl 1; // 0x02
570 kAudioQueueProcessingTap_Siphon = 1 shl 2; // 0x04
571
572 // these are flags that are passed to the callback and from GetSourceAudio
573 kAudioQueueProcessingTap_StartOfStream = 1 shl 8; // 0x100
574 kAudioQueueProcessingTap_EndOfStream = 1 shl 9; // 0x200
575
576 //#pragma mark -
577 //#pragma mark Structs
578 //==================================================================================================
579 // STRUCTS
580 //==================================================================================================
581
582 {!
583 @struct AudioQueueBuffer
584 @abstract Defines a buffer of audio data to be managed by an audio queue.
585 @discussion
586 Each audio queue has an associated set of audio queue buffers. You can request that a
587 queue allocate buffers using the AudioQueueAllocateBuffer function and dispose of them
588 using the AudioQueueFreeBuffer function.
589
590 You may also use AudioQueueAllocateBufferWithPacketDescriptions to allocate buffers
591 with space for AudioPacketDescriptions, as used in VBR formats. The
592 mPacketDescriptionCapacity, mmPacketDescriptions, and mPacketDescriptionCount
593 fields may only be used with buffers allocated with this function.
594
595 @field mAudioDataBytesCapacity
596 The size of the buffer, in bytes. This size is set when the buffer is allocated and
597 cannot be changed.
598 @field mAudioData
599 A pointer to the audio data in the buffer. Although you can write data to this buffer,
600 you cannot make it point to another address.
601 @field mAudioDataByteSize
602 The number of bytes of valid audio data in the buffer. You set this value when providing
603 data for playback; the audio queue sets this value when recording data from a recording
604 queue.
605 @field mUserData
606 A value you may specify to identify the buffer when it is passed back in recording or
607 playback callback functions.
608 @field mPacketDescriptionCapacity
609 The maximum number of packet descriptions that can be stored in mPacketDescriptions.
610 @field mPacketDescriptions
611 An array of AudioStreamPacketDescriptions associated with the buffer.
612 @field mPacketDescriptionCount
613 The number of valid packet descriptions in the buffer. You set this value when providing
614 buffers for playback; the audio queue sets this value when returning buffers from
615 a recording queue.
616 }
617
618 type
619 AudioQueueBuffer = record
620 mAudioDataBytesCapacity: {const} UInt32;
621 mAudioData: UnivPtr {const};
622 mAudioDataByteSize: UInt32;
623 mUserData: UnivPtr {__nullable};
624
625 mPacketDescriptionCapacity: {const} UInt32;
626 mPacketDescriptions: AudioStreamPacketDescriptionPtr {const __nullable};
627 mPacketDescriptionCount: UInt32;
628 end;
629 AudioQueueBufferPtr = ^AudioQueueBuffer;
630
631 {!
632 @typedef AudioQueueBufferRef
633 @abstract An pointer to an AudioQueueBuffer.
634 }
635 type
636 AudioQueueBufferRef = AudioQueueBufferPtr;
637 AudioQueueBufferRefPtr = ^AudioQueueBufferRef;
638
639 {!
640 @struct AudioQueueParameterEvent
641 @abstract Specifies a value for an audio queue parameter.
642 @discussion
643 Two ways are available to supply an audio queue with parameters:
644
645 <ul>
646 <li> Provide one or more parameters by calling the
647 AudioQueueEnqueueBufferWithParameters function. In this case, the parameters are
648 applied to the specified buffer when it is played.</li>
649 <li> Assign a parameter value immediately to an audio queue by calling the
650 AudioQueueSetParameter function.</li>
651 </ul>
652
653 Note that the AudioQueueGetParameter function always returns the actual value of the
654 parameter.
655
656 In Mac OS X v10.5, audio queues have one parameter available: kAudioQueueParam_Volume,
657 which controls the queue's playback volume.
658
659 @field mID
660 The parameter.
661 @field mValue
662 The value of the specified parameter.
663 }
664 type
665 AudioQueueParameterEvent = record
666 mID: AudioQueueParameterID;
667 mValue: AudioQueueParameterValue;
668 end;
669 AudioQueueParameterEventPtr = ^AudioQueueParameterEvent;
670
671
672 {!
673 @struct AudioQueueLevelMeterState
674 @abstract Specifies the current level metering information for one channel of an audio queue.
675 @discussion
676 @field mAveragePower
677 The audio channel's average RMS power.
678 @field mPeakPower
679 The audio channel's peak RMS power
680 }
681 type
682 AudioQueueLevelMeterState = record
683 mAveragePower: Float32;
684 mPeakPower: Float32;
685 end;
686 AudioQueueLevelMeterStatePtr = ^AudioQueueLevelMeterState;
687
688 {!
689 @typedef AudioQueueProcessingTapRef
690 @abstract An object for intercepting and processing audio within an audio queue.
691 }
692 type
693 AudioQueueProcessingTapRef = ^OpaqueAudioQueueProcessingTap; { an opaque type }
694 OpaqueAudioQueueProcessingTap = record end;
695
696
697 //#pragma mark -
698 //#pragma mark Callbacks
699 //==================================================================================================
700 // CALLBACKS
701 //==================================================================================================
702
703
704 {!
705 @typedef AudioQueueOutputCallback
706 @abstract Defines a pointer to a callback function that is called when a playback audio
707 queue has finished taking data from a buffer.
708
709 @discussion
710 A playback buffer callback is invoked when the audio queue has finished with the data to
711 be played and the buffer is available to your application for reuse. Your application
712 might want to immediately refill and re-enqueue the completed buffer at this time.
713 @param inUserData
714 The value specified by the inUserData parameter of the AudioQueueNewOutput function.
715 @param inAQ
716 The audio queue that invoked the callback.
717 @param inBuffer
718 The audio queue buffer made available by the audio queue.
719 }
720 type
721 AudioQueueOutputCallback = procedure( inUserData: UnivPtr {__nullable}; inAQ: AudioQueueRef; inBuffer: AudioQueueBufferRef );
722
723 {!
724 @typedef AudioQueueInputCallback
725 @abstract Defines a pointer to a callback function that is called when a recording audio
726 queue has finished filling a buffer.
727 @discussion
728 You specify a recording buffer callback when calling AudioQueueNewInput. Your callback
729 is invoked each time the recording audio queue has filled a buffer with input data.
730 Typically, your callback should write the audio queue buffer's data to a file or other
731 buffer, and then re-queue the audio queue buffer to receive more data.
732
733 @param inUserData
734 The value you've specified in the inUserData parameter of the AudioQueueNewInput
735 function.
736 @param inAQ
737 The audio queue that invoked the callback.
738 @param inBuffer
739 An audio queue buffer, newly filled by the audio queue, containing the new audio data
740 your callback needs to write.
741 @param inStartTime
742 A pointer to an audio time stamp structure corresponding to the first sample contained
743 in the buffer. This contains the sample time of the first sample in the buffer.
744 @param inNumberPacketDescriptions
745 The number of audio packets contained in the data provided to the callback
746 @param inPacketDescs
747 For compressed formats which require packet descriptions, the packet descriptions
748 produced by the encoder for the incoming buffer.
749 }
750 type
751 AudioQueueInputCallback = procedure( inUserData: UnivPtr {__nullable}; inAQ: AudioQueueRef; inBuffer: AudioQueueBufferRef; const (*var*) inStartTime: AudioTimeStamp; inNumberPacketDescriptions: UInt32; {const} inPacketDescs: AudioStreamPacketDescriptionPtr {* __nullable} );
752
753
754 {!
755 @typedef AudioQueuePropertyListenerProc
756 @abstract Defines a pointer to a callback function that is called when a specified
757 property changes value.
758 @discussion
759 You assign a property listener callback when calling AudioQueueAddPropertyListener.
760
761 @param inUserData
762 A pointer to the data specified by the inUserData parameter of the
763 AudioQueueAddPropertyListener function.
764 @param inAQ
765 The audio queue that invoked the callback.
766 @param inID
767 The ID of the property that invoked the callback.
768 }
769 type
770 AudioQueuePropertyListenerProc = procedure( inUserData: UnivPtr {__nullable}; inAQ: AudioQueueRef; inID: AudioQueuePropertyID );
771
772 {!
773 @typedef AudioQueueProcessingTapCallback
774 @abstract A function called when an audio queue has data to be processed by its tap
775
776 @discussion
777 A processing callback is invoked when the audio queue has data that can be processed by a given
778 tap.
779
780 The audio queue will call the processing callback when it has sufficient data to provide for
781 processing.
782
783 In the case of a siphoning tap, the callback function can inspect the audio data in ioData, but
784 should not otherwise modify it. The callback should not call
785 AudioQueueProcessingTapGetSourceAudio.
786
787 A non-siphoning callback should call AudioQueueProcessingTapGetSourceAudio to request from the
788 queue as much source data as it needs in order to produce the requested number of output
789 samples. When the callback requests source data it may receive less data than it requests.
790
791 In the case of a tap on an audio output queue, the tap must emit the exact number of sample
792 frames that the queue requests. In normal circumstances, the tap's requests for source data will
793 be satisfied (as the client running the audio queue is also providing the queue with the audio
794 source material). If there is insufficient source data available (this is indicated by the
795 outNumberFrames from the GetSource call), then the processing tap should deal as best as it can;
796 it can either return less data than was requested or insert silence, noise, etc. itself. If it
797 returns less data than requested, the hosting audio queue will fill in the remainder with
798 silence.
799
800 In the case of a tap on an audio input queue, the tap may provide back less audio data than is
801 being requested. Typically this will occur because the tap will ask for source data that is not
802 available at this time (the audio input hasn't arrived yet), so the tap should cache the source
803 data that it needs and return as many processed samples as it can. If the processing tap falls
804 behind and is not providing data quickly enough silence will be generated in the data provided
805 to the client (and there is no signal about this either).
806
807 A processing tap executes in a semi-real-time context, so the general limitations for real-time
808 processing apply. Avoid using API's which may block. In particular, it is not safe to call the
809 audio queue on which the tap was installed, with the exceptions of
810 AudioQueueProcessingTapGetSourceAudio and AudioQueueProcessingTapGetQueueTime.
811
812 In normal operation the source data will be continuous from the last time the callback was
813 called and the processed samples should be continuous from the previous samples returned. If
814 there is any discontinuity between the last samples provided for processing the audio queue will
815 set the bit for kAudioQueueProcessing_StartOfStream in the inFlags. After a discontinuity the
816 first sample that the processing tap outputs should correspond to the first sample that was
817 provided in the source samples (so a reset and then consequent process serves to re-anchor a
818 relationship between the processing tap's source and processed samples). In this case the
819 processing tap will typically discard any previous state (for instance, if a processing tap was
820 adding a reverb to a signal, then the discontinuity flag would act the same as AudioUnitReset;
821 any previous source information in the processing tap should be discarded).
822
823 The caller is responsible for absorbing any processing delays. For example, if the processing is
824 to be done by an audio unit that reports a processing latency, then the caller should remove
825 those latency samples from the audio unit's rendering and not return them to the audio queue.
826
827 The processing tap is able to operate on the provided source data in place (that is, it can do
828 "in place processing") and return pointers to that buffer rather than its own. This works in a
829 similar way as AudioUnit render operations.
830
831 When an output audio queue is being stopped asynchronously, the processing tap will see the
832 kAudioQueueProcessingTap_EndOfStream bit set on return from GetSourceAudio, and is responsible
833 for propagating this bit from the callback when its processing has reached this point.
834
835 A processing tap will NEVER see the same source data again, so, it should keep its own copy if
836 it needs to keep it for further reference past the duration of this call. It also cannot assume
837 that the pointers to the source data that it retrieves will remain valid AFTER the processing
838 tap has executed.
839
840 The processing tap should ensure that the data pointers it provides in outProcessedData remain
841 valid until the tap is executed again.
842
843 A processing tap is destroyed implicitly when its audio queue is disposed. It may also be
844 removed explicitly, via AudioQueueProcessingTapDispose.
845
846 @param inClientData
847 the client data pointer passed to AudioQueueProcessingTapNew
848 @param inAQ
849 The audio queue that invoked the callback.
850 @param inAQTap
851 The tap for this callback.
852 @param inNumberFrames
853 The requested number of sample frames to be rendered.
854 @param ioFlags
855 On entry, the flags passed at construction time are provided. On exit,
856 the start/end of stream flags should be set when appropriate.
857 @param ioAudioTimeStamp
858 On an input audio queue, the timestamp must be returned from this function.
859 On an output audio queue, the callback is provided a continuous timestamp.
860 @param outNumberFrames
861 The number of frames of audio data provided in the processed data. Can be 0.
862 @param ioData
863 For non-siphoning taps, on entry, the buffer pointers are null and the lengths
864 are zero. On exit, they should contain the tap's output.
865
866 Siphoning taps receive valid buffers which they must not alter.
867 }
868 type
869 AudioQueueProcessingTapCallback = procedure( inClientData: UnivPtr; inAQTap: AudioQueueProcessingTapRef; inNumberFrames: UInt32; var ioTimeStamp: AudioTimeStamp; var ioFlags: AudioQueueProcessingTapFlags; var outNumberFrames: UInt32; var ioData: AudioBufferList );
870
871 //==================================================================================================
872 // FUNCTIONS
873 //==================================================================================================
874
875 //#pragma /mark -
876 //#pragma /mark Creating/destroying queues
877 //=============================================================================
878 // Creating/destroying queues
879 //=============================================================================
880
881 {!
882 @function AudioQueueNewOutput
883 @abstract Creates a new audio queue for playing audio data.
884 @discussion
885 To create an playback audio queue, you allocate buffers, then queue buffers (using
886 AudioQueueEnqueueBuffer). The callback receives buffers and typically queues them again.
887 To schedule a buffer for playback, providing parameter and start time information, call
888 AudioQueueEnqueueBufferWithParameters.
889
890 @param inFormat
891 A pointer to a structure describing the format of the audio data to be played. For
892 linear PCM, only interleaved formats are supported. Compressed formats are supported.
893 @param inCallbackProc
894 A pointer to a callback function to be called when the audio queue has finished playing
895 a buffer.
896 @param inUserData
897 A value or pointer to data that you specify to be passed to the callback function.
898 @param inCallbackRunLoop
899 The event loop on which inCallbackProc is to be called. If you specify NULL, the
900 callback is called on one of the audio queue's internal threads.
901 @param inCallbackRunLoopMode
902 The run loop mode in which to call the callback. Typically, you pass
903 kCFRunLoopCommonModes. (NULL also specifies kCFRunLoopCommonModes). Other
904 possibilities are implementation specific. You can choose to create your own thread with
905 your own run loops. For more information on run loops, see Run Loops or CFRunLoop
906 Reference.
907 @param inFlags
908 Reserved for future use. Pass 0.
909 @param outAQ
910 On return, this variable contains a pointer to the newly created playback audio queue
911 object.
912 @result An OSStatus result code.
913 }
AudioQueueNewOutputnull914 function AudioQueueNewOutput( const (*var*) inFormat: AudioStreamBasicDescription; inCallbackProc: AudioQueueOutputCallback; inUserData: UnivPtr {__nullable}; inCallbackRunLoop: CFRunLoopRef {__nullable}; inCallbackRunLoopMode: CFStringRef {__nullable}; inFlags: UInt32; var outAQ: AudioQueueRef {__nullable * __nonnull} ): OSStatus; external name '_AudioQueueNewOutput';
915 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
916
917
918 {!
919 @function AudioQueueNewInput
920 @abstract Creates a new audio queue for recording audio data.
921 @discussion
922
923 Outline of how to use the queue for input:
924
925 - create input queue
926 - allocate buffers
927 - enqueue buffers (AudioQueueEnqueueBuffer, not with parameters, no packet descriptions)
928 - the callback receives buffers and re-enqueues them
929
930 @param inFormat
931 A pointer to a structure describing the format of the audio data to be recorded. For
932 linear PCM, only interleaved formats are supported. Compressed formats are supported.
933 @param inCallbackProc
934 A pointer to a callback function to be called when the audio queue has finished filling
935 a buffer.
936 @param inUserData
937 A value or pointer to data that you specify to be passed to the callback function.
938 @param inCallbackRunLoop
939 The event loop on which inCallbackProc is to be called. If you specify NULL, the
940 callback is called on one of the audio queue's internal threads.
941 @param inCallbackRunLoopMode
942 The run loop mode in which to call the callback. Typically, you pass
943 kCFRunLoopCommonModes. (NULL also specifies kCFRunLoopCommonModes). Other
944 possibilities are implementation specific. You can choose to create your own thread with
945 your own run loops. For more information on run loops, see Run Loops or CFRunLoop
946 Reference.
947 @param inFlags
948 Reserved for future use. Pass 0.
949 @param outAQ
950 On return, this variable contains a pointer to the newly created recording audio queue
951 object.
952 @result An OSStatus result code.
953 }
AudioQueueNewInputnull954 function AudioQueueNewInput( const (*var*) inFormat: AudioStreamBasicDescription; inCallbackProc: AudioQueueInputCallback; inUserData: UnivPtr {__nullable}; inCallbackRunLoop: CFRunLoopRef {__nullable}; inCallbackRunLoopMode: CFStringRef {__nullable}; inFlags: UInt32; var outAQ: AudioQueueRef {__nullable * __nonnull} ): OSStatus; external name '_AudioQueueNewInput';
955 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
956
957
958 {!
959 @function AudioQueueDispose
960 @abstract Disposes an existing audio queue.
961 @discussion
962 Disposing of the audio queue also disposes of all its resources, including its buffers.
963 @param inAQ
964 The audio queue you want to dispose of
965 @param inImmediate
966 If you pass true, the audio queue is disposed of immediately (that is, synchronously).
967 If you pass false, disposal does not take place until all enqueued buffers are
968 processed. Whether you call AudioQueueDispose synchronously or asynchronously, you can
969 no longer interact with the queue, and the queue no longer invokes any callbacks to your
970 application after the function returns.
971
972 Note that if AudioQueueDispose is called from a buffer completion callback or property
973 listener, you may receive further callbacks afterwards.
974 @result An OSStatus result code.
975 }
AudioQueueDisposenull976 function AudioQueueDispose( inAQ: AudioQueueRef; inImmediate: Boolean ): OSStatus; external name '_AudioQueueDispose';
977 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
978
979 //#pragma /mark -
980 //#pragma /mark Buffer Management
981 //=============================================================================
982 // Buffer Management
983 //=============================================================================
984
985 {!
986 @function AudioQueueAllocateBuffer
987 @abstract Asks an audio queue to allocate a buffer.
988 @discussion
989 Once allocated, the pointer to the buffer and the buffer's size are fixed and cannot be
990 changed. The mAudioDataByteSize field in the audio queue buffer structure,
991 AudioQueueBuffer, is initially set to 0.
992
993 @param inAQ
994 The audio queue you want to allocate a buffer.
995 @param inBufferByteSize
996 The desired size of the new buffer, in bytes. An appropriate buffer size depends on the
997 processing you will perform on the data as well as on the audio data format.
998 @param outBuffer
999 On return, points to the newly created audio buffer. The mAudioDataByteSize field in the
1000 audio queue buffer structure, AudioQueueBuffer, is initially set to 0.
1001 @result An OSStatus result code.
1002 }
AudioQueueAllocateBuffernull1003 function AudioQueueAllocateBuffer( inAQ: AudioQueueRef; inBufferByteSize: UInt32; var outBuffer: AudioQueueBufferRef {__nullable * __nonnull} ): OSStatus; external name '_AudioQueueAllocateBuffer';
1004 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1005
1006 {!
1007 @function AudioQueueAllocateBufferWithPacketDescriptions
1008 @abstract Asks an audio queue to allocate a buffer with space for packet descriptions.
1009 @discussion
1010 Once allocated, the pointer to the buffer and the buffer's size are fixed and cannot be
1011 changed. The mAudioDataByteSize field in the audio queue buffer structure,
1012 AudioQueueBuffer, is initially set to 0.
1013
1014 @param inAQ
1015 The audio queue you want to allocate a buffer.
1016 @param inBufferByteSize
1017 The desired size of the new buffer, in bytes. An appropriate buffer size depends on the
1018 processing you will perform on the data as well as on the audio data format.
1019 @param inNumberPacketDescriptions
1020 The desired capacity of the packet description array in the new buffer.
1021 @param outBuffer
1022 On return, points to the newly created audio buffer. The mAudioDataByteSize field in the
1023 audio queue buffer structure, AudioQueueBuffer, is initially set to 0.
1024 @result An OSStatus result code.
1025 }
AudioQueueAllocateBufferWithPacketDescriptionsnull1026 function AudioQueueAllocateBufferWithPacketDescriptions( inAQ: AudioQueueRef; inBufferByteSize: UInt32; inNumberPacketDescriptions: UInt32; var outBuffer: AudioQueueBufferRef {__nullable * __nonnull} ): OSStatus; external name '_AudioQueueAllocateBufferWithPacketDescriptions';
1027 (* API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0)) *)
1028
1029 {!
1030 @function AudioQueueFreeBuffer
1031 @abstract Disposes of an audio queue buffer.
1032 @discussion
1033 This function disposes of the buffer allocated by AudioQueueAllocateBuffer. Disposing of
1034 an audio queue also automatically disposes of any associated buffers and timeline
1035 objects. Call this function only if you want to dispose of a particular buffer while
1036 continuing to use an audio queue. You can dispose of buffers only when the associated
1037 queue is stopped (that is, not processing audio data).
1038 @param inAQ
1039 The queue from which the buffer was allocated.
1040 @param inBuffer
1041 The buffer to be disposed.
1042 @result An OSStatus result code.
1043 }
AudioQueueFreeBuffernull1044 function AudioQueueFreeBuffer( inAQ: AudioQueueRef; inBuffer: AudioQueueBufferRef ): OSStatus; external name '_AudioQueueFreeBuffer';
1045 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1046
1047
1048 {!
1049 @function AudioQueueEnqueueBuffer
1050 @abstract Assigns a buffer to an audio queue for recording or playback.
1051 @discussion
1052 If the buffer was allocated with AudioQueueAllocateBufferWithPacketDescriptions,
1053 the client should provide packet descriptions in the buffer's mPacketDescriptions
1054 and mPacketDescriptionCount fields rather than in inPacketDescs and
1055 inNumPacketDescs, which should be NULL and 0, respectively, in this case.
1056
1057 For an input queue, pass 0 and NULL for inNumPacketDescs and inPacketDescs,
1058 respectively. Your callback will receive packet descriptions owned by the audio queue.
1059
1060 @param inAQ
1061 The audio queue you are assigning the buffer to.
1062 @param inBuffer
1063 The buffer to queue (that is, to be recorded into or played from).
1064 @param inNumPacketDescs
1065 The number of packet descriptions pointed to by the inPacketDescs pointer. Applicable
1066 only for output queues and required only for variable-bit-rate (VBR) audio formats. Pass
1067 0 for input queues (no packet descriptions are required).
1068 @param inPacketDescs
1069 An array of packet descriptions. Applicable only for output queues and required only for
1070 variable-bit-rate (VBR) audio formats. Pass NULL for input queues (no packet
1071 descriptions are required).
1072 @result An OSStatus result code.
1073 }
AudioQueueEnqueueBuffernull1074 function AudioQueueEnqueueBuffer( inAQ: AudioQueueRef; inBuffer: AudioQueueBufferRef; inNumPacketDescs: UInt32; {const} inPacketDescs: AudioStreamPacketDescriptionPtr {* __nullable} ): OSStatus; external name '_AudioQueueEnqueueBuffer';
1075 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1076
1077 {!
1078 @function AudioQueueEnqueueBufferWithParameters
1079 @abstract Assigns a buffer to an audio queue for playback, providing parameters
1080 and start time information.
1081 @discussion
1082 You can exert some control of the buffer queue by using this function. You can assign
1083 audio queue settings that are in effect carried by an audio queue buffer as you enqueue
1084 it. Hence, these changes only take effect when an audio queue buffer begins playing.
1085
1086 This function queues a buffer for playback only, not for recording. Audio queues for
1087 recording have no parameters, do not support variable-bit-rate (VBR) formats (which
1088 might require trimming), and have a different way to handle timing. When queued for
1089 playback, the buffer must contain the audio data to be played back. See
1090 AudioQueueEnqueueBuffer for details on queuing a buffer for recording.
1091
1092 If the buffer was allocated with AudioQueueAllocateBufferWithPacketDescriptions,
1093 the client should provide packet descriptions in the buffer's mPacketDescriptions
1094 and mPacketDescriptionCount fields rather than in inPacketDescs and
1095 inNumPacketDescs, which should be NULL and 0, respectively, in this case.
1096 @param inAQ
1097 The audio queue associated with the buffer.
1098 @param inBuffer
1099 The buffer to be played from.
1100 @param inNumPacketDescs
1101 The number of packet descriptions pointed to by the inPacketDescs parameter. Required
1102 only for variable-bit-rate (VBR) audio formats. Pass 0 if no packet descriptions are
1103 required.
1104 @param inPacketDescs
1105 A pointer to an array of audio stream packet descriptions. Required only for VBR audio
1106 formats. Pass NULL if no packet descriptions are required.
1107 @param inTrimFramesAtStart
1108 The number of priming frames to skip at the start of the buffer.
1109 @param inTrimFramesAtEnd
1110 The number of frames to skip at the end of the buffer.
1111 @param inNumParamValues
1112 The number of parameter values pointed to by the inParamValues parameter.
1113 @param inParamValues
1114 An array of parameter values. (In Mac OS X v10.5, there is only one parameter,
1115 kAudioQueueParam_Volume.) These values are set before buffer playback and cannot be
1116 changed while the buffer is playing. How accurately changes in parameters can be
1117 scheduled depends on the size of the buffer. If there are no parameters to set
1118 (inNumParamValues = 0), pass NULL.
1119 @param inStartTime
1120 A pointer to a structure containing the desired start time for playing the buffer. If
1121 you specify the time using the mSampleTime field of the AudioTimeStamp structure, the
1122 sample time is relative to the time the queue started. If you pass NULL for the start
1123 time, the buffer starts immediately after the previously queued buffer, or as soon as
1124 possible if no buffers are queued ahead of it. Buffers are played in the order they are
1125 queued. If multiple buffers are queued, their times must be in ascending order or NULL;
1126 otherwise, an error occurs. The start time indicates when the actual audio data in the
1127 buffer is to be played (that is, the trim frames are not counted).
1128
1129 Note: When specifying a start time for a buffer, if the buffer is not the first enqueued
1130 since AudioQueueStop or AudioQueueReset, it is normally necessary to call AudioQueueFlush
1131 before AudioQueueEnqueueBufferWithParameters.
1132 @param outActualStartTime
1133 On return, points to an AudioTimeStamp structure indicating when the buffer will
1134 actually play.
1135 @result An OSStatus result code.
1136 }
AudioQueueEnqueueBufferWithParametersnull1137 function AudioQueueEnqueueBufferWithParameters( inAQ: AudioQueueRef; inBuffer: AudioQueueBufferRef; inNumPacketDescs: UInt32; {const} inPacketDescs: AudioStreamPacketDescriptionPtr {* __nullable}; inTrimFramesAtStart: UInt32; inTrimFramesAtEnd: UInt32; inNumParamValues: UInt32; {const} inParamValues: AudioQueueParameterEventPtr {* __nullable}; {const} inStartTime: AudioTimeStampPtr {* __nullable}; outActualStartTime: AudioTimeStampPtr {* __nullable} ): OSStatus; external name '_AudioQueueEnqueueBufferWithParameters';
1138 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1139
1140 //#pragma /mark -
1141 //#pragma /mark Queue Control
1142 //=============================================================================
1143 // Queue Control
1144 //=============================================================================
1145
1146 {!
1147 @function AudioQueueStart
1148 @abstract Begins playing or recording audio.
1149 @discussion
1150 If the audio hardware is not already running, this function starts it.
1151 @param inAQ
1152 The audio queue to start.
1153 @param inStartTime
1154 A pointer to the time at which the audio queue should start. If you specify the time
1155 using the mSampleTime field of the AudioTimeStamp structure, the sample time is
1156 referenced to the sample frame timeline of the associated audio device. May be NULL.
1157 @result An OSStatus result code.
1158 }
AudioQueueStartnull1159 function AudioQueueStart( inAQ: AudioQueueRef; {const} inStartTime: AudioTimeStampPtr {* __nullable} ): OSStatus; external name '_AudioQueueStart';
1160 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1161
1162 {!
1163 @function AudioQueuePrime
1164 @abstract Begins decoding buffers in preparation for playback.
1165 @discussion
1166 This function begins decoding buffers in preparation for playback. It returns when at
1167 least the number of audio sample frames are decoded and ready to play or when all
1168 enqueued buffers have been completely decoded. To ensure that a buffer has been decoded
1169 and is completely ready for playback, before playback:
1170 1. Call AudioQueueEnqueueBuffer.
1171 2. Call AudioQueuePrime, which waits if you pass 0 to have a default number of
1172 frames decoded.
1173 3. Call AudioQueueStart.
1174
1175 Calls to AudioQueuePrime following AudioQueueStart/AudioQueuePrime, and before
1176 AudioQueueReset/AudioQueueStop, will have no useful effect. In this situation,
1177 outNumberOfFramesPrepared will not have a useful return value.
1178 @param inAQ
1179 The audio queue to be primed.
1180 @param inNumberOfFramesToPrepare
1181 The number of frames to decode before returning. Pass 0 to decode all enqueued buffers.
1182 @param outNumberOfFramesPrepared
1183 If not NULL, on return, a pointer to the number of frames actually decoded and prepared
1184 for playback.
1185 @result An OSStatus result code.
1186 }
AudioQueuePrimenull1187 function AudioQueuePrime( inAQ: AudioQueueRef; inNumberOfFramesToPrepare: UInt32; outNumberOfFramesPrepared: UInt32Ptr {* __nullable} ): OSStatus; external name '_AudioQueuePrime';
1188 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1189
1190 {!
1191 @function AudioQueueStop
1192 @abstract Stops playing or recording audio.
1193 @discussion
1194 This function resets the audio queue and stops the audio hardware associated with the
1195 queue if it is not in use by other audio services. Synchronous stops occur immediately,
1196 regardless of previously buffered audio data. Asynchronous stops occur after all queued
1197 buffers have been played or recorded.
1198 @param inAQ
1199 The audio queue to stop.
1200 @param inImmediate
1201 If you pass true, the stop request occurs immediately (that is, synchronously), and the
1202 function returns when the audio queue has stopped. Buffer callbacks are invoked during
1203 the stopping. If you pass false, the function returns immediately, but the queue does
1204 not stop until all its queued buffers are played or filled (that is, the stop occurs
1205 asynchronously). Buffer callbacks are invoked as necessary until the queue actually
1206 stops. Also, a playback audio queue callback calls this function when there is no more
1207 audio to play.
1208
1209 Note that when stopping immediately, all pending buffer callbacks are normally invoked
1210 during the process of stopping. But if the calling thread is responding to a buffer
1211 callback, then it is possible for additional buffer callbacks to occur after
1212 AudioQueueStop returns.
1213 @result An OSStatus result code.
1214 }
AudioQueueStopnull1215 function AudioQueueStop( inAQ: AudioQueueRef; inImmediate: Boolean ): OSStatus; external name '_AudioQueueStop';
1216 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1217
1218 {!
1219 @function AudioQueuePause
1220 @abstract Pauses audio playback or recording.
1221 @discussion
1222 Pausing the queue does not affect buffers or reset the audio queue. To resume playback
1223 or recording using the audio queue, call AudioQueueStart.
1224 @param inAQ
1225 The queue to be paused.
1226 @result An OSStatus result code.
1227 }
AudioQueuePausenull1228 function AudioQueuePause( inAQ: AudioQueueRef ): OSStatus; external name '_AudioQueuePause';
1229 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1230
1231 {!
1232 @function AudioQueueFlush
1233 @abstract Resets the audio queue's decoder state.
1234 @discussion
1235 After all queued buffers have been played, the function cleans up all decoder state
1236 information. You must call this function following a sequence of buffers of encoded
1237 audio; otherwise, some of the audio might not play in the next set of queued buffers.
1238 The only time it is not necessary to call AudioQueueFlush is following AudioQueueStop
1239 with inImmediate=false. (This action internally calls AudioQueueFlush.)
1240
1241 Also, you might wish to call this function before calling AudioQueueStop depending on
1242 whether you want to stop immediately regardless of what has played or whether you want
1243 to ensure that all buffered data and all data that is in the middle of processing gets
1244 recorded or played before stopping.
1245
1246 @param inAQ
1247 The audio queue to be flushed.
1248
1249 @result An OSStatus result code.
1250 }
AudioQueueFlushnull1251 function AudioQueueFlush( inAQ: AudioQueueRef ): OSStatus; external name '_AudioQueueFlush';
1252 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1253
1254 {!
1255 @function AudioQueueReset
1256 @abstract Resets an audio queue.
1257 @discussion
1258 This function immediately resets an audio queue, flushes any queued buffer, removes all
1259 buffers from previously scheduled use, and resets any decoder and digital signal
1260 processing (DSP) state information. It also invokes callbacks for any flushed buffers.
1261 If you queue any buffers after calling this function, processing does not occur until
1262 the decoder and DSP state information is reset. Hence, a discontinuity (that is, a
1263 "glitch") might occur.
1264
1265 Note that when resetting, all pending buffer callbacks are normally invoked
1266 during the process of resetting. But if the calling thread is responding to a buffer
1267 callback, then it is possible for additional buffer callbacks to occur after
1268 AudioQueueReset returns.
1269 @param inAQ
1270 The audio queue to reset.
1271
1272 @result An OSStatus result code.
1273 }
AudioQueueResetnull1274 function AudioQueueReset( inAQ: AudioQueueRef ): OSStatus; external name '_AudioQueueReset';
1275 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1276
1277 //#pragma /mark -
1278 //#pragma /mark Parameter Management
1279 //=============================================================================
1280 // Parameter Management
1281 //=============================================================================
1282
1283 {!
1284 @function AudioQueueGetParameter
1285 @abstract Obtains an audio queue parameter value.
1286 @discussion
1287 You can access the current parameter values for an audio queue at any time with this
1288 function.
1289 @param inAQ
1290 The audio queue whose parameter value you want to obtain.
1291 @param inParamID
1292 The ID of the parameter you want to obtain. In Mac OS X v10.5, audio queues have one
1293 parameter available: kAudioQueueParam_Volume, which controls the queue's playback
1294 volume.
1295 @param outValue
1296 On return, points to the current value of the specified parameter.
1297 @result
1298 An OSStatus result code.
1299 }
AudioQueueGetParameternull1300 function AudioQueueGetParameter( inAQ: AudioQueueRef; inParamID: AudioQueueParameterID; var outValue: AudioQueueParameterValue ): OSStatus; external name '_AudioQueueGetParameter';
1301 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1302
1303 {!
1304 @function AudioQueueSetParameter
1305 @abstract Sets an audio queue parameter value.
1306 @discussion
1307 @param inAQ
1308 The audio queue whose parameter value you want to set.
1309 @param inParamID
1310 The ID of the parameter you want to set.
1311 @param inValue
1312 The parameter value to set.
1313 @result
1314 An OSStatus result code.
1315 }
AudioQueueSetParameternull1316 function AudioQueueSetParameter( inAQ: AudioQueueRef; inParamID: AudioQueueParameterID; inValue: AudioQueueParameterValue ): OSStatus; external name '_AudioQueueSetParameter';
1317 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1318
1319
1320 //#pragma /mark -
1321 //#pragma /mark Property Management
1322 //=============================================================================
1323 // Property Management
1324 //=============================================================================
1325
1326 {!
1327 @function AudioQueueGetProperty
1328 @abstract Obtains an audio queue property value.
1329 @discussion
1330 @param inAQ
1331 The audio queue whose property value you want to obtain.
1332 @param inID
1333 The ID of the property you want to obtain. See "Audio Queue Property IDs."
1334 @param outData
1335 On return, points to the desired property value.
1336 @param ioDataSize
1337 A pointer to the size of the property data. On input, points to the maximum bytes of
1338 space the caller expects to receive. On return, points to the actual data size.
1339 @result
1340 An OSStatus result code.
1341 }
AudioQueueGetPropertynull1342 function AudioQueueGetProperty( inAQ: AudioQueueRef; inID: AudioQueuePropertyID; outData: UnivPtr; var ioDataSize: UInt32 ): OSStatus; external name '_AudioQueueGetProperty';
1343 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1344
1345 {!
1346 @function AudioQueueSetProperty
1347 @abstract Sets an audio queue property value.
1348 @discussion
1349 @param inAQ
1350 The audio queue whose property value you want to set.
1351 @param inID
1352 The ID of the property you want to set. See "Audio Queue Property IDs" for the various
1353 audio queue properties.
1354 @param inData
1355 A pointer to the property value to set.
1356 @param inDataSize
1357 The size of the property data.
1358 @result
1359 An OSStatus result code.
1360 }
AudioQueueSetPropertynull1361 function AudioQueueSetProperty( inAQ: AudioQueueRef; inID: AudioQueuePropertyID; inData: {const} UnivPtr; inDataSize: UInt32 ): OSStatus; external name '_AudioQueueSetProperty';
1362 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1363
1364
1365 {!
1366 @function AudioQueueGetPropertySize
1367 @abstract Obtains the size of an audio queue property.
1368 @discussion
1369 @param inAQ
1370 The audio queue containing the property value whose size you want to obtain.
1371 @param inID
1372 The ID of the property value whose size you want to obtain. See "Audio Queue Property
1373 IDs" for possible values.
1374 @param outDataSize
1375 On return, points to the size of the specified property value.
1376 @result
1377 An OSStatus result code.
1378 }
AudioQueueGetPropertySizenull1379 function AudioQueueGetPropertySize( inAQ: AudioQueueRef; inID: AudioQueuePropertyID; var outDataSize: UInt32 ): OSStatus; external name '_AudioQueueGetPropertySize';
1380 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1381
1382 {!
1383 @function AudioQueueAddPropertyListener
1384 @abstract Adds a listener callback for a property.
1385 @discussion
1386 This callback is used to act upon a change in an audio queue property such as
1387 kAudioQueueProperty_IsRunning. For instance, if your application has a user interface
1388 with a Play/Stop button, and kAudioQueueProperty_IsRunning changes, you need to update
1389 your button.
1390 @param inAQ
1391 The audio queue that owns the property you want to assign the listener callback to.
1392 @param inID
1393 The ID of the property to which you want to assign a listener callback. See "Audio Queue Property IDs".
1394 @param inProc
1395 The listener callback to be called when the property value changes.
1396 @param inUserData
1397 A value to be passed to the listener callback when it is called.
1398 @result
1399 An OSStatus result code.
1400 }
AudioQueueAddPropertyListenernull1401 function AudioQueueAddPropertyListener( inAQ: AudioQueueRef; inID: AudioQueuePropertyID; inProc: AudioQueuePropertyListenerProc; inUserData: UnivPtr {__nullable} ): OSStatus; external name '_AudioQueueAddPropertyListener';
1402 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1403
1404 {!
1405 @function AudioQueueRemovePropertyListener
1406 @abstract Removes a listener callback for a property.
1407 @discussion
1408 @param inAQ
1409 The audio queue that owns the property from which you want to remove a listener.
1410 @param inID
1411 The ID of the property from which you want to remove a listener.
1412 @param inProc
1413 The listener being removed.
1414 @param inUserData
1415 The same inUserData value that was previously passed to AudioQueueAddPropertyListener.
1416 @result
1417 An OSStatus result code.
1418 }
AudioQueueRemovePropertyListenernull1419 function AudioQueueRemovePropertyListener( inAQ: AudioQueueRef; inID: AudioQueuePropertyID; inProc: AudioQueuePropertyListenerProc; inUserData: UnivPtr {__nullable} ): OSStatus; external name '_AudioQueueRemovePropertyListener';
1420 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1421
1422
1423
1424 //#pragma /mark -
1425 //#pragma /mark Handling Timing
1426 //=============================================================================
1427 // Handling Timing
1428 //=============================================================================
1429
1430 {!
1431 @function AudioQueueCreateTimeline
1432 @abstract Creates a timeline object.
1433 @discussion
1434 You need to instantiate a timeline object if you want to know about any timeline
1435 discontinuities. See AudioQueueGetCurrentTime for more details.
1436 @param inAQ
1437 The audio queue to associate with the new timeline object.
1438 @param outTimeline
1439 On return, points to the newly created timeline object.
1440 @result
1441 An OSStatus result code.
1442 }
AudioQueueCreateTimelinenull1443 function AudioQueueCreateTimeline( inAQ: AudioQueueRef; var outTimeline: AudioQueueTimelineRef {__nullable * __nonnull} ): OSStatus; external name '_AudioQueueCreateTimeline';
1444 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1445
1446 {!
1447 @function AudioQueueDisposeTimeline
1448 @abstract Disposes of a timeline object.
1449 @discussion
1450 Disposing of an audio queue automatically disposes of any associated timeline objects.
1451 Call this function only if you want to dispose of a timeline object and not the audio
1452 queue associated with it.
1453 @param inAQ
1454 The audio queue associated with the timeline object you want to dispose of.
1455 @param inTimeline
1456 The timeline object to dispose of.
1457 @result
1458 An OSStatus result code.
1459 }
AudioQueueDisposeTimelinenull1460 function AudioQueueDisposeTimeline( inAQ: AudioQueueRef; inTimeline: AudioQueueTimelineRef ): OSStatus; external name '_AudioQueueDisposeTimeline';
1461 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1462
1463 {!
1464 @function AudioQueueGetCurrentTime
1465 @abstract Obtains the current audio queue time.
1466 @discussion
1467 You must specify a timeline object if you want to be notified about any timeline
1468 discontinuities in the outTimelineDiscontinuity parameter. If you don't care about
1469 discontinuities, pass NULL in the inTimeLine and outTimelineDiscontinuity parameters.
1470 @param inAQ
1471 The audio queue whose current time you want to obtain.
1472 @param inTimeline
1473 The audio queue timeline object to which any timeline discontinuities are reported. May
1474 be NULL.
1475 @param outTimeStamp
1476 On return, points to an audio timestamp structure containing the current audio queue
1477 time. The mSampleTime field is in terms of the audio queue's sample rate, and relative
1478 to the time at which the queue has started or will start.
1479 @param outTimelineDiscontinuity
1480 Can be NULL. On return, only set to true or false if the inTimeLine parameter is not
1481 NULL. Set to true if a discontinuity has occurred in the sample timeline of the audio
1482 queue. For instance, the device's sample rate changed and a gap occurred in playback or
1483 recording, or the audio queue was unable to prepare and playback in time because it was
1484 late.
1485 @result
1486 An OSStatus result code.
1487 }
AudioQueueGetCurrentTimenull1488 function AudioQueueGetCurrentTime( inAQ: AudioQueueRef; inTimeline: AudioQueueTimelineRefPtr {__nullable}; outTimeStamp: AudioTimeStampPtr {* __nullable}; outTimelineDiscontinuity: BooleanPtr {* __nullable} ): OSStatus; external name '_AudioQueueGetCurrentTime';
1489 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1490
1491 {!
1492 @function AudioQueueDeviceGetCurrentTime
1493 @abstract Obtains the current time of the audio device associated with an audio queue.
1494 @discussion
1495 If the audio device associated with the audio queue is not running, the only valid field
1496 in the audio timestamp structure is mHostTime. This result differentiates the action of
1497 this function from that of the AudioDeviceGetCurrentTime function, (declared in
1498 AudioHardware.h) which returns an error if the audio device is not running.
1499 @param inAQ
1500 The audio queue whose audio device is to be queried.
1501 @param outTimeStamp
1502 A pointer to a structure that, on return, contains the current time of the audio device
1503 associated with the audio queue.
1504 @result
1505 An OSStatus result code.
1506 }
AudioQueueDeviceGetCurrentTimenull1507 function AudioQueueDeviceGetCurrentTime( inAQ: AudioQueueRef; var outTimeStamp: AudioTimeStamp ): OSStatus; external name '_AudioQueueDeviceGetCurrentTime';
1508 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1509
1510 {!
1511 @function AudioQueueDeviceTranslateTime
1512 @abstract Converts the time in the time base of the associated audio device from one
1513 representation to another.
1514 @discussion
1515 This function converts from one time representation to another (for example, from sample
1516 time to host time or vice versa):
1517
1518 <ul>
1519 <li> Sample time is the absolute sample frame time.
1520 Sample numbers are the count of the samples on the audio device.</li>
1521 <li> Host time is the
1522 time base of the host machine such as the time of the bus clock on the CPU.</li>
1523 </ul>
1524
1525 The mSampleTime field in the AudioTimestamp structure (described in Core Audio Data
1526 Types Reference) is always in device time, not in audio queue time. Audio queue time is
1527 relative to the audio queue's start time. The associated audio device has to be running
1528 for the AudioQueueDeviceTranslateTime function to provide a result.
1529 @param inAQ
1530 The queue whose audio device is to perform the requested time translation.
1531 @param inTime
1532 A pointer to a structure containing the time to be translated.
1533 @param outTime
1534 A pointer to the the translated time.
1535 @result
1536 An OSStatus result code.
1537 }
AudioQueueDeviceTranslateTimenull1538 function AudioQueueDeviceTranslateTime( inAQ: AudioQueueRef; const (*var*) inTime: AudioTimeStamp; var outTime: AudioTimeStamp ): OSStatus; external name '_AudioQueueDeviceTranslateTime';
1539 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1540
1541 {!
1542 @function AudioQueueDeviceGetNearestStartTime
1543 @abstract Obtains an audio device's start time that is closest to a requested start time.
1544 @discussion
1545 @param inAQ
1546 The audio queue whose device's nearest start time you want to obtain.
1547 @param ioRequestedStartTime
1548 On entry, points to the requested start time. On return, points to the actual start time.
1549 @param inFlags
1550 Reserved for future use. Pass 0.
1551 @result
1552 An OSStatus result code.
1553 }
AudioQueueDeviceGetNearestStartTimenull1554 function AudioQueueDeviceGetNearestStartTime( inAQ: AudioQueueRef; var ioRequestedStartTime: AudioTimeStamp; inFlags: UInt32 ): OSStatus; external name '_AudioQueueDeviceGetNearestStartTime';
1555 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1556
1557 //#pragma /mark -
1558 //#pragma /mark Offline Rendering
1559 //=============================================================================
1560 // Offline Rendering
1561 //=============================================================================
1562
1563 {!
1564 @function AudioQueueSetOfflineRenderFormat
1565 @abstract Specify an audio format to which the queue will perform subsequent offline rendering,
1566 or disable offline rendering.
1567 @discussion
1568 An output queue's audio playback can be redirected for capture to an audio file,
1569 to support an export function, for example. AudioQueueSetOfflineRenderFormat switches
1570 a queue between normal and offline rendering modes.
1571 @param inAQ
1572 The output queue whose offline rendering mode is to be changed.
1573 @param inFormat
1574 The desired format for offline rendering. Pass NULL to disable offline rendering and return the
1575 queue to normal output to an audio device. This format must be linear PCM and (if not mono)
1576 interleaved.
1577 @param inLayout
1578 The desired channel layout for offline rendering; also NULL when disabling offline rendering.
1579 @result
1580 An OSStatus result code.
1581 }
AudioQueueSetOfflineRenderFormatnull1582 function AudioQueueSetOfflineRenderFormat( inAQ: AudioQueueRef; {const} inFormat: AudioStreamBasicDescriptionPtr {* __nullable}; {const} inLayout: AudioChannelLayout {* __nullable} ): OSStatus; external name '_AudioQueueSetOfflineRenderFormat';
1583 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1584
1585 {!
1586 @function AudioQueueOfflineRender
1587 @abstract Obtain a buffer of audio output from a queue in offline rendering mode.
1588 @discussion
1589 @param inAQ
1590 The output queue from which to obtain output.
1591 @param inTimestamp
1592 The point in time corresponding to the beginning of the output buffer. Only mSampleTime
1593 is used. mFlags must include kAudioTimeStampSampleTimeValid.
1594 @param ioBuffer
1595 The buffer into which the queue will render.
1596 @param inNumberFrames
1597 The number of frames of audio to render. Note that fewer frames than requested may be returned.
1598 This can happen if insufficient data was enqueued.
1599 @result
1600 An OSStatus result code.
1601 }
AudioQueueOfflineRendernull1602 function AudioQueueOfflineRender( inAQ: AudioQueueRef; const (*var*) inTimestamp: AudioTimeStamp; ioBuffer: AudioQueueBufferRef; inNumberFrames: UInt32 ): OSStatus; external name '_AudioQueueOfflineRender';
1603 (* API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) *)
1604
1605 //#pragma /mark -
1606 //#pragma /mark Processing Taps
1607 //=============================================================================
1608 // Processing Taps
1609 //=============================================================================
1610
1611
1612 {!
1613 @function AudioQueueProcessingTapNew
1614 @abstract Create a new processing tap
1615 @discussion
1616 This function creates a processing tap on a given audio queue. A
1617 processing tap can only be established (or removed) on an audio queue that is
1618 stopped (paused is not sufficient). The processing tap will then be used to
1619 process either decoded data in the case of an output queue, or input data
1620 (before it is encoded) in the case of an input queue.
1621
1622 The processing is performed on audio either before or after any effects or other
1623 processing (varispeed, etc) is applied by the audio queue, depending on inFlags.
1624
1625 @param inAQ
1626 The audio queue from which to create the processing tap
1627 @param inCallback
1628 A callback which the queue will call to process the audio
1629 @param inClientData
1630 Client data provided to the callback
1631 @param inFlags
1632 Flags that are used to control aspects of the processing tap.
1633 Valid flags are:
1634 - kAudioQueueProcessingTap_PreEffects: processing is done before any
1635 further effects are applied by the audio queue to the audio
1636 - kAudioQueueProcessingTap_PostEffects: processing is done after all
1637 processing is done, including that of other taps.
1638 - kAudioQueueProcessingTap_Siphon
1639 @param outMaxFrames
1640 The maximum number of sample frames that can be requested of a processing
1641 tap at any one time. Typically this will be approximately 50 msec of audio
1642 (2048 samples @ 44.1kHz)
1643 @param outProcessingFormat
1644 The format in which the client will receive the audio data to be processed.
1645 This will always be the same sample rate as the client format and usually
1646 the same number of channels as the client format of the audio queue. (NOTE:
1647 the number of channels may be different in some cases if the client format
1648 has some channel count restrictions, for instance the client provides 5.1
1649 AAC, but the decoder can only produce stereo). The channel order, if the
1650 same as the client format, will be the same as the client channel order. If
1651 the channel count is changed, it will be to either 1 (mono) or 2 (stereo, in
1652 which case the first channel is left, the second right).
1653
1654 If the data is not in a convenient format for the client to process in, then
1655 the client should convert the data to and from that format. This is the most
1656 efficient mechanism to use (as the audio queue can chose a format that is
1657 most efficient from its playback (or recording) requirement.
1658 @param outAQTap
1659 The processing tap object.
1660
1661 @result An OSStatus result code.
1662 }
AudioQueueProcessingTapNewnull1663 function AudioQueueProcessingTapNew( inAQ: AudioQueueRef; inCallback: AudioQueueProcessingTapCallback; inClientData: UnivPtr {__nullable}; inFlags: AudioQueueProcessingTapFlags; var outMaxFrames: UInt32; var outProcessingFormat: AudioStreamBasicDescription; var outAQTap: AudioQueueProcessingTapRef {__nullable * __nonnull} ): OSStatus; external name '_AudioQueueProcessingTapNew';
1664 (* API_AVAILABLE(macos(10.7), ios(6.0), watchos(2.0), tvos(9.0)) *)
1665
1666 {!
1667 @function AudioQueueProcessingTapDispose
1668 @abstract Dispose a processing tap object
1669 @discussion
1670 As with AudioQueueProcessingTapNew, this call can only be made on an
1671 audio queue that is stopped (paused is not sufficient)
1672
1673 @param inAQTap
1674 The processing tap to dispose.
1675
1676 @result An OSStatus result code.
1677 }
AudioQueueProcessingTapDisposenull1678 function AudioQueueProcessingTapDispose( inAQTap: AudioQueueProcessingTapRef ): OSStatus; external name '_AudioQueueProcessingTapDispose';
1679 (* API_AVAILABLE(macos(10.7), ios(6.0), watchos(2.0), tvos(9.0)) *)
1680
1681 {!
1682 @function AudioQueueProcessingTapGetSourceAudio
1683 @abstract Used by a processing tap to retrieve source audio.
1684 @discussion
1685 This function may only be called from the processing tap's callback.
1686
1687 @param inAQTap
1688 the processing tap
1689 @param inNumberFrames
1690 the number of frames the processing tap requires for its processing
1691 @param ioTimeStamp
1692 On an input audio queue, the timestamp is returned from this function.
1693 On an output audio queue, the caller must provide a continuous timestamp.
1694 @param outFlags
1695 flags to describe state about the input requested, e.g.
1696 discontinuity/complete
1697 @param outNumberFrames
1698 the number of source frames that have been provided by the parent audio
1699 queue. This can be less than the number of requested frames specified in
1700 inNumberFrames
1701 @param ioData
1702 the audio buffer list which will contain the source data. The audio queue owns
1703 the buffer pointers if NULL pointers were provided (recommended). In this case
1704 the source buffers are only valid for the duration of the processing tap
1705 callback. If the buffer pointers are non-NULL, then they must be big enough to
1706 hold inNumberFrames, and the audio queue will copy its source data into those
1707 buffers.
1708
1709 @result An OSStatus result code.
1710 }
AudioQueueProcessingTapGetSourceAudionull1711 function AudioQueueProcessingTapGetSourceAudio( inAQTap: AudioQueueProcessingTapRef; inNumberFrames: UInt32; var ioTimeStamp: AudioTimeStamp; var outFlags: AudioQueueProcessingTapFlags; var outNumberFrames: UInt32; var ioData: AudioBufferList ): OSStatus; external name '_AudioQueueProcessingTapGetSourceAudio';
1712 (* API_AVAILABLE(macos(10.7), ios(6.0), watchos(2.0), tvos(9.0)) *)
1713
1714 {!
1715 @function AudioQueueProcessingTapGetQueueTime
1716 @abstract Used by a processing tap to retrieve the queue's current time.
1717 @discussion
1718 This function may only be called from the processing tap's callback, and only
1719 for audio output queues. It must be called after calling
1720 AudioQueueProcessingTapGetSourceAudio.
1721
1722 @param inAQTap
1723 the processing tap
1724 @param outQueueSampleTime
1725 the current sample time of the audio queue. This will appear to be stationary
1726 if the queue is paused.
1727 @param outQueueFrameCount
1728 the number of sample frames of queue time corresponding to the current chunk of
1729 audio being processed by the tap. This will differ from the frame count passed
1730 to the tap if the queue's playback rate is currently other than 1.0, due to the
1731 use of time compression/expansion. The frame count can also be 0 if the queue is
1732 paused.
1733
1734 @result An OSStatus result code.
1735 }
AudioQueueProcessingTapGetQueueTimenull1736 function AudioQueueProcessingTapGetQueueTime( inAQTap: AudioQueueProcessingTapRef; var outQueueSampleTime: Float64; var outQueueFrameCount: UInt32 ): OSStatus; external name '_AudioQueueProcessingTapGetQueueTime';
1737 (* API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) *)
1738
1739
1740 //CF_ASSUME_NONNULL_END
1741
1742 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
1743
1744 end.
1745 {$endc} {not MACOSALLINCLUDE}
1746