HTML5AudioSound

HTML5AudioSound is the HTML5 Audio API implementation of a sound within Phaser.

It is used automatically by the HTML5AudioSoundManager when the Web Audio API is unavailable, typically in environments that do not support it or where it has been disabled. Unlike the WebAudioSound class, HTML5AudioSound relies on native <audio> elements for playback, which means it has more limited capabilities, such as no support for audio panning.

Each sound maintains a pool of HTMLAudioElement tags loaded via Loader.audio. Because HTML5 Audio cannot share a single element across simultaneous playbacks, you must load multiple instances of the asset if you want to play the same sound more than once at the same time.

You do not create instances of this class directly. Instead, use this.sound.add(key) from within a Scene, which will return the correct sound type based on the audio system in use.

Constructor

new HTML5AudioSound(manager, key, [config])

Parameters

name	type	optional	default	description
manager	Phaser.Sound.HTML5AudioSoundManager	No		Reference to the current sound manager instance.
key	string	No		Asset key for the sound.
config	Phaser.Types.Sound.SoundConfig	Yes	"{}"	An optional config object containing default sound settings.

---

Scope: static

Extends

Phaser.Sound.BaseSound

Source: src/sound/html5/HTML5AudioSound.js#L13
Since: 3.0.0

Inherited Members

From Phaser.Sound.BaseSound:

• currentMarker
• duration
• isPaused
• isPlaying
• key
• manager
• markers
• pendingRemove
• totalDuration
• totalRate

---

Public Members

audio

audio: HTMLAudioElement

Description:

Reference to an HTML5 Audio tag used for playing sound.

Source: src/sound/html5/HTML5AudioSound.js#L66
Since: 3.0.0

---

detune

detune: number

Description:

The detune value of this Sound, given in cents. The range of the value is -1200 to 1200, but we recommend setting it to 50.

Fires: Phaser.Sound.Events#event:DETUNE

Source: src/sound/html5/HTML5AudioSound.js#L739
Since: 3.0.0

---

loop

loop: boolean

Description:

Flag indicating whether or not the sound or current sound marker will loop.

Fires: Phaser.Sound.Events#event:LOOP

Source: src/sound/html5/HTML5AudioSound.js#L871
Since: 3.0.0

---

mute

mute: boolean

Description:

Boolean indicating whether the sound is muted or not. Gets or sets the muted state of this sound.

Fires: Phaser.Sound.Events#event:MUTE

Source: src/sound/html5/HTML5AudioSound.js#L583
Since: 3.0.0

---

pan

pan: number

Description:

Gets or sets the pan of this sound, a value between -1 (full left pan) and 1 (full right pan).

Has no audible effect on HTML5 Audio Sound, but still generates the PAN Event.

Fires: Phaser.Sound.Events#event:PAN

Source: src/sound/html5/HTML5AudioSound.js#L924
Since: 3.50.0

---

previousTime

previousTime: number

Description:

Audio tag's playback position recorded on previous update method call. Set to 0 if sound is not playing.

Source: src/sound/html5/HTML5AudioSound.js#L88
Since: 3.0.0

---

rate

rate: number

Description:

Rate at which this Sound will be played. Value of 1.0 plays the audio at full speed, 0.5 plays the audio at half speed and 2.0 doubles the audio's playback speed.

Fires: Phaser.Sound.Events#event:RATE

Source: src/sound/html5/HTML5AudioSound.js#L682
Since: 3.0.0

---

seek

seek: number

Description:

Property representing the position of playback for this sound, in seconds. Setting it to a specific value moves current playback to that position. The value given is clamped to the range 0 to current marker duration. Setting seek of a stopped sound has no effect.

Fires: Phaser.Sound.Events#event:SEEK

Source: src/sound/html5/HTML5AudioSound.js#L793
Since: 3.0.0

---

startTime

startTime: number

Description:

Timestamp as generated by the Request Animation Frame or SetTimeout representing the time at which the delayed sound playback should start. Set to 0 if sound playback is not delayed.

Source: src/sound/html5/HTML5AudioSound.js#L76
Since: 3.0.0

---

tags

tags: Array.<HTMLAudioElement>

Description:

An array containing all HTML5 Audio tags that could be used for individual sound playback. Number of instances depends on the config value passed to the Loader#audio method call, default is 1.

Source: src/sound/html5/HTML5AudioSound.js#L50
Since: 3.0.0

---

volume

volume: number

Description:

Gets or sets the volume of this sound, a value between 0 (silence) and 1 (full volume).

Fires: Phaser.Sound.Events#event:VOLUME

