avfaudio-session-workflow

AVFAudio Session Workflow

Purpose

Guide Apple app audio-session design and repair. This skill owns the app-level audio intent boundary: what the app tells the system it wants to do with audio, when it activates that intent, how it responds to interruption and route changes, how it preserves typed AVFAudio policy surfaces, and how it explains failures.

It is not the audio-engine graph workflow, not the AVFoundation media-pipeline workflow, not the Core Media timing workflow, and not the Xcode execution workflow.

When To Use

• Use this skill when configuring or repairing AVAudioSession, AVAudioApplication, AVAudioApplication.requestRecordPermission, recording permission, categories, modes, options, AVAudioSession.RouteSharingPolicy, activation, deactivation, interruptions, route changes, Bluetooth, AirPlay, speaker routing, or capture-session audio-session behavior.
• Use this skill when existing audio code plays from the wrong route, fails silently, captures silence, interrupts other audio incorrectly, fails around calls, ignores headphones disconnects, or logs vague audio errors.
• Recommend avaudio-engine-workflow when the primary issue is an AVAudioEngine graph, node connection, tap, render callback, manual rendering, or format conversion.
• Recommend avfoundation-media-pipeline-workflow when the primary issue is capture, playback, media assets, readers, writers, export, or sample-buffer append policy.
• Recommend coremedia-timing-samplebuffer-workflow when the primary issue is timestamps, timebases, CMSampleBuffer, or media synchronization.
• Recommend xcode-build-run-workflow or xcode-testing-workflow when the next step is build, run, entitlement, Info.plist, simulator, device, or test execution.

Single-Path Workflow

1. Classify the audio-session request:
   • playback-only behavior
   • recording or play-and-record behavior
   • capture-session audio interaction
   • route, Bluetooth, AirPlay, or speaker behavior
   • interruption or route-change handling
   • permission or privacy gate
   • repair of an existing implementation
2. Apply the Apple docs gate:
   • read current AVFAudio or AVFoundation documentation first
   • use archive material only for legacy migration context
   • state the documented behavior relied on before recommending design or repair
   • apply ../../shared/references/apple-media-type-ownership.md before introducing string-backed audio policy, route, category, mode, or permission models
   • stop if current docs and code disagree in a way that changes the recommendation
3. Choose the app-audio policy:
   • category, mode, route-sharing policy, and options
   • activation and deactivation point
   • permission request and denial behavior
   • interruption and route-change observers
   • capture-session automatic audio-session configuration stance
4. Repair common failure modes:
   • missing microphone usage description or permission path
   • category, mode, route, permission, or output policy modeled as free-form strings instead of AVAudioSession and AVAudioApplication types
   • using overrideOutputAudioPort when defaultToSpeaker is the durable intent
   • leaving other apps interrupted after deactivation instead of using notifyOthersOnDeactivation when appropriate
   • treating denied permission as a hardware failure
   • ignoring headphones disconnect privacy expectations
   • allowing AVCaptureSession to mutate shared audio-session state unexpectedly
5. Return one recommendation with:
   • request class
   • documented Apple behavior relied on
   • chosen category, mode, options, and activation lifecycle
   • permission, route, and interruption plan
   • repair findings
   • one execution or testing handoff when runtime validation is required