PixiJS Sound

Class: SoundLibrary

SoundLibrary

Manages the playback of sounds. This is the main class for PixiJS Sound. If you're using the browser-based bundled this is PIXI.sound. Otherwise, you can do this:

Example

 import { sound } from '@pixi/sound';

 // sound is an instance of SoundLibrary
 sound.add('my-sound', 'path/to/file.mp3');
 sound.play('my-sound');

Members

context IMediaContext readonly

The global context to use.

disableAutoPause boolean

This disables auto-pause all playback when the window blurs (WebAudio only). This is helpful to keep from playing sounds when the user switches tabs. However, if you're running content within an iframe, this may be undesirable and you should disable (set to true) this behavior.

Default Value:
  • false

filtersAll filters.Filter[]

Apply filters to all sounds. Can be useful for setting global planning or global effects. Only supported with WebAudio.

Example
import { sound, filters } from '@pixi/sound';
// Adds a filter to pan all output left
sound.filtersAll = [
    new filters.StereoFilter(-1)
];

speedAll number

Set the global speed for all sounds. To set per-sound speed see SoundLibrary#speed.

supported boolean

true if WebAudio is supported on the current browser.

useLegacy boolean

Do not use WebAudio, force the use of legacy. This must be called before loading any files.

volumeAll number

Set the global volume for all sounds. To set per-sound volume see SoundLibrary#volume.

Methods

add (alias, sound) Sound

Register an existing sound with the library cache.

Name Type Description
alias string

The sound alias reference.
sound Sound

Sound reference to use.
Returns:
Type Description
Sound Instance of the Sound object.

add (alias, options) Sound

Adds a new sound by alias.

Name Type Description
alias string

The sound alias reference.
options ArrayBuffer | AudioBuffer | String | Options | HTMLAudioElement

Either the path or url to the source file. or the object of options to use.
Returns:
Type Description
Sound Instance of the Sound object.

add (map, globalOptions) SoundMap

Adds multiple sounds at once.

Name Type Attributes Description
map SoundSourceMap

Map of sounds to add, the key is the alias, the value is the string, ArrayBuffer, AudioBuffer, HTMLAudioElement or the list of options (see Options for full options).
globalOptions Options <optional>

The default options for all sounds. if a property is defined, it will use the local property instead.
Returns:
Type Description
SoundMap Instance to the Sound object.

close () this

Closes the sound library. This will release/destroy the AudioContext(s). Can be used safely if you want to initialize the sound library later. Use init method.

Returns:
Type Description
this

duration (alias) number

Get the length of a sound in seconds.

Name Type Description
alias string

The sound alias reference.
Returns:
Type Description
number The current duration in seconds.

exists (alias, assert) boolean

Checks if a sound by alias exists.

Name Type Default Description
alias string

Check for alias.
assert boolean false

Whether enable console.assert.
Returns:
Type Description
boolean true if the sound exists.

find (alias) Sound

Find a sound by alias.

Name Type Description
alias string

The sound alias reference.
Returns:
Type Description
Sound Sound object.

init () this

Re-initialize the sound library, this will recreate the AudioContext. If there's a hardware-failure call close and then init.

Returns:
Type Description
this Sound instance

isPlaying () boolean

Convenience function to check to see if any sound is playing.

Returns:
Type Description
boolean true if any sound is currently playing.

muteAll () this

Mutes all playing sounds.

Returns:
Type Description
this Instance for chaining.

pause (alias) Sound

Pauses a sound.

Name Type Description
alias string

The sound alias reference.
Returns:
Type Description
Sound Sound object.

pauseAll () this

Pauses any playing sounds.

Returns:
Type Description
this Instance for chaining.

play (alias, sprite) IMediaInstance | unknown

Plays a sound.

Name Type Description
alias string

The sound alias reference.
sprite string

The alias of the sprite to play.
Returns:
Type Description
IMediaInstance | unknown The sound instance, this cannot be reused after it is done playing. Returns null if the sound has not yet loaded.

play (alias, options) IMediaInstance | IMediaInstance<Promise>

Plays a sound.

Name Type Attributes Description
alias string

The sound alias reference.
options PlayOptions | Function <optional>

The options or callback when done.
Returns:
Type Description
IMediaInstance | IMediaInstance<Promise> The sound instance, this cannot be reused after it is done playing. Returns a Promise if the sound has not yet loaded.

remove (alias) this

Removes a sound by alias.

Name Type Description
alias string

The sound alias reference.
Returns:
Type Description
this Instance for chaining.

removeAll () this

Stops and removes all sounds. They cannot be used after this.

Returns:
Type Description
this Instance for chaining.

resume (alias) Sound

Resumes a sound.

Name Type Description
alias string

The sound alias reference.
Returns:
Type Description
Sound Instance for chaining.

resumeAll () this

Resumes any sounds.

Returns:
Type Description
this Instance for chaining.

speed (alias, speed) number

Get or set the speed for a sound.

Name Type Attributes Description
alias string

The sound alias reference.
speed number <optional>

Optional current speed to set.
Returns:
Type Description
number The current speed.

stop (alias) Sound

Stops a sound.

Name Type Description
alias string

The sound alias reference.
Returns:
Type Description
Sound Sound object.

stopAll () this

Stops all sounds.

Returns:
Type Description
this Instance for chaining.

toggleMuteAll () boolean

Toggle muted property for all sounds.

Returns:
Type Description
boolean true if all sounds are muted.

togglePauseAll () boolean

Toggle paused property for all sounds.

Returns:
Type Description
boolean true if all sounds are paused.

unmuteAll () this

Unmutes all playing sounds.

Returns:
Type Description
this Instance for chaining.

volume (alias, volume) number

Get or set the volume for a sound.

Name Type Attributes Description
alias string

The sound alias reference.
volume number <optional>

Optional current volume to set.
Returns:
Type Description
number The current volume.