SoundJS v1.0.0 API Documentation : WebAudioPlugin (original) (raw)

WebAudioPlugin Class

Play sounds using Web Audio in the browser. The WebAudioPlugin is currently the default plugin, and will be used anywhere that it is supported. To change plugin priority, check out the Sound APIregisterPlugins method.

Known Browser and OS issues for Web Audio

Firefox 25

• mp3 audio files do not load properly on all windows machines, reported here.
  For this reason it is recommended to pass another FireFox-supported type (i.e. ogg) as the default extension, until this bug is resolved

Webkit (Chrome and Safari)

• AudioNode.disconnect does not always seem to work. This can cause the file size to grow over time if you are playing a lot of audio files.

iOS 6 limitations

• Sound is initially muted and will only unmute through play being called inside a user initiated event (touch/click). Please read the mobile playback notes in the the Sound class for a full overview of the limitations, and how to get around them.
• A bug exists that will distort un-cached audio when a video element is present in the DOM. You can avoid this bug by ensuring the audio and video audio share the same sample rate.

Constructor

• Index
• Methods
• Properties

Item Index

Methods

• _addPropsToClasses static
• _compatibilitySetUp static
• _createAudioContext static
• _generateCapabilities static
• _handlePreloadComplete
• _handlePreloadError
• _isFileXHRSupported static
• _unlock
• _updateVolume
• create
• getVolume
• isPreloadComplete
• isPreloadStarted
• isSupported static
• playEmptySound static
• preload
• register
• removeAllSounds
• removeSound
• setMute
• setVolume

Properties

• _audioSources
• _capabilities static
• _panningModel
• _panningModel static
• _scratchBuffer static
• _unlocked
• _volume
• context
• context static
• DEFAULT_SAMPLE_REATE static
• dynamicsCompressorNode
• gainNode

Methods

_addPropsToClasses

() protected static

Set up needed properties on supported classes WebAudioSoundInstance and WebAudioLoader.

_compatibilitySetUp

() private static

Set up compatibility if only deprecated web audio calls are supported. See http://www.w3.org/TR/webaudio/#DeprecationNotesNeeded so we can support new browsers that don't support deprecated calls (Firefox) as well as old browsers that don't support new calls.

_createAudioContext

() AudioContext | webkitAudioContext private static

Create an audio context for the sound.

This method handles both vendor prefixes (specifically webkit support), as well as a case on iOS where audio played with a different sample rate may play garbled when first started. The default sample rate is 44,100, however it can be changed using the WebAudioPlugin/DEFAULT_SAMPLE_RATE:property.

Returns:

AudioContext | webkitAudioContext:

_generateCapabilities

() private static

Determine the capabilities of the plugin. Used internally. Please see the Sound API capabilitiesmethod for an overview of plugin capabilities.

_handlePreloadComplete

protected

Handles internal preload completion.

_handlePreloadError

protected

Handles internal preload errors

_isFileXHRSupported

() Boolean private static

Determine if XHR is supported, which is necessary for web audio.

Returns:

_unlock

() private

