AEAudioController.h

Go to the documentation of this file.

//
// AEAudioController.h
// The Amazing Audio Engine
//
// Created by Michael Tyson on 25/11/2011.
//
// This software is provided 'as-is', without any express or implied
// warranty. In no event will the authors be held liable for any damages
// arising from the use of this software.
//
// Permission is granted to anyone to use this software for any purpose,
// including commercial applications, and to alter it and redistribute it
// freely, subject to the following restrictions:
//
// 1. The origin of this software must not be misrepresented; you must not
// claim that you wrote the original software. If you use this software
// in a product, an acknowledgment in the product documentation would be
// appreciated but is not required.
//
// 2. Altered source versions must be plainly marked as such, and must not be
// misrepresented as being the original software.
//
// 3. This notice may not be removed or altered from any source distribution.
//

#ifdef __cplusplus
extern "C" {
#endif

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

@class AEAudioController;

#pragma mark - Notifications and constants

extern NSString * const AEAudioControllerSessionInterruptionBeganNotification;
extern NSString * const AEAudioControllerSessionInterruptionEndedNotification;
extern NSString * const AEAudioControllerSessionRouteChangeNotification;
extern NSString * const AEAudioControllerDidRecreateGraphNotification;
extern NSString * const AEAudioControllerErrorOccurredNotification;
 
extern NSString * const AEAudioControllerErrorKey;

extern NSString * const AEAudioControllerErrorDomain;
enum {
 AEAudioControllerErrorInputAccessDenied
};
 
typedef enum {
 AEInputModeFixedAudioFormat,
 AEInputModeVariableAudioFormat
} AEInputMode;

#pragma mark - Callbacks and protocols

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

typedef AEAudioRenderCallback AEAudioControllerRenderCallback; // Temporary alias

@protocol AEAudioPlayable <NSObject>

@property (nonatomic, readonly) AEAudioRenderCallback renderCallback;

@optional

- (void)setupWithAudioController:(AEAudioController *)audioController;

- (void)teardown;

@property (nonatomic, readonly) float volume;

@property (nonatomic, readonly) float pan;

/*
 * Whether channel is currently playing
 *
 * If this is NO, then the track will be silenced and no further render callbacks
 * will be performed until set to YES again.
 *
 * Changes are tracked by Key-Value Observing, so be sure to send KVO notifications
 * when the value changes (or use a readwrite property).
 */
@property (nonatomic, readonly) BOOL channelIsPlaying;

/*
 * Whether channel is muted
 *
 * If YES, track will be silenced, but render callbacks will continue to be performed.
 * 
 * Changes are tracked by Key-Value Observing, so be sure to send KVO notifications
 * when the value changes (or use a readwrite property).
 */
@property (nonatomic, readonly) BOOL channelIsMuted;

/*
 * The audio format for this channel
 */
@property (nonatomic, readonly) AudioStreamBasicDescription audioDescription;

@end

static void * const AEAudioSourceInput = ((void*)0x01); 
static void * const AEAudioSourceMainOutput = ((void*)0x02); 

typedef void (*AEAudioReceiverCallback) (__unsafe_unretained id receiver,
 __unsafe_unretained AEAudioController *audioController,
 void *source,
 const AudioTimeStamp *time,
 UInt32 frames,
 AudioBufferList *audio);

typedef AEAudioReceiverCallback AEAudioControllerAudioCallback; // Temporary alias
 

@protocol AEAudioReceiver <NSObject>

@property (nonatomic, readonly) AEAudioReceiverCallback receiverCallback;
 
@optional
 
- (void)setupWithAudioController:(AEAudioController *)audioController;

- (void)teardown;

@end

typedef OSStatus (*AEAudioFilterProducer)(void *producerToken,
 AudioBufferList *audio,
 UInt32 *frames);

typedef AEAudioFilterProducer AEAudioControllerFilterProducer; // Temporary alias

typedef OSStatus (*AEAudioFilterCallback)(__unsafe_unretained id filter,
 __unsafe_unretained AEAudioController *audioController,
 AEAudioFilterProducer producer,
 void *producerToken,
 const AudioTimeStamp *time,
 UInt32 frames,
 AudioBufferList *audio);
 
typedef AEAudioFilterCallback AEAudioControllerFilterCallback; // Temporary alias

@protocol AEAudioFilter <NSObject>

@property (nonatomic, readonly) AEAudioFilterCallback filterCallback;
 
@optional
 
- (void)setupWithAudioController:(AEAudioController *)audioController;

- (void)teardown;

@end


typedef enum {
 AEAudioTimingContextInput,
 AEAudioTimingContextOutput
} AEAudioTimingContext;

typedef void (*AEAudioTimingCallback) (__unsafe_unretained id receiver,
 __unsafe_unretained AEAudioController *audioController,
 const AudioTimeStamp *time,
 UInt32 frames,
 AEAudioTimingContext context);
 
typedef AEAudioTimingCallback AEAudioControllerTimingCallback; // Temporary alias

@protocol AEAudioTimingReceiver <NSObject>

@property (nonatomic, readonly) AEAudioTimingCallback timingReceiverCallback;

@end


typedef struct _channel_group_t* AEChannelGroupRef;

@class AEAudioController;

#pragma mark -

typedef enum {
 AEAudioControllerOptionEnableInput = 1 << 0,
 AEAudioControllerOptionEnableOutput = 1 << 1,
 AEAudioControllerOptionUseVoiceProcessing = 1 << 2,
 AEAudioControllerOptionUseHardwareSampleRate = 1 << 3,
 AEAudioControllerOptionEnableBluetoothInput = 1 << 4,
 AEAudioControllerOptionAllowMixingWithOtherApps = 1 << 5,
 AEAudioControllerOptionDefaults =
 AEAudioControllerOptionEnableOutput | AEAudioControllerOptionAllowMixingWithOtherApps,
} AEAudioControllerOptions;

@interface AEAudioController : NSObject

#pragma mark - Setup and start/stop



+ (AudioStreamBasicDescription)interleaved16BitStereoAudioDescription;
// Soon: __deprecated_msg("use AEAudioStreamBasicDescriptionInterleaved16BitStereo instead");

+ (AudioStreamBasicDescription)nonInterleaved16BitStereoAudioDescription;
// Soon: __deprecated_msg("use AEAudioStreamBasicDescriptionNonInterleaved16BitStereo instead");

+ (AudioStreamBasicDescription)nonInterleavedFloatStereoAudioDescription;
// Soon: __deprecated_msg("use AEAudioStreamBasicDescriptionNonInterleavedFloatStereo instead");

+ (BOOL)voiceProcessingAvailable;

- (id)initWithAudioDescription:(AudioStreamBasicDescription)audioDescription;

- (id)initWithAudioDescription:(AudioStreamBasicDescription)audioDescription inputEnabled:(BOOL)enableInput;


- (id)initWithAudioDescription:(AudioStreamBasicDescription)audioDescription options:(AEAudioControllerOptions)options;

- (id)initWithAudioDescription:(AudioStreamBasicDescription)audioDescription inputEnabled:(BOOL)enableInput useVoiceProcessing:(BOOL)useVoiceProcessing __deprecated_msg("use initWithAudioDescription:options: instead");

- (id)initWithAudioDescription:(AudioStreamBasicDescription)audioDescription inputEnabled:(BOOL)enableInput useVoiceProcessing:(BOOL)useVoiceProcessing outputEnabled:(BOOL)enableOutput __deprecated_msg("use initWithAudioDescription:options: instead");

- (BOOL)start:(NSError**)error;

- (void)stop;

- (BOOL)setAudioDescription:(AudioStreamBasicDescription)audioDescription error:(NSError**)error;

- (BOOL)setInputEnabled:(BOOL)inputEnabled error:(NSError**)error;

- (BOOL)setOutputEnabled:(BOOL)outputEnabled error:(NSError**)error;

- (BOOL)setAudioDescription:(AudioStreamBasicDescription)audioDescription
 inputEnabled:(BOOL)inputEnabled
 outputEnabled:(BOOL)outputEnabled
 error:(NSError**)error;


#pragma mark - Channel and channel group management



- (void)addChannels:(NSArray*)channels;

- (void)addChannels:(NSArray*)channels toChannelGroup:(AEChannelGroupRef)group;

- (void)removeChannels:(NSArray*)channels;

- (void)removeChannels:(NSArray*)channels fromChannelGroup:(AEChannelGroupRef)group;

- (NSArray*)channels;

- (NSArray*)channelsInChannelGroup:(AEChannelGroupRef)group;

- (AEChannelGroupRef)createChannelGroup;

- (AEChannelGroupRef)createChannelGroupWithinChannelGroup:(AEChannelGroupRef)group;

- (void)removeChannelGroup:(AEChannelGroupRef)group;

- (NSArray*)topLevelChannelGroups;

- (NSArray*)channelGroupsInChannelGroup:(AEChannelGroupRef)group;

- (void)setVolume:(float)volume forChannelGroup:(AEChannelGroupRef)group;

- (float)volumeForChannelGroup:(AEChannelGroupRef)group;

- (void)setPan:(float)pan forChannelGroup:(AEChannelGroupRef)group;

- (float)panForChannelGroup:(AEChannelGroupRef)group;

- (void)setPlaying:(BOOL)playing forChannelGroup:(AEChannelGroupRef)group;

- (BOOL)channelGroupIsPlaying:(AEChannelGroupRef)group;

- (void)setMuted:(BOOL)muted forChannelGroup:(AEChannelGroupRef)group;

- (BOOL)channelGroupIsMuted:(AEChannelGroupRef)group;

#pragma mark - Filters



- (void)addFilter:(id<AEAudioFilter>)filter;

- (void)addFilter:(id<AEAudioFilter>)filter toChannel:(id<AEAudioPlayable>)channel;

- (void)addFilter:(id<AEAudioFilter>)filter toChannelGroup:(AEChannelGroupRef)group;

- (void)addInputFilter:(id<AEAudioFilter>)filter;

- (void)addInputFilter:(id<AEAudioFilter>)filter forChannels:(NSArray*)channels;

- (void)removeFilter:(id<AEAudioFilter>)filter;

- (void)removeFilter:(id<AEAudioFilter>)filter fromChannel:(id<AEAudioPlayable>)channel;

- (void)removeFilter:(id<AEAudioFilter>)filter fromChannelGroup:(AEChannelGroupRef)group;

- (void)removeInputFilter:(id<AEAudioFilter>)filter;

- (NSArray*)filters;

- (NSArray*)filtersForChannel:(id<AEAudioPlayable>)channel;

- (NSArray*)filtersForChannelGroup:(AEChannelGroupRef)group;

- (NSArray*)inputFilters;

#pragma mark - Output receivers



- (void)addOutputReceiver:(id<AEAudioReceiver>)receiver;

- (void)addOutputReceiver:(id<AEAudioReceiver>)receiver forChannel:(id<AEAudioPlayable>)channel;

- (void)addOutputReceiver:(id<AEAudioReceiver>)receiver forChannelGroup:(AEChannelGroupRef)group;

- (void)removeOutputReceiver:(id<AEAudioReceiver>)receiver;

- (void)removeOutputReceiver:(id<AEAudioReceiver>)receiver fromChannel:(id<AEAudioPlayable>)channel;

- (void)removeOutputReceiver:(id<AEAudioReceiver>)receiver fromChannelGroup:(AEChannelGroupRef)group;

- (NSArray*)outputReceivers;

- (NSArray*)outputReceiversForChannel:(id<AEAudioPlayable>)channel;

- (NSArray*)outputReceiversForChannelGroup:(AEChannelGroupRef)group;

#pragma mark - Input receivers



- (void)addInputReceiver:(id<AEAudioReceiver>)receiver;

- (void)addInputReceiver:(id<AEAudioReceiver>)receiver forChannels:(NSArray*)channels;

- (void)removeInputReceiver:(id<AEAudioReceiver>)receiver;

- (void)removeInputReceiver:(id<AEAudioReceiver>)receiver fromChannels:(NSArray*)channels;

- (NSArray*)inputReceivers;

#pragma mark - Timing receivers



- (void)addTimingReceiver:(id<AEAudioTimingReceiver>)receiver;

- (void)removeTimingReceiver:(id<AEAudioTimingReceiver>)receiver;

- (NSArray*)timingReceivers;

#pragma mark - Realtime/Main thread messaging system



@property (nonatomic, readonly, strong) AEMessageQueue *messageQueue;

- (void)performAsynchronousMessageExchangeWithBlock:(void (^)())block
 responseBlock:(void (^)())responseBlock;

- (BOOL)performSynchronousMessageExchangeWithBlock:(void (^)())block;

void AEAudioControllerSendAsynchronousMessageToMainThread(__unsafe_unretained AEAudioController *audioController,
 AEMessageQueueMessageHandler handler,
 void *userInfo,
 int userInfoLength);

- (void)beginMessageExchangeBlock;

- (void)endMessageExchangeBlock;

#pragma mark - Metering



- (void)outputAveragePowerLevel:(Float32*)averagePower peakHoldLevel:(Float32*)peakLevel;

- (void)outputAveragePowerLevels:(Float32*)averagePowers peakHoldLevels:(Float32*)peakLevels channelCount:(UInt32)count;

- (void)averagePowerLevel:(Float32*)averagePower peakHoldLevel:(Float32*)peakLevel forGroup:(AEChannelGroupRef)group;

- (void)averagePowerLevels:(Float32*)averagePowers peakHoldLevels:(Float32*)peakLevels forGroup:(AEChannelGroupRef)group channelCount:(UInt32)count;

- (void)inputAveragePowerLevel:(Float32*)averagePower peakHoldLevel:(Float32*)peakLevel;

- (void)inputAveragePowerLevels:(Float32*)averagePowers peakHoldLevels:(Float32*)peakLevels channelCount:(UInt32)count;

#pragma mark - Utilities



AudioStreamBasicDescription *AEAudioControllerAudioDescription(__unsafe_unretained AEAudioController *audioController);

AudioStreamBasicDescription *AEAudioControllerInputAudioDescription(__unsafe_unretained AEAudioController *audioController);

long AEConvertSecondsToFrames(__unsafe_unretained AEAudioController *audioController, NSTimeInterval seconds);

NSTimeInterval AEConvertFramesToSeconds(__unsafe_unretained AEAudioController *audioController, long frames);

BOOL AECurrentThreadIsAudioThread(void);

#pragma mark - Properties

#if TARGET_OS_IPHONE
@property (nonatomic, assign) NSString * audioSessionCategory;
#endif

#if TARGET_OS_IPHONE
@property (nonatomic, assign) BOOL allowMixingWithOtherApps;
#endif

#if TARGET_OS_IPHONE
@property (nonatomic, assign) BOOL useMeasurementMode;
#endif

#if TARGET_OS_IPHONE
@property (nonatomic, assign) BOOL avoidMeasurementModeForBuiltInSpeaker;
#endif

#if TARGET_OS_IPHONE
@property (nonatomic, assign) BOOL boostBuiltInMicGainInMeasurementMode;
#endif

@property (nonatomic, assign) BOOL muteOutput;

@property (nonatomic, assign) float masterOutputVolume;

#if TARGET_OS_IPHONE
@property (nonatomic, assign) BOOL enableBluetoothInput;
#endif

@property (nonatomic, readonly) BOOL inputGainAvailable;

@property (nonatomic, assign) float inputGain;

@property (nonatomic, assign) BOOL voiceProcessingEnabled;

@property (nonatomic, assign) BOOL voiceProcessingOnlyForSpeakerAndMicrophone;

@property (nonatomic, assign) AEInputMode inputMode;

@property (nonatomic, strong) NSArray *inputChannelSelection;

@property (nonatomic, assign) NSTimeInterval preferredBufferDuration;

@property (nonatomic, readonly) NSTimeInterval currentBufferDuration;

#if TARGET_OS_IPHONE
@property (nonatomic, readonly) NSTimeInterval inputLatency;
#endif

#if TARGET_OS_IPHONE
@property (nonatomic, readonly) NSTimeInterval outputLatency;
#endif

#if TARGET_OS_IPHONE
@property (nonatomic, assign) BOOL automaticLatencyManagement;
#endif

@property (nonatomic, readonly) BOOL running;

@property (nonatomic, readonly) BOOL playingThroughDeviceSpeaker;

@property (nonatomic, readonly) BOOL recordingThroughDeviceMicrophone;

@property (nonatomic, readonly) BOOL audioInputAvailable;

@property (nonatomic, readonly) BOOL inputEnabled;

@property (nonatomic, readonly) BOOL outputEnabled;

@property (nonatomic, readonly) int numberOfInputChannels;

@property (nonatomic, readonly) AudioStreamBasicDescription inputAudioDescription;

@property (nonatomic, readonly) AudioStreamBasicDescription audioDescription;

@property (nonatomic, readonly) AudioUnit audioUnit;

@property (nonatomic, readonly) AUGraph audioGraph;

#pragma mark - Timing

#if TARGET_OS_IPHONE
NSTimeInterval AEAudioControllerInputLatency(__unsafe_unretained AEAudioController *controller);
#endif

#if TARGET_OS_IPHONE
NSTimeInterval AEAudioControllerOutputLatency(__unsafe_unretained AEAudioController *controller);
#endif

AudioTimeStamp AEAudioControllerCurrentAudioTimestamp(__unsafe_unretained AEAudioController *controller);

@end

#ifdef __cplusplus
}
#endif