API Documentation for: 0.6.0
Show:

HTMLAudioPlugin Class

Extends AbstractPlugin
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 FlashAudioPlugin.

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 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.
  • Occasionally very short samples will get cut off.
  • 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. Note that audio sprites can be used as a solution to this issue.

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.
  • audio sprites can be used to mitigate some of these issues and are strongly recommended on iOS

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

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.

_handlePreloadComplete

() protected

Handles internal preload completion.

_handlePreloadError

(
  • event
)
protected

Handles internal preload erros

Parameters:

_updateVolume

() protected

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

create

(
  • src
  • startTime
  • duration
)
AbstractSoundInstance

Inherited from AbstractPlugin: create:219

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

()

Inherited from AbstractPlugin: getVolume:252

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

Returns:

The volume level, between 0 and 1.

initialize

() deprecated protected

Inherited from AbstractPlugin: initialize:99

REMOVED. Removed in favor of using MySuperClass_constructor. See extend and promote for details.

There is an inheritance tutorial distributed with EaselJS in /tutorials/Inheritance.

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

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

(
  • loader
)

Inherited from AbstractPlugin: preload:160

Internally preload a sound.

Parameters:

  • loader Loader

    The sound URI to load.

register

(
  • loadItem
  • instances
)
Object

Inherited from AbstractPlugin: register:138

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

  • instances Number

    The number of concurrently playing instances to allow for the channel at any time. 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 getMute, 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

_AUDIO_ENDED

String protected static

Defined in _AUDIO_ENDED:146

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

Default: ended

_AUDIO_READY

String protected static

Defined in _AUDIO_READY:136

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

Default: canplaythrough

_AUDIO_SEEKED

String protected static

Defined in _AUDIO_SEEKED:156

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

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

Default: stalled

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

Defined in _capabilities:187

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

_TIME_UPDATE

String protected static

Defined in _TIME_UPDATE:176

Event constant for the "timeupdate" event for cleaner code. Utilized for looping audio sprites. This event callsback ever 15 to 250ms and can be dropped by the browser for performance.

Default: timeupdate

defaultNumChannels

Number

Defined in defaultNumChannels:98

Available since 0.4.0

The default number of instances to allow. Used by 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 deprecated

Defined in enableIOS:198

Deprecated now that we have audio sprite support. Audio sprites are strongly recommend on iOS for the following reasons:

  • 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:125

    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. Audio sprites work around this limitation.

    Default: 30