Audio Pro

1 - 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.

Time & Space Nodes

Character & Modulation Nodes

Utility Nodes

These are the same processors the base gem exposes as mix effects — one DSP, two authoring surfaces. Two mix effects have no node form: Binaural, because spatialization is automatic and per-source, and Pitch.

Structure 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.

Playing a Graph

There are three ways to reach a graph. They form an escalation ladder — most projects should use the last one.

AudioGraphPlayerComponent

The recommended surface. Drop it on an entity, point it at a graph, and it handles the rest.

It acquires lazily on the first Play or variable set, applies spatialization and looping, and holds its own handle — there is no acquire/release to write. Its per-entity bus offers Play, Finish, Stop, and SetVariable in float, int, bool and string forms.

With no Pro manager present it is inert and warns rather than failing.

Graph libraries

An AudioGraphLibrary (.agl) maps names to graphs, so gameplay code refers to "door_creak" rather than a path. Libraries are assigned to the Pro manager and can be added or removed at runtime.

Because .audiograph is a source-only file — no builder, no product asset — the library uses a custom picker that browses source files directly rather than the product catalog. This is the same approach ScriptCanvas uses for .scriptcanvas, and it is worth copying if you build an asset that references source files.

Current limitation: the picker stores an absolute source path.

Instance Lifecycle

This is the behaviour most likely to surprise you, so it is worth stating plainly.

There are two kinds of instance:

• Fire-and-forget — created by PlayGraph / PlayAudioGraph, destroyed when it stops.
• Owned — created by AcquireGraph / AcquireAudioGraph, and kept until you explicitly release it.

For an owned instance, Stop, Finish, a fade-out or a natural end all quiesce it to idle rather than destroying it. Sounds stop, pooled resources return, entry gates deactivate and the phase resets — but the instance, its variables and its spatial and loop configuration are all retained. Only ReleaseAudioGraph or manager shutdown actually destroys it.

The reason: a play → loop → end → replay cycle should keep its variables across calls. What you hear is identical to destruction; the difference is that replaying does not mean reconfiguring.

GetGraph(name) returns the live instance for a name, acquiring on first call. Repeat calls return the same id, and because owned instances persist, a handle normally stays valid for the lifetime of whatever is holding it.

All instance ids are 64-bit unsigned integers, and 0 means failure.

Runtime API

Everything below is on AudioGraphRequestBus — a GS_AudioPro bus, not the Audio Manager’s.

Named access: AddGraphLibrary, RemoveGraphLibrary, PlayGraph(name), AcquireGraph(name), GetGraph(name)

Raw path: PlayAudioGraph(assetPath), AcquireAudioGraph(assetPath)

Transport: FireAudioGraph(id), StopAudioGraph(id), StopAllAudioGraphs(), FinishAudioGraph(id), StopAudioGraphFade(id, fadeTime), ReleaseAudioGraph(id)

Variables: SetAudioGraphVariable (float), SetAudioGraphVariableInt, SetAudioGraphVariableBool, SetAudioGraphVariableString — each taking (instanceId, name, value)

Spatialization: SetAudioGraphEntity(id, entity), SetAudioGraphPosition(id, position), ClearAudioGraphSpatialization(id)

State: SetAudioGraphLooping(id, bool), IsAudioGraphActive(id)

Per-entity playback goes through AudioGraphPlayerRequestBus instead, addressed by entity id.

See Also

• Audio Pro — the rest of the premium tier, and the full bus map
• gs_graphcanvas Framework — the underlying framework
• Mix Effects — the same processors, authored on components
• Audio Events — simple event-based playback, in the free gem
• SFXR Profiles — what the Sfxr node consumes

2 - Score Arrangement

The Score Arrangement system provides multi-layer dynamic music for GS_Play projects. A ScoreArrangementTrack asset defines a musical score with configurable tempo, time signature, fade behavior, and multiple layers that can be enabled or disabled at runtime. This allows game music to adapt to gameplay state – adding or removing instrumental layers, changing intensity, or crossfading between sections.

Score tracks are assigned to the Pro Audio Manager and controlled through AudioScoreRequestBus. They are not on the base audio manager’s bus.

For usage guides and setup examples, see The Basics: GS_Audio.

Contents

• Data Model
• API Reference
• See Also

Data Model

ScoreArrangementTrack

A multi-layer musical score asset. Each track defines the musical structure and contains one or more layers that play simultaneously.

ScoreLayer

A single musical layer within a score arrangement. Each layer represents one track of audio (e.g. drums, bass, melody) that can be independently enabled or disabled.

TimeSignatures (Enum)

Supported musical time signatures for score arrangement tracks.

API Reference

Request Bus: AudioScoreRequestBus

