avaudio-engine-workflow

name	avaudio-engine-workflow
description	Guide AVAudioEngine implementation and repair for Apple apps and packages, including node graph ownership, AVAudioNode attachment, input and output nodes, player scheduling, taps, AVAudioFormat, format conversion, manual rendering, offline processing, AVAudioUnit hosting, and real-time audio callback safety. Use when fixing broken engine graphs or modernizing custom audio processing.

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