Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

< Previous PageNext Page > Hide TOC

Audio Toolbox Reference

This reference section describes the constants, data types and functions that comprise the Audio Toolbox framework available for Mac OS X.

In this section:

Audio Converter Reference
Audio Format Reference
Audio File Reference
AUGraph Reference
Music Player and Music Sequence Reference


Audio Converter Reference

Audio converters are designed to meet a developer’s encoding and decoding needs. It allows for conversions between most conceivable combinations of input and output formats, assuming proper codecs are available on the system.

Audio Converter Types

Defined Data Types

Typedefs are used to simplify the declaration of converters and the use of properties in the context of an audio converter.

Data Structures

AudioConverterPrimeInfo

Stores information regarding the number of frames used in priming input for the current codec.

typedef struct AudioConverterPrimeInfo {
UInt32 leadingFrames;
UInt32 trailingFrames;
} AudioConverterPrimeInfo;

Discussion

An instance of this structure is input via the kAudioConverterPrimeInfo property. The instance works in conjunction with the kAudioConverterPrimeMethod property, which specifies the priming method used by the codec. When a priming method is in use, the members of this structure are used to specify the number of leading and trailing frames (when using kConverterPrimeMethod_Pre), or just the number of trailing frames (when using kConverterPrimeMethod_Normal), for all input packets.

Availability
Declared In
AudioConverter.h

Audio Converter Constants

Constants are provided for the developer’s convenience. They provide a consistent set of values for various aspects of a converter’s operations, and may be appended by the developer at any time.

Converter Quality Settings

Used by kAudioConverterSampleRateConverterQuality to set the relative quality of the conversion.

kAudioConverterQuality_Max = 0x7F
kAudioConverterQuality_High = 0x60
kAudioConverterQuality_Medium = 0x40
kAudioConverterQuality_Low = 0x20
kAudioConverterQuality_Min = 0

Note: The relative quality of a conversion is an arbitrary aspect of the codec used, and may or may not alter the quality of the resulting conversion.

Priming Method Selectors

Specifies the priming method currently in use, as referenced in the kAudioConverterPrimeMethod property.

kConverterPrimeMethod_Pre = 0

When kAudioConverterPrimeMethod is set to this value, the converter will expect that the packet be primed with both leading and trailing frames.

kConverterPrimeMethod_Normal = 1

Set kAudioConverterPrimeMethod to this when the trailing frames are needed for the conversion; leading frames are assumed to silent.

kConverterPrimeMethod_None = 2

Used when the leading and trailing frames are assumed to be silent and priming is not needed.

Audio Converter Properties

The properties are used to query a converter for its settings, and sometimes, to modify those properties.

kAudioConverterPropertyMinimumInputBufferSize = 'mibs'

Returns a UInt32 containing the size of the smallest input buffer size, in bytes, that can be supplied into the AudioConverterConvertBuffer() function or the *AudioConverterInputProc callback.

kAudioConverterPropertyMinimumOutputBufferSize = 'mobs'

Returns a UInt32 containing the size of the smallest buffer that will bereturned as a result of AudioConverterConvertBuffer() or AudioConverterFillBuffer().

kAudioConverterPropertyMaximumInputBufferSize = 'xibs'

Returns a UInt32 containing the largest buffer size that will requested by *AudioConverterInputProc; returns 0xFFFFFFFF if the value depends on the size of the input.

kAudioConverterPropertyMaximumInputPacketSize = 'xips'

Returns a UInt32 containing the size, in bytes, of the largest packet of data that may be input.

kAudioConverterPropertyMaximumOutputPacketSize = 'xops'

Returns a UInt32 containing the size, in bytes, of the largest packet of data that will be output.

kAudioConverterPropertyCalculateInputBufferSize = 'cibs'

On input, takes a UInt32 with the desired output size, in bytes; returns the number of bytes needed as input to generate the requested output.

kAudioConverterPropertyCalculateOutputBufferSize = 'cobs'

On input, takes a UInt32 with the desired input size, in bytes; returns the number of bytes returned as output for the requested input.

kAudioConverterPropertyInputCodecParameters = 'icdp'

Takes in a buffer of untyped data for private use relative and specific to the format.

kAudioConverterPropertyOutputCodecParameters = 'ocdp'

Takes in a buffer of untyped data for private use relative and specific to the format.

kAudioConverterSampleRateConverterAlgorithm = 'srci'

Deprecated. Use kAudioConverterSampleRateConverterQuality instead.

kAudioConverterSampleRateConverterQuality = 'srcq'

Specifies the quality of the sample rate conversion, using the “Converter Quality Settings.”

kAudioConverterPrimeMethod = 'prmm'

Specifies the priming method, using the “Priming Method Selectors.”

kAudioConverterPrimeInfo = 'prim'

Returns in a pointer to an AudioConverterPrimeInfo instance.

kAudioConverterChannelMap = 'chmp'

Takes an array of SInt32 values where the index represents an output channel and the value stored at the index in the array is the connecting input channel; the size of the array is the number of output channels.

kAudioConverterDecompressionMagicCookie = 'dmgc'

Takes a void pointer towards the magic cookie that may be required to decompress the data.

kAudioConverterCompressionMagicCookie = 'cmgc'

Returns a void pointer towards the magic cookie used to compress the output data; may be passed back via kAudioConverterDecompressionMagicCookie for decompressing the data.

Audio Converter Functions

AudioConverterNew

Creates a new audio converter.

extern OSStatus AudioConverterNew(
const AudioStreamBasicDescription* inSourceFormat,
const AudioStreamBasicDescription* inDestinationFormat, AudioConverterRef* outAudioConverter
);

Discussion

This function takes in two AudioStreamBasicDescription instances, one for the source, and one for the destination, sets up all of the internal links needed for the conversion, and returns a pointer for the new converter. Note that if the setup fails, an error is returned which specifies the error that was encountered.

Availability
Declared In
AudioConverter.h

AudioConverterDispose

Destroys an audio converter.

extern OSStatus AudioConverterDispose(AudioConverterRef inAudioConverter);

Discussion

This function deallocates the memory used by inAudioConverter.

Availability
Declared In
AudioConverter.h

AudioConverterReset

Resets the audio converter to its post-initialization state.

extern OSStatus AudioConverterReset(AudioConverterRef inAudioConverter);

