Audio Format Services Reference

Framework	AudioToolbox/AudioToolbox.h
Declared in	AudioFormat.h

Overview

This document describes Audio Format Services, a C interface for obtaining information about audio formats and codecs.

Functions

AudioFormatGetProperty

Gets the value of an audio format property.

OSStatus AudioFormatGetProperty (
   AudioFormatPropertyID inPropertyID,
   UInt32                inSpecifierSize,
   const void            *inSpecifier,
   UInt32                *ioPropertyDataSize,
   void                  *outPropertyData
);

Parameters

inPropertyID: An AudioFormatPropertyID constant. For a list of these constants, see “Audio Format Property Identifiers.”
inSpecifierSize: The size of the specifier data.
inSpecifier: A buffer of data used as an input argument for querying some of the properties.
ioDataSize: On input, the size of the outPropertyData buffer. On output, the number of bytes written to the buffer.
outPropertyData: The buffer to write the property data to. If the outPropertyData parameter is NULL and ioPropertyDataSize is not NULL, the amount that would have been written is reported.

Return Value

A result code. Returns noErr if successful.

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.0 and later.

Related Sample Code

Declared In

AudioFormat.h

AudioFormatGetPropertyInfo

Gets information about an audio format property.

OSStatus AudioFormatGetPropertyInfo (
   AudioFormatPropertyID  inPropertyID,
   UInt32                 inSpecifierSize,
   const void             *inSpecifier,
   UInt32                 *outPropertyDataSize
);

Parameters

inPropertyID: An AudioFormatPropertyID constant.
inSpecifierSize: The size of the specifier data.
inSpecifier: A buffer of data used as an input argument for querying some of the properties.
outDataSize: The the size in bytes of the current value of the property. To get the property value, you need a buffer of this size.

Return Value

A result code. Returns noErr if successful.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

AudioFormat.h

Data Types

AudioBalanceFade

Describes audio left/right balance and front/back fade values.

struct AudioBalanceFade {
   Float32                   mLeftRightBalance;
   Float32                   mBackFrontFade;
   UInt32                    mType;
   const AudioChannelLayout  *mChannelLayout;
};
typedef struct AudioBalanceFade AudioBalanceFade;

Fields

mLeftRightBalance: The audio left/right balance, where -1 represents full left, 0 represents center, and +1 represents full right.
mBackFrontFade: The audio front/back fade, where -1 represents full rear, 0 represents center, and +1 represents full front.
mType: An AudioBalanceFadeType constant. max unity gain, or equal power.
mChannelLayout: The size, in bytes, of the mMagicCookie parameter.

Discussion

This data structure is used with the kAudioFormatProperty_BalanceFade property.

Availability

Available in iOS 3.0 and later.

Declared In

AudioFormat.h

AudioFormatInfo

A specifier for the kAudioFormatProperty_FormatList property.

struct AudioFormatInfo {
   AudioStreamBasicDescription  mASBD;
   const void                   *mMagicCookie;
   UInt32                       mMagicCookieSize;
};
typedef struct AudioFormatInfo AudioFormatInfo;

Fields

mASBD: An AudioStreamBasicDescription structure.
mMagicCookie: A pointer to the decompression information for the data described in the mASBD parameter.
mMagicCookieSize: The size, in bytes, of the mMagicCookie parameter.

Availability

Available in iOS 2.0 and later.

Declared In

AudioFormat.h

AudioFormatListItem

Represents a value from the kAudioFormatProperty_FormatList property.

struct AudioFormatListItem {
   AudioStreamBasicDescription  mASBD;
   AudioChannelLayoutTag        mChannelLayoutTag;
};
typedef struct AudioFormatListItem AudioFormatListItem;

Fields

mASBD: An AudioStreamBasicDescription structure.
mChannelLayoutTag: An AudioChannelLayoutTag value.

Availability

Available in iOS 2.0 and later.

Declared In

AudioFormat.h

AudioPanningInfo

Audio panning information.

struct AudioPanningInfo {
   UInt32                   mPanningMode;
   UInt32                   mCoordinateFlags;
   Float32                  mCoordinates[3];
   Float32                  mGainScale;
   const AudioChannelLayout *mOutputChannelMap;
};
typedef struct AudioPanningInfo AudioPanningInfo;

