Phaser API Documentation

  Version: 
Filter

Web Audio API implementation of the sound.

Constructor:

new WebAudioSound(manager, key, [config])

Parameters:

name type arguments Default description
manager Phaser.Sound.WebAudioSoundManager

Reference to the WebAudio Sound Manager that owns this Sound instance.

key string

Asset key for the sound.

config Phaser.Types.Sound.SoundConfig <optional> {}

An optional config object containing default sound settings.

Since: 3.0.0

Extends


Members

audioBuffer: AudioBuffer
Focus
Focus

Description:

Audio buffer containing decoded data of the audio asset to be played.

Type:
AudioBuffer
Since: 3.0.0
Focus
Focus
<private> config: Phaser.Types.Sound.SoundConfig
Focus
Focus

Description:

A config object used to store default sound settings' values. Default values will be set by properties' setters.

Type:
Inherited from: Phaser.Sound.BaseSound#config
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 113)
Focus
Focus
<private> currentConfig: Phaser.Types.Sound.SoundConfig
Focus
Focus

Description:

Reference to the currently used config. It could be default config or marker config.

Type:
Inherited from: Phaser.Sound.BaseSound#currentConfig
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 135)
Focus
Focus
<readonly> currentMarker: Phaser.Types.Sound.SoundMarker
Focus
Focus

Description:

Currently playing marker. 'null' if whole sound is playing.

Type:
Default: null
Inherited from: Phaser.Sound.BaseSound#currentMarker
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 159)
Focus
Focus
detune: number
Focus
Focus

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.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
<readonly> duration: number
Focus
Focus

Description:

A value representing the duration, in seconds. It could be total sound duration or a marker duration.

Type:
number
Inherited from: Phaser.Sound.BaseSound#duration
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 92)
Focus
Focus
<readonly> hasEnded: boolean
Focus
Focus

Description:

Used for keeping track when sound source playback has ended so its state can be updated accordingly.

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
<readonly> hasLooped: boolean
Focus
Focus

Description:

Used for keeping track when sound source has looped so its state can be updated accordingly.

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
<readonly> isPaused: boolean
Focus
Focus

Description:

Flag indicating if sound is currently paused.

Type:
boolean
Default: false
Inherited from: Phaser.Sound.BaseSound#isPaused
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 68)
Focus
Focus
<readonly> isPlaying: boolean
Focus
Focus

Description:

Flag indicating if sound is currently playing.

Type:
boolean
Default: false
Inherited from: Phaser.Sound.BaseSound#isPlaying
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 57)
Focus
Focus
<readonly> key: string
Focus
Focus

Description:

Asset key for the sound.

Type:
string
Inherited from: Phaser.Sound.BaseSound#key
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 47)
Focus
Focus
loop: boolean
Focus
Focus

Description:

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

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
loopSource: AudioBufferSourceNode
Focus
Focus

Description:

A reference to a second audio source used for gapless looped playback.

Type:
AudioBufferSourceNode
Default: null
Since: 3.0.0
Focus
Focus
loopTime: number
Focus
Focus

Description:

The time at which the sound loop source should actually start playback.

Based on BaseAudioContext.currentTime value.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus

Description:

Local reference to the sound manager.

Type:
Inherited from: Phaser.Sound.BaseSound#manager
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 38)
Focus
Focus
<readonly> markers: Object.<string, Phaser.Types.Sound.SoundMarker>
Focus
Focus

Description:

Object containing markers definitions.

Type:
Default: {}
Inherited from: Phaser.Sound.BaseSound#markers
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 148)
Focus
Focus
mute: boolean
Focus
Focus

Description:

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

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
muteNode: GainNode
Focus
Focus

Description:

Gain node responsible for controlling this sound's muting.

Type:
GainNode
Since: 3.0.0
Focus
Focus
pan: number
Focus
Focus

Description:

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

Always returns zero on iOS / Safari as it doesn't support the stereo panner node.

Type:
number
Default: 0
Since: 3.50.0
Focus
Focus
pannerNode: StereoPannerNode
Focus
Focus

Description:

Panner node responsible for controlling this sound's pan.

Doesn't work on iOS / Safari.

Type:
StereoPannerNode
Since: 3.50.0
Focus
Focus
pendingRemove: boolean
Focus
Focus

Description:

Flag indicating if destroy method was called on this sound.

Type:
boolean
Default: false
Inherited from: Phaser.Sound.BaseSound#pendingRemove
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 171)
Focus
Focus
playTime: number
Focus
Focus

Description:

