О чем этот пример

При работе с аудио в HTML5-играх разработчики часто сталкиваются с микро-задержками при запуске и зацикливании звуков. Эти лаги нарушают ритм музыкальных игр и портят впечатление от геймплея. В этой статье мы разберем пример из официальной документации Phaser, который демонстрирует, как использовать свойства `audioPlayDelay` и `loopEndOffset` для компенсации этих задержек. Вы научитесь создавать идеально синхронизированные аудиодорожки, что критически важно для ритм-игр, интерактивных музыкальных приложений и любых проектов, где важен точный звук.

Версия Phaser: код и демо в этой статье рассчитаны на Phaser 3.90.0.

Живой запуск

Ниже встроен рабочий билд примера. Оригинальный источник: GitHub.

Исходный код


class Example extends Phaser.Scene
{
    bass;
    gui;
    bitmapFont;
    bottomSpeaker;
    middleSpeaker;
    topRightSpeaker;
    topLeftSpeaker;

    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.bitmapFont('atari-classic', 'assets/fonts/bitmap/atari-classic.png', 'assets/fonts/bitmap/atari-classic.xml');

        this.load.image('streets', 'assets/sprites/cyberpunk-street.png');

        this.load.atlas('speakers', 'assets/sprites/speakers/speakers.png', 'assets/sprites/speakers/speakers.json');