Singleton bus – single address, single handler. Implemented by the Pro Audio Manager.

The adaptive-music loop is PlayScore once, then PlayTrack and StopTrack as game state changes. Layers stay in time with each other because they share the arrangement’s tempo and time signature – bringing a percussion layer in mid-bar does not knock it out of sync.

See Also

For conceptual overviews and usage guides:

• GS_Audio Overview – Top-level audio gem documentation
• The Basics: GS_Audio – Scripting-level usage guide

For component references:

• Audio Manager – Controls score playback via the request bus

Get GS_Audio

GS_Audio — Explore this gem on the product page and add it to your project.

3 - Geometric Acoustics

The base gem places sounds by direction and distance. Geometric acoustics adds the room: sound muffled by the geometry between it and the listener, and reverb derived from the space the listener is actually standing in rather than an effect an author dialled in.

Geometry is authored, not inferred. You mark up the acoustically significant parts of a level with volumes and shapes carrying material presets — you do not hand the simulation your render meshes.

Contents

• Turning It On
• Authoring Geometry
• Acoustic Materials
• Occlusion
• Reflections
• How It Stays Safe
• What This Does Not Do
• See Also

Turning It On

Geometric acoustics is off by default. It is enabled on the Pro manager’s settings, which are additive to the base project settings.

Authoring Geometry

Two components mark up a level. Both carry a material preset, plus a custom material for the Custom case.

The Shape variant is usually the faster path — a wall you have already blocked out with a Shape becomes acoustically real by adding one component.

Registration goes through a request bus that takes raw vertices rather than entities. That is deliberate: it is what will let streaming systems fold geometry in and out of the simulation without the acoustics layer knowing anything about entity lifetimes.

Acoustic Materials

Fifteen presets, plus Custom.

The soft-barrier group is the interesting one for designers. A curtain over a doorway does not block the sound behind it, it dulls it — which is the effect people usually reach for a low-pass filter to fake.

Occlusion

Each voice is simulated against the geometry between it and the listener, and muffled accordingly.

Volumetric is what gives partial occlusion at edges — a sound leaking around a doorframe rather than switching off as it passes behind the jamb. If occlusion feels binary and abrupt, this is the setting to change.

Occlusion ducks the direct signal.

Reflections

Reverb is derived from the geometry around the listener — one shared room, recomputed as the listener moves through the level. Reflection Mode has a PerSource value reserved for future work; it currently falls back to Listener.

Two behaviours are worth understanding because they are deliberate design choices, not side effects:

Reverb eases between rooms. Crossing a geometry boundary blends the reverb toward the new room over the Reflection Smooth Time rather than snapping. Set it to 0 if you want an instant change.

Reverb does not fade with distance. Each voice taps its raw source into a wet-only reverb, so the room stays constant across its whole volume while only the dry signal falls off with distance. This is what makes a large room sound like the same room from either end of it. The reverb send does taper at the far edge of a sound’s range — flat until three quarters of max distance, then eased to zero — so an event’s distance settings still bound how far it feeds the room.

How It Stays Safe

Worth knowing if you are budgeting for this system.

Reflections use a parametric reverb model — a handful of decay-time floats — rather than convolution. No impulse response ever crosses to the audio thread, and there is no ambisonic decode in the path.

The reflection simulation runs on a worker thread at up to 15 Hz, committing its results under a mutex. Occlusion and direct-path values are lock-free single-writer floats. Everything else stays on the main thread.

The practical consequence: enabling geometric acoustics adds a bounded, predictable cost rather than a per-sound one that scales alarmingly.

What This Does Not Do

State these to yourself before evaluating the result — each is a deliberate v1 boundary, not a defect.

• Reverb cannot tell your room from the one next door. It is listener-centric, so a source sealed in an adjacent room still contributes to the same shared reverb. Distinguishing them is what per-source reflections would do, and that is not built.
• An occluded source still feeds the room. Occlusion ducks the direct signal only. Within max distance, a muffled source still excites the reverb.
• Geometry is what you author. Render meshes and PhysX colliders are not consulted — v1 is authored volumes and O3DE Shapes.
• No offline baking. There are no precomputed reverb probes.
• Reverb is the tail, not early reflections. The parametric model gives you the decay, not discrete early reflections.
• CPU only. There is no GPU acceleration path.

See Also

For related systems:

• Spatialization — the base direction and distance layer this builds on
• Mixing & Effects — influence-driven reverb, the manual alternative
• Audio Pro — the rest of the premium tier
• Audio Signal Model — why environment and reverb are one layer

For conceptual overviews and usage guides:

• The Basics: Audio Pro

Get GS_Audio

GS_Audio — Explore this gem on the product page and add it to your project.

4 - Klatt Voice Synthesis

