AudioToolbox---AUAudioUni

AudioToolbox

主要功能有录制或者播放音频，转换音频格式，分析音频流，配置音频会话
AudioToolbox 提供了用于记录，回放和流解析的接口，该框架为音频管理提供了丰富的接口

AUAudioUnit （音频单元）

AUAudioUnit类定义了主机接口（硬件）和音频单元的接口
主机可以提供用这个类实例化的版本3或者版本2的音频单元，并且在某种成都上控制音频单元在进程中实例化还是在单独的扩展进城中实例化。

版本3音频单元扩展可以在iOS，tvOS和MacOS上通过主机应用程序使用，并通过App Store分发。
----将组件通常作为一个 app 扩展包含音频组合在 plist 文件中，这个类必须实现AUAudioUnitFactory协议，这个类通常实例化一个AUAudioUnit子类使用。
~—通过调registerSubclass:asComponentDescription:name:version:方法将组建描述与AUAudioUnit子类联系起来

版本2音频单元应该继承AUAudioUnitV2Bridge类，版本2的音频单元组件注册方式如下
----将组件通常作为一个 app 扩展包含音频组合在 plist 文件中，这个类必须实现AudioComponentFactoryFunction协议，
~—通过调用AudioComponentRegister函数将组件描述与AudioComponentFactoryFunction关联起来

机器不用关心实例化AUAudioUnit子类，initWithComponentDescription:options:error:方法确保使用了正确的子类。

notice ：：当使用带有版本2音频单元的AUAudioUnit类时，或者使用带有版本3音频单元的C AudioComponent和AudioUnit api时，所有主要功能都在这两个api之间架起了桥梁。在适用时，本文档引用与每个版本3方法或属性等价的版本2 API。

initialization（初始化）

initWithComponentDescription 1

- (instancetype)initWithComponentDescription:(AudioComponentDescription)componentDescription error:(NSError * _Nullable *)outError;

同步初始化一个AudioUnit对象

initWithComponentDescription 2

- (instancetype)initWithComponentDescription:(AudioComponentDescription)componentDescription options:(AudioComponentInstantiationOptions)options error:(NSError * _Nullable *)outError;
同步初始化一个AudioUnit对象

instantiation（实例化）

+ (void)instantiateWithComponentDescription:(AudioComponentDescription)componentDescription options:(AudioComponentInstantiationOptions)options completionHandler:(void (^)(AUAudioUnit *audioUnit, NSError *error))completionHandler;
异步初始化一个AudioUnit对象。

function and peoperty（方法和属性）

音频单元的硬件信息

@property(readonly, nonatomic) AudioComponentDescription componentDescription;
用于创建音频单元的组件描述
@property(readonly, nonatomic) AudioComponent component;
创建音频单元需要的组件描述的组件

@property(readonly, copy, nonatomic) NSString *componentName;
audiounit 组件的名称

@property(readonly, nonatomic) uint32_t componentVersion;
audiounit 组件的版本

@property(readonly, copy, nonatomic) NSString *audioUnitName;
audiounit 的名称，来自组件的名称

@property(readonly, copy, nonatomic) NSString *manufacturerName;
音频单元的制造商名称，来自组件的名称

managing Render resources（音频渲染管理）

- (BOOL)allocateRenderResourcesAndReturnError:(NSError * _Nullable *)outError;
申请音频渲染所需要的资源

- (void)deallocateRenderResources;
释放音频渲染所需要的资源

- (void)reset;
重置音频渲染的状态 --主机应该在提供给音频单元的输入流中的不连续点(例如，在seeking向前或向后查找时)调用此函数。作为响应，音频单元应该清除延迟线、过滤器等。子类应该调用超类实现。

@property(readonly, nonatomic) BOOL renderResourcesAllocated;
确定audiounit 是否已经申请到资源

Querying Busses(查询音频输入输出)

@property(readonly, nonatomic) AUAudioUnitBusArray *inputBusses;
音频单元输入连接点的数组

