Documentation
Docs/en/reference/audio/playback.md
Audio Playback Contract
Generated reference. Do not edit directly. Update
BuildTools/AudioInterface.json, then runpython BuildTools/docs_audio.py --write.
| Index | Formats | Delivery | Decoding | Playback | Validation | Canonical JSON | Guide |
| Stable ID | Rule | Requirement | Why | Source |
|---|---|---|---|---|
audio.playback.effect-api |
Game.PlaySound | Use Game.PlaySound on the client for non-music playback and retain its uint32 handle when the sound must be placed again; zero means no live sound was started. | The script method delegates the exact resource path to AudioManager and exposes the non-reused lifetime handle returned when the sound enters the mixer list. | Source/Scripting/ClientGlobalScriptMethods.cpp |
audio.playback.effect-base-first |
Exact effect path | Resolve project concepts and numbered variants before Game.PlaySound, then pass the exact selected resource path including its authored suffix. | Variant policy belongs to the embedding project; AudioManager performs no stem normalization, suffix fallback, or catalog convention. | Source/Client/AudioManager.cpp |
audio.playback.effect-contiguous-variants |
Placed sound start | Use the Game.PlaySound overload with attenuation and pan to start a placed sound; attenuation at or below zero returns handle zero before file I/O. | Placement is a caller-owned projection onto mixer attenuation and stereo balance, while distance curves and listener selection remain project policy. | Source/Scripting/ClientGlobalScriptMethods.cpp, Source/Client/AudioManager.cpp |
audio.playback.global-mix |
Placed sound update | Call Game.UpdateSound with a live handle to replace attenuation and pan as the source or listener moves; false means the handle is zero, audio is inactive, or playback already finished. | The update runs under the audio-device lock, so the mixer observes one placement pair and a completed sound cannot be revived through a stale handle. | Source/Client/AudioManager.cpp |
audio.playback.music-api |
Game.PlayMusic | Use Game.PlayMusic with an exact resource path and repeat interval; an empty path stops current music and succeeds. | The script entry point owns the empty-name stop convention before delegating to AudioManager. | Source/Scripting/ClientGlobalScriptMethods.cpp |
audio.playback.single-music |
Single music stream | Expect a new music request to stop every existing music instance before attempting to load the replacement. | AudioManager.PlayMusic calls StopMusic before Load, so a failed replacement does not restore the previous track. | Source/Client/AudioManager.cpp |
audio.playback.repeat |
Repeat interval | Pass a nonzero repeatTime to replay after completion; values at or below one millisecond repeat immediately, and larger values insert that delay. | ProcessSound schedules NextPlayTime using a one-millisecond threshold and rewinds retained Ogg streams before replay. | Source/Client/AudioManager.cpp |
audio.playback.separate-volumes |
Sound and music volumes | Use Audio.SoundVolume and Audio.MusicVolume as startup defaults, then Game.SetSoundVolume and Game.SetMusicVolume for live changes; the frontend clamps each mix operation to 0 through 100. | AudioManager owns live volume state because Engine settings are immutable, selects it by IsMusic, and AppAudio normalizes the clamped percentage before SDL mixing. | Source/Client/AudioManager.cpp, Source/Frontend/Application.cpp |
audio.playback.disabled-success |
Disabled audio return convention | Do not use PlayMusic true or a PlaySound handle as resource-existence proof when audio is disabled or unavailable; PlayMusic remains a successful no-op while PlaySound returns handle zero. | A disabled device is a normal player state, so music reports no refusal and effects report only that no live sound exists; baker validation owns resource correctness. | Source/Client/AudioManager.cpp |
audio.playback.default-acm |
Stereo pan law | Pass pan in the range -1 through 1 for the stock balance law: negative attenuates the right channel, positive attenuates the left, and the near channel stays at unity. | AudioManager applies pan to the per-callback mix buffer rather than decoded storage, so later placement updates do not compound an earlier pan and loud samples are not boosted into clipping. | Source/Client/AudioManager.cpp |