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

AUGraphCountNodeConnections

Deprecated in Mac OS X v10.5. Instead, use AUGraphCountNodeInteractions.

OSStatus AUGraphCountNodeConnections(
   AUGraph inGraph,
   AUNode  inNode,
   UInt32  *outNumConnections
);

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

AUGraphGetConnectionInfo

Deprecated in Mac OS X v10.5. Instead, use AUGraphGetInteractionInfo.

OSStatus AUGraphGetConnectionInfo(
   AUGraph inGraph,
   UInt32  inConnectionIndex,
   AUNode  *outSourceNode,
   UInt32  *outSourceOutputNumber,
   AUNode  *outDestNode,
   UInt32  *outDestInputNumber
);

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

AUGraphGetNodeConnections

Deprecated in Mac OS X v10.5. Instead, use AUGraphGetNodeInteractions.

OSStatus AUGraphGetNodeConnections(
   AUGraph                 inGraph,
   AUNode                  inNode,
   AudioUnitNodeConnection *outConnections,
   UInt32                  *ioNumConnections
);

AUGraphGetNodeCount

The number of nodes in an audio processing graph.

OSStatus AUGraphGetNodeCount (
   AUGraph inGraph,
   UInt32  *outNumberOfNodes
);

AUGraphGetNodeInfo

Deprecated in Mac OS X v10.5. Instead, use AUGraphNodeInfo.

OSStatus AUGraphGetNodeInfo(
   AUGraph                     inGraph,
   AUNode                      inNode,
   struct ComponentDescription *outDescription,
   UInt32                      *outClassDataSize,
   void                        **outClassData,
   AudioUnit                   *outAudioUnit
);

AUGraphGetNodeInfoSubGraph

Gets the audio processing subgraph object represented by a node.

OSStatus AUGraphGetNodeInfoSubGraph(
   const AUGraph inGraph,
   AUNode        inNode,
   AUGraph       *outSubGraph);

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

AUGraphGetNumberOfConnections

Deprecated in Mac OS X v10.5. Instead, use AUGraphGetNumberOfInteractions.

OSStatus AUGraphGetNumberOfConnections(
   AUGraph inGraph,
   UInt32  *outNumConnections
);

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

AUGraphIsNodeSubGraph

Determines whether a node object represent an audio processing graph or an audio unit.

OSStatus AUGraphIsNodeSubGraph(
   const AUGraph inGraph,
   AUNode        inNode,
   Boolean       *outFlag);

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

AUGraphNewNode

Deprecated in Mac OS X v10.5. Instead, use AUGraphAddNode.

   OSStatus AUGraphNewNode(
   AUGraph                         inGraph,
   const AudioComponentDescription *inDescription,
   UInt32                          inClassDataSize,// reserved: must be zero
   const void                      *inClassData,
   AUNode                          *outNode
);

AUGraphNewNodeSubGraph

Creates a node object to represent a subgraph.

OSStatus AUGraphNewNodeSubGraph(
   AUGraph inGraph,
   AUNode  *outNode);

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

AUGraphRemoveRenderNotification

Deprecated in Mac OS X v10.5. Instead, use AUGraphRemoveRenderNotify.

OSStatus AUGraphRemoveRenderNotification(
   AUGraph inGraph,
   AudioUnitRenderCallback inCallback,
   void *inRefCon
);

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

AUGraphSetRenderNotification

Deprecated in Mac OS X v10.3. Instead, use AUGraphAddRenderNotify.

OSStatus AUGraphSetRenderNotification(
   AUGraph inGraph,
   AudioUnitRenderCallback inCallback,
   void *inRefCon
);

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 Mac OS X v10.5 and later.

Declared in AUGraph.h.

kAUNodeInteraction_InputCallback

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

Available in Mac OS X v10.5 and later.

Declared in AUGraph.h.

Result Codes

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

---