16.2. Audio playback, mixing, 3D spatial audio, and effects

Module audio_boost

16.2.1. Type aliases

SID = uint64

Sound ID — a unique handle for every playing sound. Returned by all play functions.

AudioSystemChannels = tuple<command:Channel?;collect:Channel?;next_sid:Atomic64?>

typedef AudioSystemChannels = tuple<command:jobque::Channel?;collect:jobque::Channel?;next_sid:jobque::Atomic64?> aka AudioSystemChannels

16.2.2. Constants

SPEED_OF_SOUND = 343.3f

SPEED_OF_SOUND:float const

MAX_SPEED_OF_OBJECT = 171.65f

MAX_SPEED_OF_OBJECT:float const

MA_CHANNELS = 2

MA_CHANNELS:int const

MA_HRTF = true

MA_HRTF:bool const

INVALID_SID = 0x0

INVALID_SID:uint64 aka SID const

16.2.3. Enumerations

AudioChannelState
Values:

  • stopped = 0 - Channel has finished playing.

  • stopping = 1 - Channel is fading out and will stop.

  • playing = 2 - Channel is actively playing audio.

  • paused = 3 - Channel is paused.

  • starting = 4 - Channel has been created but has not started playing yet.

ReverbPreset

enum ReverbPreset

16.2.4. Structures

AudioChannelStatus
Fields:

  • state : AudioChannelState - Current playback state.

  • playback_position : uint64 - Current playback position in PCM frames.

  • consumed_position : uint64 - Frames of actual audio consumed (excludes silence padding).

  • stream_que_length : int - Number of pending PCM chunks in the stream queue.

Attenuation

struct Attenuation

16.2.5. Audio system lifecycle

audio_system_collect()

Process deferred audio cleanup. Call periodically when using with_collected_audio_system.

audio_system_create(collect: bool = false): AudioSystemChannels

Low-level: creates the audio system. Prefer with_audio_system.

Arguments:

  • collect : bool

audio_system_finalize(channel: Channel?&; collectChannel: Channel?&; next_sid: Atomic64?)

Low-level: shuts down the audio system.

Arguments:
audio_system_release_context()

Release the mixer context reference.

with_audio_system(blk: block<():void>)

Initializes the audio system, runs the block, then shuts down. All audio API calls must happen inside this block.

Arguments:

  • blk : block<void>

with_collected_audio_system(blk: block<():void>)

Initializes the audio system with garbage collection, runs the block, then shuts down. Use audio_system_collect to process deferred cleanup.

Arguments:

  • blk : block<void>

16.2.6. Sound playback

play_3d_sound_from_file(filename: string; position: float3; attenuation: Attenuation; rate: int; channels: int): uint64

plays 3D sound from file note - this function is blocking for the duration of the decoder creation

Arguments:

  • filename : string

  • position : float3

  • attenuation : Attenuation

  • rate : int

  • channels : int

play_3d_sound_from_pcm(position: float3; attenuation: Attenuation; rate: int; channels: int; samples: array<float>): uint64

plays 3D sound from PCM data

Arguments:

  • position : float3

  • attenuation : Attenuation

  • rate : int

  • channels : int

  • samples : array<float>

play_3d_sound_from_pcm_stream(position: float3; attenuation: Attenuation; rate: int; channels: int): uint64

Create a 3D PCM streaming channel. Feed it samples with append_to_pcm.

Arguments:

  • position : float3

  • attenuation : Attenuation

  • rate : int

  • channels : int

play_3d_sound_loop_from_pcm(position: float3; attenuation: Attenuation; rate: int; channels: int; samples: array<float>): uint64

plays 3D looping sound from PCM data

Arguments:

  • position : float3

  • attenuation : Attenuation

  • rate : int

  • channels : int

  • samples : array<float>

play_sound_from_file(filename: string; rate: int; channels: int): uint64

plays sound from file note - this function is blocking for the duration of the decoder creation

Arguments:

  • filename : string

  • rate : int

  • channels : int

play_sound_from_pcm(rate: int; channels: int; samples: array<float>): uint64

plays sound from PCM data

Arguments:

  • rate : int

  • channels : int

  • samples : array<float>

play_sound_from_pcm_stream(rate: int; channels: int; sid: SID = generate_sound_sid()): uint64

Create a PCM streaming channel. Feed it samples with append_to_pcm.

Arguments:

  • rate : int

  • channels : int

  • sid : SID

play_sound_loop_from_pcm(rate: int; channels: int; samples: array<float>): uint64

plays looping sound from PCM data

Arguments:

  • rate : int

  • channels : int

  • samples : array<float>

16.2.7. Sound control

set_global_pause(pause: bool)

set global pause of sounds

Arguments:

  • pause : bool

set_global_pitch(pitch: float)

set global pitch of sounds

Arguments:

  • pitch : float

