AVFoundation 音频开发速查手册：iOS/macOS 音频会话、引擎与中断处理完整指南

axiom-avfoundation-ref by charleswiltgen/axiom

196 周安装量

716 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/charleswiltgen/axiom --skill axiom-avfoundation-ref

iOS 音频处理 Swift

🇨🇳中文介绍

AVFoundation 音频参考

快速参考

// AUDIO SESSION SETUP
import AVFoundation

try AVAudioSession.sharedInstance().setCategory(
    .playback,                              // or .playAndRecord, .ambient
    mode: .default,                         // or .voiceChat, .measurement
    options: [.mixWithOthers, .allowBluetooth]
)
try AVAudioSession.sharedInstance().setActive(true)

// AUDIO ENGINE PIPELINE
let engine = AVAudioEngine()
let player = AVAudioPlayerNode()
engine.attach(player)
engine.connect(player, to: engine.mainMixerNode, format: nil)
try engine.start()
player.scheduleFile(audioFile, at: nil)
player.play()

// INPUT PICKER (iOS 26+)
import AVKit
let picker = AVInputPickerInteraction()
picker.delegate = self
myButton.addInteraction(picker)
// In button action: picker.present()

// AIRPODS HIGH QUALITY (iOS 26+)
try AVAudioSession.sharedInstance().setCategory(
    .playAndRecord,
    options: [.bluetoothHighQualityRecording, .allowBluetoothA2DP]
)

AVAudioSession

类别

类别	使用场景	静音开关

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

文本转语音工具 - 使用 inference.sh CLI 实现高品质AI语音合成，支持多种模型和语言

7,800 周安装

对话音频生成工具：使用Dia TTS创建逼真多说话人对话，支持情感控制和节奏调整

7,700 周安装

Transloadit 云端媒体处理 | 视频编码、图像优化、音频转码、OCR 文档

7,700 周安装

AI音乐生成工具 - 使用inference.sh CLI快速生成歌曲、配乐和背景音乐

7,700 周安装

模式	使用场景
`.default`	通用音频
`.voiceChat`	VoIP，减少回声
`.videoChat`	FaceTime 风格
`.gameChat`	游戏内语音聊天
`.videoRecording`	相机录制
`.measurement`	平坦响应，无处理
`.moviePlayback`	视频播放
`.spokenAudio`	播客，有声读物

// 混音
.mixWithOthers          // 与其他应用同时播放
.duckOthers             // 播放时降低其他音频音量
.interruptSpokenAudioAndMixWithOthers  // 暂停播客，混入音乐

// 蓝牙
.allowBluetooth         // HFP（通话）
.allowBluetoothA2DP     // 高质量立体声
.bluetoothHighQualityRecording  // iOS 26+ AirPods 录音

// 路由
.defaultToSpeaker       // 路由到扬声器（非听筒）
.allowAirPlay           // 启用 AirPlay

NotificationCenter.default.addObserver(
    forName: AVAudioSession.interruptionNotification,
    object: nil,
    queue: .main
) { notification in
    guard let userInfo = notification.userInfo,
          let typeValue = userInfo[AVAudioSessionInterruptionTypeKey] as? UInt,
          let type = AVAudioSession.InterruptionType(rawValue: typeValue) else {
        return
    }

    switch type {
    case .began:
        // 暂停播放
        player.pause()

    case .ended:
        guard let optionsValue = userInfo[AVAudioSessionInterruptionOptionKey] as? UInt else { return }
        let options = AVAudioSession.InterruptionOptions(rawValue: optionsValue)
        if options.contains(.shouldResume) {
            player.play()
        }

    @unknown default:
        break
    }
}

NotificationCenter.default.addObserver(
    forName: AVAudioSession.routeChangeNotification,
    object: nil,
    queue: .main
) { notification in
    guard let userInfo = notification.userInfo,
          let reasonValue = userInfo[AVAudioSessionRouteChangeReasonKey] as? UInt,
          let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else {
        return
    }

    switch reason {
    case .oldDeviceUnavailable:
        // 耳机拔出 — 暂停播放
        player.pause()

    case .newDeviceAvailable:
        // 新设备连接
        break

    case .categoryChange:
        // 系统或其他应用更改了类别
        break

    default:
        break
    }
}

