Using Audio in SLUDGE

SLUDGE can play various audio files, split into two overall types... track-based music formats (such as .MOD and .XM files) and sampled sound formats (.WAV and .OGG).

Sampled sounds:

Sampled sounds can be used for speech, sound effects and music. SLUDGE supports .WAV and .OGG files of any frequency and depth (i.e. 8 or 16 bit).

You can play sampled sounds using the playSound function - simply specify the file handle of the sample file as the parameter. Alternatively, sounds can be looped using the loopSound function (instead of the sound playing once and stopping, it plays repeatedly). Sounds can be stopped by the stopSound function.

When sampled sounds are played using either of the above functions, they are played at the volume most recently specified by the setDefaultSoundVolume function. If this function has not yet been called, the default sound volume is 255 - or, in other words, full.

After a sound has started playing, its volume can be changed using setSoundVolume and the function setSoundLoopPoints can be used to change the start and end points at which a sample played using loopSound loops.

Preloading sounds before you need them:

You can use the cacheSound function to load (and, if required, decompress) a sound file into memory without playing it. This means there's no pause when you actually come to play the sound, because it's already been loaded.

Using the freeSound function you can also remove sounds from the cache once you no longer need them, although this is only really worthwhile for huge sounds (music, for example). Sounds are also removed from the cache automatically once they become old - it can only hold 8 files at once. Call getSoundCache to determine the contents of the cache at any given moment.

Stopping one sound when starting another:

If one sound is to "replace" another (for example, a looping wind sound effect which should stop at the same time as a slamming door sound effect starts) it is wise to start the new sound effect before stopping the old one, rather than the other way around:

loopSound ('badweather.wav');
say (ego, 'I'm not going out there...');
addOverlay ('closeddoor.tga', 100, 100);
playSound ('slam.wav');
stopSound ('badweather.wav');
say (ego, 'That's better.');

This is because the playSound function has to load the sound to be played from the data file before it can be started. For small sound files this is almost instantaneous, but for larger files this can create a slight pause while the sound is being loaded into memory. Using the order above, the old sound will still be playing during this period.

Track-based music:

Music support in SLUDGE works slightly differently... it is possible to play only 3 track-based music files at any one time on channels numbered 0 to 2. Therefore, when playing a music file you must also specify on which channel you wish to play it (this is all achieved using one call to the startMusic function). This makes sure that SLUDGE doesn't accidentally play it instead of another file which you wanted to keep playing too.

After starting a piece of music, any further music command (for example, the stopMusic function, which stops a song playing) will use these channel numbers rather than the file handles. For example...

var t = pickOne ('slow.xm', 'fast.s3m', 'punkrock.mod', 'samba.mid');
startMusic (t, 2);
pause (100);
stopMusic (2);

This will play 100 frames-worth of a random tune and then stop, no matter which tune was picked. Should any music be playing on either channel 0 or channel 1 at the time, it will not be affected.

Like sampled sounds, SLUDGE can set the default volume at which songs will start playing (using the setDefaultMusicVolume function) and also change the volume at which each channel is currently playing (using the setMusicVolume function).