Version: stable
FUNCTION | |
---|---|
sound.is_music_playing() | check if background music is playing |
sound.get_rms() | get RMS value from mixer group |
sound.get_peak() | get peak gain value from mixer group |
sound.set_group_gain() | set mixer group gain |
sound.get_group_gain() | get mixer group gain |
sound.get_groups() | get all mixer group names |
sound.get_group_name() | get mixer group name string |
sound.is_phone_call_active() | check if a phone call is active |
sound.play() | plays a sound |
sound.stop() | stop a playing a sound(s) |
sound.pause() | pause a playing a sound(s) |
sound.set_gain() | set sound gain |
sound.set_pan() | set sound pan |
MESSAGE | |
---|---|
play_sound | plays a sound |
stop_sound | stop a playing a sound(s) |
set_gain | set sound gain |
sound_done | reports when a sound has finished playing |
sound.is_music_playing()
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 triggeredPARAMETERS
RETURNS
playing |
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.get_rms(group,window)
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 |
group name |
window |
window length in seconds |
RETURNS
rms_l |
RMS value for left channel |
rms_r |
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.get_peak(group,window)
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 |
group name |
window |
window length in seconds |
RETURNS
peak_l |
peak value for left channel |
peak_r |
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.set_group_gain(group,gain)
20 * log(gain)
.
Inversely, to find the linear value from a dB value, use the formula
10db/20
.
PARAMETERS
group |
group name |
gain |
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.get_group_gain(group)
20 * log(gain)
.
Inversely, to find the linear value from a dB value, use the formula
10db/20
.
PARAMETERS
group |
group name |
RETURNS
gain |
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_groups()
PARAMETERS
RETURNS
groups |
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_group_name(group)
PARAMETERS
group |
group name |
RETURNS
name |
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.is_phone_call_active()
false
.
PARAMETERS
RETURNS
call_active |
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(url,[play_properties],[complete_function])
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.
PARAMETERS
url |
the sound that should play |
[play_properties] |
|
[complete_function] |
function to call when the sound has finished playing.
|
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, pan = -1.0 } )
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
sound.stop(url)
PARAMETERS
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")
sound.pause(url,pause)
PARAMETERS
url |
the sound that should pause |
pause |
true if the sound should pause |
EXAMPLES
Assuming the script belongs to an instance with a sound-component with id "sound", this will make the component pause all playing voices:sound.pause("#sound", true)
sound.set_gain(url,[gain])
20 * log(gain)
.
Inversely, to find the linear value from a dB value, use the formula
10db/20
.
PARAMETERS
url |
the sound to set the gain of |
[gain] |
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.5sound.set_gain("#sound", 0.5)
sound.set_pan(url,[pan])
PARAMETERS
url |
the sound to set the panning value to |
[pan] |
sound panning between -1.0 and 1.0 |
EXAMPLES
Assuming the script belongs to an instance with a sound-component with id "sound", this will set the gain to 0.5sound.set_pan("#sound", 0.5) -- pan to the right
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] |
delay in seconds before the sound starts playing, default is 0. |
[gain] |
sound gain between 0 and 1, default is 1. |
[play_id] |
the identifier of the sound, can be used to distinguish between consecutive plays from the same component. |
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})
stop a playing a sound(s)
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")
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] |
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.5msg.post("#sound", "set_gain", {gain = 0.5})
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] |
id number supplied when the message was posted. |