Try to unlock audio on iOS. This is triggered from either WebAudio plugin setup (which will work if inside of a mousedown or touchend event stack), or the first document touchend/mousedown event. If it fails (touchend will fail if the user presses for too long, indicating a scroll event instead of a click event.

Note that earlier versions of iOS supported touchstart for this, but iOS9 removed this functionality. Adding a touchstart event to support older platforms may preclude a mousedown even from getting fired on iOS9, so we stick with mousedown and touchend.

_updateVolume

() protected

Set the gain value for master audio. Should not be called externally.

create

(

• src
• startTime
• duration

)

AbstractSoundInstance

Create a sound instance. If the sound has not been preloaded, it is internally preloaded here.

Parameters:

• src String
  The sound source to use.
• startTime Number
  Audio sprite property used to apply an offset, in milliseconds.
• duration Number
  Audio sprite property used to set the time the clip plays for, in milliseconds.

Returns:

getVolume

() Number

Get the master volume of the plugin, which affects all SoundInstances.

Returns:

Number:

The volume level, between 0 and 1.

isPreloadComplete

Boolean

Checks if preloading has finished for a specific source.

Parameters:

• src String
  The sound URI to load.

Returns:

isPreloadStarted

Boolean

Checks if preloading has started for a specific source. If the source is found, we can assume it is loading, or has already finished loading.

Parameters:

• src String
  The sound URI to check.

Returns:

isSupported

() Boolean static

Determine if the plugin can be used in the current browser/OS.

Returns:

Boolean:

If the plugin can be initialized.

playEmptySound

() static

Plays an empty sound in the web audio context. This is used to enable web audio on iOS devices, as they require the first sound to be played inside of a user initiated event (touch/click). This is called whenWebAudioPlugin is initialized (by Sound initializeDefaultPluginsfor example).

Example

function handleTouch(event) {
    createjs.WebAudioPlugin.playEmptySound();
}

preload

Internally preload a sound.

Parameters:

• loader Loader
  The sound URI to load.

register

Object

Pre-register a sound for preloading and setup. This is called by Sound. Note all plugins provide a Loader instance, which PreloadJScan use to assist with preloading.

Parameters:

• loadItem String
  An Object containing the source of the audio Note that not every plugin will manage this value.

Returns:

Object:

A result object, containing a "tag" for preloading purposes.

removeAllSounds

Remove all sounds added using WebAudioPlugin/register. Note this does not cancel a preload.

Parameters:

• src String
  The sound URI to unload.

removeSound

Remove a sound added using WebAudioPlugin/register. Note this does not cancel a preload.

Parameters:

• src String
  The sound URI to unload.

setMute

Boolean

Mute all sounds via the plugin.

Parameters:

• value Boolean
  If all sound should be muted or not. Note that plugin-level muting just looks up the mute value of Sound muted, so this property is not used here.

Returns:

Boolean:

If the mute call succeeds.

setVolume

Boolean

Set the master volume of the plugin, which affects all SoundInstances.

Parameters:

• value Number
  The volume to set, between 0 and 1.

Returns:

Boolean:

If the plugin processes the setVolume call (true). The Sound class will affect all the instances manually otherwise.

Properties

_audioSources

Object protected

Object hash indexed by the source URI of each file to indicate if an audio source has begun loading, is currently loading, or has completed loading. Can be used to store non boolean data after loading is complete (for example arrayBuffers for web audio).

_capabilities

Object private static

The capabilities of the plugin. This is generated via the _generateCapabilitiesmethod and is used internally.

Default: null

_panningModel

Number / String protected

Value to set panning model to equal power for WebAudioSoundInstance. Can be "equalpower" or 0 depending on browser implementation.

_panningModel

Number / String private static

Value to set panning model to equal power for WebAudioSoundInstance. Can be "equalpower" or 0 depending on browser implementation.

_scratchBuffer

AudioBuffer private static

_unlocked

Boolean private

Indicated whether audio on iOS has been unlocked, which requires a touchend/mousedown event that plays an empty sound.

_volume

Number protected

The internal master volume value of the plugin.

Default: 1

context

AudioContext

The web audio context, which WebAudio uses to play audio. All nodes that interact with the WebAudioPlugin need to be created within this context.

context

AudioContext static

The web audio context, which WebAudio uses to play audio. All nodes that interact with the WebAudioPlugin need to be created within this context.

Advanced users can set this to an existing context, but must do so before they callregisterPlugins or initializeDefaultPlugins.

DEFAULT_SAMPLE_REATE

Number static

The default sample rate used when checking for iOS compatibility. See _createAudioContext.

Default: 44100

dynamicsCompressorNode

AudioNode

A DynamicsCompressorNode, which is used to improve sound quality and prevent audio distortion. It is connected to context.destination.

Can be accessed by advanced users through createjs.Sound.activePlugin.dynamicsCompressorNode.

gainNode

AudioGainNode

A GainNode for controlling master volume. It is connected to dynamicsCompressorNode.

Can be accessed by advanced users through createjs.Sound.activePlugin.gainNode.