Audio Converter Services Reference

Framework	AudioToolbox/AudioToolbox.h
Declared in	AudioConverter.h

Overview

Audio converter objects convert between various linear PCM audio formats. They can also convert between linear PCM and compressed formats. Supported transformations include the following:

PCM bit depth
PCM sample rate
PCM floating point to and from PCM integer
PCM interleaved to and from PCM deinterleaved
PCM to and from compressed formats

A single audio converter may perform more than one of the listed transformations.

Functions by Task

Managing Audio Converter Objects

Configuring Audio Converter Properties

Performing Conversions

Functions

AudioConverterConvertBuffer

Converts audio data from one linear PCM format to another.

OSStatus AudioConverterConvertBuffer (
   AudioConverterRef  inAudioConverter,
   UInt32             inInputDataSize,
   const void         *inInputData,
   UInt32             *ioOutputDataSize,
   void               *outOutputData
);

Parameters

inAudioConverter: The audio converter to use for format conversion.
inInputDataSize: The size, in bytes, of the audio data input buffer.
inInputData: The audio data to convert.
ioOutputDataSize: On input, the size, in bytes, of the buffer available for the converted data. On output, the number of bytes written to the output buffer (pointed to by the outOutputData parameter).
outOutputData: On output, the converted audio data.

Return Value

A result code.

Discussion

This function is for the special case of converting from one linear PCM format to another. This function cannot perform sample rate conversions and cannot be used for conversion to or from most compressed formats. To perform these types of conversion, use AudioConverterFillComplexBuffer instead.

Availability

Available in iOS 2.1 and later.

Declared In

AudioConverter.h

AudioConverterConvertComplexBuffer

Converts audio data from one linear PCM format to another, where both use the same sample rate.

OSStatus AudioConverterConvertComplexBuffer (
   AudioConverterRef      inAudioConverter,
   UInt32                 inNumberPCMFrames,
   const AudioBufferList  *inInputData,
   AudioBufferList        *outOutputData
);

Parameters

inAudioConverter: The audio converter to use for the format conversion.
inNumberPCMFrames: The number of linear PCM frames to convert.
inInputData: The source audio buffer list.
outOutputData: The destination audio buffer list.

Return Value

A result code.

Discussion

This function is appropriate for linear PCM-to-linear PCM audio data format conversion where there is no sample rate conversion.

Availability

Available in iOS 5.0 and later.

Related Sample Code

aurioTouch2

Declared In

AudioConverter.h

AudioConverterDispose

Disposes of an audio converter object.

OSStatus AudioConverterDispose (
   AudioConverterRef inAudioConverter
);

Parameters

inAudioConverter: The audio converter object to dispose of.

Return Value

A result code.

Discussion

Availability

Available in iOS 2.1 and later.

Related Sample Code

iPhoneACFileConvertTest

Declared In

AudioConverter.h

AudioConverterFillComplexBuffer

Converts audio data supplied by a callback function, supporting non-interleaved and packetized formats.

OSStatus AudioConverterFillComplexBuffer(
   AudioConverterRef                   inAudioConverter,
   AudioConverterComplexInputDataProc  inInputDataProc,
   void                                *inInputDataProcUserData,
   UInt32                              *ioOutputDataPacketSize,
   AudioBufferList                     *outOutputData,
   AudioStreamPacketDescription        *outPacketDescription
);

Parameters

inAudioConverter: The audio converter to use for format conversion.
inInputDataProc: A callback function that supplies audio data to convert. This callback is invoked repeatedly as the converter is ready for new input data.
inInputDataProcUserData: Custom data for use by your application when receiving a callback invocation.
ioOutputDataPacketSize: On input, the size of the output buffer (in the outOutputData parameter), expressed in number packets in the audio converter’s output format. On output, the number of packets of converted data that were written to the output buffer.
outOutputData: On output, the converted audio data.
outPacketDescription: On input, must point to a block of memory capable of holding the number of packet descriptions specified in the ioOutputDataPacketSize parameter. (See Audio Format Services Reference for functions that let you determine whether an audio format uses packet descriptions). If not NULL on output and if the audio converter’s output format uses packet descriptions, then this parameter contains an array of packet descriptions.

Return Value

A result code.

Discussion

