Phaser API Documentation

  Version: 
Filter

Web Audio API implementation of the Sound Manager.

Not all browsers can play all audio formats.

There is a good guide to what's supported: Cross-browser audio basics: Audio codec support.

Constructor:

new WebAudioSoundManager(game)

Parameters:

name type description
game Phaser.Game

Reference to the current game instance.

Since: 3.0.0

Extends


Members

<private> _detune: number
Focus
Focus

Description:

Property that actually holds the value of global detune.

Type:
number
Default: 0
Inherited from: Phaser.Sound.BaseSoundManager#_detune
Since: 3.0.0
Focus
Focus
<private> _rate: number
Focus
Focus

Description:

Property that actually holds the value of global playback rate.

Type:
number
Default: 1
Inherited from: Phaser.Sound.BaseSoundManager#_rate
Since: 3.0.0
Focus
Focus
context: AudioContext
Focus
Focus

Description:

The AudioContext being used for playback.

Type:
AudioContext
Since: 3.0.0
Focus
Focus
destination: AudioNode
Focus
Focus

Description:

Destination node for connecting individual sounds to.

Type:
AudioNode
Since: 3.0.0
Focus
Focus
detune: number
Focus
Focus

Description:

Global detuning of all sounds in cents. The range of the value is -1200 to 1200, but we recommend setting it to 50.

Type:
number
Default: 0
Inherited from: Phaser.Sound.BaseSoundManager#detune
Since: 3.0.0
Focus
Focus
<readonly> game: Phaser.Game
Focus
Focus

Description:

Local reference to game.

Type:
Inherited from: Phaser.Sound.BaseSoundManager#game
Since: 3.0.0
Focus
Focus
gameLostFocus: boolean
Focus
Focus

Description:

Flag used to track if the game has lost focus.

Type:
boolean
Default: false
Inherited from: Phaser.Sound.BaseSoundManager#gameLostFocus
Since: 3.60.0
Focus
Focus
<readonly> jsonCache: Phaser.Cache.BaseCache
Focus
Focus

Description:

Local reference to the JSON Cache, as used by Audio Sprites.

Type:
Inherited from: Phaser.Sound.BaseSoundManager#jsonCache
Since: 3.7.0
Focus
Focus
listenerPosition: Phaser.Math.Vector2
Focus
Focus

Description:

The Spatial Audio listener position.

Only available with WebAudio.

You can modify the x/y properties of this Vec2 directly to adjust the listener position within the game world.

Type:
Inherited from: Phaser.Sound.BaseSoundManager#listenerPosition
Since: 3.60.0
Focus
Focus
<readonly> locked: boolean
Focus
Focus

Description:

Mobile devices require sounds to be triggered from an explicit user action, such as a tap, before any sound can be loaded/played on a web page. Set to true if the audio system is currently locked awaiting user interaction.

Type:
boolean
Inherited from: Phaser.Sound.BaseSoundManager#locked
Since: 3.0.0
Focus
Focus
masterMuteNode: GainNode
Focus
Focus

Description:

Gain node responsible for controlling global muting.

Type:
GainNode
Since: 3.0.0
Focus
Focus
masterVolumeNode: GainNode
Focus
Focus

Description:

Gain node responsible for controlling global volume.

Type:
GainNode
Since: 3.0.0
Focus
Focus
mute: boolean
Focus
Focus
Type:
boolean
Overrides: Phaser.Sound.BaseSoundManager#mute
Since: 3.0.0
Focus
Focus
pauseOnBlur: boolean
Focus
Focus

Description:

Flag indicating if sounds should be paused when game looses focus, for instance when user switches to another tab/program/app.

Type:
boolean
Default: true
Inherited from: Phaser.Sound.BaseSoundManager#pauseOnBlur
Since: 3.0.0
Focus
Focus
rate: number
Focus
Focus

Description:

Global playback rate at which all the sounds 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.