Fields

mPanningMode: The panning mode to be used for the pan. See “Audio Panning Modes.”
mCoordinateFlags: For the available coordinate flags, see Channel Coordinate Flags.
mCoordinates: For the available coordinate index constants, see Channel Coordinate Index Constants.
mGainScale: A multiplier for audio panning values, typically representing a volume value in the range from 0 to 1. A value of 1 results in audio panning at unity gain. A value of 0 silences all channels.
mOutputChannelMap: The channel map used to determine channel volumes for the audio panning.

Availability

Available in iOS 3.0 and later.

Declared In

AudioFormat.h

ExtendedAudioFormatInfo

A specifier for the kAudioFormatProperty_FormatList property, including the codec to use.

struct ExtendedAudioFormatInfo {
   AudioStreamBasicDescription  mASBD;
   const void                   *mMagicCookie;
   UInt32                       mMagicCookieSize;
   AudioClassDescription        mClassDescription;
};
typedef struct ExtendedAudioFormatInfo ExtendedAudioFormatInfo;

Fields

mASBD: An AudioStreamBasicDescription struct.
mMagicCookie: Decompression information for the audio data format specified in the mASBD field.
mMagicCookieSize: The size, in bytes, of the mMagicCookie field.
mClassDescription: An AudioClassDescription struct that specifies the codec to be used.

Availability

Available in iOS 4.3 and later.

Declared In

AudioFormat.h

AudioFormatPropertyID

A type for four-char codes for audio format property identifiers.

typedef UInt32 AudioFormatPropertyID;

Discussion

See “Audio Format Property Identifiers.”

Availability

Available in iOS 2.0 and later.

Declared In

AudioFormat.h

Constants

Audio Balance Fade Types

Identifiers for audio balance fade types.

enum {
   kAudioBalanceFadeType_MaxUnityGain = 0,
   kAudioBalanceFadeType_EqualPower   = 1
};

Constants

kAudioBalanceFadeType_MaxUnityGain

Ensures that the overall gain value never exceeds 1.0 by fading one channel as the other channel’s level rises. This can reduce overall loudness when the balance or fade is not in the center.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioBalanceFadeType_EqualPower

Overall loudness remains constant, but gain can exceed 1.0. The gain value is 1.0 when the balance and fade are in the center. From there they can increase to +3dB (1.414) and decrease to silence.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

Discussion

These constants are used as values for the mType field of the AudioBalanceFade structure.

Audio Format Property Identifiers

Constants for use with the AudioFormatGetPropertyInfo and AudioFormatGetProperty functions.

enum {
   // AudioStreamBasicDescription structure properties
   kAudioFormatProperty_FormatInfo                       = 'fmti',
   kAudioFormatProperty_FormatName                       = 'fnam',
   kAudioFormatProperty_EncodeFormatIDs                  = 'acof',
   kAudioFormatProperty_DecodeFormatIDs                  = 'acif',
   kAudioFormatProperty_FormatList                       = 'flst',
   kAudioFormatProperty_ASBDFromESDS                     = 'essd',
   kAudioFormatProperty_ChannelLayoutFromESDS            = 'escl',
   kAudioFormatProperty_OutputFormatList                 = 'ofls',
   kAudioFormatProperty_Encoders                         = 'aven',
   kAudioFormatProperty_Decoders                         = 'avde',
   kAudioFormatProperty_FormatIsVBR                      = 'fvbr',
   kAudioFormatProperty_FormatIsExternallyFramed         = 'fexf',
   kAudioFormatProperty_AvailableEncodeBitRates          = 'aebr',
   kAudioFormatProperty_AvailableEncodeSampleRates       = 'aesr',
   kAudioFormatProperty_AvailableEncodeChannelLayoutTags = 'aecl',
   kAudioFormatProperty_AvailableEncodeNumberChannels    = 'avnc',
   kAudioFormatProperty_ASBDFromMPEGPacket               = 'admp',
   //
   // AudioChannelLayout structure properties
   kAudioFormatProperty_BitmapForLayoutTag               = 'bmtg',
   kAudioFormatProperty_MatrixMixMap                     = 'mmap',
   kAudioFormatProperty_ChannelMap                       = 'chmp',
   kAudioFormatProperty_NumberOfChannelsForLayout        = 'nchm',
   kAudioFormatProperty_ValidateChannelLayout            = 'vacl',
   kAudioFormatProperty_ChannelLayoutForTag              = 'cmpl',
   kAudioFormatProperty_TagForChannelLayout              = 'cmpt',
   kAudioFormatProperty_ChannelLayoutName                = 'lonm',
   kAudioFormatProperty_ChannelLayoutSimpleName          = 'lsnm',
   kAudioFormatProperty_ChannelLayoutForBitmap           = 'cmpb',
   kAudioFormatProperty_ChannelName                      = 'cnam',
   kAudioFormatProperty_ChannelShortName                 = 'csnm',
   kAudioFormatProperty_TagsForNumberOfChannels          = 'tagc',
   kAudioFormatProperty_PanningMatrix                    = 'panm',
   kAudioFormatProperty_BalanceFade                      = 'balf',
   //
   // ID3 tag (MP3 metadata) properties
   kAudioFormatProperty_ID3TagSize                       = 'id3s',
   kAudioFormatProperty_ID3TagToDictionary               = 'id3d'
};

Constants

kAudioFormatProperty_FormatInfo

General information about a format. Set the inSpecifier parameter to a magic cookie, or NULL. On input, the property value is an AudioStreamBasicDescription structure which should have at least the mFormatID field filled out. On output, the structure will be filled out as much as possible given the information known about the format and the contents of the magic cookie (if any is given). If multiple formats can be described by the AudioStreamBasicDescription and the associated magic cookie, this property will return the base level format.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_FormatName

A name for a given format. Set the inSpecifier parameter to an AudioStreamBasicDescription structure describing the format to ask about. The value is a CFStringRef object. The caller is responsible for releasing the returned string. For some formats, such as linear PCM, you get back a descriptive string, for example, “16-bit, interleaved.”

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_EncodeFormatIDs

An array of UInt32 values representing format identifiers for formats that are valid output formats for a converter. You must set the inSpecifier parameter to NULL.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_DecodeFormatIDs

An array of UInt32 values representing format identifiers for formats that are valid input formats for a converter. You must set the inSpecifier parameter to NULL.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_FormatList

A list of AudioFormatListItem structures describing the audio formats contained within the compressed bit stream, as described by the magic cookie. Set the inSpecifier parameter to an AudioFormatInfo structure.

The mFormatID field of the AudioStreamBasicDescription structure must filled in. Formats are returned in order from the most to least “rich,” with channel count taking the highest precedence, followed by sample rate.

The kAudioFormatProperty_FormatList property is the preferred method for discovering format information of the audio data. If the audio data can only be described by a single AudioFormatListItem, this property would be equivalent to using the kAudioFormatProperty_FormatInfo property, which should be used by the application as a fallback case, to ensure backward compatibility with existing systems when kAudioFormatProperty_FormatList is not present on the system.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ASBDFromESDS

An AudioStreamBasicDescription structure for a given elementary stream descriptor (ESDS). Set the inSpecifier parameter to an ESDS. If multiple formats can be described by the ESDS, this property will return the base level format.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ChannelLayoutFromESDS

An AudioChannelLayout structure for a given elementary stream descriptor (ESDS). Set the inSpecifier parameter to an ESDS.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_OutputFormatList

A list of AudioFormatListItem structures describing the audio formats which may be obtained by decoding the format described by the specifier. Set the inSpecifier parameter to an AudioFormatInfo structure. At a minimum, the formatID field of the AudioStreamBasicDescription structure must filled in. Other fields may be filled in. If there is no magic cookie, then the number of channels and sample rate should be filled in.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_FirstPlayableFormatFromList

The index of the first AudioFormatListItem structure that represents an audio format that is playable on the system. To use this property, pass in, to the AudioFormatGetProperty function, the list of AudioFormatListItem structures that you obtain using the kAudioFormatProperty_OutputFormatList property.

Available in iOS 2.2 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_Encoders

