1 {!
2 @file AudioConverter.h
3 @framework AudioToolbox.framework
4 @copyright (c) 1985-2015 by Apple, Inc., all rights reserved.
5 @abstract API's to perform audio format conversions.
6
7 @discussion
8 AudioConverters convert between various linear PCM and compressed
9 audio formats. Supported transformations include:
10
11 - PCM float/integer/bit depth conversions
12 - PCM sample rate conversion
13 - PCM interleaving and deinterleaving
14 - encoding PCM to compressed formats
15 - decoding compressed formats to PCM
16
17 A single AudioConverter may perform more than one
18 of the above transformations.
19 }
20 { Pascal Translation: Jonas Maebe <jonas@freepascal.org>, July 2019 }
21 {
22 Modified for use with Free Pascal
23 Version 308
24 Please report any bugs to <gpc@microbizz.nl>
25 }
26
27 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
28 {$mode macpas}
29 {$modeswitch cblocks}
30 {$packenum 1}
31 {$macro on}
32 {$inline on}
33 {$calling mwpascal}
34
35 unit AudioConverter;
36 interface
37 {$setc UNIVERSAL_INTERFACES_VERSION := $0400}
38 {$setc GAP_INTERFACES_VERSION := $0308}
39
40 {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
41 {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
42 {$endc}
43
44 {$ifc defined CPUPOWERPC and defined CPUI386}
45 {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
46 {$endc}
47 {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
48 {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
49 {$endc}
50
51 {$ifc not defined __ppc__ and defined CPUPOWERPC32}
52 {$setc __ppc__ := 1}
53 {$elsec}
54 {$setc __ppc__ := 0}
55 {$endc}
56 {$ifc not defined __ppc64__ and defined CPUPOWERPC64}
57 {$setc __ppc64__ := 1}
58 {$elsec}
59 {$setc __ppc64__ := 0}
60 {$endc}
61 {$ifc not defined __i386__ and defined CPUI386}
62 {$setc __i386__ := 1}
63 {$elsec}
64 {$setc __i386__ := 0}
65 {$endc}
66 {$ifc not defined __x86_64__ and defined CPUX86_64}
67 {$setc __x86_64__ := 1}
68 {$elsec}
69 {$setc __x86_64__ := 0}
70 {$endc}
71 {$ifc not defined __arm__ and defined CPUARM}
72 {$setc __arm__ := 1}
73 {$elsec}
74 {$setc __arm__ := 0}
75 {$endc}
76 {$ifc not defined __arm64__ and defined CPUAARCH64}
77 {$setc __arm64__ := 1}
78 {$elsec}
79 {$setc __arm64__ := 0}
80 {$endc}
81
82 {$ifc defined cpu64}
83 {$setc __LP64__ := 1}
84 {$elsec}
85 {$setc __LP64__ := 0}
86 {$endc}
87
88
89 {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
90 {$error Conflicting definitions for __ppc__ and __i386__}
91 {$endc}
92
93 {$ifc defined __ppc__ and __ppc__}
94 {$setc TARGET_CPU_PPC := TRUE}
95 {$setc TARGET_CPU_PPC64 := FALSE}
96 {$setc TARGET_CPU_X86 := FALSE}
97 {$setc TARGET_CPU_X86_64 := FALSE}
98 {$setc TARGET_CPU_ARM := FALSE}
99 {$setc TARGET_CPU_ARM64 := FALSE}
100 {$setc TARGET_OS_MAC := TRUE}
101 {$setc TARGET_OS_IPHONE := FALSE}
102 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
103 {$setc TARGET_OS_EMBEDDED := FALSE}
104 {$elifc defined __ppc64__ and __ppc64__}
105 {$setc TARGET_CPU_PPC := FALSE}
106 {$setc TARGET_CPU_PPC64 := TRUE}
107 {$setc TARGET_CPU_X86 := FALSE}
108 {$setc TARGET_CPU_X86_64 := FALSE}
109 {$setc TARGET_CPU_ARM := FALSE}
110 {$setc TARGET_CPU_ARM64 := FALSE}
111 {$setc TARGET_OS_MAC := TRUE}
112 {$setc TARGET_OS_IPHONE := FALSE}
113 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
114 {$setc TARGET_OS_EMBEDDED := FALSE}
115 {$elifc defined __i386__ and __i386__}
116 {$setc TARGET_CPU_PPC := FALSE}
117 {$setc TARGET_CPU_PPC64 := FALSE}
118 {$setc TARGET_CPU_X86 := TRUE}
119 {$setc TARGET_CPU_X86_64 := FALSE}
120 {$setc TARGET_CPU_ARM := FALSE}
121 {$setc TARGET_CPU_ARM64 := FALSE}
122 {$ifc defined iphonesim}
123 {$setc TARGET_OS_MAC := FALSE}
124 {$setc TARGET_OS_IPHONE := TRUE}
125 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
126 {$elsec}
127 {$setc TARGET_OS_MAC := TRUE}
128 {$setc TARGET_OS_IPHONE := FALSE}
129 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
130 {$endc}
131 {$setc TARGET_OS_EMBEDDED := FALSE}
132 {$elifc defined __x86_64__ and __x86_64__}
133 {$setc TARGET_CPU_PPC := FALSE}
134 {$setc TARGET_CPU_PPC64 := FALSE}
135 {$setc TARGET_CPU_X86 := FALSE}
136 {$setc TARGET_CPU_X86_64 := TRUE}
137 {$setc TARGET_CPU_ARM := FALSE}
138 {$setc TARGET_CPU_ARM64 := FALSE}
139 {$ifc defined iphonesim}
140 {$setc TARGET_OS_MAC := FALSE}
141 {$setc TARGET_OS_IPHONE := TRUE}
142 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
143 {$elsec}
144 {$setc TARGET_OS_MAC := TRUE}
145 {$setc TARGET_OS_IPHONE := FALSE}
146 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
147 {$endc}
148 {$setc TARGET_OS_EMBEDDED := FALSE}
149 {$elifc defined __arm__ and __arm__}
150 {$setc TARGET_CPU_PPC := FALSE}
151 {$setc TARGET_CPU_PPC64 := FALSE}
152 {$setc TARGET_CPU_X86 := FALSE}
153 {$setc TARGET_CPU_X86_64 := FALSE}
154 {$setc TARGET_CPU_ARM := TRUE}
155 {$setc TARGET_CPU_ARM64 := FALSE}
156 {$setc TARGET_OS_MAC := FALSE}
157 {$setc TARGET_OS_IPHONE := TRUE}
158 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
159 {$setc TARGET_OS_EMBEDDED := TRUE}
160 {$elifc defined __arm64__ and __arm64__}
161 {$setc TARGET_CPU_PPC := FALSE}
162 {$setc TARGET_CPU_PPC64 := FALSE}
163 {$setc TARGET_CPU_X86 := FALSE}
164 {$setc TARGET_CPU_X86_64 := FALSE}
165 {$setc TARGET_CPU_ARM := FALSE}
166 {$setc TARGET_CPU_ARM64 := TRUE}
167 {$ifc defined ios}
168 {$setc TARGET_OS_MAC := FALSE}
169 {$setc TARGET_OS_IPHONE := TRUE}
170 {$setc TARGET_OS_EMBEDDED := TRUE}
171 {$elsec}
172 {$setc TARGET_OS_MAC := TRUE}
173 {$setc TARGET_OS_IPHONE := FALSE}
174 {$setc TARGET_OS_EMBEDDED := FALSE}
175 {$endc}
176 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
177 {$elsec}
178 {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ nor __arm64__ is defined.}
179 {$endc}
180
181 {$ifc defined __LP64__ and __LP64__ }
182 {$setc TARGET_CPU_64 := TRUE}
183 {$elsec}
184 {$setc TARGET_CPU_64 := FALSE}
185 {$endc}
186
187 {$ifc defined FPC_BIG_ENDIAN}
188 {$setc TARGET_RT_BIG_ENDIAN := TRUE}
189 {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
190 {$elifc defined FPC_LITTLE_ENDIAN}
191 {$setc TARGET_RT_BIG_ENDIAN := FALSE}
192 {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
193 {$elsec}
194 {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
195 {$endc}
196 {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
197 {$setc CALL_NOT_IN_CARBON := FALSE}
198 {$setc OLDROUTINENAMES := FALSE}
199 {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
200 {$setc OPAQUE_UPP_TYPES := TRUE}
201 {$setc OTCARBONAPPLICATION := TRUE}
202 {$setc OTKERNEL := FALSE}
203 {$setc PM_USE_SESSION_APIS := TRUE}
204 {$setc TARGET_API_MAC_CARBON := TRUE}
205 {$setc TARGET_API_MAC_OS8 := FALSE}
206 {$setc TARGET_API_MAC_OSX := TRUE}
207 {$setc TARGET_CARBON := TRUE}
208 {$setc TARGET_CPU_68K := FALSE}
209 {$setc TARGET_CPU_MIPS := FALSE}
210 {$setc TARGET_CPU_SPARC := FALSE}
211 {$setc TARGET_OS_UNIX := FALSE}
212 {$setc TARGET_OS_WIN32 := FALSE}
213 {$setc TARGET_RT_MAC_68881 := FALSE}
214 {$setc TARGET_RT_MAC_CFM := FALSE}
215 {$setc TARGET_RT_MAC_MACHO := TRUE}
216 {$setc TYPED_FUNCTION_POINTERS := TRUE}
217 {$setc TYPE_BOOL := FALSE}
218 {$setc TYPE_EXTENDED := FALSE}
219 {$setc TYPE_LONGLONG := TRUE}
220 uses MacTypes,CoreAudioTypes;
221 {$endc} {not MACOSALLINCLUDE}
222
223 {$ALIGN POWER}
224
225 //==================================================================================================
226
227 {!
228 @header AudioConverter.h
229
230 }
231
232 //=============================================================================
233 // Includes
234 //=============================================================================
235
236
237 //CF_ASSUME_NONNULL_BEGIN
238
239
240 //=============================================================================
241 // Theory of Operation
242 //=============================================================================
243
244 //=============================================================================
245 // Types specific to the Audio Converter API
246 //=============================================================================
247
248 {!
249 @typedef AudioConverterRef
250 @abstract A reference to an AudioConverter object.
251 }
252 type
253 AudioConverterRef = ^OpaqueAudioConverter; { an opaque type }
254 OpaqueAudioConverter = record end;
255
256 type
257 AudioConverterPropertyID = UInt32;
258
259 //=============================================================================
260 // Standard Properties
261 //=============================================================================
262
263 {!
264 @enum AudioConverterPropertyID
265 @abstract The properties of an AudioConverter, accessible via AudioConverterGetProperty()
266 and AudioConverterSetProperty().
267
268 @constant kAudioConverterPropertyMinimumInputBufferSize
269 a UInt32 that indicates the size in bytes of the smallest buffer of input
270 data that can be supplied via the AudioConverterInputProc or as the input to
271 AudioConverterConvertBuffer
272 @constant kAudioConverterPropertyMinimumOutputBufferSize
273 a UInt32 that indicates the size in bytes of the smallest buffer of output
274 data that can be supplied to AudioConverterFillComplexBuffer or as the output to
275 AudioConverterConvertBuffer
276 @constant kAudioConverterPropertyMaximumInputBufferSize
277 DEPRECATED. The AudioConverter input proc may be passed any number of packets of data.
278 If fewer are packets are returned than required, then the input proc will be called again.
279 If more packets are passed than required, they will remain in the client's buffer and be
280 consumed as needed.
281 @constant kAudioConverterPropertyMaximumInputPacketSize
282 a UInt32 that indicates the size in bytes of the largest single packet of
283 data in the input format. This is mostly useful for variable bit rate
284 compressed data (decoders).
285 @constant kAudioConverterPropertyMaximumOutputPacketSize
286 a UInt32 that indicates the size in bytes of the largest single packet of
287 data in the output format. This is mostly useful for variable bit rate
288 compressed data (encoders).
289 @constant kAudioConverterPropertyCalculateInputBufferSize
290 a UInt32 that on input holds a size in bytes that is desired for the output
291 data. On output, it will hold the size in bytes of the input buffer required
292 to generate that much output data. Note that some converters cannot do this
293 calculation.
294 @constant kAudioConverterPropertyCalculateOutputBufferSize
295 a UInt32 that on input holds a size in bytes that is desired for the input
296 data. On output, it will hold the size in bytes of the output buffer
297 required to hold the output data that will be generated. Note that some
298 converters cannot do this calculation.
299 @constant kAudioConverterPropertyInputCodecParameters
300 The value of this property varies from format to format and is considered
301 private to the format. It is treated as a buffer of untyped data.
302 @constant kAudioConverterPropertyOutputCodecParameters
303 The value of this property varies from format to format and is considered
304 private to the format. It is treated as a buffer of untyped data.
305 @constant kAudioConverterSampleRateConverterAlgorithm
306 DEPRECATED: please use kAudioConverterSampleRateConverterComplexity instead
307 @constant kAudioConverterSampleRateConverterComplexity
308 An OSType that specifies the sample rate converter algorithm to use (as defined in
309 AudioToolbox/AudioUnitProperties.h)
310 @constant kAudioConverterSampleRateConverterQuality
311 A UInt32 that specifies rendering quality of the sample rate converter (see
312 enum constants below)
313 @constant kAudioConverterSampleRateConverterInitialPhase
314 A Float64 with value 0.0 <= x < 1.0 giving the initial subsample position of the
315 sample rate converter.
316 @constant kAudioConverterCodecQuality
317 A UInt32 that specifies rendering quality of a codec (see enum constants
318 below)
319 @constant kAudioConverterPrimeMethod
320 a UInt32 specifying priming method (usually for sample-rate converter) see
321 explanation for struct AudioConverterPrimeInfo below along with enum
322 constants
323 @constant kAudioConverterPrimeInfo
324 A pointer to AudioConverterPrimeInfo (see explanation for struct
325 AudioConverterPrimeInfo below)
326 @constant kAudioConverterChannelMap
327 An array of SInt32's. The size of the array is the number of output
328 channels, and each element specifies which input channel's data is routed to
329 that output channel (using a 0-based index of the input channels), or -1 if
330 no input channel is to be routed to that output channel. The default
331 behavior is as follows. I = number of input channels, O = number of output
332 channels. When I > O, the first O inputs are routed to the first O outputs,
333 and the remaining puts discarded. When O > I, the first I inputs are routed
334 to the first O outputs, and the remaining outputs are zeroed.
335
336 A simple example for splitting mono input to stereo output (instead of routing
337 the input to only the first output channel):
338
339 <pre>
340 // this should be as large as the number of output channels:
341 SInt32 channelMap[2] = ( 0, 0 );
342 AudioConverterSetProperty(theConverter, kAudioConverterChannelMap,
343 sizeof(channelMap), channelMap);
344 </pre>
345 @constant kAudioConverterDecompressionMagicCookie
346 A void * pointing to memory set up by the caller. Required by some formats
347 in order to decompress the input data.
348 @constant kAudioConverterCompressionMagicCookie
349 A void * pointing to memory set up by the caller. Returned by the converter
350 so that it may be stored along with the output data. It can then be passed
351 back to the converter for decompression at a later time.
352 @constant kAudioConverterEncodeBitRate
353 A UInt32 containing the number of bits per second to aim for when encoding
354 data. Some decoders will also allow you to get this property to discover the bit rate.
355 @constant kAudioConverterEncodeAdjustableSampleRate
356 For encoders where the AudioConverter was created with an output sample rate
357 of zero, and the codec can do rate conversion on its input, this provides a
358 way to set the output sample rate. The property value is a Float64.
359 @constant kAudioConverterInputChannelLayout
360 The property value is an AudioChannelLayout.
361 @constant kAudioConverterOutputChannelLayout
362 The property value is an AudioChannelLayout.
363 @constant kAudioConverterApplicableEncodeBitRates
364 The property value is an array of AudioValueRange describing applicable bit
365 rates based on current settings.
366 @constant kAudioConverterAvailableEncodeBitRates
367 The property value is an array of AudioValueRange describing available bit
368 rates based on the input format. You can get all available bit rates from
369 the AudioFormat API.
370 @constant kAudioConverterApplicableEncodeSampleRates
371 The property value is an array of AudioValueRange describing applicable
372 sample rates based on current settings.
373 @constant kAudioConverterAvailableEncodeSampleRates
374 The property value is an array of AudioValueRange describing available
375 sample rates based on the input format. You can get all available sample
376 rates from the AudioFormat API.
377 @constant kAudioConverterAvailableEncodeChannelLayoutTags
378 The property value is an array of AudioChannelLayoutTags for the format and
379 number of channels specified in the input format going to the encoder.
380 @constant kAudioConverterCurrentOutputStreamDescription
381 Returns the current completely specified output AudioStreamBasicDescription.
382 For example when encoding to AAC, your original output stream description
383 will not have been completely filled out.
384 @constant kAudioConverterCurrentInputStreamDescription
385 Returns the current completely specified input AudioStreamBasicDescription.
386 @constant kAudioConverterPropertySettings
387 Returns the a CFArray of property settings for converters.
388 @constant kAudioConverterPropertyBitDepthHint
389 An SInt32 of the source bit depth to preserve. This is a hint to some
390 encoders like lossless about how many bits to preserve in the input. The
391 converter usually tries to preserve as many as possible, but a lossless
392 encoder will do poorly if more bits are supplied than are desired in the
393 output. The bit depth is expressed as a negative number if the source was floating point,
394 e.g. -32 for float, -64 for double.
395 @constant kAudioConverterPropertyFormatList
396 An array of AudioFormatListItem structs describing all the data formats produced by the
397 encoder end of the AudioConverter. If the ioPropertyDataSize parameter indicates that
398 outPropertyData is sizeof(AudioFormatListItem), then only the best format is returned.
399 This property may be used for example to discover all the data formats produced by the AAC_HE2
400 (AAC High Efficiency vers. 2) encoder.
401 }
402 const
403 kAudioConverterPropertyMinimumInputBufferSize = FourCharCode('mibs');
404 kAudioConverterPropertyMinimumOutputBufferSize = FourCharCode('mobs');
405 kAudioConverterPropertyMaximumInputBufferSize = FourCharCode('xibs');
406 kAudioConverterPropertyMaximumInputPacketSize = FourCharCode('xips');
407 kAudioConverterPropertyMaximumOutputPacketSize = FourCharCode('xops');
408 kAudioConverterPropertyCalculateInputBufferSize = FourCharCode('cibs');
409 kAudioConverterPropertyCalculateOutputBufferSize = FourCharCode('cobs');
410 kAudioConverterPropertyInputCodecParameters = FourCharCode('icdp');
411 kAudioConverterPropertyOutputCodecParameters = FourCharCode('ocdp');
412 kAudioConverterSampleRateConverterAlgorithm = FourCharCode('srci');
413 kAudioConverterSampleRateConverterComplexity = FourCharCode('srca');
414 kAudioConverterSampleRateConverterQuality = FourCharCode('srcq');
415 kAudioConverterSampleRateConverterInitialPhase = FourCharCode('srcp');
416 kAudioConverterCodecQuality = FourCharCode('cdqu');
417 kAudioConverterPrimeMethod = FourCharCode('prmm');
418 kAudioConverterPrimeInfo = FourCharCode('prim');
419 kAudioConverterChannelMap = FourCharCode('chmp');
420 kAudioConverterDecompressionMagicCookie = FourCharCode('dmgc');
421 kAudioConverterCompressionMagicCookie = FourCharCode('cmgc');
422 kAudioConverterEncodeBitRate = FourCharCode('brat');
423 kAudioConverterEncodeAdjustableSampleRate = FourCharCode('ajsr');
424 kAudioConverterInputChannelLayout = FourCharCode('icl ');
425 kAudioConverterOutputChannelLayout = FourCharCode('ocl ');
426 kAudioConverterApplicableEncodeBitRates = FourCharCode('aebr');
427 kAudioConverterAvailableEncodeBitRates = FourCharCode('vebr');
428 kAudioConverterApplicableEncodeSampleRates = FourCharCode('aesr');
429 kAudioConverterAvailableEncodeSampleRates = FourCharCode('vesr');
430 kAudioConverterAvailableEncodeChannelLayoutTags = FourCharCode('aecl');
431 kAudioConverterCurrentOutputStreamDescription = FourCharCode('acod');
432 kAudioConverterCurrentInputStreamDescription = FourCharCode('acid');
433 kAudioConverterPropertySettings = FourCharCode('acps');
434 kAudioConverterPropertyBitDepthHint = FourCharCode('acbd');
435 kAudioConverterPropertyFormatList = FourCharCode('flst');
436
437
438 //=============================================================================
439 //
440 //=============================================================================
441
442 {!
443 @enum Mac OS X AudioConverter Properties
444
445 @constant kAudioConverterPropertyDithering
446 A UInt32. Set to a value from the enum of dithering algorithms below.
447 Zero means no dithering and is the default. (Mac OS X only.)
448 @constant kAudioConverterPropertyDitherBitDepth
449 A UInt32. Dither is applied at this bit depth. (Mac OS X only.)
450
451 }
452 const
453 kAudioConverterPropertyDithering = FourCharCode('dith');
454 kAudioConverterPropertyDitherBitDepth = FourCharCode('dbit');
455
456 {!
457 @enum Dithering algorithms
458
459 @abstract Constants to be used as the value for kAudioConverterPropertyDithering.
460
461 @constant kDitherAlgorithm_TPDF Dither signal is generated by a white noise source with a triangular probability density function
462 @constant kDitherAlgorithm_NoiseShaping Use a static, perceptually weighted noise shaped dither
463 }
464 const
465 kDitherAlgorithm_TPDF = 1;
466 kDitherAlgorithm_NoiseShaping = 2;
467
468 {!
469 @enum Quality constants
470
471 @abstract Constants to be used with kAudioConverterSampleRateConverterQuality.
472
473 @constant kAudioConverterQuality_Max maximum quality
474 @constant kAudioConverterQuality_High high quality
475 @constant kAudioConverterQuality_Medium medium quality
476 @constant kAudioConverterQuality_Low low quality
477 @constant kAudioConverterQuality_Min minimum quality
478 }
479 const
480 kAudioConverterQuality_Max = $7F;
481 kAudioConverterQuality_High = $60;
482 kAudioConverterQuality_Medium = $40;
483 kAudioConverterQuality_Low = $20;
484 kAudioConverterQuality_Min = 0;
485
486
487 {!
488 @enum Sample Rate Converter Complexity
489 @constant kAudioConverterSampleRateConverterComplexity_Linear
490 @discussion Linear interpolation. lowest quality, cheapest.
491 InitialPhase and PrimeMethod properties are not operative with this mode.
492 @constant kAudioConverterSampleRateConverterComplexity_Normal
493 @discussion Normal quality sample rate conversion.
494 @constant kAudioConverterSampleRateConverterComplexity_Mastering
495 @discussion Mastering quality sample rate conversion. More expensive.
496 @constant kAudioConverterSampleRateConverterComplexity_MinimumPhase
497 @discussion Minimum phase impulse response. Stopband attenuation varies with quality setting.
498 The InitialPhase and PrimeMethod properties are not operative with this mode.
499 There are three levels of quality provided.
500 kAudioConverterQuality_Low (or Min) : noise floor to -96 dB
501 kAudioConverterQuality_Medium : noise floor to -144 dB
502 kAudioConverterQuality_High (or Max) : noise floor to -160 dB (this uses double precision internally)
503 Quality equivalences to the other complexity modes are very roughly as follows:
504 MinimumPhase Low is somewhat better than Normal Medium.
505 MinimumPhase Medium is similar to Normal Max.
506 MinimumPhase High is similar to Mastering Low.
507 In general, MinimumPhase performs better than Normal and Mastering for the equivalent qualities listed above.
508 MinimumPhase High is several times faster than Mastering Low.
509
510 }
511 const
512 kAudioConverterSampleRateConverterComplexity_Linear = FourCharCode('line'); // linear interpolation
513 kAudioConverterSampleRateConverterComplexity_Normal = FourCharCode('norm'); // normal quality range, the default
514 kAudioConverterSampleRateConverterComplexity_Mastering = FourCharCode('bats'); // higher quality range, more expensive
515 kAudioConverterSampleRateConverterComplexity_MinimumPhase = FourCharCode('minp'); // minimum phase impulse response.
516
517
518 {!
519 @enum Prime method constants
520
521 @abstract Constants to be used with kAudioConverterPrimeMethod.
522
523 @constant kConverterPrimeMethod_Pre
524 Primes with leading + trailing input frames.
525 @constant kConverterPrimeMethod_Normal
526 Only primes with trailing (zero latency). Leading frames are assumed to be
527 silence.
528 @constant kConverterPrimeMethod_None
529 Acts in "latency" mode. Both leading and trailing frames assumed to be
530 silence.
531 }
532 const
533 kConverterPrimeMethod_Pre = 0;
534 kConverterPrimeMethod_Normal = 1;
535 kConverterPrimeMethod_None = 2;
536
537 {!
538 @struct AudioConverterPrimeInfo
539 @abstract Specifies priming information.
540
541 @field leadingFrames
542 Specifies the number of leading (previous) input frames, relative to the normal/desired
543 start input frame, required by the converter to perform a high quality conversion. If
544 using kConverterPrimeMethod_Pre, the client should "pre-seek" the input stream provided
545 through the input proc by leadingFrames. If no frames are available previous to the
546 desired input start frame (because, for example, the desired start frame is at the very
547 beginning of available audio), then provide "leadingFrames" worth of initial zero frames
548 in the input proc. Do not "pre-seek" in the default case of
549 kConverterPrimeMethod_Normal or when using kConverterPrimeMethod_None.
550
551 @field trailingFrames
552 Specifies the number of trailing input frames (past the normal/expected end input frame)
553 required by the converter to perform a high quality conversion. The client should be
554 prepared to provide this number of additional input frames except when using
555 kConverterPrimeMethod_None. If no more frames of input are available in the input stream
556 (because, for example, the desired end frame is at the end of an audio file), then zero
557 (silent) trailing frames will be synthesized for the client.
558
559 @discussion
560 When using AudioConverterFillComplexBuffer() (either a single call or a series of calls), some
561 conversions, particularly involving sample-rate conversion, ideally require a certain
562 number of input frames previous to the normal start input frame and beyond the end of
563 the last expected input frame in order to yield high-quality results.
564
565 These are expressed in the leadingFrames and trailingFrames members of the structure.
566
567 The very first call to AudioConverterFillComplexBuffer(), or first call after
568 AudioConverterReset(), will request additional input frames beyond those normally
569 expected in the input proc callback to fulfill this first AudioConverterFillComplexBuffer()
570 request. The number of additional frames requested, depending on the prime method, will
571 be approximately:
572
573 <pre>
574 kConverterPrimeMethod_Pre leadingFrames + trailingFrames
575 kConverterPrimeMethod_Normal trailingFrames
576 kConverterPrimeMethod_None 0
577 </pre>
578
579 Thus, in effect, the first input proc callback(s) may provide not only the leading
580 frames, but also may "read ahead" by an additional number of trailing frames depending
581 on the prime method.
582
583 kConverterPrimeMethod_None is useful in a real-time application processing live input,
584 in which case trailingFrames (relative to input sample rate) of through latency will be
585 seen at the beginning of the output of the AudioConverter. In other real-time
586 applications such as DAW systems, it may be possible to provide these initial extra
587 audio frames since they are stored on disk or in memory somewhere and
588 kConverterPrimeMethod_Pre may be preferable. The default method is
589 kConverterPrimeMethod_Normal, which requires no pre-seeking of the input stream and
590 generates no latency at the output.
591 }
592 type
593 AudioConverterPrimeInfo = record
594 leadingFrames: UInt32;
595 trailingFrames: UInt32;
596 end;
597 AudioConverterPrimeInfoPtr = ^AudioConverterPrimeInfo;
598
599 //=============================================================================
600 // Errors
601 //=============================================================================
602 const
603 kAudioConverterErr_FormatNotSupported = FourCharCode('fmt?');
604 kAudioConverterErr_OperationNotSupported = $6F703F3F; // 'op??', integer used because of trigraph
605 kAudioConverterErr_PropertyNotSupported = FourCharCode('prop');
606 kAudioConverterErr_InvalidInputSize = FourCharCode('insz');
607 kAudioConverterErr_InvalidOutputSize = FourCharCode('otsz');
608 // e.g. byte size is not a multiple of the frame size
609 kAudioConverterErr_UnspecifiedError = FourCharCode('what');
610 kAudioConverterErr_BadPropertySizeError = FourCharCode('!siz');
611 kAudioConverterErr_RequiresPacketDescriptionsError = FourCharCode('!pkd');
612 kAudioConverterErr_InputSampleRateOutOfRange = FourCharCode('!isr');
613 kAudioConverterErr_OutputSampleRateOutOfRange = FourCharCode('!osr');
614
615
616 //=============================================================================
617 // Routines
618 //=============================================================================
619
620 //-----------------------------------------------------------------------------
621 {!
622 @function AudioConverterNew
623 @abstract Create a new AudioConverter.
624
625 @param inSourceFormat
626 The format of the source audio to be converted.
627 @param inDestinationFormat
628 The destination format to which the audio is to be converted.
629 @param outAudioConverter
630 On successful return, points to a new AudioConverter instance.
631 @result An OSStatus result code.
632
633 @discussion
634 For a pair of linear PCM formats, the following conversions
635 are supported:
636
637 <ul>
638 <li>addition and removal of channels, when the stream descriptions'
639 mChannelsPerFrame does not match. Channels may also be reordered and removed
640 using the kAudioConverterChannelMap property.</li>
641 <li>sample rate conversion</li>
642 <li>interleaving/deinterleaving, when the stream descriptions' (mFormatFlags &
643 kAudioFormatFlagIsNonInterleaved) does not match.</li>
644 <li>conversion between any pair of the following formats:</li>
645 <ul>
646 <li>8 bit integer, signed or unsigned</li>
647 <li>16, 24, or 32-bit integer, big- or little-endian. Other integral
648 bit depths, if high-aligned and non-packed, are also supported</li>
649 <li>32 and 64-bit float, big- or little-endian.</li>
650 </ul>
651 </ul>
652
653 Also, encoding and decoding between linear PCM and compressed formats is
654 supported. Functions in AudioToolbox/AudioFormat.h return information about the
655 supported formats. When using a codec, you can use any supported PCM format (as
656 above); the converter will perform any necessary additional conversion between
657 your PCM format and the one created or consumed by the codec.
658 }
AudioConverterNewnull659 function AudioConverterNew( const (*var*) inSourceFormat: AudioStreamBasicDescription; const (*var*) inDestinationFormat: AudioStreamBasicDescription; var outAudioConverter: AudioConverterRef {__nullable * __nonnull} ): OSStatus; external name '_AudioConverterNew';
660 (* API_AVAILABLE(macos(10.1), ios(2.0), watchos(2.0), tvos(9.0)) *)
661
662
663 //-----------------------------------------------------------------------------
664 {!
665 @function AudioConverterNewSpecific
666 @abstract Create a new AudioConverter using specific codecs.
667
668 @param inSourceFormat
669 The format of the source audio to be converted.
670 @param inDestinationFormat
671 The destination format to which the audio is to be converted.
672 @param inNumberClassDescriptions
673 The number of class descriptions.
674 @param inClassDescriptions
675 AudioClassDescriptions specifiying the codec to instantiate.
676 @param outAudioConverter
677 On successful return, points to a new AudioConverter instance.
678 @result An OSStatus result code.
679
680 @discussion
681 This function is identical to AudioConverterNew(), except that the client may
682 explicitly choose which codec to instantiate if there is more than one choice.
683 }
AudioConverterNewSpecificnull684 function AudioConverterNewSpecific( const (*var*) inSourceFormat: AudioStreamBasicDescription; const (*var*) inDestinationFormat: AudioStreamBasicDescription; inNumberClassDescriptions: UInt32; const (*var*) inClassDescriptions: AudioClassDescription; var outAudioConverter: AudioConverterRef {__nullable * __nonnull} ): OSStatus; external name '_AudioConverterNewSpecific';
685 (* API_AVAILABLE(macos(10.4), ios(2.0), watchos(2.0), tvos(9.0)) *)
686
687 //-----------------------------------------------------------------------------
688 {!
689 @function AudioConverterDispose
690 @abstract Destroy an AudioConverter.
691
692 @param inAudioConverter
693 The AudioConverter to dispose.
694 @result An OSStatus result code.
695 }
AudioConverterDisposenull696 function AudioConverterDispose( inAudioConverter: AudioConverterRef ): OSStatus; external name '_AudioConverterDispose';
697 (* API_AVAILABLE(macos(10.1), ios(2.0), watchos(2.0), tvos(9.0)) *)
698
699 //-----------------------------------------------------------------------------
700 {!
701 @function AudioConverterReset
702 @abstract Reset an AudioConverter
703
704 @param inAudioConverter
705 The AudioConverter to reset.
706 @result An OSStatus result code.
707
708 @discussion
709 Should be called whenever there is a discontinuity in the source audio stream
710 being provided to the converter. This will flush any internal buffers in the
711 converter.
712 }
713
AudioConverterResetnull714 function AudioConverterReset( inAudioConverter: AudioConverterRef ): OSStatus; external name '_AudioConverterReset';
715 (* API_AVAILABLE(macos(10.1), ios(2.0), watchos(2.0), tvos(9.0)) *)
716
717 //-----------------------------------------------------------------------------
718 {!
719 @function AudioConverterGetPropertyInfo
720 @abstract Returns information about an AudioConverter property.
721
722 @param inAudioConverter
723 The AudioConverter to query.
724 @param inPropertyID
725 The property to query.
726 @param outSize
727 If non-null, on exit, the maximum size of the property value in bytes.
728 @param outWritable
729 If non-null, on exit, indicates whether the property value is writable.
730 @result An OSStatus result code.
731 }
AudioConverterGetPropertyInfonull732 function AudioConverterGetPropertyInfo( inAudioConverter: AudioConverterRef; inPropertyID: AudioConverterPropertyID; outSize: UInt32Ptr {* __nullable}; outWritable: BooleanPtr {* __nullable} ): OSStatus; external name '_AudioConverterGetPropertyInfo';
733 (* API_AVAILABLE(macos(10.1), ios(2.0), watchos(2.0), tvos(9.0)) *)
734
735 //-----------------------------------------------------------------------------
736 {!
737 @function AudioConverterGetProperty
738 @abstract Returns an AudioConverter property value.
739
740 @param inAudioConverter
741 The AudioConverter to query.
742 @param inPropertyID
743 The property to fetch.
744 @param ioPropertyDataSize
745 On entry, the size of the memory pointed to by outPropertyData. On
746 successful exit, the size of the property value.
747 @param outPropertyData
748 On exit, the property value.
749 @result An OSStatus result code.
750 }
AudioConverterGetPropertynull751 function AudioConverterGetProperty( inAudioConverter: AudioConverterRef; inPropertyID: AudioConverterPropertyID; var ioPropertyDataSize: UInt32; outPropertyData: UnivPtr ): OSStatus; external name '_AudioConverterGetProperty';
752 (* API_AVAILABLE(macos(10.1), ios(2.0), watchos(2.0), tvos(9.0)) *)
753
754 //-----------------------------------------------------------------------------
755 {!
756 @function AudioConverterSetProperty
757 @abstract Sets an AudioConverter property value.
758
759 @param inAudioConverter
760 The AudioConverter to modify.
761 @param inPropertyID
762 The property to set.
763 @param inPropertyDataSize
764 The size in bytes of the property value.
765 @param inPropertyData
766 Points to the new property value.
767 @result An OSStatus result code.
768 }
AudioConverterSetPropertynull769 function AudioConverterSetProperty( inAudioConverter: AudioConverterRef; inPropertyID: AudioConverterPropertyID; inPropertyDataSize: UInt32; inPropertyData: {const} UnivPtr ): OSStatus; external name '_AudioConverterSetProperty';
770 (* API_AVAILABLE(macos(10.1), ios(2.0), watchos(2.0), tvos(9.0)) *)
771
772 //-----------------------------------------------------------------------------
773 {!
774 @typedef AudioConverterInputDataProc
775 @abstract Callback function for supplying input data to AudioConverterFillBuffer.
776
777 @param inAudioConverter
778 The AudioConverter requesting input.
779 @param ioDataSize
780 On entry, the minimum number of bytes of audio data the converter
781 would like in order to fulfill its current FillBuffer request.
782 On exit, the number of bytes of audio data actually being provided
783 for input, or 0 if there is no more input.
784 @param outData
785 On exit, *outData should point to the audio data being provided
786 for input.
787 @param inUserData
788 The inInputDataProcUserData parameter passed to AudioConverterFillBuffer().
789 @result An OSStatus result code.
790
791 @discussion
792 <b>NOTE:</b> This API is now deprecated,
793 use AudioConverterFillComplexBuffer instead.
794
795 This callback function supplies input to AudioConverterFillBuffer.
796
797 The AudioConverter requests a minimum amount of data (*ioDataSize). The callback
798 may return any amount of data. If it is less than than the minimum, the callback
799 will simply be called again in the near future.
800
801 The callback supplies a pointer to a buffer of audio data. The callback is
802 responsible for not freeing or altering this buffer until it is called again.
803
804 If the callback returns an error, it must return zero bytes of data.
805 AudioConverterFillBuffer will stop producing output and return whatever output
806 has already been produced to its caller, along with the error code. This
807 mechanism can be used when an input proc has temporarily run out of data, but
808 has not yet reached end of stream.
809 }
810 type
inAudioConverternull811 AudioConverterInputDataProc = function( inAudioConverter: AudioConverterRef; var ioDataSize: UInt32; var outData: UnivPtr {__nonnull * __nonnull}; inUserData: UnivPtr {__nullable} ): OSStatus;
812
813 //-----------------------------------------------------------------------------
814 (*
815 {!
816 @function AudioConverterFillBuffer
817 @abstract Converts data supplied by an input callback function.
818
819 @param inAudioConverter
820 The AudioConverter to use.
821 @param inInputDataProc
822 A callback function which supplies the input data.
823 @param inInputDataProcUserData
824 A value for the use of the callback function.
825 @param ioOutputDataSize
826 On entry, the size of the buffer pointed to by outOutputData.
827 On exit, the number of bytes written to outOutputData
828 @param outOutputData
829 The buffer into which the converted data is written.
830 @result An OSStatus result code.
831
832 @discussion
833 <b>NOTE:</b> This API is now deprecated,
834 use AudioConverterFillComplexBuffer instead.
835
836 Produces a buffer of output data from an AudioConverter. The supplied input
837 callback function is called whenever necessary.
838 }
839 extern OSStatus
840 AudioConverterFillBuffer( AudioConverterRef inAudioConverter,
841 AudioConverterInputDataProc inInputDataProc,
842 void * __nullable inInputDataProcUserData,
843 UInt32 * ioOutputDataSize,
844 void * outOutputData)
845
846 API_DEPRECATED("no longer supported", macos(10.1, 10.5)) API_UNAVAILABLE(ios, watchos, tvos);
847 *)
848 //-----------------------------------------------------------------------------
849 {!
850 @function AudioConverterConvertBuffer
851 @abstract Converts data from an input buffer to an output buffer.
852
853 @param inAudioConverter
854 The AudioConverter to use.
855 @param inInputDataSize
856 The size of the buffer inInputData.
857 @param inInputData
858 The input audio data buffer.
859 @param ioOutputDataSize
860 On entry, the size of the buffer outOutputData. On exit, the number of bytes
861 written to outOutputData.
862 @param outOutputData
863 The output data buffer.
864 @result
865 Produces a buffer of output data from an AudioConverter, using the supplied
866 input buffer.
867 @discussion
868 <b>WARNING:</b> this function will fail for any conversion where there is a
869 variable relationship between the input and output data buffer sizes. This
870 includes sample rate conversions and most compressed formats. In these cases,
871 use AudioConverterFillComplexBuffer. Generally this function is only appropriate for
872 PCM-to-PCM conversions where there is no sample rate conversion.
873 }
874 function AudioConverterConvertBuffer( inAudioConverter: AudioConverterRef; inInputDataSize: UInt32; inInputData: {const} UnivPtr; var ioOutputDataSize: UInt32; outOutputData: UnivPtr ): OSStatus; external name '_AudioConverterConvertBuffer';
875 (* API_AVAILABLE(macos(10.1), ios(2.0), watchos(2.0), tvos(9.0)) *)
876
877 //-----------------------------------------------------------------------------
878 {!
879 @typedef AudioConverterComplexInputDataProc
880 @abstract Callback function for supplying input data to AudioConverterFillComplexBuffer.
881
882 @param inAudioConverter
883 The AudioConverter requesting input.
884 @param ioNumberDataPackets
885 On entry, the minimum number of packets of input audio data the converter
886 would like in order to fulfill its current FillBuffer request. On exit, the
887 number of packets of audio data actually being provided for input, or 0 if
888 there is no more input.
889 @param ioData
890 On exit, the members of ioData should be set to point to the audio data
891 being provided for input.
892 @param outDataPacketDescription
893 If non-null, on exit, the callback is expected to fill this in with
894 an AudioStreamPacketDescription for each packet of input data being provided.
895 @param inUserData
896 The inInputDataProcUserData parameter passed to AudioConverterFillComplexBuffer().
897 @result An OSStatus result code.
898
899 @discussion
900 This callback function supplies input to AudioConverterFillComplexBuffer.
901
902 The AudioConverter requests a minimum number of packets (*ioNumberDataPackets).
903 The callback may return one or more packets. If this is less than the minimum,
904 the callback will simply be called again in the near future.
905
906 The callback manipulates the members of ioData to point to one or more buffers
907 of audio data (multiple buffers are used with non-interleaved PCM data). The
908 callback is responsible for not freeing or altering this buffer until it is
909 called again.
910
911 If the callback returns an error, it must return zero packets of data.
912 AudioConverterFillComplexBuffer will stop producing output and return whatever
913 output has already been produced to its caller, along with the error code. This
914 mechanism can be used when an input proc has temporarily run out of data, but
915 has not yet reached end of stream.
916 }
917 type
inAudioConverternull918 AudioConverterComplexInputDataProc = function( inAudioConverter: AudioConverterRef; var ioNumberDataPackets: UInt32; var ioData: AudioBufferList; outDataPacketDescription: AudioStreamPacketDescriptionPtrPtr {* __nullable * __nullable}; inUserData: UnivPtr {__nullable} ): OSStatus;
919
920 //-----------------------------------------------------------------------------
921 {!
922 @function AudioConverterFillComplexBuffer
923 @abstract Converts data supplied by an input callback function, supporting non-interleaved
924 and packetized formats.
925
926 @param inAudioConverter
927 The AudioConverter to use.
928 @param inInputDataProc
929 A callback function which supplies the input data.
930 @param inInputDataProcUserData
931 A value for the use of the callback function.
932 @param ioOutputDataPacketSize
933 On entry, the capacity of outOutputData expressed in packets in the
934 converter's output format. On exit, the number of packets of converted
935 data that were written to outOutputData.
936 @param outOutputData
937 The converted output data is written to this buffer.
938 @param outPacketDescription
939 If non-null, and the converter's output uses packet descriptions, then
940 packet descriptions are written to this array. It must point to a memory
941 block capable of holding *ioOutputDataPacketSize packet descriptions.
942 (See AudioFormat.h for ways to determine whether an audio format
943 uses packet descriptions).
944 @result An OSStatus result code.
945
946 @discussion
947 Produces a buffer list of output data from an AudioConverter. The supplied input
948 callback function is called whenever necessary.
949 }
950 function AudioConverterFillComplexBuffer( inAudioConverter: AudioConverterRef; inInputDataProc: AudioConverterComplexInputDataProc; inInputDataProcUserData: UnivPtr {__nullable}; var ioOutputDataPacketSize: UInt32; var outOutputData: AudioBufferList; outPacketDescription: AudioStreamPacketDescriptionPtr {* __nullable} ): OSStatus; external name '_AudioConverterFillComplexBuffer';
951 (* API_AVAILABLE(macos(10.2), ios(2.0), watchos(2.0), tvos(9.0)) *)
952
953
954 //-----------------------------------------------------------------------------
955 {!
956 @function AudioConverterConvertComplexBuffer
957 @abstract Converts PCM data from an input buffer list to an output buffer list.
958
959 @param inAudioConverter
960 The AudioConverter to use.
961 @param inNumberPCMFrames
962 The number of PCM frames to convert.
963 @param inInputData
964 The source audio buffer list.
965 @param outOutputData
966 The converted output data is written to this buffer list.
967 @result An OSStatus result code.
968 @discussion
969 <b>WARNING:</b> this function will fail for any conversion where there is a
970 variable relationship between the input and output data buffer sizes. This
971 includes sample rate conversions and most compressed formats. In these cases,
972 use AudioConverterFillComplexBuffer. Generally this function is only appropriate for
973 PCM-to-PCM conversions where there is no sample rate conversion.
974 }
975 function AudioConverterConvertComplexBuffer( inAudioConverter: AudioConverterRef; inNumberPCMFrames: UInt32; const (*var*) inInputData: AudioBufferList; var outOutputData: AudioBufferList ): OSStatus; external name '_AudioConverterConvertComplexBuffer';
976 (* API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) *)
977
978
979 //CF_ASSUME_NONNULL_END
980 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
981
982 end.
983 {$endc} {not MACOSALLINCLUDE}
984