The time at which the sound should have started playback from the beginning.

Treat this property as read-only.

Based on BaseAudioContext.currentTime value.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
rate: number
Focus
Focus

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

Type:
number
Default: 1
Since: 3.0.0
Focus
Focus
rateUpdates: array
Focus
Focus

Description:

An array where we keep track of all rate updates during playback.

Treat this property as read-only.

Array of object types: { time: number, rate: number }

Type:
array
Default: []
Since: 3.0.0
Focus
Focus
seek: number
Focus
Focus

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.

Type:
number
Since: 3.0.0
Focus
Focus
source: AudioBufferSourceNode
Focus
Focus

Description:

A reference to an audio source node used for playing back audio from audio data stored in Phaser.Sound.WebAudioSound#audioBuffer.

Type:
AudioBufferSourceNode
Default: null
Since: 3.0.0
Focus
Focus
spatialNode: PannerNode
Focus
Focus

Description:

The Stereo Spatial Panner node.

Type:
PannerNode
Since: 3.60.0
Focus
Focus

Description:

If the Spatial Panner node has been set to track a vector or Game Object, this retains a reference to it.

Type:
Since: 3.60.0
Focus
Focus
startTime: number
Focus
Focus

Description:

The time at which the sound source should have actually started playback.

Treat this property as read-only.

Based on BaseAudioContext.currentTime value.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
<readonly> totalDuration: number
Focus
Focus

Description:

The total duration of the sound in seconds.

Type:
number
Inherited from: Phaser.Sound.BaseSound#totalDuration
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 103)
Focus
Focus
<readonly> totalRate: number
Focus
Focus

Description:

A property that holds the value of sound's actual playback rate, after its rate and detune values has been combined with global rate and detune values.

Type:
number
Default: 1
Inherited from: Phaser.Sound.BaseSound#totalRate
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 79)
Focus
Focus
volume: number
Focus
Focus

Description:

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

Type:
number
Default: 1
Since: 3.0.0
Focus
Focus
volumeNode: GainNode
Focus
Focus

Description:

Gain node responsible for controlling this sound's volume.

Type:
GainNode
Since: 3.0.0
Focus
Focus
x: number
Focus
Focus

Description:

Sets the x position of this Sound in Spatial Audio space.

This only has any effect if the sound was created with a SpatialSoundConfig object.

Also see the WebAudioSoundManager.setListenerPosition method.

If you find that the sound becomes too quiet, too quickly, as it moves away from the listener, then try different refDistance property values when configuring the spatial sound.

Type:
number
Since: 3.60.0
Focus
Focus
y: number
Focus
Focus

Description:

Sets the y position of this Sound in Spatial Audio space.

This only has any effect if the sound was created with a SpatialSoundConfig object.

Also see the WebAudioSoundManager.setListenerPosition method.

If you find that the sound becomes too quiet, too quickly, as it moves away from the listener, then try different refDistance property values when configuring the spatial sound.

Type:
number
Since: 3.60.0
Focus
Focus

Methods

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
addMarker(marker)
Focus
Focus

Description:

Adds a marker into the current sound. A marker is represented by name, start time, duration, and optionally config object. This allows you to bundle multiple sounds together into a single audio file and use markers to jump between them for playback.

Parameters:

name type description
marker Phaser.Types.Sound.SoundMarker

Marker object.

Returns:
Description:

Whether the marker was added successfully.

Type:
  • boolean
Inherited from: Phaser.Sound.BaseSound#addMarker
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 182)
Focus
Focus
applyConfig()
Focus
Focus

Description:

Method used internally for applying config values to some of the sound properties.

Overrides: Phaser.Sound.BaseSound#applyConfig
Since: 3.0.0
Focus
Focus
calculateRate()
Focus
Focus

Description:

Method used internally to calculate total playback rate of the sound.

Overrides: Phaser.Sound.BaseSound#calculateRate
Since: 3.0.0
Focus
Focus
<private> createAndStartBufferSource()
Focus
Focus

Description:

Used internally.

Since: 3.0.0
Focus
Focus
createAndStartLoopBufferSource()
Focus
Focus

Description:

This method is only used internally and it creates a looping buffer source.

Since: 3.0.0
Focus
Focus
createBufferSource()
Focus
Focus

Description:

This method is only used internally and it creates a buffer source.

Type:
  • AudioBufferSourceNode
Since: 3.0.0
Focus
Focus
destroy()
Focus
Focus

Description:

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

Overrides: Phaser.Sound.BaseSound#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
getCurrentTime()
Focus
Focus