let engine = AVAudioEngine()

// 创建节点
let player = AVAudioPlayerNode()
let reverb = AVAudioUnitReverb()
reverb.loadFactoryPreset(.largeHall)
reverb.wetDryMix = 50

// 附加到引擎
engine.attach(player)
engine.attach(reverb)

// 连接：player → reverb → mixer → output
engine.connect(player, to: reverb, format: nil)
engine.connect(reverb, to: engine.mainMixerNode, format: nil)

// 启动
engine.prepare()
try engine.start()

// 播放文件
let url = Bundle.main.url(forResource: "audio", withExtension: "m4a")!
let file = try AVAudioFile(forReading: url)
player.scheduleFile(file, at: nil)
player.play()

节点	用途
`AVAudioPlayerNode`	播放音频文件/缓冲区
`AVAudioInputNode`	麦克风输入 (engine.inputNode)
`AVAudioOutputNode`	扬声器输出 (engine.outputNode)
`AVAudioMixerNode`	混合多个输入
`AVAudioUnitEQ`	均衡器
`AVAudioUnitReverb`	混响效果
`AVAudioUnitDelay`	延迟效果
`AVAudioUnitDistortion`	失真效果
`AVAudioUnitTimePitch`	时间拉伸 / 音高变换

let inputNode = engine.inputNode
let format = inputNode.outputFormat(forBus: 0)

inputNode.installTap(onBus: 0, bufferSize: 1024, format: format) { buffer, time in
    // 处理音频缓冲区
    guard let channelData = buffer.floatChannelData?[0] else { return }
    let frameLength = Int(buffer.frameLength)

    // 计算 RMS 电平
    var sum: Float = 0
    for i in 0..<frameLength {
        sum += channelData[i] * channelData[i]
    }
    let rms = sqrt(sum / Float(frameLength))
    let dB = 20 * log10(rms)

    DispatchQueue.main.async {
        self.levelMeter = dB
    }
}

// 完成后别忘了移除
inputNode.removeTap(onBus: 0)

// AVAudioEngine 麦克风输入始终为 44.1kHz/32-bit float
// 使用 AVAudioConverter 处理其他格式

let inputFormat = engine.inputNode.outputFormat(forBus: 0)
let outputFormat = AVAudioFormat(
    commonFormat: .pcmFormatInt16,
    sampleRate: 48000,
    channels: 1,
    interleaved: false
)!

let converter = AVAudioConverter(from: inputFormat, to: outputFormat)!

// 在监听器回调中：
let outputBuffer = AVAudioPCMBuffer(
    pcmFormat: outputFormat,
    frameCapacity: AVAudioFrameCount(outputFormat.sampleRate * 0.1)
)!

var error: NSError?
converter.convert(to: outputBuffer, error: &error) { inNumPackets, outStatus in
    outStatus.pointee = .haveData
    return inputBuffer
}

源	iOS 行为	备注
44.1 kHz	直通	CD 质量
48 kHz	直通	视频标准
96 kHz	直通	高解析度
192 kHz	直通	高解析度
DSD	不支持	使用 DoP 或转换

import AVKit

class RecordingViewController: UIViewController {
    let inputPicker = AVInputPickerInteraction()

    override func viewDidLoad() {
        super.viewDidLoad()

        // 首先配置音频会话
        try? AVAudioSession.sharedInstance().setCategory(.playAndRecord)
        try? AVAudioSession.sharedInstance().setActive(true)

        // 设置选择器
        inputPicker.delegate = self
        selectMicButton.addInteraction(inputPicker)
    }

    @IBAction func selectMicTapped(_ sender: UIButton) {
        inputPicker.present()
    }
}

extension RecordingViewController: AVInputPickerInteractionDelegate {
    // 根据需要实现委托方法
}

// 配置两个 AudioDataOutput
let foaOutput = AVCaptureAudioDataOutput()
foaOutput.spatialAudioChannelLayoutTag = kAudioChannelLayoutTag_HOA_ACN_SN3D  // 4 通道