Use this function for all audio data format conversions except for the special case of converting from one linear PCM format to another with no sample rate conversion.

Availability

Available in iOS 2.1 and later.

Related Sample Code

iPhoneACFileConvertTest

Declared In

AudioConverter.h

AudioConverterGetProperty

Gets an audio converter property value.

OSStatus AudioConverterGetProperty (
   AudioConverterRef         inAudioConverter,
   AudioConverterPropertyID  inPropertyID,
   UInt32                    *ioPropertyDataSize,
   void                      *outPropertyData
);

Parameters

inAudioConverter: The audio converter to get a property value from.
inPropertyID: The property whose value you want.
ioPropertyDataSize: On input, the size of the memory pointed to by the outPropertyData parameter. On output, the size of the property value.
outPropertyData: On output, the property value you wanted to get.

Return Value

A result code.

Special Considerations

Some Core Audio property values are C types and others are Core Foundation objects.

If you call this function to retrieve a value that is a Core Foundation object, then this function—despite the use of “Get” in its name—duplicates the object. You are responsible for releasing the object, as described in “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability

Available in iOS 2.1 and later.

Related Sample Code

Declared In

AudioConverter.h

AudioConverterGetPropertyInfo

Gets information about an audio converter property.

OSStatus AudioConverterGetPropertyInfo (
   AudioConverterRef         inAudioConverter,
   AudioConverterPropertyID  inPropertyID,
   UInt32                    *outSize,
   Boolean                   *outWritable
);

Parameters

inAudioConverter: The audio converter to get property information from.
inPropertyID: The property you want information about.
outSize: On output, the size of the property value in bytes. Can be NULL on output.
outWritable: On output, a Boolean value indicating whether the property value is writable (true) or not (false). Can be NULL on output.

Return Value

A result code.

Availability

Available in iOS 2.1 and later.

Related Sample Code

iPhoneACFileConvertTest

Declared In

AudioConverter.h

AudioConverterNew

Creates a new audio converter object based on specified audio formats.

OSStatus AudioConverterNew (
   const AudioStreamBasicDescription    *inSourceFormat,
   const AudioStreamBasicDescription    *inDestinationFormat,
   AudioConverterRef                    *outAudioConverter
);

Parameters

inSourceFormat: The format of the source audio to be converted.
inDestinationFormat: The destination format to which the audio is to be converted.
outAudioConverter: On return, a new audio converter object.

Return Value

A result code.

Discussion

For a pair of linear PCM formats, the following conversions are supported:

Addition and removal of channels, when the input and output format mChannelsPerFrame fields do not match. Channels may also be reordered and removed using the kAudioConverterChannelMap property.
Sample rate conversion.
Interleaving and deinterleaving, when the input and output format (mFormatFlags & kAudioFormatFlagIsNonInterleaved) values do not match.
Conversion between any pair of the following formats:
- 8-bit integer, signed or unsigned.
- 16-, 24-, or 32-bit integer, big- or little-endian. Other integral bit depths, if high-aligned and nonpacked, are also supported
- 32- and 64-bit floating point, big- or little-endian.

Encoding and decoding between linear PCM and compressed formats is supported. Functions in Audio Format Services (AudioToolbox/AudioFormat.h) return information about the formats supported on a system. When using a codec, you can use any supported PCM format. The converter object performs any necessary additional conversion between your PCM format and the one created or consumed by the codec.

Availability

Available in iOS 2.1 and later.

Related Sample Code

Declared In

AudioConverter.h

AudioConverterNewSpecific

Creates a new audio converter object using a specified codec.

OSStatus AudioConverterNewSpecific (
   const AudioStreamBasicDescription  *inSourceFormat,
   const AudioStreamBasicDescription  *inDestinationFormat,
   UInt32                             inNumberClassDescriptions,
   AudioClassDescription              *inClassDescriptions,
   AudioConverterRef                  *outAudioConverter
);

Parameters

inSourceFormat: The format of the source audio to be converted.
inDestinationFormat: The destination format to which the audio is to be converted.
inNumberClassDescriptions: The number of class descriptions supplied in the inClassDescriptions parameter.
inClassDescriptions: A list of AudioClassDescription objects that specify the codec to use.
outAudioConverter: On return, a new audio converter object.

Return Value

A result code.

Discussion