Availability
Declared In
AudioConverter.h

AudioConverterGetPropertyInfo

Retrieves the size and writable state of the data belonging to the queried property.

extern OSStatus AudioConverterGetPropertyInfo(
AudioConverterRef inAudioConverter,
AudioConverterPropertyID inPropertyID,
UInt32* outSize,
Boolean* outWritable
);

Discussion

The outSize value returned reflects the size, in bytes, of the data returned by calling AudioConverterGetProperty() with the respective property.

Availability
Declared In
AudioConverter.h

AudioConverterGetProperty

Returns the requested property data.

extern OSStatus AudioConverterGetProperty(
AudioConverterRef inAudioConverter,
AudioConverterPropertyID inPropertyID,
UInt32* ioPropertyDataSize,
void* outPropertyData
);

Discussion

The ioPropertyDataSize parameter should be the value obtained from calling AudioConverterGetPropertyInfo(); the output value of ioPropertyDataSize will be the actual data size of the returned data, for reference.

Availability
Declared In
AudioConverter.h

AudioConverterSetProperty

Sets the property data to inPropertyData.

extern OSStatus AudioConverterSetProperty(
AudioConverterRef inAudioConverter,
AudioConverterPropertyID inPropertyID,
UInt32 inPropertyDataSize,
const void* inPropertyData
);

Discussion

The inPropertyDataSize should be the size of data being input, and inPropertyData should point to the data to be set for inPropertyID.

Availability
Declared In
AudioConverter.h

AudioConverterInputDataProc

Should provide data for AudioConverterFillBuffer().

typedef OSStatus (*AudioConverterInputDataProc) (
AudioConverterRef inAudioConverter,
UInt32* ioDataSize,
void** outData,
void* inUserData
);

Discussion

Deprecated. On input, ioDataSize will be the amount of data the converter needs to fill its buffer; on output, this value should reflect the amount of the data provided (if there is no more input data available, 0 should be returned).

AudioConverterFillBuffer

Fills the provided buffer with converted data.

extern OSStatus AudioConverterFillBuffer(
AudioConverterRef inAudioConverter,
AudioConverterInputDataProc inInputDataProc,
void* inInputDataProcUserData,
UInt32* ioOutputDataSize,
void* outOutputData
);

Discussion

Deprecated. Uses the provided inInputDataProc callback to acquire data, converts it, and places the converted data in. outOutputData. Deprecated since it can only work with a single buffer. Use AudioConverterFillComplexBuffer() instead.

Availability
Declared In
AudioConverter.h

AudioConverterComplexInputDataProc

Should provide AudioConverterFillComplexBuffer() with data for conversion.

typedef OSStatus (*AudioConverterComplexInputDataProc) (
AudioConverterRef inAudioConverter,
UInt32* ioNumberDataPackets,
AudioBufferList* ioData,
AudioStreamPacketDescription** outDataPacketDescription,
void* inUserData
);

Discussion

AudioConverterFillComplexBuffer() will use this callback to acquire data to convert. The returned data will be an AudioBufferList, meaning that the data should be in separate indices, one for each channel. Use inUserData for any data the callback may need passed to it. The caller will pass the number of packets requested in ioNumberDataPackets, and upon completion, the callback should return the number of packets actually provided, or 0 if there is no data left to provide. The resulting packet format is specified in outDataPacketDescription.

AudioConverterFillComplexBuffer

Fills the AudioBufferList with converted data.

extern OSStatus AudioConverterFillComplexBuffer(
AudioConverterRef inAudioConverter,
AudioConverterComplexInputDataProc inInputDataProc,
void* inInputDataProcUserData,
UInt32* ioOutputDataPacketSize,
AudioBufferList* outOutputData,
AudioStreamPacketDescription* outPacketDescription
);

Discussion

Using the callback provided in inInputDataProc, this function will convert input data using inAudioConverter and will place the resulting converted data in outOutputData. Any relevant data for the callback should be passed in via inInputDataProcUserData, while outPacketDescription will contain the format of the returned data. On input, ioOutDataPacketSize should contain the number of packets requested, and as output, will contain the number of packets returned.

Availability
Declared In
AudioConverter.h

Audio Converter Result Codes

These values are returned when errors occur.

kAudioConverterErr_FormatNotSupported = 'fmt?’
kAudioConverterErr_OperationNotSupported = 0x6F703F3F
kAudioConverterErr_PropertyNotSupported = 'prop'
kAudioConverterErr_InvalidInputSize = 'insz'
kAudioConverterErr_InvalidOutputSize = 'otsz'
kAudioConverterErr_UnspecifiedError = 'what'
kAudioConverterErr_BadPropertySizeError = '!siz'
kAudioConverterErr_RequiresPacketDescriptionsError = '!pkd’

Audio Format Reference

The audio format system is provided to allow the developer to get more information about certain aspects of AudioStreamBasicDescription and AudioChannelLayout instances, and other important pieces of information.

Audio Format Types

Defined Data Types

The AudioFormatPropertyID typedef is used to hold the property ID being queried using the audio format functions.

Data Structures

AudioPanningInfo

Stores information about the position of sound sources.

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

Discussion

The mPanningMode value is based on the panning mode constants. The value of mCoordinateFlags will be based on the Coordinate Flag constants. The precise coordinates of the source is located in mCoordinates, and the mOutputChannelMap points to an instance of an AudioChannelLayout (specified in CoreAudioTypes.h), which tracks channel layouts in hardware and in files.

Availability
Declared In
AudioFormat.h

Audio Format Constants

Constants are provided for the developer’s convenience. They provide a consistent set of values for various aspects of a converter’s operations.

Panning Modes

These constants define various panning algorithms that can be specified in an AudioPanningInfo instance.

kPanningMode_SoundField = 3

An Ambisonic format.

kPanningMode_VectorBasedPanning = 4

A format for panning between two speakers.

Coordinate Flags

Used by the mCoordinateFlags value in the AudioPanningInfo structure; found in CoreAudioTypes.h.

kAudioChannelFlags_RectangularCoordinates = (1L<<0)

Use if cartesian coordinates are used for speaker positioning; either this or spherical coordinates must be chosen.

kAudioChannelFlags_SphericalCoordinates = (1L<<1)

