iOS Developer Library

Developer

AudioToolbox Framework Reference Audio Converter Services Reference

Options
Deployment Target:

On This Page
Language:

Audio Converter Services Reference

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

  • Disposes of an audio converter object.

    Declaration

    Swift

    func AudioConverterDispose(_ inAudioConverter: AudioConverterRef) -> OSStatus

    Objective-C

    OSStatus AudioConverterDispose ( AudioConverterRef inAudioConverter );

    Parameters

    inAudioConverter

    The audio converter object to dispose of.

    Return Value

    A result code.

    Discussion

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func AudioConverterNew(_ inSourceFormat: UnsafePointer<AudioStreamBasicDescription>, _ inDestinationFormat: UnsafePointer<AudioStreamBasicDescription>, _ outAudioConverter: UnsafeMutablePointer<AudioConverterRef>) -> OSStatus

    Objective-C

    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.

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Creates a new audio converter object using a specified codec.

    Declaration

    Swift

    func AudioConverterNewSpecific(_ inSourceFormat: UnsafePointer<AudioStreamBasicDescription>, _ inDestinationFormat: UnsafePointer<AudioStreamBasicDescription>, _ inNumberClassDescriptions: UInt32, _ inClassDescriptions: UnsafePointer<AudioClassDescription>, _ outAudioConverter: UnsafeMutablePointer<AudioConverterRef>) -> OSStatus

    Objective-C

    OSStatus AudioConverterNewSpecific ( const AudioStreamBasicDescription *inSourceFormat, const AudioStreamBasicDescription *inDestinationFormat, UInt32 inNumberClassDescriptions, const 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.

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func AudioConverterReset(_ inAudioConverter: AudioConverterRef) -> OSStatus

    Objective-C

    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.

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Gets an audio converter property value.

    Declaration

    Swift

    func AudioConverterGetProperty(_ inAudioConverter: AudioConverterRef, _ inPropertyID: AudioConverterPropertyID, _ ioPropertyDataSize: UnsafeMutablePointer<UInt32>, _ outPropertyData: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Gets information about an audio converter property.

    Declaration

    Swift

    func AudioConverterGetPropertyInfo(_ inAudioConverter: AudioConverterRef, _ inPropertyID: AudioConverterPropertyID, _ outSize: UnsafeMutablePointer<UInt32>, _ outWritable: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    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.

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Sets the value of an audio converter object property.

    Declaration

    Swift

    func AudioConverterSetProperty(_ inAudioConverter: AudioConverterRef, _ inPropertyID: AudioConverterPropertyID, _ inPropertyDataSize: UInt32, _ inPropertyData: UnsafePointer<Void>) -> OSStatus

    Objective-C

    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
    • );

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Converts audio data from one linear PCM format to another.

    Declaration

    Swift

    func AudioConverterConvertBuffer(_ inAudioConverter: AudioConverterRef, _ inInputDataSize: UInt32, _ inInputData: UnsafePointer<Void>, _ ioOutputDataSize: UnsafeMutablePointer<UInt32>, _ outOutputData: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func AudioConverterFillComplexBuffer(_ inAudioConverter: AudioConverterRef, _ inInputDataProc: AudioConverterComplexInputDataProc, _ inInputDataProcUserData: UnsafeMutablePointer<Void>, _ ioOutputDataPacketSize: UnsafeMutablePointer<UInt32>, _ outOutputData: UnsafeMutablePointer<AudioBufferList>, _ outPacketDescription: UnsafeMutablePointer<AudioStreamPacketDescription>) -> OSStatus

    Objective-C

    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.

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func AudioConverterConvertComplexBuffer(_ inAudioConverter: AudioConverterRef, _ inNumberPCMFrames: UInt32, _ inInputData: UnsafePointer<AudioBufferList>, _ outOutputData: UnsafeMutablePointer<AudioBufferList>) -> OSStatus

    Objective-C

    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.

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 5.0 and later.

Callbacks

  • Supplies input data to the AudioConverterFillComplexBuffer function.

    Declaration

    Objective-C

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

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.1 and later.

Data Types

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

    Declaration

    Swift

    struct AudioConverterPrimeInfo { var leadingFrames: UInt32 var trailingFrames: UInt32 }

    Objective-C

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

  • A reference to an audio converter object.

    Declaration

    Swift

    typealias AudioConverterRef = COpaquePointer

    Objective-C

    typedef struct OpaqueAudioConverter *AudioConverterRef;

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.1 and later.

  • An audio converter property identifier.

    Declaration

    Swift

    typealias AudioConverterPropertyID = UInt32

    Objective-C

    typedef UInt32 AudioConverterPropertyID;

    Import Statement

    import AudioToolbox

    Availability

    Available in iOS 2.1 and later.

Constants

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

    Declaration

    Swift

    var kAudioConverterPropertyMinimumInputBufferSize: Int { get } var kAudioConverterPropertyMinimumOutputBufferSize: Int { get } var kAudioConverterPropertyMaximumInputBufferSize: Int { get } var kAudioConverterPropertyMaximumInputPacketSize: Int { get } var kAudioConverterPropertyMaximumOutputPacketSize: Int { get } var kAudioConverterPropertyCalculateInputBufferSize: Int { get } var kAudioConverterPropertyCalculateOutputBufferSize: Int { get } var kAudioConverterPropertyInputCodecParameters: Int { get } var kAudioConverterPropertyOutputCodecParameters: Int { get } var kAudioConverterSampleRateConverterAlgorithm: Int { get } var kAudioConverterSampleRateConverterComplexity: Int { get } var kAudioConverterSampleRateConverterQuality: Int { get } var kAudioConverterSampleRateConverterInitialPhase: Int { get } var kAudioConverterCodecQuality: Int { get } var kAudioConverterPrimeMethod: Int { get } var kAudioConverterPrimeInfo: Int { get } var kAudioConverterChannelMap: Int { get } var kAudioConverterDecompressionMagicCookie: Int { get } var kAudioConverterCompressionMagicCookie: Int { get } var kAudioConverterEncodeBitRate: Int { get } var kAudioConverterEncodeAdjustableSampleRate: Int { get } var kAudioConverterInputChannelLayout: Int { get } var kAudioConverterOutputChannelLayout: Int { get } var kAudioConverterApplicableEncodeBitRates: Int { get } var kAudioConverterAvailableEncodeBitRates: Int { get } var kAudioConverterApplicableEncodeSampleRates: Int { get } var kAudioConverterAvailableEncodeSampleRates: Int { get } var kAudioConverterAvailableEncodeChannelLayoutTags: Int { get } var kAudioConverterCurrentOutputStreamDescription: Int { get } var kAudioConverterCurrentInputStreamDescription: Int { get } var kAudioConverterPropertySettings: Int { get } var kAudioConverterPropertyBitDepthHint: Int { get } var kAudioConverterPropertyFormatList: Int { get } var kAudioConverterPropertyCanResumeFromInterruption: Int { get }

    Objective-C

    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

      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.

    • kAudioConverterPropertyMinimumOutputBufferSize

      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.

    • kAudioConverterPropertyMaximumInputBufferSize

      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.

    • kAudioConverterPropertyMaximumInputPacketSize

      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.

    • kAudioConverterPropertyMaximumOutputPacketSize

      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.

    • kAudioConverterPropertyCalculateInputBufferSize

      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.

    • kAudioConverterPropertyCalculateOutputBufferSize

      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.

    • kAudioConverterPropertyInputCodecParameters

      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.

    • kAudioConverterPropertyOutputCodecParameters

      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.

    • kAudioConverterSampleRateConverterAlgorithm

      kAudioConverterSampleRateConverterAlgorithm

      Deprecated. Use kAudioConverterSampleRateConverterComplexity instead.

      Available in iOS 2.1 and later.

    • kAudioConverterSampleRateConverterComplexity

      kAudioConverterSampleRateConverterComplexity

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

      Available in iOS 2.1 and later.

    • kAudioConverterSampleRateConverterQuality

      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.

    • kAudioConverterSampleRateConverterInitialPhase

      kAudioConverterSampleRateConverterInitialPhase

      A Float64 value equal to 0.0.

      Available in iOS 2.1 and later.

    • kAudioConverterCodecQuality

      kAudioConverterCodecQuality

      The rendering quality of a codec. A UInt32 value.

      Available in iOS 2.1 and later.

    • kAudioConverterPrimeMethod

      kAudioConverterPrimeMethod

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

      Available in iOS 2.1 and later.

    • kAudioConverterPrimeInfo

      kAudioConverterPrimeInfo

      An AudioConverterPrimeInfo structure.

      Available in iOS 2.1 and later.

    • kAudioConverterChannelMap

      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.

    • kAudioConverterDecompressionMagicCookie

      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.

    • kAudioConverterCompressionMagicCookie

      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.

    • kAudioConverterEncodeBitRate

      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.

    • kAudioConverterEncodeAdjustableSampleRate

      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.

    • kAudioConverterInputChannelLayout

      kAudioConverterInputChannelLayout

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

      Available in iOS 2.1 and later.

    • kAudioConverterOutputChannelLayout

      kAudioConverterOutputChannelLayout

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

      Available in iOS 2.1 and later.

    • kAudioConverterApplicableEncodeBitRates

      kAudioConverterApplicableEncodeBitRates

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

      Available in iOS 2.1 and later.

    • kAudioConverterAvailableEncodeBitRates

      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.

    • kAudioConverterApplicableEncodeSampleRates

      kAudioConverterApplicableEncodeSampleRates

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

      Available in iOS 2.1 and later.

    • kAudioConverterAvailableEncodeSampleRates

      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.

    • kAudioConverterAvailableEncodeChannelLayoutTags

      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.

    • kAudioConverterCurrentOutputStreamDescription

      kAudioConverterCurrentOutputStreamDescription

      The current, completely specified output AudioStreamBasicDescription structure.

      Available in iOS 2.1 and later.

    • kAudioConverterCurrentInputStreamDescription

      kAudioConverterCurrentInputStreamDescription

      The current, completely specified input AudioStreamBasicDescription structure.

      Available in iOS 2.1 and later.

    • kAudioConverterPropertySettings

      kAudioConverterPropertySettings

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

      Available in iOS 2.1 and later.

    • kAudioConverterPropertyBitDepthHint

      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.

    • kAudioConverterPropertyFormatList

      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.

    • kAudioConverterPropertyCanResumeFromInterruption

      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.

    Import Statement

  • Constants used with the kAudioConverterPrimeMethod property.

    Declaration

    Swift

    var kConverterPrimeMethod_Pre: Int { get } var kConverterPrimeMethod_Normal: Int { get } var kConverterPrimeMethod_None: Int { get }

    Objective-C

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

    Constants

    • kConverterPrimeMethod_Pre

      kConverterPrimeMethod_Pre

      Prime with leading + trailing input frames.

      Available in iOS 2.1 and later.

    • kConverterPrimeMethod_Normal

      kConverterPrimeMethod_Normal

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

      Available in iOS 2.1 and later.

    • kConverterPrimeMethod_None

      kConverterPrimeMethod_None

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

      Available in iOS 2.1 and later.

    Import Statement

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

    Declaration

    Swift

    var kAudioConverterQuality_Max: Int { get } var kAudioConverterQuality_High: Int { get } var kAudioConverterQuality_Medium: Int { get } var kAudioConverterQuality_Low: Int { get } var kAudioConverterQuality_Min: Int { get }

    Objective-C

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

    Constants

    • kAudioConverterQuality_Max

      kAudioConverterQuality_Max

      Specifies maximum sample-rate conversion quality.

      Available in iOS 2.1 and later.

    • kAudioConverterQuality_High

      kAudioConverterQuality_High

      Specifies high sample rate conversion quality.

      Available in iOS 2.1 and later.

    • kAudioConverterQuality_Medium

      kAudioConverterQuality_Medium

      Specifies medium sample rate conversion quality.

      Available in iOS 2.1 and later.

    • kAudioConverterQuality_Low

      kAudioConverterQuality_Low

      Specifies low sample rate conversion quality.

      Available in iOS 2.1 and later.

    • kAudioConverterQuality_Min

      kAudioConverterQuality_Min

      Specifies minimum sample rate conversion quality.

      Available in iOS 2.1 and later.

    Discussion

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

    Import Statement

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

    Declaration

    Swift

    var kAudioConverterSampleRateConverterComplexity_Linear: Int { get } var kAudioConverterSampleRateConverterComplexity_Normal: Int { get } var kAudioConverterSampleRateConverterComplexity_Mastering: Int { get }

    Objective-C

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

    Constants

    • kAudioConverterSampleRateConverterComplexity_Linear

      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.

    • kAudioConverterSampleRateConverterComplexity_Normal

      kAudioConverterSampleRateConverterComplexity_Normal

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

      Available in iOS 2.1 and later.

    • kAudioConverterSampleRateConverterComplexity_Mastering

      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.

    Import Statement

Result Codes

This table lists result codes defined for Audio Converter Services.