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

Macros
#define	AEAudioBufferListCreateOnStack(name) AEAudioBufferListCreateOnStackWithFormat(name, AEAudioDescription)
	Create an audio buffer list on the stack, using the default audio format.

#define	AEAudioBufferListCreateOnStackWithFormat(name, audioFormat)
	Create an audio buffer list on the stack, with a custom audio format.

#define	AEAudioBufferListCopyOnStack(name, sourceBufferList, offsetFrames) AEAudioBufferListCopyOnStackWithByteOffset(name, sourceBufferList, offsetFrames * AEAudioDescription.mBytesPerFrame)
	Create a stack copy of the given audio buffer list and offset mData pointers.

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

#define	AEAudioBufferListCopyOnStackWithChannelSubset(name, sourceBufferList, channelSet)
	Create a stack copy of an audio buffer list that points to a subset of its channels.

Functions
AudioBufferList *	AEAudioBufferListCreate (int frameCount)
	Allocate an audio buffer list and the associated mData pointers, using the default audio format.

AudioBufferList *	AEAudioBufferListCreateWithFormat (AudioStreamBasicDescription audioFormat, int frameCount)
	Allocate an audio buffer list and the associated mData pointers, with a custom audio format.

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, int oNumberOfChannels)
	Get the number of frames in a buffer list, with the default audio format.

UInt32	AEAudioBufferListGetLengthWithFormat (const AudioBufferList bufferList, AudioStreamBasicDescription audioFormat, int oNumberOfChannels)
	Get the number of frames in a buffer list, with a custom audio format.

void	AEAudioBufferListSetLength (AudioBufferList *bufferList, UInt32 frames)
	Set the number of frames in a buffer list, with the default audio format.

void	AEAudioBufferListSetLengthWithFormat (AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 frames)
	Set the number of frames in a buffer list, with a custom audio format.

void	AEAudioBufferListOffset (AudioBufferList *bufferList, UInt32 frames)
	Offset the pointers in a buffer list, with the default audio format.

void	AEAudioBufferListOffsetWithFormat (AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 frames)
	Offset the pointers in a buffer list, with a custom audio format.

void	AEAudioBufferListAssign (AudioBufferList target, const AudioBufferList source, UInt32 offset, UInt32 length)
	Assign values of one buffer list to another, with the default audio format.

void	AEAudioBufferListAssignWithFormat (AudioBufferList target, const AudioBufferList source, AudioStreamBasicDescription audioFormat, UInt32 offset, UInt32 length)
	Assign values of one buffer list to another, with the default audio format.

void	AEAudioBufferListSilence (const AudioBufferList *bufferList, UInt32 offset, UInt32 length)
	Silence an audio buffer list (zero out frames), with the default audio format.

void	AEAudioBufferListSilenceWithFormat (const AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 offset, UInt32 length)
	Silence an audio buffer list (zero out frames), with a custom audio format.

void	AEAudioBufferListCopyContents (const AudioBufferList target, const AudioBufferList source, UInt32 targetOffset, UInt32 sourceOffset, UInt32 length)
	Copy the contents of one AudioBufferList to another, with the default audio format.

void	AEAudioBufferListCopyContentsWithFormat (const AudioBufferList target, const AudioBufferList source, AudioStreamBasicDescription audioFormat, UInt32 targetOffset, UInt32 sourceOffset, UInt32 length)
	Copy the contents of one AudioBufferList to another, with a custom audio format.

Macro Definition Documentation

#define AEAudioBufferListCreateOnStack ( name ) AEAudioBufferListCreateOnStackWithFormat(name, AEAudioDescription)

Create an audio buffer list on the stack, using the default audio format.

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

#define AEAudioBufferListCreateOnStackWithFormat	(	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; \
    for ( int i=0; i<name->mNumberBuffers; i++ ) { \
        name->mBuffers[i].mNumberChannels \
            = audioFormat.mFormatFlags & kAudioFormatFlagIsNonInterleaved ? 1 : audioFormat.mChannelsPerFrame; \
    }

Create an audio buffer list on the stack, with a custom audio format.

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,
		offsetFrames
	)	AEAudioBufferListCopyOnStackWithByteOffset(name, sourceBufferList, offsetFrames * AEAudioDescription.mBytesPerFrame)

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
offsetFrames	Number of frames of noninterleaved float to offset mData/mDataByteSize members

#define AEAudioBufferListCopyOnStackWithByteOffset	(	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, with offset in bytes.

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 AEAudioBufferListCopyOnStackWithChannelSubset	(	name,
		sourceBufferList,
		channelSet
	)