let stereoOutput = AVCaptureAudioDataOutput()
stereoOutput.spatialAudioChannelLayoutTag = kAudioChannelLayoutTag_Stereo    // 2 通道

// 创建元数据生成器
let metadataGenerator = AVCaptureSpatialAudioMetadataSampleGenerator()

// 将 FOA 缓冲区提供给生成器
func captureOutput(_ output: AVCaptureOutput,
                   didOutput sampleBuffer: CMSampleBuffer,
                   from connection: AVCaptureConnection) {
    metadataGenerator.append(sampleBuffer)
    // 同时写入 FOA AssetWriterInput
}

// 录制停止时，获取元数据样本
let metadataSample = metadataGenerator.createMetadataSample()
// 写入元数据轨道

组件	用途
ASAF	Apple 空间音频格式 — 制作格式
APAC	Apple 位置音频编解码器 — 交付编解码器

import Cinematic

// 加载空间音频资源
let asset = AVURLAsset(url: spatialAudioURL)
let audioInfo = try await CNAssetSpatialAudioInfo(asset: asset)

// 配置混音参数
let intensity: Float = 0.5  // 0.0 到 1.0
let style = CNSpatialAudioRenderingStyle.cinematic

// 创建并应用音频混音
let audioMix = audioInfo.audioMix(
    effectIntensity: intensity,
    renderingStyle: style
)
playerItem.audioMix = audioMix

风格	效果
`.cinematic`	平衡的语音/环境音
`.studio`	增强语音清晰度
`.inFrame`	聚焦于可见说话者
+ 6 种提取模式	仅语音、仅环境音干声

// 1. 设置类别
try AVAudioSession.sharedInstance().setCategory(.playback)

// 2. 在 Info.plist 中启用后台模式
// <key>UIBackgroundModes</key>
// <array><string>audio</string></array>

// 3. 设置正在播放信息（推荐）
let nowPlayingInfo: [String: Any] = [
    MPMediaItemPropertyTitle: "歌曲标题",
    MPMediaItemPropertyArtist: "艺术家",
    MPNowPlayingInfoPropertyElapsedPlaybackTime: player.currentTime,
    MPMediaItemPropertyPlaybackDuration: duration
]
MPNowPlayingInfoCenter.default().nowPlayingInfo = nowPlayingInfo

🇺🇸English

AVFoundation Audio Reference

Quick Reference

// AUDIO SESSION SETUP
import AVFoundation

try AVAudioSession.sharedInstance().setCategory(
    .playback,                              // or .playAndRecord, .ambient
    mode: .default,                         // or .voiceChat, .measurement
    options: [.mixWithOthers, .allowBluetooth]
)
try AVAudioSession.sharedInstance().setActive(true)

// AUDIO ENGINE PIPELINE
let engine = AVAudioEngine()
let player = AVAudioPlayerNode()
engine.attach(player)
engine.connect(player, to: engine.mainMixerNode, format: nil)
try engine.start()
player.scheduleFile(audioFile, at: nil)
player.play()

// INPUT PICKER (iOS 26+)
import AVKit
let picker = AVInputPickerInteraction()
picker.delegate = self
myButton.addInteraction(picker)
// In button action: picker.present()

// AIRPODS HIGH QUALITY (iOS 26+)
try AVAudioSession.sharedInstance().setCategory(
    .playAndRecord,
    options: [.bluetoothHighQualityRecording, .allowBluetoothA2DP]
)

AVAudioSession

Category	Use Case	Silent Switch	Background
`.ambient`	Game sounds, not primary	Silences	No
`.soloAmbient`	Default, interrupts others	Silences	No
`.playback`	Music player, podcast	Ignores	Yes
`.record`	Voice recorder	—	Yes
`.playAndRecord`	VoIP, voice chat	Ignores	Yes

Modes

Mode	Use Case
`.default`	General audio
`.voiceChat`	VoIP, reduces echo
`.videoChat`	FaceTime-style
`.gameChat`	Voice chat in games
`.videoRecording`	Camera recording
`.measurement`	Flat response, no processing

Options

