将AVAudioUnitSampler用作Audio Unit v3扩展时出现声音失真问题

我之前在做类似的AUv3扩展时也踩过这个坑——直接返回AVAudioUnitSampler的底层auAudioUnit确实会导致GarageBand这类宿主里声音失真，核心原因是高层封装的AVAudioUnitSampler和AUv3扩展的生命周期、格式适配逻辑不兼容。下面是几个必须调整的关键点，亲测有效：

1. 用自定义AUAudioUnit子类封装AVAudioUnitSampler #

不要直接把sampler.auAudioUnit暴露给宿主，而是创建一个自定义的AUAudioUnit子类，把AVAudioUnitSampler作为内部音频节点。这样你能完全掌控AU的生命周期、格式处理和渲染逻辑，避免宿主与高层组件的适配冲突。

示例代码：

class CustomSamplerAU: AUAudioUnit {
    private let sampler: AVAudioUnitSampler
    private var inputBus: AUAudioUnitBus!
    private var outputBus: AUAudioUnitBus!

    override init(componentDescription: AudioComponentDescription, options: AudioComponentInstantiationOptions = []) throws {
        self.sampler = try AVAudioUnitSampler()
        super.init(componentDescription: componentDescription, options: options)
        
        // 初始化默认音频格式（后续会被宿主动态更新）
        let defaultFormat = AVAudioFormat(standardFormatWithSampleRate: 44100, channels: 2)!
        inputBus = AUAudioUnitBus(format: defaultFormat)
        outputBus = AUAudioUnitBus(format: defaultFormat)
        
        addInputBus(inputBus)
        addOutputBus(outputBus)
        
        // 建立内部音频路由：AU输入 → Sampler → AU输出
        try sampler.auAudioUnit.inputBusses[0].connect(to: inputBus, format: defaultFormat)
        try outputBus.connect(to: sampler.auAudioUnit.outputBusses[0], format: defaultFormat)
    }

    // 转发最大渲染帧数设置给内部Sampler
    override var maximumFramesToRender: AUAudioFrameCount {
        get { sampler.auAudioUnit.maximumFramesToRender }
        set { sampler.auAudioUnit.maximumFramesToRender = newValue }
    }

    // 管理资源分配/释放的生命周期
    override func allocateRenderResources() throws {
        try super.allocateRenderResources()
        try sampler.auAudioUnit.allocateRenderResources()
    }

    override func deallocateRenderResources() {
        sampler.auAudioUnit.deallocateRenderResources()
        super.deallocateRenderResources()
    }

    // 委托渲染逻辑给内部Sampler
    override func render(_ actionFlags: UnsafeMutablePointer<AudioUnitRenderActionFlags>, timestamp: UnsafePointer<AudioTimeStamp>, frameCount: AUAudioFrameCount, inputBusNumber: Int, inputData: UnsafeMutablePointer<AudioBufferList>, outputBusNumber: Int, outputData: UnsafeMutablePointer<AudioBufferList>) throws {
        try sampler.auAudioUnit.render(actionFlags, timestamp: timestamp, frameCount: frameCount, inputBusNumber: inputBusNumber, inputData: inputData, outputBusNumber: outputBusNumber, outputData: outputData)
    }

    // 线程安全的采样加载方法
    func loadSoundBank(at url: URL) throws {
        try sampler.loadSoundBankInstrument(at: url, program: 0, bankMSB: 0, bankLSB: 0)
    }
}

然后在你的AudioUnitViewController中返回这个自定义AU：

public func createAudioUnit(with componentDescription: AudioComponentDescription) throws -> AUAudioUnit {
    let customAU = try CustomSamplerAU(componentDescription: componentDescription)
    
    // 在AU的专用调度队列加载采样，避免线程冲突
    customAU.auScheduleTask { [weak customAU] in
        guard let customAU = customAU else { return }
        do {
            guard let soundBankURL = Bundle.main.url(forResource: "YourSoundBank", withExtension: "sf2") else {
                fatalError("Sound bank not found in bundle")
            }
            try customAU.loadSoundBank(at: soundBankURL)
        } catch {
            print("Failed to load sound bank: \(error.localizedDescription)")
        }
    }
    
    return customAU
}

2. 确保音频格式与宿主完全匹配 #

宿主（如GarageBand）会动态设置音频格式（采样率、通道数等），你的AU必须正确响应格式变化。在自定义AU中重写格式相关方法，确保输入输出格式与宿主同步：

extension CustomSamplerAU {
    override func format(for bus: AUAudioUnitBus) -> AVAudioFormat {
        if bus == inputBus {
            return sampler.auAudioUnit.inputBusses[0].format
        } else {
            return sampler.auAudioUnit.outputBusses[0].format
        }
    }

    override func setFormat(_ format: AVAudioFormat, for bus: AUAudioUnitBus) throws {
        try super.setFormat(format, for: bus)
        if bus == inputBus {
            try sampler.auAudioUnit.setFormat(format, for: sampler.auAudioUnit.inputBusses[0])
        } else {
            try sampler.auAudioUnit.setFormat(format, for: sampler.auAudioUnit.outputBusses[0])
        }
    }
}

3. 线程安全地加载采样资源 #

AVAudioUnitSampler的加载操作（如加载音色库）绝对不能在主线程执行，否则会阻塞音频渲染线程，导致失真、卡顿。上面的示例中使用auScheduleTask方法，它会把任务放到AU的专用调度队列执行，确保线程安全。

4. 调整增益避免信号削波 #

失真的常见原因是音频信号过载（音量超过0dB）。你可以给自定义AU添加音量控制，限制输出信号的强度：

extension CustomSamplerAU {
    var volume: Float {
        get { sampler.volume }
        set { sampler.volume = max(0.0, min(newValue, 1.0)) } // 限制在0-1之间，防止削波
    }
}

你可以在ViewController中添加UI控件来调整这个参数，或者默认设置一个安全值（比如0.7），避免初始音量过高导致失真。

内容的提问来源于stack exchange，提问作者Pavel Alexeev