- Select ref document -

Sound API documentation

version 1.2.144

Functions and messages for controlling sound components and mixer groups.

Functions

sound.get_group_gain

sound.get_group_gain(group)

Get mixer group gain

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10db/20.

Parameters

group

string | hash group name

group

string | hash group name

Returns

gain

number gain in linear scale

gain

number gain in linear scale

Examples

Get the mixer group gain for the "soundfx" and convert to dB:

local gain = sound.get_group_gain("soundfx")
local gain_db = 20 * log(gain)

sound.get_group_name

sound.get_group_name(group)

Get a mixer group name as a string.

This function is to be used for debugging and development tooling only. The function does a reverse hash lookup, which does not return a proper string value when the game is built in release mode.

Parameters

group

string | hash group name

group

string | hash group name

Returns

name

string group name

name

string group name

Examples

Get the mixer group string names so we can show them as labels on a dev mixer overlay:

local groups = sound.get_groups()
for _,group in ipairs(groups) do
    local name = sound.get_group_name(group)
    msg.post("/mixer_overlay#gui", "set_mixer_label", { group = group, label = name})
end

sound.get_groups

sound.get_groups()

Get a table of all mixer group names (hashes).

Returns

groups

table table of mixer group names

groups

table table of mixer group names

Examples

Get the mixer groups, set all gains to 0 except for "master" and "soundfx" where gain is set to 1:

local groups = sound.get_groups()
for _,group in ipairs(groups) do
    if group == hash("master") or group == hash("soundfx") then
        sound.set_group_gain(group, 1)
    else
        sound.set_group_gain(group, 0)
    end
end

sound.get_peak

sound.get_peak(group, window)

Get peak value from mixer group.

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10db/20. Also note that the returned value might be an approximation and in particular the effective window might be larger than specified.

Parameters

group

string | hash group name

window

number window length in seconds

group

string | hash group name

window

number window length in seconds

Returns

peak_l

number peak value for left channel

peak_r

number peak value for right channel

peak_l

number peak value for left channel

peak_r

number peak value for right channel

Examples

Get the peak gain from the "master" group and convert to dB for displaying:

local left_p, right_p = sound.get_peak("master", 0.1)
left_p_db = 20 * log(left_p)
right_p_db = 20 * log(right_p)

sound.get_rms

sound.get_rms(group, window)

Get RMS (Root Mean Square) value from mixer group. This value is the square root of the mean (average) value of the squared function of the instantaneous values.

For instance: for a sinewave signal with a peak gain of -1.94 dB (0.8 linear), the RMS is 0.8 × 1/sqrt(2) which is about 0.566.

Note the returned value might be an approximation and in particular the effective window might be larger than specified.

Parameters

group

string | hash group name

window

number window length in seconds

group

string | hash group name

window

number window length in seconds

Returns

rms_l

number RMS value for left channel

rms_r

number RMS value for right channel

rms_l

number RMS value for left channel

rms_r

number RMS value for right channel

Examples

Get the RMS from the "master" group where a mono -1.94 dB sinewave is playing:

local rms = sound.get_rms("master", 0.1) -- throw away right channel.
print(rms) --> 0.56555819511414

sound.is_music_playing

sound.is_music_playing()

Checks if background music is playing, e.g. from iTunes.

On non mobile platforms, this function always return false.

Returns

playing

boolean true if music is playing, otherwise false.

playing

boolean true if music is playing, otherwise false.

Examples

If music is playing, mute "master":

if sound.is_music_playing() then
    -- mute "master"
    sound.set_group_gain("master", 0)
end

sound.is_phone_call_active

sound.is_phone_call_active()

Checks if a phone call is active. If there is an active phone call all other sounds will be muted until the phone call is finished.

On non mobile platforms, this function always return false.

Returns

call_active

boolean true if there is an active phone call, false otherwise.

call_active

boolean true if there is an active phone call, false otherwise.

Examples

Test if a phone call is on-going:

if sound.is_phone_call_active() then
    -- do something sensible.
end

sound.play

sound.play(url, [play_properties])

Make the sound component play its sound. Multiple voices is supported. The limit is set to 32 voices per sound component.

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10db/20.

Parameters

url

string | hash | url the sound that should play

[play_properties]
table optional table with properties:
delay
number delay in seconds before the sound starts playing, default is 0.
gain
number sound gain between 0 and 1, default is 1. The final gain of the sound will be a combination of this gain, the group gain and the master gain.
url

string | hash | url the sound that should play

[play_properties]
table optional table with properties:
delay
number delay in seconds before the sound starts playing, default is 0.
gain
number sound gain between 0 and 1, default is 1. The final gain of the sound will be a combination of this gain, the group gain and the master gain.

Examples

Assuming the script belongs to an instance with a sound-component with id "sound", this will make the component play its sound after 1 second:

sound.play("#sound", { delay = 1, gain = 0.5 } )

sound.set_gain

sound.set_gain(url, [gain])

Set gain on all active playing voices of a sound.

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10db/20.

Parameters

url

string | hash | url the sound to set the gain of

[gain]

number sound gain between 0 and 1. The final gain of the sound will be a combination of this gain, the group gain and the master gain.

url

string | hash | url the sound to set the gain of

[gain]

number sound gain between 0 and 1. The final gain of the sound will be a combination of this gain, the group gain and the master gain.

Examples

Assuming the script belongs to an instance with a sound-component with id "sound", this will set the gain to 0.5

sound.set_gain("#sound", 0.5)

sound.set_group_gain

sound.set_group_gain(group, gain)

Set mixer group gain

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10db/20.

Parameters

group

string | hash group name

gain

number gain in linear scale

group

string | hash group name

gain

number gain in linear scale

Examples

Set mixer group gain on the "soundfx" group to -4 dB:

local gain_db = -4
local gain = 10^gain_db/20 -- 0.63095734448019
sound.set_group_gain("soundfx", gain)

sound.stop

sound.stop(url)

Stop playing all active voices

Parameters

url

string | hash | url the sound that should stop

url

string | hash | url the sound that should stop

Examples

Assuming the script belongs to an instance with a sound-component with id "sound", this will make the component stop all playing voices:

sound.stop("#sound")

Messages

play_sound

"play_sound", { [delay=…], [gain=…] }

Post this message to a sound-component to make it play its sound. Multiple voices is support. The limit is set to 32 voices per sound component.

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10db/20.

Fields

[delay]

number delay in seconds before the sound starts playing, default is 0.

[gain]

number sound gain between 0 and 1, default is 1.

[delay]

number delay in seconds before the sound starts playing, default is 0.

[gain]

number sound gain between 0 and 1, default is 1.

Examples

Assuming the script belongs to an instance with a sound-component with id "sound", this will make the component play its sound after 1 second:

msg.post("#sound", "play_sound", {delay = 1, gain = 0.5})

set_gain

"set_gain", { [gain=…] }

Post this message to a sound-component to set gain on all active playing voices.

Note that gain is in linear scale, between 0 and 1. To get the dB value from the gain, use the formula 20 * log(gain). Inversely, to find the linear value from a dB value, use the formula 10db/20.

Fields

[gain]

number sound gain between 0 and 1, default is 1.

[gain]

number sound gain between 0 and 1, default is 1.

Examples

Assuming the script belongs to an instance with a sound-component with id "sound", this will set the gain to 0.5

msg.post("#sound", "set_gain", {gain = 0.5})

stop_sound

"stop_sound"

Post this message to a sound-component to make it stop playing all active voices

Examples

Assuming the script belongs to an instance with a sound-component with id "sound", this will make the component stop all playing voices:

msg.post("#sound", "stop_sound")