Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Core Audio Types Reference
This chapter describes the structures and constants shared throughout all portions of Core Audio.
The CoreAudioTypes.h file
contains general structures and typedefs that are found and used throughout
Core Audio, including structures that represent an audio buffer,
a structure describing the particular format of an audio stream,
channel layout structures, and structures for timing information.
In this section:
Audio Value Structures
Audio Buffer Structures
Audio Stream Basic Description
Audio Stream Packet Description
SMPTE Time
Audio Time Stamp
Audio Channel Layouts
Audio Value Structures
AudioValueRange
Represents a continuous range of values.
typedef struct AudioValueRange{
Float64 mMinimum;
Float64 mMaximum;
} AudioValueRange;
Availability
- Available in Mac OS X v10.1 and later.
Declared In
CoreAudioTypes.h
AudioValueTranslation
Contains an input and output buffer and associated size values, for translation use.
typedef struct AudioValueTranslation {
void* mInputData;
UInt32 mInputDataSize;
void* mOutputData;
UInt32 mOutputDataSize;
} AudioValueTranslation;
Availability
- Available in Mac OS X v10.1 and later.
Declared In
CoreAudioTypes.h
Audio Buffer Structures
AudioBuffer
A single buffer and the associated data.
typedef struct AudioBuffer {
UInt32 mNumberChannels;
UInt32 mDataByteSize;
void* mData;
} AudioBuffer;
Discussion
This structure is not used on its own, but with AudioBufferList as
one of its data members. An instance of AudioBuffer keeps
track of the number of channels in the buffer, the size of the buffer,
and a pointer to the buffer data.
Availability
- Available in Mac OS X v10.0 and later.
Declared In
CoreAudioTypes.h
AudioBufferList
Keeps track of multiple buffers.
typedef struct AudioBufferList {
UInt32 mNumberBuffers;
AudioBuffer mBuffers[1];
} AudioBufferList;
Discussion
When audio data is interleaved, only one buffer is needed in the AudioBufferList; when dealing with multiple mono channels, each will need its own buffer. This is accomplished by allocating the needed space and pointing mBuffers to it.
Availability
- Available in Mac OS X v10.0 and later.
Declared In
CoreAudioTypes.h
Audio Stream Basic Description
AudioStreamBasicDescription
Contains all the information needed for describing streams of audio data.
typedef struct AudioStreamBasicDescription {
Float64 mSampleRate;
UInt32 mFormatID;
UInt32 mFormatFlags;
UInt32 mBytesPerPacket;
UInt32 mFramesPerPacket;
UInt32 mBytesPerFrame;
UInt32 mChannelsPerFrame;
UInt32 mBitsPerChannel;
UInt32 mReserved;
} AudioStreamBasicDescription;
Discussion
The AudioStreamBasicDescription is the
fundamental descriptive structure in Core Audio. The “Audio Format” API
deals extensively with AudioStreamBasicDescription,
as do most other parts of Core Audio.
Availability
- Available in Mac OS X v10.0 and later.
Declared In
CoreAudioTypes.h
Format IDs
These values reflect various audio formats available from
within Core Audio, and are used to populate the mFormatID field
in AudioStreamBasicDescription instances.
kAudioFormatLinearPCM = 'lpcm' |
kAudioFormatAC3 = 'ac-3' |
kAudioFormat60958AC3 ='cac3' |
kAudioFormatMPEG = 'mpeg' |
kAudioFormatAppleIMA4 = 'ima4' |
kAudioFormatMPEG4AAC = 'aac ' |
kAudioFormatMPEG4CELP = 'celp' |
kAudioFormatMPEG4HVXC = 'hvxc' |
kAudioFormatMPEG4TwinVQ = 'twvq' |
kAudioFormatTimeCode = 'time' |
kAudioFormatMIDIStream = 'midi' |
kAudioFormatParameterValueStream = 'apvs' |
Format Flags
These values are used to fill the mFormatFlags field
of an AudioStreamBasicDescription, and reflect the
formatting of the audio stream data.
Standard flags:
kAudioFormatFlagIsFloat = (1L << 0) |
kAudioFormatFlagIsBigEndian = (1L << 1) |
kAudioFormatFlagIsSignedInteger = (1L << 2) |
kAudioFormatFlagIsPacked = (1L << 3) |
kAudioFormatFlagIsAlignedHigh = (1L << 4) |
kAudioFormatFlagIsNonInterleaved = (1L << 5) |
kAudioFormatFlagsAreAllClear = (1L << 31) |
Linear PCM flags:
kLinearPCMFormatFlagIsFloat = kAudioFormatFlagIsFloat |
kLinearPCMFormatFlagIsBigEndian = kAudioFormatFlagIsBigEndian |
kLinearPCMFormatFlagIsSignedInteger = kAudioFormatFlagIsSignedInteger |
kLinearPCMFormatFlagIsPacked = kAudioFormatFlagIsPacked |
kLinearPCMFormatFlagIsAlignedHigh = kAudioFormatFlagIsAlignedHigh |
kLinearPCMFormatFlagIsNonInterleaved = kAudioFormatFlagIsNonInterleaved |
kLinearPCMFormatFlagsAreAllClear = kAudioFormatFlagsAreAllClear |
Audio Stream Packet Description
AudioStreamPacketDescription
typedef struct AudioStreamPacketDescription {
SInt64 mStartOffset;
UInt64 mLength;
} AudioStreamPacketDescription;
Availability
- Available in Mac OS X v10.2 and later.
Declared In
CoreAudioTypes.h
SMPTE Time
SMPTETime
SMPTE time is a format used to sync audio and video streams, based on video framing.
typedef struct SMPTETime {
UInt64 mCounter;
UInt32 mType;
UInt32 mFlags;
SInt16 mHours;
SInt16 mMinutes;
SInt16 mSeconds;
SInt16 mFrames;
} SMPTETime;
Availability
- Available in Mac OS X v10.0 and later.
Declared In
CoreAudioTypes.h
SMPTE Types
These constants are used for the mType value
in SMPTETime to specify different frame rates.
kSMPTETimeType24 = 0 |
kSMPTETimeType25 = 1 |
kSMPTETimeType30Drop = 2 |
kSMPTETimeType30 = 3 |
kSMPTETimeType2997 = 4 |
kSMPTETimeType2997Drop = 5 |
SMPTE Time Stamps
These constants are used for the mFlags value
in SMPTETime.
kSMPTETimeValid = (1L << 0) |
kSMPTETimeRunning = (1L << 1) |
Audio Time Stamp
AudioTimeStamp
Encapsulates time stamp information in various formats.
typedef struct AudioTimeStamp {
Float64 mSampleTime;
UInt64 mHostTime;
Float64 mRateScalar;
UInt64 mWordClockTime;
SMPTETime mSMPTETime;
UInt32 mFlags;
UInt32 mReserved;
} AudioTimeStamp;
Availability
- Available in Mac OS X v10.0 and later.
Declared In
CoreAudioTypes.h
Time Stamp Flags
The mFlags value in AudioTimeStamp uses
these values, which signify which time formats are valid.
kAudioTimeStampSampleTimeValid = (1L << 0), |
kAudioTimeStampHostTimeValid = (1L << 1), |
kAudioTimeStampRateScalarValid = (1L << 2), |
kAudioTimeStampWordClockTimeValid = (1L << 3), |
kAudioTimeStampSMPTETimeValid = (1L << 4) |
Audio Channel Layouts
AudioChannelDescription
Contains information describing a single channel.
typedef struct AudioChannelDescription {
AudioChannelLabel mChannelLabel;
UInt32 mChannelFlags;
Float32 mCoordinates[3];
} AudioChannelDescription;
Discussion
This structure is used by AudioChannelLayout to
describe the position of a speaker. The mChannelFlags data
member contains a “Channel Labels” value, while mChannelFlags marks which
coordinate system is in use. The position of the speaker is kept
in mCoordinates, as per the “Channel Flags” and “Channel Coordinates.”
Availability
- Available in Mac OS X v10.2 and later.
Declared In
CoreAudioTypes.h
AudioChannelLayout
Specifies the channel layout in files and hardware.
typedef struct AudioChannelLayout {
AudioChannelLayoutTag mChannelLayoutTag;
UInt32 mChannelBitmap;
UInt32 mNumberChannelDescriptions;
AudioChannelDescription mChannelDescriptions[1];
} AudioChannelLayout;
Discussion
This structure is used to keep track of the channel arrangements. A “Channel Layout Tags” value, stored in mChannelLayoutTag, signifies which layout scheme is in use, or, if the scheme is not available there, mChannelBitmap may contain a bitmap describing the layout. The bitmap is formed using “Channel Bitmaps.”
Availability
- Available in Mac OS X v10.2 and later.
Declared In
CoreAudioTypes.h
Defined Data Types
Typedefs are provided to help describe channel layouts.
typedef UInt32 AudioChannelLabel; |
typedef UInt32 AudioChannelLayoutTag; |
Channel Labels
Specifies which channel is described by an AudioChannelDescription.
Unknown/unused:
kAudioChannelLabel_Unknown = 0xFFFFFFFF |
kAudioChannelLabel_Unused = 0 |
Standard channels:
kAudioChannelLabel_Left = 1 |
kAudioChannelLabel_Right= 2 |
kAudioChannelLabel_Center = 3 |
kAudioChannelLabel_LFEScreen = 4 |
kAudioChannelLabel_LeftSurround = 5 |
kAudioChannelLabel_RightSurround = 6 |
kAudioChannelLabel_LeftCenter = 7 |
kAudioChannelLabel_RightCenter = 8 |
kAudioChannelLabel_CenterSurround = 9 |
kAudioChannelLabel_LeftSurroundDirect = 10 |
kAudioChannelLabel_RightSurroundDirect = 11 |
kAudioChannelLabel_TopCenterSurround = 12 |
kAudioChannelLabel_VerticalHeightLeft = 13 |
kAudioChannelLabel_VerticalHeightCenter = 14 |
kAudioChannelLabel_VerticalHeightRight = 15 |
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 |
kAudioChannelLabel_RightTotal = 39 |
kAudioChannelLabel_HearingImpaired = 40 |
kAudioChannelLabel_Narration = 41 |
kAudioChannelLabel_Mono = 42 |
kAudioChannelLabel_DialogCentricMix = 43 |
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 channels:
kAudioChannelLabel_HeadphonesLeft = 301 |
kAudioChannelLabel_HeadphonesRight = 302 |
kAudioChannelLabel_ClickTrack = 304 |
kAudioChannelLabel_ForeignLanguage = 305 |
Channel Bitmaps
Used in the mChannelBitmap field
of an AudioChannelLayout to specify a custom
layout.
kAudioChannelBit_Left = (1L<<0) |
kAudioChannelBit_Right = (1L<<1) |
kAudioChannelBit_Center = (1L<<2) |
kAudioChannelBit_LFEScreen = (1L<<3) |
kAudioChannelBit_LeftSurround = (1L<<4) |
kAudioChannelBit_RightSurround = (1L<<5) |
kAudioChannelBit_LeftCenter = (1L<<6) |
kAudioChannelBit_RightCenter = (1L<<7) |
kAudioChannelBit_CenterSurround = (1L<<8) |
kAudioChannelBit_LeftSurroundDirect = (1L<<9) |
kAudioChannelBit_RightSurroundDirect = (1L<<10) |
kAudioChannelBit_TopCenterSurround = (1L<<11) |
kAudioChannelBit_VerticalHeightLeft = (1L<<12) |
kAudioChannelBit_VerticalHeightCenter = (1L<<13) |
kAudioChannelBit_VerticalHeightRight = (1L<<14) |
kAudioChannelBit_TopBackLeft = (1L<<15) |
kAudioChannelBit_TopBackCenter = (1L<<16) |
kAudioChannelBit_TopBackRight = (1L<<17) |
Channel Flags
Specifies which coordinate system is in use, and if the distances
are measured in meters; stored in mChannelFields in
an AudioChannelDescription instance.
kAudioChannelFlags_RectangularCoordinates = (1L<<0) |
kAudioChannelFlags_SphericalCoordinates = (1L<<1) |
kAudioChannelFlags_Meters = (1L<<2) |
Channel Coordinates
Specifies the meaning of indices of mCoordinates in AudioChannelDescription.
For rectangular coordinates:
kAudioChannelCoordinates_LeftRight = 0 |
kAudioChannelCoordinates_BackFront = 1 |
kAudioChannelCoordinates_DownUp = 2 |
For spherical coordinates:
kAudioChannelCoordinates_Azimuth = 0 |
kAudioChannelCoordinates_Elevation = 1 |
kAudioChannelCoordinates_Distance = 2 |
Channel Layout Tags
Specifies which channel layout is in use; stored in mChannelLayout in AudioChannelLayout.
Other/unknown:
kAudioChannelLayoutTag_UseChannelDescriptions = 0 |
kAudioChannelLayoutTag_UseChannelBitmap = 1 |
kAudioChannelLayoutTag_AllUnknown = 9 |
General layouts:
kAudioChannelLayoutTag_Mono = 100 |
kAudioChannelLayoutTag_Stereo = 101 |
kAudioChannelLayoutTag_StereoHeadphones = 2 |
kAudioChannelLayoutTag_MatrixStereo = 3 |
kAudioChannelLayoutTag_MidSide = 4 |
kAudioChannelLayoutTag_XY = 5 |
kAudioChannelLayoutTag_Binaural = 6 |
kAudioChannelLayoutTag_Quadraphonic = 7 |
kAudioChannelLayoutTag_Ambisonic_B_Format = 8 |
kAudioChannelLayoutTag_AudioUnit_5_0 = 107 |
MPEG defined layouts:
kAudioChannelLayoutTag_MPEG_1_0 = 100 |
kAudioChannelLayoutTag_MPEG_2_0 = 101 |
kAudioChannelLayoutTag_MPEG_3_0_A = 102 |
kAudioChannelLayoutTag_MPEG_3_0_B = 103 |
kAudioChannelLayoutTag_MPEG_4_0_A = 104 |
kAudioChannelLayoutTag_MPEG_4_0_B = 105 |
kAudioChannelLayoutTag_MPEG_5_0_A = 106 |
kAudioChannelLayoutTag_MPEG_5_0_B = 107 |
kAudioChannelLayoutTag_MPEG_5_0_C = 108 |
kAudioChannelLayoutTag_MPEG_5_0_D = 109 |
kAudioChannelLayoutTag_MPEG_5_1_A = 110 |
kAudioChannelLayoutTag_MPEG_5_1_B = 111 |
kAudioChannelLayoutTag_MPEG_5_1_C = 112 |
kAudioChannelLayoutTag_MPEG_5_1_D = 113 |
kAudioChannelLayoutTag_MPEG_6_1_A = 114 |
kAudioChannelLayoutTag_MPEG_7_1_A = 115 |
kAudioChannelLayoutTag_MPEG_7_1_B = 116 |
kAudioChannelLayoutTag_MPEG_7_1_C = 117 |
kAudioChannelLayoutTag_Emagic_Default_7_1 = 118 |
kAudioChannelLayoutTag_SMPTE_DTV = 119 |
ITU defined layouts:
kAudioChannelLayoutTag_ITU_1_0 = 100 |
kAudioChannelLayoutTag_ITU_2_0 = 101 |
kAudioChannelLayoutTag_ITU_2_1 = 120 |
kAudioChannelLayoutTag_ITU_2_2 = 121 |
kAudioChannelLayoutTag_ITU_3_0 = 102 |
kAudioChannelLayoutTag_ITU_3_1 = 104 |
kAudioChannelLayoutTag_ITU_3_2 = 106 |
kAudioChannelLayoutTag_ITU_3_2_1 = 110 |
kAudioChannelLayoutTag_ITU_3_4_1 = 117 |
DVD defined layouts:
kAudioChannelLayoutTag_DVD_0 = 100 |
kAudioChannelLayoutTag_DVD_1 = 101 |
kAudioChannelLayoutTag_DVD_2 = 120 |
kAudioChannelLayoutTag_DVD_3 = 121 |
kAudioChannelLayoutTag_DVD_4 = 122 |
kAudioChannelLayoutTag_DVD_5 = 123 |
kAudioChannelLayoutTag_DVD_6 = 124 |
kAudioChannelLayoutTag_DVD_7 = 102 |
kAudioChannelLayoutTag_DVD_8 = 104 |
kAudioChannelLayoutTag_DVD_9 = 106 |
kAudioChannelLayoutTag_DVD_10 = 125 |
kAudioChannelLayoutTag_DVD_11 = 126 |
kAudioChannelLayoutTag_DVD_12 = 110 |
kAudioChannelLayoutTag_DVD_13 = 104 |
kAudioChannelLayoutTag_DVD_14 = 106 |
kAudioChannelLayoutTag_DVD_15 = 125 |
kAudioChannelLayoutTag_DVD_16 = 126 |
kAudioChannelLayoutTag_DVD_17 = 110 |
kAudioChannelLayoutTag_DVD_18 = 127 |
kAudioChannelLayoutTag_DVD_19 = 107 |
kAudioChannelLayoutTag_DVD_20 = 111 |
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)