AudioSource
- Module
- Audio
- Header
#include "Audio/AudioSource.h"- Namespace
Mowo
Constructors
| Signature | Name | Description |
|---|---|---|
AudioSource() | AudioSource | |
~AudioSource() | ~AudioSource | |
AudioSource(const AudioSource&) = delete | AudioSource | Non-copyable, movable |
AudioSource(AudioSource&& other) noexcept | AudioSource |
Public functions
| Returns | Name | Description |
|---|---|---|
AudioSource& | operator= | |
AudioSource& | operator= | |
bool | Load | Load a sound file (VFS path). |
bool | Load | |
bool | SetSubmix | Re-routes a loaded source to another submix; sends stay as they are. |
const std::string& | GetSubmixName | |
void | SetEnvelopeFollowerEnabled | Sends: a copy of this source into another submix at level, on top of its main route. |
bool | IsEnvelopeFollowerEnabled | |
float | GetEnvelopeRms | |
float | GetEnvelopePeak | |
bool | SetSend | |
bool | RemoveSend | |
float | GetSendLevel | |
size_t | GetSendCount | |
bool | LoadPcmStream | Bind the source to a live PCM ring instead of a file — network voice, synthesised audio, anything produced frame by frame. |
bool | LoadPcmStream | |
uint32_t | PushPcmStream | Producer side of a PCM stream. |
uint32_t | GetPcmStreamQueuedSamples | |
bool | IsPcmStream | |
void | Unload | |
void | Play | |
void | Stop | |
void | Pause | |
bool | IsPlaying | True while the voice is logically playing — including while virtualized, where the underlying ma_sound is stopped but the voice still owns a playback position. |
bool | IsAtEnd | |
bool | WasStopped | True after Stop() — this voice's or one a concurrency group issued to make room — or when a full group refused Play(); false once it starts. |
void | SetVolume | |
float | GetVolume | |
void | SetPitch | |
float | GetPitch | |
void | SetLooping | |
bool | IsLooping | |
void | SetSpatial | 3D spatialization |
void | SetPosition | |
void | SetMinDistance | |
void | SetMaxDistance | |
void | SetAttenuationModel | An ma_attenuation_model value. |
void | SetRolloff | |
void | SetVelocity | |
void | GetVelocity | |
void | SetDopplerFactor | |
float | GetDopplerFactor | |
void | SetDirection | |
void | SetCone | |
void | FadeIn | |
void | FadeOut | |
void | FadeTo | |
void | SeekToFrame | |
void | SeekToSeconds | |
uint64_t | GetCursorInFrames | |
float | GetCursorInSeconds | |
float | GetLengthInSeconds | |
void | SetLowPassCutoff | Per-source low-pass filter (used by occlusion). |
float | GetLowPassCutoff | |
bool | AddEffect | Ordered source effect chain (UE's Source Effect Chain): sound → occlusion/distance low-pass → effects[0] → effects[1] → … → envelope tap → sends/submix. |
bool | InsertEffect | |
bool | RemoveEffect | |
void | ClearEffects | |
size_t | GetEffectCount | |
AudioEffect* | GetEffect | |
void | AddParameterBinding | Parameter modulation (FAudioParameters). |
void | ClearParameterBindings | |
size_t | GetParameterBindingCount | |
void | ApplyParameterBindings | |
float | GetParameterVolumeScale | |
float | GetParameterPitchScale | |
float | GetAssetPitch | The clip's authored default pitch (its header), applied under SetPitch. |
float | GetParameterCutoff | |
bool | IsLoaded | |
bool | IsStreaming | True when the clip reads from disk as it plays rather than being resident. |
float | GetLoudnessGainDb | The normalisation gain the cook stored in the clip, in dB. |
uint64_t | GetResidentBytes | Decoded bytes this source holds in memory, counted against the engine's resident budget; 0 for a streaming or live source. |
void | SetPriority | Priority is the primary ranking key of the voice budget (0..100, higher wins; effective volume breaks ties). |
float | GetPriority | |
bool | IsVirtual | |
float | GetPlaybackPositionSeconds | Virtual-aware cursor: the tracked position while virtualized, the real ma_sound cursor otherwise. |
VoiceHandle | GetVoiceHandle | |
void | ApplyExternalSpatialization | External spatialization (FAudioSpatialization). |
void | ClearExternalSpatialization | |
bool | IsExternallySpatialized | |
float | GetExternalGain | |
float | GetExternalPan | |
void | SetSoundClass | Sound class (FSoundClasses): its volume/pitch/low-pass, and every ancestor's and active mix's, ride on this source's modulation each tick. |
const std::string& | GetSoundClass | |
void | SetConcurrencyGroup | |
const std::string& | GetConcurrencyGroup | |
void | SetCaptionTag | What this voice is, for the acoustic compass (AudioEngine::QueryAudible): a captioned cue tags every voice it starts with its caption. |
const std::string& | GetCaptionTag | |
bool | IsSpatialized | |
void | GetPosition | |
float | GetMinDistance | |
float | GetMaxDistance | |
void | VirtualizeVoice | AudioEngine's budget pass drives these three — do not call them from gameplay code, they bypass the registry's playing/virtual bookkeeping. |
void | DevirtualizeVoice | |
void | EndVirtualVoice |
Function details
AudioSource
AudioSource()~AudioSource
~AudioSource()AudioSource
AudioSource(const AudioSource&) = deleteNon-copyable, movable
AudioSource
AudioSource(AudioSource&& other) noexceptoperator=
AudioSource& operator=(const AudioSource&) = deleteoperator=
AudioSource& operator=(AudioSource&& other) noexceptLoad
bool Load(const std::string& filePath, AudioBus bus = AudioBus::SFX, bool streaming = false)Load a sound file (VFS path). The bus form names one of the default submixes; the string form names any submix in the tree (a name that does not exist falls back to SFX with a warning).
Load
bool Load(const std::string& filePath, const std::string& submix, bool streaming = false)SetSubmix
bool SetSubmix(const std::string& submix)Re-routes a loaded source to another submix; sends stay as they are.
GetSubmixName
const std::string& GetSubmixName() constSetEnvelopeFollowerEnabled
void SetEnvelopeFollowerEnabled(bool enabled)Sends: a copy of this source into another submix at level, on top of its main route. Post-fader (the default) takes the signal after the source volume and its distance attenuation, so a fading source fades in the send too; pre-fader takes it after the attenuation but before the source volume, so a send level holds while the source is faded. Sends set before Load are applied by it. Setting a level of 0 keeps the send; RemoveSend drops it. A level tap on this source's own signal (after the occlusion filter, before the sends split). Lip-sync and meters read it; off by default because it is one more node per voice.
IsEnvelopeFollowerEnabled
bool IsEnvelopeFollowerEnabled() constGetEnvelopeRms
float GetEnvelopeRms() constGetEnvelopePeak
float GetEnvelopePeak() constSetSend
bool SetSend(const std::string& submix, float level, bool preFader = false)RemoveSend
bool RemoveSend(const std::string& submix)GetSendLevel
float GetSendLevel(const std::string& submix) constGetSendCount
size_t GetSendCount() constLoadPcmStream
bool LoadPcmStream(uint32_t sampleRate, uint32_t channels, uint32_t ringSamples, AudioBus bus = AudioBus::Voice)Bind the source to a live PCM ring instead of a file — network voice, synthesised audio, anything produced frame by frame. The source behaves like any other from here on: spatialization, min/max distance, attenuation model, rolloff and the occlusion low-pass all apply. Starvation plays silence rather than ending the sound.
LoadPcmStream
bool LoadPcmStream(uint32_t sampleRate, uint32_t channels, uint32_t ringSamples, const std::string& submix)PushPcmStream
uint32_t PushPcmStream(const int16_t* samples, uint32_t count)Producer side of a PCM stream. Returns the samples accepted; 0 means the ring was full and the block was dropped whole.
GetPcmStreamQueuedSamples
uint32_t GetPcmStreamQueuedSamples() constIsPcmStream
bool IsPcmStream() constUnload
void Unload()Play
void Play()Stop
void Stop()Pause
void Pause()IsPlaying
bool IsPlaying() constTrue while the voice is logically playing — including while virtualized, where the underlying ma_sound is stopped but the voice still owns a playback position.
IsAtEnd
bool IsAtEnd() constWasStopped
bool WasStopped() constTrue after Stop() — this voice's or one a concurrency group issued to make room — or when a full group refused Play(); false once it starts. Stop() rewinds, so IsAtEnd alone cannot tell a stopped voice from a paused one.
SetVolume
void SetVolume(float volume)GetVolume
float GetVolume() constSetPitch
void SetPitch(float pitch)GetPitch
float GetPitch() constSetLooping
void SetLooping(bool loop)IsLooping
bool IsLooping() constSetSpatial
void SetSpatial(bool spatial)3D spatialization
SetPosition
void SetPosition(float x, float y, float z)SetMinDistance
void SetMinDistance(float dist)SetMaxDistance
void SetMaxDistance(float dist)SetAttenuationModel
void SetAttenuationModel(int32_t model)An ma_attenuation_model value.
SetRolloff
void SetRolloff(float rolloff)SetVelocity
void SetVelocity(float x, float y, float z)GetVelocity
void GetVelocity(float& x, float& y, float& z) constSetDopplerFactor
void SetDopplerFactor(float factor)GetDopplerFactor
float GetDopplerFactor() constSetDirection
void SetDirection(float x, float y, float z)SetCone
void SetCone(float innerRadians, float outerRadians, float outerGain)FadeIn
void FadeIn(float durationMs)FadeOut
void FadeOut(float durationMs)FadeTo
void FadeTo(float targetVolume, float durationMs)SeekToFrame
void SeekToFrame(uint64_t frame)SeekToSeconds
void SeekToSeconds(float seconds)GetCursorInFrames
uint64_t GetCursorInFrames() constGetCursorInSeconds
float GetCursorInSeconds() constGetLengthInSeconds
float GetLengthInSeconds() constSetLowPassCutoff
void SetLowPassCutoff(float cutoffHz)Per-source low-pass filter (used by occlusion). Cutoff >= 19999 Hz removes the filter entirely (source plays through the bus directly); any lower value inserts/maintains a LowPassEffect between the sound and its bus group. Safe to call repeatedly from the same thread — re-attaches only when crossing the "enabled / disabled" boundary.
GetLowPassCutoff
float GetLowPassCutoff() constAddEffect
bool AddEffect(Ref<AudioEffect> effect)Ordered source effect chain (UE's Source Effect Chain): sound → occlusion/distance low-pass → effects[0] → effects[1] → … → envelope tap → sends/submix. The low-pass slot stays its own, so occlusion never competes with an authored filter for it. An effect lives in one chain; adding one already in this chain is refused. Effects come from the AudioEngine::Create*Effect factories and survive a reload of the clip.
InsertEffect
bool InsertEffect(size_t index, Ref<AudioEffect> effect)RemoveEffect
bool RemoveEffect(AudioEffect* effect)ClearEffects
void ClearEffects()GetEffectCount
size_t GetEffectCount() constGetEffect
AudioEffect* GetEffect(size_t index) constAddParameterBinding
void AddParameterBinding(const FAudioParameterBinding& binding)Parameter modulation (FAudioParameters). Bindings stack: Volume and Pitch bindings multiply onto the authored volume and pitch (Get/SetVolume and Get/SetPitch keep meaning the authored values), and the darkest LowPassCutoff binding sits under whatever SetLowPassCutoff asked for. AudioEngine::UpdateVoices re-evaluates every live source each tick.
ClearParameterBindings
void ClearParameterBindings()GetParameterBindingCount
size_t GetParameterBindingCount() constApplyParameterBindings
void ApplyParameterBindings()GetParameterVolumeScale
float GetParameterVolumeScale() constGetParameterPitchScale
float GetParameterPitchScale() constGetAssetPitch
float GetAssetPitch() constThe clip's authored default pitch (its header), applied under SetPitch.
GetParameterCutoff
float GetParameterCutoff() constIsLoaded
bool IsLoaded() constIsStreaming
bool IsStreaming() constTrue when the clip reads from disk as it plays rather than being resident. Set by Load(), from the cook's decision: a compressed source goes through miniaudio's own streaming decoder, a cooked .maudio through FMaudioFileStream.
GetLoudnessGainDb
float GetLoudnessGainDb() constThe normalisation gain the cook stored in the clip, in dB. Applied under the authored volume, so SetVolume/GetVolume keep meaning what the caller asked for.
GetResidentBytes
uint64_t GetResidentBytes() constDecoded bytes this source holds in memory, counted against the engine's resident budget; 0 for a streaming or live source.
SetPriority
void SetPriority(float priority)Priority is the primary ranking key of the voice budget (0..100, higher wins; effective volume breaks ties). A source over budget is virtualized: its ma_sound stops feeding the mixer while AudioEngine keeps advancing the playback position, so de-virtualization resumes where it would have been had it never dropped out.
GetPriority
float GetPriority() constIsVirtual
bool IsVirtual() constGetPlaybackPositionSeconds
float GetPlaybackPositionSeconds() constVirtual-aware cursor: the tracked position while virtualized, the real ma_sound cursor otherwise.
GetVoiceHandle
VoiceHandle GetVoiceHandle() constApplyExternalSpatialization
void ApplyExternalSpatialization(float gain, float pan, float lowPassHz)External spatialization (FAudioSpatialization). While a non-native spatializer runs, miniaudio's own spatializer is off for this voice and the plugin's gain, pan and low-pass apply instead; Clear hands the voice back to miniaudio. AudioEngine::UpdateVoices drives both.
ClearExternalSpatialization
void ClearExternalSpatialization()IsExternallySpatialized
bool IsExternallySpatialized() constGetExternalGain
float GetExternalGain() constGetExternalPan
float GetExternalPan() constSetSoundClass
void SetSoundClass(const std::string& className)Sound class (FSoundClasses): its volume/pitch/low-pass, and every ancestor's and active mix's, ride on this source's modulation each tick. Concurrency group: a full group applies its rule when Play is called.
GetSoundClass
const std::string& GetSoundClass() constSetConcurrencyGroup
void SetConcurrencyGroup(const std::string& group)GetConcurrencyGroup
const std::string& GetConcurrencyGroup() constSetCaptionTag
void SetCaptionTag(const std::string& caption)What this voice is, for the acoustic compass (AudioEngine::QueryAudible): a captioned cue tags every voice it starts with its caption.
GetCaptionTag
const std::string& GetCaptionTag() constIsSpatialized
bool IsSpatialized() constGetPosition
void GetPosition(float& x, float& y, float& z) constGetMinDistance
float GetMinDistance() constGetMaxDistance
float GetMaxDistance() constVirtualizeVoice
void VirtualizeVoice()AudioEngine's budget pass drives these three — do not call them from gameplay code, they bypass the registry's playing/virtual bookkeeping.
DevirtualizeVoice
void DevirtualizeVoice(float positionSeconds)EndVirtualVoice
void EndVirtualVoice()