深入理解 AudioUnit(一) ~ IO Unit 结构和运行机制

OSStatus AudioUnitRender(
    AudioUnit inUnit,
    AudioUnitRenderActionFlags * __nullable ioActionFlags,
    const AudioTimeStamp * inTimeStamp,
    UInt32 inOutputBusNumber,
    UInt32 inNumberFrames,
    AudioBufferList *ioData
) API_AVAILABLE(macos(10.2), ios(2.0), watchos(2.0), tvos(9.0));

// 创建 IO Unit, 创建之前, 需要先创建 description, 这是创建 AudioUnit 的标准做法, 还有其他的办法来创建, 后面的部分会介绍
  AudioComponentDescription io_unit_description;
  // Output 表示 IO Unit
  io_unit_description.componentType = kAudioUnitType_Output;
  // subtype 我们设置为 RemoteIO, 如果要 AEC/ANS, 需要设置为 kAudioUnitSubType_VoiceProcessingIO
  io_unit_description.componentSubType = kAudioUnitSubType_RemoteIO;
  io_unit_description.componentManufacturer = kAudioUnitManufacturer_Apple;
  io_unit_description.componentFlags = 0;
  io_unit_description.componentFlagsMask = 0;

  // Obtain an audio unit instance given the description.
  // 通过 desc 获取 AudioUnit
  AudioComponent io_unit_ref =
      AudioComponentFindNext(nullptr, &io_unit_description);

  // 创建一个 Remote IO audio unit.
  if (CheckHasError(AudioComponentInstanceNew(io_unit_ref, &io_unit_),
                    "create io unit")) {
    io_unit_ = nullptr;
    return false;
  }

  // Enable input on the input scope of the input element.
  // 打开 Input Bus, 上面介绍到 Input Bus 和 Output Bus 是独立的, 这里我们只采集, 不播放, 所以只打开 Input Bus.
  UInt32 enable_input = 1;
  if (CheckHasError(AudioUnitSetProperty(io_unit_, kAudioOutputUnitProperty_EnableIO,
                                      kAudioUnitScope_Input, kInputBus, &enable_input,
                                      sizeof(enable_input)),
                 "set Property_EnableIO on inputbus : input scope")) {
    return false;
  }

  // Enable output on the output scope of the output element.
  // 因为只录制, 所以关闭 output
  UInt32 enable_output = 0;
  if (CheckHasError(AudioUnitSetProperty(io_unit_, kAudioOutputUnitProperty_EnableIO,
                                      kAudioUnitScope_Output, kOutputBus,
                                      &enable_output, sizeof(enable_output)),
                 "set Property_EnableIO on kOutputBus : output scope")) {
    return false;
  }

  // Disable AU buffer allocation for the recorder, we allocate our own.
  // TODO(henrika): not sure that it actually saves resource to make this call.
  UInt32 flag = 0;
  if (CheckHasError(AudioUnitSetProperty(
                                      io_unit_, kAudioUnitProperty_ShouldAllocateBuffer,
                                      kAudioUnitScope_Output, kInputBus, &flag, sizeof(flag)),
                 "set Property_ShouldAllocateBuffer on inputbus : output scope")) {
    return false;
  }

// 设置 AudioFormat, 这里 format 不影响理解, 细节暂不展开
// 注意我们设置采集的音频格式, 需要设置在 Input Bus 的 Output Scope, 如果有点困惑, 需要再看一前面的图和介绍.
  AudioStreamBasicDescription format = audio_format_;
  UInt32 size = sizeof(format);
  // Set the format on the output scope of the input element/bus.
  if (CheckHasError(AudioUnitSetProperty(io_unit_, kAudioUnitProperty_StreamFormat, kAudioUnitScope_Output, kInputBus, &format, size),
  "set Property_StreamFormat on inputbus : output scope")) {
    return false;
  }

