API Documentation for: 1.0.0
Show:

WebAudioPlugin Class

Extends AbstractPlugin
Defined in: WebAudioPlugin:41
Module: SoundJS

Available since 0.4.0

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 API registerPlugins 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

    WebAudioPlugin

    ()

    Defined in WebAudioPlugin:41

    Available since 0.4.0

    Methods

    _addPropsToClasses

    () protected static

    Defined in _addPropsToClasses:422

    Available since 0.6.0

    Set up needed properties on supported classes WebAudioSoundInstance and WebAudioLoader.

    _compatibilitySetUp

    () private static

    Defined in _compatibilitySetUp:363

    Available since 0.4.2

    Set up compatibility if only deprecated web audio calls are supported. See http://www.w3.org/TR/webaudio/#DeprecationNotes Needed 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

    Defined in _createAudioContext:326

    Available since 1.0.0

    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 capabilities method for an overview of plugin capabilities.

    _handlePreloadComplete

    (
    • event
    )
    protected

    Handles internal preload completion.

    Parameters:

    _handlePreloadError

    (
    • event
    )
    protected

    Handles internal preload errors

    Parameters:

    _isFileXHRSupported

    () Boolean private static

    Defined in _isFileXHRSupported:240

    Available since 0.4.2

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

    Returns:

    Boolean:

    If XHR is supported.

    _unlock

    () private

    Defined in _unlock:391

    Available since 0.6.2

    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

    Inherited from AbstractPlugin but overwritten in _updateVolume:440

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

    create

    (
    • src
    • startTime
    • duration
    )
    AbstractSoundInstance

    Inherited from AbstractPlugin: create:213

    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:

    AbstractSoundInstance:

    A sound instance for playback and control.

    getVolume

    () Number

    Inherited from AbstractPlugin: getVolume:252

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

    Returns:

    Number:

    The volume level, between 0 and 1.

    isPreloadComplete

    (
    • src
    )
    Boolean

    Checks if preloading has finished for a specific source.

    Parameters:

    • src String

      The sound URI to load.

    Returns:

    isPreloadStarted

    (
    • src
    )
    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

    Defined in isSupported:198

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

    Returns:

    Boolean:

    If the plugin can be initialized.

    playEmptySound

    () static

    Defined in playEmptySound:214

    Available since 0.4.1

    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 when WebAudioPlugin is initialized (by Sound initializeDefaultPlugins for example).

    Example

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

    preload

    (
    • loader
    )

    Inherited from AbstractPlugin: preload:154

    Internally preload a sound.

    Parameters:

    • loader Loader

      The sound URI to load.

    register

    (
    • loadItem
    )
    Object

    Inherited from AbstractPlugin: register:132

    Pre-register a sound for preloading and setup. This is called by Sound. Note all plugins provide a Loader instance, which PreloadJS can 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

    (
    • src
    )

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

    Parameters:

    • src String

      The sound URI to unload.

    removeSound

    (
    • src
    )

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

    Parameters:

    • src String

      The sound URI to unload.

    setMute

    (
    • value
    )
    Boolean

    Inherited from AbstractPlugin: setMute:261

    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

    (
    • value
    )
    Boolean

    Inherited from AbstractPlugin: setVolume:239

    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

    Defined in _capabilities:131

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

    Default: null

    _panningModel

    Number / String protected

    Defined in _panningModel:82

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

    _panningModel

    Number / String private static

    Defined in _panningModel:142

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

    _scratchBuffer

    AudioBuffer private static

    Defined in _scratchBuffer:164

    The scratch buffer that will be assigned to the buffer property of a source node on close. Works around an iOS Safari bug: https://github.com/CreateJS/SoundJS/issues/102

    Advanced users can set this to an existing source node, but must do so before they call registerPlugins or initializeDefaultPlugins.

    _unlocked

    Boolean private

    Defined in _unlocked:178

    Available since 0.6.2

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

    _volume

    Number protected

    Inherited from AbstractPlugin: _volume:83

    The internal master volume value of the plugin.

    Default: 1

    context

    AudioContext

    Defined in context:90

    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

    Defined in context:151

    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 call registerPlugins 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

    Defined in gainNode:109

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

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