Sound API documentation

Functions and messages for controlling sound components and mixer groups.

Version: stable

Functions

sound.get_group_gain()

sound.get_group_gain(group)

Get mixer group gain

PARAMETERS

RETURNS

EXAMPLES

local gain = sound.get_group_gain("soundfx")
local gain_db = 60 * 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

RETURNS

EXAMPLES

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).

PARAMETERS

None

RETURNS

EXAMPLES

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

RETURNS

EXAMPLES

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

RETURNS

EXAMPLES

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

• In the init function of your main collection script before any sounds are triggered
• In a window listener callback when the window.WINDOW_EVENT_FOCUS_GAINED event is received

PARAMETERS

None

RETURNS

EXAMPLES

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.

PARAMETERS

None

RETURNS

EXAMPLES

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

sound.pause()

sound.pause(url,pause)

Pause all active voices

PARAMETERS

EXAMPLES

sound.pause("#sound", true)

sound.play()

sound.play(url,play_properties,complete_function)

Make the sound component play its sound. Multiple voices are supported. The limit is set to 32 voices per sound component. 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

RETURNS

EXAMPLES

sound.play("#sound", { delay = 1, gain = 0.9, 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.set_gain()

sound.set_gain(url,gain)

Set gain on all active playing voices of a sound.

PARAMETERS

EXAMPLES

sound.set_gain("#sound", 0.9)

sound.set_group_gain()

sound.set_group_gain(group,gain)

Set mixer group gain

PARAMETERS

EXAMPLES

sound.set_group_gain("soundfx", 0.5)

sound.set_pan()

sound.set_pan(url,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.

PARAMETERS

EXAMPLES

sound.set_pan("#sound", 0.5) -- pan to the right

sound.stop()

sound.stop(url,stop_properties)

Stop playing all active voices or just one voice if play_id provided

PARAMETERS

EXAMPLES

sound.stop("#sound")
local id = sound.play("#sound")
sound.stop("#sound", {play_id = id})

Messages

play_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. play_id should be specified in case you want to receive sound_done or sound_stopped in on_message().

EXAMPLES

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

-- use `play_id` and `msg.post()` if you want to recieve `sound_done` or `sound_stopped` in on_message()
function init()
 msg.post("#sound", "play_sound", {play_id = 1, delay = 1, gain = 0.5})
end

function on_message(self, message_id, message)
 if message_id == hash("sound_done") then
     print("Sound play id: "..message.play_id)
 end
end

set_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.

EXAMPLES

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

sound_done

This message is sent back to the sender of a play_sound message if the sound could be played to completion and a play_id was provided with the play_sound message.

sound_stopped

This message is sent back to the sender of a play_sound message, if the sound has been manually stopped and a play_id was provided with the play_sound message.

stop_sound

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

EXAMPLES

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

Properties

gain

The gain on the sound-component. Note that gain is in linear scale, between 0 and 1.

EXAMPLES

function init(self)
  local gain = go.get("#sound", "gain")
  go.set("#sound", "gain", gain * 1.5)
end

pan

The pan on the sound-component. The valid range is from -1.0 to 1.0, representing -45 degrees left, to +45 degrees right.

EXAMPLES

function init(self)
  local pan = go.get("#sound", "pan")
  go.set("#sound", "pan", pan * -1)
end

sound

The sound data used when playing the sound. The type of the property is hash.

EXAMPLES

function init(self)
  -- load a wav file bundled as a custom resource
  local wav = sys.load_resource("foo.wav")
  -- get resource path to the sound component
  local resource_path = go.get("#sound", "sound")
  -- update the resource with the loaded wav file
  resource.set_sound(resource_path, wav)
  -- play the updated sound
  sound.play("#sound")
end

speed

The speed on the sound-component where 1.0 is normal speed, 0.5 is half speed and 2.0 is double speed.

EXAMPLES

function init(self)
  local speed = go.get("#sound", "speed")
  go.set("#sound", "speed", speed * 0.5)
end