Use if spherical coordinates are used for speaker positioning; either this or cartesian coordinates must be chosen.

kAudioChannelFlags_Meters = (1L<<2)

Use when units are in meters; if not set, then the units are relative to the coordinate system chosen.

Audio Format Properties

The audio format tool uses the property system to get various pieces of information about structures used in Core Audio.

AudioStreamBasicDescription Properties

When the specifier parameter for AudioFormatGetPropertyInfo() and AudioFormatGetProperty() is an AudioStreamBasicDescription instance, these properties may be queried.

kAudioFormatProperty_FormatInfo = 'fmti'

Returns an AudioStreamBasicDescription whose values contain information about the specifier’s format.

kAudioFormatProperty_FormatIsVBR = 'fvbr'

Returns a UInt32 where a non-zero value means that the format has a variable bit rate (VBR).

kAudioFormatProperty_FormatIsExternallyFramed = 'fexf'

Returns a UInt32, where a non-zero value indicates that the format is externally framed.

kAudioFormatProperty_FormatName = 'fnam'

Returns a CFStringRef containing the name of the specified format.

kAudioFormatProperty_AvailableEncodeChannelLayouts = 'aecl'

Takes in an AudioStreamBasicDescription and returns an AudioChannelLayoutTag array containing Audio Channel Layout constants.

AudioChannelLayout Properties
kAudioFormatProperty_ChannelLayoutForTag = 'cmpl

Takes an “Channel Layout Tags” value (as specified in CoreAudioTypes.h) as the specifier and returns an AudioChannelLayout with all of its members filled with their respective versions of the input data.

kAudioFormatProperty_TagForChannelLayout = 'cmpt'

Takes an AudioChannelLayout as the specifier and returns an AudioChannelLayoutTag with all of its members filled with their respective versions of the input data.

kAudioFormatProperty_ChannelLayoutForBitmap = 'cmpb'

Takes in a UInt32 that contains a layout bitmap and returns an AudioChannelLayout with all of its members filled with their respective versions of the input data.

kAudioFormatProperty_BitmapForLayoutTag = 'bmtg'

Takes in a “Channel Layout Tags” value and returns a UInt32 with the bitmap of the channel layout.

kAudioFormatProperty_ChannelLayoutName = 'lonm'

Takes in an AudioChannelLayout and returns a CFStringRef with the name of the channel.

kAudioFormatProperty_ChannelName = 'cnam'

Takes in an AudioChannelDescription with a populated mChannelLabel value, and returns a CFStringRef with the name of the channel.

kAudioFormatProperty_MatrixMixMap = 'mmap'

Takes in an array of two AudioChannelLayout pointers, the first to the input and the second to the output, and returns a two dimensional Float32 array, with the input being the rows and the output being the columns, where the value at a coordinate is the gain that needs to be applied to the input to achieve the output at that channel.

kAudioFormatProperty_NumberOfChannelsForLayout = 'nchm'

Takes in an AudioChannelLayout as the specifier and returns a UInt32 with the number of channels represented in the layout.

kAudioFormatProperty_PanningMatrix = 'panm'

Takes in an AudioPanningInfo instance and returns a Float32 array where each channel receives a volume level for each channel in the AudioPanningInfo’s AudioChannelLayout array.

Other Properties

These are other properties that involve discovering encoding and decoding formats and available sample and bit rates.

kAudioFormatProperty_EncodeFormatIDs = 'acif'

Does not take a specifier (set to NULL), and returns a UInt32 array containing “Format IDs” (specified in CoreAudioTypes.h) for valid input formats into a converter.

kAudioFormatProperty_DecodeFormatIDs = 'acof'

Does not take a specifier (set to NULL), and returns a UInt32 array containing Format ID constants for valid output formats into a converter.

kAudioFormatProperty_AvailableEncodeSampleRates = 'aesr'

Takes in a Format ID constant and returns an AudioValueRange with all of the available sample rates.

kAudioFormatProperty_AvailableEncodeBitRates = 'aebr'

Takes in a Format ID constant and returns an AudioValueRange with all of the available bit rates.

Audio Format Functions

These functions comprise the Audio Format property management system. These functions work by providing property ID, which notifies them as to which action should be performed, and a specifier, which is the data on which the operation is to be performed.

AudioFormatGetPropertyInfo

Retrieves the size of the data to be returned by the property.

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

Availability
Declared In
AudioFormat.h

AudioFormatGetProperty

Retrieves the property information for the given property ID and selected specifier.

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

Availability
Declared In
AudioFormat.h

Audio Format Result Codes

These values are returned when errors occur.

kAudioFormatUnspecifiedError = 'what'
kAudioFormatUnsupportedPropertyError = 'prop'
kAudioFormatBadPropertySizeError = '!siz'
kAudioFormatBadSpecifierSizeError = '!spc'
kAudioFormatUnsupportedDataFormatError = 'fmt?'
kAudioFormatUnknownFormatError = '!fmt'

Audio File Reference

The Audio File API allows for opening and saving audio files in various formats, for later use.

Audio File Types

Defined Data Types

Typedefs are used to simplify the declaration of converters and the use of properties in the context of an audio file.

Data Structures

AudioFileTypeAndFormatID

Used by the kAudioGlobalInfo_AvailableStreamDescriptionForFormat property to query for AudioStreamBasicDescriptions based on format and file type.

typedef struct AudioFileTypeAndFormatID{
UInt32 mFileType;
UInt32 mFormatID;
} AudioFileTypeAndFormat;

Discussion

The value of mFileType is a “File Types” value, while mFormatID is from the “Format IDs” in CoreAudioTypes.h.

Constants

Constants are provided for the developer’s convenience. They provide a consistent set of values for various aspects of an audio file.

File Types

These constants are used to specify file types when using functions and structures related to audio files.

kAudioFileAIFFType = 'AIFF'
kAudioFileAIFCType = 'AIFC'
kAudioFileWAVEType = 'WAVE'
kAudioFileSoundDesigner2Type = 'Sd2f'
kAudioFileNextType = 'NeXT'
kAudioFileMP3Type = 'MPG3'
kAudioFileAC3Type = 'ac-3'
kAudioFileAAC_ADTSType = 'adts'

Audio File Properties

The Audio File API uses the property system to get and set information about files and global settings.

Audio File Properties

