Игровое аудио — Sound, голоса, шины

Звуковые эффекты для игр: Sound — клип, декодированный заранее, а audio.play() сразу пускает его в микс — много одновременно, с питчем, случайными вариантами и приоритетами — через шины с громкостью, эхом и реверберацией. Звуки приложения (тап по кнопке, сигнал, музыка) играют через AudioPlayer, на любом хосте; audio — микшер игрового движка: только десктоп и iOS, на Android, в вебе и в веб-плеере — немой no-op.

  • сыграть звуковой эффект в игре — выстрел, прыжок, подбор монеты (audio.play)
  • каждый раз играть другой звук шага или удара (варианты)
  • зациклить звук двигателя или ветра и менять его питч на ходу (Voice)
  • плавно увести звук в тишину или запустить что-то, когда он доиграл (ended)
  • задать отдельную громкость музыке, эффектам и звукам UI (шины)
  • добавить звукам реверберацию, эхо или приглушающий low-pass-фильтр
  • не дать важным звукам оборваться, когда играет много сразу (priority)
  • глушить эффекты на паузе, понижать их тон в замедлении
  • откатиться на AudioPlayer там, где игровое аудио не работает
  • проверить в headless-тесте, что звук сыграл (expect.audio)

Платформы: iOS (варианты движка full, 2d и core), десктоп; не на Android, не в вебе и не в веб-плеере — проверяй audio.supported.

Обзор

TypeScript
const main = async () => {
  const click = await Sound.load(asset('./sfx/click.wav'))
  const steps = await Sound.load([asset('./sfx/step1.wav'), asset('./sfx/step2.wav'), asset('./sfx/step3.wav')])
  const hum = await Sound.load(asset('./sfx/hum.wav'))

  audio.play(click, { bus: 'ui' })                                       // запустил и забыл
  audio.play(steps, { volume: 0.6, pitch: 0.9 + Math.random() * 0.2 })  // случайный вариант при каждом play

  const engine = audio.play(hum, { loop: true, fade: 0.5 })               // держим Voice, чтобы управлять им
  engine.pitch = 1.3
  engine.addEventListener('ended', () => console.log('engine off'))
  setTimeout(() => engine.stop({ fade: 1 }), 3000)

  audio.bus('sfx').reverb = 'cave'
  audio.bus('music').volume = 0.5
}
main()

Где работает игровое аудио: audio.supported

audio.supported говорит, микширует ли этот хост игровое аудио: true на десктопном хосте и на iOS, как только движок открыл аудиоустройство, false на Android, в вебе и в веб-плеере. Без него ничего не бросает исключений: Sound.load сразу резолвится в немой клип (ready === false) без загрузки, play возвращает уже завершённый Voice, каждый сеттер — no-op. Где звук должен быть слышен на любом хосте, откатывайся на AudioPlayer:

TypeScript
const main = async () => {
  const coinUrl = asset('./sfx/coin.wav')
  const coin = await Sound.load(coinUrl)      // немой клип там, где audio.supported равен false

  const playCoin = () => {                    // игра вызывает это при каждом подборе
    if (audio.supported) audio.play(coin)
    else new AudioPlayer(coinUrl).play()      // Android, веб: плеер платформы
  }
  playCoin()
}
main()

Оболочка iOS-приложения несёт самый маленький вариант движка, которого хватает её бандлу, а в варианте 3d (его выбирают для приложения с 3D, но без 2D) игрового аудио нет: чтобы оно было, задай "ios": { "variant": "full" } в app.json. Приложение-вьюер le.codes на iOS работает на варианте full.

Note

iOS-хост не задаёт категорию аудиосессии, так что действует умолчание Apple, пока плагин, который пишет звук (audio-recorder, speech, webrtc), не задаст свою: переключатель «Звонок/Бесшумно» глушит игровое аудио, а в фоне звук останавливается.

Загружай звуки до того, как они зазвучат: Sound.load

Загрузи каждый эффект один раз, до старта уровня: Sound.load скачивает файл и декодирует весь клип, так что последующий play стартует мгновенно и ничего не стоит.

