avaudio-engine-workflow

AVAudio Engine Workflow

Purpose

Guide AVAudioEngine graph design and repair. This skill owns audio-node ownership, graph construction, connection formats, typed AVFAudio buffer and format surfaces, taps, manual rendering, offline processing, Audio Unit hosting through AVAudioUnit, and real-time safety boundaries.

It is not the app audio-session workflow, not the AVFoundation capture or asset workflow, and not a low-level Core Audio C API repair workflow except where AVAudioEngine wraps the lower-level behavior.

When To Use

• Use this skill when code creates, connects, mutates, starts, stops, or repairs an AVAudioEngine graph.
• Use this skill for AVAudioPlayerNode, AVAudioInputNode, AVAudioOutputNode, AVAudioMixerNode, AVAudioSourceNode, AVAudioSinkNode, taps, AVAudioFormat, manual rendering, offline processing, AVAudioUnit, Audio Unit instantiation, and render-block safety.
• Use this skill when existing code crashes from unattached nodes, format mismatches, missing input or output hardware, illegal graph mutation, callback allocation, actor isolation mistakes, or UI work inside real-time audio paths.
• Recommend avfaudio-session-workflow when the primary problem is category, route, permission, interruption, or activation policy.
• Recommend coreaudio-modernization-repair-workflow when the primary problem is legacy AudioQueue, AudioUnit, AudioConverter, pointer, callback, or OSStatus code outside AVAudioEngine.

Single-Path Workflow

1. Classify the engine request:
   • playback graph
   • input capture or tap
   • processing chain or effects
   • source or sink node
   • manual rendering or offline processing
   • Audio Unit hosting
   • repair of an existing graph
2. Apply the Apple docs gate:
   • read current AVFAudio docs for the relevant engine, node, format, or rendering behavior
   • state the documented graph, format, or real-time behavior relied on
   • apply ../../shared/references/apple-media-type-ownership.md before introducing custom graph, buffer, format, or unit-hosting abstractions
3. Map the graph:
   • engine owner and lifetime
   • attached nodes
   • connection order
   • bus formats and conversion points
   • start, schedule, stop, and teardown lifecycle
   • real-time and non-real-time boundaries
4. Repair common failure modes:
   • node used before attach(_:)
   • exact format mismatch where no mixer or output conversion applies
   • input or output node used when hardware is unavailable
   • graph mutation that breaks mixer or channel-count assumptions
   • render callback that allocates, locks, logs, awaits, or touches UI
   • hand-rolled format or buffer structs replacing AVAudioFormat, AVAudioPCMBuffer, AVAudioFile, AVAudioConverter, or AudioStreamBasicDescription while still configuring Apple audio APIs
   • completion handlers that mutate engine state from an arbitrary thread without a clear hop
5. Return one recommendation with:
   • graph class
   • documented Apple behavior relied on
   • graph ownership and connection plan
   • format and rendering plan
   • repair findings
   • validation and handoff expectation