These properties are to be used when getting and setting information about an particular audio file.

kAudioFilePropertyFileFormat = 'ffmt'

Passes a UInt32 that identifies the file’s format, based on the “Format IDs” found in CoreAudioTypes.h.

kAudioFilePropertyDataFormat = 'dfmt'

Passes an AudioStreamBasicDescription that describes the file’s format.

kAudioFilePropertyIsOptimized = 'optm'

Returns a UInt32 with either a value of 0, meaning that the file is not optimized, and therefore, not ready to be written to, or a value of 1, meaning that the file is currently optimized.

kAudioFilePropertyMagicCookieData = 'mgic'

Passes a void pointer towards memory set up for use as a magic cookie.

kAudioFilePropertyAudioDataByteCount = 'bcnt'

Passes a UInt64 that contains the size of the audio data in the file, in bytes.

kAudioFilePropertyAudioDataPacketCount = 'pcnt'

Passes a UInt64 that contains the size of the audio data in the file, in packets.

kAudioFilePropertyMaximumPacketSize = 'psze'

Passes a UInt32 that contains the maximum packet size in the file.

kAudioFilePropertyDataOffset = 'doff'

Passes an SInt64 that contains offset of where the audio data begins inside the file.

kAudioFilePropertyChannelLayout = 'cmap'

Passes an AudioChannelLayout, specified in CoreAudioTypes.h, used in the file.

kAudioFilePropertyDeferSizeUpdates = 'dszu'

Passes a UInt32 where a value of 1 means that the file size information in the file header is updated only when the file is read, optimized, or closed; a value of 0 denotes that the header is updated with every write.

kAudioFilePropertyDataFormatName = 'fnme'

Deprecated in favor of the kAudioFormatProperty_formatName property, available from Audio Format “Audio Format Properties.”

Audio File Global Info Properties

The Global Info Properties are used to retrieve general information about the environment that is being used. Many of these properties require a specifier for use, meaning that, in addition to passing a property ID, a piece of information being queried upon is passed in as a specifier.

kAudioFileGlobalInfo_ReadableTypes = 'afrf'

Takes NULL as its specifier, and returns a UInt32 array containing the File Type constants which are readable.

kAudioFileGlobalInfo_WritableTypes = 'afwf'

Takes NULL as its specifier, and returns a UInt32 array containing the File Type constants which are writable.

kAudioFileGlobalInfo_FileTypeName = 'ftnm'

Takes a UInt32 containing a File Type constant as its specifier and returns a CFString containing the name of the file type.

kAudioFileGlobalInfo_ExtensionsForType = 'fext'

Takes a UInt32 containing a File Type constant as its specifier and returns a CFArray of CFString values containing the file extensions recognized for this file type.

kAudioFileGlobalInfo_AllExtensions = 'alxt'

Takes NULL as its specifier and returns a CFArray of CFString values containing all of the recognizable file extensions.

kAudioFileGlobalInfo_AvailableFormatIDs = 'fmid'

Takes a UInt32 containing a File Type constant as its specifier and returns a UInt32 array containing format ID constants for formats readable by audio file.

kAudioFileGlobalInfo_AvailableStreamDescriptionsForFormat = 'sdid'

Takes an AudioFileTypeAndFormatID instance as its specifier and returns an AudioStreamBasicDescription array whose elements correspond with the elements in the specifier.

Audio File Functions

These functions are provided to access the functionality of the Audio File API.

Data Handling

AudioFileCreate

Creates a new file using the descriptions provided.

extern OSStatus AudioFileCreate(
const FSRef *inParentRef,
CFStringRef inFileName,
UInt32 inFileType,
const AudioStreamBasicDescription *inFormat,
UInt32 inFlags,
FSRef *outNewFileRef,
AudioFileID *outAudioFile
);

Discussion

The directory that the file to be place into is provided with inParentRef, the name of the file is contained within inFileName, a File Type constant must be provided with inFileType, the format must be specified using inFormat, inFlag contains flags for opening and creating the file (currently undefined; should be set to 0), and outNewFileRef is provided for file system use, while outAudioFile is for use with other audio file functions.

Availability
Declared In
AudioFile.h

AudioFileInitialize

Wipes clean a existing file to prepare it for writing.

extern OSStatus AudioFileInitialize(
const FSRef *inFileRef,
UInt32 inFileType,
const AudioStreamBasicDescription *inFormat,
UInt32 inFlags,
AudioFileID *outAudioFile
);

Discussion

The inFileRef is the file to be initialized, with the inFileType being a File Type constant value, inFormat being an AudioStreamBasicDescription specifying the format for the file, inFlags being relevant creation and opening flags (currently undefined; should be set to 0), and outAudioFile being an AudioFileID for use with other audio file functions.

Availability
Declared In
AudioFile.h

AudioFileOpen

Opens a file while preserving its contents.

extern OSStatus AudioFileOpen (
const FSRef *inFileRef,
SInt8 inPermissions,
UInt32 inFlags,
AudioFileID *outAudioFile
);

Discussion

The inFileRef should be a reference to an existing file, inPermissions being the permissions for the file, as used by FSOpenFork(), and inFlags, currently undefined, should be set to 0; outAudioFile is a file instance that will be returned for use in other audio file functions.

Availability
Declared In
AudioFile.h

AudioFile_ReadProc

Should read the contents of a file.

typedef OSStatus (*AudioFile_ReadProc)(
void * inRefCon,
SInt64 inPosition,
ByteCount requestCount,
void *buffer,
ByteCount* actualCount
);

Discussion

This callback needs to be provided by the developer for the purpose of reading the audio data for use with AudioFormatInitializeWithCallbacks() and AudioFormatOpenWithCallbacks(). Constants for use by the callback are passed in via inRefCon, the position to be read from will be passed in via inPosition, the number of bytes requested is passed in via requestCount, the processed data is passed in via buffer, and actualCount returns the number of bytes returned.

AudioFile_WriteProc

Should write the given buffer to the file.

typedef OSStatus (*AudioFile_WriteProc)(
void * inRefCon,
SInt64 inPosition,
ByteCount requestCount,
const void *buffer,
ByteCount* actualCount
);

Discussion

This callback needs to be provided by the developer for the purpose of writing to a file. Constants for use by the callback are passed in via inRefCon, the position to be read from will be passed in via inPosition, the number of bytes requested is passed in via requestCount, the data processed to is passed in via buffer, and actualCount returns the number of bytes written.

