AEMixerBuffer Class Reference

Mixer buffer. More...

#import <AEMixerBuffer.h>

Inherits <NSObject>.

Instance Methods
(id)	- initWithClientFormat:
	Initialiser.
(void)	- AEMixerBufferEnqueue
	Enqueue audio.
(void)	- setRenderCallback:peekCallback:userInfo:forSource:
	Assign callbacks for a source.
(void)	- AEMixerBufferDequeue
	Dequeue audio.
(void)	- AEMixerBufferDequeueSingleSource
	Dequeue a single source.
(UInt32)	- AEMixerBufferPeek
	Peek the audio buffer.
(void)	- AEMixerBufferEndTimeInterval
	Mark end of time interval.
(void)	- AEMixerBufferMarkSourceIdle
	Mark the given source as idle.
(void)	- setAudioDescription:forSource:
	Set a different AudioStreamBasicDescription for a source.
(void)	- setVolume:forSource:
	Set volume for source.
(float)	- volumeForSource:
	Get volume for source.
(void)	- setPan:forSource:
	Set pan for source.
(float)	- panForSource:
	Get pan for source.
(void)	- unregisterSource:
	Force the mixer to unregister a source.

Properties
AudioStreamBasicDescription	clientFormat
	Client audio format.
NSTimeInterval	sourceIdleThreshold
	How long to wait for empty sources before assuming they are idle.
BOOL	assumeInfiniteSources
	Whether to assume sources have infinite capacity.
int	debugLevel
	Debug level.

Detailed Description

Mixer buffer.

This class performs mixing of multiple audio sources, using the timestamps corresponding to each audio packet from each source to synchronise all sources together.

To use it, create an instance, passing in the AudioStreamBasicDescription of your audio, then provide data for each source by calling AEMixerBufferEnqueue. Or, provide callbacks for one or more sources with setRenderCallback:peekCallback:userInfo:forSource:, which will cause this class to call your callbacks when data is needed.

Then, call AEMixerBufferDequeue to consume mixed and synchronised audio ready for playback, recording, etc.

Method Documentation

- (id) initWithClientFormat:

(AudioStreamBasicDescription)

clientFormat

Initialiser.

Parameters

clientFormat

The AudioStreamBasicDescription defining the audio format used

- (void) AEMixerBufferEnqueue		(AEMixerBuffer *)	mixerBuffer
		(AEMixerBufferSource)	source
		(AudioBufferList *)	audio
		(UInt32)	lengthInFrames
		(const AudioTimeStamp *)	timestamp

Enqueue audio.

Feed the buffer with audio blocks. Identify each source via the source parameter. You may use any identifier you like - pointers, numbers, etc (just cast to AEMixerBufferSource).