This function is identical to AudioConverterNew function, except that your application may explicitly choose which codec to instantiate if there is more than one choice.

Availability

Available in iOS 2.1 and later.

Declared In

AudioConverter.h

AudioConverterReset

Resets an audio converter object, clearing and flushing its buffers.

OSStatus AudioConverterReset (
   AudioConverterRef inAudioConverter
);

Parameters

inAudioConverter: The audio converter object to reset.

Return Value

A result code.

Discussion

Call this function after a discontinuity in the source audio stream being provided to the converter.

Availability

Available in iOS 2.1 and later.

Declared In

AudioConverter.h

AudioConverterSetProperty

Sets the value of an audio converter object property.

OSStatus AudioConverterSetProperty (
   AudioConverterRef        inAudioConverter,
   AudioConverterPropertyID inPropertyID,
   UInt32                   inPropertyDataSize,
   const void               *inPropertyData
);

Parameters

inAudioConverter: The audio converter to set a property value on.
inPropertyID: The property whose value you want to set.
inPropertyDataSize: The size, in bytes, of the property value.
inPropertyData: The value you want to apply to the specified property.

Return Value

A result code.

Discussion

You can employ the property mechanism, for example, to split a monaural input to both channels of a stereo output. You would do this as follows:

 SInt32 channelMap[2] = {0, 0}; // array size should match the number of output channels

 AudioConverterSetProperty (

    theConverter,

    kAudioConverterChannelMap,

    sizeof(channelMap),

    channelMap

);

Availability

Available in iOS 2.1 and later.

Related Sample Code

Declared In

AudioConverter.h

Callbacks by Task

Providing Audio Data to a Converter

Deprecated Callbacks

Callbacks

AudioConverterComplexInputDataProc

Supplies input data to the AudioConverterFillComplexBuffer function.

typedef OSStatus (*AudioConverterComplexInputDataProc) (
   AudioConverterRef             inAudioConverter,
   UInt32                        *ioNumberDataPackets,
   AudioBufferList               *ioData,
   AudioStreamPacketDescription  **outDataPacketDescription,
   void                          *inUserData
);

If you named your callback function MyAudioConverterComplexInputDataProc, you would declare it like this:

OSStatus AudioConverterComplexInputDataProc (
   AudioConverterRef             inAudioConverter,
   UInt32                        *ioNumberDataPackets,
   AudioBufferList               *ioData,
   AudioStreamPacketDescription  **outDataPacketDescription,
   void                          *inUserData
);

Parameters

inAudioConverter: The audio converter object that invoked this callback to obtain new data to convert.
ioNumberDataPackets: On input, the minimum number of packets of input audio data the converter needs for its current conversion cycle. On output, the number of packets of audio data provided for conversion, or 0 if there is no more data to convert.
ioData: On output, point the fields of the AudioBufferList structure, passed by this parameter, to the audio data you are providing to be converted.
outDataPacketDescription: If not NULL on input, the audio converter expects this callback to provide an array of AudioStreamPacketDescription structures on output, one for each packet of audio data you are providing in the ioData parameter.
inUserData: On input, the custom application data you provided to the AudioConverterFillComplexBuffer function.

Discussion

This callback supplies input audio data to the AudioConverterFillComplexBuffer function.

The audio converter object requests a minimum number of packets in the ioNumberDataPackets parameter. Your callback may provide one or more packets. If the number you provide is less than the minimum requested, the converter will invoke your callback again in the near future.

You write your callback to manipulate the fields of the AudioBufferList structure, in the ioData parameter, to point to one or more buffers of audio data. You use a single buffer for interleaved PCM data, or multiple buffers for non-interleaved PCM data. Your callback is responsible for not freeing or altering the buffer(s) until invoked again.

If your callback returns an error, it must return zero packets of data. Upon receiving zero packets, the AudioConverterFillComplexBuffer function delivers any pending output, stops producing further output, and returns the error code. You can use this mechanism when an input callback has temporarily run out of data but has not yet reached the end of the input audio stream.

Availability

Available in iOS 2.1 and later.

Declared In

AudioConverter.h

AudioConverterInputDataProc

Deprecated. Use AudioConverterFillComplexBuffer instead.

   
typedef OSStatus (*AudioConverterInputDataProc) (
   AudioConverterRef    inAudioConverter,
   UInt32               *ioDataSize,
   void                 **outData,
   void                 *inUserData
);

