Документация
Docs/ru/reference/audio/playback.md
Контракт воспроизведения аудио
Сгенерированный справочник. Не редактируйте его источник напрямую. Обновите
BuildTools/AudioInterface.json, затем выполнитеpython BuildTools/docs_audio.py --write.
| Индекс | Форматы | Доставка | Декодирование | Воспроизведение | Проверка | Канонический JSON | Руководство |
| Стабильный ID | Правило | Требование | Причина | Источник |
|---|---|---|---|---|
audio.playback.effect-api |
Game.PlaySound | Используйте Game.PlaySound на клиенте для воспроизведения не-музыки и сохраняйте его uint32 handle, если звук потребуется позиционировать повторно; ноль означает, что живой звук не запущен. | Script method передаёт точный путь ресурса в AudioManager и раскрывает непереиспользуемый handle времени жизни, возвращаемый при добавлении звука в список mixer. | Source/Scripting/ClientGlobalScriptMethods.cpp |
audio.playback.effect-base-first |
Точный путь эффекта | Разрешайте проектные понятия и нумерованные варианты до Game.PlaySound, затем передавайте точный путь выбранного ресурса вместе с авторским суффиксом. | Политика вариантов принадлежит встраиваемому проекту: AudioManager не нормализует основы, не подставляет суффиксы и не навязывает соглашение каталога. | Source/Client/AudioManager.cpp |
audio.playback.effect-contiguous-variants |
Запуск позиционированного звука | Используйте overload Game.PlaySound с attenuation и pan для запуска позиционированного звука; attenuation не больше нуля возвращает нулевой handle до файлового ввода-вывода. | Позиционирование — проекция, принадлежащая вызывающему коду, в attenuation и стереобаланс mixer; кривые расстояния и выбор listener остаются политикой проекта. | Source/Scripting/ClientGlobalScriptMethods.cpp, Source/Client/AudioManager.cpp |
audio.playback.global-mix |
Обновление позиционированного звука | Вызывайте Game.UpdateSound с живым handle, чтобы заменить attenuation и pan при движении источника или listener; false означает нулевой handle, неактивное аудио или уже завершившееся воспроизведение. | Обновление выполняется под lock аудиоустройства, поэтому mixer наблюдает одну согласованную пару позиционирования, а завершённый звук нельзя оживить устаревшим handle. | Source/Client/AudioManager.cpp |
audio.playback.music-api |
Game.PlayMusic | Используйте Game.PlayMusic с точным путём ресурса и интервалом повтора; пустой путь останавливает текущую музыку и сообщает об успехе. | Script entry point применяет соглашение об остановке по пустому имени до делегирования AudioManager. | Source/Scripting/ClientGlobalScriptMethods.cpp |
audio.playback.single-music |
Один музыкальный поток | Ожидайте, что новый запрос музыки остановит каждый существующий музыкальный экземпляр до загрузки замены. | AudioManager.PlayMusic вызывает StopMusic до Load, поэтому неудачная замена не восстанавливает предыдущую композицию. | Source/Client/AudioManager.cpp |
audio.playback.repeat |
Интервал повтора | Передайте ненулевой repeatTime для повтора после завершения; значения не больше одной миллисекунды повторяют немедленно, большие вставляют заданную задержку. | ProcessSound планирует NextPlayTime с порогом в одну миллисекунду и перематывает сохранённые Ogg streams перед повтором. | Source/Client/AudioManager.cpp |
audio.playback.separate-volumes |
Громкость звуков и музыки | Используйте Audio.SoundVolume и Audio.MusicVolume как начальные значения, затем Game.SetSoundVolume и Game.SetMusicVolume для изменений в runtime; frontend ограничивает каждую операцию микширования диапазоном от 0 до 100. | AudioManager владеет текущей громкостью, поскольку настройки Engine неизменяемы, выбирает её по IsMusic, а AppAudio нормализует ограниченный процент перед SDL-микшированием. | Source/Client/AudioManager.cpp, Source/Frontend/Application.cpp |
audio.playback.disabled-success |
Соглашение о результате отключённого аудио | Не используйте true от PlayMusic или handle от PlaySound как доказательство существования ресурса при отключённом или недоступном аудио: PlayMusic остаётся успешной no-op операцией, а PlaySound возвращает нулевой handle. | Отключённое устройство — нормальное состояние игрока, поэтому музыка не сообщает отказ, а эффекты лишь показывают отсутствие живого звука; корректность ресурса принадлежит проверке baker. | Source/Client/AudioManager.cpp |
audio.playback.default-acm |
Закон стереопанорамирования | Передавайте pan в диапазоне от -1 до 1 для штатного закона баланса: отрицательное значение ослабляет правый канал, положительное — левый, а ближний канал остаётся с единичным усилением. | AudioManager применяет pan к буферу каждого callback, а не к декодированному хранилищу, поэтому последующие обновления позиции не накапливают предыдущее панорамирование, а громкие samples не усиливаются до clipping. | Source/Client/AudioManager.cpp |