Sound Manager (ssk.soundMgr.*)

The Sound Manager is a basic sound effects and music manager with these functions and listeners:

Functions
add	addEffect	addMusic	dump
enableSFX	enableMusic	load	setDebugLevel
setMaxMusicChannels	setVolume	stop	stopAll
release	releaseAll

Listeners
onSound (Effect)	onSound (Music)

Adding Sounds

There is one 'generic' function for adding sounds and two helper functions that call it.

ssk.soundMgr.add( name, path [, params ] )

ssk.soundMgr.addEffect( name, path [, params ] )

ssk.soundMgr.addMusic( name, path [, params ] )

name - Name to identify sound by in future.
- Must be unique.
- Case-sensitive.
path - Full path (including file name) to sound file.
params ({}) - Table of named parameters to configure sound.
- soundType (effect) - Must be effect or music.
  - Helper functions override this parameter to match their type.
- baseDir (system.ResourceDirectory) - Folder type for path.
- preload (false) - Preload this sound.
- sticky (nil) - If true, this sound is skipped during normal release.
- minTweenTime (nil) - Set this to a positive non-zero value to keep sounds from flooding (playing repeatedly and too quickly).
  - This prevents this sound from repeating any sooner than minTweenTime milliseconds.
  - This is handy for sound effects that can happen quickly and can be used as a basic 'flood control'.


soundMgr.add( "click", "sounds/sfx/click.mp3", { soundType = "effect", preload = true, minTweenTime = 200 } )

soundMgr.addEffect( "explosion", "sounds/sfx/explosion.wav", { preload = true, sticky = true } )

soundMgr.addMusic( "Sugar Plum Breakdown", "sounds/music/Sugar Plum Breakdown.mp3" )

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.
onComplete (nil) - Optional listener to execute when done playing sound.

Playing Sound Effects


post( "onSound", { sound = "click" } )

Playing Music


post( "onSound", { sound = "Sugar Plum Breakdown", fadein = 1500 } )

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.

Tip: Do this before you start playing sounds.

ssk.soundMgr.setMaxMusicChannels( [ max ] )

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.

Complete Example


local soundMgr = ssk.soundMgr

soundMgr.enableSFX( true )

soundMgr.enableMusic( true )

soundMgr.setVolume(0.8)

soundMgr.setVolume(0.5, "music")

soundMgr.setDebugLevel( 1 )

soundMgr.add( "click", "sounds/sfx/click.mp3", { preload = true, minTweenTime = 200 } )

soundMgr.addEffect( "explosion", "sounds/sfx/explosion.wav", { preload = true, sticky = true } )

soundMgr.addMusic( "Sugar Plum Breakdown", "sounds/music/Sugar Plum Breakdown.mp3" )

soundMgr.release( "click" )

soundMgr.release( "explosion" )

post( "onSound", { sound = "click" } )

nextFrame( function() post( "onSound", { sound = "click" } ) end, 100 )

timer.performWithDelay( 2000, 
    function()
        post( "onSound", { sound = "explosion" } )
        nextFrame( function() post( "onSound", { sound = "explosion" } ) end, 250 )
    end )

local function onComplete()
    print("All sounds should be done.")
    soundMgr.dump()
end

timer.performWithDelay( 3000, 
    function()
        post( "onSound", 
              { sound = "Sugar Plum Breakdown", fadein = 1500, 
                loops = 0, onComplete = onComplete } )
    end )

timer.performWithDelay( 3500, 
    function()
        print("Stopping early.")
        soundMgr.stopAll("music")
    end )