Type:
number
Default: 1
Inherited from: Phaser.Sound.BaseSoundManager#rate
Since: 3.0.0
Focus
Focus
<private> sounds: Array.<Phaser.Sound.BaseSound>
Focus
Focus

Description:

An array containing all added sounds.

Type:
Default: []
Inherited from: Phaser.Sound.BaseSoundManager#sounds
Since: 3.0.0
Focus
Focus
<private> unlocked: boolean
Focus
Focus

Description:

Flag used internally for handling when the audio system has been unlocked, if there ever was a need for it.

Type:
boolean
Default: false
Inherited from: Phaser.Sound.BaseSoundManager#unlocked
Since: 3.0.0
Focus
Focus
volume: number
Focus
Focus
Type:
number
Overrides: Phaser.Sound.BaseSoundManager#volume
Since: 3.0.0
Focus
Focus

Methods

add(key, [config])
Focus
Focus

Description:

Adds a new sound into the sound manager.

Parameters:

name type arguments description
key string

Asset key for the sound.

config Phaser.Types.Sound.SoundConfig <optional>

An optional config object containing default sound settings.

Returns:
Description:

The new sound instance.

Overrides: Phaser.Sound.BaseSoundManager#add
Since: 3.0.0
Focus
Focus
addAudioSprite(key, [config])
Focus
Focus

Description:

Adds a new audio sprite sound into the sound manager. Audio Sprites are a combination of audio files and a JSON configuration. The JSON follows the format of that created by https://github.com/tonistiigi/audiosprite

Parameters:

name type arguments description
key string

Asset key for the sound.

config Phaser.Types.Sound.SoundConfig <optional>

An optional config object containing default sound settings.

Returns:
Description:

The new audio sprite sound instance.

Inherited from: Phaser.Sound.BaseSoundManager#addAudioSprite
Since: 3.0.0
Focus
Focus
addListener(event, fn, [context])
Focus
Focus

Description:

Add a listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#addListener
Since: 3.0.0
Focus
Focus
createAudioContext(game)
Focus
Focus

Description:

Method responsible for instantiating and returning AudioContext instance. If an instance of an AudioContext class was provided through the game config, that instance will be returned instead. This can come in handy if you are reloading a Phaser game on a page that never properly refreshes (such as in an SPA project) and you want to reuse already instantiated AudioContext.

Parameters:

name type description
game Phaser.Game

Reference to the current game instance.

Returns:
Description:

The AudioContext instance to be used for playback.

Type:
  • AudioContext
Since: 3.0.0
Focus
Focus
decodeAudio([audioKey], [audioData])
Focus
Focus

Description:

Decode audio data into a format ready for playback via Web Audio.

The audio data can be a base64 encoded string, an audio media-type data uri, or an ArrayBuffer instance.

The audioKey is the key that will be used to save the decoded audio to the audio cache.

Instead of passing a single entry you can instead pass an array of Phaser.Types.Sound.DecodeAudioConfig objects as the first and only argument.

Decoding is an async process, so be sure to listen for the events to know when decoding has completed.

Once the audio has decoded it can be added to the Sound Manager or played via its key.

Parameters:

name type arguments description
audioKey string | Array.<Phaser.Types.Sound.DecodeAudioConfig> <optional>

The string-based key to be used to reference the decoded audio in the audio cache, or an array of audio config objects.

audioData ArrayBuffer | string <optional>

The audio data, either a base64 encoded string, an audio media-type data uri, or an ArrayBuffer instance.

Since: 3.18.0
Focus
Focus
destroy()
Focus
Focus

Description:

Calls Phaser.Sound.BaseSoundManager#destroy method and cleans up all Web Audio API related stuff.

Overrides: Phaser.Sound.BaseSoundManager#destroy
Since: 3.0.0
Focus
Focus
emit(event, [args])
Focus
Focus

Description:

Calls each of the listeners registered for a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

args * <optional>

Additional arguments that will be passed to the event handler.

Returns:
Description:

true if the event had listeners, else false.

Type:
  • boolean
Inherited from: Phaser.Events.EventEmitter#emit
Since: 3.0.0
Focus
Focus
eventNames()
Focus
Focus

Description:

Return an array listing the events for which the emitter has registered listeners.

Type:
  • Array.<(string
  • symbol)>
Inherited from: Phaser.Events.EventEmitter#eventNames
Since: 3.0.0
Focus
Focus
<private> forEachActiveSound(callback, [scope])
Focus
Focus

Description:

Method used internally for iterating only over active sounds and skipping sounds that are marked for removal.

Parameters:

name type arguments description
callback Phaser.Types.Sound.EachActiveSoundCallback

Callback function. (manager: Phaser.Sound.BaseSoundManager, sound: Phaser.Sound.BaseSound, index: number, sounds: Phaser.Manager.BaseSound[]) => void

scope * <optional>

Callback context.

Inherited from: Phaser.Sound.BaseSoundManager#forEachActiveSound
Since: 3.0.0
Focus
Focus
get(key)
Focus
Focus

Description:

Gets the first sound in this Sound Manager that matches the given key. If none can be found it returns null.

Parameters:

name type description
key string

Sound asset key.

Returns:
Description:
  • The sound, or null.
Inherited from: Phaser.Sound.BaseSoundManager#get
Since: 3.23.0
Focus
Focus
getAll([key])
Focus
Focus

Description:

Gets all sounds in this Sound Manager.

You can optionally specify a key, in which case only Sound instances that match the given key will be returned.

Parameters:

name type arguments description
key string <optional>

Optional asset key. If given, only Sound instances with this key will be returned.

Returns:
Description:
  • The sounds, or an empty array.
Type:
Inherited from: Phaser.Sound.BaseSoundManager#getAll
Since: 3.23.0
Focus
Focus
getAllPlaying()
Focus
Focus

Description:

Returns all sounds from this Sound Manager that are currently playing. That is, Sound instances that have their isPlaying property set to true.

Returns:
Description:
  • All currently playing sounds, or an empty array.
Type:
Inherited from: Phaser.Sound.BaseSoundManager#getAllPlaying
Since: 3.60.0
Focus
Focus
isPlaying(key)
Focus
Focus

Description:

When a key is given, returns true if any sound with that key is playing.

When no key is given, returns true if any sound is playing.

Parameters:

name type description
key string

Sound asset key.

Returns:
Description:
  • Per the key argument, true if any matching sound is playing, otherwise false.
Type:
  • boolean
Inherited from: Phaser.Sound.BaseSoundManager#isPlaying
Since: 3.85.0
Focus
Focus
listenerCount(event)
Focus
Focus

Description:

Return the number of listeners listening to a given event.

Parameters:

name type description
event string | symbol

The event name.

Returns:
Description:

The number of listeners.

Type:
  • number
Inherited from: Phaser.Events.EventEmitter#listenerCount
Since: 3.0.0
Focus
Focus
listeners(event)
Focus
Focus

Description:

Return the listeners registered for a given event.

Parameters:

name type description
event string | symbol

The event name.

Returns:
Description:

The registered listeners.

Type:
  • Array.<function()>
Inherited from: Phaser.Events.EventEmitter#listeners
Since: 3.0.0
Focus
Focus
off(event, [fn], [context], [once])
Focus
Focus

Description:

Remove the listeners of a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#off
Since: 3.0.0
Focus
Focus
on(event, fn, [context])
Focus
Focus

Description:

Add a listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#on
Since: 3.0.0
Focus
Focus
<protected> onBlur()
Focus
Focus

Description:

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

Overrides: Phaser.Sound.BaseSoundManager#onBlur
Since: 3.0.0
Focus
Focus
<protected> onFocus()
Focus
Focus

Description:

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

Overrides: Phaser.Sound.BaseSoundManager#onFocus
Since: 3.0.0
Focus
Focus
<private> onGameBlur()
Focus
Focus