If you named your callback function MyAudioConverterInputDataProc, you would declare it like this:

OSStatus MyAudioConverterInputDataProc (
   AudioConverterRef    inAudioConverter,
   UInt32               *ioDataSize,
   void                 **outData,
   void                 *inUserData
);

Discussion

This deprecated callback supplies input data to the AudioConverterFillBuffer function. Use AudioConverterComplexInputDataProc instead.

Availability

Available in iOS 2.1 and later.

Declared In

AudioConverter.h

Data Types

AudioConverterPrimeInfo

Specifies priming information for an audio converter, used as a value for the kAudioConverterPrimeInfo property.

struct AudioConverterPrimeInfo {
   UInt32 leadingFrames;
   UInt32 trailingFrames;
};
typedef struct AudioConverterPrimeInfo AudioConverterPrimeInfo;

Fields

leadingFrames: The number of leading frames of input audio data required for the converter to perform high-quality conversion. This number is determined by the input audio format. Leading frames precede, in time, the desired starting input frame. If using the kConverterPrimeMethod_Pre value for the kAudioConverterPrimeMethod property, your application should provide the specified number of leading frames from the the input stream when your input callback is first invoked. If no leading frames are available (because, for example, the desired start frame is at the very beginning of available audio), then your callback should provide the requested number of silent (0-valued) leading frames. Your callback should not provide a value for the leadingFrames field when the kAudioConverterPrimeMethod property value is kConverterPrimeMethod_Normal or kConverterPrimeMethod_None.
trailingFrames: The number of trailing frames of input audio data required by the converter to perform high-quality conversion. Trailing frames follow, in time, the expected final input frame. Your application should be prepared to provide this number of additional input frames except when using the kConverterPrimeMethod_None value for the kAudioConverterPrimeMethod property. If no additional frames are available in the input stream (because, for example, the desired end frame is at the end of an audio file), then the audio converter synthesizes a sufficient number of silent (0-valued) trailing frames.

Discussion

Some audio data format conversions, particularly those involving sample-rate conversion, yield higher quality output when leading or trailing frames are available to the converter. The appropriate number of these so-called priming frames depends on the input audio data format.

You specify leading or trailing frames in the leadingFrames and trailingFrames fields of an AudioConverterPrimeInfo structure. You then configure your audio converter by calling the AudioConverterSetProperty function for the kAudioConverterPrimeInfo property, specifying this structure as the property value. You also indicate to the converter which priming option to use by setting the kAudioConverterPrimeMethod property.

When you configure an audio converter by specifying leading or trailing frames, you alter the behavior of the AudioConverterFillComplexBuffer function. The very first call to that function, or the first call after calling AudioConverterReset, results in a request for additional input frames when the converter object invokes your AudioConverterComplexInputDataProc callback. The number of priming frames requested depends on the priming option you specify, as shown in Table 1.

**Table 1** Priming options and priming frames
Priming option	Number of priming frames (approximate)
`kConverterPrimeMethod_Pre`	`leadingFrames` + `trailingFrames`
`kConverterPrimeMethod_Normal`	`trailingFrames`
`kConverterPrimeMethod_None`	`0`

The default priming option is that specified by the kConverterPrimeMethod_Normal constant. This option requires no preseeking of the input stream. It generates trailingFrames of latency at output.

The kConverterPrimeMethod_Pre priming option results in a first invocation of your callback that asks for approximately leadingFrames + trailingFrames priming frames. Latency at output will correspond, approximately, to this duration.

The kConverterPrimeMethod_None priming constant is especially useful in real-time applications that process live input. This option minimizes output latency, but is appropriate only for formats that do not require priming frames.

In a digital audio workstation, the kConverterPrimeMethod_Pre option may be preferable for real-time applications. This is because your application may be able to provide priming frames by preloading them from disk or memory, avoiding latency while still supporting audio formats that require priming.

Availability

Available in iOS 2.1 and later.

Declared In

AudioConverter.h

AudioConverterRef

A reference to an audio converter object.

typedef struct OpaqueAudioConverter *AudioConverterRef;

Availability

Available in iOS 2.1 and later.

Declared In

AudioConverter.h

