HTMLAudioPlugin Class
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 requires Quicktime to be installed for audio playback.
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
()
Item Index
Methods
Properties
- AUDIO_ENDED static
- AUDIO_ERROR static
- AUDIO_READY static
- AUDIO_SEEKED static
- AUDIO_STALLED static
- audioSources
- capabilities static
- defaultNumChannels
- enableIOS
- MAX_INSTANCES static
Methods
create
-
src
Create a sound instance. If the sound has not been preloaded, it is internally preloaded here.
Parameters:
-
src
StringThe sound source to use.
Returns:
createTag
-
src
Create an HTML audio tag.
Parameters:
-
src
StringThe source file to set for the audio tag.
Returns:
generateCapabiities
()
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
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:
-
event
Object
init
()
protected
An initialization function run by the constructor
isPreloadStarted
-
src
Checks if preloading has started for a specific source.
Parameters:
-
src
StringThe sound URI to check.
Returns:
isSupported
()
Boolean
static
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:
preload
-
src
-
instance
-
basePath
Internally preload a sound.
register
-
src
-
instances
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:
Returns:
Properties
AUDIO_READY
String
static
Event constant for the "canPlayThrough" event for cleaner code.
Default: canplaythrough
AUDIO_SEEKED
String
static
Event constant for the "seeked" event for cleaner code. We utilize this event for maintaining loop events.
Default: seeked
AUDIO_STALLED
String
static
Event constant for the "stalled" event for cleaner code.
Default: stalled
audioSources
Object
protected
Object hash indexed by the source of each file to indicate if an audio source is loaded, or loading.
capabilities
Object
protected
static
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.
defaultNumChannels
Number
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
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:
Default: false
MAX_INSTANCES
Number
static
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