@property(readonly, nonatomic) AUAudioUnitBusArray *outputBusses;
音频单元输出连接点的数组

Managing the Render Cycle(循环播放处理)

@property(readonly, nonatomic) AURenderBlock renderBlock;
主机申请音频单元渲染音频回调的块

@property(readonly, nonatomic) AUScheduleParameterBlock scheduleParameterBlock;
主机用来调用调整参数的块

@property(nonatomic) AUAudioFrameCount maximumFramesToRender;
音频单元一次可以呈现的最大帧数

- (NSInteger)tokenByAddingRenderObserver:(AURenderObserver)observer;
添加每个渲染周期的监听回调函数 在每个渲染周期都会回调

- (void)removeRenderObserver:(NSInteger)token;
移除添加的渲染周期回调

Querying paramenters(查询音频参数)

@property(readonly, nonatomic) BOOL allParameterValues;
所有的音频参数
- (NSArray<NSNumber *> *)parametersForOverviewWithCount:(NSInteger)count;
返回音频单元最主要的参数。–该方法允许主机查询音频单元的少量最重要参数，这些参数将显示在紧凑的通用视图中。

Managing midi events(管理乐器数字接口事件)

@property(readonly, getter=isMusicDeviceOrEffect, nonatomic) BOOL musicDeviceOrEffect;
指定音频接口是否响应 midi 事件

@property(readonly, nonatomic) NSInteger virtualMIDICableCount;
由音乐设备或效果实现的虚拟MIDI电缆的数量。
@property(readonly, nonatomic) AUScheduleMIDIEventBlock scheduleMIDIEventBlock;
midi 事件的回调函数

Managing Presets(音频单元预设管理)

@property(copy, nonatomic) NSDictionary<NSString *,id> *fullState;
一个音频单元属性和参数的可持续性快照，适合作为用户的预置保存

@property(copy, nonatomic) NSDictionary<NSString *,id> *fullStateForDocument;
音频单元的属性和参数的可持续性快照，适合保存在用户的文档中。

@property(readonly, copy, nonatomic) NSArray<AUAudioUnitPreset *> *factoryPresets;
音频单元的预置集合

@property(retain, nonatomic) AUAudioUnitPreset *currentPreset;
音频单元的最后预置

Optimizing Performance （性能优化）

@property(readonly, nonatomic) NSTimeInterval latency;
音频单元的延迟时间，以秒为单位

@property(readonly, nonatomic) NSTimeInterval tailTime;
音频单元的结束时间，以秒为单位

@property(nonatomic) NSInteger renderQuality;
渲染质量，在音频质量和 cpu 负载之间提供一种权衡

@property(nonatomic) BOOL shouldBypassEffect;
是否对音频单元直接由输入到输出，而无需任何处理

@property(readonly, nonatomic) BOOL canProcessInPlace;
音频单元是否可以实时处理，而不需要单独的输出到缓冲区

@property(getter=isRenderingOffline, nonatomic) BOOL renderingOffline;
是否可以离线渲染音频单元 ，本地音频应当使用次属性

channel Capabilities(通道功能)

@property(readonly, copy, nonatomic) NSArray<NSNumber *> *channelCapabilities;
输入和输出的通道值的集合。是 NSNumber 的集合，是输入输出的排列方式 输入–输出–输入–输出…

Host Callbacks （硬件回调）

@property(copy, nonatomic) AUHostMusicalContextBlock musicalContextBlock;
音乐上下文信息的回调，访问此属性的信息之前 应该将音频单元缓存到安全存储中

@property(copy, nonatomic) AUHostTransportStateBlock transportStateBlock;
主机传输状态信息 问此属性的信息之前 应该将音频单元缓存到安全存储中

@property(copy, nonatomic) NSString *contextName;
音频单元连接的硬件上下文信息，方便显示到音频单元的视图中

Input /Output Units(输入/输出单元)

@property(nonatomic, readonly) BOOL canPerformInput;
I/O设备是否可以执行输入

@property(nonatomic, readonly) BOOL canPerformOutput;
I/O设备是否可以执行输出

