AVFoundation Audio

Playback, recording, and real-time processing on Apple platforms via AVFAudio. The deep reference — every category/mode/option, AVAudioPlayer, AVAudioRecorder, AVAudioEngine node graphs, AVSpeechSynthesizer, Now Playing / remote commands, recording settings, full examples — lives in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Dials

Set these explicitly at the start; they change what "correct" means.

1. ROLE — playback (.playback category; music/podcast/sound) · record (.record; capture only) · play-and-record (.playAndRecord; VoIP, voice memo, live monitoring). Picks the AVAudioSession category and what permissions/Info.plist keys you need.
2. ENGINE — simple (AVAudioPlayer/AVAudioRecorder — files, sound effects, basic record; default) · engine (AVAudioEngine node graph — effects, mixing, taps, real-time DSP). Don't reach for AVAudioEngine unless you need the graph.
3. BACKGROUND — foreground-only (default) · background (audio keeps playing when backgrounded — requires the audio UIBackgroundMode and an active non-mixing session like .playback).

When to use

Building or reviewing any code that plays audio, records from the mic, processes audio in real time, configures AVAudioSession, or wires lock-screen / Control Center playback. Not for AVPlayer-based video or HLS streaming, and not for MusicKit / Apple Music catalog playback.

Core rules