AVFoundation Audio

Configure AVAudioSession and construct AVAudioEngine node graphs for playback, recording, real-time DSP, and multi-track audio pipelines in iOS and iPadOS.

Audio Session Configuration
Interruption & Route Change Handling
AVAudioEngine Architecture
Live Microphone Capture & Taps
Common Mistakes
Review Checklist
References

Audio Session Configuration

AVAudioSession coordinates app audio with the system audio subsystem. Defer activation until playback or recording begins to avoid prematurely silencing background audio.

import AVFAudio

@MainActor
final class AudioSessionManager {
    static let shared = AudioSessionManager()

    func configurePlayback() throws {
        let session = AVAudioSession.sharedInstance()
        try session.setCategory(.playback, mode: .moviePlayback, options: [])
        try session.setActive(true)
    }

    func configureRecording() throws {
        let session = AVAudioSession.sharedInstance()
        try session.setCategory(
            .playAndRecord,
            mode: .measurement,
            options: [.defaultToSpeaker, .allowBluetoothHFP]
        )
        try session.setActive(true)
    }

    func deactivate() throws {
        try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
    }
}

Key Categories and Modes

.playback: Media playback that continues when the Ring/Silent switch is set to silent or screen locks.
.record: Pure recording without playback; silences background audio.
.playAndRecord: Bidirectional audio (VoIP, chat, audio recording while monitoring). Use .defaultToSpeaker to prevent routing audio only to receiver.
.ambient: Mixes with other audio apps; silenced by Ring/Silent switch.

Interruption & Route Change Handling

Always observe AVAudioSession.interruptionNotification and AVAudioSession.routeChangeNotification asynchronously using NotificationCenter async sequences.

import AVFAudio

actor AudioNotificationObserver {
    private var task: Task<Void, Never>?

    func startObserving(
        onInterruption: @Sendable @escaping (Bool) -> Void,
        onPauseForRouteLoss: @Sendable @escaping () -> Void
    ) {
        task = Task {
            for await notification in NotificationCenter.default.notifications(named: AVAudioSession.interruptionNotification) {
                guard let userInfo = notification.userInfo,
                      let typeValue = userInfo[AVAudioSessionInterruptionTypeKey] as? UInt,
                      let type = AVAudioSession.InterruptionType(rawValue: typeValue) else { continue }

                switch type {
                case .began:
                    onInterruption(true)
                case .ended:
                    let optionsValue = userInfo[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
                    let shouldResume = AVAudioSession.InterruptionOptions(rawValue: optionsValue).contains(.shouldResume)
                    onInterruption(!shouldResume)
                @unknown default:
                    break
                }
            }
        }
    }

    func stopObserving() {
        task?.cancel()
        task = nil
    }
}

Pause playback immediately when AVAudioSessionRouteChangeReasonKey indicates .oldDeviceUnavailable (e.g., headphones disconnected).

AVAudioEngine Architecture

AVAudioEngine coordinates a graph of AVAudioNode instances (player nodes, mixer nodes, effect nodes) connected together.

import AVFAudio

@MainActor
final class AudioEngineController {
    private let engine = AVAudioEngine()
    private let playerNode = AVAudioPlayerNode()

    func setupGraph(audioFileURL: URL) throws {
        let file = try AVAudioFile(forReading: audioFileURL)
        let format = file.processingFormat

        engine.attach(playerNode)
        engine.connect(playerNode, to: engine.mainMixerNode, format: format)

        try engine.start()

        playerNode.scheduleFile(file, at: nil) {
            // Playback completed
        }
        playerNode.play()
    }

    func stop() {
        playerNode.stop()
        engine.stop()
        engine.reset()
    }
}

Live Microphone Capture & Taps

To analyze or stream microphone PCM buffers, install an audio tap on the inputNode. Always remove previous taps before installing a new tap or tearing down.

import AVFAudio

final class MicrophoneTapManager: Sendable {
    private let engine = AVAudioEngine()

    func startTapping(bufferHandler: @escaping @Sendable (AVAudioPCMBuffer, AVAudioTime) -> Void) throws {
        let inputNode = engine.inputNode
        let format = inputNode.outputFormat(forBus: 0)

        inputNode.removeTap(onBus: 0)
        inputNode.installTap(onBus: 0, bufferSize: 1024, format: format) { buffer, time in
            bufferHandler(buffer, time)
        }

        engine.prepare()
        try engine.start()
    }

    func stopTapping() {
        engine.inputNode.removeTap(onBus: 0)
        engine.stop()
    }
}

Common Mistakes

Activating session at app launch: Causes unwanted background audio suspension. Deactivate or defer activation until the user requests audio.
Mismatching audio formats in engine connections: Connecting nodes with incompatible sample rates or channel counts without a mixer or format converter throws an exception.
Duplicate tap installation: Calling installTap(onBus:bufferSize:format:) on a bus that already has a tap installed crashes at runtime. Always call removeTap(onBus:) first.
Ignoring route loss: Failing to pause playback when headphones disconnect blares audio through built-in speakers.
Retaining AVAudioEngine across session resets: Handle AVAudioEngineConfigurationChange by rebuilding graph or restarting the engine.

Review Checklist

Does AVAudioSession configuration set appropriate category, mode, and options (.defaultToSpeaker, .allowBluetoothHFP)?
Is setActive(true) deferred until audio playback/recording actually starts?
Is setActive(false, options: .notifyOthersOnDeactivation) invoked when stopping to restore other audio apps?
Are route changes observed, specifically pausing on .oldDeviceUnavailable?
Are interruptions (.began and .ended with .shouldResume) handled gracefully?
Does microphone capture check and request AVAudioApplication.requestRecordPermission() prior to starting?
Are audio node taps properly removed prior to re-installing or stopping?

References

Audio Engine Patterns — Advanced mixer graphs, EQ, audio conversion, and unit tests.
AVFAudio Documentation — Official Apple AVFAudio API reference.
AVAudioSession Guide — Audio session lifecycle, routing, and categories.
AVAudioEngine Guide — Real-time audio node processing graph.