name: audio-and-sound

description: "Use this skill when adding audio or sound to a Phaser 4 game. Covers loading audio, playing sounds, music, volume, spatial audio, Web Audio API, and SoundManager. Triggers on: sound, audio, music, volume, mute."

Audio and Sound

Phaser provides a unified Sound system via this.sound (a SoundManager) that abstracts over Web Audio API and HTML5 Audio. It handles loading, playback, volume, panning, looping, markers, audio sprites, spatial audio, and browser autoplay-policy unlocking.

Key source paths: src/sound/BaseSoundManager.js, src/sound/BaseSound.js, src/sound/webaudio/, src/sound/html5/, src/sound/SoundManagerCreator.js, src/sound/events/, src/sound/typedefs/

Related skills: ../loading-assets/SKILL.md, ../game-setup-and-config/SKILL.md

Quick Start

class GameScene extends Phaser.Scene {
    preload() {
        this.load.audio('bgm', 'assets/music.mp3');
        this.load.audio('coin', ['assets/coin.ogg', 'assets/coin.mp3']);
    }

    create() {
        // Fire-and-forget (auto-destroys when complete)
        this.sound.play('coin');

        // Retained reference for ongoing control
        this.music = this.sound.add('bgm', { loop: true, volume: 0.5 });
        this.music.play();
    }
}

Assets loaded via this.load.audio() in preload() are ready by the time create() runs. Provide an array of URLs for cross-browser format fallback.

Core Concepts

WebAudio vs HTML5 Audio

Phaser auto-selects the best backend via SoundManagerCreator.create():

1. If config.audio.noAudio is true, or the device supports neither Web Audio nor HTML5 Audio, a NoAudioSoundManager is created (all calls are no-ops).
2. If the device supports Web Audio and config.audio.disableWebAudio is not true, a WebAudioSoundManager is created (preferred).
3. Otherwise, an HTML5AudioSoundManager is created as fallback.

WebAudio advantages: precise timing, gapless looping, stereo panning (StereoPannerNode), spatial audio (PannerNode), per-sound gain nodes, decodeAudio() for runtime decoding.

HTML5 Audio limitations: no spatial audio, no real stereo panning (pan fires events but no audible effect), less precise looping, requires instances count at load time for simultaneous playback.

Force HTML5 or disable audio via game config: audio: { disableWebAudio: true } or audio: { noAudio: true }. Pass audio: { context: existingAudioContext } to reuse a WebAudio context in SPAs.

The SoundManager (this.sound)

Accessed via this.sound in any Scene. It is a single shared instance across the entire game. Key responsibilities:

• Adding, playing, and removing sound instances
• Global volume, mute, rate, and detune
• Automatic pause/resume when the browser tab loses/gains focus (pauseOnBlur, default true)
• Audio unlock handling for mobile browsers
• Spatial audio listener position (WebAudio only)

Sound Instances

Created via this.sound.add(key, config). Each instance has its own playback state, volume, rate, detune, loop, pan, and seek properties. A sound must exist in the audio cache (loaded via the Loader) before it can be added.

State flags: isPlaying (boolean), isPaused (boolean).

const sfx = this.sound.add('explosion', { volume: 0.8 });
sfx.play();        // returns boolean
sfx.pause();       // only works if isPlaying
sfx.resume();      // only works if isPaused
sfx.stop();        // resets to stopped state
sfx.destroy();     // marks for removal from manager

Common Patterns

Playing Sounds

Fire-and-forget -- this.sound.play(key, config?) adds, plays, and auto-destroys the sound on completion:

this.sound.play('explosion');
this.sound.play('powerup', { volume: 0.5, rate: 1.2 });

Retained reference -- this.sound.add(key, config?) then call play() on the instance:

const laser = this.sound.add('laser');
laser.play();
// Later: laser.stop(), laser.volume = 0.3, etc.

Volume, Rate, and Detune

Each property can be set per-sound or globally on the manager. Global and per-sound values combine (for rate/detune, they multiply via calculateRate()).

// Per-sound
sound.volume = 0.5;          // 0 to 1
sound.setVolume(0.5);        // chainable alternative
sound.rate = 1.5;            // 0.5 = half speed, 2.0 = double speed
sound.setRate(1.5);
sound.detune = 200;          // cents, -1200 to 1200
sound.setDetune(200);

// Global (affects all sounds)
this.sound.volume = 0.8;
this.sound.setVolume(0.8);
this.sound.rate = 1.0;
this.sound.setRate(1.0);
this.sound.detune = 0;
this.sound.setDetune(0);

The effective playback rate is: sound.rate * manager.rate * detuneRate where detuneRate = Math.pow(1.0005777895065548, sound.detune + manager.detune).

Looping

// Via config at creation
const bgm = this.sound.add('music', { loop: true });
bgm.play();

// Toggle during playback
bgm.loop = false;
bgm.setLoop(false);  // chai