|
ADC Home > Reference Library > Reference > Audio > Core Audio > Audio Toolbox Framework Reference
|
AudioConverter.h |
| Includes: |
Functions for performing audio format conversions.
AudioConverters convert between various linear PCM and compressed
audio formats. Supported transformations include:
AudioConverterConvertBuffer |
Converts data from an input buffer to an output buffer.
extern OSStatus AudioConverterConvertBuffer( AudioConverterRef inAudioConverter, UInt32 inInputDataSize, const void*inInputData, UInt32*ioOutputDataSize, void*outOutputData);
inAudioConverterinInputDataSizeinInputDataioOutputDataSizeoutOutputDataProduces a buffer of output data from an AudioConverter, using the supplied
input buffer.
WARNING: this function will fail for any conversion where there is a
variable relationship between the input and output data buffer sizes. This
includes sample rate conversions and most compressed formats. In these cases,
use AudioConverterFillBuffer. Generally this function is only appropriate for
PCM-to-PCM conversions where there is no sample rate conversion.
AudioConverterDispose |
Destroy an AudioConverter.
extern OSStatus AudioConverterDispose( AudioConverterRef inAudioConverter);
inAudioConverterAn OSStatus result code.
AudioConverterFillBuffer |
Converts data supplied by an input callback function.
extern OSStatus AudioConverterFillBuffer( AudioConverterRef inAudioConverter, AudioConverterInputDataProc inInputDataProc, void*inInputDataProcUserData, UInt32*ioOutputDataSize, void*outOutputData);
inAudioConverterinInputDataProcinInputDataProcUserDataioOutputDataSizeoutOutputDataAn OSStatus result code.
Produces a buffer of output data from an AudioConverter. The supplied input
callback function is called whenever necessary.
NOTE: AudioConverterFillBuffer is limited to simpler conversions
that do not involve multiple deinterleaved buffers or packetized
formats. Use AudioConverterFillComplexBuffer for those cases.
AudioConverterFillComplexBuffer |
Converts data supplied by an input callback function, supporting non-interleaved and packetized formats.
extern OSStatus AudioConverterFillComplexBuffer( AudioConverterRef inAudioConverter, AudioConverterComplexInputDataProc inInputDataProc, void*inInputDataProcUserData, UInt32*ioOutputDataPacketSize, AudioBufferList*outOutputData, AudioStreamPacketDescription*outPacketDescription) ;
inAudioConverterinInputDataProcinInputDataProcUserDataioOutputDataPacketSizeoutOutputDataoutPacketDescriptionAn OSStatus result code.
Produces a buffer list of output data from an AudioConverter. The supplied input callback function is called whenever necessary.
AudioConverterGetProperty |
Returns an AudioConverter property value.
extern OSStatus AudioConverterGetProperty( AudioConverterRef inAudioConverter, AudioConverterPropertyID inPropertyID, UInt32*ioPropertyDataSize, void*outPropertyData);
inAudioConverterinPropertyIDioPropertyDataSizeoutPropertyDataAn OSStatus result code.
AudioConverterGetPropertyInfo |
Returns information about an AudioConverter property.
extern OSStatus AudioConverterGetPropertyInfo( AudioConverterRef inAudioConverter, AudioConverterPropertyID inPropertyID, UInt32*outSize, Boolean*outWritable);
inAudioConverterinPropertyIDoutSizeoutWritableAn OSStatus result code.
AudioConverterNew |
Create a new AudioConverter.
extern OSStatus AudioConverterNew( const AudioStreamBasicDescription*inSourceFormat, const AudioStreamBasicDescription*inDestinationFormat, AudioConverterRef*outAudioConverter);
inSourceFormatinDestinationFormatoutAudioConverterAn OSStatus result code.
For a pair of linear PCM formats, the following conversions
are supported:
AudioConverterNewSpecific |
Create a new AudioConverter using specific codecs.
extern OSStatus AudioConverterNewSpecific( const AudioStreamBasicDescription*inSourceFormat, const AudioStreamBasicDescription*inDestinationFormat, UInt32 inNumberClassDescriptions, AudioClassDescription*inClassDescriptions, AudioConverterRef*outAudioConverter) ;
inSourceFormatinDestinationFormatinNumberClassDescriptionsinClassDescriptionsoutAudioConverterAn OSStatus result code.
This function is identical to AudioConverterNew(), except that the client may explicitly choose which codec to instantiate if there is more than one choice.
AudioConverterReset |
Reset an AudioConverter
extern OSStatus AudioConverterReset( AudioConverterRef inAudioConverter);
inAudioConverterAn OSStatus result code.
Should be called whenever there is a discontinuity in the source audio stream being provided to the converter. This will flush any internal buffers in the converter.
AudioConverterSetProperty |
Sets an AudioConverter property value.
extern OSStatus AudioConverterSetProperty( AudioConverterRef inAudioConverter, AudioConverterPropertyID inPropertyID, UInt32 inPropertyDataSize, const void*inPropertyData);
inAudioConverterinPropertyIDinPropertyDataSizeinPropertyDataAn OSStatus result code.
AudioConverterComplexInputDataProc |
Callback function for supplying input data to AudioConverterFillComplexBuffer.
typedef OSStatus (*AudioConverterComplexInputDataProc)( AudioConverterRef inAudioConverter, UInt32*ioNumberDataPackets, AudioBufferList*ioData, AudioStreamPacketDescription** outDataPacketDescription, void*inUserData);
inAudioConverter- The AudioConverter requesting input.
ioNumberDataPackets- On entry, the minimum number of packets of input audio data the converter would like in order to fulfill its current FillBuffer request. On exit, the number of packets of audio data actually being provided for input, or 0 if there is no more input.
ioData- On exit, the members of ioData should be set to point to the audio data being provided for input.
outDataPacketDescription- If non-null, on exit, the callback is expected to fill this in with an AudioStreamPacketDescription for each packet of input data being provided.
inUserData- The inInputDataProcUserData parameter passed to AudioConverterFillBuffer().
An OSStatus result code.
This callback function supplies input to AudioConverterFillComplexBuffer.
The AudioConverter requests a minimum number of packets (*ioNumberDataPackets).
The callback may return one or more packets. If this is less than than the minimum,
the callback will simply be called again in the near future.
The callback manipulates the members of ioData to point to one or more buffers
of audio data (multiple buffers are used with non-interleaved PCM data). The
callback is responsible for not freeing or altering this buffer until it is
called again.
If the callback returns an error, it must return zero packets of data.
AudioConverterFillComplexBuffer will stop producing output and return whatever
output has already been produced to its caller, along with the error code. This
mechanism can be used when an input proc has temporarily run out of data, but
has not yet reached end of stream.
AudioConverterInputDataProc |
Callback function for supplying input data to AudioConverterFillBuffer.
typedef OSStatus (*AudioConverterInputDataProc)( AudioConverterRef inAudioConverter, UInt32*ioDataSize, void** outData, void*inUserData);
inAudioConverter- The AudioConverter requesting input.
ioDataSize- On entry, the minimum number of bytes of audio data the converter would like in order to fulfill its current FillBuffer request. On exit, the number of bytes of audio data actually being provided for input, or 0 if there is no more input.
outData- On exit, *outData should point to the audio data being provided for input.
inUserData- The inInputDataProcUserData parameter passed to AudioConverterFillBuffer().
An OSStatus result code.
This callback function supplies input to AudioConverterFillBuffer.
The AudioConverter requests a minimum amount of data (*ioDataSize). The callback
may return any amount of data. If it is less than than the minimum, the callback
will simply be called again in the near future.
The callback supplies a pointer to a buffer of audio data. The callback is
responsible for not freeing or altering this buffer until it is called again.
If the callback returns an error, it must return zero bytes of data.
AudioConverterFillBuffer will stop producing output and return whatever output
has already been produced to its caller, along with the error code. This
mechanism can be used when an input proc has temporarily run out of data, but
has not yet reached end of stream.
AudioConverterRef |
A reference to an AudioConverter object.
typedef struct OpaqueAudioConverter * AudioConverterRef;
AudioConverterPrimeInfo |
Specifies priming information.
struct AudioConverterPrimeInfo { UInt32 leadingFrames; UInt32 trailingFrames; };
leadingFrames- Specifies the number of leading (previous) input frames, relative to the normal/desired start input frame, required by the converter to perform a high quality conversion. If using kConverterPrimeMethod_Pre, the client should "pre-seek" the input stream provided through the input proc by leadingFrames. If no frames are available previous to the desired input start frame (because, for example, the desired start frame is at the very beginning of available audio), then provide "leadingFrames" worth of initial zero frames in the input proc. Do not "pre-seek" in the default case of kConverterPrimeMethod_Normal or when using kConverterPrimeMethod_None.
trailingFrames- Specifies the number of trailing input frames (past the normal/expected end input frame) required by the converter to perform a high quality conversion. The client should be prepared to provide this number of additional input frames except when using kConverterPrimeMethod_None. If no more frames of input are available in the input stream (because, for example, the desired end frame is at the end of an audio file), then zero (silent) trailing frames will be synthesized for the client.
When using AudioConverterFillBuffer() (either a single call or a series of calls), some
conversions, particularly involving sample-rate conversion, ideally require a certain
number of input frames previous to the normal start input frame and beyond the end of
the last expected input frame in order to yield high-quality results.
These are expressed in the leadingFrames and trailingFrames members of the structure.
The very first call to AudioConverterFillBuffer(), or first call after
AudioConverterReset(), will request additional input frames beyond those normally
expected in the input proc callback to fulfill this first AudioConverterFillBuffer()
request. The number of additional frames requested, depending on the prime method, will
be approximately:
kConverterPrimeMethod_Pre leadingFrames + trailingFrames
kConverterPrimeMethod_Normal trailingFrames
kConverterPrimeMethod_None 0
AudioConverterPropertyID |
The properties of an AudioConverter, accessible via AudioConverterGetProperty() and AudioConverterSetProperty().
enum // typedef UInt32 AudioConverterPropertyID { kAudioConverterPropertyMinimumInputBufferSize = 'mibs', kAudioConverterPropertyMinimumOutputBufferSize = 'mobs', kAudioConverterPropertyMaximumInputBufferSize = 'xibs', kAudioConverterPropertyMaximumInputPacketSize = 'xips', kAudioConverterPropertyMaximumOutputPacketSize = 'xops', kAudioConverterPropertyCalculateInputBufferSize = 'cibs', kAudioConverterPropertyCalculateOutputBufferSize = 'cobs', kAudioConverterPropertyInputCodecParameters = 'icdp', kAudioConverterPropertyOutputCodecParameters = 'ocdp', kAudioConverterSampleRateConverterAlgorithm = 'srci', kAudioConverterSampleRateConverterQuality = 'srcq', kAudioConverterCodecQuality = 'cdqu', kAudioConverterPrimeMethod = 'prmm', kAudioConverterPrimeInfo = 'prim', kAudioConverterChannelMap = 'chmp', kAudioConverterDecompressionMagicCookie = 'dmgc', kAudioConverterCompressionMagicCookie = 'cmgc', kAudioConverterEncodeBitRate = 'brat', kAudioConverterEncodeAdjustableSampleRate = 'ajsr', kAudioConverterInputChannelLayout = 'icl ', kAudioConverterOutputChannelLayout = 'ocl ', kAudioConverterApplicableEncodeBitRates = 'aebr', kAudioConverterAvailableEncodeBitRates = 'vebr', kAudioConverterApplicableEncodeSampleRates = 'aesr', kAudioConverterAvailableEncodeSampleRates = 'vesr', kAudioConverterAvailableEncodeChannelLayoutTags = 'aecl', kAudioConverterCurrentOutputStreamDescription = 'acod', kAudioConverterCurrentInputStreamDescription = 'acid', kAudioConverterPropertySettings = 'acps', kAudioConverterPropertyBitDepthHint = 'acbd' };
kAudioConverterPropertyMinimumInputBufferSize- a UInt32 that indicates the size in bytes of the smallest buffer of input data that can be supplied via the AudioConverterInputProc or as the input to AudioConverterConvertBuffer
kAudioConverterPropertyMinimumOutputBufferSize- a UInt32 that indicates the size in bytes of the smallest buffer of output data that can be supplied to AudioConverterFillBuffer or as the output to AudioConverterConvertBuffer
kAudioConverterPropertyMaximumInputBufferSize- a UInt32 that indicates the size in bytes of the largest buffer of input data that will be requested from the AudioConverterInputProc. This is mostly useful for variable bit rate compressed data. This will be equal to 0xFFFFFFFF if the maximum value depends on what is requested from the output, which is usually the case for constant bit rate formats.
kAudioConverterPropertyMaximumInputPacketSize- a UInt32 that indicates the size in bytes of the largest single packet of data in the input format. This is mostly useful for variable bit rate compressed data (decoders).
kAudioConverterPropertyMaximumOutputPacketSize- a UInt32 that indicates the size in bytes of the largest single packet of data in the output format. This is mostly useful for variable bit rate compressed data (encoders).
kAudioConverterPropertyCalculateInputBufferSize- a UInt32 that on input holds a size in bytes that is desired for the output data. On output, it will hold the size in bytes of the input buffer required to generate that much output data. Note that some converters cannot do this calculation.
kAudioConverterPropertyCalculateOutputBufferSize- a UInt32 that on input holds a size in bytes that is desired for the input data. On output, it will hold the size in bytes of the output buffer required to hold the output data that will be generated. Note that some converters cannot do this calculation.
kAudioConverterPropertyInputCodecParameters- The value of this property varies from format to format and is considered private to the format. It is treated as a buffer of untyped data.
kAudioConverterPropertyOutputCodecParameters- The value of this property varies from format to format and is considered private to the format. It is treated as a buffer of untyped data.
kAudioConverterSampleRateConverterAlgorithm- DEPRECATED: please use kAudioConverterSampleRateConverterQuality instead
An OSType that specifies the sample rate converter to use (as defined in AudioUnit/AudioUnitProperties.h -- for now only Apple SRC's can be used)kAudioConverterSampleRateConverterQuality- A UInt32 that specifies rendering quality of the sample rate converter (see enum constants below)
kAudioConverterCodecQuality- A UInt32 that specifies rendering quality of a codec (see enum constants below)
kAudioConverterPrimeMethod- a UInt32 specifying priming method (usually for sample-rate converter) see explanation for struct AudioConverterPrimeInfo below along with enum constants
kAudioConverterPrimeInfo- A pointer to AudioConverterPrimeInfo (see explanation for struct AudioConverterPrimeInfo below)
kAudioConverterChannelMap- An array of SInt32's. The size of the array is the number of output channels, and each element specifies which input channel's data is routed to that output channel (using a 0-based index of the input channels), or -1 if no input channel is to be routed to that output channel. The default behavior is as follows. I = number of input channels, O = number of output channels. When I > O, the first O inputs are routed to the first O outputs, and the remaining puts discarded. When O > I, the first I inputs are routed to the first O outputs, and the remaining outputs are zeroed.
A simple example for splitting mono input to stereo output (instead of routing the input to only the first output channel):
// this should be as large as the number of output channels: SInt32 channelMap[2] = { 0, 0 }; AudioConverterSetProperty(theConverter, kAudioConverterChannelMap, sizeof(channelMap), channelMap);kAudioConverterDecompressionMagicCookie- A void * pointing to memory set up by the caller. Required by some formats in order to decompress the input data.
kAudioConverterCompressionMagicCookie- A void * pointing to memory set up by the caller. Returned by the converter so that it may be stored along with the output data. It can then be passed back to the converter for decompression at a later time.
kAudioConverterEncodeBitRate- A UInt32 containing the number of bits per second to aim for when encoding data. This property is only relevant to encoders.
kAudioConverterEncodeAdjustableSampleRate- For encoders where the AudioConverter was created with an output sample rate of zero, and the codec can do rate conversion on its input, this provides a way to set the output sample rate. The property value is a Float64.
kAudioConverterInputChannelLayout- The property value is an AudioChannelLayout.
kAudioConverterOutputChannelLayout- The property value is an AudioChannelLayout.
kAudioConverterApplicableEncodeBitRates- The property value is an array of AudioValueRange describing applicable bit rates based on current settings.
kAudioConverterAvailableEncodeBitRates- The property value is an array of AudioValueRange describing available bit rates based on the input format. You can get all available bit rates from the AudioFormat API.
kAudioConverterApplicableEncodeSampleRates- The property value is an array of AudioValueRange describing applicable sample rates based on current settings.
kAudioConverterAvailableEncodeSampleRates- The property value is an array of AudioValueRange describing available sample rates based on the input format. You can get all available sample rates from the AudioFormat API.
kAudioConverterAvailableEncodeChannelLayoutTags- The property value is an array of AudioChannelLayoutTags for the format and number of channels specified in the input format going to the encoder.
kAudioConverterCurrentOutputStreamDescription- Returns the current completely specified output AudioStreamBasicDescription. For example when encoding to AAC, your original output stream description will not have been completely filled out.
kAudioConverterCurrentInputStreamDescription- Returns the current completely specified input AudioStreamBasicDescription.
kAudioConverterPropertySettings- Returns the a CFArray of property settings for converters.
kAudioConverterPropertyBitDepthHint- A UInt32 of the source bit depth to preserve. This is a hint to some encoders like lossless about how many bits to preserve in the input. The converter usually tries to preserve as many as possible, but a lossless encoder will do poorly if more bits are supplied than are desired in the output.
Prime method constants |
Constants to be used with kAudioConverterPrimeMethod.
enum { kConverterPrimeMethod_Pre = 0, kConverterPrimeMethod_Normal = 1, kConverterPrimeMethod_None = 2 };
kConverterPrimeMethod_Pre- Primes with leading + trailing input frames.
kConverterPrimeMethod_Normal- Only primes with trailing (zero latency). Leading frames are assumed to be silence.
kConverterPrimeMethod_None- Acts in "latency" mode. Both leading and trailing frames assumed to be silence.
Quality constants |
Constants to be used with kAudioConverterSampleRateConverterQuality.
enum { kAudioConverterQuality_Max = 0x7F, kAudioConverterQuality_High = 0x60, kAudioConverterQuality_Medium = 0x40, kAudioConverterQuality_Low = 0x20, kAudioConverterQuality_Min = 0 };
kAudioConverterQuality_Max- maximum quality
kAudioConverterQuality_High- high quality
kAudioConverterQuality_Medium- medium quality
kAudioConverterQuality_Low- low quality
kAudioConverterQuality_Min- minimum quality
|