Documentation
Docs/en/reference/audio/decoding.md
Audio Decoding 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.decoding.wav-chunk-order |
WAV chunk order | Provide RIFF/WAVE with one usable fmt chunk and a non-empty data chunk; AudioBaker walks chunks in any order, skips unknown chunks, and respects odd-byte padding. | Real exports commonly insert metadata chunks or reorder fmt and data, so the baker validates chunk bounds instead of prescribing a narrow sequence. | Source/Tools/AudioBaker.cpp |
audio.decoding.wav-pcm-width |
WAV PCM widths | Author WAV as PCM at 8, 16, 24, or 32 bits or IEEE float at 32 bits; channel count and sample rate must be positive and block alignment must match the declared frame shape. | AudioBaker converts each supported sample to signed 16-bit before Vorbis encoding and rejects truncated frames or inconsistent format metadata. | Source/Tools/AudioBaker.cpp |
audio.decoding.acm-shape |
Baked payload verification | Reject a generated or passthrough payload unless libvorbisfile opens it as a valid Vorbis stream. | The bake boundary catches malformed native input and encoder output before the client attempts playback; runtime then reads channel and sample-rate metadata from the verified stream. | Source/Tools/AudioBaker.cpp |
audio.decoding.ogg-streaming |
Ogg streaming | Expect Ogg Vorbis to decode in 64 KiB native chunks and 128 KiB Web chunks; short files are retained fully and release the stream after the initial decode. | AudioManager uses a platform-sized streaming portion and clears OggStream when the first read reaches EOF. | Source/Client/AudioManager.cpp |
audio.decoding.device-conversion |
Device conversion | Let AppAudio convert decoded sample format, channel count, and rate to the active SDL output-device format before playback. | AudioManager does not require authored assets to match one fixed hardware format. | Source/Client/AudioManager.cpp, Source/Frontend/Application.cpp |
audio.decoding.callback-mixing |
Audio callback mixing | Treat playback as client audio-callback work; mutations of the active sound list must hold the audio-device lock. | The SDL stream callback asks AudioManager to fill output while game-thread play/stop/update operations can add, mutate, or erase sounds. | Source/Client/AudioManager.cpp, Source/Frontend/Application.cpp |
audio.decoding.unsupported-extension |
Single runtime decoder | Route authored audio through AudioBaker and let AudioManager decode every resulting resource as Ogg Vorbis regardless of its preserved source suffix. | Unsupported source extensions never enter the Audio baker, and runtime has no suffix dispatch that could silently accept an empty or differently encoded payload. | Source/Client/AudioManager.cpp |