API Documentation for: 0.5.2
Show:

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

Android Native Browser 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.

Constructor

HTMLAudioPlugin

()

Defined in HTMLAudioPlugin:41

Methods

_createTag

(
  • src
)
HTMLElement protected

Defined in _createTag:324

Create an HTML audio tag.

Parameters:

  • src String

    The source file to set for the audio tag.

Returns:

HTMLElement: Returns an HTML audio tag.

_generateCapabilities

() protected static

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

_handleTagLoad

(
  • event
)
deprecated protected

Defined in _handleTagLoad:305

Deprecated as this will not be required with new approach to basePath. 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.

Parameters:

_init

() protected

Defined in _init:254

An initialization function run by the constructor

create

(
  • src
)
SoundInstance

Defined in create:363

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.

isPreloadStarted

(
  • src
)
Boolean

Defined in isPreloadStarted:382

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:173

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.

Returns:

Boolean: If the plugin can be initialized.

preload

(
  • src
  • instance
)

Defined in preload:393

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:264

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.

removeAllSounds

(
  • src
)

Defined in removeAllSounds:352

Available since 0.4.1

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

Parameters:

  • src String

    The sound URI to unload.

removeSound

(
  • src
)

Defined in removeSound:340

Available since 0.4.1

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

Parameters:

  • src String

    The sound URI to unload.

Properties

_AUDIO_ENDED

String protected static

Defined in _AUDIO_ENDED:117

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

Default: ended

_AUDIO_READY

String protected static

Defined in _AUDIO_READY:107

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

Default: canplaythrough

_AUDIO_SEEKED

String protected static

Defined in _AUDIO_SEEKED:127

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

Default: seeked

_AUDIO_STALLED

String protected static

Defined in _AUDIO_STALLED:137

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

Default: stalled

_audioSources

Object protected

Defined in _audioSources:229

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 protected static

Defined in _capabilities:147

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

defaultNumChannels

Number

Defined in defaultNumChannels:238

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

enableIOS

Boolean

Defined in enableIOS:158

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

    MAX_INSTANCES

    Number static

    Defined in MAX_INSTANCES:97

    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