TypeScript
Sound.load(src: string | string[], options?: { stereo?: boolean }): Promise<Sound>
sound.duration      // секунды (первого варианта); 0 для немого клипа
sound.channels      // 1, или 2 с { stereo: true }
sound.variants      // из скольких файлов он загружен
sound.urls          // источники, как переданы
sound.ready         // false без аудио хоста или после dispose()
sound.disposed      // true после dispose()
sound.dispose()     // освободить декодированный клип сейчас; играющие его голоса сразу останавливаются. Идемпотентно

src — всё, что принимает fetch: asset('./x.wav'), удалённый URL. WAV, MP3 и OGG Vorbis; файл, который не декодируется, отклоняет промис (Sound.load: <url>: cannot decode (wav / mp3 / ogg vorbis)). Декодирование идёт вне главного потока.

Клип декодируется в моно, если не передан { stereo: true }: моно — то, что пространственно размещает 3D-источник, и то, чем эффекты и так являются. Оставь стерео для 2D-подложек и эмбиентов; стереоклипы играют на своём, меньшем пуле голосов.

Note

Sound держит весь клип в памяти как 32-битный float на частоте движка — 192 КБ на секунду моно при 48 кГц, вдвое больше в стерео (audio.stats.clipBytes). Он живёт всё время работы приложения: потеря ссылки ничего не освобождает. Делай dispose() тому, что завершённому уровню больше не нужно. Музыка, озвучка и длинные треки — дело AudioPlayer, медиаплеера платформы: один файл на плеер.

Случайные варианты: шаги, удары

Загрузи массив файлов, чтобы каждый раз играл другой: каждый play выбирает вариант случайно и, когда их три и больше, никогда не повторяет один и тот же дважды подряд — шаги, удары, рикошеты.

TypeScript
const main = async () => {
  const steps = await Sound.load([asset('./sfx/step1.wav'), asset('./sfx/step2.wav'), asset('./sfx/step3.wav')])

  const footstep = () =>                      // вызывай каждый раз, когда нога касается земли
    audio.play(steps, { volume: 0.6, pitch: 0.9 + Math.random() * 0.2 })   // вариант, чуть сдвинутый по высоте
  footstep()
}
main()

Звуковой эффект в игре: audio.play

В игре audio.play сразу запускает загруженный Sound — выстрел, прыжок, монету — и возвращает его Voice. Клик кнопки в приложении — это AudioPlayer: на Android и в вебе audio молчит.

TypeScript
audio.play(sound: Sound, options?: {
  volume?: number     // линейное усиление; по умолчанию 1 (больше 1 усиливает)
  pitch?: number      // скорость воспроизведения, 0.01 … 10: 2 = на октаву выше и вдвое быстрее; по умолчанию 1
  loop?: boolean      // по умолчанию false
  bus?: string        // по умолчанию 'sfx'
  priority?: number   // перевешивает меньшие числа, когда пул полон; по умолчанию 0
  fade?: number       // fade-in, секунды; по умолчанию 0
  startAt?: number    // секунды от начала клипа; по умолчанию 0
  pan?: number        // -1 слева … 1 справа; по умолчанию 0
}): Voice
audio.stopAll(fade?: number)   // каждый голос на каждой шине; fade в секундах, по умолчанию 0
TypeScript
const main = async () => {
  const jump = await Sound.load(asset('./sfx/jump.wav'))   // загрузить один раз, до старта уровня

  Input.on('keydown', (e) => {
    if (e.code !== 'Space' || e.repeat) return
    audio.play(jump, { volume: 0.8 })                      // запустил и забыл: доиграет до конца
  })
}
main()

audio.play — 2D: звучит одинаково, что бы ни делала камера, размещается только через pan. Для звука в точке мира — эмиттеры на узлах, зоны реверберации, слушатель — используй 3D-аудио (AudioSource, audio.playAt), на том же движке.

Слишком много звуков сразу: пул голосов и priority

Движок микширует не более 80 моно- и 20 стереоголосов одновременно и ничего не аллоцирует на каждый play. Когда пул полон, новый звук забирает слот играющего голоса с меньшим или равным priority: сначала самый низкий приоритет, затем одиночные звуки раньше циклов, затем самый тихий, затем самый старый. Вытесненный голос завершается (ended срабатывает, audio.stats.stolen его считает). Если у каждого играющего голоса приоритет выше, новый звук отклоняется: play возвращает уже завершённый голос.