Description:

Internal handler for Phaser.Core.Events#BLUR.

Inherited from: Phaser.Sound.BaseSoundManager#onGameBlur
Since: 3.23.0
Focus
Focus
<private> onGameFocus()
Focus
Focus

Description:

Internal handler for Phaser.Core.Events#FOCUS.

Inherited from: Phaser.Sound.BaseSoundManager#onGameFocus
Since: 3.23.0
Focus
Focus
once(event, fn, [context])
Focus
Focus

Description:

Add a one-time listener for a given event.

Parameters:

name type arguments Default description
event string | symbol

The event name.

fn function

The listener function.

context * <optional> this

The context to invoke the listener with.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#once
Since: 3.0.0
Focus
Focus
pauseAll()
Focus
Focus

Description:

Pauses all the sounds in the game.

Inherited from: Phaser.Sound.BaseSoundManager#pauseAll
Since: 3.0.0
Focus
Focus
play(key, [extra])
Focus
Focus

Description:

Adds a new sound to the sound manager and plays it.

The sound will be automatically removed (destroyed) once playback ends.

This lets you play a new sound on the fly without the need to keep a reference to it.

Parameters:

name type arguments description
key string

Asset key for the sound.

extra Phaser.Types.Sound.SoundConfig | Phaser.Types.Sound.SoundMarker <optional>

An optional additional object containing settings to be applied to the sound. It could be either config or marker object.

Returns:
Description:

Whether the sound started playing successfully.

Type:
  • boolean
Inherited from: Phaser.Sound.BaseSoundManager#play
Since: 3.0.0
Focus
Focus
playAudioSprite(key, spriteName, [config])
Focus
Focus

Description:

Adds a new audio sprite sound to the sound manager and plays it. The sprite will be automatically removed (destroyed) once playback ends. This lets you play a new sound on the fly without the need to keep a reference to it.

Parameters:

name type arguments description
key string

Asset key for the sound.

spriteName string

The name of the sound sprite to play.

config Phaser.Types.Sound.SoundConfig <optional>

An optional config object containing default sound settings.

Returns:
Description:

Whether the audio sprite sound started playing successfully.

Type:
  • boolean
Inherited from: Phaser.Sound.BaseSoundManager#playAudioSprite
Since: 3.0.0
Focus
Focus
remove(sound)
Focus
Focus

Description:

Removes a sound from the sound manager. The removed sound is destroyed before removal.

Parameters:

name type description
sound Phaser.Sound.BaseSound

The sound object to remove.

Returns:
Description:

True if the sound was removed successfully, otherwise false.

Type:
  • boolean
Inherited from: Phaser.Sound.BaseSoundManager#remove
Since: 3.0.0
Focus
Focus
removeAll()
Focus
Focus

Description:

Removes all sounds from the manager, destroying the sounds.

Inherited from: Phaser.Sound.BaseSoundManager#removeAll
Since: 3.23.0
Focus
Focus
removeAllListeners([event])
Focus
Focus

Description:

Remove all listeners, or those of the specified event.

Parameters:

name type arguments description
event string | symbol <optional>

The event name.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#removeAllListeners
Since: 3.0.0
Focus
Focus
removeByKey(key)
Focus
Focus

Description:

Removes all sounds from the sound manager that have an asset key matching the given value. The removed sounds are destroyed before removal.

Parameters:

name type description
key string

The key to match when removing sound objects.

Returns:
Description:

The number of matching sound objects that were removed.

Type:
  • number
Inherited from: Phaser.Sound.BaseSoundManager#removeByKey
Since: 3.0.0
Focus
Focus
removeListener(event, [fn], [context], [once])
Focus
Focus

Description:

Remove the listeners of a given event.

Parameters:

name type arguments description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Returns:
Description:

this.

Inherited from: Phaser.Events.EventEmitter#removeListener
Since: 3.0.0
Focus
Focus
resumeAll()
Focus
Focus

