Sound

This module provides a high-level interface for playing sounds. For information on importing sound assets, see the Sounds page. It includes functions for playing 2D and 3D sounds, setting sound properties (volume, pitch, pan, etc.), and managing sound streams.

To use this module, include the following line in your project file:

require engine.sound_core // or require engine.core

Type aliases

SoundHandle = uint64

Sound Handle type

StrudelHandle = int

typedef StrudelHandle = int aka StrudelHandle

Constants

INVALID_SOUND_HANDLE = 0x0

Handle of sound that is not valid

INVALID_STRUDEL_HANDLE = 0

INVALID_STRUDEL_HANDLE:int aka StrudelHandle const

Enumerations

ReverbPreset

Reverberation presets’ enum. These presets are based on I3DL2 standard. The numbers correspond to fields of ReverbProperties struct, look at the struct for more details.

Presets:

:Values: * **Generic** = 0 -     Generic:           -1000,  -100, 1.49f, 0.83f,  -2602, 0.007f,   200, 0.011f, 100.0f, 100.0f

  • PaddedCell = 1 - PaddedCell: -1000, -600, 0.17f, 0.10f, -1204, 0.001f, 207, 0.002f, 100.0f, 100.0f

  • Room = 2 - Room: -1000, -454, 0.40f, 0.83f, -1646, 0.002f, 53, 0.003f, 100.0f, 100.0f

  • Bathroom = 3 - Bathroom: -1000, -1200, 1.49f, 0.54f, -370, 0.007f, 1030, 0.011f, 100.0f, 60.0f

  • LivingRoom = 4 - LivingRoom: -1000, -600, 0.50f, 0.10f, -1376, 0.003f, -1104, 0.004f, 100.0f, 100.0f

  • StoneRoom = 5 - StoneRoom: -1000, -300, 0.50f, 0.64f, -711, 0.012f, 83, 0.017f, 100.0f, 100.0f

  • Auditorium = 6 - Auditorium: -1000, -476, 0.60f, 0.59f, -789, 0.020f, -289, 0.030f, 100.0f, 100.0f

  • ConcertHall = 7 - ConcertHall: -1000, -500, 0.70f, 0.70f, -1230, 0.020f, -2, 0.029f, 100.0f, 100.0f

  • Cave = 8 - Cave: -1000, 0, 1.30f, 0.91f, -602, 0.015f, -302, 0.022f, 100.0f, 100.0f

  • Arena = 9 - Arena: -1000, -698, 0.33f, 0.70f, -1166, 0.020f, 16, 0.030f, 100.0f, 100.0f

  • Hangar = 10 - Hangar: -1000, -1000, 1.46f, 0.82f, -602, 0.020f, 198, 0.030f, 100.0f, 100.0f

  • CarpetedHallway = 11 - CarpetedHallway: -1000, -400, 0.30f, 0.10f, -1831, 0.002f, -1630, 0.030f, 100.0f, 100.0f

  • Hallway = 12 - Hallway: -1000, -300, 1.49f, 0.59f, -1219, 0.007f, 441, 0.011f, 100.0f, 100.0f

  • StoneCorridor = 13 - StoneCorridor: -1000, -237, 1.49f, 0.59f, -1214, 0.013f, 395, 0.020f, 100.0f, 100.0f

  • Alley = 14 - Alley: -1000, -270, 1.49f, 0.86f, -1204, 0.007f, -4, 0.011f, 100.0f, 100.0f

  • Forest = 15 - Forest: -1000, -3300, 1.49f, 0.54f, -2560, 0.162f, -613, 0.088f, 79.0f, 100.0f

  • City = 16 - City: -1000, -800, 1.49f, 0.67f, -2273, 0.007f, -2217, 0.011f, 50.0f, 100.0f

  • Mountains = 17 - Mountains: -1000, -2500, 1.49f, 0.21f, -2780, 0.300f, -2014, 0.100f, 27.0f, 100.0f

  • Quarry = 18 - Quarry: -1000, -1000, 1.49f, 0.83f, -10000, 0.061f, 500, 0.025f, 100.0f, 100.0f

  • Plain = 19 - Plain: -1000, -2000, 1.49f, 0.50f, -2466, 0.179f, -2514, 0.100f, 21.0f, 100.0f

  • ParkingLot = 20 - ParkingLot: -1000, 0, 1.65f, 1.50f, -1363, 0.008f, -1153, 0.012f, 100.0f, 100.0f

  • SewerPipe = 21 - SewerPipe: -1000, -1000, 2.81f, 0.14f, 429, 0.014f, 648, 0.021f, 80.0f, 60.0f

  • Underwater = 22 - Underwater: -1000, -4000, 1.49f, 0.10f, -449, 0.007f, 1700, 0.011f, 100.0f, 100.0f

