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
Порядок запуска один для музыки и звука:
- Запрос трека. Принимается только у включённого хэндлера. Клип асинхронно запрашивается у хэндла ассета. У каждого запроса свой токен отмены: новый запрос отменяет прежний, ещё не исполненный, и тот до запуска не доходит. Повторный запрос того же клипа, пока он грузится, присоединяется к идущей загрузке — трек запустится один раз.
- Загрузка клипа. Пока она идёт, прежний трек играет. Загрузка сорвалась — ошибка в лог и останов прежнего трека.
- Останов прежнего трека, если он был. Его клип отпускается, кроме случая, когда новый трек играет тот же клип.
- Воспроизведение.
Останов или новый запрос во время загрузки — штатная ситуация: запрос отменяется, запуска нет. Сама загрузка не прерывается: клип догружается и остаётся в буфере кэша ассетов, удержание отменённого запроса кэш снимает сам. Сбой отменённой загрузки пишется в лог, но играющий трек не трогает. Конец прежнего трека, пока грузится запрошенный, запрос не отменяет и не подменяет.
Отпущенный клип не выгружается сразу: он остаётся в буфере кэша ассетов и выгружается по его правилам (см. 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 }
}