Description:

Resumes all the sounds in the game.

Inherited from: Phaser.Sound.BaseSoundManager#resumeAll
Since: 3.0.0
Focus
Focus
setAudioContext(context)
Focus
Focus

Description:

This method takes a new AudioContext reference and then sets this Sound Manager to use that context for all playback.

As part of this call it also disconnects the master mute and volume nodes and then re-creates them on the new given context.

Parameters:

name type description
context AudioContext

Reference to an already created AudioContext instance.

Returns:
Description:

The WebAudioSoundManager instance.

Since: 3.21.0
Focus
Focus
setDetune(value)
Focus
Focus

Description:

Sets the global detuning of all sounds in cents. The range of the value is -1200 to 1200, but we recommend setting it to 50.

Parameters:

name type description
value number

The range of the value is -1200 to 1200, but we recommend setting it to 50.

Returns:
Description:

This Sound Manager.

Inherited from: Phaser.Sound.BaseSoundManager#setDetune
Since: 3.3.0
Focus
Focus
setListenerPosition([x], [y])
Focus
Focus

Description:

Sets the X and Y position of the Spatial Audio listener on this Web Audios context.

If you call this method with no parameters it will default to the center-point of the game canvas. Depending on the type of game you're making, you may need to call this method constantly to reset the listener position as the camera scrolls.

Calling this method does nothing on HTML5Audio.

Parameters:

name type arguments description
x number <optional>

The x position of the Spatial Audio listener.

y number <optional>

The y position of the Spatial Audio listener.

Overrides: Phaser.Sound.BaseSoundManager#setListenerPosition
Since: 3.60.0
Focus
Focus
setMute(value)
Focus
Focus

Description:

Sets the muted state of all this Sound Manager.

Parameters:

name type description
value boolean

true to mute all sounds, false to unmute them.

Returns:
Description:

This Sound Manager.

Since: 3.3.0
Focus
Focus
setRate(value)
Focus
Focus

Description:

Sets the global playback rate at which all the sounds will be played.

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 audios playback speed.

Parameters:

name type description
value number

Global playback rate at which all the sounds will be played.

Returns:
Description:

This Sound Manager.

Inherited from: Phaser.Sound.BaseSoundManager#setRate
Since: 3.3.0
Focus
Focus
setVolume(value)
Focus
Focus

Description:

Sets the volume of this Sound Manager.

Parameters:

name type description
value number

The global volume of this Sound Manager.

Returns:
Description:

This Sound Manager.

Since: 3.3.0
Focus
Focus
shutdown()
Focus
Focus

Description:

Removes all listeners.

Inherited from: Phaser.Events.EventEmitter#shutdown
Since: 3.0.0
Focus
Focus
stopAll()
Focus
Focus

Description:

Stops all the sounds in the game.

Inherited from: Phaser.Sound.BaseSoundManager#stopAll
Since: 3.0.0
Focus
Focus
stopByKey(key)
Focus
Focus

Description:

Stops any sounds matching the given key.

Parameters:

name type description
key string

Sound asset key.

Returns:
Description:
  • How many sounds were stopped.
Type:
  • number
Inherited from: Phaser.Sound.BaseSoundManager#stopByKey
Since: 3.23.0
Focus
Focus
unlock()
Focus
Focus

Description:

Unlocks Web Audio API on the initial input event.

Read more about how this issue is handled here in this article.

Overrides: Phaser.Sound.BaseSoundManager#unlock
Since: 3.0.0
Focus
Focus
<protected> update(time, delta)
Focus
Focus

Description:

Update method called on every game step.

Removes destroyed sounds and updates every active sound in the game.

Parameters:

name type description
time number

The current timestamp as generated by the Request Animation Frame or SetTimeout.

delta number

The delta time elapsed since the last frame.

Overrides: Phaser.Sound.BaseSoundManager#update
Since: 3.0.0
Focus
Focus