        this.load.audio('bass', [ 'assets/audio/tech/bass.ogg', 'assets/audio/tech/bass.mp3' ]);
        this.load.audio('drums', [ 'assets/audio/tech/drums.ogg', 'assets/audio/tech/drums.mp3' ]);
        this.load.audio('percussion', [ 'assets/audio/tech/percussion.ogg', 'assets/audio/tech/percussion.mp3' ]);
        this.load.audio('synth1', [ 'assets/audio/tech/synth1.ogg', 'assets/audio/tech/synth1.mp3' ]);
        this.load.audio('synth2', [ 'assets/audio/tech/synth2.ogg', 'assets/audio/tech/synth2.mp3' ]);
        this.load.audio('top1', [ 'assets/audio/tech/top1.ogg', 'assets/audio/tech/top1.mp3' ]);
        this.load.audio('top2', [ 'assets/audio/tech/top2.ogg', 'assets/audio/tech/top2.mp3' ]);
    }

    create ()
    {
        /*
         * These values are used to compensate for lags, caused by
         * time difference between calling play method on an audio
         * tag element and it actually staring to play audio and
         * changing audio tag playback position, in order to achieve
         * gapless looping and precise delayed playback.
         *
         * You might need to tweak this value to get the desired results
         * since lags vary depending on the browser/platform.
         */
        this.sound.audioPlayDelay = 0.1;
        this.sound.loopEndOffset = 0.05;

        const streets = this.add.image(0, 0, 'streets');
        streets.setScale(600 / 192);
        streets.setOrigin(0);

        this.topLeftSpeaker = this.add.image(445, 332, 'speakers', 'top-left');
        this.topLeftSpeaker.setOrigin(1, 0.46);
        this.topRightSpeaker = this.add.image(445, 332, 'speakers', 'top-right');
        this.topRightSpeaker.setOrigin(0, 0.975);
        this.middleSpeaker = this.add.image(443, 417, 'speakers', 'middle');
        this.middleSpeaker.setOrigin(0.5, 1);
        this.bottomSpeaker = this.add.image(443, 504, 'speakers', 'bottom');
        this.bottomSpeaker.setOrigin(0.5, 1);

        this.bass = this.sound.add('bass');
        const drums = this.sound.add('drums');
        const percussion = this.sound.add('percussion');
        const synth1 = this.sound.add('synth1');
        const synth2 = this.sound.add('synth2');
        const top1 = this.sound.add('top1');
        const top2 = this.sound.add('top2');

        this.gui = new dat.GUI();
        const sm = this.gui.addFolder('Sound Manager');
        sm.add(this.sound, 'rate', 0.5, 2).listen();
        sm.add(this.sound, 'detune', -1200, 1200).step(50).listen();

        const loopMarker = {
            name: 'loop',
            start: 0,
            duration: 7.68,
            config: {
                loop: true
            }
        };

        if (this.sound.locked)
        {
            const text = this.add.bitmapText(400, 70, 'atari-classic', 'Tap to start', 40);
            text.x -= Math.round(text.width / 2);
            text.y -= Math.round(text.height / 2);

            this.sound.once('unlocked', function (soundManager)
            {
                text.visible = false;

                this.startStem.call(this, this.bass, 'Bass', this.bottomSpeaker);

            }, this);
        }
        else
        {
            this.startStem.call(this, this.bass, 'Bass', this.bottomSpeaker);
        }

        this.bass.addMarker(loopMarker);

        // Delay option can only be passed in config
        this.bass.play('loop', {
            delay: 0
        });

        // Below won't work

        // sound.delay = delay;
        // sound.play('loop');

        this.bass.once('looped', function (sound)
        {
            this.startStem.call(this, drums, 'Drums', this.middleSpeaker);
        }, this);

        drums.addMarker(loopMarker);
        drums.play('loop', {
            delay: loopMarker.duration
        });
        drums.once('looped', function (sound)
        {
            this.startStem.call(this, percussion, 'Percussion', this.middleSpeaker);
        }, this);

        percussion.addMarker(loopMarker);
        percussion.play('loop', {
            delay: loopMarker.duration * 2
        });
        percussion.once('looped', function (sound)
        {
            this.startStem.call(this, synth1, 'Synth 1', this.topRightSpeaker);
        }, this);

        synth1.addMarker(loopMarker);
        synth1.play('loop', {
            delay: loopMarker.duration * 3
        });
        synth1.once('looped', function (sound)
        {
            this.startStem.call(this, synth2, 'Synth 2', this.topRightSpeaker);
        }, this);

        synth2.addMarker(loopMarker);
        synth2.play('loop', {
            delay: loopMarker.duration * 4
        });
        synth2.once('looped', function (sound)
        {
            this.startStem.call(this, top1, 'Top 1', this.topLeftSpeaker);
        }, this);

        top1.addMarker(loopMarker);
        top1.play('loop', {
            delay: loopMarker.duration * 5
        });
        top1.once('looped', function (sound)
        {
            this.startStem.call(this, top2, 'Top 2', this.topLeftSpeaker);
            sm.open();
        }, this);

        top2.addMarker(loopMarker);
        top2.play('loop', {
            delay: loopMarker.duration * 6
        });
    }

    update ()
    {
        this.middleSpeaker.y = this.bottomSpeaker.y - this.bottomSpeaker.height * this.bottomSpeaker.scaleY;
        this.topLeftSpeaker.y =
            this.topRightSpeaker.y =
                this.middleSpeaker.y - this.middleSpeaker.height * this.middleSpeaker.scaleY;

        this.tweens.setGlobalTimeScale(this.bass.totalRate);
    }

    startStem (stem, text, speaker)
    {
        const s = this.gui.addFolder(text);
        s.add(stem, 'seek', 0, stem.duration).step(0.01).listen();
        s.add(stem, 'mute').listen();
        s.open();

        this.tweens.add({
            targets: speaker,
            scaleX: 1.3,
            scaleY: 1.1,

            duration: 241,

            ease: 'Sine.easeInOut',
            repeat: -1,
            yoyo: true
        });
    }
}

/**
 * @author    Pavle Goloskokovic <pgoloskokovic@gmail.com> (http://prunegames.com)
 *
 * Cyberpunk Street Environment by Luis Zuno (https://www.patreon.com/posts/8303915) / CC-BY-3.0
 */

const config = {
    type: Phaser.AUTO,
    parent: 'phaser-example',
    width: 800,
    height: 600,
    backgroundColor: '#838282',
    scene: Example,
    pixelArt: true,
    audio: {
        disableWebAudio: true
    }
};

const game = new Phaser.Game(config);

Проблема: лаги HTML5 Audio API

При использовании HTML5 Audio (когда WebAudio отключен, как в этом примере) существует задержка между вызовом метода play() и фактическим началом воспроизведения. Аналогичная проблема возникает в момент перехода с конца лупа на его начало. Эти лаги зависят от браузера и платформы, из-за чего звук может "дребезжать" или появляться неприятные паузы.

В примере эти задержки компенсируются двумя свойствами менеджера звуков Phaser: this.sound.audioPlayDelay и this.sound.loopEndOffset.