Value:

int name ## _bufferCount = MIN(sourceBufferList->mNumberBuffers-1, channelSet.lastChannel) - \
                               MIN(sourceBufferList->mNumberBuffers-1, channelSet.firstChannel) + 1; \
    char name ## _bytes[sizeof(AudioBufferList)+(sizeof(AudioBuffer)*(name ## _bufferCount-1))]; \
    AudioBufferList * name = (AudioBufferList*)name ## _bytes; \
    name->mNumberBuffers = name ## _bufferCount; \
    memcpy(name->mBuffers, &sourceBufferList->mBuffers[MIN(sourceBufferList->mNumberBuffers-1, channelSet.firstChannel)], \
        sizeof(AudioBuffer) * name ## _bufferCount);

Create a stack copy of an audio buffer list that points to a subset of its channels.

Parameters

name	Name of the variable to create on the stack
sourceBufferList	The original buffer list to copy
channelSet	The subset of channels

Function Documentation

AudioBufferList* AEAudioBufferListCreate ( int frameCount )

Allocate an audio buffer list and the associated mData pointers, using the default audio format.

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

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* AEAudioBufferListCreateWithFormat	(	AudioStreamBasicDescription	audioFormat,
		int	frameCount
	)

Allocate an audio buffer list and the associated mData pointers, with a custom audio format.

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,
		int *	oNumberOfChannels
	)

Get the number of frames in a buffer list, with the default audio format.

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
oNumberOfChannels	If not NULL, will be set to the number of channels of audio in 'list'

Returns: Number of frames in the buffer list

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

Get the number of frames in a buffer list, with a custom audio format.

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,
		UInt32	frames
	)

Set the number of frames in a buffer list, with the default audio format.

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
frames	The number of frames to set

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

Set the number of frames in a buffer list, with a custom audio format.

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,
		UInt32	frames
	)

Offset the pointers in a buffer list, with the default audio format.

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
frames	The number of frames to offset the mData pointers by

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

Offset the pointers in a buffer list, with a custom audio format.

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 AEAudioBufferListAssign	(	AudioBufferList *	target,
		const AudioBufferList *	source,
		UInt32	offset,
		UInt32	length
	)

Assign values of one buffer list to another, with the default audio format.

Note that this simply assigns the buffer list values; if you wish to copy the contents, use AEAudioBufferListCopy or AEAudioBufferListCopyContents

Parameters

target	Target buffer list, to assign values to
source	Source buffer list, to assign values from
offset	Offset into target buffer
length	Length to assign, in frames

void AEAudioBufferListAssignWithFormat	(	AudioBufferList *	target,
		const AudioBufferList *	source,
		AudioStreamBasicDescription	audioFormat,
		UInt32	offset,
		UInt32	length
	)

Assign values of one buffer list to another, with the default audio format.

Note that this simply assigns the buffer list values; if you wish to copy the contents, use AEAudioBufferListCopy or AEAudioBufferListCopyContents

Parameters

target	Target buffer list, to assign values to
source	Source buffer list, to assign values from
audioFormat	Audio format describing the audio in the buffer list
offset	Offset into target buffer
length	Length to assign, in frames

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

Silence an audio buffer list (zero out frames), with the default audio format.

Parameters

bufferList	Pointer to an AudioBufferList containing audio
offset	Offset into buffer
length	Number of frames to silence

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

Silence an audio buffer list (zero out frames), with a custom audio format.

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

void AEAudioBufferListCopyContents	(	const AudioBufferList *	target,
		const AudioBufferList *	source,
		UInt32	targetOffset,
		UInt32	sourceOffset,
		UInt32	length
	)

Copy the contents of one AudioBufferList to another, with the default audio format.

Parameters

target	Target buffer list, to copy to
source	Source buffer list, to copy from
targetOffset	Offset into target buffer
sourceOffset	Offset into source buffer
length	Number of frames to copy

void AEAudioBufferListCopyContentsWithFormat	(	const AudioBufferList *	target,
		const AudioBufferList *	source,
		AudioStreamBasicDescription	audioFormat,
		UInt32	targetOffset,
		UInt32	sourceOffset,
		UInt32	length
	)

Copy the contents of one AudioBufferList to another, with a custom audio format.

Parameters

target	Target buffer list, to copy to
source	Source buffer list, to copy from
audioFormat	Audio format describing the audio in the buffer list
targetOffset	Offset into target buffer
sourceOffset	Offset into source buffer
length	Number of frames to copy

Macros

Functions

Macro Definition Documentation

Function Documentation