@property(nonatomic, getter=isInputEnabled) BOOL inputEnabled;
音频单元是否可以输入音频

@property(nonatomic, getter=isOutputEnabled) BOOL outputEnabled;
音频单元是否可以输出音频

@property(nonatomic, copy) AUInputHandler inputHandler;
音频单元输入可用时的回调

@property(nonatomic, copy) AURenderPullInputBlock outputProvider;
音频单元输出可用时的回调

@property(nonatomic, readonly) AudioObjectID deviceID;
获取I/O硬件设备ID。

- (BOOL)setDeviceID:(AudioObjectID)deviceID error:(NSError * _Nullable *)outError;
设置I/O硬件设备ID。

- (BOOL)startHardwareAndReturnError:(NSError * _Nullable *)outError;
启动音频硬件

- (void)stopHardware;
停止音频硬件

Audio Unit Implementtations（音频单元实现）

@property(nonatomic, readonly) AUInternalRenderBlock internalRenderBlock;
必须提供的渲染回调，为了实现渲染。

+ (void)registerSubclass:(Class)cls asComponentDescription:(AudioComponentDescription)componentDescription name:(NSString *)name version:(UInt32)version;
注册一个音频单元作为AUAudioUnit的子类，改方法动态的向音频组件注册一个AUAudioUnit子类，子类可以通过AudioComponentInstanceNew或者initWithComponentDescription:error: or initWithComponentDescription:options:error:实例化，也可以通过其它任何的音频单元 api实例化

- (BOOL)shouldChangeToFormat:(AVAudioFormat *)format forBus:(AUAudioUnitBus *)bus;
设置总线格式，可以重新设置音频单元的总线格式

- (void)setRenderResourcesAllocated:(BOOL)flag;
设置renderresourcesassigned属性的布尔值。

constants（常量）

AUEventSampleTime

AUEventSampleTimeImmediate = (AUEventSampleTime)0xffffffff00000000LL
默认音频采样速率

AUAudioUnitBusType

enum : NSInteger {
   AUAudioUnitBusTypeInput     = 1,
   AUAudioUnitBusTypeOutput    = 2
} AUAudioUnitBusType;

AUHostTransportStateFlags

enum : NSUInteger {
   AUHostTransportStateChanged          = 1,
   AUHostTransportStateMoving           = 2,
   AUHostTransportStateRecording        = 4,
   AUHostTransportStateCycling          = 8
} AUHostTransportStateFlags;

AURenderEventType

enum : uint8_t {
   AURenderEventParameter        = 1,
   AURenderEventParameterRamp    = 2,
   AURenderEventMIDI             = 8,
   AURenderEventMIDISysEx        = 9
} AURenderEventType;

AURenderPullInputBlock（音频单元渲染输入回调）

typedef AUAudioUnitStatus (^AURenderPullInputBlock)(AudioUnitRenderActionFlags *actionFlags, const AudioTimeStamp *timestamp, AUAudioFrameCount frameCount, NSInteger inputBusNumber, AudioBufferList *inputData);
回调提供有效的缓冲输入数据和mDataByteSize（mDataByteSize必须与frameCount一致），他也可以替换缓冲区的输入指针。

AURenderBlock （音频单元渲染回调）

typedef AUAudioUnitStatus (^AURenderBlock)(AudioUnitRenderActionFlags *actionFlags, const AudioTimeStamp *timestamp, AUAudioFrameCount frameCount, NSInteger outputBusNumber, AudioBufferList *outputData, AURenderPullInputBlock pullInputBlock);

AURenderObserver （音频单元渲染音频回调）

typedef void (^AURenderObserver)(AudioUnitRenderActionFlags actionFlags, const AudioTimeStamp *timestamp, AUAudioFrameCount frameCount, NSInteger outputBusNumber);
这个方法在基类AURenderBlock每个渲染周期之前和之后调用 观察者可以在使用kAudioUnitRenderAction_PreRender和kAudioUnitRenderAction_PostRender动作标志值之前和之后进行区分。

