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

Inputs

• request: optional free-text engine task.
• graph_goal: optional goal such as playback, record, tap, process, source-node, sink-node, manual-rendering, offline-processing, audio-unit, or repair.
• platform_context: optional platform emphasis such as ios, macos, or mixed-apple.
• Defaults:
  • docs-first guidance always applies
  • prefer Apple and Swift media types unless ../../shared/references/apple-media-type-ownership.md identifies a concrete escape hatch
  • prefer AVAudioEngine and AVAudioUnit surfaces before lower-level callback APIs when they honestly fit
  • keep real-time render paths free of actor hops, locks, allocation, logging, and UI work

Outputs

• status
  • success: an engine design or repair path is ready
  • handoff: another Apple Dev skill owns the next step
  • blocked: graph ownership, format, or runtime evidence is too unclear
• path_type
  • primary: the recommendation uses current AVFAudio surfaces
  • fallback: the recommendation requires lower-level Core Audio analysis
• output
  • resolved engine request class
  • documented Apple behavior relied on
  • graph ownership and node connection plan
  • format and callback-safety findings
  • repair steps
  • validation and handoff expectation

Guards and Stop Conditions

• Do not hide engine ownership behind a broad audio manager unless one owner must coordinate multiple independent graphs or lifetimes.
• Do not replace AVAudioEngine, AVAudioNode, AVAudioFormat, AVAudioPCMBuffer, AVAudioFile, AVAudioConverter, or AVAudioUnit with custom wrappers or generic structs unless the Apple type boundary remains inspectable.
• Do not claim audio graph, route, latency, underrun, or callback safety is verified without runtime evidence.
• Do not put Swift concurrency, logging, allocation, blocking I/O, locks, or UI work in real-time render callbacks.
• Do not silently migrate low-level Core Audio code to AVAudioEngine when the existing code depends on behavior AVAudioEngine does not expose.
• Stop with blocked when the graph cannot be reconstructed from the code or the failure requires live hardware evidence.

Fallbacks and Handoffs

• Recommend avfaudio-session-workflow for app-level audio intent, permission, route, interruption, or activation policy.
• Recommend coreaudio-modernization-repair-workflow for legacy Core Audio, Audio Toolbox, or OSStatus work.
• Recommend coremedia-timing-samplebuffer-workflow for timestamp or sample-buffer synchronization problems.
• Recommend xcode-build-run-workflow for build, run, entitlements, device setup, and runtime diagnostics.
• Recommend xcode-testing-workflow for test design, repeatable engine checks, or regression coverage.
• Recommend explore-apple-swift-docs when more docs lookup is the next honest step.

Customization

Use references/customization-flow.md.

scripts/customization_config.py exists to preserve the repo-wide customization-file contract, but this workflow defines no runtime-enforced knobs.

References

Workflow References

• references/engine-graph-and-repair.md
• references/realtime-rendering-safety.md
• references/customization-flow.md

Support References

• Use ../../shared/references/apple-media-type-ownership.md for the shared Apple media type and framework-selection contract.
• Recommend references/snippets/apple-xcode-project-core.md when the user needs reusable Xcode-project baseline policy for apps that host audio engines.

Script Inventory

• scripts/customization_config.py