AudioAdvancedControl

⚠️ Экспериментальный пакет. Не прошёл обкатку в продуктовой эксплуатации. Публичное API хэндлеров (AdvancedMusicHandler, AdvancedSoundHandler), режимы воспроизведения и состав настроечных полей могут измениться без обратной совместимости.

Namespace: Vortex.Sdk.AudioAdvancedControl.* Сборка: ru.vortex.sdk.audio.advancedcontrol


Назначение

Управляемый выгружаемый игровой звук: музыка и звуковые петли, привязанные к жизни объекта. Клип загружается перед запуском и уходит из памяти после останова.

  • Два хэндлера: AdvancedMusicHandler (слот cover-музыки) и AdvancedSoundHandler (обычный звук с каналом громкости).
  • Список клипов за AssetHandle<AudioClip> — в памяти только клип играющего трека.
  • Три режима: треки по списку, случайный с антиповтором, один раз.
  • Управление из UIStateSwitcher: публичные методы под EventFire.
  • Две паузы: игры и ручная.

Вне ответственности:

  • Короткие общие звуки (клики UI, эффекты) — это AudioSystem и записи базы звуков.
  • Громкость и высота отдельного клипа — не настраиваются.
  • Выбор, что и когда играет — решает тот, кто включает объект или зовёт методы.

Когда использовать: звук принадлежит подгружаемому контенту (катсцена, сцена, мини-игра) и не должен оставаться в памяти после него. Записи базы звуков из памяти не выгружаются.


Зависимости

Зависимость Назначение
Vortex.Core.AssetHandleSystem AssetHandle<AudioClip>
Vortex.Core.AudioSystem, Vortex.Unity.AudioSystem AudioController, хэндлы управления звуком и их события конца трека, SoundClipFixed
Vortex.Sdk.Core.GameCore GameController, GameStates.Paused — пауза игры
UniTask загрузка клипа

Использование

Повесить хэндлер на объект контента и заполнить список клипов.

Поле Назначение
clips список хэндлов клипов
mode режим проигрывания
autoStart запускать при включении объекта; по умолчанию включено
channel канал громкости — только у AdvancedSoundHandler

Музыка катсцены: AdvancedMusicHandler на корне контента с автозапуском.

Эмбиент фазы: AdvancedSoundHandler в режиме Index с одним клипом в списке (он играет по кругу) на объекте, который включает состояние фазы (GameObjectsSwitch). Состояние ушло — объект выключился, звук остановлен, клип отпущен.

Управление из состояния свитчера: EventFire с вызовом метода хэндлера.

handler.Play(2);       // трек №2
handler.PlayNext();    // следующий по режиму
handler.Stop();
handler.Pause();
handler.Unpause();

Архитектура

Handlers/
  AdvancedAudioHandler (abstract)  — список клипов, режим, выбор трека, загрузка и отпуск, конец трека, паузы
  ├── AdvancedMusicHandler         — выход: слот cover-музыки
  └── AdvancedSoundHandler         — выход: обычный звук, канал громкости

Model/
  AdvancedPlaybackMode             — Index / Random / OneShot

Пакет состоит из хэндлеров: общего состояния у него нет, шины и контроллера тоже.

Режимы

Режим Поведение
Index треки играют по списку: после окончания трека запускается следующий, после последнего — первый
Random после окончания трека запускается случайный; недавно игравшие не выбираются
OneShot трек играет один раз, затем звук останавливается и клип отпускается

Останавливается после проигрывания только OneShot. В Index и Random звук идёт, пока его не остановят.

Выбор трека

Номер текущего трека при включении объекта равен -1. Следующий номер выдаёт один внутренний метод:

  • Index и OneShot — увеличение на единицу, после последнего снова первый;
  • Random — случайный номер вне истории. История хранит половину списка (округляя вниз) — та же механика, что у звуков базы.

Автозапуск, PlayNext и переход к следующему треку по окончании идут через него: из -1 первым выпадает трек 0, в Random — случайный. Play(номер) выставляет номер напрямую.

Жизненный цикл

OnEnable  → номер = -1 → [autoStart] PlayNext
PlayNext / Play(n) → загрузка клипа → останов прежнего трека → запуск
трек доиграл → [Index / Random] следующий трек  |  [OneShot] останов → отпуск клипа
Stop      → останов → отпуск клипа
OnDisable → Stop