Давай музыкальным подложкам, циклам двигателя и диалогам priority выше, чем пулям и шагам:

TypeScript
const main = async () => {
  const hum = await Sound.load(asset('./sfx/engine.wav'))
  const shot = await Sound.load(asset('./sfx/shot.wav'))

  const engine = audio.play(hum, { loop: true, priority: 5 })   // перевешивает любой выстрел
  for (let i = 0; i < 100; i++) audio.play(shot)                 // очередь: больше 80 моноголосов
  console.log('engine', engine.playing, 'cut off', audio.stats.stolen)   // engine true, cut off 21
}
main()

Зациклить звук и менять его на ходу: Voice

Держи Voice, который вернул audio.play, чтобы менять звук, пока он играет — двигатель, чей питч следует за скоростью, нарастающий ветер, — и чтобы его остановить.

TypeScript
voice.playing        // true, пока играет; false, когда закончился, остановлен или был отобран
voice.time           // секунды от начала клипа
voice.volume = 0.5   // вживую, те же единицы, что в опциях
voice.pitch = 1.2
voice.pan = -1       // только 2D-голоса
voice.stop(options?: { fade?: number })     // секунды; по умолчанию 0 (сразу)
voice.addEventListener('ended', () => { })  // один раз: клип закончился, stop() или пул забрал слот
TypeScript
const main = async () => {
  const hum = await Sound.load(asset('./sfx/engine.wav'))

  class EngineSound extends System<'engineSound'> {
    speed = 0                                                    // м/с: задаёт код машины
    private voice: Voice
    onAttach() { this.voice = audio.play(hum, { loop: true, fade: 0.5 }) }   // держим Voice
    update() { this.voice.pitch = 0.8 + Math.min(this.speed / 30, 1) }      // 0.8 на холостых … 1.8 на 30 м/с
    onDetach() { this.voice.stop({ fade: 0.3 }) }
  }

  const scene = new Scene().system(EngineSound)
  scene.open()
  scene.engineSound.speed = 15                                  // питч 1.3 со следующего кадра
}
main()

Voice — билет в пул движка, а не ресурс: потеря его ничего не освобождает, а одиночный звук, который никто не держит, играет до конца. Как только голос завершён, playing читается как false и его сеттеры ничего не делают — его слот, возможно, уже играет другой звук.

Затухание и действие по окончании звука: stop, ended

voice.stop({ fade }) плавно завершает цикл; событие ended сообщает, что голос завершён, — вешай на него то, что идёт дальше, например уровень, который стартует, когда отыграл обратный отсчёт.

TypeScript
const main = async () => {
  const countdown = await Sound.load(asset('./sfx/countdown.wav'))
  const wind = await Sound.load(asset('./sfx/wind.wav'), { stereo: true })

  const intro = audio.play(countdown, { bus: 'ui' })
  intro.addEventListener('ended', () => {                       // добавляй при запуске
    console.log('GO')                                           // здесь стартует уровень
    const ambience = audio.play(wind, { loop: true, fade: 2 })  // нарастает за 2 с
    setTimeout(() => ambience.stop({ fade: 3 }), 30000)         // затухает за 3 с
  })
}
main()
Note

ended срабатывает на кадре после завершения голоса — после stop() сразу, не дожидаясь fade. Добавляй слушатель при запуске: добавленный после завершения голоса никогда не сработает. Голос, который так и не заиграл (нет аудио хоста, Sound после dispose, отклонённый play), завершён с самого начала, и слушатель, добавленный к нему, срабатывает немедленно — так что цепочка вроде этой работает и там, где audio.supported равен false.

Отдельная громкость для музыки, эффектов и UI: audio.bus

Каждый голос играет через микшерную шину, так что одна настройка делает громче, тише или выключает целую группу звуков — эффекты, музыку, клики UI, — как это делают звуковые настройки игры.

