class

AudioEngine

Module
Audio
Header
#include "Audio/AudioEngine.h"
Namespace
Mowo

Public functions

ReturnsNameDescription
AudioEngine&Get
boolInitializeheadless = no output device (miniaudio noDevice graph, 48 kHz stereo); callers pull mixed output manually via ReadFrames.
voidShutdown
boolReadFramesManually pump the node graph (headless engines only — a device-backed engine reads from its audio thread).
std::vector<FAudioPlaybackDeviceInfo>EnumeratePlaybackDevicesOutput device.
boolSetPlaybackDevice
const std::string&GetRequestedPlaybackDevice
const std::string&GetPlaybackDeviceName
boolIsPlaybackDeviceRunning
voidPollPlaybackDeviceMain-thread poll: reopens a lost device, and while the requested device is absent looks for it every few seconds.
voidSimulatePlaybackDeviceLossWhat the device callback would do on a device loss, for a test that has no device to unplug.
voidSetBusVolume
floatGetBusVolume
voidSetMasterVolume
floatGetMasterVolume
voidSetBusPitch
floatGetBusPitch
floatGetBusActivity
floatGetSubmixActivitySame meter for any submix: the voices routed to it or to a submix under it, through every fader from there up to it.
voidSetListenerPosition
voidSetListenerDirection
voidSetListenerWorldUp
voidSetListenerVelocity
std::vector<FAudibleSound>QueryAudibleWhat is audible to listener 0 right now and from where, loudest first: playing, non-virtual voices at or above minLoudness.
ma_engine*GetEngineAccess to ma_engine for AudioSource creation
ma_vfs*GetVFSThe VFS miniaudio streams through.
ma_sound_group*GetBusGroup
ma_node_graph*GetNodeGraphforwards ma_engine_get_node_graph
uint32_tGetSampleRate
uint32_tGetChannels
AudioSource*PlayOneShotFire-and-forget playback.
voidStopAllStop all playing sounds (for PIE cleanup)
AudioSubmix*CreateSubmixThe submix tree.
AudioSubmix*FindSubmix
boolRemoveSubmix
AudioSubmix*GetBusSubmix
std::vector<AudioSubmix*>GetSubmixes
const char*BusName
boolParseBus
AudioBusBusOfThe default bus a submix budgets its voices against: itself when it is one, otherwise the nearest default bus above it (Master at worst).
voidPauseAllPause/resume all sounds (for PIE pause)
voidResumeAll
boolIsInitialized
voidLoadVolumeSettings
Ref<LowPassEffect>CreateLowPassEffectFactories.
Ref<HighPassEffect>CreateHighPassEffect
Ref<BandPassEffect>CreateBandPassEffect
Ref<PeakEqEffect>CreatePeakEqEffect
Ref<LowShelfEffect>CreateLowShelfEffect
Ref<HighShelfEffect>CreateHighShelfEffect
Ref<DelayEffect>CreateDelayEffect
Ref<ReverbEffect>CreateReverbEffect
Ref<CompressorEffect>CreateCompressorEffect
Ref<ConvolutionReverbEffect>CreateConvolutionReverbEffectConvolution reverb.
Ref<ConvolutionReverbEffect>CreateConvolutionReverbEffectFromVFS
Ref<EnvelopeFollowerEffect>CreateEnvelopeFollowerEffect
boolAddBusEffectPer-bus effect chain.
boolRemoveBusEffect
voidClearBusEffects
size_tGetBusEffectCount
AudioEffect*GetBusEffect
void*RegisterManagedEffectBridge surface for languages without RefCounted semantics.
voidDestroyManagedEffect
VoiceHandleRegisterVoiceEvery AudioSource registers a voice on Load and drops it on Unload, so the engine has the live-sound list miniaudio does not expose.
voidUnregisterVoice
voidRebindVoice
voidSetVoiceBus
voidNotifyVoiceStarted
voidNotifyVoiceStopped
voidSetVoicePriority
boolAdmitVoiceConcurrency (FSoundClasses groups).
uint32_tCountPlayingInGroup
floatGetVoicePriority
voidUpdateVoicesRe-rank + apply virtualization.
boolIsVoiceVirtual
boolIsVoicePlaying
floatGetVoicePositionSeconds
floatGetVoiceScore
voidSetMaxVoices
uint32_tGetMaxVoices
voidSetBusMaxVoices0 = unlimited.
uint32_tGetBusMaxVoices
voidSetVoiceHysteresis
floatGetVoiceHysteresis
uint64_tGetResidentBytesResident memory budget.
uint64_tGetResidentBudgetBytes
voidSetResidentBudgetBytes
boolWouldExceedResidentBudget
voidAddResidentBytes
uint32_tGetStreamingVoiceCount
uint32_tGetForcedStreamCount
voidNoteForcedStream
uint64_tDefaultResidentBudgetForDevice
voidForEachVoiceEvery registered voice, for the debug surface: the source, whether it is logically playing and whether it is virtualized.
uint32_tGetLiveVoiceCount
uint32_tGetAudibleVoiceCount
uint32_tGetVirtualVoiceCount

