Audio

System to play and manage sounds.

---

Play

Convenience alias for PlaySound2D — plays a sound with no positional data. Accepts the same arguments as PlaySound2D.

Sig: Audio.Play(sound, volume=1, pitch=1, startTime=0, loop=false, priority=0) - Arg: SoundWave sound Sound wave to play - Arg: number volume Volume multiplier - Arg: number pitch Pitch multiplier - Arg: number startTime Start time offset - Arg: boolean loop Loop sound - Arg: integer priority Sound priority

---

Pause

Mute every currently-playing voice of sound by driving its volume to 0 (pitch is held at 1, priority is bumped to 1). The voices keep ticking — this is a volume duck, not a transport pause. To resume audibility, call Audio.UpdateSound(sound, volume, pitch, priority) with the desired volume. For a true transport pause that preserves cursor position, use an Audio3D node and call Audio3D:PauseAudio() instead.

Sig: Audio.Pause(sound) - Arg: SoundWave sound Sound wave to mute

---

Stop

Alias for StopSounds — stops every currently-playing voice of sound.

Sig: Audio.Stop(sound) - Arg: SoundWave sound Sound wave to stop

---

PlaySound2D

Play a sound with no positional data. TODO: Rename to PlaySound() if we add 2D support.

Sig: Audio.PlaySound2D(sound, volume=1, pitch=1, startTime=0, loop=false, priority=0) - Arg: SoundWave sound Sound wave to play - Arg: number volume Volume multiplier - Arg: number pitch Pitch multiplier - Arg: number startTime Start time offset - Arg: boolean loop Loop sound - Arg: integer priority Sound priority

---

PlaySound3D

Play a sound at a position in 3D space.

Alias: PlaySoundAtPosition

Sig: Audio.PlaySound3D(sound, position, innerRadius, outerRadius, attenuationFunc=AttenuationFunc.Linear, volume=1, pitch=1, startTime=0, loop=false, priority=0) - Arg: SoundWave sound Sound wave to play - Arg: Vector position Position of sound - Arg: number innerRadius Inner radius - Arg: number outerRadius Outer radius - Arg: AttenuationFunc(integer) attenuationFunc Attenuation function - Arg: number volume Volume multiplier - Arg: number pitch Pitch multiplier - Arg: number startTime Start time offset - Arg: boolean loop Loop sound - Arg: integer priority Sound priority

---

PlaySoundAtPosition

Play a sound at a world-space position. Identical to PlaySound3D — preferred name going forward; PlaySound3D stays for compatibility.

Sig: Audio.PlaySoundAtPosition(sound, position, innerRadius, outerRadius, attenuationFunc=AttenuationFunc.Linear, volume=1, pitch=1, startTime=0, loop=false, priority=0) - Arg: SoundWave sound Sound wave to play - Arg: Vector position World-space position of sound - Arg: number innerRadius Inner radius - Arg: number outerRadius Outer radius - Arg: AttenuationFunc(integer) attenuationFunc Attenuation function - Arg: number volume Volume multiplier - Arg: number pitch Pitch multiplier - Arg: number startTime Start time offset - Arg: boolean loop Loop sound - Arg: integer priority Sound priority

---

StopSounds

Stop sounds using a particular sound wave.

Alias: StopSound

Sig: Audio.StopSounds(sound) - Arg: SoundWave sound Sound wave to stop

---

StopAllSounds

Stop all sounds.

Sig: Audio.StopAllSounds()

---

UpdateSound

Updates volume, pitch, and priority for a currently playing sound wave. Note: This will update volume/pitch/priority for all currently playing sounds of the same sound wave asset.

Sig: Audio.UpdateSound(sound, volume, pitch, priority=0) - Arg: SoundWave sound Sound wave to update - Arg: number volume New volume - Arg: number pitch New pitch - Arg: integer priority New priority

---

IsSoundPlaying

Check if a sound wave is playing.

Sig: playing = Audio.IsSoundPlaying(sound) - Arg: SoundWave sound Sound wave to check - Ret: boolean playing Is the sound playing

---

SetAudioClassVolume

Set the volume of an audio class. Audio classes can be used to control the volume and pitch of multiple sounds.

Sig: Audio.SetAudioClassVolume(volume) - Arg: number volume Volume multiplier