// Mixing
.mixWithOthers          // Play with other apps
.duckOthers             // Lower other audio while playing
.interruptSpokenAudioAndMixWithOthers  // Pause podcasts, mix music

// Bluetooth
.allowBluetooth         // HFP (calls)
.allowBluetoothA2DP     // High quality stereo
.bluetoothHighQualityRecording  // iOS 26+ AirPods recording

// Routing
.defaultToSpeaker       // Route to speaker (not receiver)
.allowAirPlay           // Enable AirPlay

Interruption Handling

NotificationCenter.default.addObserver(
    forName: AVAudioSession.interruptionNotification,
    object: nil,
    queue: .main
) { notification in
    guard let userInfo = notification.userInfo,
          let typeValue = userInfo[AVAudioSessionInterruptionTypeKey] as? UInt,
          let type = AVAudioSession.InterruptionType(rawValue: typeValue) else {
        return
    }

    switch type {
    case .began:
        // Pause playback
        player.pause()

    case .ended:
        guard let optionsValue = userInfo[AVAudioSessionInterruptionOptionKey] as? UInt else { return }
        let options = AVAudioSession.InterruptionOptions(rawValue: optionsValue)
        if options.contains(.shouldResume) {
            player.play()
        }

    @unknown default:
        break
    }
}

Route Change Handling

NotificationCenter.default.addObserver(
    forName: AVAudioSession.routeChangeNotification,
    object: nil,
    queue: .main
) { notification in
    guard let userInfo = notification.userInfo,
          let reasonValue = userInfo[AVAudioSessionRouteChangeReasonKey] as? UInt,
          let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else {
        return
    }

    switch reason {
    case .oldDeviceUnavailable:
        // Headphones unplugged — pause playback
        player.pause()

    case .newDeviceAvailable:
        // New device connected
        break

    case .categoryChange:
        // Category changed by system or another app
        break

    default:
        break
    }
}

AVAudioEngine

Basic Pipeline

let engine = AVAudioEngine()

// Create nodes
let player = AVAudioPlayerNode()
let reverb = AVAudioUnitReverb()
reverb.loadFactoryPreset(.largeHall)
reverb.wetDryMix = 50

// Attach to engine
engine.attach(player)
engine.attach(reverb)

// Connect: player → reverb → mixer → output
engine.connect(player, to: reverb, format: nil)
engine.connect(reverb, to: engine.mainMixerNode, format: nil)

// Start
engine.prepare()
try engine.start()

// Play file
let url = Bundle.main.url(forResource: "audio", withExtension: "m4a")!
let file = try AVAudioFile(forReading: url)
player.scheduleFile(file, at: nil)
player.play()

Node Types

Node	Purpose
`AVAudioPlayerNode`	Plays audio files/buffers
`AVAudioInputNode`	Mic input (engine.inputNode)
`AVAudioOutputNode`	Speaker output (engine.outputNode)
`AVAudioMixerNode`	Mix multiple inputs
`AVAudioUnitEQ`	Equalizer
`AVAudioUnitReverb`	Reverb effect

Installing Taps (Audio Analysis)

let inputNode = engine.inputNode
let format = inputNode.outputFormat(forBus: 0)

inputNode.installTap(onBus: 0, bufferSize: 1024, format: format) { buffer, time in
    // Process audio buffer
    guard let channelData = buffer.floatChannelData?[0] else { return }
    let frameLength = Int(buffer.frameLength)

    // Calculate RMS level
    var sum: Float = 0
    for i in 0..<frameLength {
        sum += channelData[i] * channelData[i]
    }
    let rms = sqrt(sum / Float(frameLength))
    let dB = 20 * log10(rms)

    DispatchQueue.main.async {
        self.levelMeter = dB
    }
}

// Don't forget to remove when done
inputNode.removeTap(onBus: 0)

Format Conversion

// AVAudioEngine mic input is always 44.1kHz/32-bit float
// Use AVAudioConverter for other formats

let inputFormat = engine.inputNode.outputFormat(forBus: 0)
let outputFormat = AVAudioFormat(
    commonFormat: .pcmFormatInt16,
    sampleRate: 48000,
    channels: 1,
    interleaved: false
)!

let converter = AVAudioConverter(from: inputFormat, to: outputFormat)!

