AEAudioController.h File Reference
#import <AudioToolbox/AudioToolbox.h>
#import <AudioUnit/AudioUnit.h>
#import <Foundation/Foundation.h>
#import "AEMessageQueue.h"

Go to the source code of this file.

Classes

protocol  <AEAudioPlayable>
 AEAudioPlayable protocol. More...
 
protocol  <AEAudioReceiver>
 AEAudioReceiver protocol. More...
 
protocol  <AEAudioFilter>
 AEAudioFilter protocol. More...
 
protocol  <AEAudioTimingReceiver>
 AEAudioTimingReceiver protocol. More...
 
class  AEAudioController
 Main controller class. More...
 

Typedefs

typedef OSStatus(* AEAudioRenderCallback )(__unsafe_unretained id channel, __unsafe_unretained AEAudioController *audioController, const AudioTimeStamp *time, UInt32 frames, AudioBufferList *audio)
 Render callback.
 
typedef AEAudioRenderCallback AEAudioControllerRenderCallback
 
typedef void(* AEAudioReceiverCallback )(__unsafe_unretained id receiver, __unsafe_unretained AEAudioController *audioController, void *source, const AudioTimeStamp *time, UInt32 frames, AudioBufferList *audio)
 Audio receiver callback.
 
typedef AEAudioReceiverCallback AEAudioControllerAudioCallback
 
typedef OSStatus(* AEAudioFilterProducer )(void *producerToken, AudioBufferList *audio, UInt32 *frames)
 Filter audio producer.
 
typedef AEAudioFilterProducer AEAudioControllerFilterProducer
 
typedef OSStatus(* AEAudioFilterCallback )(__unsafe_unretained id filter, __unsafe_unretained AEAudioController *audioController, AEAudioFilterProducer producer, void *producerToken, const AudioTimeStamp *time, UInt32 frames, AudioBufferList *audio)
 Filter callback.
 
typedef AEAudioFilterCallback AEAudioControllerFilterCallback
 
typedef void(* AEAudioTimingCallback )(__unsafe_unretained id receiver, __unsafe_unretained AEAudioController *audioController, const AudioTimeStamp *time, UInt32 frames, AEAudioTimingContext context)
 Timing callback.
 
typedef AEAudioTimingCallback AEAudioControllerTimingCallback
 
typedef struct _channel_group_t * AEChannelGroupRef
 Channel group identifier.
 

Enumerations

enum  { AEAudioControllerErrorInputAccessDenied }
 
enum  AEInputMode { AEInputModeFixedAudioFormat, AEInputModeVariableAudioFormat }
 Input mode. More...
 
enum  AEAudioTimingContext { AEAudioTimingContextInput, AEAudioTimingContextOutput }
 Timing contexts. More...
 
enum  AEAudioControllerOptions {
  AEAudioControllerOptionEnableInput = 1 << 0, AEAudioControllerOptionEnableOutput = 1 << 1, AEAudioControllerOptionUseVoiceProcessing = 1 << 2, AEAudioControllerOptionUseHardwareSampleRate = 1 << 3,
  AEAudioControllerOptionEnableBluetoothInput = 1 << 4, AEAudioControllerOptionAllowMixingWithOtherApps = 1 << 5, AEAudioControllerOptionDefaults
}
 Options for initializing. More...
 

Variables

NSString *const AEAudioControllerSessionInterruptionBeganNotification
 Notification that the audio session has been interrupted.
 
NSString *const AEAudioControllerSessionInterruptionEndedNotification
 Notification that the audio session interrupted has ended, and control has been passed back to the application.
 
NSString *const AEAudioControllerSessionRouteChangeNotification
 Notification that the system's audio route has changed.
 
NSString *const AEAudioControllerDidRecreateGraphNotification
 Notification that AEAudioController has shut down and re-initialized the audio graph.
 
NSString *const AEAudioControllerErrorOccurredNotification
 Some asynchronous error occurred, such as when the user denies your app record access.
 