---

GetAudioClassVolume

Get the volume of an audio class. Audio classes can be used to control the volume and pitch of multiple sounds.

Sig: volume = Audio.GetAudioClassVolume() - Ret: number volume Volume multiplier

---

SetAudioClassPitch

Set the pitch of an audio class. Audio classes can be used to control the volume and pitch of multiple sounds.

Sig: Audio.SetAudioClassPitch(pitch) - Arg: number pitch Pitch multiplier

---

GetAudioClassPitch

Get the pitch of an audio class. Audio classes can be used to control the volume and pitch of multiple sounds.

Sig: pitch = Audio.GetAudioClassPitch() - Ret: number pitch Pitch multiplier

---

SetMasterVolume

Set the master volume.

Sig: Audio.SetMasterVolume(volume) - Arg: number volume Master volume

---

GetMasterVolume

Get the master volume.

Sig: volume = Audio.GetMasterVolume() - Ret: number volume Master volume

---

SetMasterPitch

Set the master pitch.

Sig: Audio.SetMasterPitch(pitch) - Arg: number pitch Master pitch

---

GetMasterPitch

Get the master pitch.

Sig: pitch = Audio.GetMasterPitch() - Ret: number pitch Master pitch

---

Switching the SoundWave on a playing Audio3D

Audio3D:SetSoundWave(newWave) automatically releases the live voice when the wave actually changes, so the intuitive pattern just works on every click:

self.audioPlayer:SetSoundWave(LoadAsset(nextTrack))
self.audioPlayer:PlayAudio()

Internally, if a different wave is passed in while the node is currently audible, SetSoundWave synchronously calls AudioManager::StopComponent(this) and zeroes mPlayTime. The next AudioManager::Update tick then sees IsPlaying() && !IsAudible() and spawns a fresh voice bound to the new wave. Passing the same wave is a no-op — playback is not interrupted.

You almost never need ResetAudio() in script code anymore — it's only useful if you want to hard-kill the voice without changing the wave.

Goal	Call sequence
Start a track on an idle Audio3D	SetSoundWave(w) → PlayAudio()
Switch the track on a playing Audio3D	SetSoundWave(w) → PlayAudio() (voice swap is automatic)
Pause but keep position (resume later)	PauseAudio()
Stop and rewind	StopAudio()
Hard-kill the voice right now	ResetAudio()

For one-shot sounds that don't need a node, prefer Audio.PlaySound2D / Audio.PlaySound3D — they always allocate a fresh voice.

---

Signals

The audio system broadcasts the following signal through the global SignalBus. Subscribe to it from any node — it fires each time a wave reaches the end of one play, including each wrap of a looping voice (so playlist scripts can auto-advance even from looped tracks). User-initiated stops (StopSound, StopSounds, StopAllSounds, audio3d:StopAudio) do not fire it.

Signal	Emitted When	Args
SoundFinished	A wave reaches the end of one play — non-looping voices fire once on natural end; looping voices fire every wrap. Fires for both Audio.PlaySound2D / PlaySound3D voices and Audio3D-driven voices.	SoundWave soundWave — the asset that just finished.

Example:

function MyMusicController:Start()
    SignalBus.Subscribe("SoundFinished", self, function(self, soundWave)
        if soundWave == self.musicTrack then
            self:PlayNextTrack()
        end
    end)
end

For per-node notifications on an Audio3D (without bus filtering), connect to that node's OnFinished signal instead — see Audio3D Signals.

---

Audio analysis

Real-time analysis helpers used to build visualizers (bass/mid/treble bars, spectrum graphs, loudness meters). All work on every Polyphase target — Windows, Linux, Android, GameCube/Wii, 3DS, plus any console addon that wires the stream hooks. They return 0 (or zero-filled tables) when nothing is playing on the queried voice, so visualizer code never has to special-case idle audio.

Voice index vs. streamId. A "voice index" is a slot in the engine's audio mixer pool — voices spawned through Audio.PlaySound2D/PlaySound3D and Audio3D nodes consume one. If your script already holds an Audio3D reference, prefer audio3d:GetRMS() etc. — they look up the voice index for you. A "streamId" is the value returned by AUD_OpenStream, used by push-PCM sources like the VideoPlayer addon.