TypeScript
audio.bus(name: string): Bus   // 'master' | 'sfx' | 'music' | 'ui' | 'voice', или своя
audio.master                   // audio.bus('master')

bus.name
bus.volume = 0.7               // линейное усиление; по умолчанию 1
bus.muted = true               // по умолчанию false
bus.lowpass = 1200             // частота среза в Гц, 20 … 20000; null = выкл (по умолчанию)
bus.echo = { delay: 0.35, decay: 0.4, mix: 0.3 }   // null = выкл (по умолчанию)
bus.reverb = 'hall'            // пресет, параметры или null = выкл (по умолчанию)
bus.stopAll(fade?: number)     // голоса, играющие на этой шине; fade в секундах
TypeScript
const main = async () => {
  const shot = await Sound.load(asset('./sfx/shot.wav'))
  const settings = { music: 0.4, effects: 0.8, interface: false }   // что сохранил экран настроек

  audio.bus('music').volume = settings.music
  audio.bus('sfx').volume = settings.effects
  audio.bus('ui').muted = !settings.interface

  audio.play(shot)                            // на 'sfx', шине по умолчанию: на 0.8
}
main()

Голос играет на sfx, если play (или его источник) не назвал другую шину; каждая другая шина идёт в master. Пять шин выше существуют с самого начала; любое другое имя создаёт шину при первом обращении — до 11 своих (16 всего). Сверх этого audio.bus() предупреждает и возвращает шину, которая ничего не делает, а голоса, отправленные на неё, играют на sfx. Bus получается только из audio.bus(); чтение настройки возвращает то, что было установлено.

Note

опечатка в имени шины — не ошибка: она тихо создаёт новую шину. А stopAll() на шине останавливает голоса, игравшие на ней, а не голоса шин, которые в неё идут: audio.master.stopAll() — это не audio.stopAll().

Note

AudioPlayer в этот микшер не входит — кроме десктопного хоста, где он играет через шину music: audio.bus('music') достаёт до него только там. В остальных местах задавай собственный volume плеера.

Реверберация, эхо и приглушение: эффекты шины

Шина может окрасить всё, что на ней играет: реверберация пещеры или зала, эхо в каньоне, low-pass, который приглушает звук под водой. Цепочка инсертов идёт low-pass → эхо → реверберация; изменения сглаживаются, так что переключение reverb в дверном проёме не щёлкает.

  • lowpass — частота среза в Гц, 20 … 20000: чем ниже, тем глуше.
  • echo — delay секунд между повторами (до 2), decay обратная связь 0 … 0.95 (сколько повторов выживает), mix доля «мокрого» сигнала 0 … 1. Отсутствующие поля: 0.3 / 0.4 / 0.3.
  • reverb — имя пресета или { roomSize, damping, width, mix, preDelay }: roomSize 0 (чулан) … 1 (собор), damping потеря высоких частот 0 … 1, width стереоширина хвоста 0 … 1, mix доля «мокрого» сигнала 0 … 1, preDelay секунды до хвоста (до 0.25). Отсутствующие поля берутся из room.

REVERB_PRESETS содержит шесть пресетов как параметры:

пресет roomSize damping width mix preDelay (с)
room 0.45 0.6 0.8 0.18 0.005
bathroom 0.55 0.15 0.6 0.35 0.002
hall 0.82 0.4 1.0 0.3 0.025
cave 0.9 0.25 1.0 0.45 0.04
arena 0.95 0.5 1.0 0.3 0.06
outdoor 0.3 0.8 1.0 0.06 0
TypeScript
const main = async () => {
  const shot = await Sound.load(asset('./sfx/shot.wav'))
  const sfx = audio.bus('sfx')

  sfx.reverb = 'cave'                                  // игрок заходит в пещеру
  sfx.echo = { delay: 0.35, decay: 0.4, mix: 0.25 }
  audio.play(shot)                                     // слышен с хвостом и эхом пещеры

  setTimeout(() => {                                   // через 5 с — под водой
    sfx.reverb = { ...REVERB_PRESETS.cave, mix: 0.2 }  // пресет, но «суше»
    sfx.echo = null                                    // выкл
    sfx.lowpass = 800                                  // Гц: глухо
  }, 5000)
}
main()