AudioFile_GetSizeProc

Should provide the size of the file to the caller.

typedef SInt64 (*AudioFile_GetSizeProc)(void * inRefCon);

Discussion

This callback should return an SInt32 with the audio stream data size to the caller. If any constants need to be passed to the callback, their values should be pointed to by inRefCon.

AudioFile_SetSizeProc

Should set the file size to the passed value.

typedef OSStatus (*AudioFile_SetSizeProc)(
void * inRefCon,
SInt64 inSize
);

Discussion

This callback should set the size of the file to inSize, while inRefCon is provided to pass any needed arguments to the callback.

AudioFileInitializeWithCallbacks

Initializes an audio file using the provided callbacks.

extern OSStatus AudioFileInitializeWithCallbacks(
void * inRefCon,
AudioFile_ReadProc inReadFunc,
AudioFile_WriteProc inWriteFunc,
AudioFile_GetSizeProc inGetSizeFunc,
AudioFile_SetSizeProc inSetSizeFunc,
UInt32 inFileType,
const AudioStreamBasicDescription *inFormat,
UInt32 inFlags,
AudioFileID *outAudioFile
);

Discussion

This function will wipe the data target clean and set the various attributes using inFileType, inFormat, and inFlags. The callbacks need to be provided by the developer, according to the callback specifications elsewhere in this reference. Upon completion, outAudioFile will contain a reference to a file instance, for use with other audio file functions.

Availability
Declared In
AudioFile.h

AudioFileOpenFileWithCallbacks

Opens the file an prepares it for use.

extern OSStatus AudioFileOpenWithCallbacks(
void * inRefCon,
AudioFile_ReadProc inReadFunc,
AudioFile_WriteProc inWriteFunc,
AudioFile_GetSizeProc inGetSizeFunc,
AudioFile_SetSizeProc inSetSizeFunc,
UInt32 inFlags,
AudioFileID *outAudioFile
);

Discussion

Using this function will prepare the target data, while the callbacks specified here will be used when reading, writing, and modifying the data. This function is provided to allow for the use of Audio File’s APIs with sources other than files.

AudioFileClose

Closes the file.

extern OSStatus AudioFileClose(AudioFileID inAudioFile);

Availability
Declared In
AudioFile.h

AudioFileOptimize

Optimizes the file.

extern OSStatus AudioFileOptimize(AudioFileID inAudioFile);

Discussion

Optimizing a file will prepare it for any data which may be appended to the end of it. This is a costly operation and should not be performed during a process-intensive routine. The kAudioFilepropertyIsOptimized flag is available to determine whether or not the file is optimized.

Availability
Declared In
AudioFile.h

AudioFileReadBytes

Reads in a certain number of bytes from the file.

extern OSStatus AudioFileReadBytes(
AudioFileID inAudioFile,
Boolean inUseCache,
SInt64 inStartingByte,
UInt32 *ioNumBytes,
void *outBuffer
);

Discussion

Here, inAudioFile is the file being read from, inStartingByte is the point from which to read from, ioNumBytes being the amount to read, and outBuffer is where the read data is stored. To cache the read, set inUseCache to true.

Availability
Declared In
AudioFile.h

AudioFileWriteBytes

Write the contents of the buffer to the file.

extern OSStatus AudioFileWriteBytes(
AudioFileID inAudioFile,
Boolean inUseCache,
SInt64 inStartingByte,
UInt32 *ioNumBytes,
void *inBuffer
);

Discussion

Specify the file to be written to with inAudioFile, where to write within the file by specifying inStartingByte, how much is to be written using ioNumBytes (and verifying how much was written at output, as well), and the data to be written should be pointed to by inBuffer. To cache the written data, set inUseCache to true.

Availability
Declared In
AudioFile.h

AudioFileReadPackets

Reads in a certain number of packets from the input file.

extern OSStatus AudioFileReadPackets(
AudioFileID inAudioFile,
Boolean inUseCache,
UInt32 *outNumBytes,
AudioStreamPacketDescription *outPacketDescriptions,
SInt64 inStartingPacket,
UInt32 *ioNumPackets,
void *outBuffer
);

Discussion

This function reads in the contents of the file by packet, starting at inStartingPoint. The packets that have been read are described in outPacketDescriptions, while the number of packets is specified in ioNumPackets (with the actual number of packets read being the return value), and the size, in bytes, of the read in packets returned in outNumBytes. If the read should be cached, set inUseCache to true.

Availability
Declared In
AudioFile.h

AudioFileWritePackets

Writes the buffer to the file, by packets.

extern OSStatus AudioFileWritePackets(
AudioFileID inAudioFile,
Boolean inUseCache,
UInt32 inNumBytes,
AudioStreamPacketDescription *inPacketDescriptions,
SInt64 inStartingPacket,
UInt32 *ioNumPackets,
void *inBuffer
);

Discussion

When writing to inAudioFile, specify the starting index as inStartingPacket, the format of the packet as defined in inPacketDescrptions, the size of the write as inNumBytes, and the number of packets to be written in ioNumPackets. If the write should be cached, set inUseCache to true.

Availability
Declared In
AudioFile.h
Property Access

AudioFileGetPropertyInfo

Returns the size of the data that will be returned for the property.

extern OSStatus AudioFileGetPropertyInfo(
AudioFileID inAudioFile,
AudioFilePropertyID inPropertyID,
UInt32 *outDataSize,
UInt32 *isWritable
);

Discussion

The file being queried should be passed in as inAudioFile, while the property being queried is passed in as inPropertyID. The size of the resulting data is returned in outDataSize, and isWritable will reflect if the data is modifiable.

Availability
Declared In
AudioFile.h

AudioFileGetProperty

Returns the data for the specified property.

extern OSStatus AudioFileGetProperty(
AudioFileID inAudioFile,
AudioFilePropertyID inPropertyID,
UInt32 *ioDataSize,
void *outPropertyData
);

Discussion

The file and property being queried should be specified in inAudioFile and inPropertyID, respectively, with the size retrieved with AudioFileGetPropertyInfo() passed into ioDataSize, and the resulting data being placed in outPropertyData.

Availability
Declared In
AudioFile.h

