API Documentation for: 0.5.0

HTMLAudioPlugin Class

Defined in: HTMLAudioPlugin:41
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 older browsers that do not support html audio, 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 limitations

  • 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.
  • MP3 encoding will not always work for audio tags if it's not default. We've found default encoding with 64kbps works.
  • There is a limit to how many audio tags you can load and play at once, which appears to be determined by hardware and browser settings. See HTMLAudioPlugin.MAX_INSTANCES for a safe estimate.
Safari limitations
  • Safari requires Quicktime to be installed for audio playback.
iOS 6 limitations
Note it is recommended to use WebAudioPlugin for iOS (6+). HTML Audio is disabled by default as it 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 HTML Audio 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/click). This currently means you cannot loop sound or use a delay.
  • Android Chrome 26.0.1410.58 specific limitations
  • Chrome reports true when you run createjs.Sound.BrowserDetect.isChrome, but is a different browser with different abilities.
  • Can only play 1 sound at a time.
  • Sound is not cached.
  • Sound can only be loaded in a user initiated touch/click event.
  • There is a delay before a sound is played, presumably while the src is loaded.

See Sound for general notes on known issues.




Defined in HTMLAudioPlugin:41



  • src

Defined in create:366

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


  • src String

    The sound source to use.


SoundInstance: A sound instance for playback and control.


  • src
HTMLElement protected

Defined in createTag:327

Create an HTML audio tag.


  • src String

    The source file to set for the audio tag.


HTMLElement: Returns an HTML audio tag.


() protected static

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


  • event

Defined in handleTagLoad:310

Checks if src was changed on tag used to create instances in TagPool before loading Currently PreloadJS does this when a basePath is set, so we are replicating that behavior for internal preloading.



() protected

Defined in init:260

An initialization function run by the constructor


  • src

Defined in isPreloadStarted:385

Available since 0.4.0

Checks if preloading has started for a specific source.


  • src String

    The sound URI to check.


Boolean: If the preload has started.


() Boolean static

Defined in isSupported:176

Determine if the plugin can be used in the current browser/OS. Note that HTML audio is available in most modern browsers, but is disabled in iOS because of its limitations.


Boolean: If the plugin can be initialized.


  • src
  • instance
  • basePath

Defined in preload:396

Available since 0.4.0

Internally preload a sound.


  • 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.

  • basePath String

    A file path to prepend to the src.


  • src
  • instances

Defined in register:270

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.


  • src String

    The source of the audio

  • instances Number

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


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.


  • src

Defined in removeAllSounds:355

Available since 0.4.1

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


  • src String

    The sound URI to unload.


  • src

Defined in removeSound:343

Available since 0.4.1

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


  • src String

    The sound URI to unload.



String static

Defined in AUDIO_ENDED:124

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

Default: ended


String static

Defined in AUDIO_ERROR:142

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

Default: error


String static

Defined in AUDIO_READY:115

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

Default: canplaythrough


String static

Defined in AUDIO_SEEKED:133

Event constant for the "seeked" event for cleaner code. We utilize this event for maintaining loop events.

Default: seeked


String static

Defined in AUDIO_STALLED:151

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

Default: stalled


Object protected

Defined in audioSources:235

Available since 0.4.0

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


Object protected static

Defined in capabilities:104

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



Defined in defaultNumChannels:244

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 property only exists as a limitation of HTML audio.

Default: 2



Defined in enableIOS:161

Allows users to enable HTML audio on IOS, which is disabled by default. Note this needs to be set before HTMLAudioPlugin is registered with SoundJS. This is not recommend because of severe limitations on IOS devices including:

  • it can only have one <audio> tag
  • can not preload or autoplay the audio
  • can not cache the audio
  • can not play the audio except inside a user initiated event
  • Default: false


    Number static

    Defined in MAX_INSTANCES:94

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

    Default: 30