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

Constants

INVALID_SOUND_HANDLE = 0x0

Handle of sound that is not valid

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:

Generic:           -1000,  -100, 1.49f, 0.83f,  -2602, 0.007f,   200, 0.011f, 100.0f, 100.0f
PaddedCell:        -1000,  -600, 0.17f, 0.10f,  -1204, 0.001f,   207, 0.002f, 100.0f, 100.0f
Room:              -1000,  -454, 0.40f, 0.83f,  -1646, 0.002f,    53, 0.003f, 100.0f, 100.0f
Bathroom:          -1000, -1200, 1.49f, 0.54f,   -370, 0.007f,  1030, 0.011f, 100.0f,  60.0f
LivingRoom:        -1000,  -600, 0.50f, 0.10f,  -1376, 0.003f, -1104, 0.004f, 100.0f, 100.0f
StoneRoom:         -1000,  -300, 0.50f, 0.64f,   -711, 0.012f,    83, 0.017f, 100.0f, 100.0f
Auditorium:        -1000,  -476, 0.60f, 0.59f,   -789, 0.020f,  -289, 0.030f, 100.0f, 100.0f
ConcertHall:       -1000,  -500, 0.70f, 0.70f,  -1230, 0.020f,    -2, 0.029f, 100.0f, 100.0f
Cave:              -1000,     0, 1.30f, 0.91f,   -602, 0.015f,  -302, 0.022f, 100.0f, 100.0f
Arena:             -1000,  -698, 0.33f, 0.70f,  -1166, 0.020f,    16, 0.030f, 100.0f, 100.0f
Hangar:            -1000, -1000, 1.46f, 0.82f,   -602, 0.020f,   198, 0.030f, 100.0f, 100.0f
CarpetedHallway:   -1000,  -400, 0.30f, 0.10f,  -1831, 0.002f, -1630, 0.030f, 100.0f, 100.0f
Hallway:           -1000,  -300, 1.49f, 0.59f,  -1219, 0.007f,   441, 0.011f, 100.0f, 100.0f
StoneCorridor:     -1000,  -237, 1.49f, 0.59f,  -1214, 0.013f,   395, 0.020f, 100.0f, 100.0f
Alley:             -1000,  -270, 1.49f, 0.86f,  -1204, 0.007f,    -4, 0.011f, 100.0f, 100.0f
Forest:            -1000, -3300, 1.49f, 0.54f,  -2560, 0.162f,  -613, 0.088f,  79.0f, 100.0f
City:              -1000,  -800, 1.49f, 0.67f,  -2273, 0.007f, -2217, 0.011f,  50.0f, 100.0f
Mountains:         -1000, -2500, 1.49f, 0.21f,  -2780, 0.300f, -2014, 0.100f,  27.0f, 100.0f
Quarry:            -1000, -1000, 1.49f, 0.83f, -10000, 0.061f,   500, 0.025f, 100.0f, 100.0f
Plain:             -1000, -2000, 1.49f, 0.50f,  -2466, 0.179f, -2514, 0.100f,  21.0f, 100.0f
ParkingLot:        -1000,     0, 1.65f, 1.50f,  -1363, 0.008f, -1153, 0.012f, 100.0f, 100.0f
SewerPipe:         -1000, -1000, 2.81f, 0.14f,    429, 0.014f,   648, 0.021f,  80.0f,  60.0f
Underwater:        -1000, -4000, 1.49f, 0.10f,   -449, 0.007f,  1700, 0.011f, 100.0f, 100.0f
Values:

  • Generic = 0

  • PaddedCell = 1

  • Room = 2

  • Bathroom = 3

  • LivingRoom = 4

  • StoneRoom = 5

  • Auditorium = 6

  • ConcertHall = 7

  • Cave = 8

  • Arena = 9

  • Hangar = 10

  • CarpetedHallway = 11

  • Hallway = 12

  • StoneCorridor = 13

  • Alley = 14

  • Forest = 15

  • City = 16

  • Mountains = 17

  • Quarry = 18

  • Plain = 19

  • ParkingLot = 20

  • SewerPipe = 21

  • Underwater = 22

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

  • B : float

  • C : float

  • D : float

  • E : float

  • F : float

Functions

valid(sound: SoundHandle): bool

Check if the sound handle is valid

Arguments:
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

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

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

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

default_attenuation(): Attenuation

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

is_audio_active(): bool

Check if audio system is active

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_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_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_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_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_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_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_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)
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)
stop(sid: SoundHandle; time: float = 0.025f): SoundHandle

Stop the sound

Arguments:

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

  • time : float - time in seconds for the sound to smoothly stop

Returns:

Usage example:

let handle = play_sound_stream(44100, 1) // or let handle = play_sound_loop() or etc.
// do something
stop(handle)
pause(sid: SoundHandle; paused: bool = true): SoundHandle

Pause or resume the sound

Arguments:

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

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

Returns:

Usage example:

let handle = play_sound_stream(44100, 1)
// append some sounds to stream
pause(handle, true) // pause
pause(handle, false) // resume
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_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 - time in seconds for the sound volume to smoothly change

Returns:

  • SoundHandle - the handle of the sound with changed volume

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_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_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)
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_playing(sid: SoundHandle): bool

Check if the sound state is playing

Arguments:
is_paused(sid: SoundHandle): bool

Check if the sound state is paused

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:
is_stopped(sid: SoundHandle): bool

Check if the sound state is stopped

Arguments:
get_position(sid: SoundHandle): float

Get the playback position of the active sound

Arguments:
get_duration(sid: SoundHandle): float

get the duration of the active sound in seconds

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:
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_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

get_sound_resource(sid: SoundHandle): SoundId

Get the resource id of the sound

Arguments:
get_total_sounds_count(): int

Get the number of active sounds

get_queued_sounds_count(): int

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

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))}")
})
get_playing_sounds_count(): int

Get the number of sounds that are currently playing