AudioFileSetProperty

Sets the data for the respective property.

extern OSStatus AudioFileSetProperty(
AudioFileID inAudioFile,
AudioFilePropertyID inPropertyID,
UInt32 inDataSize,
const void *inPropertyData
);

Discussion

The file and property being set should be specified in inAudioFile and inPropertyID, respectively, with the size of the data being written passed into ioDataSize, and the data being written coming from inPropertyData.

Availability
Declared In
AudioFile.h
Global Info Access

AudioFileGetGlobalInfoSize

Calculates the size of the data that will be returned for the property.

extern OSStatus AudioFileGetGlobalInfoSize(
AudioFilePropertyID inPropertyID,
UInt32 inSpecifierSize,
void *inSpecifier,
UInt32 *outDataSize
);

Discussion

Gets the size of the inPropertyID for the inSpecifier and places it in outDataSize.

Availability
Declared In
AudioFile.h

AudioFileGetGlobalInfo

Retrieves the data for the queried property and specifier.

extern OSStatus AudioFileGetGlobalInfo(
AudioFilePropertyID inPropertyID,
UInt32 inSpecifierSize,
void *inSpecifier,
UInt32 *ioDataSize,
void *outPropertyData
);

Discussion

This function takes inPropertyID and returns outPropertyData based on inSpecifier.

Availability
Declared In
AudioFile.h

Audio File Result Codes

These values are returned when errors occur.

kAudioFileUnspecifiedError = 'wht?'
kAudioFileUnsupportedFileTypeError = 'typ?'
kAudioFileUnsupportedDataFormatError = 'fmt?'
kAudioFileUnsupportedPropertyError = 'pty?'
kAudioFileBadPropertySizeError = '!siz'
kAudioFilePermissionsError = 'prm?'
kAudioFileNotOptimizedError = 'optm'
kAudioFileFormatNameUnavailableError = 'nme?'
kAudioFileInvalidChunkError = 'chk?'
kAudioFileDoesNotAllow64BitDataSizeError = 'off?'
kAudioFileInvalidPacketOffsetError = 'pck?'
kAudioFileInvalidFileError = 'dta?'
kAudioFileOperationNotSupportedError = 0x6F703F3F

AUGraph Reference

The AUGraph API allows for creating graphs of Audio Units for processing audio data.

AUGraph Types

Defined Data Types

Typedefs are used to simplify the declaration of converters and the use of properties in the context of a graph.

Data Structures

AudioUnitNodeConnection

Used to symbolize the connection between two nodes.

typedef struct AudioUnitNodeConnection{
AUNode sourceNode;
UInt32 sourceOutputNumber;
AUNode destNode;
UInt32 destInputNumber;
} AudioUnitNodeConnection;

Availability
Declared In
AUGraph.h

AUGraph Functions

These functions are provided to access the functionality of the AUGraph API.

NewAUGraph

Creates a new AUGraph instance.

extern OSStatus NewAUGraph(AUGraph *outGraph);

Availability
Declared In
AUGraph.h

DisposeAUGraph

Destroys an AUGraph instance.

extern OSStatus DisposeAUGraph(AUGraph inGraph);

Availability
Declared In
AUGraph.h

AUGraphNewNode

Creates a new node inside of the specified graph.

extern OSStatus AUGraphNewNode(
AUGraph inGraph,
const ComponentDescription *inDescription,
UInt32 inClassDataSize,
const void *inClassData,
AUNode *outNode
);

Discussion

The graph to which the new node is to be added is set in inGraph, while the node to be added may be specified using either a ComponentDescription, obtained from the Component Manager. The value of inClassData is a CFPropertyList containing the serialized data of a saved state. The function returns outNode for future reference towards the newly-created node.

Availability
Declared In
AUGraph.h

AUGraphNewNodeSubGraph

Adds a new subgraph within the graph.

extern OSStatus AUGraphNewNodeSubGraph(
AUGraph inGraph,
AUNode *outNode
);

Discussion

The subgraph node pointed to by outNode may be populated as if it were a graph in itself. The entire graph becomes active when the subgraph node is connected to the rest of the graph, and it is deactivated when it is disconnected.

Availability
Declared In
AUGraph.h

AUGraphRemoveNode

Removes the specified node from the graph.

extern OSStatus AUGraphRemoveNode(
AUGraph inGraph,
AUNode inNode
);

Availability
Declared In
AUGraph.h

AUGraphGetNodeCount

Returns the number of nodes in the current graph.

extern OSStatus AUGraphGetNodeCount(
AUGraph inGraph,
UInt32 *outNumberOfNodes
);

Availability
Declared In
AUGraph.h

AUGraphGetIndNode

Returns a pointer to the node at the specified index.

extern OSStatus AUGraphGetIndNode(
AUGraph inGraph,
UInt32 inIndex,
AUNode *outNode
);

Discussion

The index for the node is arbitrarily assigned when the node is added to the graph.

Availability
Declared In
AUGraph.h

AUGraphGetNodeInfo

Returns information about a node.

extern OSStatus AUGraphGetNodeInfo(
AUGraph inGraph,
AUNode inNode,
ComponentDescription *outDescription,
UInt32 *outClassDataSize,
void **outClassData,
AudioUnit *outAudioUnit
);

Discussion

This function retrieves various pieces of information about a graph’s nodes, which may be saved and used to rebuild the graph later using AUGraphNewNode(). The node and graph containing the node in question are passed as inGraph and inNode, respectively. Upon output, outDescription points to a ComponentDescription, provided by the Component Manager. Also, outClassData points towards a CFPropertyRef, which may be saved and used to rebuild the graph later on. The node’s Audio Unit type is pointed to by outAudioUnit. The outClassDataSize parameter is currently not used, and will return 0.

Availability
Declared In
AUGraph.h

AUGraphGetNodeInfoSubGraph

Returns a pointer towards a subgraph.

extern OSStatus AUGraphGetNodeInfoSubGraph(
const AUGraph inGraph,
const AUNode inNode,
AUGraph *outSubGraph
);

Availability
Declared In
AUGraph.h

AUGraphIsNodeSubGraph

Indicates if a node is a subgraph.

extern OSStatus AUGraphIsNodeSubGraph(
const AUGraph inGraph,
const AUNode inNode,
Boolean* outFlag
);