AudioConverterPropertyID

An audio converter property identifier.

typedef UInt32 AudioConverterPropertyID;

Availability

Available in iOS 2.1 and later.

Declared In

AudioConverter.h

Constants

Audio Converter Properties

Audio converter properties, used with the AudioConverterGetPropertyInfo, AudioConverterGetProperty, and AudioConverterSetProperty functions.

enum {
   kAudioConverterPropertyMinimumInputBufferSize    = 'mibs',
   kAudioConverterPropertyMinimumOutputBufferSize   = 'mobs',
   kAudioConverterPropertyMaximumInputBufferSize    = 'xibs',
   kAudioConverterPropertyMaximumInputPacketSize    = 'xips',
   kAudioConverterPropertyMaximumOutputPacketSize   = 'xops',
   kAudioConverterPropertyCalculateInputBufferSize  = 'cibs',
   kAudioConverterPropertyCalculateOutputBufferSize = 'cobs',
   kAudioConverterPropertyInputCodecParameters      = 'icdp',
   kAudioConverterPropertyOutputCodecParameters     = 'ocdp',
   kAudioConverterSampleRateConverterAlgorithm      = 'srci',
   kAudioConverterSampleRateConverterComplexity     = 'srca',
   kAudioConverterSampleRateConverterQuality        = 'srcq',
   kAudioConverterSampleRateConverterInitialPhase   = 'srcp',
   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',
   kAudioConverterPropertyFormatList                = 'flst'
   kAudioConverterPropertyCanResumeFromInterruption = 'crfi'
};

Constants

kAudioConverterPropertyMinimumInputBufferSize

A UInt32 value that indicates the size, in bytes, of the smallest buffer of input data that can be supplied via the audio converter input callback or as the input to the AudioConverterConvertBuffer function.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyMinimumOutputBufferSize

A UInt32 value that indicates the size, in bytes, of the smallest buffer of output data that can be supplied to AudioConverterFillComplexBuffer or as the output to AudioConverterConvertBuffer

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyMaximumInputBufferSize

Deprecated. The audio converter input callback may be passed any number of packets of data. If fewer are packets are returned than required, then the input proc is called again. If more packets are passed than required, they remain in the client's buffer and are consumed as needed.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyMaximumInputPacketSize

A UInt32 value 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).

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyMaximumOutputPacketSize

A UInt32 value 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).

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyCalculateInputBufferSize

A UInt32 value that on input holds a size, in bytes, that is desired for the output data. On output, it holds the size, in bytes, of the input buffer required to generate that much output data. Note that some converters cannot do this calculation.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyCalculateOutputBufferSize

A UInt32 value that on input holds a size, in bytes, that is desired for the input data. On output, it holds the size, in bytes, of the output buffer required to hold the output data to be generated. Some converters cannot do this calculation.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

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.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

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.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterSampleRateConverterAlgorithm

Deprecated. Use kAudioConverterSampleRateConverterComplexity instead.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterSampleRateConverterComplexity

The sample rate conversion algorithm, specified using a constant from “Sample Rate Conversion Complexity Identifiers.”

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterSampleRateConverterQuality

The rendering quality of the sample rate converter, specified using a constant from “Sample Rate Conversion Quality Identifiers.” See also kAudioConverterSampleRateConverterComplexity.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterSampleRateConverterInitialPhase

A Float64 value equal to 0.0.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterCodecQuality

The rendering quality of a codec. A UInt32 value.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPrimeMethod

The priming method, usually for sample-rate conversion. See AudioConverterPrimeInfo and “Converter Priming Constants.”

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPrimeInfo

An AudioConverterPrimeInfo structure.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterChannelMap

An array of SInt32 values that specify an input-to-output channel mapping.

The size of the array is the number of output channels. Each element specifies, using a 0-based index, which input channel’s data is routed to that output channel. A value of -1 indicates that no input channel is to be routed to that output channel.

The default behavior is as follows. Given that In = the number of input channels and Out = the number of output channels. When In > Out, the first Out inputs are routed to the first Out outputs, and the remaining inputs are discarded. When Out > In, the first In inputs are routed to the first Out outputs, and the remaining outputs are zeroed.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterDecompressionMagicCookie

A void* value that points to memory set up by the caller. This property is required by some audio data formats in order to decompress the input data.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterCompressionMagicCookie

A void* value that points to memory set up by the caller. This property is returned by the converter so that your application may store it along with the output data. This property can then be passed back to the converter for decompression at a later time.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterEncodeBitRate

A UInt32 value containing the number of bits per second to aim for when encoding data. Some decoders also allow you to query this property to discover the bit rate.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterEncodeAdjustableSampleRate

A Float64 value that specifies an output sample rate.

For encoding audio converters a) with a specified output sample rate of 0 and b) that are capable of performing sample rate conversion on the input data, this property provides a way to set output sample rate.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterInputChannelLayout

An AudioChannelLayout structure that specifies an audio converter’s input channel layout.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterOutputChannelLayout

An AudioChannelLayout structure that specifies an audio converter’s output channel layout.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterApplicableEncodeBitRates

An array of AudioValueRange structures that describes applicable bit rates based on current settings.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterAvailableEncodeBitRates

An array of AudioValueRange structures that describes the available bit rates based on the input format. You can determine the available bit rates using Audio Format Services.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterApplicableEncodeSampleRates

An array of AudioValueRange structures that describes applicable sample rates based on current settings.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterAvailableEncodeSampleRates

An array of AudioValueRange structures that describes the available sample rates based on the input format. You can determine the available sample rates using Audio Format Services.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterAvailableEncodeChannelLayoutTags

An array of AudioChannelLayoutTag values for the format and number of channels specified in the encoder’s input format.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterCurrentOutputStreamDescription

The current, completely specified output AudioStreamBasicDescription structure.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterCurrentInputStreamDescription

The current, completely specified input AudioStreamBasicDescription structure.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertySettings

An array (of type CFArray) of property settings for converters.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyBitDepthHint

A UInt32 value that designates the source bit depth to preserve.

This is a hint used by some encoders, such as the Apple lossless encoder. The converter usually tries to preserve as many bits as possible. A lossless encoder does poorly if more bits are supplied than are desired in the output.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyFormatList

An array of AudioFormatListItem structures that describes the set of data formats produced by the encoder end of an audio converter.

If the ioPropertyDataSize parameter of the AudioConverterGetProperty function indicates that the size of the data in the outPropertyData parameter is sizeof (AudioFormatListItem), then only the best format is returned. This property may be used, for example, to discover all the data formats produced by the AAC High Efficiency version 2 encoder (specified by the kAudioFormatMPEG4AAC_HE_V2 constant).

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertyCanResumeFromInterruption

Indicates whether the underlying codec supports resumption of processing following an audio interruption. A read-only UInt32 value.

If the property’s value is 1, the codec can resume work following an audio interruption. If the property’s value is 0, audio interruptions destroy the codec’s state.

If the property is unimplemented (in which case, a call to the AudioConverterGetProperty function for this property returns an error), then the codec is not a hardware codec.

Available in iOS 3.1 and later.

Declared in AudioConverter.h.

Converter Priming Constants

Constants used with the kAudioConverterPrimeMethod property.

enum {
   kConverterPrimeMethod_Pre     = 0,
   kConverterPrimeMethod_Normal  = 1,
   kConverterPrimeMethod_None    = 2
};

Constants

kConverterPrimeMethod_Pre

Prime with leading + trailing input frames.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kConverterPrimeMethod_Normal

Prime with trailing frames only, for zero latency. Leading frames are assumed to be silence.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kConverterPrimeMethod_None

Acts in “latency” mode. Leading and trailing frames are both assumed to be silence.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

Sample Rate Conversion Quality Identifiers

Specifiers for sample rate conversion quality, used for the kAudioConverterSampleRateConverterQuality property.

enum {
   kAudioConverterQuality_Max     = 0x7F,
   kAudioConverterQuality_High    = 0x60,
   kAudioConverterQuality_Medium  = 0x40,
   kAudioConverterQuality_Low     = 0x20,
   kAudioConverterQuality_Min     = 0
};

Constants

kAudioConverterQuality_Max

Specifies maximum sample-rate conversion quality.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterQuality_High

Specifies high sample rate conversion quality.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterQuality_Medium

Specifies medium sample rate conversion quality.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterQuality_Low

Specifies low sample rate conversion quality.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterQuality_Min