set_pan(sid: SID; pan: float): uint64

set pan of sound

Arguments:

  • sid : SID

  • pan : float

set_pause(sid: SID; paused: bool): uint64

pause or unpause sound

Arguments:

  • sid : SID

  • paused : bool

set_pitch(sid: SID; pitch: float): uint64

set pitch of sound

Arguments:

  • sid : SID

  • pitch : float

set_playback_position(sid: SID; position: uint64): uint64

set playback position for sound (in frames)

Arguments:

  • sid : SID

  • position : uint64

set_volume(sid: SID; volume: float; time: float = 0.002f): uint64

set volume of sound

Arguments:

  • sid : SID

  • volume : float

  • time : float

stop(sid: SID; time: float = 0f): uint64

stop sound

Arguments:

  • sid : SID

  • time : float

16.2.8. 3D audio

set_head_position(pos: float3; dir: float3; vel: float3 = float3(0f, 0f, 0f))

set head position for 3D sound

Arguments:

  • pos : float3

  • dir : float3

  • vel : float3

set_position(sid: SID; pos: float3; dir: float3 = float3(0f, 0f, 0f)): uint64

set sound position for 3D sound

Arguments:

  • sid : SID

  • pos : float3

  • dir : float3

16.2.9. Reverb

set_reverb(sid: SID; reverb: I3DL2ReverbProperties): uint64

set reverb for sound

Arguments:
set_reverb_preset(sid: SID; preset: ReverbPreset): uint64

set reverb from preset for sound

Arguments:

16.2.10. Chorus

set_chorus(sid: SID; config: ma_chorus_config): uint64

set chorus effect for sound

Arguments:
set_chorus_default(sid: SID): uint64

set chorus effect with default settings for sound

Arguments:

16.2.11. Attenuation

compute_attenuation(attn: Attenuation; d: float): float

compute attenuation given distance

Arguments:
default_attenuation(): Attenuation

default attenuation 1 / (d + 1)

inverse_distance_attenuation(dmin: float): Attenuation

DEFAULT ATTENUATION MODEL fades with inverse distance, i.e. dmin / (d + dmin)

Arguments:

  • dmin : float

inverse_square_attenuation(dmin: float): Attenuation

fades with inverse square distance, i.e. dmin^2 / (d^2 + dmin^2)

Arguments:

  • dmin : float

linear_attenuation(dmax: float): Attenuation

fades linearly with distance, i.e 1 - d / dmax

Arguments:

  • dmax : float

quadratic_attenuation(dmax: float): Attenuation

fades quadratically with distance, i.e 1 - d^2 / dmax^2

Arguments:

  • dmax : float

16.2.12. Status monitoring

clear_status(status: LockBox?)

clear status for sound

Arguments:
set_status_update(sid: SID; status: LockBox?): uint64

set status for sound

Arguments:
unset_status_update(sid: SID): uint64

unset status for sound

Arguments:

16.2.13. Command batching

batch(cb: block<():void>)

Execute a block of audio commands as a single atomic batch.

Arguments:

  • cb : block<void>

begin_batch()

Begin batching audio commands. All commands until end_batch are sent atomically.

end_batch()

End batching and send all batched commands atomically.

16.2.14. PCM stream

append_box_to_pcm(sid: SID; box: LockBox?; samples: array<float>): uint64

append samples from lock box to PCM stream. Box is grabbed and released on audio thread. samples buffer must outlive the grab — caller keeps it alive until box.isReady.

Arguments:
append_to_pcm(sid: SID; samples: array<float>): uint64

append samples to PCM stream

Arguments:

  • sid : SID

  • samples : array<float>

16.2.15. Decoding

decode_audio(data: array<uint8>|array<uint8>#; channels: int&; rate: int&): array<float>

Decode an audio file (MP3, WAV, FLAC, Vorbis) from raw bytes to PCM float samples. Returns interleaved sample data; sets channels and rate.

Arguments:

  • data : option<array<uint8>| array<uint8>#>

  • channels : int&

  • rate : int&

16.2.16. Sound ID

generate_sound_sid(): uint64

generate unique ID for sound

16.2.17. Internal channel management

get_audio_command_channel(): void?

def get_audio_command_channel () : void?

get_collect_command_channel(): void?

def get_collect_command_channel () : void?

get_sound_sid(): void?

def get_sound_sid () : void?

set_audio_thread_command_channel(ch: void?)

Warning

This is unsafe operation.

def set_audio_thread_command_channel (ch: void?)

Arguments:

  • ch : void?

set_collect_thread_command_channel(ch: void?)

Warning

This is unsafe operation.

def set_collect_thread_command_channel (ch: void?)

Arguments:

  • ch : void?

set_sound_sid(next_sid: void?)

def set_sound_sid (next_sid: void?)

Arguments:

  • next_sid : void?