Availability
Declared In
AUGraph.h

AUGraphConnectNodeInput

Connects two graph nodes together and specifies the way inputs are ordered.

extern OSStatus AUGraphConnectNodeInput(
AUGraph inGraph,
AUNode inSourceNode,
UInt32 inSourceOutputNumber,
AUNode inDestNode,
UInt32 inDestInputNumber
);

Discussion

When connecting nodes together, the developer must specify how the output of one node maps to the input of another. To prevent fan out, all output-input connections are one-to-one, where each node may have multiple inputs and outputs (indexed starting with 0).

Availability
Declared In
AUGraph.h

AUGraphDisconnectNodeInput

Disconnects the input from the graph.

extern OSStatus AUGraphDisconnectNodeInput(
AUGraph inGraph,
AUNode inDestNode,
UInt32 inDestInputNumber
);

Availability
Declared In
AUGraph.h

AUGraphClearConnections

Clears all of the connections between all inputs and outputs.

extern OSStatus AUGraphClearConnections(AUGraph inGraph);

Availability
Declared In
AUGraph.h

AUGraphGetNumberOfConnections

Returns the number of connections present in the graph.

extern OSStatus AUGraphGetNumberOfConnections(
AUGraph inGraph,
UInt32 *outNumberOfConnections
);

Availability
Declared In
AUGraph.h

AUGraphCountNodeConnections

Returns the number of connections that involve the specified node.

extern OSStatus AUGraphCountNodeConnections(
AUGraph inGraph,
AUNode inNode,
UInt32 *outNumConnections
);

Availability
Declared In
AUGraph.h

AUGraphGetNodeConnections

Returns an array containing the number of connections involving the specified node.

extern OSStatus AUGraphGetNodeConnections(
AUGraph inGraph,
AUNode inNode,
AudioUnitNodeConnection *outConnections,
UInt32 *ioNumConnections
);

Discussion

This function returns an “AudioUnitNodeConnection” array containing information about all of the pairs of connections that involve inNode. The size of the array will be reflected in ioNumConnections, while the value returned by AUGraphCountNodeConnections() should be passed to this parameter upon input.

Availability
Declared In
AUGraph.h

AUGraphGetConnectionInfo

Returns information about a particular connection.

extern OSStatus AUGraphGetConnectionInfo(
AUGraph inGraph,
UInt32 inConnectionIndex,
AUNode *outSourceNode,
UInt32 *outSourceOutputNumber,
AUNode *outDestNode,
UInt32 *outDestInputNumber
);

Discussion

Passing an index will return the information about it. The indices are arbitrarily assigned when the connections are made, and should follow the indices contained in the outConnections array returned by AUGraphGetNodeConnections().

Availability
Declared In
AUGraph.h

AUGraphUpdate

Updates all changes made to the graph while it is running.

extern OSStatus AUGraphUpdate(
AUGraph inGraph,
Boolean *outIsUpdated
);

Discussion

When a graph is running, no changes actually occur to the graph until AUGraphUpdate() is called. All node connect and disconnect requests are queued until this function called. When the graph is not running, all connect and disconnect requests are processed immediately, and therefore, AUGraphUpdate() is not necessary. If the value of outIsUpdated is NULL, the update will block all rendering until it is finished; a non-NULL value will allow AUGraphUpdate() to return immediately. A true value for outIsUpdated will indicate that all changes have occurred to the graph, whereas a false value means that there are still changes that have not occurred.

Availability
Declared In
AUGraph.h

AUGraphOpen

Instantiates every Audio Unit in the graph.

extern OSStatus AUGraphOpen(AUGraph inGraph);

Discussion

This function should be called after the initial set of nodes is added to the graph and connections have been made between them. This will instantiate the nodes, meaning that their properties will be ready for modification. Each node’s sample rate may also be set after the graph is opened.

Availability
Declared In
AUGraph.h

AUGraphClose

Closes the graph and deallocates its Audio Unit nodes.

extern OSStatus AUGraphClose(AUGraph inGraph);

Availability
Declared In
AUGraph.h

AUGraphInitialize

Initializes the graph and the connected Audio Units.

extern OSStatus AUGraphInitialize(AUGraph inGraph);

Discussion

Invoking this function will activate the connections between nodes and will initialize all nodes that are part of a connection. It is important to note that if format changes occur, sample rates for output nodes must be set before this function is called.

Availability
Declared In
AUGraph.h

AUGraphUninitialize

Uninitializes the graph and all of the Audio Units.

extern OSStatus AUGraphUninitialize(AUGraph inGraph);

Availability
Declared In
AUGraph.h

AUGraphStart

Begins audio rendering through the graph.

extern OSStatus AUGraphStart(AUGraph inGraph);

Discussion

This function starts with the head node, always an output unit, and works through the graph to get to the inputs, pulls the data, and renders it through all of the Audio Units in the path leading to the head.

Availability
Declared In
AUGraph.h

AUGraphStop

Stops all rendering through the graph.

extern OSStatus AUGraphStop(AUGraph inGraph);

Availability
Declared In
AUGraph.h

AUGraphIsOpen

Returns a boolean value indicting whether or not the graph is open.

extern OSStatus AUGraphIsOpen(
AUGraph inGraph,
Boolean *outIsOpen
);

Availability
Declared In
AUGraph.h

AUGraphIsInitialized

Returns a boolean value indicting whether or not the graph is initialized.

extern OSStatus AUGraphIsInitialized(
AUGraph inGraph,
Boolean *outIsInitialized
);

Availability
Declared In
AUGraph.h

AUGraphIsRunning

Returns a boolean value indicting whether or not the graph is running.

extern OSStatus AUGraphIsRunning(
AUGraph inGraph,
Boolean *outIsRunning
);

Availability
Declared In
AUGraph.h

AUGraphGetCPULoad

Returns the amount of load on the CPU.

extern OSStatus AUGraphGetCPULoad(
AUGraph inGraph,
Float32 *outCPULoad
);

Availability
Declared In
AUGraph.h

AUGraphSetRenderNotification

Specifies a callback for the render process.

extern OSStatus AUGraphSetRenderNotification(
AUGraph inGraph,
AudioUnitRenderCallback inCallback,
void *inRefCon
);

Discussion

