iOS Developer Library

Developer

AudioToolbox Framework Reference Audio Format Services Reference

Options
Deployment Target:

On This Page
Language:

Audio Format Services Reference

Inherits From


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AudioToolbox

Objective-C

@import AudioToolbox;

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

Functions

  • Gets the value of an audio format property.

    Declaration

    Swift

    func AudioFormatGetProperty(_ inPropertyID: AudioFormatPropertyID, _ inSpecifierSize: UInt32, _ inSpecifier: UnsafePointer<Void>, _ ioDataSize: UnsafeMutablePointer<UInt32>, _ outPropertyData: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later

  • Gets information about an audio format property.

    Declaration

    Swift

    func AudioFormatGetPropertyInfo(_ inPropertyID: AudioFormatPropertyID, _ inSpecifierSize: UInt32, _ inSpecifier: UnsafePointer<Void>, _ outDataSize: UnsafeMutablePointer<UInt32>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later

Data Types

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

    Declaration

    Swift

    struct AudioBalanceFade { var mLeftRightBalance: Float32 var mBackFrontFade: Float32 var mType: UInt32 var mChannelLayout: UnsafePointer<AudioChannelLayout> init() init(mLeftRightBalance mLeftRightBalance: Float32, mBackFrontFade mBackFrontFade: Float32, mType mType: UInt32, mChannelLayout mChannelLayout: UnsafePointer<AudioChannelLayout>) }

    Objective-C

    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

  • A specifier for the kAudioFormatProperty_FormatList property.

    Declaration

    Swift

    struct AudioFormatInfo { var mASBD: AudioStreamBasicDescription var mMagicCookie: UnsafePointer<Void> var mMagicCookieSize: UInt32 init() init(mASBD mASBD: AudioStreamBasicDescription, mMagicCookie mMagicCookie: UnsafePointer<Void>, mMagicCookieSize mMagicCookieSize: UInt32) }

    Objective-C

    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

  • Represents a value from the kAudioFormatProperty_FormatList property.

    Declaration

    Swift

    struct AudioFormatListItem { var mASBD: AudioStreamBasicDescription var mChannelLayoutTag: AudioChannelLayoutTag init() init(mASBD mASBD: AudioStreamBasicDescription, mChannelLayoutTag mChannelLayoutTag: AudioChannelLayoutTag) }

    Objective-C

    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

  • Audio panning information.

    Declaration

    Swift

    struct AudioPanningInfo { var mPanningMode: UInt32 var mCoordinateFlags: UInt32 var mCoordinates: (Float32, Float32, Float32) var mGainScale: Float32 var mOutputChannelMap: UnsafePointer<AudioChannelLayout> init() init(mPanningMode mPanningMode: UInt32, mCoordinateFlags mCoordinateFlags: UInt32, mCoordinates mCoordinates: (Float32, Float32, Float32), mGainScale mGainScale: Float32, mOutputChannelMap mOutputChannelMap: UnsafePointer<AudioChannelLayout>) }

    Objective-C

    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

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

    Declaration

    Swift

    struct ExtendedAudioFormatInfo { var mASBD: AudioStreamBasicDescription var mMagicCookie: UnsafePointer<Void> var mMagicCookieSize: UInt32 var mClassDescription: AudioClassDescription init() init(mASBD mASBD: AudioStreamBasicDescription, mMagicCookie mMagicCookie: UnsafePointer<Void>, mMagicCookieSize mMagicCookieSize: UInt32, mClassDescription mClassDescription: AudioClassDescription) }

    Objective-C

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

    Fields

    mASBD
    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

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

    Declaration

    Swift

    typealias AudioFormatPropertyID = UInt32

    Objective-C

    typedef UInt32 AudioFormatPropertyID;

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later

Constants

  • Identifiers for audio balance fade types.

    Declaration

    Swift

    var kAudioBalanceFadeType_MaxUnityGain: Int { get } var kAudioBalanceFadeType_EqualPower: Int { get }

    Objective-C

    enum { kAudioBalanceFadeType_MaxUnityGain = 0, kAudioBalanceFadeType_EqualPower = 1 };

    Constants

    • kAudioBalanceFadeType_MaxUnityGain

      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

    • kAudioBalanceFadeType_EqualPower

      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

    Discussion

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

  • Constants for use with the AudioFormatGetPropertyInfo and AudioFormatGetProperty functions.

    Declaration

    Swift

    var kAudioFormatProperty_FormatInfo: Int { get } var kAudioFormatProperty_FormatName: Int { get } var kAudioFormatProperty_EncodeFormatIDs: Int { get } var kAudioFormatProperty_DecodeFormatIDs: Int { get } var kAudioFormatProperty_FormatList: Int { get } var kAudioFormatProperty_ASBDFromESDS: Int { get } var kAudioFormatProperty_ChannelLayoutFromESDS: Int { get } var kAudioFormatProperty_OutputFormatList: Int { get } var kAudioFormatProperty_FirstPlayableFormatFromList: Int { get } var kAudioFormatProperty_Encoders: Int { get } var kAudioFormatProperty_Decoders: Int { get } var kAudioFormatProperty_FormatIsVBR: Int { get } var kAudioFormatProperty_FormatIsExternallyFramed: Int { get } var kAudioFormatProperty_AvailableEncodeBitRates: Int { get } var kAudioFormatProperty_AvailableEncodeSampleRates: Int { get } var kAudioFormatProperty_AvailableEncodeChannelLayoutTags: Int { get } var kAudioFormatProperty_AvailableEncodeNumberChannels: Int { get } var kAudioFormatProperty_ASBDFromMPEGPacket: Int { get } var kAudioFormatProperty_BitmapForLayoutTag: Int { get } var kAudioFormatProperty_MatrixMixMap: Int { get } var kAudioFormatProperty_ChannelMap: Int { get } var kAudioFormatProperty_NumberOfChannelsForLayout: Int { get } var kAudioFormatProperty_ValidateChannelLayout: Int { get } var kAudioFormatProperty_ChannelLayoutForTag: Int { get } var kAudioFormatProperty_TagForChannelLayout: Int { get } var kAudioFormatProperty_ChannelLayoutName: Int { get } var kAudioFormatProperty_ChannelLayoutSimpleName: Int { get } var kAudioFormatProperty_ChannelLayoutForBitmap: Int { get } var kAudioFormatProperty_ChannelName: Int { get } var kAudioFormatProperty_ChannelShortName: Int { get } var kAudioFormatProperty_TagsForNumberOfChannels: Int { get } var kAudioFormatProperty_PanningMatrix: Int { get } var kAudioFormatProperty_BalanceFade: Int { get } var kAudioFormatProperty_ID3TagSize: Int { get } var kAudioFormatProperty_ID3TagToDictionary: Int { get }

    Objective-C

    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

      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

    • kAudioFormatProperty_FormatName

      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

    • kAudioFormatProperty_EncodeFormatIDs

      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

    • kAudioFormatProperty_DecodeFormatIDs

      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

    • kAudioFormatProperty_FormatList

      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

    • kAudioFormatProperty_ASBDFromESDS

      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

    • kAudioFormatProperty_ChannelLayoutFromESDS

      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

    • kAudioFormatProperty_OutputFormatList

      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

    • kAudioFormatProperty_FirstPlayableFormatFromList

      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

    • kAudioFormatProperty_Encoders

      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

    • kAudioFormatProperty_Decoders

      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

    • kAudioFormatProperty_FormatIsVBR

      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

    • kAudioFormatProperty_FormatIsExternallyFramed

      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

    • kAudioFormatProperty_AvailableEncodeBitRates

      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

    • kAudioFormatProperty_AvailableEncodeSampleRates

      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

    • kAudioFormatProperty_AvailableEncodeChannelLayoutTags

      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

    • kAudioFormatProperty_AvailableEncodeNumberChannels

      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

    • kAudioFormatProperty_ASBDFromMPEGPacket

      kAudioFormatProperty_ASBDFromMPEGPacket

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

      Available in iOS 3.0 and later

    • kAudioFormatProperty_BitmapForLayoutTag

      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

    • kAudioFormatProperty_MatrixMixMap

      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

    • kAudioFormatProperty_ChannelMap

      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

    • kAudioFormatProperty_NumberOfChannelsForLayout

      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

    • kAudioFormatProperty_ValidateChannelLayout

      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

    • kAudioFormatProperty_ChannelLayoutForTag

      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

    • kAudioFormatProperty_TagForChannelLayout

      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

    • kAudioFormatProperty_ChannelLayoutName

      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

    • kAudioFormatProperty_ChannelLayoutSimpleName

      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

    • kAudioFormatProperty_ChannelLayoutForBitmap

      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

    • kAudioFormatProperty_ChannelName

      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

    • kAudioFormatProperty_ChannelShortName

      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

    • kAudioFormatProperty_TagsForNumberOfChannels

      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

    • kAudioFormatProperty_PanningMatrix

      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

    • kAudioFormatProperty_BalanceFade

      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

    • kAudioFormatProperty_ID3TagSize

      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

    • kAudioFormatProperty_ID3TagToDictionary

      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

  • A constant to determine which hardware codecs can be used.

    Declaration

    Swift

    var kAudioFormatProperty_HardwareCodecCapabilities: Int { get }

    Objective-C

    enum { kAudioFormatProperty_HardwareCodecCapabilities = 'hwcc', };

    Constants

    • kAudioFormatProperty_HardwareCodecCapabilities

      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

      Deprecated in iOS 8.0

    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
    • }

    See also Audio Codec Conversion Types and Audio Codec Manufacturer and Implementation Types.

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

    Declaration

    Swift

    var kAudioDecoderComponentType: Int { get } var kAudioEncoderComponentType: Int { get }

    Objective-C

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

    Constants

    • kAudioDecoderComponentType

      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

    • kAudioEncoderComponentType

      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

    Discussion

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

  • Identifiers for audio codec manufacturers and implementation types.

    Declaration

    Swift

    var kAppleSoftwareAudioCodecManufacturer: Int { get } var kAppleHardwareAudioCodecManufacturer: Int { get }

    Objective-C

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

    Constants

    • kAppleSoftwareAudioCodecManufacturer

      kAppleSoftwareAudioCodecManufacturer

      A software-based audio codec supplied by Apple Inc.

      Available in iOS 3.0 and later

    • kAppleHardwareAudioCodecManufacturer

      kAppleHardwareAudioCodecManufacturer

      A hardware-based audio codec supplied by Apple Inc.

      Available in iOS 3.0 and later

    Discussion

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

  • Identifiers for audio panning algorithms.

    Declaration

    Swift

    var kPanningMode_SoundField: Int { get } var kPanningMode_VectorBasedPanning: Int { get }

    Objective-C

    enum { kPanningMode_SoundField = 3, kPanningMode_VectorBasedPanning = 4 };

    Constants

    • kPanningMode_SoundField

      kPanningMode_SoundField

      The SoundField panning algorithm.

      Available in iOS 3.0 and later

    • kPanningMode_VectorBasedPanning

      kPanningMode_VectorBasedPanning

      A vector-based panning algorithm.

      Available in iOS 3.0 and later

Result Codes

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