Audio Unit Processing Graph Services Reference

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
);

AUGraphAddRenderNotify

Adds a render notification callback to an audio processing graph.

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

AUGraphClearConnections

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

OSStatus AUGraphClearConnections (
   AUGraph inGraph
);

AUGraphClose

Closes an audio unit processing graph.

OSStatus AUGraphClose (
   AUGraph inGraph
);

AUGraphConnectNodeInput

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

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

AUGraphCountNodeInteractions

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

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

AUGraphDisconnectNodeInput

Disconnects a node’s input.

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

AUGraphGetCPULoad

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

OSStatus AUGraphGetCPULoad (
   AUGraph inGraph,
   Float32 *outAverageCPULoad
);

AUGraphGetIndNode

Gets the audio processing graph node at a given index.

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

AUGraphGetInteractionInfo

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

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

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
);

AUGraphGetNodeCount

The number of nodes in an audio processing graph.

OSStatus AUGraphGetNodeCount (
   AUGraph inGraph,
   UInt32  *outNumberOfNodes
);

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
);

AUGraphGetNumberOfInteractions

Retrieves the number of interactions for an audio processing graph.

OSStatus AUGraphGetNumberOfInteractions (
   AUGraph inGraph,
   UInt32  *outNumInteractions
);

AUGraphInitialize

Initializes an audio processing graph.

OSStatus AUGraphInitialize (
   AUGraph inGraph
);

AUGraphIsInitialized

Determines whether an audio processing graph is initialized.

OSStatus AUGraphIsInitialized (
   AUGraph inGraph,
   Boolean *outIsInitialized
);

AUGraphIsOpen

Determines whether an audio processing graph is open.

OSStatus AUGraphIsOpen (
   AUGraph inGraph,
   Boolean *outIsOpen
);

AUGraphIsRunning

Determines whether an audio processing graph running.

OSStatus AUGraphIsRunning (
   AUGraph inGraph,
   Boolean *outIsRunning
);

AUGraphNodeInfo

Returns information about a node object.

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

AUGraphOpen

Opens an audio processing graph.

OSStatus AUGraphOpen (
   AUGraph inGraph
);

AUGraphRemoveNode

Removes a node from an audio processing graph.

OSStatus AUGraphRemoveNode (
   AUGraph inGraph,
   AUNode inNode
);

AUGraphRemoveRenderNotify

Removes a notification callback from an audio processing graph.

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

AUGraphSetNodeInputCallback

Sets an input callback function for a node.

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

AUGraphStart

Starts an audio processing graph.

OSStatus AUGraphStart (
   AUGraph inGraph
);

AUGraphStop

Stops an audio processing graph.

OSStatus AUGraphStop (
   AUGraph inGraph
);

AUGraphUninitialize

Uninitializes an audio processing graph.

OSStatus AUGraphUninitialize (
   AUGraph inGraph
);

AUGraphUpdate

Updates the state of a running audio processing graph.

OSStatus AUGraphUpdate (
   AUGraph inGraph,
   Boolean *outIsUpdated
);

DisposeAUGraph

Disposes of an audio processing graph.

OSStatus DisposeAUGraph (
   AUGraph inGraph
);

NewAUGraph

Creates a new audio processing graph.

OSStatus NewAUGraph (
   AUGraph *outGraph
);

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

AUGraph

An opaque type representing an audio processing graph.

typedef struct OpaqueAUGraph *AUGraph;

AUNode

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

typedef SInt32 AUNode;

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.

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

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.

Result Codes

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