AUScheduleParameterBlock （参数更改回调）

typedef void (^AUScheduleParameterBlock)(AUEventSampleTime eventSampleTime, AUAudioFrameCount rampDurationSampleFrames, AUParameterAddress parameterAddress, AUValue value);
主要包括以下参数 1 eventSampleTime 2 rampDurationSampleFrames 3 parameterAddress

AUScheduleMIDIEventBlock（MIDI 事件回调）

typedef void (^AUScheduleMIDIEventBlock)(AUEventSampleTime eventSampleTime, uint8_t cable, NSInteger length, const uint8_t *midiBytes);
主要包括以下参数 1 eventSampleTime 2 cable 3 length 4 midiBytes

AUHostMusicalContextBlock （音频硬件特征回调）

typedef BOOL (^AUHostMusicalContextBlock)(double *currentTempo, double *timeSignatureNumerator, NSInteger *timeSignatureDenominator, double *currentBeatPosition, NSInteger *sampleOffsetToNextBeat, double *currentMeasureDownbeatPosition);
如果硬件 app通过musicalContextBlock属性将该块提供给音频单元，则可以在每个呈现周期的开始调用该块，以获取关于当前呈现周期的音乐上下文的信息。提供的任何参数都可能为null，以表明音频单元对该特定信息不感兴趣。

AUHostTransportStateBlock（音频硬件传输状态回调）

typedef BOOL (^AUHostTransportStateBlock)(AUHostTransportStateFlags *transportStateFlags, double *currentSamplePosition, double *cycleStartBeatPosition, double *cycleEndBeatPosition);
如果硬件 app通过transportStateBlock属性将该块提供给音频单元，则可以在每个呈现周期的开始调用该块，以获取关于当前呈现周期的音乐上下文的信息。提供的任何参数都可能为null，以表明音频单元对该特定信息不感兴趣。

AUInputHandler （I/O输入输出回调）

typedef void (^AUInputHandler)(AudioUnitRenderActionFlags *actionFlags, const AudioTimeStamp *timestamp, AUAudioFrameCount frameCount, NSInteger inputBusNumber);

AUInternalRenderBlock（I/O输入回调）

这个块是在子类中实现的，主机不应该使用它。

Instance Properties（实例属性）

@property(readonly, copy, nonatomic) NSString *audioUnitShortName;
音频短名

@property(copy, nonatomic) NSArray<NSNumber *> *channelMap;
音轨数组

@property(nonatomic, readonly) NSTimeInterval deviceInputLatency;
设备延迟输入时间

@property(nonatomic, readonly) NSTimeInterval deviceOutputLatency;
设备延迟输出时间

@property(nonatomic, readonly, getter=isRunning) BOOL running;
是否在运行

@property(nonatomic) NSInteger MIDIOutputBufferSizeHint;
MIDI输出缓冲区大小

@property(copy, nonatomic) AUMIDIOutputEventBlock MIDIOutputEventBlock;
MIDI 输出事件回调

@property(readonly, copy, nonatomic) NSArray<NSString *> *MIDIOutputNames;
MIDI设备输出名称

@property(nonatomic) AUMIDICIProfileChangedBlock profileChangedBlock;
配置文件改变回调

@property(readonly, nonatomic) BOOL providesUserInterface;
是否提供用户界面啊

@property(readonly, nonatomic) BOOL supportsMPE;
是否支持MPE封装

Instance Properties（实例方法）

- (BOOL)disableProfile:(MIDICIProfile *)profile cable:(uint8_t)cable onChannel:(MIDIChannelNumber)channel error:(NSError * _Nullable *)outError;
禁用配置文件，canble。。。

- (BOOL)enableProfile:(MIDICIProfile *)profile cable:(uint8_t)cable onChannel:(MIDIChannelNumber)channel error:(NSError * _Nullable *)outError;
启用配置文件，canble。。。

- (MIDICIProfileState *)profileStateForCable:(uint8_t)cable channel:(MIDIChannelNumber)channel;