#import <AudioToolbox/AudioToolbox.h>
#import <Foundation/Foundation.h>

Functions
Time Utilities
void	AETimeInit (void)
	Initialize time utilities.

uint64_t	AECurrentTimeInHostTicks (void)
	Get current global timestamp, in host ticks.

double	AECurrentTimeInSeconds (void)
	Get current global timestamp, in seconds.

uint64_t	AEHostTicksFromSeconds (double seconds)
	Convert time in seconds to host ticks.

double	AESecondsFromHostTicks (uint64_t ticks)
	Convert time in host ticks to seconds.

AudioBufferList Utilities
#define	AEAllocateAndInitAudioBufferList AEAudioBufferListCreate

#define	AEAudioBufferListCreateOnStack(name, audioFormat)
	Create an audio buffer list on the stack.

#define	AEAudioBufferListCopyOnStack(name, sourceBufferList, offsetBytes)
	Create a stack copy of the given audio buffer list and offset mData pointers.

#define	AECopyAudioBufferList AEAudioBufferListCopy

#define	AEFreeAudioBufferList AEAudioBufferListFree

#define	AEGetNumberOfFramesInAudioBufferList AEAudioBufferListGetLength

AudioBufferList *	AEAudioBufferListCreate (AudioStreamBasicDescription audioFormat, int frameCount)
	Allocate an audio buffer list and the associated mData pointers.

AudioBufferList *	AEAudioBufferListCopy (const AudioBufferList *original)
	Create a copy of an audio buffer list.

void	AEAudioBufferListFree (AudioBufferList *bufferList)
	Free a buffer list and associated mData buffers.

UInt32	AEAudioBufferListGetLength (const AudioBufferList bufferList, AudioStreamBasicDescription audioFormat, int oNumberOfChannels)
	Get the number of frames in a buffer list.

void	AEAudioBufferListSetLength (AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 frames)
	Set the number of frames in a buffer list.

void	AEAudioBufferListOffset (AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 frames)
	Offset the pointers in a buffer list.

void	AEAudioBufferListSilence (const AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 offset, UInt32 length)
	Silence an audio buffer list (zero out frames)

AudioStreamBasicDescription Utilities
enum	AEAudioStreamBasicDescriptionSampleType { AEAudioStreamBasicDescriptionSampleTypeFloat32, AEAudioStreamBasicDescriptionSampleTypeInt16, AEAudioStreamBasicDescriptionSampleTypeInt32 }
	Types of samples, for use with AEAudioStreamBasicDescriptionMake. More...

const AudioStreamBasicDescription	AEAudioStreamBasicDescriptionNonInterleavedFloatStereo
	32-bit floating-point PCM audio description, non-interleaved, 44.1kHz

const AudioStreamBasicDescription	AEAudioStreamBasicDescriptionNonInterleaved16BitStereo
	16-bit stereo PCM audio description, non-interleaved, 44.1kHz

const AudioStreamBasicDescription	AEAudioStreamBasicDescriptionInterleaved16BitStereo
	16-bit stereo PCM audio description, interleaved, 44.1kHz

AudioStreamBasicDescription	AEAudioStreamBasicDescriptionMake (AEAudioStreamBasicDescriptionSampleType sampleType, BOOL interleaved, int numberOfChannels, double sampleRate)
	Create a custom AudioStreamBasicDescription.

void	AEAudioStreamBasicDescriptionSetChannelsPerFrame (AudioStreamBasicDescription *audioDescription, int numberOfChannels)
	Assign a channel count to an AudioStreamBasicDescription.

Other Utilities
#define	AECheckOSStatus(result, operation) (_AECheckOSStatus((result),(operation),strrchr(__FILE__, '/')+1,__LINE__))
	Check an OSStatus condition.

AudioComponentDescription	AEAudioComponentDescriptionMake (OSType manufacturer, OSType type, OSType subtype)
	Create an AudioComponentDescription structure.

BOOL	AERateLimit (void)
	Rate limit an operation.

Macro Definition Documentation

#define AEAllocateAndInitAudioBufferList AEAudioBufferListCreate

#define AEAudioBufferListCreateOnStack	(	name,
		audioFormat
	)

Value:

int name ## _numberBuffers = audioFormat.mFormatFlags & kAudioFormatFlagIsNonInterleaved \
 ? audioFormat.mChannelsPerFrame : 1; \
 char name ## _bytes[sizeof(AudioBufferList)+(sizeof(AudioBuffer)*(name ## _numberBuffers-1))]; \
 memset(&name ## _bytes, 0, sizeof(name ## _bytes)); \
 AudioBufferList * name = (AudioBufferList*)name ## _bytes; \
 name->mNumberBuffers = name ## _numberBuffers;

Create an audio buffer list on the stack.

This is useful for creating buffers for temporary use, without needing to perform any memory allocations. It will create a local AudioBufferList* variable on the stack, with a name given by the first argument, and initialise the buffer according to the given audio format.

The created buffer will have NULL mData pointers and 0 mDataByteSize: you will need to assign these to point to a memory buffer.

Parameters

name	Name of the variable to create on the stack
audioFormat	The audio format to use

#define AEAudioBufferListCopyOnStack	(	name,
		sourceBufferList,
		offsetBytes
	)

Value:

char name ## _bytes[sizeof(AudioBufferList)+(sizeof(AudioBuffer)*(sourceBufferList->mNumberBuffers-1))]; \
 memcpy(name ## _bytes, sourceBufferList, sizeof(name ## _bytes)); \
 AudioBufferList * name = (AudioBufferList*)name ## _bytes; \
 for ( int i=0; i<name->mNumberBuffers; i++ ) { \
 name->mBuffers[i].mData = (char*)name->mBuffers[i].mData + offsetBytes; \
 name->mBuffers[i].mDataByteSize -= offsetBytes; \
 }

Create a stack copy of the given audio buffer list and offset mData pointers.

This is useful for creating buffers that point to an offset into the original buffer, to fill later regions of the buffer. It will create a local AudioBufferList* variable on the stack, with a name given by the first argument, copy the original AudioBufferList structure values, and offset the mData and mDataByteSize variables.

Note that only the AudioBufferList structure itself will be copied, not the data to which it points.

Parameters

name	Name of the variable to create on the stack
sourceBufferList	The original buffer list to copy
offsetBytes	Number of bytes to offset mData/mDataByteSize members

#define AECopyAudioBufferList AEAudioBufferListCopy

#define AEFreeAudioBufferList AEAudioBufferListFree

#define AEGetNumberOfFramesInAudioBufferList AEAudioBufferListGetLength

#define AECheckOSStatus	(	result,
		operation
	)	(_AECheckOSStatus((result),(operation),strrchr(__FILE__, '/')+1,__LINE__))

Check an OSStatus condition.

Parameters

result	The result
operation	A description of the operation, for logging purposes

Enumeration Type Documentation

enum AEAudioStreamBasicDescriptionSampleType

Types of samples, for use with AEAudioStreamBasicDescriptionMake.

Enumerator:

AEAudioStreamBasicDescriptionSampleTypeFloat32	32-bit floating point
AEAudioStreamBasicDescriptionSampleTypeInt16	Signed 16-bit integer.
AEAudioStreamBasicDescriptionSampleTypeInt32	Signed 32-bit integer.

Function Documentation

AudioBufferList* AEAudioBufferListCreate	(	AudioStreamBasicDescription	audioFormat,
		int	frameCount
	)

Allocate an audio buffer list and the associated mData pointers.

Note: Do not use this utility from within the Core Audio thread (such as inside a render callback). It may cause the thread to block, inducing audio stutters.

Parameters

audioFormat	Audio format describing audio to be stored in buffer list
frameCount	The number of frames to allocate space for (or 0 to just allocate the list structure itself)

Returns: The allocated and initialised audio buffer list

AudioBufferList* AEAudioBufferListCopy ( const AudioBufferList * original )

Create a copy of an audio buffer list.

Note: Do not use this utility from within the Core Audio thread (such as inside a render callback). It may cause the thread to block, inducing audio stutters.

Parameters

original The original AudioBufferList to copy

Returns: The new, copied audio buffer list

void AEAudioBufferListFree ( AudioBufferList * bufferList )

Free a buffer list and associated mData buffers.

Note: Do not use this utility from within the Core Audio thread (such as inside a render callback). It may cause the thread to block, inducing audio stutters.

UInt32 AEAudioBufferListGetLength	(	const AudioBufferList *	bufferList,
		AudioStreamBasicDescription	audioFormat,
		int *	oNumberOfChannels
	)

Get the number of frames in a buffer list.

Calculates the frame count in the buffer list based on the given audio format. Optionally also provides the channel count.

Parameters

