AudioEngine
- Module
- Audio
- Header
#include "Audio/AudioEngine.h"- Namespace
Mowo
Public functions
| Returns | Name | Description |
|---|---|---|
AudioEngine& | Get | |
bool | Initialize | headless = no output device (miniaudio noDevice graph, 48 kHz stereo); callers pull mixed output manually via ReadFrames. |
void | Shutdown | |
bool | ReadFrames | Manually pump the node graph (headless engines only — a device-backed engine reads from its audio thread). |
std::vector<FAudioPlaybackDeviceInfo> | EnumeratePlaybackDevices | Output device. |
bool | SetPlaybackDevice | |
const std::string& | GetRequestedPlaybackDevice | |
const std::string& | GetPlaybackDeviceName | |
bool | IsPlaybackDeviceRunning | |
void | PollPlaybackDevice | Main-thread poll: reopens a lost device, and while the requested device is absent looks for it every few seconds. |
void | SimulatePlaybackDeviceLoss | What the device callback would do on a device loss, for a test that has no device to unplug. |
void | SetBusVolume | |
float | GetBusVolume | |
void | SetMasterVolume | |
float | GetMasterVolume | |
void | SetBusPitch | |
float | GetBusPitch | |
float | GetBusActivity | |
float | GetSubmixActivity | Same meter for any submix: the voices routed to it or to a submix under it, through every fader from there up to it. |
void | SetListenerPosition | |
void | SetListenerDirection | |
void | SetListenerWorldUp | |
void | SetListenerVelocity | |
std::vector<FAudibleSound> | QueryAudible | What is audible to listener 0 right now and from where, loudest first: playing, non-virtual voices at or above minLoudness. |
ma_engine* | GetEngine | Access to ma_engine for AudioSource creation |
ma_vfs* | GetVFS | The VFS miniaudio streams through. |
ma_sound_group* | GetBusGroup | |
ma_node_graph* | GetNodeGraph | forwards ma_engine_get_node_graph |
uint32_t | GetSampleRate | |
uint32_t | GetChannels | |
AudioSource* | PlayOneShot | Fire-and-forget playback. |
void | StopAll | Stop all playing sounds (for PIE cleanup) |
AudioSubmix* | CreateSubmix | The submix tree. |
AudioSubmix* | FindSubmix | |
bool | RemoveSubmix | |
AudioSubmix* | GetBusSubmix | |
std::vector<AudioSubmix*> | GetSubmixes | |
const char* | BusName | |
bool | ParseBus | |
AudioBus | BusOf | The default bus a submix budgets its voices against: itself when it is one, otherwise the nearest default bus above it (Master at worst). |
void | PauseAll | Pause/resume all sounds (for PIE pause) |
void | ResumeAll | |
bool | IsInitialized | |
void | LoadVolumeSettings | |
Ref<LowPassEffect> | CreateLowPassEffect | Factories. |
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> | CreateConvolutionReverbEffect | Convolution reverb. |
Ref<ConvolutionReverbEffect> | CreateConvolutionReverbEffectFromVFS | |
Ref<EnvelopeFollowerEffect> | CreateEnvelopeFollowerEffect | |
bool | AddBusEffect | Per-bus effect chain. |
bool | RemoveBusEffect | |
void | ClearBusEffects | |
size_t | GetBusEffectCount | |
AudioEffect* | GetBusEffect | |
void* | RegisterManagedEffect | Bridge surface for languages without RefCounted semantics. |
void | DestroyManagedEffect | |
VoiceHandle | RegisterVoice | Every AudioSource registers a voice on Load and drops it on Unload, so the engine has the live-sound list miniaudio does not expose. |
void | UnregisterVoice | |
void | RebindVoice | |
void | SetVoiceBus | |
void | NotifyVoiceStarted | |
void | NotifyVoiceStopped | |
void | SetVoicePriority | |
bool | AdmitVoice | Concurrency (FSoundClasses groups). |
uint32_t | CountPlayingInGroup | |
float | GetVoicePriority | |
void | UpdateVoices | Re-rank + apply virtualization. |
bool | IsVoiceVirtual | |
bool | IsVoicePlaying | |
float | GetVoicePositionSeconds | |
float | GetVoiceScore | |
void | SetMaxVoices | |
uint32_t | GetMaxVoices | |
void | SetBusMaxVoices | 0 = unlimited. |
uint32_t | GetBusMaxVoices | |
void | SetVoiceHysteresis | |
float | GetVoiceHysteresis | |
uint64_t | GetResidentBytes | Resident memory budget. |
uint64_t | GetResidentBudgetBytes | |
void | SetResidentBudgetBytes | |
bool | WouldExceedResidentBudget | |
void | AddResidentBytes | |
uint32_t | GetStreamingVoiceCount | |
uint32_t | GetForcedStreamCount | |
void | NoteForcedStream | |
uint64_t | DefaultResidentBudgetForDevice | |
void | ForEachVoice | Every registered voice, for the debug surface: the source, whether it is logically playing and whether it is virtualized. |
uint32_t | GetLiveVoiceCount | |
uint32_t | GetAudibleVoiceCount | |
uint32_t | GetVirtualVoiceCount |
Function details
Get
static AudioEngine& Get()Initialize
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
void Shutdown()ReadFrames
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
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
bool SetPlaybackDevice(const std::string& name)GetRequestedPlaybackDevice
const std::string& GetRequestedPlaybackDevice() constGetPlaybackDeviceName
const std::string& GetPlaybackDeviceName() constIsPlaybackDeviceRunning
bool IsPlaybackDeviceRunning() constPollPlaybackDevice
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
void SimulatePlaybackDeviceLoss()What the device callback would do on a device loss, for a test that has no device to unplug.
SetBusVolume
void SetBusVolume(AudioBus bus, float volume)GetBusVolume
float GetBusVolume(AudioBus bus) constSetMasterVolume
void SetMasterVolume(float volume)GetMasterVolume
float GetMasterVolume() constSetBusPitch
void SetBusPitch(AudioBus bus, float pitch)GetBusPitch
float GetBusPitch(AudioBus bus) constGetBusActivity
float GetBusActivity(AudioBus bus) constGetSubmixActivity
float GetSubmixActivity(const AudioSubmix* submix) constSame meter for any submix: the voices routed to it or to a submix under it, through every fader from there up to it.
SetListenerPosition
void SetListenerPosition(uint32_t listenerIndex, float x, float y, float z)SetListenerDirection
void SetListenerDirection(uint32_t listenerIndex, float x, float y, float z)SetListenerWorldUp
void SetListenerWorldUp(uint32_t listenerIndex, float x, float y, float z)SetListenerVelocity
void SetListenerVelocity(uint32_t listenerIndex, float x, float y, float z)QueryAudible
std::vector<FAudibleSound> QueryAudible(float minLoudness = 0.01f) constWhat 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
ma_engine* GetEngine()Access to ma_engine for AudioSource creation
GetVFS
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
ma_sound_group* GetBusGroup(AudioBus bus)GetNodeGraph
ma_node_graph* GetNodeGraph()forwards ma_engine_get_node_graph
GetSampleRate
uint32_t GetSampleRate() constGetChannels
uint32_t GetChannels() constPlayOneShot
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
void StopAll()Stop all playing sounds (for PIE cleanup)
CreateSubmix
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
AudioSubmix* FindSubmix(const std::string& name) constRemoveSubmix
bool RemoveSubmix(const std::string& name)GetBusSubmix
AudioSubmix* GetBusSubmix(AudioBus bus) constGetSubmixes
std::vector<AudioSubmix*> GetSubmixes() constBusName
static const char* BusName(AudioBus bus)ParseBus
static bool ParseBus(const std::string& name, AudioBus& outBus)BusOf
AudioBus BusOf(const AudioSubmix* submix) constThe default bus a submix budgets its voices against: itself when it is one, otherwise the nearest default bus above it (Master at worst).
PauseAll
void PauseAll()Pause/resume all sounds (for PIE pause)
ResumeAll
void ResumeAll()IsInitialized
bool IsInitialized() constLoadVolumeSettings
void LoadVolumeSettings()CreateLowPassEffect
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
Ref<HighPassEffect> CreateHighPassEffect(float cutoffHz, uint32_t order = 4)CreateBandPassEffect
Ref<BandPassEffect> CreateBandPassEffect(float cutoffHz, uint32_t order = 4)CreatePeakEqEffect
Ref<PeakEqEffect> CreatePeakEqEffect(float gainDb, float q, float frequencyHz)CreateLowShelfEffect
Ref<LowShelfEffect> CreateLowShelfEffect(float gainDb, float slope, float frequencyHz)CreateHighShelfEffect
Ref<HighShelfEffect> CreateHighShelfEffect(float gainDb, float slope, float frequencyHz)CreateDelayEffect
Ref<DelayEffect> CreateDelayEffect(float delaySeconds, float decay = 0.5f, float dryWet = 0.5f)CreateReverbEffect
Ref<ReverbEffect> CreateReverbEffect(float roomSize = 0.5f, float damping = 0.5f, float wet = 0.33f, float dry = 0.7f)CreateCompressorEffect
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
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
Ref<ConvolutionReverbEffect> CreateConvolutionReverbEffectFromVFS(const std::string& irPath, float wet = 0.4f, float dry = 0.8f)CreateEnvelopeFollowerEffect
Ref<EnvelopeFollowerEffect> CreateEnvelopeFollowerEffect(float attackMs = 5.0f, float releaseMs = 60.0f)AddBusEffect
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
bool RemoveBusEffect(AudioBus bus, AudioEffect* effect)ClearBusEffects
void ClearBusEffects(AudioBus bus)GetBusEffectCount
size_t GetBusEffectCount(AudioBus bus) constGetBusEffect
AudioEffect* GetBusEffect(AudioBus bus, size_t index) constRegisterManagedEffect
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
void DestroyManagedEffect(void* handle)RegisterVoice
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
void UnregisterVoice(VoiceHandle handle)RebindVoice
void RebindVoice(VoiceHandle handle, AudioSource* source)SetVoiceBus
void SetVoiceBus(VoiceHandle handle, AudioBus bus)NotifyVoiceStarted
void NotifyVoiceStarted(VoiceHandle handle)NotifyVoiceStopped
void NotifyVoiceStopped(VoiceHandle handle)SetVoicePriority
void SetVoicePriority(VoiceHandle handle, float priority)AdmitVoice
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
uint32_t CountPlayingInGroup(const std::string& group) constGetVoicePriority
float GetVoicePriority(VoiceHandle handle) constUpdateVoices
void UpdateVoices(float deltaTime)Re-rank + apply virtualization. deltaTime advances the virtual playback clock of every virtualized voice.
IsVoiceVirtual
bool IsVoiceVirtual(VoiceHandle handle) constIsVoicePlaying
bool IsVoicePlaying(VoiceHandle handle) constGetVoicePositionSeconds
float GetVoicePositionSeconds(VoiceHandle handle) constGetVoiceScore
float GetVoiceScore(VoiceHandle handle) constSetMaxVoices
void SetMaxVoices(uint32_t maxVoices)GetMaxVoices
uint32_t GetMaxVoices() constSetBusMaxVoices
void SetBusMaxVoices(AudioBus bus, uint32_t maxVoices)0 = unlimited. Applied on top of the global cap.
GetBusMaxVoices
uint32_t GetBusMaxVoices(AudioBus bus) constSetVoiceHysteresis
void SetVoiceHysteresis(float margin)GetVoiceHysteresis
float GetVoiceHysteresis() constGetResidentBytes
uint64_t GetResidentBytes() constResident 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
uint64_t GetResidentBudgetBytes() constSetResidentBudgetBytes
void SetResidentBudgetBytes(uint64_t bytes)WouldExceedResidentBudget
bool WouldExceedResidentBudget(uint64_t additionalBytes) constAddResidentBytes
void AddResidentBytes(int64_t delta)GetStreamingVoiceCount
uint32_t GetStreamingVoiceCount() constGetForcedStreamCount
uint32_t GetForcedStreamCount() constNoteForcedStream
void NoteForcedStream()DefaultResidentBudgetForDevice
static uint64_t DefaultResidentBudgetForDevice(uint64_t physicalBytes)ForEachVoice
void ForEachVoice(const std::function<void(VoiceHandle handle, const AudioSource* source, bool playing, bool virtualized)>& visitor) constEvery registered voice, for the debug surface: the source, whether it is logically playing and whether it is virtualized.
GetLiveVoiceCount
uint32_t GetLiveVoiceCount() constGetAudibleVoiceCount
uint32_t GetAudibleVoiceCount() constGetVirtualVoiceCount
uint32_t GetVirtualVoiceCount() const