Functions and messages for controlling sound components and mixer groups.
plays a sound
Post this message to a sound-component to make it 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
.
A sound will continue to play even if the game object the sound component belonged to is deleted. You can send a stop_sound
to stop the sound.
[delay] -
number delay in seconds before the sound starts playing, default is 0.
[gain] -
number sound gain between 0 and 1, default is 1.
[play_id] -
number the identifier of the sound, can be used to distinguish between consecutive plays from the same component.
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 sound 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
.
[gain] -
number sound gain between 0 and 1, default is 1.
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})
get mixer group gain
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
.
group -
string | hash group name
gain -
number gain in linear scale
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)
get mixer group name string
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.
group -
string | hash group name
name -
string group name
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
get all mixer group names
Get a table of all mixer group names (hashes).
groups -
table table of mixer group names
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
get peak gain value from mixer group
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.
group -
string | hash group name
window -
number window length in seconds
peak_l -
number peak value for left channel
peak_r -
number peak value for right channel
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)
get RMS value from mixer group
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.
group -
string | hash group name
window -
number window length in seconds
rms_l -
number RMS value for left channel
rms_r -
number RMS value for right channel
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
check if background music is playing
Checks if background music is playing, e.g. from iTunes.
On non mobile platforms,
this function always return false
.
On Android you can only get a correct reading
of this state if your game is not playing any sounds itself. This is a limitation
in the Android SDK. If your game is playing any sounds, even with a gain of zero, this
function will return false
.
The best time to call this function is:
init
function of your main collection script before any sounds are triggeredBoth those times will give you a correct reading of the state even when your application is swapped out and in while playing sounds and it works equally well on Android and iOS.
playing -
boolean true
if music is playing, otherwise false
.
If music is playing, mute "master":
if sound.is_music_playing() then -- mute "master" sound.set_group_gain("master", 0) end
check if a phone call is 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
.
call_active -
boolean true
if there is an active phone call, false
otherwise.
Test if a phone call is on-going:
if sound.is_phone_call_active() then -- do something sensible. end
plays a sound
Make the sound component play its sound. Multiple voices are 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
.
A sound will continue to play even if the game object the sound component belonged to is deleted. You can call sound.stop()
to stop the sound.
url -
string | hash | url the sound that should play
[play_properties] -
delay
gain
pan
[complete_function] -
function(self, message_id, message, sender)) function to call when the sound has finished playing.
self
message_id
"sound_done"
.message
play_id
- the sequential play identifier that was given by the sound.play function.sender
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, pan = -1.0 } )
Using the callback argument, you can chain several sounds together:
local function sound_done(self, message_id, message, sender) -- play 'boom' sound fx when the countdown has completed if message_id == hash("sound_done") and message.play_id == self.countdown_id then sound.play("#boom", nil, sound_done) end end function init(self) self.countdown_id = sound.play("#countdown", nil, sound_done) end
set sound 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
.
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.
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)
set mixer 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
.
group -
string | hash group name
gain -
number gain in linear scale
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)
set sound pan
Set panning on all active playing voices of a sound.
The valid range is from -1.0 to 1.0, representing -45 degrees left, to +45 degrees right.
url -
string | hash | url the sound to set the panning value to
[pan] -
number sound panning between -1.0 and 1.0
Assuming the script belongs to an instance with a sound-component with id "sound", this will set the gain to 0.5
sound.set_pan("#sound", 0.5) -- pan to the right
stop a playing a sound(s)
Stop playing all active voices
url -
string | hash | url the sound that should stop
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")
reports when a sound has finished playing
This message is sent back to the sender of a play_sound
message, if the sound
could be played to completion.
[play_id] -
number id number supplied when the message was posted.
stop a playing a sound(s)
Post this message to a sound-component to make it stop playing all active voices
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")