| Framework | AudioToolbox/AudioToolbox.h |
| Declared in | AudioFormat.h |
This document describes Audio Format Services, a C interface for obtaining information about audio formats and codecs in iPhone OS and Mac OS X.
Gets the value of an audio format property.
OSStatus AudioFormatGetProperty ( AudioFormatPropertyID inPropertyID, UInt32 inSpecifierSize, const void *inSpecifier, UInt32 *ioPropertyDataSize, void *outPropertyData );
An AudioFormatPropertyID constant. For a list of these constants, see “Audio Format Property Identifiers.”
The size of the specifier data.
A buffer of data used as an input argument for querying some of the properties.
On input, the size of the outPropertyData buffer. On output, the number of bytes written to the buffer.
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.
A result code. Returns noErr if successful.
AudioFormat.hGets information about an audio format property.
OSStatus AudioFormatGetPropertyInfo ( AudioFormatPropertyID inPropertyID, UInt32 inSpecifierSize, const void *inSpecifier, UInt32 *outPropertyDataSize );
An AudioFormatPropertyID constant.
The size of the specifier data.
A buffer of data used as an input argument for querying some of the properties.
The the size in bytes of the current value of the property. To get the property value, you need a buffer of this size.
A result code. Returns noErr if successful.
AudioFormat.hDescribes audio left/right balance and front/back fade values.
struct AudioBalanceFade {
Float32 mLeftRightBalance;
Float32 mBackFrontFade;
UInt32 mType;
const AudioChannelLayout *mChannelLayout;
};
typedef struct AudioBalanceFade AudioBalanceFade;
mLeftRightBalanceThe audio left/right balance, where -1 represents full left, 0 represents center, and +1 represents full right.
mBackFrontFadeThe audio front/back fade, where -1 represents full rear, 0 represents center, and +1 represents full front.
mTypeAn AudioBalanceFadeType constant. max unity gain, or equal power.
mChannelLayoutThe size, in bytes, of the mMagicCookie parameter.
This data structure is used with the kAudioFormatProperty_BalanceFade property.
AudioFormat.hA specifier for the kAudioFormatProperty_FormatList property.
struct AudioFormatInfo {
AudioStreamBasicDescription mASBD;
const void *mMagicCookie;
UInt32 mMagicCookieSize;
};
typedef struct AudioFormatInfo AudioFormatInfo;
mASBDAn AudioStreamBasicDescription structure.
mMagicCookieA pointer to the decompression information for the data described in the mASBD parameter.
mMagicCookieSizeThe size, in bytes, of the mMagicCookie parameter.
AudioFormat.hRepresents a value from the kAudioFormatProperty_FormatList property.
struct AudioFormatListItem {
AudioStreamBasicDescription mASBD;
AudioChannelLayoutTag mChannelLayoutTag;
};
typedef struct AudioFormatListItem AudioFormatListItem;
mASBDAn AudioStreamBasicDescription structure.
mChannelLayoutTagAn AudioChannelLayoutTag value.
AudioFormat.hAudio panning information.
struct AudioPanningInfo {
UInt32 mPanningMode;
UInt32 mCoordinateFlags;
Float32 mCoordinates[3];
Float32 mGainScale;
const AudioChannelLayout *mOutputChannelMap;
};
typedef struct AudioPanningInfo AudioPanningInfo;
mPanningModeThe panning mode to be used for the pan. See “Audio Panning Modes.”
mCoordinateFlagsFor the available coordinate flags, see Channel Coordinate Flags.
mCoordinatesFor the available coordinate index constants, see Channel Coordinate Index Constants.
mGainScaleA 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.
mOutputChannelMapThe channel map used to determine channel volumes for the audio panning.
AudioFormat.hA type for four-char codes for audio format property identifiers.
typedef UInt32 AudioFormatPropertyID;
See “Audio Format Property Identifiers.”
AudioFormat.hIdentifiers for audio balance fade types.
enum {
kAudioBalanceFadeType_MaxUnityGain = 0,
kAudioBalanceFadeType_EqualPower = 1
};
kAudioBalanceFadeType_MaxUnityGainEnsures 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioBalanceFadeType_EqualPowerOverall 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
These constants are used as values for the mType field of the AudioBalanceFade structure.
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_ChannelLayoutForTag = 'cmpl',
kAudioFormatProperty_TagForChannelLayout = 'cmpt',
kAudioFormatProperty_ChannelLayoutName = 'lonm',
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'
};
kAudioFormatProperty_FormatInfoGeneral 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_FormatNameA 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_EncodeFormatIDsAn 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_DecodeFormatIDsAn 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_FormatListA 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ASBDFromESDSAn 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ChannelLayoutFromESDSAn AudioChannelLayout structure for a given elementary stream descriptor (ESDS). Set the inSpecifier parameter to an ESDS.
Available in iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_OutputFormatListA 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_FirstPlayableFormatFromListThe 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 iPhone OS 2.2 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_EncodersAn 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_DecodersAn 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_FormatIsVBRIndicates 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_FormatIsExternallyFramedIndicates 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_AvailableEncodeBitRatesAn array of AudioValueRange structures describing all available bit rates. The specifier is a UInt32 format identifier.
Available in iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_AvailableEncodeSampleRatesAn array of AudioValueRange structures describing all available sample rates. The specifier is a UInt32 format identifier.
Available in iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_AvailableEncodeChannelLayoutTagsAn 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_AvailableEncodeNumberChannelsAn 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ASBDFromMPEGPacketAn AudioStreamBasicDescription structure for a given MPEG Packet. The specifier is an MPEG Packet.
Available in iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_BitmapForLayoutTagA 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_MatrixMixMapA 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ChannelMapAn 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_NumberOfChannelsForLayoutThe 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ChannelLayoutForTagThe 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_TagForChannelLayoutAn 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ChannelLayoutNameThe 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 iPhone OS 2.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ChannelLayoutForBitmapThe 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ChannelNameThe 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ChannelShortNameAn 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_TagsForNumberOfChannelsAn array of AudioChannelLayoutTag values for the number of channels specified. The specifier is a UInt32 value that indicates the number of channels.
Available in iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_PanningMatrixAn 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_BalanceFadeAn 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ID3TagSizeA 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 iPhone OS 2.2 and later.
Declared in AudioFormat.h.
kAudioFormatProperty_ID3TagToDictionaryA 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 iPhone OS 2.2 and later.
Declared in AudioFormat.h.
A constant to determine which hardware codecs can be used.
enum {
kAudioFormatProperty_HardwareCodecCapabilities = 'hwcc',
};
kAudioFormatProperty_HardwareCodecCapabilitiesA 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
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).
enum {
kAudioDecoderComponentType = 'adec',
kAudioEncoderComponentType = 'aenc',
};
kAudioDecoderComponentTypeA 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAudioEncoderComponentTypeA 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 iPhone OS 3.0 and later.
Declared in AudioFormat.h.
For an example of how to use these constants, see the description for “Hardware Codec Capabilities.”
Identifiers for audio codec manufacturers and implementation types.
enum {
kAppleSoftwareAudioCodecManufacturer = 'appl',
kAppleHardwareAudioCodecManufacturer = 'aphw'
};
kAppleSoftwareAudioCodecManufacturerA software-based audio codec supplied by Apple Inc.
Available in iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kAppleHardwareAudioCodecManufacturerA hardware-based audio codec supplied by Apple Inc.
Available in iPhone OS 3.0 and later.
Declared in AudioFormat.h.
For an example of how to use these constants, see the description for “Hardware Codec Capabilities.”
Identifiers for audio panning algorithms.
enum {
kPanningMode_SoundField = 3,
kPanningMode_VectorBasedPanning = 4
};
kPanningMode_SoundFieldThe SoundField panning algorithm.
Available in iPhone OS 3.0 and later.
Declared in AudioFormat.h.
kPanningMode_VectorBasedPanningA vector-based panning algorithm.
Available in iPhone OS 3.0 and later.
Declared in AudioFormat.h.
This table lists the result codes defined for Audio Format Services.
Last updated: 2009-08-14