// In tap callback:
let outputBuffer = AVAudioPCMBuffer(
    pcmFormat: outputFormat,
    frameCapacity: AVAudioFrameCount(outputFormat.sampleRate * 0.1)
)!

var error: NSError?
converter.convert(to: outputBuffer, error: &error) { inNumPackets, outStatus in
    outStatus.pointee = .haveData
    return inputBuffer
}

Bit-Perfect Audio / DAC Output

iOS Behavior

iOS provides bit-perfect output by default to USB DACs — no resampling occurs. The DAC receives the source sample rate directly.

// iOS automatically matches source sample rate to DAC
// No special configuration needed for bit-perfect output

let player = AVAudioPlayerNode()
// File at 96kHz → DAC receives 96kHz

Avoiding Resampling

// Check hardware sample rate
let hardwareSampleRate = AVAudioSession.sharedInstance().sampleRate

// Match your audio format to hardware when possible
let format = AVAudioFormat(
    standardFormatWithSampleRate: hardwareSampleRate,
    channels: 2
)

USB DAC Routing

// List available outputs
let currentRoute = AVAudioSession.sharedInstance().currentRoute
for output in currentRoute.outputs {
    print("Output: \(output.portName), Type: \(output.portType)")
    // USB DAC shows as .usbAudio
}

// Prefer USB output
try AVAudioSession.sharedInstance().setPreferredInput(usbPort)

Sample Rate Considerations

Source	iOS Behavior	Notes
44.1 kHz	Passthrough	CD quality
48 kHz	Passthrough	Video standard
96 kHz	Passthrough	Hi-res
192 kHz	Passthrough	Hi-res
DSD	Not supported	Use DoP or convert

iOS 26+ Input Selection

AVInputPickerInteraction

Native input device selection with live metering:

import AVKit

class RecordingViewController: UIViewController {
    let inputPicker = AVInputPickerInteraction()

    override func viewDidLoad() {
        super.viewDidLoad()

        // Configure audio session first
        try? AVAudioSession.sharedInstance().setCategory(.playAndRecord)
        try? AVAudioSession.sharedInstance().setActive(true)

        // Setup picker
        inputPicker.delegate = self
        selectMicButton.addInteraction(inputPicker)
    }

    @IBAction func selectMicTapped(_ sender: UIButton) {
        inputPicker.present()
    }
}

extension RecordingViewController: AVInputPickerInteractionDelegate {
    // Implement delegate methods as needed
}

Features:

Live sound level metering
Microphone mode selection
System remembers selection per app

iOS 26+ AirPods High Quality Recording

LAV-microphone equivalent quality for content creators:

// AVAudioSession approach
try AVAudioSession.sharedInstance().setCategory(
    .playAndRecord,
    options: [
        .bluetoothHighQualityRecording,  // New in iOS 26
        .allowBluetoothA2DP              // Fallback
    ]
)

// AVCaptureSession approach
let captureSession = AVCaptureSession()
captureSession.configuresApplicationAudioSessionForBluetoothHighQualityRecording = true

Notes:

Uses dedicated Bluetooth link optimized for AirPods
Falls back to HFP if device doesn't support HQ mode
Supports AirPods stem controls for start/stop recording

Spatial Audio Capture (iOS 26+)

First Order Ambisonics (FOA)

Record 3D spatial audio using device microphone array:

// With AVCaptureMovieFileOutput (simple)
let audioInput = AVCaptureDeviceInput(device: audioDevice)
audioInput.multichannelAudioMode = .firstOrderAmbisonics

// With AVAssetWriter (full control)
// Requires two AudioDataOutputs: FOA (4ch) + Stereo (2ch)

AVAssetWriter Spatial Audio Setup

// Configure two AudioDataOutputs
let foaOutput = AVCaptureAudioDataOutput()
foaOutput.spatialAudioChannelLayoutTag = kAudioChannelLayoutTag_HOA_ACN_SN3D  // 4 channels

let stereoOutput = AVCaptureAudioDataOutput()
stereoOutput.spatialAudioChannelLayoutTag = kAudioChannelLayoutTag_Stereo    // 2 channels

