springroll.Sound Class

Extends springroll.EventDispatcher
Defined in: springroll.Sound:19
Module: Sound

Acts as a wrapper for SoundJS as well as adding lots of other functionality for managing sounds.

_getSoundInst

(
  • channel
  • id
)
SoundInstance
private

Defined in _getSoundInst:979

Gets a SoundInstance, from the pool if available or maks a new one if not.

Parameters:

  • channel createjs.SoundInstance

    A createjs SoundInstance to initialize the object with.

  • id String

    The alias of the sound that is going to be used.

Returns:

SoundInstance:

The SoundInstance that is ready to use.

_markLoaded

(
  • alias
  • callback
)
private

Defined in _markLoaded:1533

Marks a sound as loaded. If it needs to play after the load, then it is played.

Parameters:

  • alias String

    The alias of the sound to mark.

  • callback Function

    A function to call to show that the sound is loaded.

_onSoundComplete

(
  • inst
)
private

Defined in _onSoundComplete:1092

The callback used for when a sound instance is complete.

Parameters:

  • inst SoundInstance

    The SoundInstance that is complete.s

_playAfterload

(
  • result
)
private

Defined in _playAfterload:1005

Plays a sound after it finishes loading.

Parameters:

  • result String | Object

    The sound to play as an alias or load manifest.

_playEmpty

()
private

Defined in _playEmpty:336

Satisfies the iOS event needed to initialize the audio Note that we listen on touchend as per http://www.holovaty.com/writing/ios9-web-audio/

_poolinst

(
  • inst
)
private

Defined in _poolinst:1598

Places a SoundInstance back in the pool for reuse.

Parameters:

  • inst SoundInstance

    The instance to repool.

_stopInst

(
  • inst
)
private

Defined in _stopInst:1162

Stops and repools a specific SoundInstance.

Parameters:

  • inst SoundInstance

    The SoundInstance to stop.

_stopSound

(
  • s
)
private

Defined in _stopSound:1146

Stops all playing SoundInstances for a sound.

Parameters:

  • s Object

    The sound (from the _sounds dictionary) to stop.

_update

(
  • elapsed
)
private

Defined in _update:747

The update call, used for fading sounds. This is bound to the instance of Sound

Parameters:

  • elapsed Int

    The time elapsed since the previous frame, in milliseconds.

addContext

(
  • config
)
Sound
public

Defined in addContext:418

Loads a context config object. This should not be called until after Sound.init() is complete.

Parameters:

  • config Object

    The config to load.

    • [context] String optional

      The optional sound context to load sounds into unless otherwise specified by the individual sound. Sounds do not require a context.

    • [path=""] String optional

      The path to prepend to all sound source urls in this config.

    • [preload=false] Boolean optional

      Option to preload all sound files in this context..

    • sounds Array

      The list of sounds, either as String ids or Objects with settings.

      • listItem Object | String
        Not actually a property called listItem, but an entry in the array. If this is a string, then it is the same as {'id':''}.
      • listItem.id String
        The id to reference the sound by.
      • [listItem.src] String optional
        The src path to the file, without an extension. If omitted, defaults to id.
      • [listItem.volume=1] Number optional
        The default volume for the sound, from 0 to 1.
      • [listItem.loop=false] Boolean optional
        If the sound should loop by default whenever the loop parameter in play() is not specified.
      • [listItem.context] String optional
        A context name to override config.context with.
      • [listItem.preload] Boolean optional
        If the sound should be preloaded immediately.

Returns:

Sound:

The sound object for chaining

contextExists

(
  • context
)
Boolean
public

Defined in contextExists:542

If a context exists

Parameters:

  • context String

    The name of context to look for.

Returns:

Boolean:

true if the context exists, false otherwise.

destroy

()
public

Inherited from springroll.EventDispatcher but overwritten in destroy:1615

Destroys springroll.Sound. This unloads loaded sounds in SoundJS.

exists

(
  • alias
)
Boolean
public

Defined in exists:530

If a sound exists in the list of recognized sounds.

Parameters:

  • alias String

    The alias of the sound to look for.

Returns:

Boolean:

true if the sound exists, false otherwise.

fadeIn

(
  • aliasOrInst
  • [duration=500]
  • [targetVol]
  • [startVol=0]
)
public

Defined in fadeIn:636

Fades a sound from 0 to a specified volume.

