API Documentation for: 0.4.1
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 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.

Constructor

HTMLAudioPlugin

()

Defined in HTMLAudioPlugin:39

Methods

create

(
  • src
)
SoundInstance

Defined in create:314

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

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

() protected

Defined in init:240

An initialization function run by the constructor

isPreloadStarted

(
  • src
)
Boolean

Defined in isPreloadStarted:332

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

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

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

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

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

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 static

Defined in AUDIO_ENDED:122

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

Default: ended

AUDIO_ERROR

String static

Defined in AUDIO_ERROR:140

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

Default: error

AUDIO_READY

String static

Defined in AUDIO_READY:113

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

Default: canplaythrough

AUDIO_SEEKED

String static

Defined in AUDIO_SEEKED:131

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

Default: seeked

AUDIO_STALLED

String static

Defined in AUDIO_STALLED:149

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

Default: stalled

audioSources

Object protected

Defined in audioSources:218

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

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

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

MAX_INSTANCES

Number static

Defined in MAX_INSTANCES:92

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