An array of AudioClassDescription structures for all installed encoders for the specified audio format. Set the inSpecifier parameter to the format that you are interested in, for instance, 'aac'.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_Decoders

An array of AudioClassDescription structures for all installed decoders for the specified audio format. Set the inSpecifier parameter to the format that you are interested in, for instance, 'aac'.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_FormatIsVBR

Indicates whether or not a format has a variable number of bytes-per-packet. The specifier is an AudioStreamBasicDescription structure describing the format to ask about. The value is a UInt32 where nonzero means the format is VBR.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_FormatIsExternallyFramed

Indicates whether or not a format requires external framing information in the form of AudioStreamPacketDescription structures. The specifier is an AudioStreamBasicDescription structure describing the format to ask about. The value is a UInt32 where nonzero means the format is externally framed. Any format that has variable-byte-sized packets requires packet descriptions.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_AvailableEncodeBitRates

An array of AudioValueRange structures describing all available bit rates. The specifier is a UInt32 format identifier.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_AvailableEncodeSampleRates

An array of AudioValueRange structures describing all available sample rates. The specifier is a UInt32 format identifier.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_AvailableEncodeChannelLayoutTags

An array of AudioChannelLayoutTag values for the format and number of channels specified. If mChannelsPerFrame field of the specifier is zero, then all layouts supported by the format are returned. The specifier is an AudioStreamBasicDescription structure with at least the mFormatID and mChannelsPerFrame fields set.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_AvailableEncodeNumberChannels

An array of UInt32 values indicating the number of channels that can be encoded. A value of 0xFFFFFFFF indicates that any number of channels may be encoded. The specifier is an AudioStreamBasicDescription structure with at least the mFormatID field set.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ASBDFromMPEGPacket

An AudioStreamBasicDescription structure for a given MPEG Packet. The specifier is an MPEG Packet.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_BitmapForLayoutTag

A bitmap for an AudioChannelLayoutTag value, if there is one. Set the inSpecifier parameter to an AudioChannelLayoutTag value containing the layout tag. The value is an UInt32 bitmap. The bits are as defined in Core Audio Data Types Reference. To go in the other direction, that is, to get a layout tag for a bitmap, use the kAudioFormatProperty_TagForChannelLayout where your layout tag is kAudioChannelLayoutTag_UseChannelBitmap and the bitmap is filled in.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_MatrixMixMap

A matrix of scaling coefficients for converting audio from one channel map to another in a standard way, if one is known. Otherwise, an error is returned. Set the inSpecifier parameter to an array of two pointers to AudioChannelLayout structures. The first points to the input layout, the second to the output layout. The value is a two dimensional array of Float32 values, where the first dimension (rows) is the input channel and the second dimension (columns) is the output channel.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ChannelMap

An array of SInt32 values for reordering input channels. Set the inSpecifier parameter to an array of two pointers to AudioChannelLayout structures. The first points to the input layout, the second to the output layout. The length of the output array is equal to the number of output channels.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_NumberOfChannelsForLayout

The number of valid channels represented in an AudioChannelLayout structure. Set the inSpecifier parameter to the AudioChannelLayout structure you want to examine. If the layout tag is specified, the value contains the number of channels for that layout. If the bitmap is specified, the value contains the number of channels represented by that bitmap. If the layout tag is kAudioChannelLayoutTag_UseChannelDescriptions, the value contains the number of channel descriptions.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ValidateChannelLayout

Indicates the validity of the AudioChannelLayout struct provided as the specifier, to let you determine the number of valid channels represented in the layout. If the LayoutTag is specified, it returns the number of channels for that layout. If the bitmap is specified, it returns the number of channels represented by that bitmap.

If the layout tag is kAudioChannelLayoutTag_UseChannelDescriptions it returns the number of channel descriptions.

Available in iOS 4.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ChannelLayoutForTag

The channel descriptions for a standard channel layout. Set the inSpecifier parameter to an AudioChannelLayoutTag value (the mChannelLayoutTag field of the AudioChannelLayout structure) containing the layout constant. The value is an AudioChannelLayout structure. In typical use, an AudioChannelLayout can be valid with just a defined AudioChannelLayoutTag (that is, those layouts have predefined speaker locations and orderings). Returns an error if the tag is kAudioChannelLayoutTag_UseChannelBitmap.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_TagForChannelLayout

An AudioChannelLayoutTag value for a layout, if there is one. Set the inSpecifier parameter to an AudioChannelLayout structure containing the layout description. This can be used to reduce a layout specified by kAudioChannelLayoutTag_UseChannelDescriptions or kAudioChannelLayoutTag_UseChannelBitmap to a known AudioChannelLayoutTag value.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ChannelLayoutName

The a name for a particular channel layout. Set the inSpecifier parameter to an AudioChannelLayout structure containing the layout description. The value is a CFStringRef object. The caller is responsible for releasing the returned string.

Available in iOS 2.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ChannelLayoutSimpleName

A simplified name for channel layout. Compared to the value of the kAudioFormatProperty_ChannelLayoutName property, the name in this property omits the channel labels. The specifier is an AudioChannelLayout struct containing the layout description. The value is a CFStringRef object. The caller is responsible for releasing the returned string.

Available in iOS 4.2 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ChannelLayoutForBitmap

The channel descriptions for a standard channel layout, in the form of an AudioChannelLayout structure. In some uses, an AudioChannelLayout can be valid with the mChannelLayoutTag field set to an kAudioChannelLayoutTag_UseChannelBitmap value and the bitmap set appropriately. The specifier is a UInt32 value representing he mChannelBitmap field of the AudioChannelLayout structure that contains the layout.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ChannelName

The name for a particular channel. The specifier is an AudioChannelDescription structure that has its mChannelLabel field set. The value is a CFStringRef opaque type. The caller is responsible for releasing the returned string.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ChannelShortName

An abbreviated name for a particular channel. The specifier is an AudioChannelDescription structure that has its mChannelLabel field set. The value is a CFStringRef opaque type. The caller is responsible for releasing the returned string.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_TagsForNumberOfChannels

An array of AudioChannelLayoutTag values for the number of channels specified. The specifier is a UInt32 value that indicates the number of channels.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_PanningMatrix

An array of Float32 values, each representing the audio level of one channel.

The specifier is an AudioPanningInfo structure containing a “Audio Panning Modes” constant and an AudioChannelLayout structure that describes the destination channel layout. The source being panned should be mono. For example, for a quad channel layout, the array contains four Float32 values.

This property supports audio panning performed by simple level setting of each channel. More complex panning algorithms (such as HRTF or distance filtering) cannot use this property. You can apply the level values to a mixer or other processing code. Level values typically range from 0 to 1, where 0 represents silence and 1 represents unity gain. For stereo formats, vector based panning is equivalent to the equal-power panning mode.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_BalanceFade

An array of coefficients, each a Float32 value, for applying left/right audio balance and front/back audio fade.

The specifier is an AudioBalanceFade structure. Level values typically range from 0 to 1, where 0 represents silence and 1 represents unity gain.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ID3TagSize

A UInt32 value indicating the ID3 tag size. The inSpecifier parameter must begin with the ID3 tag header and be at least 10 bytes in length.

Available in iOS 2.2 and later.

Declared in AudioFormat.h.

kAudioFormatProperty_ID3TagToDictionary

A CFDictionary object containing key/value pairs for the frames in the ID3 tag. Set the inSpecifier parameter to the entire ID3 tag. The caller must call the CFRelease function for the returned dictionary.

Available in iOS 2.2 and later.

Declared in AudioFormat.h.

Hardware Codec Capabilities

A constant to determine which hardware codecs can be used.

enum {
   kAudioFormatProperty_HardwareCodecCapabilities = 'hwcc',
};

Constants

kAudioFormatProperty_HardwareCodecCapabilities

A UInt32 value indicating the number of codecs from the specified list that can be used, if the application were to begin using them in the specified order. Set the inSpecifier parameter to an array of AudioClassDescription structures that describes a set of one or more audio codecs. If the property value is the same as the size of the array in the inSpecifier parameter, all of the specified codecs can be used.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

Discussion

Use this property to determine whether a desired set of codecs can be simultaneously instantiated.

Hardware-based codecs can be used only when playing or recording using Audio Queue Services or using interfaces, such as AV Foundation, which use Audio Queue Services. In particular, you cannot use hardware-based audio codecs with OpenAL or when using the I/O audio unit.

When describing the presence of a hardware codec, the system does not consider the current audio session category. Some categories disallow the use of hardware codecs. A set of hardware codecs is considered available, by this constant, based only on whether the hardware supports the specified combination of codecs.

Some codecs may be available in both hardware and software implementations. Use the kAudioFormatProperty_Encoders and kAudioFormatProperty_Decoders constants to determine whether a given codec is present, and whether it is hardware or software-based.

Software-based codecs can always be instantiated, so there is no need to use this constant when using software encoding or decoding.

The following code example illustrates how to check whether or not a hardware AAC encoder and a hardware AAC decoder are available, in that order of priority:

AudioClassDescription requestedCodecs[2] = {

        kAudioEncoderComponentType,

        kAudioFormatAAC,

        kAppleHardwareAudioCodecManufacturer

},

        kAudioDecoderComponentType,

        kAudioFormatAAC,

        kAppleHardwareAudioCodecManufacturer

};

UInt32 successfulCodecs = 0;

size = sizeof (successfulCodecs);

OSStatus result =   AudioFormatGetProperty (

                        kAudioFormatProperty_HardwareCodecCapabilities,

                        requestedCodecs,

                        sizeof (requestedCodecs),

                        &size,

                        &successfulCodecs

);

switch (successfulCodecs) {

    case 0:

        // aac hardware encoder is unavailable. aac hardware decoder availability

        // is unknown; could ask again for only aac hardware decoding

    case 1:

        // aac hardware encoder is available but, while using it, no hardware

        // decoder is available.

    case 2:

        // hardware encoder and decoder are available simultaneously

Audio Codec Conversion Types

Identifiers that distinguish audio decoders (which translate to linear PCM format) from audio encoders (which translate from linear PCM format).

enum {
   kAudioDecoderComponentType  = 'adec',
   kAudioEncoderComponentType  = 'aenc',
};

Constants

kAudioDecoderComponentType

A codec that translates audio data from some other format to linear PCM. The component subtype specifies the format ID of the starting format.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAudioEncoderComponentType

A codec that translates audio data from linear PCM to some other format. The component subtype specifies the format ID of the target format.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

Discussion

For an example of how to use these constants, see the description for “Hardware Codec Capabilities.”

Audio Codec Manufacturer and Implementation Types

Identifiers for audio codec manufacturers and implementation types.

enum {
   kAppleSoftwareAudioCodecManufacturer  = 'appl',
   kAppleHardwareAudioCodecManufacturer  = 'aphw'
};

Constants

kAppleSoftwareAudioCodecManufacturer

A software-based audio codec supplied by Apple Inc.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kAppleHardwareAudioCodecManufacturer

A hardware-based audio codec supplied by Apple Inc.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

Discussion

For an example of how to use these constants, see the description for “Hardware Codec Capabilities.”

Audio Panning Modes

Identifiers for audio panning algorithms.

enum {
   kPanningMode_SoundField         = 3,
   kPanningMode_VectorBasedPanning = 4
};

Constants

kPanningMode_SoundField

The SoundField panning algorithm.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

kPanningMode_VectorBasedPanning

A vector-based panning algorithm.

Available in iOS 3.0 and later.

Declared in AudioFormat.h.

Result Codes

This table lists the result codes defined for Audio Format Services.

Result Code	Value	Description
`kAudioFormatUnspecifiedError`	'what'	An unspecified error. Available in iOS 2.0 and later.
`kAudioFormatUnsupportedPropertyError`	'prop'	The specified property is not supported. Available in iOS 2.0 and later.
`kAudioFormatBadPropertySizeError`	'!siz'	Available in iOS 2.0 and later.
`kAudioFormatBadSpecifierSizeError`	'!spc'	Available in iOS 2.0 and later.
`kAudioFormatUnsupportedDataFormatError`	'fmt?'	The specified data format is not supported. Available in iOS 2.0 and later.
`kAudioFormatUnknownFormatError`	'!fmt'	The specified data format is not a known format. Available in iOS 2.0 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.