Structures

ReverbProperties

Reverberation properties for 3D sound. These properties are based on I3DL2 standard.

Fields:

  • lRoom : int - in range [-10000, 0], default: -10000 mB - Attenuation of the room effect

  • lRoomHF : int - in range [-10000, 0], default: 0 mB - Attenuation of the room effect at high frequencies

  • flDecayTime : float - in range [0.1, 20.0], default: 1.0 s - Reverberation decay time at low frequencies

  • flDecayHFRatio : float - in range [0.1, 2.0], default: 0.5 - Ratio of the decay time at high frequencies to the decay time at low frequencies

  • lReflections : int - in range [-10000, 1000], default: -10000 mB - Attenuation of early reflections relative to lRoom

  • flReflectionsDelay : float - in range [0.0, 0.3], default: 0.02 s - Delay time of the first reflection relative to the direct path

  • lReverb : int - in range [-10000, 2000], default: -10000 mB - Attenuation of late reverberation relative to lRoom

  • flReverbDelay : float - in range [0.0, 0.1], default: 0.04 s - Time limit between the early reflections and the late reverberation relative to the time of the first reflection

  • flDiffusion : float - in range [0.0, 100.0], default: 100.0 % - Echo density in the late reverberation decay

  • flDensity : float - in range [0.0, 100.0], default: 100.0 % - Modal density in the late reverberation decay

Attenuation

A structure representing sound attenuation, the resulting attenuation is calculated as A * distance^2 + B * distance + C / (D * distance ^ 2 + E * distance + F)

Fields:

  • A : float - Coefficient for the quadratic term in the numerator

  • B : float - Coefficient for the linear term in the numerator

  • C : float - Constant term in the numerator

  • D : float - Coefficient for the quadratic term in the denominator

  • E : float - Coefficient for the linear term in the denominator

  • F : float - Constant term in the denominator

Functions

append_to_stream(sid: SoundHandle; samples: array<float>): uint64

Append sounds to the stream

Arguments:

  • sid : SoundHandle - the handle of the stream to append to

  • samples : array<float> - an array of floats that define the sound to append

Usage example:

let wave = [0.028, 0.057, 0.086, 0.115, 0.144, 0.173, 0.202, 0.231]
let handle = append_to_stream(play_sound_stream(44100, 1), wave)
default_attenuation(): Attenuation

A default attenuation model, 1 / (d + 1), which is the same as inverse_distance_attenuation(1.)

get_duration(sid: SoundHandle): float

get the duration of the active sound in seconds

Arguments:
get_playing_sounds_count(): int

Get the number of sounds that are currently playing

get_position(sid: SoundHandle): float

Get the playback position of the active sound

Arguments:
get_queued_sounds_count(): int

Get the number of queued sounds (sounds that are waiting for resource to be loaded)

get_sound_resource(sid: SoundHandle): SoundId

Get the resource id of the sound

Arguments:
get_stream_queue(sid: SoundHandle): int

