-
Notifications
You must be signed in to change notification settings - Fork 2
Class: Sound
Sound is a class that abstracts some of the details of managing sounds, such as sound effects and music. Its main feature is managing the allocation of sources so you can play multiple instances of a sound hassle-free.
When instantiating the Sound class, you can tell it whether or not this sound is "long" or "short". All this really determines is what new sources are created from. If a sound is long, a source will be created from the sound's file path. If a sound is short, an instance of SoundData will be created from the sound's file path on initialisation and then used to create sources when needed.
SoundData stores decoded sound data, which isn't cheap to store in memory. However, since it's already decoded, it's faster to create sources from it (at least in theory). This is why it should be used for shorter sounds; short sounds have a lot less data in them, and are usually played a lot more often.
All you really need to know is that you should use short sounds for stuff like sounds effects, and long sounds for stuff like music and background ambience.
Sound manages sources by maintaining a dynamically growing pool (or, collection) of them. When Sound:play is called, Sound will look for a source in the pool that is not playing (determined via Source:isStopped); if it finds one, it will use that source to play the sound. If a stopped source can't be found, a new one will be created and added to the pool. This means the pool will dynamically grow to the needs of the sound.
If you want to clear the pool of all stopped sources, or even every source, stopped or not, you can use Sound:clearStopped or Sound:clearAll, respectively.
count
The number of sources in this sound's pool.
data
The data that this sound uses to make a new source. If long is false then this will be an instance of SoundData. If not, then this will be a string containing the file path of the sound file. Note that you can't set this.
defaultPan
The default X pan that sources are given when created by this sound. The default is 0.
defaultVolume
The default volume that sources are given when created by this sound. The default is 1.
file
A string containing the file path of the sound file. If long is true, this will be equal to data. Note that you can't set this.
long
If true, the sound is "long." If false, the sound is "short." Note that you can't set this.
initialize(file, long, volume, pan)
Initialises the sound.
file: A string denoting the path to the sound file. Can also be a SoundData object (if the sound is "short").
long: If true, the sound will be "long". If false, the sound will be "short". Defaults to false.
volume: Sets defaultVolume to this.
pan: Sets defaultPan pan to this.
clearAll()
Removes all sources, stopped or not, from the pool.
clearStopped()
Removes all stopped sources (determined via determined via Source:isStopped) from the pool.
loop(volume, pan)
Same as Sound:play, but sets the source to loop before returning it.
volume: Will set the source's volume to this instead of defaultVolume.
pan: Will set the source's X pan to this instead of defaultPan.
pause(last)
Pauses all non-stopped sources, or only the last played source, if specified.
last: If true, only the last played source will be paused. Defaults to false.
play(volume, pan)
Creates and plays a new source for this sound, which it returns.
volume: Will set the source's volume to this instead of defaultVolume.
pan: Will set the source's X pan to this instead of defaultPan.
resume(last)
Resumes all non-stopped sources, or only the last played source, if specified.
last: If true, only the last played source will be resumed. Defaults to false.
rewind(last)
Rewinds all non-stopped sources, or only the last played source, if specified.
last: If true, only the last played source will be rewound. Defaults to false.
stop(last)
Ensures that all sources are stopped, or only the last played source, if specified.
last: If true, only the last played source will be stopped. Defaults to false.