Loading Sounds

When adding sounds you may specify to preload or not preload each sound. Additionally, you may force a sound file to load at any time.

Tip 1: Once a file is loaded it won't re-load if you try to load again.Tip 2: If you attempt to play an un-loaded sound, it will be loaded automatically, but this could cause a slight delay for large sounds files. So, preloading or force-loading before you need to play a sound is generally a good idea.

ssk.soundMgr.addMusic( name )

name - Name of previously added sound that you wish to load.

Playing Sounds

There is no function to play a sound directly. Instead, sound effects and music are both played using the onSound event.

This may seem weird at first, but it is by design. The idea is that, once you have configured the sound manager, you should be able to play a sound from anywhere with a single line of code. No fuss, no muss.

The onSound event takes a number of (mostly optional) arguments:

sound (required) - Name of sound (must match previously added sound).

loops (1) - Optional number of times to loop sound:

-1 or 0 - Infinite.

N > 0 - N times.

duration (nil) - If specified, sound plays up to this many milliseconds and auto-stops.

fadein (nil) - If specified, fade up from 0 to channel volume over fadein milliseconds.

Playing Sound Effects

Playing Music

Tip: If you try to play the same music while it is playing already, you will get a warning and the second attempt will fail.

Stopping Sounds

You can stop individual sounds, categories or sounds ("effect" or "music") or all sounds.

Unlike playing sounds, stopping sounds is a direct call because it is typically done from a single location in games and apps, so there is no need for 'distributed access'.

Stop

Use this function to stop all playing instances of a specific sound:

ssk.soundMgr.stop( name )

name - Name of sound to stop.

Stop All

Use this function to stop categories of sounds ("effect" or "music") or all sounds.

ssk.soundMgr.stopAll( [ stopType ] )

stopType (nil) - Type of sounds to stop.

nil - All sounds.

"effect" - Effect sounds.

"music" - Music sounds.

Freeing (Releasing) Memory

You are responsible for freeing memory used by sounds you no longer need loaded. Fortunately, the Sound Manager makes this easy.

Warning: Releasing a sound will stop any instance(s) of that sound currently being played.

Release

You can release the memory associated with any single sound (as long as it is not currently playing) with this function:

ssk.soundMgr.release( name [, force ] )

name - Name of sound (must match previously added sound).

force (false) - Set this to true for force sticky sounds to be removed.

Release All

You can release the memory associated with any single sound (as long as it is not currently playing) with this function:

ssk.soundMgr.releaseAll( [ releaseType [, force ] ] )

releaseType (nil) - Type of sounds to release.

nil - All sounds.

"effect" - Effect sounds.

"music" - Music sounds.

force (false) - Set this to true for force sticky sounds to be removed.

Tip: If you try to play the same music while it is playing already, you will get a warning and the second attempt will fail.

Configuring the Sound Manager

Max Music Channels

By default, the manager allocates four music channels for music and the rest (28) are for sound effects. This is typically enough, but if you feel it won't be, simply call this function with the number of max channels you want held aside for music.

Volume Control

By default, all channels are set at max volume (1.0), but the Sound Manager give you complete control of these volume:

Global Volume - Multiplier for all channels.

Effect Volume - Multiplier for "effect" channels.

Music Volume - Multiplier for "music" channels.

The volume for any sound is determined by this equation:

Channel Volume == Global Volume x Type Volume

ssk.soundMgr.setVolume( volume [ , volType ] )

volume (1.0) - Volume level in range [0,1].

volType (nil) - Volume type to set:

nil - Global

effect - Effect channels.

music - Music channels.

Tip: While you usually do this during initialization, you can change volumes any time.

Enabling Effects

By default, effect sounds are enabled, but you can disable them at any time by passing false to this function (defaults to true):

ssk.soundMgr.enableSFX( [ enable ] )

Tip: Disabling does not stop currently playing sounds. It prevents new ones from starting.

Enabling Music

By default, music sounds are enabled, but you can disable them at any time by passing false to this function (defaults to true):

ssk.soundMgr.enableMusic( [ enable ] )

Tip: Disabling does not stop currently playing sounds. It prevents new ones from starting.

Debugging

By default, only warnings and error messages are printed to the console. However, while you are working on your game/app, you may find it useful to get additional information. This module supports three levels of debug messaging.

ssk.soundMgr.setDebugLevel( [ level ] )

level (0) - Debug messaging level to use after this call.

0 - None.

1 - Basic messages.

2 - Verbose.

Tip: Disabling does not stop currently playing sounds. It prevents new ones from starting.