Get the number of batches in the stream queue (returns 0 if the stream is empty). This function is useful for streaming sounds to check if the stream is empty. append_to_stream function can be used to add more samples to the stream.

Arguments:
get_total_sounds_count(): int

Get the number of active sounds

inverse_distance_attenuation(dmin: float): Attenuation

An attenuation model with sound pressure level fading with inverse distance, using the formula dmin / (d + dmin). This is the default attenuation model.

Arguments:

  • dmin : float

inverse_square_attenuation(dmin: float): Attenuation

An attenuation model with sound pressure level fading with inverse square distance, using the formula dmin^2 / (d^2 + dmin^2)

Arguments:

  • dmin : float

is_audio_active(): bool

Check if audio system is active

is_paused(sid: SoundHandle): bool

Check if the sound state is paused

Arguments:
is_playing(sid: SoundHandle): bool

Check if the sound state is playing or starting (the sound has already been initialized and is playing or is about to start playing)

Arguments:
is_starting(sid: SoundHandle): bool

Check if the sound state is starting (the sound has already been initialized but is not playing yet)

Arguments:
is_stopped(sid: SoundHandle): bool

Check if the sound state is stopped

Arguments:
is_stopping(sid: SoundHandle): bool

Check if the sound state is stopping (the stop has already been called and the sound is fading out)

Arguments:
iterate_sounds(cb: block<(sid:SoundHandle;in_queue:bool):void>)

Iterate over all active sounds and invoke the callback for each sound

Arguments:

  • cb : block<(sid: SoundHandle;in_queue:bool):void> - the callback that takes sound handle and sound data as parameters

Usage example:

iterate_sounds($ (sid, in_queue) {
    system_print("Sound {sid} in queue: {in_queue} playing: {is_playing(sid)} resource: {get_resource_name(get_sound_resource(sid))}")
})
linear_attenuation(dmax: float): Attenuation

An attenuation model with sound pressure level fading linearly with distance, using the formula 1 - d / dmax

Arguments:

  • dmax : float

pause(sid: SoundHandle; paused: bool = true; time: float = 0.025f): SoundHandle

Pause or resume the sound with optional fade time

Arguments:

  • sid : SoundHandle - the handle of the sound to pause or resume

  • paused : bool - true to pause, false to resume

  • time : float - fade duration in seconds (default 0.025s for smooth transition)

Returns:

Usage example:

let handle = play_sound_stream(44100, 1)
// append some sounds to stream
pause(handle, true) // pause
pause(handle, false) // resume
play_3d_sound(position: float3; attenuation: Attenuation; rate: int; channels: int; samples: array<float>): SoundHandle

Start playing the 3D sound defined by an array of floats with given rate and number of channels

Arguments:

  • position : float3 - the world position of the sound

  • attenuation : Attenuation - the attenuation of the sound

  • rate : int - the sample rate

  • channels : int - the number of channels (1 or 2)

  • samples : array<float> - an array of floats that define the sound

Returns:

Usage example:

let node : NodeId = ...
let wave = [0.028, 0.057, 0.086, 0.115, 0.144, 0.173, 0.202, 0.231]
let handle = play_3d_sound(node.worldPosition, inverse_distance_attenuation(5.), 44100, 1, wave)
play_3d_sound(res_id: SoundId; position: float3; attenuation: Attenuation): SoundHandle

Start playing the 3D sound

Arguments:

  • res_id : SoundId - the sound to play

  • position : float3 - the world position of the sound

  • attenuation : Attenuation - the attenuation of the sound

Returns:

Usage example:

let node : NodeId = ...
let soundId = request_sound("my_sound.wav")
play_3d_sound(soundId, node.worldPosition, inverse_distance_attenuation(5.))
play_3d_sound_loop(position: float3; attenuation: Attenuation; rate: int; channels: int; samples: array<float>): SoundHandle

Start playing the 3D sound as loop defined by array of floats with given rate and number of channels

