.. _stdlib_audio_boost: ===================================================== Audio playback, mixing, 3D spatial audio, and effects ===================================================== .. das:module:: audio_boost Module audio_boost ++++++++++++ Type aliases ++++++++++++ .. _alias-SID: .. das:attribute:: SID = uint64 Sound ID — a unique handle for every playing sound. Returned by all play functions. .. _alias-AudioSystemChannels: .. das:attribute:: AudioSystemChannels = tuple typedef AudioSystemChannels = tuple aka AudioSystemChannels +++++++++ Constants +++++++++ .. _global-audio_boost-SPEED_OF_SOUND: .. das:attribute:: SPEED_OF_SOUND = 343.3f SPEED_OF_SOUND:float const .. _global-audio_boost-MAX_SPEED_OF_OBJECT: .. das:attribute:: MAX_SPEED_OF_OBJECT = 171.65f MAX_SPEED_OF_OBJECT:float const .. _global-audio_boost-MA_CHANNELS: .. das:attribute:: MA_CHANNELS = 2 MA_CHANNELS:int const .. _global-audio_boost-MA_HRTF: .. das:attribute:: MA_HRTF = true MA_HRTF:bool const .. _global-audio_boost-INVALID_SID: .. das:attribute:: INVALID_SID = 0x0 INVALID_SID:uint64 aka SID const ++++++++++++ Enumerations ++++++++++++ .. _enum-audio_boost-AudioChannelState: .. das:attribute:: 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. .. _enum-audio_boost-ReverbPreset: .. das:attribute:: ReverbPreset enum ReverbPreset ++++++++++ Structures ++++++++++ .. _struct-audio_boost-AudioChannelStatus: .. das:attribute:: AudioChannelStatus :Fields: * **state** : :ref:`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. .. _struct-audio_boost-Attenuation: .. das:attribute:: Attenuation struct Attenuation ++++++++++++++++++++++ Audio system lifecycle ++++++++++++++++++++++ * :ref:`audio_system_collect () ` * :ref:`audio_system_create (collect: bool = false) : AudioSystemChannels ` * :ref:`audio_system_finalize (var channel: Channel?&; var collectChannel: Channel?&; var next_sid: Atomic64?) ` * :ref:`audio_system_release_context () ` * :ref:`with_audio_system (blk: block\<():void\>) ` * :ref:`with_collected_audio_system (blk: block\<():void\>) ` .. _function-audio_boost_audio_system_collect: .. das:function:: audio_system_collect() Process deferred audio cleanup. Call periodically when using with_collected_audio_system. .. _function-audio_boost_audio_system_create_bool: .. das:function:: audio_system_create(collect: bool = false) : AudioSystemChannels Low-level: creates the audio system. Prefer with_audio_system. :Arguments: * **collect** : bool .. _function-audio_boost_audio_system_finalize_Channel_q__ref__Channel_q__ref__Atomic64_q_: .. das:function:: audio_system_finalize(channel: Channel?&; collectChannel: Channel?&; next_sid: Atomic64?) Low-level: shuts down the audio system. :Arguments: * **channel** : :ref:`Channel `?\ & * **collectChannel** : :ref:`Channel `?\ & * **next_sid** : :ref:`Atomic64 `? .. _function-audio_boost_audio_system_release_context: .. das:function:: audio_system_release_context() Release the mixer context reference. .. _function-audio_boost_with_audio_system_block_ls__c_void_gr_: .. das:function:: 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 .. _function-audio_boost_with_collected_audio_system_block_ls__c_void_gr_: .. das:function:: 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 ++++++++++++++ Sound playback ++++++++++++++ * :ref:`play_3d_sound_from_file (filename: string; position: float3; attenuation: Attenuation; rate: int; channels: int) : uint64 ` * :ref:`play_3d_sound_from_pcm (position: float3; attenuation: Attenuation; rate: int; channels: int; var samples: array\) : uint64 ` * :ref:`play_3d_sound_from_pcm_stream (position: float3; attenuation: Attenuation; rate: int; channels: int) : uint64 ` * :ref:`play_3d_sound_loop_from_pcm (position: float3; attenuation: Attenuation; rate: int; channels: int; var samples: array\) : uint64 ` * :ref:`play_sound_from_file (filename: string; rate: int; channels: int) : uint64 ` * :ref:`play_sound_from_pcm (rate: int; channels: int; var samples: array\) : uint64 ` * :ref:`play_sound_from_pcm_stream (rate: int; channels: int; sid: SID = generate_sound_sid()) : uint64 ` * :ref:`play_sound_loop_from_pcm (rate: int; channels: int; var samples: array\) : uint64 ` .. _function-audio_boost_play_3d_sound_from_file_string_float3_Attenuation_int_int: .. das:function:: 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** : :ref:`Attenuation ` * **rate** : int * **channels** : int .. _function-audio_boost_play_3d_sound_from_pcm_float3_Attenuation_int_int_array_ls_float_gr_: .. das:function:: play_3d_sound_from_pcm(position: float3; attenuation: Attenuation; rate: int; channels: int; samples: array) : uint64 plays 3D sound from PCM data :Arguments: * **position** : float3 * **attenuation** : :ref:`Attenuation ` * **rate** : int * **channels** : int * **samples** : array .. _function-audio_boost_play_3d_sound_from_pcm_stream_float3_Attenuation_int_int: .. das:function:: 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** : :ref:`Attenuation ` * **rate** : int * **channels** : int .. _function-audio_boost_play_3d_sound_loop_from_pcm_float3_Attenuation_int_int_array_ls_float_gr_: .. das:function:: play_3d_sound_loop_from_pcm(position: float3; attenuation: Attenuation; rate: int; channels: int; samples: array) : uint64 plays 3D looping sound from PCM data :Arguments: * **position** : float3 * **attenuation** : :ref:`Attenuation ` * **rate** : int * **channels** : int * **samples** : array .. _function-audio_boost_play_sound_from_file_string_int_int: .. das:function:: 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 .. _function-audio_boost_play_sound_from_pcm_int_int_array_ls_float_gr_: .. das:function:: play_sound_from_pcm(rate: int; channels: int; samples: array) : uint64 plays sound from PCM data :Arguments: * **rate** : int * **channels** : int * **samples** : array .. _function-audio_boost_play_sound_from_pcm_stream_int_int_SID: .. das:function:: 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** : :ref:`SID ` .. _function-audio_boost_play_sound_loop_from_pcm_int_int_array_ls_float_gr_: .. das:function:: play_sound_loop_from_pcm(rate: int; channels: int; samples: array) : uint64 plays looping sound from PCM data :Arguments: * **rate** : int * **channels** : int * **samples** : array +++++++++++++ Sound control +++++++++++++ * :ref:`set_global_pause (pause: bool) ` * :ref:`set_global_pitch (pitch: float) ` * :ref:`set_pan (sid: SID; pan: float) : uint64 ` * :ref:`set_pause (sid: SID; paused: bool) : uint64 ` * :ref:`set_pitch (sid: SID; pitch: float) : uint64 ` * :ref:`set_playback_position (sid: SID; position: uint64) : uint64 ` * :ref:`set_volume (sid: SID; volume: float; time: float = 0.002f) : uint64 ` * :ref:`stop (sid: SID; time: float = 0f) : uint64 ` .. _function-audio_boost_set_global_pause_bool: .. das:function:: set_global_pause(pause: bool) set global pause of sounds :Arguments: * **pause** : bool .. _function-audio_boost_set_global_pitch_float: .. das:function:: set_global_pitch(pitch: float) set global pitch of sounds :Arguments: * **pitch** : float .. _function-audio_boost_set_pan_SID_float: .. das:function:: set_pan(sid: SID; pan: float) : uint64 set pan of sound :Arguments: * **sid** : :ref:`SID ` * **pan** : float .. _function-audio_boost_set_pause_SID_bool: .. das:function:: set_pause(sid: SID; paused: bool) : uint64 pause or unpause sound :Arguments: * **sid** : :ref:`SID ` * **paused** : bool .. _function-audio_boost_set_pitch_SID_float: .. das:function:: set_pitch(sid: SID; pitch: float) : uint64 set pitch of sound :Arguments: * **sid** : :ref:`SID ` * **pitch** : float .. _function-audio_boost_set_playback_position_SID_uint64: .. das:function:: set_playback_position(sid: SID; position: uint64) : uint64 set playback position for sound (in frames) :Arguments: * **sid** : :ref:`SID ` * **position** : uint64 .. _function-audio_boost_set_volume_SID_float_float: .. das:function:: set_volume(sid: SID; volume: float; time: float = 0.002f) : uint64 set volume of sound :Arguments: * **sid** : :ref:`SID ` * **volume** : float * **time** : float .. _function-audio_boost_stop_SID_float: .. das:function:: stop(sid: SID; time: float = 0f) : uint64 stop sound :Arguments: * **sid** : :ref:`SID ` * **time** : float ++++++++ 3D audio ++++++++ * :ref:`set_head_position (pos: float3; dir: float3; vel: float3 = float3(0f,0f,0f)) ` * :ref:`set_position (sid: SID; pos: float3; dir: float3 = float3(0f,0f,0f)) : uint64 ` .. _function-audio_boost_set_head_position_float3_float3_float3: .. das:function:: 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 .. _function-audio_boost_set_position_SID_float3_float3: .. das:function:: set_position(sid: SID; pos: float3; dir: float3 = float3(0f,0f,0f)) : uint64 set sound position for 3D sound :Arguments: * **sid** : :ref:`SID ` * **pos** : float3 * **dir** : float3 ++++++ Reverb ++++++ * :ref:`set_reverb (sid: SID; reverb: I3DL2ReverbProperties) : uint64 ` * :ref:`set_reverb_preset (sid: SID; preset: ReverbPreset) : uint64 ` .. _function-audio_boost_set_reverb_SID_I3DL2ReverbProperties: .. das:function:: set_reverb(sid: SID; reverb: I3DL2ReverbProperties) : uint64 set reverb for sound :Arguments: * **sid** : :ref:`SID ` * **reverb** : :ref:`I3DL2ReverbProperties ` .. _function-audio_boost_set_reverb_preset_SID_ReverbPreset: .. das:function:: set_reverb_preset(sid: SID; preset: ReverbPreset) : uint64 set reverb from preset for sound :Arguments: * **sid** : :ref:`SID ` * **preset** : :ref:`ReverbPreset ` ++++++ Chorus ++++++ * :ref:`set_chorus (sid: SID; config: ma_chorus_config) : uint64 ` * :ref:`set_chorus_default (sid: SID) : uint64 ` .. _function-audio_boost_set_chorus_SID_ma_chorus_config: .. das:function:: set_chorus(sid: SID; config: ma_chorus_config) : uint64 set chorus effect for sound :Arguments: * **sid** : :ref:`SID ` * **config** : :ref:`ma_chorus_config ` .. _function-audio_boost_set_chorus_default_SID: .. das:function:: set_chorus_default(sid: SID) : uint64 set chorus effect with default settings for sound :Arguments: * **sid** : :ref:`SID ` +++++++++++ Attenuation +++++++++++ * :ref:`compute_attenuation (attn: Attenuation; d: float) : float ` * :ref:`default_attenuation () : Attenuation ` * :ref:`inverse_distance_attenuation (dmin: float) : Attenuation ` * :ref:`inverse_square_attenuation (dmin: float) : Attenuation ` * :ref:`linear_attenuation (dmax: float) : Attenuation ` * :ref:`quadratic_attenuation (dmax: float) : Attenuation ` .. _function-audio_boost_compute_attenuation_Attenuation_float: .. das:function:: compute_attenuation(attn: Attenuation; d: float) : float compute attenuation given distance :Arguments: * **attn** : :ref:`Attenuation ` * **d** : float .. _function-audio_boost_default_attenuation: .. das:function:: default_attenuation() : Attenuation default attenuation 1 / (d + 1) .. _function-audio_boost_inverse_distance_attenuation_float: .. das:function:: inverse_distance_attenuation(dmin: float) : Attenuation DEFAULT ATTENUATION MODEL fades with inverse distance, i.e. dmin / (d + dmin) :Arguments: * **dmin** : float .. _function-audio_boost_inverse_square_attenuation_float: .. das:function:: inverse_square_attenuation(dmin: float) : Attenuation fades with inverse square distance, i.e. dmin^2 / (d^2 + dmin^2) :Arguments: * **dmin** : float .. _function-audio_boost_linear_attenuation_float: .. das:function:: linear_attenuation(dmax: float) : Attenuation fades linearly with distance, i.e 1 - d / dmax :Arguments: * **dmax** : float .. _function-audio_boost_quadratic_attenuation_float: .. das:function:: quadratic_attenuation(dmax: float) : Attenuation fades quadratically with distance, i.e 1 - d^2 / dmax^2 :Arguments: * **dmax** : float +++++++++++++++++ Status monitoring +++++++++++++++++ * :ref:`clear_status (var status: LockBox?) ` * :ref:`set_status_update (sid: SID; var status: LockBox?) : uint64 ` * :ref:`unset_status_update (sid: SID) : uint64 ` .. _function-audio_boost_clear_status_LockBox_q_: .. das:function:: clear_status(status: LockBox?) clear status for sound :Arguments: * **status** : :ref:`LockBox `? .. _function-audio_boost_set_status_update_SID_LockBox_q_: .. das:function:: set_status_update(sid: SID; status: LockBox?) : uint64 set status for sound :Arguments: * **sid** : :ref:`SID ` * **status** : :ref:`LockBox `? .. _function-audio_boost_unset_status_update_SID: .. das:function:: unset_status_update(sid: SID) : uint64 unset status for sound :Arguments: * **sid** : :ref:`SID ` ++++++++++++++++ Command batching ++++++++++++++++ * :ref:`batch (cb: block\<():void\>) ` * :ref:`begin_batch () ` * :ref:`end_batch () ` .. _function-audio_boost_batch_block_ls__c_void_gr_: .. das:function:: batch(cb: block<():void>) Execute a block of audio commands as a single atomic batch. :Arguments: * **cb** : block .. _function-audio_boost_begin_batch: .. das:function:: begin_batch() Begin batching audio commands. All commands until end_batch are sent atomically. .. _function-audio_boost_end_batch: .. das:function:: end_batch() End batching and send all batched commands atomically. ++++++++++ PCM stream ++++++++++ * :ref:`append_box_to_pcm (sid: SID; box: LockBox?; var samples: array\) : uint64 ` * :ref:`append_to_pcm (sid: SID; var samples: array\) : uint64 ` .. _function-audio_boost_append_box_to_pcm_SID_LockBox_q__array_ls_float_gr_: .. das:function:: append_box_to_pcm(sid: SID; box: LockBox?; samples: array) : 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: * **sid** : :ref:`SID ` * **box** : :ref:`LockBox `? * **samples** : array .. _function-audio_boost_append_to_pcm_SID_array_ls_float_gr_: .. das:function:: append_to_pcm(sid: SID; samples: array) : uint64 append samples to PCM stream :Arguments: * **sid** : :ref:`SID ` * **samples** : array ++++++++ Decoding ++++++++ * :ref:`decode_audio (data: array\|array\#; var channels: int&; var rate: int&) : array\ ` .. _function-audio_boost_decode_audio_array_ls_uint8_gr_array_ls_uint8_gr__hh__int_ref__int_ref_: .. das:function:: decode_audio(data: array|array#; channels: int&; rate: int&) : array 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\ #> * **channels** : int\ & * **rate** : int\ & ++++++++ Sound ID ++++++++ * :ref:`generate_sound_sid () : uint64 ` .. _function-audio_boost_generate_sound_sid: .. das:function:: generate_sound_sid() : uint64 generate unique ID for sound +++++++++++++++++++++++++++ Internal channel management +++++++++++++++++++++++++++ * :ref:`get_audio_command_channel () : void? ` * :ref:`get_collect_command_channel () : void? ` * :ref:`get_sound_sid () : void? ` * :ref:`set_audio_thread_command_channel (ch: void?) ` * :ref:`set_collect_thread_command_channel (ch: void?) ` * :ref:`set_sound_sid (next_sid: void?) ` .. _function-audio_boost_get_audio_command_channel: .. das:function:: get_audio_command_channel() : void? def get_audio_command_channel () : void? .. _function-audio_boost_get_collect_command_channel: .. das:function:: get_collect_command_channel() : void? def get_collect_command_channel () : void? .. _function-audio_boost_get_sound_sid: .. das:function:: get_sound_sid() : void? def get_sound_sid () : void? .. _function-audio_boost_set_audio_thread_command_channel_void_q_: .. das:function:: set_audio_thread_command_channel(ch: void?) .. warning:: This is unsafe operation. def set_audio_thread_command_channel (ch: void?) :Arguments: * **ch** : void? .. _function-audio_boost_set_collect_thread_command_channel_void_q_: .. das:function:: set_collect_thread_command_channel(ch: void?) .. warning:: This is unsafe operation. def set_collect_thread_command_channel (ch: void?) :Arguments: * **ch** : void? .. _function-audio_boost_set_sound_sid_void_q_: .. das:function:: set_sound_sid(next_sid: void?) def set_sound_sid (next_sid: void?) :Arguments: * **next_sid** : void?