bufferList	Pointer to an AudioBufferList containing audio
audioFormat	Audio format describing the audio in the buffer list
oNumberOfChannels	If not NULL, will be set to the number of channels of audio in 'list'

Returns: Number of frames in the buffer list

void AEAudioBufferListSetLength	(	AudioBufferList *	bufferList,
		AudioStreamBasicDescription	audioFormat,
		UInt32	frames
	)

Set the number of frames in a buffer list.

Calculates the frame count in the buffer list based on the given audio format, and assigns it to the buffer list members.

Parameters

bufferList	Pointer to an AudioBufferList containing audio
audioFormat	Audio format describing the audio in the buffer list
frames	The number of frames to set

void AEAudioBufferListOffset	(	AudioBufferList *	bufferList,
		AudioStreamBasicDescription	audioFormat,
		UInt32	frames
	)

Offset the pointers in a buffer list.

Increments the mData pointers in the buffer list by the given number of frames. This is useful for filling a buffer in incremental stages.

Parameters

bufferList	Pointer to an AudioBufferList containing audio
audioFormat	Audio format describing the audio in the buffer list
frames	The number of frames to offset the mData pointers by

void AEAudioBufferListSilence	(	const AudioBufferList *	bufferList,
		AudioStreamBasicDescription	audioFormat,
		UInt32	offset,
		UInt32	length
	)

Silence an audio buffer list (zero out frames)

Parameters

bufferList	Pointer to an AudioBufferList containing audio
audioFormat	Audio format describing the audio in the buffer list
offset	Offset into buffer
length	Number of frames to silence (0 for whole buffer)

AudioStreamBasicDescription AEAudioStreamBasicDescriptionMake	(	AEAudioStreamBasicDescriptionSampleType	sampleType,
		BOOL	interleaved,
		int	numberOfChannels,
		double	sampleRate
	)

Create a custom AudioStreamBasicDescription.

Parameters

sampleType	Kind of samples
interleaved	Whether samples are interleaved within the same buffer, or in separate buffers for each channel
numberOfChannels	Channel count
sampleRate	The sample rate, in Hz (e.g. 44100)

Returns: A new AudioStreamBasicDescription describing the audio format

void AEAudioStreamBasicDescriptionSetChannelsPerFrame	(	AudioStreamBasicDescription *	audioDescription,
		int	numberOfChannels
	)

Assign a channel count to an AudioStreamBasicDescription.

This method ensures that the mBytesPerFrame/mBytesPerPacket value is updated correctly for both interleaved and non-interleaved audio.

void AETimeInit ( void )

Initialize time utilities.

uint64_t AECurrentTimeInHostTicks ( void )

Get current global timestamp, in host ticks.

double AECurrentTimeInSeconds ( void )

Get current global timestamp, in seconds.

uint64_t AEHostTicksFromSeconds ( double seconds )

Convert time in seconds to host ticks.

Parameters

seconds The time in seconds

Returns: The time in host ticks

double AESecondsFromHostTicks ( uint64_t ticks )

Convert time in host ticks to seconds.

Parameters

ticks The time in host ticks

Returns: The time in seconds

AudioComponentDescription AEAudioComponentDescriptionMake	(	OSType	manufacturer,
		OSType	type,
		OSType	subtype
	)

Create an AudioComponentDescription structure.

Parameters

manufacturer	The audio component manufacturer (e.g. kAudioUnitManufacturer_Apple)
type	The type (e.g. kAudioUnitType_Generator)
subtype	The subtype (e.g. kAudioUnitSubType_AudioFilePlayer)

Returns: An AudioComponentDescription structure with the given attributes

BOOL AERateLimit ( void )

Rate limit an operation.

This can be used to prevent spamming error messages to the console when something goes wrong.

Variable Documentation

const AudioStreamBasicDescription AEAudioStreamBasicDescriptionNonInterleavedFloatStereo

32-bit floating-point PCM audio description, non-interleaved, 44.1kHz

const AudioStreamBasicDescription AEAudioStreamBasicDescriptionNonInterleaved16BitStereo

16-bit stereo PCM audio description, non-interleaved, 44.1kHz

const AudioStreamBasicDescription AEAudioStreamBasicDescriptionInterleaved16BitStereo

16-bit stereo PCM audio description, interleaved, 44.1kHz

Functions

AudioBufferList Utilities

AudioStreamBasicDescription Utilities

Other Utilities

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation