CoreAudioTypes
Discussion
This header defines the types and constants that all the CoreAudio APIs have in common.
Functions
A macro to get the number of channels out of an AudioChannelLayoutTag
#define AudioChannelLayoutTag_GetNumberOfChannels(layoutTag) ((UInt32)((layoutTag) & 0x0000FFFF))
Discussion
The low 16 bits of an AudioChannelLayoutTag gives the number of channels except
for kAudioChannelLayoutTag_UseChannelDescriptions and
kAudioChannelLayoutTag_UseChannelBitmap.
Parameter Descriptions
- layoutTag
- The AudioChannelLayoutTag to examine.
- function result
- The number of channels the tag indicates.
A C++ inline function for checking if an ASBD indicates native endian linear PCM
data.
#if defined (
__cplusplus
) (
inline bool IsAudioFormatNativeEndian(const AudioStreamBasicDescription& f
);
Parameter Descriptions
- f
- The AudioStreamBasicDescription to examine.
- function result
- Whether or not the ASBD indicates native endian linear PCM data.
Typedefs
A tag idenitfying how the channel is to be used.
typedef UInt32 AudioChannelLabel;
A tag identifying a particular pre-defined channel layout.
typedef UInt32 AudioChannelLayoutTag;
Structs
A structure to hold a buffer of audio data.
struct AudioBuffer {
UInt32 mNumberChannels;
UInt32 mDataByteSize;
void* mData;
} ;
Field Descriptions
- mNumberChannels
- The number of interleaved channels in the buffer.
- mDataByteSize
- The number of bytes in the buffer pointed at by mData.
- mData
- A pointer to the buffer of audio data.
A variable length array of AudioBuffer structures.
struct AudioBufferList {
UInt32 mNumberBuffers;
AudioBuffer mBuffers[kVariableLengthArray];
} ;
Field Descriptions
- mNumberBuffers
- The number of AudioBuffers in the mBuffers array.
- mBuffers
- A variable length array of AudioBuffers.
This structure describes a single channel.
struct AudioChannelDescription {
AudioChannelLabel mChannelLabel;
UInt32 mChannelFlags;
Float32 mCoordinates[3];
} ;
Field Descriptions
- mChannelLabel
- The AudioChannelLabel that describes the channel.
- mChannelFlags
- Flags that control the interpretation of mCoordinates.
- mCoordinates
- An ordered triple that specifies a precise speaker location.
This structure is used to specify channel layouts in files and hardware.
struct AudioChannelLayout {
AudioChannelLayoutTag mChannelLayoutTag;
UInt32 mChannelBitmap;
UInt32 mNumberChannelDescriptions;
AudioChannelDescription mChannelDescriptions[kVariableLengthArray];
} ;
Field Descriptions
- mChannelLayoutTag
- The AudioChannelLayoutTag that indicates the layout.
- mChannelBitmap
- If mChannelLayoutTag is set to kAudioChannelLayoutTag_UseChannelBitmap, this
field is the channel usage bitmap.
- mNumberChannelDescriptions
- The number of items in the mChannelDescriptions array.
- mChannelDescriptions
- A variable length array of AudioChannelDescriptions that describe the
layout.
This structure is used to describe codecs installed on the system.
struct AudioClassDescription {
OSType mType;
OSType mSubType;
OSType mManufacturer;
} ;
Field Descriptions
- mType
- The four char code codec type.
- mSubType
- The four char code codec subtype.
- mManufacturer
- The four char code codec manufacturer.
This structure encapsulates all the information for describing the basic
format properties of a stream of audio data.
struct AudioStreamBasicDescription {
Float64 mSampleRate;
UInt32 mFormatID;
UInt32 mFormatFlags;
UInt32 mBytesPerPacket;
UInt32 mFramesPerPacket;
UInt32 mBytesPerFrame;
UInt32 mChannelsPerFrame;
UInt32 mBitsPerChannel;
UInt32 mReserved;
} ;
Discussion
This structure is sufficient to describe any constant bit rate format that has
channels that are the same size. Extensions are required for variable bit rate
data and for constant bit rate data where the channels have unequal sizes.
However, where applicable, the appropriate fields will be filled out correctly
for these kinds of formats (the extra data is provided via separate properties).
In all fields, a value of 0 indicates that the field is either unknown, not
applicable or otherwise is inapproprate for the format and should be ignored.
Note that 0 is still a valid value for most formats in the mFormatFlags field.
In audio data a frame is one sample across all channels. In non-interleaved
audio, the per frame fields identify one channel. In interleaved audio, the per
frame fields identify the set of n channels. In uncompressed audio, a Packet is
one frame, (mFramesPerPacket == 1). In compressed audio, a Packet is an
indivisible chunk of compressed data, for example an AAC packet will contain
1024 sample frames.
Field Descriptions
- mSampleRate
- The number of sample frames per second of the data in the stream.
- mFormatID
- A four char code indicating the general kind of data in the stream.
- mFormatFlags
- Flags specific to each format.
- mBytesPerPacket
- The number of bytes in a packet of data.
- mFramesPerPacket
- The number of sample frames in each packet of data.
- mBytesPerFrame
- The number of bytes in a single sample frame of data.
- mChannelsPerFrame
- The number of channels in each frame of data.
- mBitsPerChannel
- The number of bits of sample data for each channel in a frame of data.
- mReserved
- Pads the structure out to force an even 8 byte alignment.
This structure describes the packet layout of a buffer of data where the size of
each packet may not be the same or where there is extraneous data between
packets.
struct AudioStreamPacketDescription {
SInt64 mStartOffset;
UInt32 mVariableFramesInPacket;
UInt32 mDataByteSize;
} ;
Field Descriptions
- mStartOffset
- The number of bytes from the start of the buffer to the beginning of the
packet.
- mVariableFramesInPacket
- The number of sample frames of data in the packet. For formats with a
constant number of frames per packet, this field is set to 0.
- mDataByteSize
- The number of bytes in the packet.
A strucutre that holds different representations of the same point in time.
struct AudioTimeStamp {
Float64 mSampleTime;
UInt64 mHostTime;
Float64 mRateScalar;
UInt64 mWordClockTime;
SMPTETime mSMPTETime;
UInt32 mFlags;
UInt32 mReserved;
} ;
Field Descriptions
- mSampleTime
- The absolute sample frame time.
- mHostTime
- The host machine's time base (see ).
- mRateScalar
- The ratio of actual host ticks per sample frame to the nominal host ticks
per sample frame.
- mWordClockTime
- The word clock time.
- mSMPTETime
- The SMPTE time.
- mFlags
- A set of flags indicating which representations of the time are valid.
- mReserved
- Pads the structure out to force an even 8 byte alignment.
This structure holds a pair of numbers that represent a continuous range of
values.
struct AudioValueRange {
Float64 mMinimum;
Float64 mMaximum;
} ;
Field Descriptions
- mMinimum
- The minimum value.
- mMaximum
- The maximum value.
This stucture holds the buffers necessary for translation operations.
struct AudioValueTranslation {
void* mInputData;
UInt32 mInputDataSize;
void* mOutputData;
UInt32 mOutputDataSize;
} ;
Field Descriptions
- mInputData
- The buffer containing the data to be translated.
- mInputDataSize
- The number of bytes in the buffer pointed at by mInputData.
- mOutputData
- The buffer to hold the result of the translation.
- mOutputDataSize
- The number of bytes in the buffer pointed at by mOutputData.
A structure for holding a SMPTE time.
struct SMPTETime {
SInt16 mSubframes;
SInt16 mSubframeDivisor;
UInt32 mCounter;
UInt32 mType;
UInt32 mFlags;
SInt16 mHours;
SInt16 mMinutes;
SInt16 mSeconds;
SInt16 mFrames;
} ;
Field Descriptions
- mSubframes
- The number of subframes in the full message.
- mSubframeDivisor
- The number of subframes per frame (typically 80).
- mCounter
- The total number of messages received.
- mType
- The kind of SMPTE time using the SMPTE time type constants.
- mFlags
- A set of flags that indicate the SMPTE state.
- mHours
- The number of hourse in the full message.
- mMinutes
- The number of minutes in the full message.
- mSeconds
- The number of seconds in the full message.
- mFrames
- The number of frames in the full message.
Enumerations
These constants are for use in the mChannelLabel field of an
AudioChannelDescription structure.
enum
{
kAudioChannelLabel_Unknown = 0xFFFFFFFF, // unknown or unspecified other use
kAudioChannelLabel_Unused = 0, // channel is present, but has no intended use or destination
kAudioChannelLabel_UseCoordinates = 100, // channel is described by the mCoordinates fields.
kAudioChannelLabel_Left = 1,
kAudioChannelLabel_Right = 2,
kAudioChannelLabel_Center = 3,
kAudioChannelLabel_LFEScreen = 4,
kAudioChannelLabel_LeftSurround = 5, // WAVE: "Back Left"
kAudioChannelLabel_RightSurround = 6, // WAVE: "Back Right"
kAudioChannelLabel_LeftCenter = 7,
kAudioChannelLabel_RightCenter = 8,
kAudioChannelLabel_CenterSurround = 9, // WAVE: "Back Center" or plain "Rear Surround"
kAudioChannelLabel_LeftSurroundDirect = 10, // WAVE: "Side Left"
kAudioChannelLabel_RightSurroundDirect = 11, // WAVE: "Side Right"
kAudioChannelLabel_TopCenterSurround = 12,
kAudioChannelLabel_VerticalHeightLeft = 13, // WAVE: "Top Front Left"
kAudioChannelLabel_VerticalHeightCenter = 14, // WAVE: "Top Front Center"
kAudioChannelLabel_VerticalHeightRight = 15, // WAVE: "Top Front Right"
kAudioChannelLabel_TopBackLeft = 16,
kAudioChannelLabel_TopBackCenter = 17,
kAudioChannelLabel_TopBackRight = 18,
kAudioChannelLabel_RearSurroundLeft = 33,
kAudioChannelLabel_RearSurroundRight = 34,
kAudioChannelLabel_LeftWide = 35,
kAudioChannelLabel_RightWide = 36,
kAudioChannelLabel_LFE2 = 37,
kAudioChannelLabel_LeftTotal = 38, // matrix encoded 4 channels
kAudioChannelLabel_RightTotal = 39, // matrix encoded 4 channels
kAudioChannelLabel_HearingImpaired = 40,
kAudioChannelLabel_Narration = 41,
kAudioChannelLabel_Mono = 42,
kAudioChannelLabel_DialogCentricMix = 43,
kAudioChannelLabel_CenterSurroundDirect = 44, // back center, non diffuse
// first order ambisonic channels
kAudioChannelLabel_Ambisonic_W = 200,
kAudioChannelLabel_Ambisonic_X = 201,
kAudioChannelLabel_Ambisonic_Y = 202,
kAudioChannelLabel_Ambisonic_Z = 203,
// Mid/Side Recording
kAudioChannelLabel_MS_Mid = 204,
kAudioChannelLabel_MS_Side = 205,
// X-Y Recording
kAudioChannelLabel_XY_X = 206,
kAudioChannelLabel_XY_Y = 207,
// other
kAudioChannelLabel_HeadphonesLeft = 301,
kAudioChannelLabel_HeadphonesRight = 302,
kAudioChannelLabel_ClickTrack = 304,
kAudioChannelLabel_ForeignLanguage = 305,
// generic discrete channel
kAudioChannelLabel_Discrete = 400,
// numbered discrete channel
kAudioChannelLabel_Discrete_0 = (1L<<16) | 0,
kAudioChannelLabel_Discrete_1 = (1L<<16) | 1,
kAudioChannelLabel_Discrete_2 = (1L<<16) | 2,
kAudioChannelLabel_Discrete_3 = (1L<<16) | 3,
kAudioChannelLabel_Discrete_4 = (1L<<16) | 4,
kAudioChannelLabel_Discrete_5 = (1L<<16) | 5,
kAudioChannelLabel_Discrete_6 = (1L<<16) | 6,
kAudioChannelLabel_Discrete_7 = (1L<<16) | 7,
kAudioChannelLabel_Discrete_8 = (1L<<16) | 8,
kAudioChannelLabel_Discrete_9 = (1L<<16) | 9,
kAudioChannelLabel_Discrete_10 = (1L<<16) | 10,
kAudioChannelLabel_Discrete_11 = (1L<<16) | 11,
kAudioChannelLabel_Discrete_12 = (1L<<16) | 12,
kAudioChannelLabel_Discrete_13 = (1L<<16) | 13,
kAudioChannelLabel_Discrete_14 = (1L<<16) | 14,
kAudioChannelLabel_Discrete_15 = (1L<<16) | 15,
kAudioChannelLabel_Discrete_65535 = (1L<<16) | 65535
};
Discussion
These channel labels attempt to list all labels in common use. Due to the
ambiguities in channel labeling by various groups, there may be some overlap or
duplication in the labels below. Use the label which most clearly describes what
you mean.
WAVE files seem to follow the USB spec for the channel flags. A channel map lets
you put these channels in any order, however a WAVE file only supports labels
1-18 and if present, they must be in the order given below. The integer values
for the labels below match the bit position of the label in the USB bitmap and
thus also the WAVE file bitmap.
These constants are used in the mChannelLayoutTag field of an AudioChannelLayout
structure.
enum
{
// Some channel abbreviations used below:
// L - left
// R - right
// C - center
// Ls - left surround
// Rs - right surround
// Cs - center surround
// Rls - rear left surround
// Rrs - rear right surround
// Lw - left wide
// Rw - right wide
// Lsd - left surround direct
// Rsd - right surround direct
// Lc - left center
// Rc - right center
// Ts - top surround
// Vhl - vertical height left
// Vhc - vertical height center
// Vhr - vertical height right
// Lt - left matrix total. for matrix encoded stereo.
// Rt - right matrix total. for matrix encoded stereo.
// General layouts
kAudioChannelLayoutTag_UseChannelDescriptions = (0L<<16) | 0, // use the array of AudioChannelDescriptions to define the mapping.
kAudioChannelLayoutTag_UseChannelBitmap = (1L<<16) | 0, // use the bitmap to define the mapping.
kAudioChannelLayoutTag_Mono = (100L<<16) | 1, // a standard mono stream
kAudioChannelLayoutTag_Stereo = (101L<<16) | 2, // a standard stereo stream (L R) - implied playback
kAudioChannelLayoutTag_StereoHeadphones = (102L<<16) | 2, // a standard stereo stream (L R) - implied headphone playbac
kAudioChannelLayoutTag_MatrixStereo = (103L<<16) | 2, // a matrix encoded stereo stream (Lt, Rt)
kAudioChannelLayoutTag_MidSide = (104L<<16) | 2, // mid/side recording
kAudioChannelLayoutTag_XY = (105L<<16) | 2, // coincident mic pair (often 2 figure 8's)
kAudioChannelLayoutTag_Binaural = (106L<<16) | 2, // binaural stereo (left, right)
kAudioChannelLayoutTag_Ambisonic_B_Format = (107L<<16) | 4, // W, X, Y, Z
kAudioChannelLayoutTag_Quadraphonic = (108L<<16) | 4, // front left, front right, back left, back right
kAudioChannelLayoutTag_Pentagonal = (109L<<16) | 5, // left, right, rear left, rear right, center
kAudioChannelLayoutTag_Hexagonal = (110L<<16) | 6, // left, right, rear left, rear right, center, rear
kAudioChannelLayoutTag_Octagonal = (111L<<16) | 8, // front left, front right, rear left, rear right,
// front center, rear center, side left, side right
kAudioChannelLayoutTag_Cube = (112L<<16) | 8, // left, right, rear left, rear right
// top left, top right, top rear left, top rear right
// MPEG defined layouts
kAudioChannelLayoutTag_MPEG_1_0 = kAudioChannelLayoutTag_Mono, // C
kAudioChannelLayoutTag_MPEG_2_0 = kAudioChannelLayoutTag_Stereo, // L R
kAudioChannelLayoutTag_MPEG_3_0_A = (113L<<16) | 3, // L R C
kAudioChannelLayoutTag_MPEG_3_0_B = (114L<<16) | 3, // C L R
kAudioChannelLayoutTag_MPEG_4_0_A = (115L<<16) | 4, // L R C Cs
kAudioChannelLayoutTag_MPEG_4_0_B = (116L<<16) | 4, // C L R Cs
kAudioChannelLayoutTag_MPEG_5_0_A = (117L<<16) | 5, // L R C Ls Rs
kAudioChannelLayoutTag_MPEG_5_0_B = (118L<<16) | 5, // L R Ls Rs C
kAudioChannelLayoutTag_MPEG_5_0_C = (119L<<16) | 5, // L C R Ls Rs
kAudioChannelLayoutTag_MPEG_5_0_D = (120L<<16) | 5, // C L R Ls Rs
kAudioChannelLayoutTag_MPEG_5_1_A = (121L<<16) | 6, // L R C LFE Ls Rs
kAudioChannelLayoutTag_MPEG_5_1_B = (122L<<16) | 6, // L R Ls Rs C LFE
kAudioChannelLayoutTag_MPEG_5_1_C = (123L<<16) | 6, // L C R Ls Rs LFE
kAudioChannelLayoutTag_MPEG_5_1_D = (124L<<16) | 6, // C L R Ls Rs LFE
kAudioChannelLayoutTag_MPEG_6_1_A = (125L<<16) | 7, // L R C LFE Ls Rs Cs
kAudioChannelLayoutTag_MPEG_7_1_A = (126L<<16) | 8, // L R C LFE Ls Rs Lc Rc
kAudioChannelLayoutTag_MPEG_7_1_B = (127L<<16) | 8, // C Lc Rc L R Ls Rs LFE (doc: IS-13818-7 MPEG2-AAC Table 3.1)
kAudioChannelLayoutTag_MPEG_7_1_C = (128L<<16) | 8, // L R C LFE Ls R Rls Rrs
kAudioChannelLayoutTag_Emagic_Default_7_1 = (129L<<16) | 8, // L R Ls Rs C LFE Lc Rc
kAudioChannelLayoutTag_SMPTE_DTV = (130L<<16) | 8, // L R C LFE Ls Rs Lt Rt
// (kAudioChannelLayoutTag_ITU_5_1 plus a matrix encoded stereo mix)
// ITU defined layouts
kAudioChannelLayoutTag_ITU_1_0 = kAudioChannelLayoutTag_Mono, // C
kAudioChannelLayoutTag_ITU_2_0 = kAudioChannelLayoutTag_Stereo, // L R
kAudioChannelLayoutTag_ITU_2_1 = (131L<<16) | 3, // L R Cs
kAudioChannelLayoutTag_ITU_2_2 = (132L<<16) | 4, // L R Ls Rs
kAudioChannelLayoutTag_ITU_3_0 = kAudioChannelLayoutTag_MPEG_3_0_A, // L R C
kAudioChannelLayoutTag_ITU_3_1 = kAudioChannelLayoutTag_MPEG_4_0_A, // L R C Cs
kAudioChannelLayoutTag_ITU_3_2 = kAudioChannelLayoutTag_MPEG_5_0_A, // L R C Ls Rs
kAudioChannelLayoutTag_ITU_3_2_1 = kAudioChannelLayoutTag_MPEG_5_1_A, // L R C LFE Ls Rs
kAudioChannelLayoutTag_ITU_3_4_1 = kAudioChannelLayoutTag_MPEG_7_1_C, // L R C LFE Ls Rs Rls Rrs
// DVD defined layouts
kAudioChannelLayoutTag_DVD_0 = kAudioChannelLayoutTag_Mono, // C (mono)
kAudioChannelLayoutTag_DVD_1 = kAudioChannelLayoutTag_Stereo, // L R
kAudioChannelLayoutTag_DVD_2 = kAudioChannelLayoutTag_ITU_2_1, // L R Cs
kAudioChannelLayoutTag_DVD_3 = kAudioChannelLayoutTag_ITU_2_2, // L R Ls Rs
kAudioChannelLayoutTag_DVD_4 = (133L<<16) | 3, // L R LFE
kAudioChannelLayoutTag_DVD_5 = (134L<<16) | 4, // L R LFE Cs
kAudioChannelLayoutTag_DVD_6 = (135L<<16) | 5, // L R LFE Ls Rs
kAudioChannelLayoutTag_DVD_7 = kAudioChannelLayoutTag_MPEG_3_0_A, // L R C
kAudioChannelLayoutTag_DVD_8 = kAudioChannelLayoutTag_MPEG_4_0_A, // L R C Cs
kAudioChannelLayoutTag_DVD_9 = kAudioChannelLayoutTag_MPEG_5_0_A, // L R C Ls Rs
kAudioChannelLayoutTag_DVD_10 = (136L<<16) | 4, // L R C LFE
kAudioChannelLayoutTag_DVD_11 = (137L<<16) | 5, // L R C LFE Cs
kAudioChannelLayoutTag_DVD_12 = kAudioChannelLayoutTag_MPEG_5_1_A, // L R C LFE Ls Rs
// 13 through 17 are duplicates of 8 through 12.
kAudioChannelLayoutTag_DVD_13 = kAudioChannelLayoutTag_DVD_8, // L R C Cs
kAudioChannelLayoutTag_DVD_14 = kAudioChannelLayoutTag_DVD_9, // L R C Ls Rs
kAudioChannelLayoutTag_DVD_15 = kAudioChannelLayoutTag_DVD_10, // L R C LFE
kAudioChannelLayoutTag_DVD_16 = kAudioChannelLayoutTag_DVD_11, // L R C LFE Cs
kAudioChannelLayoutTag_DVD_17 = kAudioChannelLayoutTag_DVD_12, // L R C LFE Ls Rs
kAudioChannelLayoutTag_DVD_18 = (138L<<16) | 5, // L R Ls Rs LFE
kAudioChannelLayoutTag_DVD_19 = kAudioChannelLayoutTag_MPEG_5_0_B, // L R Ls Rs C
kAudioChannelLayoutTag_DVD_20 = kAudioChannelLayoutTag_MPEG_5_1_B, // L R Ls Rs C LFE
// These layouts are recommended for AudioUnit usage
// These are the symmetrical layouts
kAudioChannelLayoutTag_AudioUnit_4 = kAudioChannelLayoutTag_Quadraphonic,
kAudioChannelLayoutTag_AudioUnit_5 = kAudioChannelLayoutTag_Pentagonal,
kAudioChannelLayoutTag_AudioUnit_6 = kAudioChannelLayoutTag_Hexagonal,
kAudioChannelLayoutTag_AudioUnit_8 = kAudioChannelLayoutTag_Octagonal,
// These are the surround-based layouts
kAudioChannelLayoutTag_AudioUnit_5_0 = kAudioChannelLayoutTag_MPEG_5_0_B, // L R Ls Rs C
kAudioChannelLayoutTag_AudioUnit_6_0 = (139L<<16) | 6, // L R Ls Rs C Cs
kAudioChannelLayoutTag_AudioUnit_7_0 = (140L<<16) | 7, // L R Ls Rs C Rls Rrs
kAudioChannelLayoutTag_AudioUnit_5_1 = kAudioChannelLayoutTag_MPEG_5_1_A, // L R C LFE Ls Rs
kAudioChannelLayoutTag_AudioUnit_6_1 = kAudioChannelLayoutTag_MPEG_6_1_A, // L R C LFE Ls Rs Cs
kAudioChannelLayoutTag_AudioUnit_7_1 = kAudioChannelLayoutTag_MPEG_7_1_C, // L R C LFE Ls Rs Rls Rrs
kAudioChannelLayoutTag_AAC_Quadraphonic = kAudioChannelLayoutTag_Quadraphonic, // L R Ls Rs
kAudioChannelLayoutTag_AAC_4_0 = kAudioChannelLayoutTag_MPEG_4_0_B, // C L R Cs
kAudioChannelLayoutTag_AAC_5_0 = kAudioChannelLayoutTag_MPEG_5_0_D, // C L R Ls Rs
kAudioChannelLayoutTag_AAC_5_1 = kAudioChannelLayoutTag_MPEG_5_1_D, // C L R Ls Rs Lfe
kAudioChannelLayoutTag_AAC_6_0 = (141L<<16) | 6, // C L R Ls Rs Cs
kAudioChannelLayoutTag_AAC_6_1 = (142L<<16) | 7, // C L R Ls Rs Cs Lfe
kAudioChannelLayoutTag_AAC_7_0 = (143L<<16) | 7, // C L R Ls Rs Rls Rrs
kAudioChannelLayoutTag_AAC_7_1 = kAudioChannelLayoutTag_MPEG_7_1_B, // C Lc Rc L R Ls Rs Lfe
kAudioChannelLayoutTag_AAC_Octagonal = (144L<<16) | 8, // C L R Ls Rs Rls Rrs Cs
kAudioChannelLayoutTag_TMH_10_2_std = (145L<<16) | 16, // L R C Vhc Lsd Rsd Ls Rs Vhl Vhr Lw Rw Csd Cs LFE1 LFE2
kAudioChannelLayoutTag_TMH_10_2_full = (146L<<16) | 21, // TMH_10_2_std plus: Lc Rc HI VI Haptic
kAudioChannelLayoutTag_DiscreteInOrder = (147L<<16) | 0 // needs to be ORed with the actual number of channels
};
Discussion
Constants
Constants for use with AudioStreamBasicDescription
enum
{
kAudioStreamAnyRate = 0
};
Discussion
Constants
Constants
- kAudioStreamAnyRate
- The format can use any sample rate. Note that this constant can only appear
in listings of supported formats. It will never appear in a current format.
The flags that indicate which fields in an AudioTimeStamp structure are valid.
enum
{
kAudioTimeStampSampleTimeValid = (1L << 0),
kAudioTimeStampHostTimeValid = (1L << 1),
kAudioTimeStampRateScalarValid = (1L << 2),
kAudioTimeStampWordClockTimeValid = (1L << 3),
kAudioTimeStampSMPTETimeValid = (1L << 4)
};
Discussion
Flags
Constants
- kAudioTimeStampSampleTimeValid
- The sample frame time is valid.
- kAudioTimeStampHostTimeValid
- The host time is valid.
- kAudioTimeStampRateScalarValid
- The rate scalar is valid.
- kAudioTimeStampWordClockTimeValid
- The word clock time is valid.
- kAudioTimeStampSMPTETimeValid
- The SMPTE time is valid.
These constants are for use in the mChannelBitmap field of an
AudioChannelLayout structure.
enum
{
kAudioChannelBit_Left = (1L<<0),
kAudioChannelBit_Right = (1L<<1),
kAudioChannelBit_Center = (1L<<2),
kAudioChannelBit_LFEScreen = (1L<<3),
kAudioChannelBit_LeftSurround = (1L<<4), // WAVE: "Back Left"
kAudioChannelBit_RightSurround = (1L<<5), // WAVE: "Back Right"
kAudioChannelBit_LeftCenter = (1L<<6),
kAudioChannelBit_RightCenter = (1L<<7),
kAudioChannelBit_CenterSurround = (1L<<8), // WAVE: "Back Center"
kAudioChannelBit_LeftSurroundDirect = (1L<<9), // WAVE: "Side Left"
kAudioChannelBit_RightSurroundDirect = (1L<<10), // WAVE: "Side Right"
kAudioChannelBit_TopCenterSurround = (1L<<11),
kAudioChannelBit_VerticalHeightLeft = (1L<<12), // WAVE: "Top Front Left"
kAudioChannelBit_VerticalHeightCenter = (1L<<13), // WAVE: "Top Front Center"
kAudioChannelBit_VerticalHeightRight = (1L<<14), // WAVE: "Top Front Right"
kAudioChannelBit_TopBackLeft = (1L<<15),
kAudioChannelBit_TopBackCenter = (1L<<16),
kAudioChannelBit_TopBackRight = (1L<<17)
};
Discussion
Bitmap Constants
These constants are used in the mChannelFlags field of an
AudioChannelDescription structure.
enum
{
kAudioChannelFlags_AllOff = 0,
kAudioChannelFlags_RectangularCoordinates = (1L<<0),
kAudioChannelFlags_SphericalCoordinates = (1L<<1),
kAudioChannelFlags_Meters = (1L<<2)
};
Discussion
Coordinate Flags
Constants
- kAudioChannelFlags_RectangularCoordinates
- The channel is specified by the cartesioan coordinates of the speaker
position. This flag is mutally exclusive with
kAudioChannelFlags_SphericalCoordinates.
- kAudioChannelFlags_SphericalCoordinates
- The channel is specified by the spherical coordinates of the speaker
position. This flag is mutally exclusive with
kAudioChannelFlags_RectangularCoordinates.
- kAudioChannelFlags_Meters
- Set to indicate the units are in meters, clear to indicate the units are
relative to the unit cube or unit sphere.
Constants for indexing the mCoordinates array in an AudioChannelDescription
structure.
enum
{
kAudioChannelCoordinates_LeftRight = 0,
kAudioChannelCoordinates_BackFront = 1,
kAudioChannelCoordinates_DownUp = 2,
kAudioChannelCoordinates_Azimuth = 0,
kAudioChannelCoordinates_Elevation = 1,
kAudioChannelCoordinates_Distance = 2
};
Discussion
Coordinate Index Constants
Constants
- kAudioChannelCoordinates_LeftRight
- For rectangulare coordinates, negative is left and positive is right.
- kAudioChannelCoordinates_BackFront
- For rectangulare coordinates, negative is back and positive is front.
- kAudioChannelCoordinates_DownUp
- For rectangulare coordinates, negative is below ground level, 0 is ground
level, and positive is above ground level.
- kAudioChannelCoordinates_Azimuth
- For spherical coordinates, 0 is front center, positive is right, negative is
left. This is measured in degrees.
- kAudioChannelCoordinates_Elevation
- For spherical coordinates, +90 is zenith, 0 is horizontal, -90 is nadir.
This is measured in degrees.
- kAudioChannelCoordinates_Distance
- For spherical coordinates, the units are described by flags.
Some commonly used combinations of flags for AudioStreamBasicDescriptions.
enum
{
#if TARGET_RT_BIG_ENDIAN
kAudioFormatFlagsNativeEndian = kAudioFormatFlagIsBigEndian,
#else
kAudioFormatFlagsNativeEndian = 0,
#endif
kAudioFormatFlagsNativeFloatPacked = kAudioFormatFlagIsFloat | kAudioFormatFlagsNativeEndian | kAudioFormatFlagIsPacked
};
Discussion
Used Combinations of ASBD Flags
Constants
- kAudioFormatFlagsNativeEndian
- Defined to set or clear kAudioFormatFlagIsBigEndian depending on the
endianness of the processor at build time.
- kAudioFormatFlagsNativeFloatPacked
- The flags for the canonical format of fully packed, native endian floating
point data.
Some commonly used combinations of AudioTimeStamp flags.
enum
{
kAudioTimeStampSampleHostTimeValid = (kAudioTimeStampSampleTimeValid | kAudioTimeStampHostTimeValid)
};
Discussion
Combinations of AudioTimeStamp Flags
Constants
- kAudioTimeStampSampleHostTimeValid
- The sample frame time and the host time are valid.
The four char code IDs used to identify individual formats of audio data.
enum
{
kAudioFormatLinearPCM = 'lpcm',
kAudioFormatAC3 = 'ac-3',
kAudioFormat60958AC3 = 'cac3',
kAudioFormatAppleIMA4 = 'ima4',
kAudioFormatMPEG4AAC = 'aac ',
kAudioFormatMPEG4CELP = 'celp',
kAudioFormatMPEG4HVXC = 'hvxc',
kAudioFormatMPEG4TwinVQ = 'twvq',
kAudioFormatMACE3 = 'MAC3',
kAudioFormatMACE6 = 'MAC6',
kAudioFormatULaw = 'ulaw',
kAudioFormatALaw = 'alaw',
kAudioFormatQDesign = 'QDMC',
kAudioFormatQDesign2 = 'QDM2',
kAudioFormatQUALCOMM = 'Qclp',
kAudioFormatMPEGLayer1 = '.mp1',
kAudioFormatMPEGLayer2 = '.mp2',
kAudioFormatMPEGLayer3 = '.mp3',
kAudioFormatDVAudio = 'dvca',
kAudioFormatVariableDurationDVAudio = 'vdva',
kAudioFormatTimeCode = 'time',
kAudioFormatMIDIStream = 'midi',
kAudioFormatParameterValueStream = 'apvs',
kAudioFormatAppleLossless = 'alac'
};
Discussion
IDs
Constants
- kAudioFormatLinearPCM
- Linear PCM, uses the standard flags.
- kAudioFormatAC3
- AC-3, has no flags.
- kAudioFormat60958AC3
- AC-3 packaged for transport over an IEC 60958 compliant digital audio
interface. Uses the standard flags.
- kAudioFormatAppleIMA4
- Apples implementation of IMA 4:1 ADPCM, has no flags.
- kAudioFormatMPEG4AAC
- MPEG-4 AAC, the flags field contains the MPEG-4 audio object type constant
indicating the specific kind of data.
- kAudioFormatMPEG4CELP
- MPEG-4 CELP, the flags field contains the MPEG-4 audio object type constant
indicating the specific kind of data.
- kAudioFormatMPEG4HVXC
- MPEG-4 HVXC, the flags field contains the MPEG-4 audio object type constant
indicating the specific kind of data.
- kAudioFormatMPEG4TwinVQ
- MPEG-4 TwinVQ, the flags field contains the MPEG-4 audio object type
constant indicating the specific kind of data.
- kAudioFormatMACE3
- MACE 3:1, has no flags.
- kAudioFormatMACE6
- MACE 6:1, has no flags.
- kAudioFormatULaw
- µLaw 2:1, has no flags.
- kAudioFormatALaw
- aLaw 2:1, has no flags.
- kAudioFormatQDesign
- QDesign music, has no flags
- kAudioFormatQDesign2
- QDesign2 music, has no flags
- kAudioFormatQUALCOMM
- QUALCOMM PureVoice, has no flags
- kAudioFormatMPEGLayer1
- MPEG-1/2, Layer 1 audio, has no flags
- kAudioFormatMPEGLayer2
- MPEG-1/2, Layer 2 audio, has no flags
- kAudioFormatMPEGLayer3
- MPEG-1/2, Layer 3 audio, has no flags
- kAudioFormatDVAudio
- DV Audio, has no flags
- kAudioFormatVariableDurationDVAudio
- Variable duration DV Audio, has no flags.
- kAudioFormatTimeCode
- A stream of IOAudioTimeStamps, uses the IOAudioTimeStamp flags (see
IOKit/audio/IOAudioTypes.h).
- kAudioFormatMIDIStream
- A stream of MIDIPacketLists where the time stamps in the MIDIPacketList are
sample offsets in the stream. The mSampleRate field is used to describe how
time is passed in this kind of stream and an AudioUnit that receives or
generates this stream can use this sample rate, the number of frames it is
rendering and the sample offsets within the MIDIPacketList to define the
time for any MIDI event within this list. It has no flags.
- kAudioFormatParameterValueStream
- A "side-chain" of Float32 data that can be fed or generated by an AudioUnit
and is used to send a high density of parameter value control information.
An AU will typically run a ParameterValueStream at either the sample rate of
the AudioUnit's audio data, or some integer divisor of this (say a half or a
third of the sample rate of the audio). The Sample Rate of the ASBD
describes this relationship. It has no flags.
- kAudioFormatAppleLossless
- Apple Lossless, has no flags.
Constants that describe the various kinds of MPEG-4 audio data.
enum
{
kMPEG4Object_AAC_Main = 1,
kMPEG4Object_AAC_LC = 2,
kMPEG4Object_AAC_SSR = 3,
kMPEG4Object_AAC_LTP = 4,
kMPEG4Object_AAC_SBR = 5,
kMPEG4Object_AAC_Scalable = 6,
kMPEG4Object_TwinVQ = 7,
kMPEG4Object_CELP = 8,
kMPEG4Object_HVXC = 9
};
Discussion
These constants are used in the flags field of an AudioStreamBasicDescription
that describes an MPEG-4 audio stream.
Constants that describe the type of SMPTE time.
enum
{
kSMPTETimeType24 = 0,
kSMPTETimeType25 = 1,
kSMPTETimeType30Drop = 2,
kSMPTETimeType30 = 3,
kSMPTETimeType2997 = 4,
kSMPTETimeType2997Drop = 5,
kSMPTETimeType60 = 6,
kSMPTETimeType5994 = 7
};
Discussion
Time Types
Constants
- kSMPTETimeType24
- 24 Frame
- kSMPTETimeType25
- 25 Frame
- kSMPTETimeType30Drop
- 30 Drop Frame
- kSMPTETimeType30
- 30 Frame
- kSMPTETimeType2997
- 29.97 Frame
- kSMPTETimeType2997Drop
- 29.97 Drop Frame
- kSMPTETimeType60
- 60 Frame
- kSMPTETimeType5994
- 59.94 Frame
Flags that describe the SMPTE time state.
enum
{
kSMPTETimeValid = (1L << 0),
kSMPTETimeRunning = (1L << 1)
};
Discussion
State Flags
Constants
- kSMPTETimeValid
- The full time is valid.
- kSMPTETimeRunning
- Time is running.
These are the standard flags for use in the mFormatFlags field of the
AudioStreamBasicDescription structure.
enum
{
kAudioFormatFlagIsFloat = (1L << 0),
kAudioFormatFlagIsBigEndian = (1L << 1),
kAudioFormatFlagIsSignedInteger = (1L << 2),
kAudioFormatFlagIsPacked = (1L << 3),
kAudioFormatFlagIsAlignedHigh = (1L << 4),
kAudioFormatFlagIsNonInterleaved = (1L << 5),
kAudioFormatFlagIsNonMixable = (1L << 6),
kAudioFormatFlagsAreAllClear = (1L << 31),
kLinearPCMFormatFlagIsFloat = kAudioFormatFlagIsFloat,
kLinearPCMFormatFlagIsBigEndian = kAudioFormatFlagIsBigEndian,
kLinearPCMFormatFlagIsSignedInteger = kAudioFormatFlagIsSignedInteger,
kLinearPCMFormatFlagIsPacked = kAudioFormatFlagIsPacked,
kLinearPCMFormatFlagIsAlignedHigh = kAudioFormatFlagIsAlignedHigh,
kLinearPCMFormatFlagIsNonInterleaved = kAudioFormatFlagIsNonInterleaved,
kLinearPCMFormatFlagIsNonMixable = kAudioFormatFlagIsNonMixable,
kLinearPCMFormatFlagsAreAllClear = kAudioFormatFlagsAreAllClear,
kAppleLosslessFormatFlag_16BitSourceData = 1,
kAppleLosslessFormatFlag_20BitSourceData = 2,
kAppleLosslessFormatFlag_24BitSourceData = 3,
kAppleLosslessFormatFlag_32BitSourceData = 4
};
Discussion
Typically, when an ASBD is being used, the fields describe the complete layout
of the sample data in the buffers that are represented by this description -
where typically those buffers are represented by an AudioBuffer that is
contained in an AudioBufferList.
However, when an ASBD has the kAudioFormatFlagIsNonInterleaved flag, the
AudioBufferList has a different structure and semantic. In this case, the ASBD
fields will describe the format of ONE of the AudioBuffers that are contained in
the list, AND each AudioBuffer in the list is determined to have a single (mono)
channel of audio data. Then, the ASBD's mChannelsPerFrame will indicate the
total number of AudioBuffers that are contained within the AudioBufferList -
where each buffer contains one channel. This is used primarily with the
AudioUnit (and AudioConverter) representation of this list - and won't be found
in the AudioHardware usage of this structure.
Constants
- kAudioFormatFlagIsFloat
- Set for floating point, clear for integer.
- kAudioFormatFlagIsBigEndian
- Set for big endian, clear for little endian.
- kAudioFormatFlagIsSignedInteger
- Set for signed integer, clear for unsigned integer. This is only valid if
kAudioFormatFlagIsFloat is clear.
- kAudioFormatFlagIsPacked
- Set if the sample bits occupy the entire available bits for the channel,
clear if they are high or low aligned within the channel.
- kAudioFormatFlagIsAlignedHigh
- Set if the sample bits are placed into the high bits of the channel, clear
for low bit placement. This is only valid if kAudioFormatFlagIsPacked is
clear.
- kAudioFormatFlagIsNonInterleaved
- Set if the samples for each channel are located contiguously and the
channels are layed out end to end, clear if the samples for each frame are
layed out contiguously and the frames layed out end to end.
- kAudioFormatFlagIsNonMixable
- Set to indicate when a format is non-mixable. Note that this flag is only
used when interacting with the HAL's stream format information. It is not a
valid flag for any other uses.
- kAudioFormatFlagsAreAllClear
- Set if all the flags would be clear in order to preserve 0 as the wild card
value.
- kLinearPCMFormatFlagIsFloat
- Synonym for kAudioFormatFlagIsFloat.
- kLinearPCMFormatFlagIsBigEndian
- Synonym for kAudioFormatFlagIsBigEndian.
- kLinearPCMFormatFlagIsSignedInteger
- Synonym for kAudioFormatFlagIsSignedInteger.
- kLinearPCMFormatFlagIsPacked
- Synonym for kAudioFormatFlagIsPacked.
- kLinearPCMFormatFlagIsAlignedHigh
- Synonym for kAudioFormatFlagIsAlignedHigh.
- kLinearPCMFormatFlagIsNonInterleaved
- Synonym for kAudioFormatFlagIsNonInterleaved.
- kLinearPCMFormatFlagIsNonMixable
- Synonym for kAudioFormatFlagIsNonMixable.
- kLinearPCMFormatFlagsAreAllClear
- Synonym for kAudioFormatFlagsAreAllClear.
- kAppleLosslessFormatFlag_16BitSourceData
- This flag is set for Apple Lossless data that was sourced from 16 bit native
endian signed integer data.
- kAppleLosslessFormatFlag_20BitSourceData
- This flag is set for Apple Lossless data that was sourced from 20 bit native
endian signed integer data aligned high in 24 bits.
- kAppleLosslessFormatFlag_24BitSourceData
- This flag is set for Apple Lossless data that was sourced from 24 bit native
endian signed integer data.
- kAppleLosslessFormatFlag_32BitSourceData
- This flag is set for Apple Lossless data that was sourced from 32 bit native
endian signed integer data.
#defines
A macro for checking if an ASBD indicates native endian linear PCM data.
#define TestAudioFormatNativeEndian(f) ((f.mFormatID == kAudioFormatLinearPCM) && ((f.mFormatFlags & kAudioFormatFlagIsBigEndian) == kAudioFormatFlagsNativeEndian))
(Last Updated 12/13/2004)