Description:

Method used internally for calculating current playback time of a playing sound.

Since: 3.0.0
Focus
Focus
getLoopTime()
Focus
Focus

Description:

Method used internally for calculating the time at witch the loop source should start playing.

Since: 3.0.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
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
pause()
Focus
Focus

Description:

Pauses the sound.

Returns:
Description:

Whether the sound was paused successfully.

Type:
  • boolean
Overrides: Phaser.Sound.BaseSound#pause
Since: 3.0.0
Focus
Focus
play([markerName], [config])
Focus
Focus

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.

Parameters:

name type arguments Default description
markerName string | Phaser.Types.Sound.SoundConfig <optional> ''

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 <optional>

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.

Returns:
Description:

Whether the sound started playing successfully.

Type:
  • boolean
Overrides: Phaser.Sound.BaseSound#play
Since: 3.0.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
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
removeMarker(markerName)
Focus
Focus

Description:

Removes a marker from the sound.

Parameters:

name type description
markerName string

The name of the marker to remove.

Returns:
Description:

Removed marker object or 'null' if there was no marker with provided name.

Inherited from: Phaser.Sound.BaseSound#removeMarker
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 259)
Focus
Focus
resetConfig()
Focus
Focus

Description:

Method used internally for resetting values of some of the config properties.

Inherited from: Phaser.Sound.BaseSound#resetConfig
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 428)
Focus
Focus
resume()
Focus
Focus

Description:

Resumes the sound.

Returns:
Description:

Whether the sound was resumed successfully.

Type:
  • boolean
Overrides: Phaser.Sound.BaseSound#resume
Since: 3.0.0
Focus
Focus
setDetune(value)
Focus
Focus

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 description
value number

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

Returns:
Description:

This Sound instance.

Since: 3.3.0
Focus
Focus
setLoop(value)
Focus
Focus

Description:

Sets the loop state of this Sound.

Parameters:

name type description
value boolean

true to loop this sound, false to not loop it.

Returns:
Description:

This Sound instance.

Since: 3.4.0
Focus
Focus
setMute(value)
Focus
Focus

Description:

Sets the muted state of this Sound.

Parameters:

name type description
value boolean

true to mute this sound, false to unmute it.

Returns:
Description:

This Sound instance.

Since: 3.4.0
Focus
Focus
setPan(value)
Focus
Focus

Description:

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

Note: iOS / Safari doesn't support the stereo panner node.

Parameters:

name type description
value number

The pan of the sound. A value between -1 (full left pan) and 1 (full right pan).

Returns:
Description:

This Sound instance.

Since: 3.50.0
Focus
Focus
setRate(value)
Focus
Focus

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

Parameters:

name type description
value number

The playback rate at of this Sound.

Returns:
Description:

This Sound instance.

Since: 3.3.0
Focus
Focus
setSeek(value)
Focus
Focus

Description:

Seeks to a specific point in this sound.

Parameters:

name type description
value number

The point in the sound to seek to.

Returns:
Description:

This Sound instance.

Since: 3.4.0
Focus
Focus
setVolume(value)
Focus
Focus

Description:

Sets the volume of this Sound.

Parameters:

name type description
value number

The volume of the sound.

Returns:
Description:

This Sound instance.

Since: 3.4.0
Focus
Focus
shutdown()
Focus
Focus

Description:

Removes all listeners.

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

Description:

Stop playing this sound.

Returns:
Description:

Whether the sound was stopped successfully.

Type:
  • boolean
Overrides: Phaser.Sound.BaseSound#stop
Since: 3.0.0
Focus
Focus
stopAndRemoveBufferSource()
Focus
Focus

Description:

This method is only used internally and it stops and removes a buffer source.

Since: 3.0.0
Focus
Focus
stopAndRemoveLoopBufferSource()
Focus
Focus

Description:

This method is only used internally and it stops and removes a looping buffer source.

Since: 3.0.0
Focus
Focus
update()
Focus
Focus

Description:

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

Overrides: Phaser.Sound.BaseSound#update
Since: 3.0.0
Focus
Focus
updateMarker(marker)
Focus
Focus

Description:

Updates previously added marker.

Parameters:

name type description
marker Phaser.Types.Sound.SoundMarker

Marker object with updated values.

Returns:
Description:

Whether the marker was updated successfully.

Type:
  • boolean
Inherited from: Phaser.Sound.BaseSound#updateMarker
Since: 3.0.0
Source: src/sound/BaseSound.js (Line 229)
Focus
Focus