coreaudio-modernization-repair-workflow

Core Audio Modernization Repair Workflow

Purpose

Guide low-level Core Audio and Audio Toolbox repair. This skill owns the legacy and escape-hatch boundary: when to keep C APIs, when to isolate them, when to migrate toward AVFAudio, and how to make old callback, pointer, buffer, format, and OSStatus code understandable and safer without erasing the Apple type boundary.

It is not the default audio recommendation when AVFAudio covers the job.

When To Use

• Use this skill when code uses AudioUnit, AudioQueue, AudioConverter, AudioComponentDescription, AudioStreamBasicDescription, AudioBufferList, render callbacks, OSStatus, unsafe pointers, or archive-era Core Audio patterns.
• Use this skill when existing code has opaque OSStatus failures, pointer lifetime bugs, callback crashes, hand-rolled format structs, unsafe Swift bridging, or low-level audio code that might be replaceable with AVAudioEngine or AVAudioSession.
• Recommend avaudio-engine-workflow when the same job can be modeled as an AVAudioEngine graph or AVAudioUnit host.
• Recommend avfaudio-session-workflow when the real issue is audio-session policy, route, permission, or interruption behavior.

Single-Path Workflow

1. Classify the low-level audio request:
   • Audio Unit hosting or rendering
   • Audio Queue playback or recording
   • Audio Converter or format conversion
   • stream description or buffer layout
   • OSStatus diagnosis
   • callback, pointer, or lifetime repair
   • migration to AVFAudio
2. Apply the Apple docs gate:
   • read current Core Audio, Audio Toolbox, AVFAudio, or Core Audio Types docs first
   • use archive docs only to understand legacy code, not to override current guidance
   • state the documented behavior or legacy context relied on
   • apply ../../shared/references/apple-media-type-ownership.md before hiding Core Audio structures, pointers, callbacks, or OSStatus values behind generic Swift wrappers
3. Decide retention versus migration:
   • keep low-level code only when it exposes needed behavior that AVFAudio does not cover
   • wrap retained low-level code behind a narrow boundary with explicit ownership
   • migrate to AVAudioEngine, AVAudioUnit, AVAudioFile, AVAudioConverter, or AVAudioSession when current APIs cover the job
4. Repair common failure modes:
   • OSStatus logged as an integer with no operation or likely cause
   • callbacks retaining invalid object pointers
   • allocation, locking, logging, or actor hops in render callbacks
   • mismatched AudioStreamBasicDescription
   • unsafe AudioBufferList memory ownership
   • AudioComponentDescription, AudioStreamBasicDescription, AudioBufferList, AudioTimeStamp, or OSStatus replaced with generic structs or errors before the low-level operation remains diagnosable
   • duplicate low-level and AVFAudio codepaths left behind after modernization
5. Return one recommendation with:
   • low-level request class
   • documented behavior or archive context relied on
   • retention or migration decision
   • boundary and ownership plan
   • repair findings
   • validation and handoff expectation