Audio Converter Services Reference

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

• AudioConverterDispose
• AudioConverterNew
• AudioConverterNewSpecific
• AudioConverterReset

Configuring Audio Converter Properties

• AudioConverterGetProperty
• AudioConverterGetPropertyInfo
• AudioConverterSetProperty

Performing Conversions

• AudioConverterConvertBuffer
• AudioConverterFillComplexBuffer

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.

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.

AudioConverterDispose

Disposes of an audio converter object.

OSStatus AudioConverterDispose (
   AudioConverterRef inAudioConverter
);

Parameters

inAudioConverter

The audio converter object to dispose of.

Discussion

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.

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.

See Also

• AudioConverterConvertBuffer

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.

See Also

• AudioConverterGetPropertyInfo
• AudioConverterSetProperty

Related Sample Code

• iPhoneExtAudioFileConvertTest

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.

See Also

• AudioConverterGetProperty
• AudioConverterSetProperty

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.

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.

See Also

• AudioConverterDispose
• AudioConverterNewSpecific

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 specifiy the codec to use.

outAudioConverter

On return, a new audio converter object.

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.

See Also

• AudioConverterDispose
• AudioConverterNew

AudioConverterReset

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

OSStatus AudioConverterReset (
   AudioConverterRef inAudioConverter
);

Parameters

inAudioConverter

The audio converter object to reset.

Discussion

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

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.

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

);

See Also

• AudioConverterGetProperty
• AudioConverterGetPropertyInfo

Callbacks by Task

Providing Audio Data to a Converter

• AudioConverterComplexInputDataProc

Deprecated Callbacks

• AudioConverterInputDataProc

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 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.

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.

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.

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.

AudioConverterRef

A reference to an audio converter object.

typedef struct OpaqueAudioConverter *AudioConverterRef;

AudioConverterPropertyID

An audio converter property identifier.

typedef UInt32 AudioConverterPropertyID;

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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterSampleRateConverterAlgorithm

Deprecated. Use kAudioConverterSampleRateConverterComplexity instead.

Available in iPhone OS 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 iPhone OS 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 iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterSampleRateConverterInitialPhase

A Float64 value equal to 0.0.

Available in iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterCodecQuality

The rendering quality of a codec. A UInt32 value.

Available in iPhone OS 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 iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPrimeInfo

An AudioConverterPrimeInfo structure.

Available in iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterInputChannelLayout

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

Available in iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterOutputChannelLayout

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

Available in iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterCurrentOutputStreamDescription

The current, completely specified output AudioStreamBasicDescription structure.

Available in iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterCurrentInputStreamDescription

The current, completely specified input AudioStreamBasicDescription structure.

Available in iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterPropertySettings

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

Available in iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterQuality_High

Specifies high sample rate conversion quality.

Available in iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterQuality_Medium

Specifies medium sample rate conversion quality.

Available in iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterQuality_Low

Specifies low sample rate conversion quality.

Available in iPhone OS 2.1 and later.

Declared in AudioConverter.h.

kAudioConverterQuality_Min

Specifies minimum sample rate conversion quality.

Available in iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 2.1 and later.

Declared in AudioConverter.h.

Result Codes

This table lists result codes defined for Audio Converter Services.