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