Порядок запуска один для музыки и звука:

  1. Запрос трека. Принимается только у включённого хэндлера. Клип асинхронно запрашивается у хэндла ассета. У каждого запроса свой токен отмены: новый запрос отменяет прежний, ещё не исполненный, и тот до запуска не доходит. Повторный запрос того же клипа, пока он грузится, присоединяется к идущей загрузке — трек запустится один раз.
  2. Загрузка клипа. Пока она идёт, прежний трек играет. Загрузка сорвалась — ошибка в лог и останов прежнего трека.
  3. Останов прежнего трека, если он был. Его клип отпускается, кроме случая, когда новый трек играет тот же клип.
  4. Воспроизведение.

Останов или новый запрос во время загрузки — штатная ситуация: запрос отменяется, запуска нет. Сама загрузка не прерывается: клип догружается и остаётся в буфере кэша ассетов, удержание отменённого запроса кэш снимает сам. Сбой отменённой загрузки пишется в лог, но играющий трек не трогает. Конец прежнего трека, пока грузится запрошенный, запрос не отменяет и не подменяет.

Отпущенный клип не выгружается сразу: он остаётся в буфере кэша ассетов и выгружается по его правилам (см. AssetCacheSystem). Повторный запрос такого клипа — мгновенный.

Конец трека

Время трека хэндлер сам не считает. Конец сообщает аудиосистема событиями хэндла управления (AudioSampleWrapper), пауза в них уже учтена:

Событие Когда приходит Что делает хэндлер
OnLoopRestart зацикленный клип доиграл и пошёл на новый круг Index, Random — запрашивает следующий трек; OneShot — останавливает звук
OnFinished незацикленный клип доиграл либо звук сняли снаружи останавливает звук и отпускает клип
  • Зацикливание. В Index и Random клип запускается зацикленным, в OneShot — нет. Музыка в слоте зациклена всегда, поэтому в OneShot она останавливается по рестарту.
  • Следующим выпал тот же трек (в списке один клип) — хэндлер ничего не делает: клип уже сам пошёл на новый круг.
  • Пока грузится запрошенный клип, оба события запрос не трогают.
  • Рестарт приходит после перехода, с опозданием до ~0,1 с (см. AudioSystem). К этому моменту клип уже начал новый круг.

Пауза

Пауз две, они независимы:

  • пауза игры — состояние GameStates.Paused;
  • ручная — Pause() / Unpause().

Звук играет, только когда нет ни одной. Unpause() при паузе игры звук не возобновит.

Ручная пауза живёт, пока объект включён: при включении объекта она сбрасывается, а Pause() у выключенного хэндлера не действует. Исключения из правила «на паузе звука нет» у музыки — в «Ограничениях».

Особенности музыки

  • Слот cover-музыки. Основная тема на время приглушается и возвращается после останова. Громкость — по общим настройкам музыки.
  • Трек в слоте зациклен всегда. Конец трека приходит только рестартом, уже после перехода. Смена трека и останов в OneShot идут с затуханием, поэтому на нём успевает прозвучать начало прежнего трека.
  • Прежний трек сменяет сам слот, с затуханием: отдельной команды останова перед запуском нового хэндлер не даёт.
  • Клип отпускается в момент команды. Хвост затухания доигрывает из буфера кэша ассетов.
  • Вытеснение. Если слот заняла другая музыка, хэндлер замолкает и отпускает клип.

Особенности звука

  • Играет как обычный звук аудиосистемы; громкость — по каналу из поля channel.
  • Прежний трек останавливается в момент запуска нового, без затухания.
  • В Index и Random клип зациклен: между рестартом и запуском следующего трека (опоздание события и загрузка клипа) звучит начало прежнего.
  • В OneShot клип не зациклен и завершается сам, без повторного начала.
  • Останов звука со стороны аудиосистемы (например, общая очистка звуков) останавливает хэндлер в любом режиме — следующий трек не запускается.

Контракт