Function details

Get

C++
static AudioEngine& Get()

Initialize

C++
bool Initialize(bool headless = false)

headless = no output device (miniaudio noDevice graph, 48 kHz stereo); callers pull mixed output manually via ReadFrames. Used by the --audio-graph-test self-test and any CI box without an audio device.

Shutdown

C++
void Shutdown()

ReadFrames

C++
bool ReadFrames(float* frames, uint32_t frameCount, uint64_t* framesRead)

Manually pump the node graph (headless engines only — a device-backed engine reads from its audio thread). frames is frameCount * GetChannels() floats. Returns false when not initialized or the read fails.

EnumeratePlaybackDevices

C++
static std::vector<FAudioPlaybackDeviceInfo> EnumeratePlaybackDevices()

Output device. The engine owns its playback device (the graph itself runs deviceless), so the device can be swapped under a running mix: nothing attached to the graph notices. name empty means the system default; a name no device carries falls back to the default and returns false, and the request is kept so the device is picked up the moment it appears. A device that stops on its own (unplugged) is reopened on the next PollPlaybackDevice, on the default if it is gone.

SetPlaybackDevice

C++
bool SetPlaybackDevice(const std::string& name)

GetRequestedPlaybackDevice

C++
const std::string& GetRequestedPlaybackDevice() const

GetPlaybackDeviceName

C++
const std::string& GetPlaybackDeviceName() const

IsPlaybackDeviceRunning

C++
bool IsPlaybackDeviceRunning() const

PollPlaybackDevice

C++
void PollPlaybackDevice(float deltaTime)

Main-thread poll: reopens a lost device, and while the requested device is absent looks for it every few seconds.

SimulatePlaybackDeviceLoss

C++
void SimulatePlaybackDeviceLoss()

What the device callback would do on a device loss, for a test that has no device to unplug.

SetBusVolume

C++
void SetBusVolume(AudioBus bus, float volume)

GetBusVolume

C++
float GetBusVolume(AudioBus bus) const

SetMasterVolume

C++
void SetMasterVolume(float volume)

GetMasterVolume

C++
float GetMasterVolume() const

SetBusPitch

C++
void SetBusPitch(AudioBus bus, float pitch)

GetBusPitch

C++
float GetBusPitch(AudioBus bus) const

GetBusActivity

C++
float GetBusActivity(AudioBus bus) const

GetSubmixActivity

C++
float GetSubmixActivity(const AudioSubmix* submix) const

Same meter for any submix: the voices routed to it or to a submix under it, through every fader from there up to it.

SetListenerPosition

C++
void SetListenerPosition(uint32_t listenerIndex, float x, float y, float z)

SetListenerDirection

C++
void SetListenerDirection(uint32_t listenerIndex, float x, float y, float z)

SetListenerWorldUp

C++
void SetListenerWorldUp(uint32_t listenerIndex, float x, float y, float z)

SetListenerVelocity

C++
void SetListenerVelocity(uint32_t listenerIndex, float x, float y, float z)

QueryAudible

C++
std::vector<FAudibleSound> QueryAudible(float minLoudness = 0.01f) const

What is audible to listener 0 right now and from where, loudest first: playing, non-virtual voices at or above minLoudness. The data behind an acoustic compass and behind captions that say which way a sound came from.

GetEngine

C++
ma_engine* GetEngine()

Access to ma_engine for AudioSource creation

GetVFS

C++
ma_vfs* GetVFS()

The VFS miniaudio streams through. Every streaming reader has to go through this one and not through the C runtime, or a clip that lives inside a packed .meaf resolves in the editor and misses in the shipped game.

GetBusGroup

C++
ma_sound_group* GetBusGroup(AudioBus bus)

GetNodeGraph

C++
ma_node_graph* GetNodeGraph()

forwards ma_engine_get_node_graph

GetSampleRate

C++
uint32_t GetSampleRate() const

GetChannels

C++
uint32_t GetChannels() const

PlayOneShot

C++
AudioSource* PlayOneShot(const std::string& path, AudioBus bus, float volume, bool spatial, float x, float y, float z)

Fire-and-forget playback. The engine owns the voice, keeps it in a pool and reaps it once it finishes (UpdateVoices), so the caller does not have to hold an AudioSource alive for a one-shot. spatial=true positions the voice at (x,y,z); spatial=false plays it 2D. Returns the voice (valid until it finishes) or nullptr when the clip fails to load.

StopAll

C++
void StopAll()

Stop all playing sounds (for PIE cleanup)

CreateSubmix

C++
AudioSubmix* CreateSubmix(const std::string& name, const std::string& parentName = "Master")

The submix tree. The five AudioBus values are the submixes the engine creates first ("Master" is the root, the other four its children); a project declares more in its config (audio.submixes, entries of the form "Name:Parent:Volume") and code creates them at runtime. Sources and sends name a submix by string, so a custom one is addressed exactly like a default bus. Removal refuses a default bus and a submix that still has sources or children attached.

FindSubmix

C++
AudioSubmix* FindSubmix(const std::string& name) const

RemoveSubmix

C++
bool RemoveSubmix(const std::string& name)

GetBusSubmix

C++
AudioSubmix* GetBusSubmix(AudioBus bus) const

GetSubmixes

C++
std::vector<AudioSubmix*> GetSubmixes() const

BusName

C++
static const char* BusName(AudioBus bus)

ParseBus

C++
static bool ParseBus(const std::string& name, AudioBus& outBus)

BusOf

C++
AudioBus BusOf(const AudioSubmix* submix) const

The default bus a submix budgets its voices against: itself when it is one, otherwise the nearest default bus above it (Master at worst).

PauseAll

C++
void PauseAll()

Pause/resume all sounds (for PIE pause)

ResumeAll

C++
void ResumeAll()

IsInitialized

C++
bool IsInitialized() const

LoadVolumeSettings

C++
void LoadVolumeSettings()

CreateLowPassEffect

C++
Ref<LowPassEffect> CreateLowPassEffect(float cutoffHz, uint32_t order = 4)

Factories. Each call init's the underlying ma_*_node against the engine's node graph using the engine's channels + sample rate. Returns nullptr on failure (init log goes through MOWO_LOG_ERROR). The returned effect is NOT yet attached — pass it to AddBusEffect to insert it into the audio graph. There is no per-source chain attachment; the only per-source effect is the occlusion low-pass AudioSource manages itself.

CreateHighPassEffect

C++
Ref<HighPassEffect> CreateHighPassEffect(float cutoffHz, uint32_t order = 4)

CreateBandPassEffect

C++
Ref<BandPassEffect> CreateBandPassEffect(float cutoffHz, uint32_t order = 4)

CreatePeakEqEffect

C++
Ref<PeakEqEffect> CreatePeakEqEffect(float gainDb, float q, float frequencyHz)

CreateLowShelfEffect

C++
Ref<LowShelfEffect> CreateLowShelfEffect(float gainDb, float slope, float frequencyHz)

CreateHighShelfEffect

C++
Ref<HighShelfEffect> CreateHighShelfEffect(float gainDb, float slope, float frequencyHz)

CreateDelayEffect

C++
Ref<DelayEffect> CreateDelayEffect(float delaySeconds, float decay = 0.5f, float dryWet = 0.5f)

CreateReverbEffect

C++
Ref<ReverbEffect> CreateReverbEffect(float roomSize = 0.5f, float damping = 0.5f, float wet = 0.33f, float dry = 0.7f)

CreateCompressorEffect

C++
Ref<CompressorEffect> CreateCompressorEffect(float thresholdDb = -20.0f, float ratio = 4.0f, float attackMs = 10.0f, float releaseMs = 100.0f, float kneeDb = 6.0f, float makeupDb = 0.0f)

CreateConvolutionReverbEffect

C++
Ref<ConvolutionReverbEffect> CreateConvolutionReverbEffect(const float* interleavedIR, uint32_t irFrames, uint32_t irChannels, float wet = 0.4f, float dry = 0.8f)

Convolution reverb. The raw overload takes interleaved f32 IR samples; the VFS overload decodes any miniaudio-supported audio file (wav/flac/mp3) at the engine's sample rate, keeping the IR's native channel count (true-stereo IRs map channel-for-channel).

CreateConvolutionReverbEffectFromVFS

C++
Ref<ConvolutionReverbEffect> CreateConvolutionReverbEffectFromVFS(const std::string& irPath, float wet = 0.4f, float dry = 0.8f)

CreateEnvelopeFollowerEffect

C++
Ref<EnvelopeFollowerEffect> CreateEnvelopeFollowerEffect(float attackMs = 5.0f, float releaseMs = 60.0f)

AddBusEffect

C++
bool AddBusEffect(AudioBus bus, Ref<AudioEffect> effect)

Per-bus effect chain. Insertion appends to the end of the chain (bus → existing chain → new effect → endpoint). Removal pulls the effect out and re-wires neighbours. The Ref ownership keeps the effect alive while attached — caller may drop their own Ref after AddBusEffect. Threading: chain mutation must happen on the main thread. miniaudio's node attach/detach is internally lock-safe but the chain bookkeeping (m_busEffects vector) is not.

RemoveBusEffect

C++
bool RemoveBusEffect(AudioBus bus, AudioEffect* effect)

ClearBusEffects

C++
void ClearBusEffects(AudioBus bus)

GetBusEffectCount

C++
size_t GetBusEffectCount(AudioBus bus) const

GetBusEffect

C++
AudioEffect* GetBusEffect(AudioBus bus, size_t index) const

RegisterManagedEffect

C++
void* RegisterManagedEffect(Ref<AudioEffect> effect)

Bridge surface for languages without RefCounted semantics. RegisterManaged takes ownership of a Ref and returns a stable raw pointer a host language can hold. The raw pointer stays valid until DestroyManaged is called (which also detaches the effect from any bus chain it's in). Lifetime overlap with the bus chain: AddBusEffect bumps the ref count (the chain holds its own Ref), so a "managed" effect can be in both m_managedEffects AND m_busEffects[bus] simultaneously without leaking.

DestroyManagedEffect

C++
void DestroyManagedEffect(void* handle)

RegisterVoice

C++
VoiceHandle RegisterVoice(AudioSource* source, AudioBus bus)

Every AudioSource registers a voice on Load and drops it on Unload, so the engine has the live-sound list miniaudio does not expose. The budget pass (UpdateVoices, driven by AudioSystem each tick) ranks the playing voices and keeps only the top audio.max_voices audible; the rest are VIRTUALIZED — their ma_sound is stopped so it costs no mixer time, while the engine keeps advancing a wall-clock playback position. A voice that wins its slot back seeks to that position and resumes. Score = priority (0..100, per-source, dominates) + effective volume (0..1, base volume × distance attenuation to listener 0, tie-breaks). Audible voices carry a hysteresis bonus when ranked, so a voice sitting on the budget boundary does not flip audible/virtual frame to frame. These are the AudioSource↔engine plumbing calls — gameplay code drives AudioSource, not this.

UnregisterVoice

C++
void UnregisterVoice(VoiceHandle handle)

RebindVoice

C++
void RebindVoice(VoiceHandle handle, AudioSource* source)

SetVoiceBus

C++
void SetVoiceBus(VoiceHandle handle, AudioBus bus)

NotifyVoiceStarted

C++
void NotifyVoiceStarted(VoiceHandle handle)

NotifyVoiceStopped

C++
void NotifyVoiceStopped(VoiceHandle handle)

SetVoicePriority

C++
void SetVoicePriority(VoiceHandle handle, float priority)

AdmitVoice

C++
bool AdmitVoice(VoiceHandle handle)

Concurrency (FSoundClasses groups). Called by AudioSource::Play for a source in a group: true lets it start — after stopping the victim the group's rule picks when the group is full — false refuses it.

CountPlayingInGroup

C++
uint32_t CountPlayingInGroup(const std::string& group) const

GetVoicePriority

C++
float GetVoicePriority(VoiceHandle handle) const

UpdateVoices

C++
void UpdateVoices(float deltaTime)

Re-rank + apply virtualization. deltaTime advances the virtual playback clock of every virtualized voice.

IsVoiceVirtual

C++
bool IsVoiceVirtual(VoiceHandle handle) const

IsVoicePlaying

C++
bool IsVoicePlaying(VoiceHandle handle) const

GetVoicePositionSeconds

C++
float GetVoicePositionSeconds(VoiceHandle handle) const

GetVoiceScore

C++
float GetVoiceScore(VoiceHandle handle) const

SetMaxVoices

C++
void SetMaxVoices(uint32_t maxVoices)

GetMaxVoices

C++
uint32_t GetMaxVoices() const

SetBusMaxVoices

C++
void SetBusMaxVoices(AudioBus bus, uint32_t maxVoices)

0 = unlimited. Applied on top of the global cap.

GetBusMaxVoices

C++
uint32_t GetBusMaxVoices(AudioBus bus) const

SetVoiceHysteresis

C++
void SetVoiceHysteresis(float margin)

GetVoiceHysteresis

C++
float GetVoiceHysteresis() const

GetResidentBytes

C++
uint64_t GetResidentBytes() const

Resident memory budget. Every clip held decoded in memory (a resident .maudio, a cooked DDC blob) is counted here; a load that would take the total past the budget streams instead when the clip can stream, so a level full of long beds degrades to disk reads rather than to an out-of-memory on a small device. The budget is audio.resident_budget_mb from the project config — per platform through its own config — and when that is 0 it is derived from the device (1/64 of physical memory through the PAL, clamped to 64..512 MB: 256 MB on a 16 GB handheld). -1 means unlimited.

GetResidentBudgetBytes

C++
uint64_t GetResidentBudgetBytes() const

SetResidentBudgetBytes

C++
void SetResidentBudgetBytes(uint64_t bytes)

WouldExceedResidentBudget

C++
bool WouldExceedResidentBudget(uint64_t additionalBytes) const

AddResidentBytes

C++
void AddResidentBytes(int64_t delta)

GetStreamingVoiceCount

C++
uint32_t GetStreamingVoiceCount() const

GetForcedStreamCount

C++
uint32_t GetForcedStreamCount() const

NoteForcedStream

C++
void NoteForcedStream()

DefaultResidentBudgetForDevice

C++
static uint64_t DefaultResidentBudgetForDevice(uint64_t physicalBytes)

ForEachVoice

C++
void ForEachVoice(const std::function<void(VoiceHandle handle, const AudioSource* source, bool playing, bool virtualized)>& visitor) const

Every registered voice, for the debug surface: the source, whether it is logically playing and whether it is virtualized.

GetLiveVoiceCount

C++
uint32_t GetLiveVoiceCount() const

GetAudibleVoiceCount

C++
uint32_t GetAudibleVoiceCount() const

GetVirtualVoiceCount

C++
uint32_t GetVirtualVoiceCount() const
Generated from Audio/AudioEngine.h via audio.json · Oct 26, 2026Version 1.0.0