Arguments:

  • position : float3 - the world position of the sound

  • attenuation : Attenuation - the attenuation of the sound

  • rate : int - the sample rate

  • channels : int - the number of channels (1 or 2)

  • samples : array<float> - an array of floats that define the sound

Returns:

  • SoundHandle - the handle of the playing 3D sound loop

Usage example:

let node : NodeId = ...
let wave = [0.028, 0.057, 0.086, 0.115, 0.144, 0.173, 0.202, 0.231]
let handle = play_3d_sound_loop(node.worldPosition, inverse_distance_attenuation(5.), 44100, 1, wave)
play_3d_sound_loop(res_id: SoundId; position: float3; attenuation: Attenuation): SoundHandle

Start playing the 3D sound as a loop

Arguments:

  • res_id : SoundId - the sound to play

  • position : float3 - the world position of the sound

  • attenuation : Attenuation - the attenuation of the sound

Returns:

  • SoundHandle - the handle of the playing 3D sound loop

Usage example:

let node : NodeId = ...
let soundId = request_sound("my_sound.wav")
play_3d_sound_loop(soundId, node.worldPosition, inverse_distance_attenuation(5.))
play_sound(rate: int; channels: int; samples: array<float>): SoundHandle

Start playing the 2D sound defined by an array of floats with given rate and number of channels

Arguments:

  • rate : int - the sample rate

  • channels : int - the number of channels (1 or 2)

  • samples : array<float> - an array of floats that define the sound

Returns:

Usage example:

let wave = [0.028, 0.057, 0.086, 0.115, 0.144, 0.173, 0.202, 0.231]
let handle = play_sound(44100, 1, wave)
play_sound(res_id: SoundId): SoundHandle

Start playing the 2D sound

Arguments:

  • res_id : SoundId - the sound to play

Returns:

Usage example:

let soundId = request_sound("my_sound.wav")
play_sound(soundId)
play_sound_loop(rate: int; channels: int; samples: array<float>): SoundHandle

Start playing the 2D sound as a loop defined by an array of floats with given rate and number of channels

Arguments:

  • rate : int - the sample rate

  • channels : int - the number of channels (1 or 2)

  • samples : array<float> - an array of floats that define the sound

Returns:

  • SoundHandle - the handle of the playing 2D sound loop

Usage example:

let wave = [0.028, 0.057, 0.086, 0.115, 0.144, 0.173, 0.202, 0.231]s
let handle = play_sound_loop(44100, 1, wave)
play_sound_loop(res_id: SoundId): SoundHandle

Start playing the 2D sound as a loop

Arguments:

  • res_id : SoundId - the sound to play

Returns:

  • SoundHandle - the handle of the playing 2D sound loop

Usage example:

let soundId = request_sound("my_sound.wav")
play_sound_loop(soundId)
play_sound_stream(rate: int; channels: int): SoundHandle

Start playing the sound stream with given rate and number of channels. Sounds can be appended to the stream using append_to_stream function.

Arguments:

  • rate : int - the sample rate

  • channels : int - the number of channels (1 or 2)

Returns:

Usage example:

let handle = play_sound_stream(44100, 1)
quadratic_attenuation(dmax: float): Attenuation

An attenuation model with sound pressure level fading quadratically with distance, using the formula 1 - d^2 / dmax^2

Arguments:

  • dmax : float

set_3d_sound_position(sid: SoundHandle; position: float3; velocity: float3 = float3(0f, 0f, 0f)): SoundHandle

Set the 3d position of the sound source and its velocity (if specified)

Arguments:

  • sid : SoundHandle - the handle of the sound

  • position : float3 - the new world position

  • velocity : float3 - the new velocity (optional)

Returns:

  • SoundHandle - the handle of the sound with changed position and velocity

Usage example:

let soundId = request_sound("my_sound.wav")
let handle = play_3d_sound_loop(soundId, float3(), inverse_distance_attenuation(5.))

