HTMLAudioPlugin Class
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 browsersTesting 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. Please use Sound.MAX_INSTANCES as a guide to how many total audio tags you can safely use in all browsers. This issue is primarily limited to IE9.
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 or 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
- 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.
- Note it is recommended to use WebAudioPlugin for iOS (6+)
- 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.
- 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_READY static
- _AUDIO_SEEKED static
- _AUDIO_STALLED static
- _audioSources
- _capabilities static
- _TIME_UPDATE static
- _volume
- MAX_INSTANCES static
Methods
_generateCapabilities
()
private
static
Determine the capabilities of the plugin. Used internally. Please see the Sound API capabilities method for an overview of plugin capabilities.
_handlePreloadComplete
-
event
Handles internal preload completion.
Parameters:
-
eventObject
_updateVolume
()
protected
Set the gain value for master audio. Should not be called externally.
create
-
src -
startTime -
duration
Create a sound instance. If the sound has not been preloaded, it is internally preloaded here.
Parameters:
Returns:
A sound instance for playback and control.
getVolume
()
Number
Get the master volume of the plugin, which affects all SoundInstances.
Returns:
The volume level, between 0 and 1.
isPreloadComplete
-
src
Checks if preloading has finished for a specific source.
Parameters:
-
srcStringThe sound URI to load.
Returns:
isPreloadStarted
-
src
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:
-
srcStringThe 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:
If the plugin can be initialized.
preload
-
loader
Internally preload a sound.
Parameters:
-
loaderLoaderThe sound URI to load.
register
-
loadItem
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:
-
loadItemStringAn Object containing the source of the audio Note that not every plugin will manage this value.
Returns:
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:
-
srcStringThe sound URI to unload.
removeSound
-
src
Remove a sound added using WebAudioPlugin/register. Note this does not cancel a preload.
Parameters:
-
srcStringThe sound URI to unload.
Properties
_AUDIO_ENDED
String
private
static
Event constant for the "ended" event for cleaner code.
Default: ended
_AUDIO_READY
String
private
static
Event constant for the "canPlayThrough" event for cleaner code.
Default: canplaythrough
_AUDIO_SEEKED
String
private
static
Event constant for the "seeked" event for cleaner code. We utilize this event for maintaining loop events.
Default: seeked
_AUDIO_STALLED
String
private
static
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
private
static
The capabilities of the plugin. This is generated via the _generateCapabilities method. Please see the Sound capabilities method for an overview of all of the available properties.
_TIME_UPDATE
String
private
static
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
MAX_INSTANCES
Number
static
The maximum number of instances that can be loaded or 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