Source: src/sound/html5/HTML5AudioSound.js#L633
Since: 3.0.0

---

Inherited Methods

From Phaser.Events.EventEmitter:

• addListener
• emit
• eventNames
• listenerCount
• listeners
• off
• on
• once
• removeAllListeners
• removeListener
• shutdown

From Phaser.Sound.BaseSound:

• addMarker
• applyConfig
• removeMarker
• resetConfig
• updateMarker

---

Public Methods

calculateRate

<instance> calculateRate()

Description:

This method is used internally to update the playback rate of this sound.

Overrides: Phaser.Sound.BaseSound#calculateRate

Source: src/sound/html5/HTML5AudioSound.js#L567
Since: 3.0.0

---

destroy

<instance> destroy()

Description:

Calls Phaser.Sound.BaseSound#destroy method and cleans up all HTML5 Audio related resources.

Overrides: Phaser.Sound.BaseSound#destroy

Source: src/sound/html5/HTML5AudioSound.js#L520
Since: 3.0.0

---

onBlur

<instance> onBlur()

Description:

Method used internally by sound manager for pausing sound if Phaser.Sound.HTML5AudioSoundManager#pauseOnBlur is set to true.

Source: src/sound/html5/HTML5AudioSound.js#L419
Since: 3.0.0

---

onFocus

<instance> onFocus()

Description:

Method used internally by sound manager for resuming sound if Phaser.Sound.HTML5AudioSoundManager#pauseOnBlur is set to true.

Source: src/sound/html5/HTML5AudioSound.js#L438
Since: 3.0.0

---

pause

<instance> pause()

Description:

Pauses the sound.

Overrides: Phaser.Sound.BaseSound#pause

Returns: boolean - Whether the sound was paused successfully.

Fires: Phaser.Sound.Events#event:PAUSE

Source: src/sound/html5/HTML5AudioSound.js#L148
Since: 3.0.0

---

pickAndPlayAudioTag

<instance> pickAndPlayAudioTag()

Description:

This method is used internally to pick and play the next available audio tag.

Returns: boolean - Whether the sound was assigned an audio tag successfully.

Source: src/sound/html5/HTML5AudioSound.js#L250
Since: 3.0.0

---

pickAudioTag

<instance> pickAudioTag()

Description:

This method performs the audio tag pooling logic. It first looks for unused audio tag to assign to this sound object. If there are no unused audio tags, based on HTML5AudioSoundManager#override property value, it looks for sound with most advanced playback and hijacks its audio tag or does nothing.

Returns: boolean - Whether the sound was assigned an audio tag successfully.

Source: src/sound/html5/HTML5AudioSound.js#L299
Since: 3.0.0

---

play

<instance> play([markerName], [config])

Description:

Play this sound, or a marked section of it.

It always plays the sound from the start. If you want to start playback from a specific time you can set 'seek' setting of the config object, provided to this call, to that value.

If you want to play the same sound simultaneously, then you need to create another instance of it and play that Sound. For HTML5 Audio this also requires creating multiple audio instances when loading the audio files.

Parameters:

name	type	optional	default	description
markerName	string | Phaser.Types.Sound.SoundConfig	Yes	"''"	If you want to play a marker then provide the marker name here. Alternatively, this parameter can be a SoundConfig object.
config	Phaser.Types.Sound.SoundConfig	Yes		Optional sound config object to be applied to this marker or entire sound if no marker name is provided. It gets memorized for future plays of current section of the sound.

Overrides: Phaser.Sound.BaseSound#play

Returns: boolean - Whether the sound started playing successfully.

Fires: Phaser.Sound.Events#event:PLAY

Source: src/sound/html5/HTML5AudioSound.js#L106
Since: 3.0.0

---

playCatchPromise

<instance> playCatchPromise()

Description:

Method used for playing audio tag and catching possible exceptions thrown from rejected Promise returned from play method call.

Source: src/sound/html5/HTML5AudioSound.js#L367
Since: 3.0.0

---

reset

<instance> reset()

Description:

Method used internally to reset sound state, usually when stopping sound or when hijacking audio tag from another sound.

Source: src/sound/html5/HTML5AudioSound.js#L407
Since: 3.0.0

---

resume

<instance> resume()

Description:

Resumes the sound.

Overrides: Phaser.Sound.BaseSound#resume

Returns: boolean - Whether the sound was resumed successfully.

Fires: Phaser.Sound.Events#event:RESUME

Source: src/sound/html5/HTML5AudioSound.js#L184
Since: 3.0.0

---

setDetune

<instance> setDetune(value)

Description:

Sets the detune value of this Sound, given in cents. The range of the value is -1200 to 1200, but we recommend setting it to 50.