this.sound.audioPlayDelay = 0.1;
this.sound.loopEndOffset = 0.05;

audioPlayDelay определяет, насколько раньше система начнет подготовку к воспроизведению. loopEndOffset указывает смещение от конца аудиофрагмента, с которого начнется подготовка к следующему циклу. Значения подобраны эмпирически и могут потребовать тонкой настройки под конкретный проект.

Структура примера: загрузка и создание сцены

Пример загружает несколько аудиофайлов, каждый из которых представляет собой отдельный музыкальный слой (stem): бас, барабаны, перкуссию и синтезаторы. Для совместимости указываются два формата: OGG и MP3.

this.load.audio('bass', [ 'assets/audio/tech/bass.ogg', 'assets/audio/tech/bass.mp3' ]);

В методе create() создаются спрайты колонок и объекты звуков через this.sound.add(). Ключевой элемент — создание маркера лупа. Маркер определяет имя, начало, длину и конфигурацию зацикленного фрагмента.

const loopMarker = {
    name: 'loop',
    start: 0,
    duration: 7.68,
    config: {
        loop: true
    }
};

Каждому звуковому объекту добавляется этот маркер методом addMarker().

Последовательный запуск с задержкой

Магия синхронизации происходит при запуске лупов с параметром delay. Каждый следующий слой начинает воспроизводиться не сразу, а со смещением, кратным длине маркера. Это создает эффект постепенного наложения инструментов.

// Запуск баса сразу
this.bass.play('loop', {
    delay: 0
});

// Запуск барабанов через одну длину лупа
drums.play('loop', {
    delay: loopMarker.duration
});

// Запуск перкуссии через две длины лупа
percussion.play('loop', {
    delay: loopMarker.duration * 2
});

Важное замечание из кода: параметр delay можно передать только в конфиге метода play(). Попытка установить sound.delay = value перед вызовом play() не сработает.

События и визуальная обратная связь

Для точного контроля момента, когда нужно запустить следующий слой, используется событие 'looped'. Оно срабатывает после первого завершения цикла.

this.bass.once('looped', function (sound) {
    this.startStem.call(this, drums, 'Drums', this.middleSpeaker);
}, this);

Метод startStem() выполняет две задачи: 1. Добавляет папку в GUI (dat.GUI) для управления громкостью и перемоткой конкретного звука. 2. Запускает твин на спрайте колонки, чтобы она пульсировала в такт музыке.

this.tweens.add({
    targets: speaker,
    scaleX: 1.3,
    scaleY: 1.1,
    duration: 241, // Длительность твина синхронизирована с темпом
    ease: 'Sine.easeInOut',
    repeat: -1,
    yoyo: true
});

В методе update() глобальная скорость твинов привязывается к общей скорости воспроизведения баса (this.bass.totalRate), что гарантирует сохранение синхронизации анимации и звука даже при изменении темпа.

Конфигурация проекта и обработка блокировки аудио

В конфиге игры явно отключается WebAudio, чтобы пример работал именно на HTML5 Audio API, где и проявляется проблема задержек.

const config = {
    // ... другие настройки ...
    audio: {
        disableWebAudio: true
    }
};

Так как в некоторых браузерах (особенно мобильных) воспроизведение аудио требует жеста пользователя, в коде есть проверка this.sound.locked. Если звук заблокирован, на экране появляется надпись "Tap to start". После первого взаимодействия срабатывает событие 'unlocked', и композиция начинает играть.

if (this.sound.locked) {
    // Показать текст "Tap to start"
    this.sound.once('unlocked', function (soundManager) {
        // Скрыть текст и запустить первый слой
    }, this);
}

Что попробовать дальше

Использование audioPlayDelay и loopEndOffset — это эффективный способ борьбы с артефактами воспроизведения в HTML5 Audio. Этот подход позволяет создавать сложные, идеально синхронизированные музыкальные композиции прямо в браузере. Для экспериментов попробуйте изменить значения задержек под ваш браузер, создать более сложную последовательность запуска лупов или привязать анимацию к другим событиям звука, например, 'pause' или 'stop'. Вы также можете адаптировать этот паттерн для синхронизации звуковых эффектов с анимацией персонажей в игре.