Sound Basics[]
To load and play a sound, use this code:
s = Sound.new("username/filename.mp3")
s:play()
Allocating Multiple Copies of a Sound[]
In general, with short sounds like laser zaps, the easiest way to program it is to simply construct a new Sound object each time the laser fires, invoke the play method, and then don't even bother saving a pointer to the sound object. The sound will finish playing, and will then get garbage collected. The system is designed for this sort of programming to be efficient.
Another approach would be to construct just one copy of the 'zap' sound at the beginning of the program, and then invoke the 'play' method each time the laser fires. However, this produces a subtly different effect. If there's only one sound object, there can only be one instance of the sound playing at any given moment. If you were to play the 'zap' sound but then invoke 'play' again before it finishes, you would cut off the first playback and initiate a second one. It might sound like 'za-zap.' On the other hand, if you had two separate copies of the sound, then the two copies would play simulataneously.
Volume Control[]
By default, sounds play at maximum volume - ie, the volume with which they were recorded. You can only adjust the volume downward. One way to do this is to adjust using the decibel scale:
s:setVolumeDecibels(-10)
The decibel scale is a little hard to get used to - it may be easier to use a scale ranging from 0 to 1:
s:setVolume(0.5)
Where 0.0 is entirely silent, and 1.0 is maximum volume. This scale corresponds to decibel gain using the formula gain_in_decibels = -((1-n)*(1-n)*40.0), with the special case that 0.0 turns the sound off entirely.
Sound Queries[]
You can query the duration of a sound:
local len = s:getLength()
You can also query the status of a sound using
local status = s:status()
The possible status values are 'playing', 'idle', 'downloading', and 'error: error message'. If the sound is not already downloaded, then using the 'play' function will block until the sound finishes downloading. If you do not wish to block, then verify that it is done downloading before playing it.
Looping a Sound[]
We have not yet had time to implement sound looping. We know this is an important feature and it is coming soon. As a stopgap measure, you can start a sound, then monitor whether or not it is playing. If not, you can start it again. This isn't perfectly seamless, but it's the best that is currently possible.