// Create metadata generator
let metadataGenerator = AVCaptureSpatialAudioMetadataSampleGenerator()

// Feed FOA buffers to generator
func captureOutput(_ output: AVCaptureOutput,
                   didOutput sampleBuffer: CMSampleBuffer,
                   from connection: AVCaptureConnection) {
    metadataGenerator.append(sampleBuffer)
    // Also write to FOA AssetWriterInput
}

// When recording stops, get metadata sample
let metadataSample = metadataGenerator.createMetadataSample()
// Write to metadata track

Output File Structure

Spatial audio files contain:

Stereo AAC track — Compatibility fallback
APAC track — Spatial audio (FOA)
Metadata track — Audio Mix tuning parameters

File formats: .mov, .mp4, .qta (QuickTime Audio, iOS 26+)

ASAF / APAC (Apple Spatial Audio)

Overview

Component	Purpose
ASAF	Apple Spatial Audio Format — production format
APAC	Apple Positional Audio Codec — delivery codec

APAC Capabilities

Bitrates: 64 kbps to 768 kbps
Supports: Channels, Objects, Higher Order Ambisonics, Dialogue, Binaural
Head-tracked rendering adaptive to listener position/orientation
Required for Apple Immersive Video

Playback

// Standard AVPlayer handles APAC automatically
let player = AVPlayer(url: spatialAudioURL)
player.play()

// Head tracking enabled automatically on AirPods

Platform Support

All Apple platforms except watchOS support APAC playback.

Audio Mix (Cinematic Framework)

Separate and remix speech vs ambient sounds in spatial recordings:

AVPlayer Integration

import Cinematic

// Load spatial audio asset
let asset = AVURLAsset(url: spatialAudioURL)
let audioInfo = try await CNAssetSpatialAudioInfo(asset: asset)

// Configure mix parameters
let intensity: Float = 0.5  // 0.0 to 1.0
let style = CNSpatialAudioRenderingStyle.cinematic

// Create and apply audio mix
let audioMix = audioInfo.audioMix(
    effectIntensity: intensity,
    renderingStyle: style
)
playerItem.audioMix = audioMix

Rendering Styles

Style	Effect
`.cinematic`	Balanced speech/ambient
`.studio`	Enhanced speech clarity
`.inFrame`	Focus on visible speakers
+ 6 extraction modes	Speech-only, ambient-only stems

AUAudioMix (Direct AudioUnit)

For apps not using AVPlayer:

// Input: 4 channels FOA
// Output: Separated speech + ambient

// Get tuning metadata from file
let audioInfo = try await CNAssetSpatialAudioInfo(asset: asset)
let remixMetadata = audioInfo.spatialAudioMixMetadata as CFData

// Apply to AudioUnit via AudioUnitSetProperty

Common Patterns

Background Audio Playback

// 1. Set category
try AVAudioSession.sharedInstance().setCategory(.playback)

// 2. Enable background mode in Info.plist
// <key>UIBackgroundModes</key>
// <array><string>audio</string></array>

// 3. Set Now Playing info (recommended)
let nowPlayingInfo: [String: Any] = [
    MPMediaItemPropertyTitle: "Song Title",
    MPMediaItemPropertyArtist: "Artist",
    MPNowPlayingInfoPropertyElapsedPlaybackTime: player.currentTime,
    MPMediaItemPropertyPlaybackDuration: duration
]
MPNowPlayingInfoCenter.default().nowPlayingInfo = nowPlayingInfo

Ducking Other Audio

try AVAudioSession.sharedInstance().setCategory(
    .playback,
    options: .duckOthers
)

// When done, restore others
try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)

Bluetooth Device Handling

// Allow all Bluetooth
try AVAudioSession.sharedInstance().setCategory(
    .playAndRecord,
    options: [.allowBluetooth, .allowBluetoothA2DP]
)

// Check current Bluetooth route
let route = AVAudioSession.sharedInstance().currentRoute
let hasBluetoothOutput = route.outputs.contains {
    $0.portType == .bluetoothA2DP || $0.portType == .bluetoothHFP
}

Anti-Patterns

Wrong Category

// WRONG — music player using ambient (silenced by switch)
try AVAudioSession.sharedInstance().setCategory(.ambient)

// CORRECT — music needs .playback
try AVAudioSession.sharedInstance().setCategory(.playback)

Missing Interruption Handling

// WRONG — no interruption observer
// Audio stops on phone call and never resumes

// CORRECT — always handle interruptions
NotificationCenter.default.addObserver(
    forName: AVAudioSession.interruptionNotification,
    // ... handle began/ended
)

Tap Memory Leaks

// WRONG — tap installed, never removed
engine.inputNode.installTap(onBus: 0, bufferSize: 1024, format: format) { ... }

// CORRECT — remove tap when done
deinit {
    engine.inputNode.removeTap(onBus: 0)
}

Format Mismatch Crashes

// WRONG — connecting nodes with incompatible formats
engine.connect(playerNode, to: mixerNode, format: wrongFormat)  // Crash!

// CORRECT — use nil for automatic format negotiation, or match exactly
engine.connect(playerNode, to: mixerNode, format: nil)

Forgetting to Activate Session

// WRONG — configure but don't activate
try AVAudioSession.sharedInstance().setCategory(.playback)
// Audio doesn't work!

// CORRECT — always activate
try AVAudioSession.sharedInstance().setCategory(.playback)
try AVAudioSession.sharedInstance().setActive(true)

Resources

WWDC : 2025-251, 2025-403, 2019-510

Docs : /avfoundation, /avkit, /cinematic

Targets: iOS 12+ (core), iOS 26+ (spatial features) Frameworks: AVFoundation, AVKit, Cinematic (iOS 26+) History: See git log for changes

Weekly Installs

132

Repository

charleswiltgen/axiom

GitHub Stars

601

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode115

codex108

gemini-cli106

claude-code105

cursor104

github-copilot94

`.ambient`	游戏音效，非主要音频	静音	否
`.soloAmbient`	默认，中断其他音频	静音	否
`.playback`	音乐播放器，播客	忽略	是
`.record`	语音录音	—	是
`.playAndRecord`	VoIP，语音聊天	忽略	是
`.multiRoute`	DJ 应用，多路输出	忽略	是

AVFoundation 音频开发速查手册：iOS/macOS 音频会话、引擎与中断处理完整指南

🇨🇳中文介绍

AVFoundation 音频参考

快速参考

AVAudioSession

类别

相关 Skills

模式

选项

中断处理

路由变更处理

AVAudioEngine

基础管线

节点类型

安装监听器（音频分析）

格式转换

无损音频 / DAC 输出

iOS 行为

避免重采样

USB DAC 路由

采样率注意事项

iOS 26+ 输入选择

AVInputPickerInteraction

iOS 26+ AirPods 高质量录音

空间音频采集 (iOS 26+)

一阶 Ambisonics (FOA)

AVAssetWriter 空间音频设置

输出文件结构

ASAF / APAC (Apple 空间音频)

概述

APAC 能力

播放

平台支持

音频混音（Cinematic 框架）

AVPlayer 集成

渲染风格

AUAudioMix（直接 AudioUnit）

常见模式

后台音频播放

压低其他音频

蓝牙设备处理

反模式

错误的类别

缺少中断处理

监听器内存泄漏

格式不匹配导致崩溃

忘记激活会话

资源

🇺🇸English

AVFoundation Audio Reference

Quick Reference

AVAudioSession

Categories

Modes

Options

Interruption Handling

Route Change Handling

AVAudioEngine

Basic Pipeline

Node Types

Installing Taps (Audio Analysis)

Format Conversion

Bit-Perfect Audio / DAC Output

iOS Behavior

Avoiding Resampling

USB DAC Routing

Sample Rate Considerations

iOS 26+ Input Selection

AVInputPickerInteraction

iOS 26+ AirPods High Quality Recording

Spatial Audio Capture (iOS 26+)

First Order Ambisonics (FOA)

AVAssetWriter Spatial Audio Setup

Output File Structure

ASAF / APAC (Apple Spatial Audio)

Overview

APAC Capabilities

Playback

Platform Support

Audio Mix (Cinematic Framework)