Parameters:

  • aliasOrInst String | SoundInstance

    The alias of the sound to fade the last played instance of, or an instance returned from play().

  • [duration=500] Number optional

    The duration in milliseconds to fade for. The default is 500ms.

  • [targetVol] Number optional

    The volume to fade to. The default is the sound's default volume.

  • [startVol=0] Number optional

    The volume to start from. The default is 0.

fadeOut

(
  • aliasOrInst
  • [duration=500]
  • [targetVol=0]
  • [startVol]
  • [stopAtEnd]
)
public

Defined in fadeOut:683

Fades a sound from the current volume to a specified volume. A sound that ends at 0 volume is stopped after the fade.

Parameters:

  • aliasOrInst String | SoundInstance

    The alias of the sound to fade the last played instance of, or an instance returned from play().

  • [duration=500] Number optional

    The duration in milliseconds to fade for. The default is 500ms.

  • [targetVol=0] Number optional

    The volume to fade to. The default is 0.

  • [startVol] Number optional

    The volume to fade from. The default is the current volume.

  • [stopAtEnd] Boolean optional

    If the sound should be stopped when the fade completes. The default is to stop it if the fade completes at a volume of 0.

getDuration

(
  • alias
)
Int | Null
public

Defined in getDuration:607

Gets the duration of a sound in milliseconds, if it has been loaded.

Parameters:

  • alias String

    The alias of the sound to look for.

Returns:

Int | Null:

The duration of the sound in milliseconds. If the sound has not been loaded, 0 is returned. If no sound exists by that alias, null is returned.

has

(
  • name
  • [callback]
)
Boolean

Inherited from springroll.EventDispatcher: has:230

Checks if the EventDispatcher has a specific listener or any listener for a given event.

Parameters:

  • name String

    The name of the single event type to check for

  • [callback] Function optional

    The listener function to check for. If omitted, checks for any listener.

Returns:

Boolean:

If the EventDispatcher has the specified listener.

init

(
  • options
)
Sound
static

Defined in init:171

Initializes the Sound singleton. If using createjs.FlashAudioPlugin, you will be responsible for setting createjs.FlashAudioPlugin.BASE_PATH.

Parameters:

  • options Object | Function

    Either the options object or the ready function

    • [plugins=createjs.WebAudioPlugin,createjs.FlashAudioPlugin] Array optional

      The SoundJS plugins to pass to createjs.Sound.registerPlugins().

    • [types=['ogg','mp3']] Array optional

      The order in which file types are preferred, where "ogg" becomes a ".ogg" extension on all sound file urls.

    • [swfPath='assets/swfs/'] String optional

      The required path to the createjs.FlashAudioPlugin SWF

    • [ready] Function optional

      A function to call when initialization is complete.

Returns:

Sound:

The new instance of the sound object

isLoaded

(
  • alias
)
Boolean
public

Defined in isLoaded:566

If a sound is loaded.

Parameters:

  • alias String

    The alias of the sound to look for.

Returns:

Boolean:

true if the sound is loaded, false if it is not loaded or does not exist.

isLoading

(
  • alias
)
Boolean
public

Defined in isLoading:578

If a sound is in the process of being loaded

Parameters:

  • alias String

    The alias of the sound to look for.

Returns:

Boolean:

A value of true if the sound is currently loading, false if it is loaded, unloaded, or does not exist.

isPlaying

(
  • alias
)
Boolean
public

Defined in isPlaying:591

If a sound is playing.

Parameters:

  • alias String

    The alias of the sound to look for.

Returns:

Boolean:

A value of true if the sound is currently playing or loading with an intent to play, false if it is not playing or does not exist.

isUnloaded

(
  • alias
)
Boolean
public

Defined in isUnloaded:554

If a sound is unloaded.

Parameters:

  • alias String

    The alias of the sound to look for.

Returns:

Boolean:

true if the sound is unloaded, false if it is loaded, loading, or does not exist.

linkContexts

(
  • parent
  • subContext
)
Boolean

Defined in linkContexts:498

Links one or more sound contexts to another in a parent-child relationship, so that the children can be controlled separately, but still be affected by setContextMute(), stopContext(), pauseContext(), etc on the parent. Note that sub-contexts are not currently affected by setContextVolume().

Parameters:

  • parent String

    The id of the SoundContext that should be the parent.

  • subContext String | Array

    The id of a SoundContext to add to parent as a sub-context, or an array of ids.

Returns:

Boolean:

true if the sound exists, false otherwise.

loadConfig

(
  • config
)
springroll.Sound
deprecated