NSString *const AEAudioControllerErrorKey
 Keys to be used with notifications.
 
NSString *const AEAudioControllerErrorDomain
 Errors.
 

Typedef Documentation

typedef OSStatus(* AEAudioRenderCallback)(__unsafe_unretained id channel, __unsafe_unretained AEAudioController *audioController, const AudioTimeStamp *time, UInt32 frames, AudioBufferList *audio)

Render callback.

This is called when audio for the channel is required. As this is called from Core Audio's realtime thread, you should not wait on locks, allocate memory, or call any Objective-C or BSD code from this callback.

The channel object is passed through as a parameter. You should not send it Objective-C messages, but if you implement the callback within your channel's @implementation block, you can gain direct access to the instance variables of the channel ("((MyChannel*)channel)->myInstanceVariable").

Parameters
channelThe channel object
audioControllerThe Audio Controller
timeThe time the buffer will be played, automatically compensated for hardware latency.
framesThe number of frames required
audioThe audio buffer list - audio should be copied into the provided buffers
Returns
A status code
typedef void(* AEAudioReceiverCallback)(__unsafe_unretained id receiver, __unsafe_unretained AEAudioController *audioController, void *source, const AudioTimeStamp *time, UInt32 frames, AudioBufferList *audio)

Audio receiver callback.

This callback is used for notifying you of incoming audio (either from the built-in microphone, or another input device), and outgoing audio that is about to be played by the system.

The receiver object is passed through as a parameter. You should not send it Objective-C messages, but if you implement the callback within your receiver's @implementation block, you can gain direct access to the instance variables of the receiver ("((MyReceiver*)receiver)->myInstanceVariable").

Do not wait on locks, allocate memory, or call any Objective-C or BSD code.

Parameters
receiverThe receiver object
audioControllerThe Audio Controller
sourceThe source of the audio: AEAudioSourceInput, AEAudioSourceMainOutput, an AEChannelGroupRef or an id<AEAudioPlayable>.
timeThe time the audio was received (for input), or the time it will be played (for output), automatically compensated for hardware latency.
framesThe length of the audio, in frames
audioThe audio buffer list
typedef OSStatus(* AEAudioFilterProducer)(void *producerToken, AudioBufferList *audio, UInt32 *frames)

Filter audio producer.

This defines the function passed to a AEAudioFilterCallback, which is used to produce input audio to be processed by the filter.

Parameters
producerTokenAn opaque pointer to be passed to the function
audioAudio buffer list to be written to
framesNumber of frames to produce on input, number of frames produced on output
Returns
A status code
typedef OSStatus(* AEAudioFilterCallback)(__unsafe_unretained id filter, __unsafe_unretained AEAudioController *audioController, AEAudioFilterProducer producer, void *producerToken, const AudioTimeStamp *time, UInt32 frames, AudioBufferList *audio)

Filter callback.

This callback is used for audio filters.

A filter implementation must call the function pointed to by the producer argument, passing producerToken, audio, and frames as arguments, in order to produce as much audio is required to produce frames frames of output audio:

    OSStatus status = producer(producerToken, audio, &frames);
    if ( status != noErr ) return status;

Then the audio can be processed as desired.

The filter object is passed through as a parameter. You should not send it Objective-C messages, but if you implement the callback within your filter's @implementation block, you can gain direct access to the instance variables of the filter ("((MyFilter*)filter)->myInstanceVariable").

Do not wait on locks, allocate memory, or call any Objective-C or BSD code.

Parameters
filterThe filter object
audioControllerThe Audio Controller
producerA function pointer to be used to produce input audio
producerTokenAn opaque pointer to be passed to the producer as the first argument
timeThe time the output audio will be played or the time input audio was received, automatically compensated for hardware latency.
framesThe length of the required audio, in frames
audioThe audio buffer list to write output audio to
Returns
A status code
typedef void(* AEAudioTimingCallback)(__unsafe_unretained id receiver, __unsafe_unretained AEAudioController *audioController, const AudioTimeStamp *time, UInt32 frames, AEAudioTimingContext context)