Parameters:

name	type	optional	description
value	number	No	The range of the value is -1200 to 1200, but we recommend setting it to 50.

Returns: Phaser.Sound.HTML5AudioSound - This Sound instance.

Fires: Phaser.Sound.Events#event:DETUNE

Source: src/sound/html5/HTML5AudioSound.js#L774
Since: 3.3.0

---

setLoop

<instance> setLoop(value)

Description:

Sets the loop state of this Sound.

Parameters:

name	type	optional	description
value	boolean	No	true to loop this sound, false to not loop it.

Returns: Phaser.Sound.HTML5AudioSound - This Sound instance.

Fires: Phaser.Sound.Events#event:LOOP

Source: src/sound/html5/HTML5AudioSound.js#L906
Since: 3.4.0

---

setMute

<instance> setMute(value)

Description:

Sets the muted state of this Sound.

Parameters:

name	type	optional	description
value	boolean	No	true to mute this sound, false to unmute it.

Returns: Phaser.Sound.HTML5AudioSound - This Sound instance.

Fires: Phaser.Sound.Events#event:MUTE

Source: src/sound/html5/HTML5AudioSound.js#L615
Since: 3.4.0

---

setPan

<instance> setPan(value)

Description:

Sets the pan of this sound, a value between -1 (full left pan) and 1 (full right pan).

Has no audible effect on HTML5 Audio Sound, but still generates the PAN Event.

Parameters:

name	type	optional	description
value	number	No	The pan of the sound. A value between -1 (full left pan) and 1 (full right pan).

Returns: Phaser.Sound.HTML5AudioSound - This Sound instance.

Fires: Phaser.Sound.Events#event:PAN

Source: src/sound/html5/HTML5AudioSound.js#L950
Since: 3.50.0

---

setRate

<instance> setRate(value)

Description:

Sets the playback rate of this Sound.

For example, a value of 1.0 plays the audio at full speed, 0.5 plays the audio at half speed and 2.0 doubles the audio's playback speed.

Parameters:

name	type	optional	description
value	number	No	The playback rate of this Sound.

Returns: Phaser.Sound.HTML5AudioSound - This Sound instance.

Fires: Phaser.Sound.Events#event:RATE

Source: src/sound/html5/HTML5AudioSound.js#L718
Since: 3.3.0

---

setSeek

<instance> setSeek(value)

Description:

Seeks to a specific point in this sound.

Parameters:

name	type	optional	description
value	number	No	The point in the sound to seek to, in seconds.

Returns: Phaser.Sound.HTML5AudioSound - This Sound instance.

Fires: Phaser.Sound.Events#event:SEEK

Source: src/sound/html5/HTML5AudioSound.js#L853
Since: 3.4.0

---

setVolume

<instance> setVolume(value)

Description:

Sets the volume of this Sound.

Parameters:

name	type	optional	description
value	number	No	The volume of the sound. A value between 0 (silence) and 1 (full volume).

Returns: Phaser.Sound.HTML5AudioSound - This Sound instance.

Fires: Phaser.Sound.Events#event:VOLUME

Source: src/sound/html5/HTML5AudioSound.js#L664
Since: 3.4.0

---

stop

<instance> stop()

Description:

Stop playing this sound.

Overrides: Phaser.Sound.BaseSound#stop

Returns: boolean - Whether the sound was stopped successfully.

Fires: Phaser.Sound.Events#event:STOP

Source: src/sound/html5/HTML5AudioSound.js#L221
Since: 3.0.0

---

stopAndReleaseAudioTag

<instance> stopAndReleaseAudioTag()

Description:

This method is used internally to stop and release the current audio tag.

Source: src/sound/html5/HTML5AudioSound.js#L388
Since: 3.0.0

---

update

<instance> update(time)

Description:

Update method called automatically by sound manager on every game step.

Parameters:

name	type	optional	description
time	number	No	The current timestamp as generated by the Request Animation Frame or SetTimeout.

Overrides: Phaser.Sound.BaseSound#update

Fires: Phaser.Sound.Events#event:COMPLETE, Phaser.Sound.Events#event:LOOPED

Source: src/sound/html5/HTML5AudioSound.js#L452
Since: 3.0.0

---

updateMute

<instance> updateMute()

Description:

This method is used internally to update the mute setting of this sound.

Source: src/sound/html5/HTML5AudioSound.js#L539
Since: 3.0.0

---

updateVolume

<instance> updateVolume()

Description:

This method is used internally to update the volume of this sound.

Source: src/sound/html5/HTML5AudioSound.js#L553
Since: 3.0.0

---