Audio Unit Processing Graph Services Reference

Framework
/System/Library/Frameworks/AudioToolbox.framework
Declared in
AUGraph.h

Overview

Audio Unit Processing Graph Services provide interfaces for representing a set of audio units, connections between their inputs and outputs, and callbacks used to provide inputs. It also enables the embedding of sub (or child) processing graphs within parent graphs to allow for a logical organization of parts of an overall signal chain.

An audio processing graph object (of type AUGraph) is a complete description of an audio signal processing network. Audio Unit Processing Graph Services may manage the instantiated audio units if the AUGraphOpen function is called.

An audio processing graph object may be introspected to get complete information about all of the audio units in the graph. The various node objects (each of type AUNode) in the graph, each representing an audio unit or a sub graph, may be added or removed, and the interactions between them modified.

A graph object’s state can be manipulated in both the rendering thread and in other threads. Consequently, any activities that affect the state of the graph are guarded with locks and a messaging model between any calling thread and the thread upon which the graph object’s output unit is called (the render thread).

A graph object will have a single head node––an output unit. The output unit is used to both start and stop the rendering operations of a graph, and is the dispatch point for the safe manipulation of the state of the graph while it is running.

Functions

AUGraphAddNode

Adds a node to an audio processing graph.

OSStatus AUGraphAddNode (
   AUGraph                         inGraph,
   const AudioComponentDescription *inDescription,
   AUNode                          *outNode
);
Parameters
inGraph

The AUGraph object that you are adding a node to.

inDescription

The AudioComponentDescription object used to find and open the audio unit that you are adding as a new node.

outNode

The newly added node.

Return Value

A result code.

Discussion

Creates a node in an audio processing graph, using the supplied AudioComponentDescription object to find and open the audio unit for the node.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphAddRenderNotify

Adds a render notification callback to an audio processing graph.

OSStatus AUGraphAddRenderNotify (
   AUGraph inGraph,
   AURenderCallback inCallback,
   void *inRefCon
);
Parameters
inGraph

inCallback

inRefCon

Return Value

Discussion

Adds a callback that the graph will call every time the graph renders. The callback will be called once before the graph’s render operation, and once after the render operation is complete.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphClearConnections

Clears all of the interactions in an audio unit processing graph.

OSStatus AUGraphClearConnections (
   AUGraph inGraph
);
Parameters
inGraph

Return Value

Discussion

This will clear all connections and callback interactions of the nodes of a graph.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphClose

Closes an audio unit processing graph.

OSStatus AUGraphClose (
   AUGraph inGraph
);
Parameters
inGraph

Return Value

Discussion

All AudioUnits are closed - leaving only its nodal representation.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphConnectNodeInput

Connects one node’s output to another node’s input.

OSStatus AUGraphConnectNodeInput (
   AUGraph inGraph,
   AUNode inSourceNode,
   UInt32 inSourceOutputNumber,
   AUNode inDestNode,
   UInt32 inDestInputNumber
);
Parameters
inGraph,

inSourceNode,

inSourceOutputNumber,

inDestNode,

inDestInputNumber

Return Value

A result code.

Discussion

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphCountNodeInteractions

Retrieves the number of interactions of an audio processing graph’s node.

OSStatus AUGraphCountNodeInteractions (
   AUGraph inGraph,
   AUNode inNode,
   UInt32 *outNumInteractions
);
Parameters
inGraph

inNode

outNumInteractions

Return Value

A result code.

Discussion

The number of node interactions currently being managed by the graph for the specified node.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphDisconnectNodeInput

Disconnects a node’s input.

OSStatus AUGraphDisconnectNodeInput (
   AUGraph inGraph,
   AUNode inDestNode,
   UInt32 inDestInputNumber
);
Parameters
inGraph

inDestNode

inDestInputNumber

Return Value

A result code.

Discussion

Use this function to disconnect a connection or a callback interaction.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphGetCPULoad

Obtains the short-term running average of the current CPU load of the audio processing graph.

OSStatus AUGraphGetCPULoad (
   AUGraph inGraph,
   Float32 *outAverageCPULoad
);
Parameters
inGraph

Return Value

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphGetIndNode

Gets the audio processing graph node at a given index.

OSStatus AUGraphGetIndNode (
   AUGraph inGraph,
   UInt32 inIndex,
   AUNode *outNode
);
Parameters
inGraph

The AUGraph object to get the node from.

inIndex

The index of the node to get.

outNode

On output, the node at the specified index.

Return Value

A result code.

Discussion

By using AUGraphGetNodeCount in conjunction with this call, you can iterate through the nodes of an audio processing graph.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphGetInteractionInfo

Retrieves information about a particular interaction in an audio processing graph.

OSStatus AUGraphGetInteractionInfo (
   AUGraph inGraph,
   UInt32 inInteractionIndex,
   AUNodeInteraction *outInteraction
);
Parameters
inGraph

inInteractionIndex

outInteraction

The interaction information at the specified index.

Return Value

A result code.

Discussion

An application can iterate through the interactions (as with the nodes) of a graph by retrieving the number of interactions, and then iterating an index starting from 0. The inInteractionIndex parameter is based on the outNumInteractions value and is only valid if no edits to the graph’s state have been made.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphGetMaxCPULoad

Obtains the maximum CPU load of an audio processing graph since this call was last made or since the graph was last started.

OSStatus AUGraphGetMaxCPULoad (
   AUGraph inGraph,
   Float32 *outMaxLoad
);
Parameters
inGraph

Return Value

A result code.

Discussion

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphGetNodeCount

The number of nodes in an audio processing graph.

OSStatus AUGraphGetNodeCount (
   AUGraph inGraph,
   UInt32  *outNumberOfNodes
);
Parameters
inGraph

the AUGraph object

outNumberOfNodes

the number of nodes

Return Value

A result code.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphGetNodeInteractions

Retrieves information about the interactions in an audio processing graph for a given node.

OSStatus AUGraphGetNodeInteractions (
   AUGraph           inGraph,
   AUNode            inNode,
   UInt32            *ioNumInteractions,
   AUNodeInteraction *outInteractions
);
Parameters
inGraph

inNode

ioNumInteractions

On input, specifies the number of interactions that can be returned. On output, the number of interactions returned.

outInteractions

The interactions that the specified node is involved in.

Return Value

A result code.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphGetNumberOfInteractions

Retrieves the number of interactions for an audio processing graph.

OSStatus AUGraphGetNumberOfInteractions (
   AUGraph inGraph,
   UInt32  *outNumInteractions
);
Parameters
inGraph

outNumInteractions

Return Value

A result code.

Discussion

The number of node interactions currently being managed by the graph.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphInitialize

Initializes an audio processing graph.

OSStatus AUGraphInitialize (
   AUGraph inGraph
);
Parameters
inGraph

Return Value

A result code.

Discussion

Calling this function calls the AudioUnitInitialize function on each opened node or audio unit that is involved in a interaction. If a node is not involved, it is initialized after it becomes involved in an interaction.

A graph must be opened before it can be initialized.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphIsInitialized

Determines whether an audio processing graph is initialized.

OSStatus AUGraphIsInitialized (
   AUGraph inGraph,
   Boolean *outIsInitialized
);
Parameters
inGraph

outIsInitialized

Return Value

A result code.

Discussion

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphIsOpen

Determines whether an audio processing graph is open.

OSStatus AUGraphIsOpen (
   AUGraph inGraph,
   Boolean *outIsOpen
);
Parameters
inGraph

outIsOpen

Return Value

A result code.

Discussion

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphIsRunning

Determines whether an audio processing graph running.

OSStatus AUGraphIsRunning (
   AUGraph inGraph,
   Boolean *outIsRunning
);
Parameters
inGraph

outIsRunning

Return Value

A result code.

Discussion

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphNodeInfo

Returns information about a node object.

OSStatus AUGraphNodeInfo (
   AUGraph                   inGraph,
   AUNode                    inNode,
   AudioComponentDescription *outDescription,
   AudioUnit                 *outAudioUnit
);
Parameters
inGraph

The AUGraph object.

inNode

The node to query.

outDescription

The component description that would describe the AudioUnit of this node.

outAudioUnit

the AudioUnit of this node

Return Value

A result code.

Discussion

You can pass NULL for any output parameter whose value you don’t care about.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphOpen

Opens an audio processing graph.

OSStatus AUGraphOpen (
   AUGraph inGraph
);
Parameters
inGraph

Return Value

A result code.

Discussion

Upon return from this function call, the audio units belonging to the graph are open but not initialized. Specifically, no resource allocation occurs.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphRemoveNode

Removes a node from an audio processing graph.

OSStatus AUGraphRemoveNode (
   AUGraph inGraph,
   AUNode inNode
);
Parameters
inGraph

The AUGraph object that you are removing a node from.

inNode

The node you want to remove.

Return Value

A result code.

Discussion

Nodes can be removed in any thread context. The output node of the graph cannot be removed while the graph is running.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphRemoveRenderNotify

Removes a notification callback from an audio processing graph.

OSStatus AUGraphRemoveRenderNotify (
   AUGraph inGraph,
   AURenderCallback inCallback,
   void *inRefCon
);
Parameters
inGraph

inCallback

inRefCon

Return Value

A result code.

Discussion

Removes a previously added render notification callback. You must provide both the callback and the context (in the inRefCon parameter) that was used previously to add the callback.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphSetNodeInputCallback

Sets an input callback function for a node.

OSStatus AUGraphSetNodeInputCallback (
   AUGraph inGraph,
   AUNode inDestNode,
   UInt32 inDestInputNumber,
   const AURenderCallbackStruct *inInputCallback
);
Parameters
inGraph,

inDestNode,

inDestInputNumber

inInputCallback

The callback that will provide input data to the node.

Return Value

A result code.

Discussion

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphStart

Starts an audio processing graph.

OSStatus AUGraphStart (
   AUGraph inGraph
);
Parameters
inGraph

Return Value

A result code.

Discussion

This function starts rendering by starting the head node of an audio processing graph. The graph must be initialized before it can be started.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphStop

Stops an audio processing graph.

OSStatus AUGraphStop (
   AUGraph inGraph
);
Parameters
inGraph

Return Value

A result code.

Discussion

This function stops rendering by stopping the head node of an audio processing graph.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphUninitialize

Uninitializes an audio processing graph.

OSStatus AUGraphUninitialize (
   AUGraph inGraph
);
Parameters
inGraph

Return Value

A result code.

Discussion

This function uninitializes the audio units that compose the audio processing graph.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraphUpdate

Updates the state of a running audio processing graph.

OSStatus AUGraphUpdate (
   AUGraph inGraph,
   Boolean *outIsUpdated
);
Parameters
inGraph

outIsUpdated

In input, pass NULL for synchronous (blocking) behavior, or non-NULL to have this function return immediately. On output, true if all of the edits were applied to the audio processing graph at the time of function return.

Return Value

A result code.

Discussion

Call this function to finalize changes to an audio processing graph’s state after making calls such as AUGraphConnectNodeInput.

Node connections and disconnections can be completely processed in the render notification callback of a graph, finalized by calling this function from within the callback. You can also remove nodes (apart from the head node) from within the render notification callback.

If this function returns the kAUGraphErr_CannotDoInCurrentContext result code, another thread was calling a function dependent on the graph’s existing state. When the competing thread completes its call, call this function again.

Audio processing graph updates are all or none. If this function encounters any errors while attempting to finalize graph events, then no pending changes are finalized.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

DisposeAUGraph

Disposes of an audio processing graph.

OSStatus DisposeAUGraph (
   AUGraph inGraph
);
Parameters
inGraph

the AUGraph object to be disposed

Return Value

A result code.

Discussion

Creates an AUGraph.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

NewAUGraph

Creates a new audio processing graph.

OSStatus NewAUGraph (
   AUGraph *outGraph
);
Parameters
outGraph

The new AUGraph object

Return Value

A result code.

Discussion

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

Data Types

AudioUnitNodeConnection

A connection between two node objects in an audio processing graph.

struct AudioUnitNodeConnection {
   AUNode sourceNode;
   UInt32 sourceOutputNumber;
   AUNode destNode;
   UInt32 destInputNumber;
};
typedef struct AudioUnitNodeConnection AudioUnitNodeConnection;
   typedef struct AudioUnitNodeConnection AUNodeConnection;
Fields
sourceNode

sourceOutputNumber

destNode

destInputNumber

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUGraph

An opaque type representing an audio processing graph.

typedef struct OpaqueAUGraph *AUGraph;
Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUNode

A member of an audio processing graph, associated with an audio unit.

typedef SInt32 AUNode;
Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUNodeInteraction

Describes the interaction between two node objects.

struct AUNodeInteraction {
   UInt32 nodeInteractionType;
   union {
      AUNodeConnection connection;
      AUNodeRenderCallback inputCallback;
   } nodeInteraction;
};
typedef struct AUNodeInteraction AUNodeInteraction;
Fields
nodeInteractionType

The interaction type.

nodeInteraction

A union providing information about a node interaction.

Discussion

This structure contains information about the interaction between two nodes (in the case of a connection), or the input to a node (in the case of a callback).

The type of the interaction is used to determine how to interpret the contents of the following union.

There may be other nodal interactions in the future, so NO ASSUMPTIONS should be made that these are the only two nodal interaction types; you must always check the nodeInteractionType and only act on those types you understand.

Arrays of these structs can be returned, the addition of new members to the nodeInteraction union will NOT change the size of this structure.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

AUNodeRenderCallback

A callback used to provide input to an audio unit.

struct AUNodeRenderCallback {
   AUNode destNode;
   AudioUnitElement destInputNumber;
   AURenderCallbackStruct cback;
};
typedef struct AUNodeRenderCallback AUNodeRenderCallback;
Fields
destNode

destInputNumber

cback

Discussion

Used to contain information when a callback is used to provide input to the specific node's specified input.

Availability
  • Available in iOS 2.0 and later.
Declared In
AUGraph.h

Constants

kAUNodeInteraction_Connection

The different types of node interactions.

enum {
   kAUNodeInteraction_Connection = 1,
   kAUNodeInteraction_InputCallback = 2
};
Constants
kAUNodeInteraction_Connection

connections between 2 audio units,

Available in iOS 2.0 and later.

Declared in AUGraph.h.

kAUNodeInteraction_InputCallback

input callbacks being registered to a single audio unit’s input bus.

Available in iOS 2.0 and later.

Declared in AUGraph.h.

Discussion

The term interaction is used as a general term to describe some interaction of a node. Currently, the interactions of a node that the graph manages are described below.

Result Codes

This table lists the result codes defined for Audio Unit Processing Graph Services.

Result CodeValueDescription
kAUGraphErr_NodeNotFound-10860

The specified node cannot be found.

Available in iOS 2.0 and later.

kAUGraphErr_InvalidConnection-10861

The attempted connection between two nodes cannot be made.

Available in iOS 2.0 and later.

kAUGraphErr_OutputNodeErr-10862

Audio processing graphs can only contain one output unit. This error is returned if trying to add a second output unit or if the graph’s output unit is removed while the graph is running.

Available in iOS 2.0 and later.

kAUGraphErr_CannotDoInCurrentContext-10863

To avoid spinning or waiting in the render thread (a bad idea!), many of the calls to AUGraph can return: kAUGraphErr_CannotDoInCurrentContext. This result is only generated when you call an AUGraph API from its render callback. It means that the lock that it required was held at that time, by another thread. If you see this result code, you can generally attempt the action again - typically the NEXT render cycle (so in the mean time the lock can be cleared), or you can delegate that call to another thread in your app. You should not spin or put-to-sleep the render thread.

Available in iOS 2.0 and later.

kAUGraphErr_InvalidAudioUnit-10864

Available in iOS 2.0 and later.