Defined in loadConfig:33

Deprecated: since version 0.3.0

Add a configuration to the load, see addContext

Parameters:

  • config Object

    The configuration

Returns:

springroll.Sound:

Sound object for chaining

off

(
  • name
  • callback
)
EventDispatcher

Inherited from springroll.EventDispatcher: off:172

Remove the event listener

Parameters:

  • name String*

    The type of event string separated by spaces, if no name is specifed remove all listeners.

  • callback Function | Array*

    The listener function or collection of callback functions

Returns:

EventDispatcher:

Return this EventDispatcher for chaining calls.

on

(
  • name
  • callback
  • [priority=0]
)
EventDispatcher

Inherited from springroll.EventDispatcher: on:98

Add an event listener. The parameters for the listener functions depend on the event.

Parameters:

  • name String | Object

    The type of event (can be multiple events separated by spaces), or a map of events to handlers

  • callback Function | Array*

    The callback function when event is fired or an array of callbacks.

  • [priority=0] Int optional

    The priority of the event listener. Higher numbers are handled first.

Returns:

EventDispatcher:

Return this EventDispatcher for chaining calls.

once

(
  • name
  • callback
  • [priority=0]
)
EventDispatcher

Inherited from springroll.EventDispatcher: once:83

Add an event listener but only handle it one time.

Parameters:

  • name String | Object

    The type of event (can be multiple events separated by spaces), or a map of events to handlers

  • callback Function | Array*

    The callback function when event is fired or an array of callbacks.

  • [priority=0] Int optional

    The priority of the event listener. Higher numbers are handled first.

Returns:

EventDispatcher:

Return this EventDispatcher for chaining calls.

pause

(
  • alias
)
public

Defined in pause:1225

Pauses a specific sound.

Parameters:

  • alias String

    The alias of the sound to pause. Internally, this can also be the object from the _sounds dictionary directly.

pauseAll

()
public

Defined in pauseAll:1341

Pauses all sounds.

pauseContext

(
  • context
)

Defined in pauseContext:1284

Pauses all sounds in a given context. Audio paused this way will not be resumed with resumeAll(), but must be resumed individually or with resumeContext().

Parameters:

  • context String

    The name of the context to pause.

pauseContext

(
  • context
)

Defined in pauseContext:1313

Resumes all sounds in a given context.

Parameters:

  • context String

    The name of the context to pause.

pauseSound

(
  • alias
)
deprecated public

Defined in pauseSound:84

Deprecated: since version 0.4.0

Unpauses a specific sound, see pause

Parameters:

  • alias String

    The alias of the sound to pause.

play

(
  • alias
  • [options]
)
SoundInstance
public

Defined in play:800

Plays a sound.

Parameters:

  • alias String

    The alias of the sound to play.

  • [options] Object | Function optional

    The object of optional parameters or complete callback function.

    • [complete] Function optional

      An optional function to call when the sound is finished.

    • [start] Function optional

      An optional function to call when the sound starts playback. If the sound is loaded, this is called immediately, if not, it calls when the sound is finished loading.

    • [interrupt=false] Boolean optional

      If the sound should interrupt previous sounds (SoundJS parameter). Default is false.

    • [delay=0] Number optional

      The delay to play the sound at in milliseconds (SoundJS parameter). Default is 0.

    • [offset=0] Number optional

      The offset into the sound to play in milliseconds (SoundJS parameter). Default is 0.

    • [loop=0] Int optional

      How many times the sound should loop. Use -1 (or true) for infinite loops (SoundJS parameter). Default is no looping.

    • [volume] Number optional

      The volume to play the sound at (0 to 1). Omit to use the default for the sound.

    • [pan=0] Number optional

      The panning to start the sound at (-1 to 1). Default is centered (0).

Returns:

SoundInstance:

An internal SoundInstance object that can be used for fading in/out as well as pausing and getting the sound's current position.

preload

(
  • list
  • [callback]
)
public

Defined in preload:1466

Preloads a list of sounds.

Parameters:

  • list Array | String

    An alias or list of aliases to load.

  • [callback] Function optional

    The function to call when all sounds have been loaded.

preloadSound

(
  • alias
  • callback
)
deprecated

Defined in preloadSound:46

Deprecated: since version 0.4.0

Preload a single sound, see preload

Parameters:

  • alias String

    The sound to preload

  • callback Function

    Callback when complete

resume

(
  • alias
)
public

Defined in resume:1258

Unpauses a specific sound.