Гарантии

  • Хэндлер удерживает клип играющего трека; на время смены трека — ещё и клип следующего. Когда отпущенный клип выгрузится, решает кэш ассетов.
  • На OnDisable звук остановлен, клип отпущен. Запрос, который в этот момент грузился, отменяется.
  • Запрос трека во время загрузки — того же или другого — даёт один запуск: последнего запрошенного трека.
  • Повторный запуск того же трека не грузит клип заново, если он ещё не отпущен.

Ограничения

  • Слот cover-музыки один на приложение. Два музыкальных хэндлера, либо хэндлер и другая система, перебивают друг друга.
  • Зацикленность музыки задаёт источник слота, а не хэндлер: сыграть музыкальный трек без зацикливания нельзя.
  • Смена трека не бесшовная. Следующий трек запрашивается после рестарта прежнего, поэтому начало прежнего трека успевает прозвучать: у звука — на время опоздания события и загрузки клипа, у музыки — ещё и на время затухания.
  • Короткие клипы. На клипах короче ~0,5 с аудиосистема может пропускать рестарты — переход к следующему треку задержится на круг.
  • Пауза мимо хэндла (AudioListener.pause, свёрнутое окно) сбивает один отсчёт рестарта: следующий трек может запуститься не вовремя.
  • Хвост затухания музыки держится на буфере кэша ассетов. При ёмкости группы кэша 0 отпущенный клип выгружается сразу, и затухание обрывается. Клипам музыки нужна группа с ненулевой ёмкостью.
  • Останов музыки до её фактического старта. Аудиосистема запускает cover-музыку с задержкой, пока гасит основную тему. Останов в это окно снимает запуск, но основная тема может остаться приглушённой до следующей смены музыки. Если в этом окне затухал прежний трек, его затухание обрывается сразу.
  • Останов музыки на паузе слышен. Аудиосистема останавливает только играющую музыку, поэтому трек снимается с паузы и гаснет с обычным затуханием.
  • Пауза в окне смены музыкального трека. Хвост прежнего трека доигрывает затухание; новый трек встаёт на паузу в момент старта.

Граничные случаи

Ситуация Поведение
Пустой список клипов Debug.LogError при запуске, звука нет
Play(n) с номером вне списка Debug.LogError, состояние не меняется
Play / PlayNext у выключенного хэндлера Debug.LogError, запрос пропущен. В состоянии свитчера вызов должен стоять после включения объекта
Элемент списка не задан Debug.LogError, прежний трек останавливается
Сбой загрузки клипа, пустой клип ошибка в лог, прежний трек останавливается
Сбой загрузки, отменённой новым запросом ошибка в лог, играющий трек не затрагивается
Запрошен клип, который уже грузится прежний запрос отменяется, новый присоединяется к той же загрузке; трек запускается один раз
Запуск не состоялся (аудиосистема не вернула управление треком) новый трек не звучит, его клип отпущен, хэндлер остановлен; в лог хэндлер ничего не пишет. Прежний музыкальный трек при этом остаётся в слоте без управления
Прежний трек доиграл, пока грузится запрошенный запрос остаётся в силе; в Index и Random очередной трек его не подменяет
Звук сняли снаружи (вытеснение из слота музыки, очистка звуков) хэндлер останавливается и отпускает клип; если в этот момент грузится запрошенный трек — он запустится
Запрошен тот же трек, что играет клип заново не грузится; трек запускается сначала
Объект выключен во время загрузки запрос отменяется, запуска нет; клип догружается и остаётся в буфере кэша
Объект выключили и включили во время загрузки трек запускается один раз
Pause() у выключенного хэндлера не действует, в лог ничего не пишется
Запуск во время паузы трек встаёт на паузу сразу, заиграет после её снятия
Один клип в списке, режим Index или Random клип играет по кругу без перезапуска
Stop без играющего трека звук не меняется; запрос, который ещё грузится, отменяется

Публичный API

namespace Vortex.Sdk.AudioAdvancedControl.Handlers
{
    public abstract class AdvancedAudioHandler : MonoBehaviour
    {
        public void Play(int number);
        public void PlayNext();
        public void Stop();
        public void Pause();
        public void Unpause();
    }

    public class AdvancedMusicHandler : AdvancedAudioHandler { }
    public class AdvancedSoundHandler : AdvancedAudioHandler { }
}

namespace Vortex.Sdk.AudioAdvancedControl.Model
{
    public enum AdvancedPlaybackMode { Index, Random, OneShot }
}