Timing callback.

This callback used to notify you when the system time advances. When called from an input context, it occurs before any input receiver calls are performed. When called from an output context, it occurs before any output receivers are performed.

The receiver object is passed through as a parameter. You should not send it Objective-C messages, but if you implement the callback within your receiver's @implementation block, you can gain direct access to the instance variables of the receiver ("((MyReceiver*)receiver)->myInstanceVariable").

Do not wait on locks, allocate memory, or call any Objective-C or BSD code.

Parameters
receiverThe receiver object
audioControllerThe Audio Controller
timeThe time the audio was received (for input), or the time it will be played (for output), automatically compensated for hardware latency.
framesThe number of frames for the current block
contextThe timing context - either input, or output
typedef struct _channel_group_t* AEChannelGroupRef

Channel group identifier.

See AEAudioController::createChannelGroup for more info.

Enumeration Type Documentation

anonymous enum
Enumerator:
AEAudioControllerErrorInputAccessDenied 

Input mode.

How to handle incoming audio

Enumerator:
AEInputModeFixedAudioFormat 

Receive input in the exact, fixed audio format you specified when initializing the audio controller, regardless of the number of input channels.

For example, if you specified a stereo audio stream description, and you have a mono input source, the mono source will be bridged to stereo.

This is the default.

AEInputModeVariableAudioFormat 

Audio format will change, depending on the number of input channels available.

Mono audio sources will produce mono audio; 8-channel audio sources will produce 8-channel audio. You can determine how many channels are being provided by examining the mNumberBuffers field of the AudioBufferList for non-interleaved audio, or the mNumberOfChannels field of the first buffer within the AudioBufferList for interleaved audio. Note that this might change without warning, as the user plugs/unplugs hardware.

Timing contexts.

Used to indicate which context the audio system is in when a timing receiver is called.

Enumerator:
AEAudioTimingContextInput 

Input context: Audio system is about to process some incoming audio (from microphone, etc).

AEAudioTimingContextOutput 

Output context: Audio system is about to render the next buffer for playback.

Options for initializing.

Enumerator:
AEAudioControllerOptionEnableInput 

Whether to enable audio input from the microphone or another input device.

AEAudioControllerOptionEnableOutput 

Whether to enable audio output.

AEAudioControllerOptionUseVoiceProcessing 

Whether to use the voice processing unit (see voiceProcessingEnabled and voiceProcessingAvailable ).

AEAudioControllerOptionUseHardwareSampleRate 

Whether to use the the actual hardware sample rate instead of converting.

AEAudioControllerOptionEnableBluetoothInput 

Enable audio input from Bluetooth devices.

AEAudioControllerOptionAllowMixingWithOtherApps 

Whether to allow mixing audio with other apps.

AEAudioControllerOptionDefaults 

Default options.

Variable Documentation

AEAudioControllerSessionInterruptionBeganNotification

Notification that the audio session has been interrupted.

AEAudioControllerSessionInterruptionEndedNotification

Notification that the audio session interrupted has ended, and control has been passed back to the application.

AEAudioControllerSessionRouteChangeNotification

Notification that the system's audio route has changed.

AEAudioControllerDidRecreateGraphNotification

Notification that AEAudioController has shut down and re-initialized the audio graph.

This can happen in response to some unexpected system errors. Objects that use the graph directly (such as creating audio units) should re-initialise the audio units.

AEAudioControllerErrorOccurredNotification

Some asynchronous error occurred, such as when the user denies your app record access.

The userInfo dictionary of the notification will contain the AVAudioControllerErrorKey, an NSError.

NSString* const AEAudioControllerErrorKey

Keys to be used with notifications.

NSString* const AEAudioControllerErrorDomain

Errors.