API Documentation for: 0.4.0
Show:

HTMLAudioPlugin Class

Defined in: HTMLAudioPlugin:39
Module: SoundJS

Play sounds using HTML <audio> tags in the browser. This plugin is the second priority plugin installed by default, after the WebAudioPlugin, which is supported on Chrome, Safari, and iOS. This handles audio in all other modern browsers. For non-supported browsers, include and install the FlashPlugin.

Known Browser and OS issues for HTML Audio

All browsers
Testing has shown in all browsers there is a limit to how many audio tag instances you are allowed. If you exceed this limit, you can expect to see unpredictable results. This will be seen as soon as you register sounds, as tags are precreated to all Chrome to load them. Please use Sound.MAX_INSTANCES as a guide to how many total audio tags you can safely use in all browsers.

IE 9 html audio quirk
Note in IE 9 there is a delay in applying volume changes to tags that occurs once playback is started. So if you have muted all sounds, they will all play during this delay until the mute applies internally. This happens regardless of when or how you apply the volume change, as the tag seems to need to play to apply it.

iOS 6 limitations
Note it is recommended to use WebAudioPlugin for iOS (6+). HTML Audio can only have one <audio> tag, can not preload or autoplay the audio, can not cache the audio, and can not play the audio except inside a user initiated event.

Android limitations

  • We have no control over audio volume. Only the user can set volume on their device.
  • We can only play audio inside a user event (touch). This currently means you cannot loop sound.
  • See Sound for general notes on known issues.

    Constructor

    HTMLAudioPlugin

    ()

    Defined in HTMLAudioPlugin:39

    Methods

    create

    (
    • src
    )
    SoundInstance

    Defined in create:268

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

    Parameters:

    • src String

      The sound source to use.

    Returns:

    SoundInstance: A sound instance for playback and control.

    createTag

    (
    • src
    )
    HTMLElement protected

    Defined in createTag:253

    Create an HTML audio tag.

    Parameters:

    • src String

      The source file to set for the audio tag.

    Returns:

    HTMLElement: Returns an HTML audio tag.

    generateCapabiities

    () protected static

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

    init

    () private

    Defined in init:218

    An initialization function run by the constructor

    isPreloadStarted

    (
    • src
    )
    Boolean

    Defined in isPreloadStarted:286

    Available since 0.4.0

    Checks if preloading has started for a specific source.

    Parameters:

    • src String

      The sound URI to check.

    Returns:

    Boolean: If the preload has started.

    isSupported

    () Boolean static

    Defined in isSupported:134

    Determine if the plugin can be used in the current browser/OS. Note that HTML audio is available in most modern browsers except iOS, where it is limited.

    Returns:

    Boolean: If the plugin can be initialized.

    preload

    (
    • src
    • instance
    )

    Defined in preload:297

    Available since 0.4.0

    Internally preload a sound.

    Parameters:

    • src String

      The sound URI to load.

    • instance Object

      An object containing a tag property that is an HTML audio tag used to load src.

    register

    (
    • src
    • instances
    )
    Object

    Defined in register:228

    Pre-register a sound instance when preloading/setup. This is called by Sound. Note that this provides an object containing a tag used for preloading purposes, which PreloadJS can use to assist with preloading.

    Parameters:

    • src String

      The source of the audio

    • instances Number

      The number of concurrently playing instances to allow for the channel at any time.

    Returns:

    Object: A result object, containing a tag for preloading purposes and a numChannels value for internally controlling how many instances of a source can be played by default.

    Properties

    AUDIO_ENDED

    String static

    Defined in AUDIO_ENDED:106

    Event constant for the "ended" event for cleaner code.

    Default: ended

    AUDIO_ERROR

    String static

    Defined in AUDIO_ERROR:115

    Event constant for the "error" event for cleaner code.

    Default: error

    AUDIO_READY

    String static

    Defined in AUDIO_READY:97

    Event constant for the "canPlayThrough" event for cleaner code.

    Default: canplaythrough

    AUDIO_STALLED

    String static

    Defined in AUDIO_STALLED:124

    Event constant for the "stalled" event for cleaner code.

    Default: stalled

    audioSources

    Object protected

    Defined in audioSources:196

    Available since 0.4.0

    Object hash indexed by the source of each file to indicate if an audio source is loaded, or loading.

    capabilities

    Object static

    Defined in capabilities:87

    The capabilities of the plugin. This is generated via the the SoundInstance TMLAudioPlugin/generateCapabilities method. Please see the Sound getCapabilities method for an overview of all of the available properties.

    defaultNumChannels

    Number

    Defined in defaultNumChannels:205

    Available since 0.4.0

    The default number of instances to allow. Passed back to Sound when a source is registered using the Sound/register method. This is only used if a value is not provided.

    NOTE this only exists as a limitation of HTML audio.

    Default: 2

    MAX_INSTANCES

    Number static

    Defined in MAX_INSTANCES:77

    The maximum number of instances that can be played. This is a browser limitation. The actual number varies from browser to browser (and is largely hardware dependant), but this is a safe estimate.

    Default: 30