О чем этот пример
Создание сложных музыкальных композиций или ритмичных звуковых ландшафтов в играх требует точной синхронизации аудиодорожек. Из-за особенностей браузеров и HTML5 Audio между запуском звука и его фактическим воспроизведением возникает задержка, которая ломает идеальные петли и сбивает ритм. В этой статье мы разберем официальный пример 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 (особенно когда disableWebAudio установлен в true) существует небольшая, но критичная задержка между моментом вызова метода play() и моментом, когда звук действительно начинает воспроизводиться. Эта задержка варьируется в зависимости от браузера и платформы. Без ее учета петля (loop) звука будет не бесшовной — между окончанием одного проигрывания и началом следующего появится щелчок или пауза. Точно так же запланированное воспроизведение звука с задержкой (delay) начнется не в точно рассчитанное время.
Пример в статье наглядно демонстрирует эту проблему и ее решение, собирая музыкальный трек из семи отдельных семплов (степов), которые запускаются друг за другом с точной задержкой.
Решение: настройка аудио-менеджера
Phaser предоставляет два свойства в глобальном объекте this.sound для тонкой настройки времени воспроизведения. Их нужно задать в методе create() до начала работы со звуками.
this.sound.audioPlayDelay = 0.1;
this.sound.loopEndOffset = 0.05;* audioPlayDelay: Компенсирует задержку между командой на воспроизведение и фактическим стартом. Значение 0.1 секунды — это отправная точка, которую, как указано в комментариях кода, возможно, придется подбирать экспериментально под вашу цель.
* loopEndOffset: Смещение, которое определяет, когда именно звук должен начать следующую итерацию петли. Это помогает сделать переход от конца лупа к его началу абсолютно плавным.
Важно: эти настройки работают только при использовании HTML5 Audio (disableWebAudio: true в конфиге).
Создание и запуск звуков с маркерами и задержкой
Основная логика примера — последовательный запуск семи аудио-степов. Каждый стем — это экземпляр Sound, загруженный в preload(). Для организации лупа используется метод addMarker(), который определяет именованный отрезок звукового файла.
const loopMarker = {
name: 'loop',
start: 0,
duration: 7.68,
config: {
loop: true
}
};
// Создаем звук и добавляем ему маркер
this.bass = this.sound.add('bass');
this.bass.addMarker(loopMarker);Ключевой момент — параметр delay при запуске. Он передается не в свойство объекта, а исключительно в конфигурационном объекте второго аргумента метода play(). В примере каждый следующий звук запускается с задержкой, кратной длине маркера, создавая эффект постепенного наложения дорожек.
// Правильно: задержка в конфиге
this.bass.play('loop', {
delay: 0
});
// Неправильно: так не сработает
// sound.delay = delay;
// sound.play('loop');
// Следующий звук запустится через одну длину маркера
drums.play('loop', {
delay: loopMarker.duration
});Последовательность запуска организуется через обработчик события looped, который срабатывает после первого завершения лупа.
Визуализация и управление через GUI
Пример не только про аудио, но и про связь звука с графикой и предоставление инструментов отладки. Каждый запущенный стем визуализируется твином на соответствующем изображении колонки, который пульсирует в такт.
this.tweens.add({
targets: speaker,
scaleX: 1.3,
scaleY: 1.1,
duration: 241,
ease: 'Sine.easeInOut',
repeat: -1,
yoyo: true
});Библиотека dat.GUI создает панель управления, где можно в реальном времени менять глобальную скорость (rate) и тон (detune) всего микса, а также для каждого стема отдельно управлять позицией воспроизведения (seek) и отключением звука (mute). В методе update() глобальная шкала времени твинов привязывается к общей скорости звука, чтобы анимация всегда соответствовала музыке.
this.tweens.setGlobalTimeScale(this.bass.totalRate);Важные нюансы конфигурации
Для работы данного механизма корректировки задержек критически важна правильная настройка игры. В конфигурационном объекте необходимо явно отключить WebAudio и включить pixelArt для сохранения стиля пиксельной графики (хотя это не влияет на звук).
const config = {
type: Phaser.AUTO,
// ... другие параметры ...
pixelArt: true,
audio: {
disableWebAudio: true // Используем HTML5 Audio
}
};Также в коде есть обработка сценария, когда аудио заблокировано политикой браузера (требуется взаимодействие пользователя). В этом случае выводится текст "Tap to start", и первый звук запускается только после события unlocked.
Что попробовать дальше
Использование audioPlayDelay и loopEndOffset в Phaser — это мощный метод для достижения профессионального качества аудио в играх, где важна точная синхронизация. Он позволяет создавать сложные, многослойные музыкальные композиции без щелчков и рассинхрона.
**Идеи для экспериментов:**
1. Поэкспериментируйте со значениями задержек (0.05, 0.15) на разных браузерах и устройствах, чтобы найти оптимальные для вашего проекта.
2. Попробуйте создать систему ритмичных звуковых эффектов (шаги, выстрелы), которые запускаются с точной задержкой относительно музыки, используя тот же принцип с delay.
3. Свяжите параметры звука (например, rate или detune) с игровой механикой, чтобы музыка динамически менялась в зависимости от действий игрока.