Skip to content
macOSDeep Dive Published Updated 2 min readViews unavailable

AUv3 on macOS: Extension Discovery and Real-Time Audio Rendering

Trace an Audio Unit v3 component from extension registration to its render block, resource lifecycle, host parameters, and real-time safety requirements.

Audio Unit v3 (AUv3) gives macOS audio plug-ins an app-extension-based component model. A host discovers components through the extension’s AudioComponents metadata and asks the Audio Toolbox API to instantiate them. A version 3 implementation subclasses AUAudioUnit; its factory creates the component instance and exposes input/output buses, parameter state, and rendering behavior. This is distinct from Core Audio device discovery: an audio device is not itself an Audio Unit plug-in.

The component’s internalRenderBlock produces audio for a host render cycle. Hosts should obtain and cache the render block before entering the real-time path. Rendering can run under tight deadlines, so avoid allocation, locks, synchronous IPC, filesystem access, and UI work in that callback. Prepare buffers and other resources during allocateRenderResources(), then release them in deallocateRenderResources().

try audioUnit.allocateRenderResources()
let render = audioUnit.renderBlock

// Cache and invoke render from the host's real-time render path.
// Keep UI, disk access, and blocking synchronization outside that path.

audioUnit.deallocateRenderResources()

This is a lifecycle sketch, not a complete host. A production implementation must supply the action flags, timestamp, frame count, output bus, audio buffers, and input-pull behavior required by the render-block signature. Respect maximumFramesToRender and validate the actual stream format instead of assuming a fixed buffer size.

Keep control and render planes separate

Use the parameter tree and scheduled parameter events for time-aligned changes. A UI gesture should update control state or schedule an event; it should not take a mutex that the render thread may need. If the host requests the Audio Unit’s view controller asynchronously, switch to the main queue before attaching its view to the app’s hierarchy.

AUv3 supports several integration modes. Apple documents that hosts can instantiate version 2 or version 3 components through AUAudioUnit and can, to some extent, control whether an Audio Unit runs in-process or in a separate extension process. Do not build a security boundary or crash-isolation guarantee around an assumed process location; query and test the actual host/runtime behavior.

Validate the component in multiple hosts, at different sample rates and channel layouts, with variable frame counts, offline rendering, repeated allocate/deallocate cycles, parameter automation, and host termination during playback. Measure callback deadlines and audio glitches; a plug-in that renders correctly in a unit test can still underrun when integrated into the system audio graph.

Related:

Sources:

Comments