Specifies minimum sample rate conversion quality.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

Discussion

Higher-quality sample-rate conversions entail higher processing cost.

Sample Rate Conversion Complexity Identifiers

Specifiers for the sample rate conversion algorithm, used for the kAudioConverterSampleRateConverterComplexity property.

enum {
   kAudioConverterSampleRateConverterComplexity_Linear     = 'line',
   kAudioConverterSampleRateConverterComplexity_Normal     = 'norm',
   kAudioConverterSampleRateConverterComplexity_Mastering  = 'bats',
};

Constants

kAudioConverterSampleRateConverterComplexity_Linear

Specifies linear interpolation for sample rate conversion. This provides the lowest quality and is, computationally, the least expensive option.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterSampleRateConverterComplexity_Normal

Specifies the normal-complexity sample rate conversion algorithm. This is the default value.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterSampleRateConverterComplexity_Mastering

Specifies a mastering-quality sample rate conversion algorithm. This provides the highest quality and is, computationally, the most expensive option.

Available in iOS 2.1 and later.

Declared in AudioConverter.h.

Result Codes

This table lists result codes defined for Audio Converter Services.

Result Code	Value	Description
`kAudioConverterErr_FormatNotSupported`	'fmt?'	Available in iOS 2.1 and later.
`kAudioConverterErr_OperationNotSupported`	0x6F703F3F	Available in iOS 2.1 and later.
`kAudioConverterErr_PropertyNotSupported`	'prop'	Available in iOS 2.1 and later.
`kAudioConverterErr_InvalidInputSize`	'insz'	Available in iOS 2.1 and later.
`kAudioConverterErr_InvalidOutputSize`	'otsz'	The byte size is not an integer multiple of the frame size. Available in iOS 2.1 and later.
`kAudioConverterErr_UnspecifiedError`	'what'	Available in iOS 2.1 and later.
`kAudioConverterErr_BadPropertySizeError`	'!siz'	Available in iOS 2.1 and later.
`kAudioConverterErr_RequiresPacketDescriptionsError`	'!pkd'	Available in iOS 2.1 and later.
`kAudioConverterErr_InputSampleRateOutOfRange`	'!isr'	Available in iOS 2.1 and later.
`kAudioConverterErr_OutputSampleRateOutOfRange`	!osr'	Available in iOS 2.1 and later.
`kAudioConverterErr_HardwareInUse`	'hwiu'	Returned from the `AudioConverterFillComplexBuffer` function if the underlying hardware codec has become unavailable, probably due to an audio interruption. On receiving this error, your application must stop calling `AudioConverterFillComplexBuffer`. You can check the value of the `kAudioConverterPropertyCanResumeFromInterruption` property to determine if the converter you are using can resume processing after an interruption. If so, then wait for an interruption-ended call from Audio Session Services, reactivate the audio session, and finally resume using the codec. If the converter cannot resume processing after an interruption, then on interruption you must abandon the conversion, re-instantiate the converter, and perform the conversion again. Available in iOS 3.1 and later.
`kAudioConverterErr_NoHardwarePermission`	‘perm’	Returned from the `AudioConverterNew` function if the new converter would use a hardware codec which the application does not have permission to use. Available in iOS 4.3 and later.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Audio Converter Services Reference

Overview

Functions by Task

Managing Audio Converter Objects

Configuring Audio Converter Properties

Performing Conversions

Functions

AudioConverterConvertBuffer

Parameters

Return Value

Discussion

Availability

Declared In

AudioConverterConvertComplexBuffer

Parameters

Return Value

Discussion

Availability

Related Sample Code

Declared In

AudioConverterDispose

Parameters

Return Value

Discussion

Availability

Related Sample Code

Declared In

AudioConverterFillComplexBuffer

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

AudioConverterGetProperty

Parameters

Return Value

Special Considerations

Availability

See Also

Related Sample Code

Declared In

AudioConverterGetPropertyInfo

Parameters

Return Value

Availability

See Also

Related Sample Code

Declared In

AudioConverterNew

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

AudioConverterNewSpecific

Parameters

Return Value

Discussion

Availability

See Also

Declared In

AudioConverterReset

Parameters

Return Value

Discussion

Availability

Declared In

AudioConverterSetProperty

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

Callbacks by Task