---

GetDuration

Duration of the SoundWave bound to a voice slot, in seconds. Returns 0.0 for idle voices or voices with no wave assigned.

Sig: seconds = Audio.GetDuration(voiceIndex) - Arg: integer voiceIndex Voice slot - Ret: number seconds Wave duration

---

GetPlayTimeNormalized

Current playback cursor on a voice slot expressed as [0, 1] of its SoundWave's duration. Looping voices wrap (fmod); non-looping voices clamp at 1.0. Returns 0.0 for idle voices or zero-duration waves. Drop-in for progress sliders and seek bars.

Sig: t = Audio.GetPlayTimeNormalized(voiceIndex) - Arg: integer voiceIndex Voice slot - Ret: number t Normalized cursor in [0, 1]

---

GetRMS

Root-mean-square amplitude of the voice's most recent playback window. Returns 0.0 when the voice is idle.

Sig: rms = Audio.GetRMS(voiceIndex) - Arg: integer voiceIndex Voice slot - Ret: number rms RMS amplitude in [0, 1]

---

GetLoudness

Perceptual loudness in [0, 1], computed from RMS with a -60 dB floor. Drop-in for bar heights.

Sig: loudness = Audio.GetLoudness(voiceIndex) - Arg: integer voiceIndex Voice slot - Ret: number loudness Normalized loudness in [0, 1]

---

GetLoudnessDb

Raw dBFS loudness clamped to [-60, 0]. Use when you need an engineering-grade signal level.

Sig: dB = Audio.GetLoudnessDb(voiceIndex) - Arg: integer voiceIndex Voice slot - Ret: number dB Loudness in dBFS, clamped [-60, 0]

---

GetFrequencies

Average FFT magnitude in the band [startHz, endHz]. Perfect for 3-bar bass/mid/treble visualizers.

Sig: magnitude = Audio.GetFrequencies(voiceIndex, startHz, endHz) - Arg: integer voiceIndex Voice slot - Arg: number startHz Lower edge of the band (Hz) - Arg: number endHz Upper edge of the band (Hz) - Ret: number magnitude Average band magnitude

---

GetSpectrum

FFT magnitudes binned across [startHz, endHz]. Returns a Lua array of numBins floats for spectrum-style displays.

Sig: bins = Audio.GetSpectrum(voiceIndex, startHz, endHz, numBins) - Arg: integer voiceIndex Voice slot - Arg: number startHz Lower edge of the range (Hz) - Arg: number endHz Upper edge of the range (Hz) - Arg: integer numBins Number of output bins (1..1024) - Ret: { number, ... } bins Array of magnitudes, length numBins

---

GetStreamRMS

RMS for a streaming voice. Same semantics as GetRMS but indexed by the streamId returned from AUD_OpenStream.

Sig: rms = Audio.GetStreamRMS(streamId) - Arg: integer streamId Streaming voice id - Ret: number rms RMS amplitude in [0, 1]

---

GetStreamLoudness

Normalized [0, 1] loudness for a streaming voice.

Sig: loudness = Audio.GetStreamLoudness(streamId) - Arg: integer streamId Streaming voice id - Ret: number loudness Normalized loudness

---

GetStreamLoudnessDb

Raw dBFS loudness for a streaming voice (clamped [-60, 0]).

Sig: dB = Audio.GetStreamLoudnessDb(streamId) - Arg: integer streamId Streaming voice id - Ret: number dB Loudness in dBFS

---

GetStreamFrequencies

Average band magnitude for a streaming voice.

Sig: magnitude = Audio.GetStreamFrequencies(streamId, startHz, endHz) - Arg: integer streamId Streaming voice id - Arg: number startHz Lower edge of the band (Hz) - Arg: number endHz Upper edge of the band (Hz) - Ret: number magnitude Average band magnitude

---

GetStreamSpectrum

Binned spectrum for a streaming voice.

Sig: bins = Audio.GetStreamSpectrum(streamId, startHz, endHz, numBins) - Arg: integer streamId Streaming voice id - Arg: number startHz Lower edge of the range (Hz) - Arg: number endHz Upper edge of the range (Hz) - Arg: integer numBins Number of output bins (1..1024) - Ret: { number, ... } bins Array of magnitudes, length numBins

---