let node : NodeId = ...
set_3d_sound_position(handle, node.worldPosition)
set_audio_listener_position(position: float3; dir: float3; velocity: float3 = float3(0f, 0f, 0f))

Set the 3d position of an audio listener

Arguments:

  • position : float3 - the world position of the listener

  • dir : float3 - direction to listener in world space

  • velocity : float3 - the velocity of the listener (optional)

Usage example:

let headNode : NodeId = ... // usually listener node attached to the camera
let forwardDir = headNode.worldForward // when camera is in forward (z axis) direction
set_audio_listener_position(headNode.worldPosition, forwardDir)
set_pan(sid: SoundHandle; pan: float): SoundHandle

Set the new pan of the playing sound in range [-1.0, 1.0]

Arguments:

  • sid : SoundHandle - the handle of the sound

  • pan : float - the new pan

Returns:

  • SoundHandle - the handle of the sound with the changed pan

set_pitch(sid: SoundHandle; pitch: float): SoundHandle

Set the new pitch of the playing sound, it should be greater than 0

Arguments:

  • sid : SoundHandle - the handle of the sound

  • pitch : float - the new pitch

Returns:

  • SoundHandle - the handle of the sound with the changed pitch

set_position(sid: SoundHandle; position: float): SoundHandle

Set the playback position of the sound

Arguments:

  • sid : SoundHandle - the handle of the sound

  • position : float - the new position in seconds

Returns:

  • SoundHandle - the handle of the sound with changed playback position

set_reverb(sid: SoundHandle; props: ReverbProperties): SoundHandle

Set properties of the reverberation for the sound. Note that each property should be in the range specified in the ReverbProperties struct.

Arguments:
Returns:

  • SoundHandle - the handle of the sound with the changed reverb properties

set_reverb_preset(sid: SoundHandle; preset: ReverbPreset): SoundHandle

Set one of the reverberation presets (taken from the ReverbPreset enum) for the sound

Arguments:
Returns:

  • SoundHandle - the handle of the sound with the changed reverb preset

set_volume(sid: SoundHandle; volume: float; time: float = 0f): SoundHandle

Set the volume of the playing sound in range [0.0, 1.0]

Arguments:

  • sid : SoundHandle - the handle of the sound

  • volume : float - the new volume

  • time : float - fade duration in seconds for smooth transition to the new volume (default 0 for immediate change)

Returns:

  • SoundHandle - the handle of the sound with changed volume

stop(sid: SoundHandle; time: float = 0.025f): SoundHandle

Stop the sound

Arguments:

  • sid : SoundHandle - the handle of the sound to stop

  • time : float - fade duration in seconds (default 0.025s for smooth transition)

Returns:

Usage example:

let handle = play_sound_stream(44100, 1) // or let handle = play_sound_loop() or etc.
// do something
stop(handle)
strudel_bpm(bpm: double|float|int)

Set tempo in beats per minute

Arguments:

  • bpm : option<double| float| int>

strudel_cps(cps: double|float|int)

Set tempo in cycles per second

Arguments:

  • cps : option<double| float| int>

strudel_fade(id: StrudelHandle; target_gain: float = 0f; fade_time: float = 0.025f): StrudelHandle

Fade out the strudel track with given id with specified fade time (default 0.025s for smooth transition)

Arguments:
strudel_pause(pause: bool)

Pause or resume the music

Arguments:

  • pause : bool

strudel_play(pattern: Pattern; gain: float = 1f): StrudelHandle

Start playing the strudel pattern with given gain

Arguments:
strudel_stop(id: StrudelHandle): StrudelHandle

Stop playing the strudel track with given id Use strudel_fade function for smooth fade out

Arguments:
strudel_volume(volume: float; time: float = 0.025f)

Set the master volume

Arguments:

  • volume : float

  • time : float

valid(sound: SoundHandle): bool

Check if the sound handle is valid

Arguments: