Lua API: 7. Sound, PlayingSound

Sound

Represents a loaded sound effect.

Member functions

getName

Get the friendly name of the sound.

getPath

Get the path to the file used by the sound.

Example:

ts = SoundManager.addSound("testSound", "sfx/misc/test.flac")
Runtime.log("test sound's name is: " .. ts:getName() .. ", using file: " .. ts:getPath())

reassign

Assign another file to the sound effect.

Parameter:

• String newPath: The path to the new file.

Example:

--[[
  Assume you have 2 sound files:
  "MyGame/assets/sounds/sfx/misc/test1.flac" and
  "MyGame/assets/sounds/sfx/misc/test2.flac",
  the following code switches the file used by a Sound.
]]--
function prepare()
  ts = SoundManager.addSound("testSound", "sfx/misc/test1.flac")
  Runtime.log("using file: " .. ts:getPath())
  Runtime.log("switching file")
  ts:reassign("sfx/misc/test2.flac")
  Runtime.log("using file: " .. ts:getPath())
end

play

Play the sound effect.

Return: A PlayingSound object.

Example:

--[[
  Assume you have this sound file:
  "MyGame/assets/sounds/sfx/misc/test.flac",
  the following code plays the sound at start.
]]--
function prepare()
  ts = SoundManager.addSound("testSound", "sfx/misc/test.flac")
  tspl = ts:play()
end

---

PlayingSound

Represents a playing sound effect.

Member functions

isValid

Check if this playing sound is valid.

Return: true if the sound hasn't been played to the end or hasn't been stopped, false otherwise.

NOTE:

• If the file has failed to load, this function always return false.
• If its value is false, the PlayingSound object should be discarded and cannot be used anymore.

pause

Pause the playing sound.

Example:

--[[
  Same environment before, the following code pauses the playing sound when
  the user presses the "P" key.
]]--

-- (omit the prepare() function)

function tick()
  if Keyboard.pressed(19) and tspl ~= nil and tspl:isValid()
  then
    Runtime.log("pause")
    tspl:pause()
  end
end

resume

Resume the paused sound.

Example:

--[[
  Add the following code to the tick() function in the above example to add
  a function for the user to press the "R" key to resume playback.
]]--

-- ( function tick() )
  if Keyboard.pressed(21) and tspl ~= nil and tspl:isValid()
  then
    Runtime.log("resume")
    tspl:resume()
  end
-- ( end function tick() )

stop

Stop the sound.

Example:

--[[
  The following code adds a function to stop/start playing sound effects when
  the user presses the Backspace key.
]]--

-- ( function tick() )
  if Keyboard.pressed(42)
  then
    if tspl ~= nil and tspl:isValid()
    then
      Runtime.log("stop")
      tspl:stop()
      tspl = nil
    else
      Runtime.log("play")
      tspl = ts:play()
    end
  end
-- ( end function tick() )

volume

Get or set the volume of the playing sound.

Parameter:

• Number vol (optional): The volume of the sound, integer, from 0 (silent) to 128 (max volume).

Return: The new volume, or the current volume if the parameter "vol" is not present.

Example:

--[[
  The following code adds a function that allows the user to adjust the volume
  of the playing sound effect through the up/down arrow keys.
]]--

-- ( function tick() )
  if Keyboard.holding(82) and tspl ~= nil and tspl:isValid()
  then
    tspl:volume(tspl:volume() + 1)
  end
  
  if Keyboard.holding(81) and tspl ~= nil and tspl:isValid()
  then
    tspl:volume(tspl:volume() - 1)
  end
-- ( end function tick() )