Parameters:

  • alias String

    The alias of the sound to pause. Internally, this can also be the object from the _sounds dictionary directly.

resumeAll

()
public

Defined in resumeAll:1353

Unpauses all sounds that were paused with pauseAll(). This does not unpause audio that was paused individually or with pauseContext().

setContextMute

(
  • context
  • muted
)
public

Defined in setContextMute:1387

Sets mute status of all sounds in a context

Parameters:

  • context String

    The name of the context to modify.

  • muted Boolean

    If the context should be muted.

setContextVolume

(
  • context
  • volume
)
public

Defined in setContextVolume:1435

Sets volume of a context. Individual sound volumes are multiplied by this value.

Parameters:

  • context String

    The name of the context to modify.

  • volume Number

    The volume for the context (0 to 1).

(
  • filetypeOrder
  • callback
)
private

Defined in :359

When the initialization as completed

Parameters:

  • filetypeOrder Array

    The list of files types

  • callback Function

    The callback function

stop

(
  • alias
)
public

Defined in stop:1120

Stops all playing or loading instances of a given sound.

Parameters:

  • alias String

    The alias of the sound to stop.

stopAll

()

Defined in stopAll:1213

Stop all sounds that are playing, regardless of context.

stopContext

(
  • context
)
public

Defined in stopContext:1185

Stops all sounds in a given context.

Parameters:

  • context String

    The name of the context to stop.

trigger

(
  • type
  • arguments
)

Inherited from springroll.EventDispatcher: trigger:48

Dispatch an event

Parameters:

  • type String

    The type of event to trigger

  • arguments

    Additional parameters for the listener functions.

type

(
  • value
)
String
private

Inherited from springroll.EventDispatcher: type:259

Return type of the value.

Parameters:

  • value

Returns:

String:

The type

unload

(
  • list
)
public

Defined in unload:1558

Unloads a list of sounds to reclaim memory if possible. If the sounds are playing, they are stopped.

Parameters:

  • list Array

    An array of sound aliases to unload.

unloadAll

()
public

Defined in unloadAll:1582

Unloads all sounds. If any sounds are playing, they are stopped. Internally this calls unload.

unpauseAll

()
deprecated public

Defined in unpauseAll:59

Deprecated: since version 0.4.0

Unpauses all sounds, see resumeAll

unpauseSound

(
  • alias
)
deprecated public

Defined in unpauseSound:71

Deprecated: since version 0.4.0

Unpauses a specific sound, see resume

Parameters:

  • alias String

    The alias of the sound to resume.

_contexts

Object private

Defined in _contexts:66

Dictionary of SoundContexts.

_destroyed

Boolean protected

Inherited from springroll.EventDispatcher: _destroyed:24

If the dispatcher is destroyed

_fades

Array private

Defined in _fades:45

Array of SoundInstance objects that are being faded in or out.

_listeners

Object private

Inherited from springroll.EventDispatcher: _listeners:17

The collection of listeners

_pool

Array private

Defined in _pool:52

Array of SoundInstance objects waiting to be used.

_sounds

Object private

Defined in _sounds:38

Dictionary of sound objects, containing configuration info and playback objects.

destroyed

Boolean

Inherited from springroll.EventDispatcher: destroyed:35

If the dispatcher is destroyed

instance

Sound public static

Defined in instance:404

The singleton instance of Sound.

isSupported

Boolean

Defined in isSupported:78

If sound is enabled. This will only be false if Sound was unable to initialize a SoundJS plugin.

muteAll

Boolean

Defined in muteAll:1423

Set the mute status of all sounds

preventDefaultOnUnmute

Boolean

Defined in preventDefaultOnUnmute:95

If preventDefault should be called on the interaction event that unmutes the audio. In most cases (games) you would want to leave this, but for a website you may want to disable it.

Default: true

soundEnabled

Boolean deprecated

Defined in soundEnabled:18

Deprecated: since version 0.4.10

If sound is supported on the device/browser, see isSupported

supportedSound

String public

Defined in supportedSound:59

The extension of the supported sound type that will be used.

systemMuted

Boolean

Defined in systemMuted:86

If sound is currently muted by the system. This will only be true on iOS until audio has been unmuted during a touch event. Listen for the 'systemUnmuted' event on Sound to be notified when the audio is unmuted on iOS.

systemUnmuted

Defined in systemUnmuted:105

Fired when audio is unmuted on iOS. If systemMuted is false, this will not be fired (or already has been fired).