This function is intended for use when the graph has Audio Units of type ‘aunt’. The callback is specified in inCallback, and is called before and after an audio render occurs. Passing NULL to inCallback removes all callbacks from the notification. Multiple notifications are allowed.

Availability
Declared In
AUGraph.h

AUGraphRemoveRenderNotification

Removes the specified callback from the notification.

extern OSStatus AUGraphRemoveRenderNotification(
AUGraph inGraph,
AudioUnitRenderCallback inCallback,
void *inRefCon
);

Discussion

This function is intended for use when the graph has Audio Units of type ‘aunt’.

Availability
Declared In
AUGraph.h

AUGraphAddRenderNotify

Specifies a callback for the render process.

extern OSStatus AUGraphAddRenderNotify(
AUGraph inGraph,
AURenderCallback inCallback,
void *inRefCon
);

Discussion

This function is intended for use when the graph has Audio Units of type ‘auXX’, where XX is one of the various version 2 Audio Unit types, as specified in AudioUnit/AUComponent.h. The callback is specified in inCallback, and is called before and after an audio render occurs. Passing NULL to inCallback removes all callbacks from the notification. Multiple notifications are allowed.

Availability
Declared In
AUGraph.h

AUGraphRemoveRenderNotify

Removes the specified callback from the notification.

extern OSStatus AUGraphRemoveRenderNotify(
AUGraph inGraph,
AURenderCallback inCallback,
void *inRefCon
);

Discussion

This function is intended for use when the graph has Audio Units of type ‘auXX’, where XX is one of the various version 2 Audio Unit types, as specified in AudioUnit/AUComponent.h.

Availability
Declared In
AUGraph.h

AUGraph Result Codes

These values are returned when errors occur.

kAUGraphErr_NodeNotFound = -10860
kAUGraphErr_InvalidConnection = -10861
kAUGraphErr_OutputNodeErr = -10862
kAUGraphErr_CannotDoInCurrentContext = -10863
kAUGraphErr_InvalidAudioUnit = -10864

Music Player and Music Sequence Reference

The Music Player and Music Sequence components allow for the sequencing of MIDI endpoints and audio units.

Music Player and Music Sequence Types

Defined Data Types

These typedefs are provided to support the different structures and functions in Music Player.

Data Structures

MIDINoteMessage

Stores information about a MIDI note event.

typedef struct MIDINoteMessage {
UInt8 channel;
UInt8 note;
UInt8 velocity;
UInt8 reserved;
Float32 duration;
} MIDINoteMessage;

Fields
channel

The channel number to which the note is assigned.

note

The value of the note to be played.

velocity

The volume at which the note is to be played.

reserved

duration

The length of time that the note should be played, in beats.

Discussion

This structure encapsulates the information needed to relay the properties of a note. An instance of this structure is used by the MusicTrackNewMIDINoteEvent function. The values of the structure are:

Availability
Declared In
MusicPlayer.h

MIDIChannelMessage

Stores the data for a MIDI channel event.

typedef struct MIDIChannelMessage {
UInt8 status;
UInt8 data1;
UInt8 data2;
UInt8 reserved;
} MIDIChannelMessage;

Fields
status

The message and the channel it is to be relayed to.

data1

Data specific to the message.

data2

Data specific to the message.

reserved

???

Discussion

This structure encapsulates the information needed for a channel event to be used in a music track. An instance of this structure is used by the MusicTrackNewMIDIChannelEvent function.

Availability
Declared In
MusicPlayer.h

MIDIRawData

Stores the information for any MIDI event.

typedef struct MIDIRawData {
UInt32 length;
UInt8 data[1];
} MIDIRawData;

Fields
length

The size of the space allocated for data.

data

The raw MIDI data to be stored; allocate as much space as needed for the data.

Discussion

This structure encapsulates the data for an event where raw MIDI data is sent to an endpoint. An instance of this structure is used by the MusicTrackNewMIDIRawDataEvent function. The values of the structure are:

Availability
Declared In
MusicPlayer.h

MIDIMetaEvent

Stores the data for a MIDI meta event.

typedef struct MIDIMetaEvent {
UInt8 metaEventType;
UInt8 unused1;
UInt8 unused2;
UInt8 unused3;
UInt32 dataLength;
UInt8 data[1];
} MIDIMetaEvent;

Fields
metaEventType

Specifies the type of meta event this structure encapsulates.

unused1

An unused value.

unused2

An unused value.

unused3

An unused value.

dataLength

The size of the space allocated for data.

data

The meta data for this event.

Discussion

This structure encapsulates the information needed to pass MIDI meta data, as found in standard MIDI files, to MIDI endpoints. An instance of this structure is used by the MusicTrackNewMetaEvent function. The values of the structure are:

Availability
Declared In
MusicPlayer.h

MusicEventUserData

Stores data for a user event .

typedef struct MusicEventUserData {
UInt32 length;
UInt8 data[1];
} MusicEventUserData;

Fields
length

The size, in bytes, of the value stored in data.

data

The data stored for this event.

Discussion

This structure encapsulates the information used on a user event. An instance of this structure is used by the MusicTrackNewUserEvent function.

Availability
Declared In
MusicPlayer.h

ExtendedNoteOnEvent

Stores the data for a playback note.

typedef struct ExtendedNoteOnEvent {
MusicDeviceInstrumentID instrumentID;
MusicDeviceGroupID groupID;
Float32 duration;
MusicDeviceNoteParams extendedParams;
} ExtendedNoteOnEvent;

Fields
instrumentID

The instrument to be used by the Music Device.

groupID

The channel of the Music Device.

duration

The length of the note.

extendedParams

Any additional parameters that need to be sent to the Music Device.

Discussion

This structure encapsulates the information needed to playback a note using a Music Device. An instance of this structure is used by the MusicTrackNewExtendedNoteEvent function.

Availability
Declared In
MusicPlayer.h

ExtendedControlEvent

Stores information regarding an event using a Music Device.

typedef struct ExtendedControlEvent {
MusicDeviceGroupID groupID;
AudioUnitParameterID controlID;
Float32 value;
} ExtendedControlEvent;

Fields
groupID

The channel of the Music Device to be controlled.

controlID

The Music Device parameter to be controlled.

value

The value to which the parameter should be set.

Discussion

This structure encapsulates the information needed to control a Music Device. An instance of this structure is used by the