When you enqueue audio from a new source (that is, the source value is one that hasn't been seen before, this class will automatically reconfigure itself to start mixing the new source. However, this will happen at some point in the near future, not immediately, so one or two buffers may be lost. If this is a problem, then call this function first on the main thread, for each source, with a NULL audio buffer, and a lengthInFrames value of 0.

This function can safely be used in a different thread from the dequeue function. It can also be used in a different thread from other calls to enqueue, given two conditions: No two threads enqueue the same source, and no two threads call enqueue for a new source simultaneously.

Parameters

mixerBuffer	The mixer buffer.
source	The audio source. This can be anything you like, as long as it is not NULL, and is unique to each source.
audio	The audio buffer list.
lengthInFrames	The length of audio.
timestamp	The timestamp associated with the audio.

- (void) setRenderCallback:		(AEMixerBufferSourceRenderCallback)	renderCallback
peekCallback:		(AEMixerBufferSourcePeekCallback)	peekCallback
userInfo:		(void *)	userInfo
forSource:		(AEMixerBufferSource)	source

Assign callbacks for a source.

Rather than providing audio for a source using AEMixerBufferEnqueue, you may provide callbacks which will be called by the mixer as required. You must either provide audio via AEMixerBufferEnqueue, or via this method, but never both.

Parameters

renderCallback	The render callback, used to receive audio.
peekCallback	The peek callback, used to get info about the source's buffer status.
userInfo	An opaque pointer that will be provided to the callbacks.
source	The audio source.

- (void) AEMixerBufferDequeue		(AEMixerBuffer *)	mixerBuffer
		(AudioBufferList *)	bufferList
		(UInt32 *)	ioLengthInFrames
		(AudioTimeStamp *)	outTimestamp

Dequeue audio.

Call this function to receive synchronised and mixed audio.

This can safely be used in a different thread from the enqueue function.

Parameters

mixerBuffer	The mixer buffer.
bufferList	The buffer list to write audio to. The mData pointers may be NULL, in which case an internal buffer will be provided. You may also pass a NULL value, which will simply discard the given number of frames.
ioLengthInFrames	On input, the number of frames of audio to dequeue. On output, the number of frames returned.
outTimestamp	On output, the timestamp of the first audio sample

- (void) AEMixerBufferDequeueSingleSource		(AEMixerBuffer *)	mixerBuffer
		(AEMixerBufferSource)	source
		(AudioBufferList *)	bufferList
		(UInt32 *)	ioLengthInFrames
		(AudioTimeStamp *)	outTimestamp

Dequeue a single source.

Normally not used, but if you wish to simply use this class to synchronise the audio across a number of sources, rather than mixing the sources together also, then this function allows you to access the synchronized audio for each source.

Do not use this function together with AEMixerBufferDequeue.

Parameters

mixerBuffer	The mixer buffer.
source	The audio source.
bufferList	The buffer list to write audio to. The mData pointers may be NULL, in which case an internal buffer will be provided.
ioLengthInFrames	On input, the number of frames of audio to dequeue. On output, the number of frames returned.
outTimestamp	On output, the timestamp of the first audio sample

- (UInt32) AEMixerBufferPeek		(AEMixerBuffer *)	mixerBuffer
		(AudioTimeStamp *)	outNextTimestamp

Peek the audio buffer.

Use this to determine how much audio is currently buffered, and the corresponding next timestamp.

Parameters

mixerBuffer	The mixer buffer
outNextTimestamp	If not NULL, the timestamp of the next available audio

Returns

Number of frames of available audio, in the specified audio format.

- (void) AEMixerBufferEndTimeInterval

(AEMixerBuffer *)

mixerBuffer

Mark end of time interval.

When receiving each audio source separately via AEMixerBufferDequeueSingleSource (instead of mixed with AEMixerBufferDequeue), you must call this function at the end of each time interval in order to inform the mixer that you are finished with that audio segment. Any sources that have not been dequeued will have their audio discarded in order to retain synchronization.

Parameters

mixerBuffer

The mixer buffer.

- (void) AEMixerBufferMarkSourceIdle		(AEMixerBuffer *)	mixerBuffer
		(AEMixerBufferSource)	source

Mark the given source as idle.

Normally, if the mixer buffer doesn't receive any audio for a given source within the time interval given by the sourceIdleThreshold property, the buffer will wait, allowing no frames to be dequeued until either further audio is received for the source, or the sourceIdleThreshold limit is met.

To avoid this delay and immediately mark a given source as idle, use this function.

Parameters

mixerBuffer	The mixer buffer
source	The source to mark as idle

- (void) setAudioDescription:		(AudioStreamBasicDescription)	audioDescription
forSource:		(AEMixerBufferSource)	source

Set a different AudioStreamBasicDescription for a source.

Important: Do not change this property while using enqueue/dequeue. You must stop enqueuing or dequeuing audio first.

- (void) setVolume:		(float)	volume
forSource:		(AEMixerBufferSource)	source

Set volume for source.

- (float) volumeForSource:

(AEMixerBufferSource)

source

Get volume for source.

- (void) setPan:		(float)	pan
forSource:		(AEMixerBufferSource)	source

Set pan for source.

- (float) panForSource:

(AEMixerBufferSource)

source

Get pan for source.

- (void) unregisterSource:

(AEMixerBufferSource)

source

Force the mixer to unregister a source.

After this function is called, the mixer will have reconfigured to stop mixing the given source. If callbacks for the source were provided, these will never be called again after this function returns.

Use of this function is entirely optional - the mixer buffer will automatically unregister sources it is no longer receiving audio for, and will clean up when deallocated.

Parameters

source

The audio source.

Property Documentation

- (AudioStreamBasicDescription) clientFormat

readwritenonatomicassign

Client audio format.

Important: Do not change this property while using enqueue/dequeue. You must stop enqueuing or dequeuing audio first.

- (NSTimeInterval) sourceIdleThreshold

readwritenonatomicassign

How long to wait for empty sources before assuming they are idle.

AEMixerBufferDequeue will return 0 frames for this duration if any sources are currently empty, before assuming the source is idle and continuing.

Set to 0.0 to avoid waiting on idle sources.

- (BOOL) assumeInfiniteSources

readwritenonatomicassign

Whether to assume sources have infinite capacity.

Setting this to YES will make the mixer assume the frame count for each source is infinite, and will render sources regardless of the frame count returned by the peek callback.

Note that the results of AEMixerBufferPeek will still return a frame count derived by the true frame count returned by the peek callback, but calling AEMixerBufferRender will assume that the available frame count across all sources is infinite.

This property is useful when using sources that generate audio on demand.

- (int) debugLevel

readwritenonatomicassign

Debug level.

---

The documentation for this class was generated from the following file:

• AEMixerBuffer.h