The Klatt Voice Synthesis system provides custom text-to-speech using Klatt formant synthesis with full 3D spatial audio. Speech is generated by SoLoud and relayed into the miniaudio graph through a custom node, so it travels the same signal chain as every other sound – see the Audio Signal Model.

All types on this page are in the GS_AudioPro namespace.

The system has two layers:

• KlattVoiceSystemComponent – A singleton that manages the shared SoLoud engine instance and tracks the 3D audio listener position.
• KlattVoiceComponent – A per-entity component that generates speech, queues segments, applies voice profiles, and emits spatialized audio from the entity’s position.

Voice characteristics are defined through KlattVoiceProfile assets containing frequency, speed, waveform, formant, and phoneme mapping configuration. Phoneme maps convert input text to ARPABET phonemes for the Klatt synthesizer, with support for custom pronunciation overrides.

For usage guides and setup examples, see The Basics: GS_Audio.

Contents

• Components
• API Reference
• Data Types
• Enumerations
• KTT Voice Tags
• Combined Example
• See Also

Components

KlattVoiceSystemComponent

Singleton component that manages the shared SoLoud engine and 3D listener tracking.

KlattVoiceComponent

Per-entity voice component with spatial audio, phoneme mapping, and segment queue.

API Reference

Request Bus: KlattVoiceSystemRequestBus

System-level voice management. Singleton bus – Single address, single handler.

Request Bus: KlattVoiceRequestBus

Per-entity voice synthesis controls. Entity-addressed bus – Single handler per entity ID.

Notification Bus: KlattVoiceNotificationBus

Events broadcast by voice components. Multiple handler bus – any number of components can subscribe.

Data Types

KlattVoiceParams

Core voice synthesis parameters controlling the Klatt formant synthesizer output.

KlattVoiceProfile

A voice profile asset combining synthesis parameters with a phoneme mapping.

KlattVoicePreset

A preset configuration for quick voice setup.

KlattSpatialConfig

3D spatial audio configuration for voice positioning.

KlattPhonemeMap

Phoneme mapping asset for text-to-ARPABET conversion with custom overrides.

PhonemeOverride

A custom pronunciation rule that overrides the base phoneme map for a specific word or pattern.

Enumerations

KlattWaveform

Glottal waveform types available for the Klatt synthesizer.

BasePhonemeMap

Available base phoneme dictionaries for text-to-ARPABET conversion.

KTT Voice Tags

KTT (Klatt Text Tags) are inline commands embedded in strings passed to KlattVoiceComponent::SpeakText. They are parsed by KlattCommandParser::Parse and stripped from the spoken text before synthesis begins — they are never heard.

Format: <ktt attr1=value1 attr2=value2>

Multiple attributes can be combined in a single tag. Attribute names are case-insensitive. String values may optionally be wrapped in quotes. An empty value (e.g. speed=) resets that parameter to the voice profile default.

speed=X

Override the speech speed multiplier from this point forward.

Normal speech <ktt speed=2.0> fast bit <ktt speed=> back to default.

decl=X / declination=X

Pitch declination — how much pitch falls over the course of the utterance. Both decl and declination are accepted.

Rising <ktt decl=0.0> steady <ktt decl=0.8> falling voice.

waveform="TYPE"

Change the glottal waveform used by the synthesizer, setting the overall character of the voice.

<ktt waveform="noise"> whispered section <ktt waveform="saw"> normal voice.

vowel=X

First formant (F1) frequency multiplier. Shifts the quality of synthesised vowel sounds.

<ktt vowel=1.4> different vowel colour here.

accent=X

Second formant (F2) frequency multiplier. Shifts accent or dialect colouration.

<ktt accent=0.8> shifted accent here.

pitch=X

F0 pitch variance amount. Controls how much pitch varies during synthesis.

<ktt pitch=2.0> very expressive speech <ktt pitch=0.1> flat monotone.

pause=X

Insert a pause of X seconds at this position in the voice playback. Value is required — there is no default.

Hello.<ktt pause=0.8> How are you?

Combined Example

Dialogue string using typewriter text commands and KTT voice tags together:

[b]Warning:[/b] [color=#FF0000]do not[/color] proceed.[pause=1]
<ktt waveform="square" pitch=1.8>This is a mechanical override.<ktt pause=0.5><ktt waveform="saw" pitch=1.0>
[speed=3]Resuming normal protocol.[/speed]

See Also

For conceptual overviews and usage guides:

• GS_Audio Overview – Top-level audio gem documentation
• The Basics: GS_Audio – Scripting-level usage guide

For component references:

• Audio Manager – Manager lifecycle that the voice system participates in

Get GS_Audio

GS_Audio — Explore this gem on the product page and add it to your project.