SoundJS

SoundJS  0.3.0

SoundJS > SoundJS > SoundJS
Search:
 
Filters

Class SoundJS

The public API for creating sounds, and controlling the overall sound levels, and affecting multiple sounds at once. All SoundJS APIs are static. SoundJS can also be used as a PreloadJS plugin to help preload audio properly.

Constructor

SoundJS ( )

Properties

activePlugin - static Object

The currently active plugin. If this is null, then no plugin could be initialized. If no plugin was specified, only the HTMLAudioPlugin is tested.
Default Value: null

AUDIO_TIMEOUT - static Number

The duration in milliseconds to determine a timeout.
Default Value: 8000

DELIMITER - static String

Determine how audio is split, when multiple paths are specified in a source.
Default Value: |

INTERRUPT_ANY - static String

The interrupt value to use to interrupt any currently playing instance with the same source.
Default Value: any

INTERRUPT_EARLY - static String

The interrupt value to use to interrupt the earliest currently playing instance with the same source.
Default Value: early

INTERRUPT_LATE - static String

The interrupt value to use to interrupt the latest currently playing instance with the same source.
Default Value: late

INTERRUPT_NONE - static String

The interrupt value to use to interrupt no currently playing instances with the same source.
Default Value: none

muted - {Boolean}

SoundJS is currently muted. No audio will play, unless existing instances are unmuted. This property is read-only.
Default Value: false

PLAY_FAILED - static String

Defines the playState of an instance that failed to play. This is usually caused by a lack of available channels when the interrupt mode was "INTERRUPT_NONE", the playback stalled, or the sound could not be found.
Default Value: playFailed

PLAY_FINISHED - static String

Defines the playState of an instance that completed playback.
Default Value: playFinished

PLAY_INITED - static String

Defines the playState of an instance that is still initializing.
Default Value: playInited

PLAY_INTERRUPTED - static String

Defines the playState of an instance that was interrupted by another instance.
Default Value: playInterrupted

PLAY_SUCCEEDED - static String

Defines the playState of an instance that is currently playing or paused.
Default Value: playSucceeded

Methods

beginPlaying

protected void beginPlaying ( )
Begin playback. This is called immediately, or after delay by SoundJS.beginPlaying
Returns: void

checkPlugin

void checkPlugin ( initializeDefault )
Determine if a plugin has been initialized. Optionally initialize the default plugin, which enables SoundJS to work without manually setting up the plugins.
Parameters:
initializeDefault <Boolean> Determines if the default plugin should be initialized if there is not yet a plugin when this is checked.
Returns: void

getCapabilities

static Object getCapabilities ( )
Get the active plugin's capabilities, which help determine if a plugin can be used in the current environment, or if the plugin supports a specific feature. Capabilities include:
  • panning: If the plugin can pan audio from left to right
  • volume; If the plugin can control audio volume.
  • mp3: If MP3 audio is supported.
  • ogg: If OGG audio is supported.
  • wav: If WAV audio is supported.
  • mpeg: If MPEG audio is supported.
  • channels: The maximum number of audio channels that can be created.
Returns: Object
An object containing the capabilities of the active plugin.

getCapability

static String | Number | Boolean getCapability ( key )
Get a specific capability of the active plugin. See the getCapabilities for a full list of capabilities.
Parameters:
key <String> The capability to retrieve
Returns: String | Number | Boolean
The capability value.

getInstanceById

static SoundInstance getInstanceById ( uniqueId )
Get a SoundInstance by a unique id. It is often useful to store audio instances by id (in form elements for example), so this method provides a useful way to access the instances via their IDs.
Parameters:
uniqueId <object> The id to use as lookup.
Returns: SoundInstance
The sound instance with the specified ID.

getMasterVolume

static Number getMasterVolume ( )
Get the master volume. All sounds multiply their current volume against the master volume.
Returns: Number
The master volume

getSrcFromId

static String getSrcFromId ( value )
Get the source of a sound via the ID passed in with the manifest. If no ID is found the value is passed back.
Parameters:
value <object> The name or src of a sound.
Returns: String
The source of the sound.

isReady

static Boolean isReady ( )
Determines if SoundJS has been initialized, and a plugin has been activated.
Returns: Boolean
If SoundJS has initialized a plugin.

pause

static pause ( id )
Pause all instances.
Parameters:
id <object> The specific sound ID (set) to target.

play

static SoundInstance play ( value , interrupt , delay , offset , loop , volume , pan )
Play a sound, receive an instance to control. If the sound failed to play, the soundInstance will still be returned, and have a playState of SoundJS.PLAY_FAILED. Note that even on sounds with failed playback, you may still be able to call play(), since the failure could be due to lack of available channels.
Parameters:
value <String> The src or ID of the audio.
interrupt <String> How to interrupt other instances of audio. Values are defined as constants on SoundJS.
delay <Number> The amount of time to delay the start of the audio. Delay is in milliseconds.
offset <Number> The point to start the audio. Offset is in milliseconds.
loop <Number> Determines how many times the audio loops when it reaches the end of a sound. Default is 0 (no loops). Set to -1 for infinite.
volume <Number> The volume of the sound, between 0 and 1
pan <Number> The left-right pan of the sound (if supported), between -1 (left) and 1 (right)
Returns: SoundInstance
A SoundInstance that can be controlled after it is created.

playInstance

protected Boolean playInstance ( )
Play an instance. This is called by the static API, as well as from plugins. This allows the core class to control delays.
Returns: Boolean
If the sound can start playing.

registerPlugin

static Boolean registerPlugin ( plugin )
Register a SoundJS plugin. Plugins handle the actual playing of audio. By default the HTMLAudio plugin will be installed if no other plugins are present when the user starts playback.
Parameters:
plugin <Object> The plugin class to install.
Returns: Boolean
Whether the plugin was successfully initialized.

registerPlugins

static Boolean registerPlugins ( plugins )
Register a list of plugins, in order of precedence.
Parameters:
plugins <Array> An array of plugins to install.
Returns: Boolean
Whether a plugin was successfully initialized.

resume

static resume ( id )
Resume all instances. Note that the pause/resume methods do not work independantly of each instance's paused state. If one instance is already paused when the SoundJS.pause method is called, then it will resume when this method is called.
Parameters:
id <object> The specific sound ID (set) to target.

setMasterVolume

static Boolean setMasterVolume ( value )
To set the volume of all instances at once, use the setVolume() method.
Parameters:
value <Number> The master volume to set.
Returns: Boolean
If the master volume was set.

setMute

static Boolean setMute ( isMuted , id )
Mute/Unmute all audio. Note that muted audio still plays at 0 volume, and that individually muted audio will be affected by setting the global mute.
Parameters:
isMuted <Boolean> Whether the audio should be muted or not.
id <String> The specific sound ID (set) to target.
Returns: Boolean
If the mute was set.

setVolume

static Boolean setVolume ( The , id )
Set the volume of all sounds. This sets the volume value of all audio, and is not a "master volume". Use setMasterVolume() instead.
Parameters:
The <Number> volume to set on all sounds. The acceptable range is 0-1.
id <String> Optional, the specific sound ID to target.
Returns: Boolean
If the volume was set.

stop

static stop ( id )
Stop all audio (Global stop).
Parameters:
id <object> The specific sound ID (set) to target.