AudioZone подменяет реверберацию шины, пока слушатель внутри неё.

Пауза и замедление: Time.paused, Time.scale

Пауза игры глушит её эффекты: Time.paused (или Time.scale = 0) делает шину sfx mute, но не замораживает её — её голоса продолжают идти неслышно, и одиночный звук может закончиться во время паузы. Все остальные шины продолжают играть, так что меню паузы сохраняет свои клики ui и свою music. С audio.timeScalePitch = true Time.scale, отличный от 1, ещё и меняет питч шины sfx (замедление понижает тон каждого эффекта; 0.1 … 4×); по умолчанию false.

TypeScript
const main = async () => {
  const hum = await Sound.load(asset('./sfx/engine.wav'))
  const scene = new Scene()                   // игровые часы доходят до микшера через 3D-движок
  scene.open()

  audio.timeScalePitch = true                 // замедление ещё и понижает тон эффектов
  audio.play(hum, { loop: true })             // на 'sfx'
  Input.on('keydown', (e) => {
    if (e.code === 'Escape') Time.paused = !Time.paused              // 'sfx' молчит, 'ui' и 'music' играют дальше
    if (e.code === 'KeyT') Time.scale = Time.scale === 1 ? 0.3 : 1   // bullet time: медленнее и ниже
  })
}
main()
Note

игровые часы доходят до аудиодвижка через 3D-движок — это действует, как только существует Scene. Игра только на 2D (Scene2D) на паузе ничего не глушит: сам задавай audio.bus('sfx').muted = Time.paused везде, где игра встаёт на паузу или продолжается.

Голоса и занятая память: audio.stats

audio.stats читает счётчики движка — для отладочного оверлея или лога производительности: играющие голоса, голоса, обрезанные полным пулом, клипы в памяти.

TypeScript
audio.stats: {
  voicesPlaying: number   // живые голоса; голос, затухающий после stop(), уже не считается
  voicesMono: number
  voicesStereo: number
  stolen: number          // голоса, вытесненные полным пулом с момента старта движка
  clips: number           // декодированные клипы в памяти
  clipBytes: number       // их размер в байтах
  peak: number            // пик выхода master за последнюю секунду-две, линейный (1 = полная шкала)
  sampleRate: number      // частота микширования движка, Гц
  listenerZone: number    // зона реверберации, в которой слушатель (0 = нет) — см. 3D-аудио
  zoneBlend: number       // насколько глубоко внутри, 0 … 1
  hrtfVoices: number      // голоса, которые прямо сейчас рендерятся бинаурально — см. 3D-аудио
}

Каждое чтение запрашивает у движка свежий объект. Без аудио хоста — всё нули.

Проверка в тесте, что звук сыграл: expect.audio

Headless-флоу (lecodes render / lecodes test без --sim или --desktop) записывает игровое аудио, а не микширует его: audio.supported равен true, Sound загружается сразу с duration 0, а одиночный звук там никогда не заканчивается (голос завершают только stop() и audio.stopAll()), так что его ended не срабатывает. Шаг проверяет это через expect.audio: played проходит, как только какой-нибудь play до этого момента использовал клип, чей источник содержит этот текст, playing — число ещё не завершённых голосов. Для игры, которая по Space играет asset('./sfx/jump.wav'):

JSON
{ "steps": [
  { "frames": 10, "expect": { "audio": { "playing": 0 } } },
  { "key": "Space", "ms": 50, "expect": { "audio": { "played": "jump" } } }
] }

expect.audio проверяется только headless. Безоконный сервер (--sim) запускает настоящий движок без аудиоустройства: загрузки, пул и stats настоящие, но голоса не продвигаются, так что одиночный звук там никогда не заканчивается, — а декодирование занимает реальное время, пока кадры идут без ограничения, так что дай загрузкам длинный шаг frames.

Смотрите также

  • Медиа — AudioPlayer для звуков приложения, музыки и длинных треков
  • 3D-аудио — AudioSource, AudioZone, scene.audio, audio.playAt, наушники
  • Time — Time.paused / Time.scale
  • Системы — где живёт покадровая звуковая логика игры