Audio Event Graph

The Audio Event Graph is an FMOD-style visual editor for authoring complex sound events. Each .audiograph file defines one sound event as a node graph — sources, filters, effects, and routing all connected visually. At runtime, the graph maps directly to a miniaudio processing pipeline.

The Audio Event Graph uses the gs_graphcanvas framework with a DataFlowGraph topology. Nodes evaluate in topological order with dirty-propagation — only nodes affected by a change are re-evaluated.

Contents

• Opening the Editor
• How It Works
• Node Catalog
• Phase Lifecycle
• Using Variables
• Extending with Custom Nodes
• Runtime API
• See Also

Opening the Editor

Open the Audio Event Graph editor from the O3DE Editor menu: GS Tools > Audio Event Graph Editor.

Each graph is a standalone .audiograph file — use File > New to create one, or File > Open to load an existing graph. Multiple graphs can be open simultaneously in separate tabs.

How It Works

Audio Event Graphs use a data-flow model. Connections carry AudioRoute values — handles that represent a point in the miniaudio processing chain. The signal flows left to right:

1. Entry nodes gate which phase is active (Start, Loop, or Finish)
2. Source nodes create sound instances and output an AudioRoute
3. Filter and effect nodes process the audio and pass it along
4. Routing nodes (If/Switch) direct the signal based on conditions or variables
5. The Output node wires the final AudioRoute to a mixing bus

Variables can be set from gameplay code at any time, causing affected nodes to re-evaluate without restarting the entire graph.

Node Catalog

Entry Nodes (Phase Gates)

Entry nodes output a gate signal. Downstream nodes only produce audio when their entry gate is active.

Source Nodes

Filter Nodes

All filter nodes take an audio_in input and produce an audio_out output. Filter parameters (cutoff frequency, Q factor, gain) are configurable per-node or bindable to variables.

Effect Nodes

Routing Nodes

The built-in gs_graphcanvas IfNode and SwitchNode work with AudioRoute values. Use them for conditional audio paths based on game state variables (e.g., play different sounds based on surface type or weather).

Terminal Node

Every graph needs exactly one Output node.

Phase Lifecycle

Audio Event Graphs support a three-phase lifecycle for structured sound playback:

1. Start — Initial playback. The Aud_StartNode gate is active. One-shot intro sounds play here.
2. Loop — Repeating section. The Aud_LoopNode gate is active. Ambient loops and sustained sounds live here.
3. Finish — Outro/tail. The Aud_FinishNode gate is active. Fade-outs and release tails play here.

Phases transition automatically: Start plays once, then Loop repeats (if looping is enabled), then Finish plays when FinishAudioGraph() is called. Not all phases are required — a simple one-shot sound only needs a Start node.

Using Variables

Variables let gameplay code control sound behavior at runtime. Common uses:

• Filter parameters — Bind a filter’s cutoff frequency to a variable, then adjust it from code (e.g., underwater muffling)
• Routing conditions — Use a variable as the condition for an If/Switch node to select different sound paths
• Source selection — Gate different source nodes based on game state

Declare variables in the Variable Panel, then either bind them to input slots (right-click > Convert to Reference) or use Get/Set variable nodes.

At runtime, set variables via the Audio Manager API:

AudioManagerRequestBus::Broadcast(&AudioManagerRequests::SetAudioGraphVariable, instanceId, "underwater", 0.8f);

Setting a variable marks dependent nodes dirty and re-evaluates only the affected portion of the graph.

Extending with Custom Nodes

To add a custom audio node:

1. Create a class inheriting from BaseNode and IDataFlowNode
2. Register it with GS_AUTO_REGISTER_NODE_FOR(MyAudioNode, "audiograph")
3. Implement Process(GraphExecutionContext& context)
4. Follow the empty any pattern for inactive outputs:

void MyAudioNode::Process(GraphExecutionContext& context)
{
    auto inputAny = context.GetInputValueAny(this, "audio_in");
    if (inputAny.empty())
    {
        context.SetOutputValueAny(this, "audio_out", AZStd::any{});  // CRITICAL: truly empty
        return;
    }
    // Process audio...
    context.SetOutputValue(this, "audio_out", outputRoute);
}

The empty any pattern ensures that inactive paths don’t mask valid audio from other connections in multi-input slots.

For full details on node creation, see gs_graphcanvas Nodes.

Runtime API

Audio Event Graphs are played through the Audio Manager component. Key methods:

See the Audio Manager documentation for the full API reference.

See Also

• gs_graphcanvas Framework — The underlying framework
• Audio Manager — Runtime audio management and playback API
• Audio Events — Simple event-based sound playback (non-graph)
• Mixing & Effects — Mixing buses and effects chains