//   Specify the callback to be called by the I/O thread to us when input audio is available. The recorded samples can then be obtained by calling the AudioUnitRender() method.

  // 这里设置 input callback, 该 callback 是个结构题, input_callback.inputProc 指定一个静态函数, AudioUnit 一旦采集到了数据, 就会调用这个函数通知我们, 然后我们使用 AudioUnitRender 从 IO Unit 中获取采集到的数据
  AURenderCallbackStruct input_callback;
  input_callback.inputProc = OnRecordedDataIsAvailable;
  input_callback.inputProcRefCon = this;
  if (CheckHasError(AudioUnitSetProperty(io_unit_, kAudioOutputUnitProperty_SetInputCallback, kAudioUnitScope_Output, kInputBus, &input_callback, sizeof(input_callback)),
                 "Set input callback on InputBus")) {
    return false;
  }

OSStatus OnRecordedDataIsAvailable(void * inRefCon,
                                   AudioUnitRenderActionFlags *ioActionFlags,
                                   const AudioTimeStamp *inTimeStamp,
                                   UInt32 inBusNumber,
                                   UInt32 inNumberFrames,
                                   AudioBufferList *ioData) {
  samples::AudioUnitRecorder *wrapper = static_cast<samples::AudioUnitRecorder *>(inRefCon);

  // 调用 AudioUnitRender 函数索要采集的数据
  // 第一个参数是我们的 ioUnit
  // 最后一个参数需注意, ioData 参数在这里 永远为 null, 所以不能把这个参数直接传给 AudioUnitRender, 需要我们自定义一个 AudioBufferList, 并非配好内存空间之后, 传给 AudioUnitRender, 它会将采集到的数据填充到该 list 中.
  // 其他参数我们直接透传即可
  OSStatus status = CheckErrorStatus(AudioUnitRender(wrapper->io_unit_, ioActionFlags, inTimeStamp, inBusNumber, inNumberFrames, &wrapper->audio_buffer_list_),
                          "AudioUnitRender call");
  if (status == noErr && wrapper->on_record_callback_) {
    // 回调给上层, 上层会把 raw audio data 保存到文件中.
    wrapper->on_record_callback_(wrapper->audio_buffer_list_);
  }
  return status;
}

...
  // 这里我们需要 enable output
  UInt32 enable_output = 1;
  if (CheckHasError(AudioUnitSetProperty(io_unit_, kAudioOutputUnitProperty_EnableIO, kAudioUnitScope_Output, kOutputBus,  &enable_output, sizeof(enable_output)),
                 "set Property_EnableIO on kOutputBus : output scope")) {
    return false;
  }
...
  // 设置我们传入的音频数据格式
  if (CheckHasError(AudioUnitSetProperty(io_unit_, kAudioUnitProperty_StreamFormat, kAudioUnitScope_Input, kOutputBus, &format, size), "set Property_StreamFormat on outputbus : input scope")) {
    return false;
  }
...

  // Render Callback 是 IO unit 的 outpus 主动回调我们, 索要即将要播放的数据, 我们在这个回调, 我们填充满 ioData, 这部分数据将会被播放出来.
  // 如果想静音的话, flag 需要设置为 kAudioUnitRenderAction_OutputIsSilence, 并且把 ioData 的数据全置为 0.
  AURenderCallbackStruct render_callback;
  render_callback.inputProc = OnAskingForMoreDataForPlayingRenderCallback;
  render_callback.inputProcRefCon = this;
  if (CheckHasError(AudioUnitSetProperty(io_unit_,
        kAudioUnitProperty_SetRenderCallback,
        kAudioUnitScope_Input,
        kOutputBus,
        &render_callback,
        sizeof(render_callback)),
    "set render callback on output bus: input scope")) {
    return false;
  }
...

OSStatus OnAskingForMoreDataForPlayingRenderCallback(
    void * inRefCon,
    AudioUnitRenderActionFlags *ioActionFlags,
    const AudioTimeStamp *inTimeStamp,
    UInt32 inBusNumber,
    UInt32 inNumberFrames,
    AudioBufferList *ioData) {
  AudioUnitPlayer *player = static_cast<AudioUnitPlayer*>(inRefCon);
  bool eof = false;
  // 这里内部实现会读取本地 PCM 数据, 并填充到 ioData->mBuffers[0].mData 里.
  player->on_ask_audio_buffer_callback_(ioData->mBuffers[0].mData,
        ioData->mBuffers[0].mDataByteSize, eof);
  if (eof) {
    //...
  }
  return noErr;
}