AudioDevice
Generated from engine/audio/audio_device.h at aceb130. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.
Audience: game code.
#include "engine/audio/audio_device.h" · namespace labrador
enum class SoundState
Section titled “enum class SoundState”{ stopped, playing, paused};What a voice is doing, in this engine's words rather than a library's.
It is three values because that is what the thing has: a voice is stopped, playing, or paused, and every audio API this engine is likely to sit on spells those three. It is the engine's own enum rather than an audio library's so that a game asking what its music is doing does not have to name a platform to ask.
class AudioDevice
Section titled “class AudioDevice”The audio backend seam.
A concrete class with one implementation chosen at build time, for the reasons engine/render/SEAM.md#2 gives for the renderer and gamepad_reader.h repeats in two sentences: asking for a backend that was not built is a missing symbol rather than a run-time answer (T5), a vtable is a tax nothing has asked to pay (T8), and promoting a concrete class to an interface later is mechanical and changes no call site. The XAudio2/DirectXTK implementation is engine/audio/xaudio2/, the browser's Web Audio one is engine/audio/webaudio/, the headless one is engine/audio/null/, and nothing outside those folders names an audio API.
IT IS WHAT MAKES THE MODULE TABLE TRUE. ARCHITECTURE has audio depending on core and math, with XAudio2 inside xaudio2/ only, so the engine's own vocabulary is spelt in its own types - a bank is a WaveBankHandle, a persistent voice a VoiceHandle, and what a voice is doing the SoundState above - and no header outside a backend folder includes an audio library to say any of it.
IT SHIPS WITH A HEADLESS IMPLEMENTATION, because PHILOSOPHY (Tests and toolchain) requires that "a seam ships with its headless implementation, or it has not shipped", since "a seam with only the platform's own implementation behind it still requires the platform in order to construct anything". SoundBank::silent() does not satisfy that rule and must not be mistaken for something that does: it is a bank with no content, which is a question about content and not about the platform. engine/audio/null/ is the headless implementation, and engine/audio/null/recording.h says what it makes assertable.
WHERE THE CUT IS, AND WHAT IS DELIBERATELY ABOVE IT. Everything this engine decides is above: which name means which wave, which handles are valid, and the clamp that folds a volume into [0,1] and a pitch and a pan into [-1,1] and refuses a NaN. Levels arrive here already clamped, never NaN, and handles arrive here already checked. Below is what an audio API actually does - open a container, find a name in it, build a voice, and start, stop, adjust or report one - and nothing else.
THE FILE ROUTE DELEGATES ITS CONTAINER TO THE BACKEND. open_wave_bank takes a directory and a bank name, never a file name: the extension, the reader and the bytes are the backend's business, exactly as a swapchain is render/'s. What crosses instead is the list of wave NAMES the definition beside the container says it holds, because that list is content this engine parses out of its own JSON. A backend with no container answers from that list; a backend with one checks the list against it and throws naming the wave that is missing. The format itself is written down once, in engine/audio/xwb_file.h, for a backend whose audio API has no reader of its own. A backend whose API has one may keep it, and that is why that cut sits above the format rather than at it. open_memory_bank instead takes already decoded, owned PCM data, for WAV assets and generated sounds. Each backend supplies its own playback storage while preserving the shared samples and frame-based loop region.
WaveBankHandle
Section titled “WaveBankHandle”VoiceHandle
Section titled “VoiceHandle”AudioDevice · ~AudioDevice
Section titled “AudioDevice · ~AudioDevice”AudioDevice();~AudioDevice();AudioDevice · operator=
Section titled “AudioDevice · operator=”AudioDevice& operator=(AudioDevice&&) noexcept;open_wave_bank
Section titled “open_wave_bank”WaveBankHandle open_wave_bank(const std::string& directory, const std::string& name, const std::vector<std::string>& wave_names);Load-time. Opens the wave bank named name under directory, and takes wave_names as what the definition beside it says is in there.
Throws std::runtime_error naming the file it looked for if the container is not there or cannot be read - which is the throw a caller catches to substitute SoundBank::silent() for an optional bank, and the reason it is a runtime_error and not a logic_error. A container this backend can read and not play is the same throw, naming the wave: an encoding the backend's reader refuses, or, in a browser, a sample rate that browser's Web Audio will not hold - the standard promises only 8000 to 96000 Hz, and each browser takes its own wider range. Under XAudio2 a streaming bank is the same throw again, naming the file, because DirectXTK plays only an in-memory one. Running out of memory is not a missing container and propagates as std::bad_alloc.
Throws std::out_of_range naming the wave if the container is there and does not hold a name wave_names lists. That is a content bug rather than a missing file, it is not the same failure, and the two are told apart by their type rather than by a flag.
open_memory_bank
Section titled “open_memory_bank”Load-time owned PCM input, checked before publication. A malformed bank throws std::invalid_argument naming the bank/wave; backend refusal throws a named std::runtime_error. C++ allocation failure propagates as std::bad_alloc. A browser's AudioBuffer refusal retains its original reason in runtime_error. Banks and wave names are nonempty/NUL-free; waves have unique names, nonempty whole mono/stereo frames at 8000..96000 Hz, frame counts fitting int, at most 2 GiB of decoded PCM per wave and any nonempty loop wholly in its wave.
Passing an lvalue copies its data; std::move transfers it. After this call returns, caller containers may be destroyed or reused: playback borrows none of their storage. Banks and voices belong to the device implementation; destroying or replacing it invalidates their handles. Moving transfers that implementation, but does not redirect a SoundBank's borrowed pointer to its original AudioDevice object.
Final sample payload is 2 bytes per sample on null/XAudio2 and 4 on Web Audio, plus backend overhead. XAudio2/Web Audio conversion also holds the input's 2-byte samples temporarily; an lvalue retains its additional caller copy. Null also retains unused vector capacity. No streaming or compressed input is implied.
Loop fields are frames. Non-looping voices play the complete wave; looping voices play from the start, then repeat the stored region. Zero loop length means the whole wave, ignoring loop_start.
wave_index
Section titled “wave_index”int wave_index(WaveBankHandle bank, const std::string& wave_name) const;The index of wave_name within bank, or -1 if the bank has no such wave. The index is the backend's own and means nothing to any other bank, which is why SoundBank hands it back inside a WaveHandle.
create_voice
Section titled “create_voice”VoiceHandle create_voice(WaveBankHandle bank, int wave_index);Load-time. A voice that plays wave wave_index from bank, for a caller that wants to stop, loop or adjust it later.
play_wave
Section titled “play_wave”void play_wave(WaveBankHandle bank, int wave_index, float volume, float pitch, float pan) const;Fire-and-forget: a new voice each time, with nothing to hold afterwards. Levels arrive clamped. Throws std::out_of_range if wave_index is not a wave of bank, on every backend. Between suspend() and resume() the one-shot is dropped and never replayed.
play_voice · stop_voice · pause_voice · resume_voice · set_voice_volume · set_voice_pitch · set_voice_pan · voice_state · is_voice_looping
Section titled “play_voice · stop_voice · pause_voice · resume_voice · set_voice_volume · set_voice_pitch · set_voice_pan · voice_state · is_voice_looping”void play_voice(VoiceHandle voice, bool loop, float volume, float pitch, float pan) const;void stop_voice(VoiceHandle voice, bool immediate) const;void pause_voice(VoiceHandle voice) const;void resume_voice(VoiceHandle voice) const;void set_voice_volume(VoiceHandle voice, float volume) const;void set_voice_pitch(VoiceHandle voice, float pitch) const;void set_voice_pan(VoiceHandle voice, float pan) const;bool is_voice_looping(VoiceHandle voice) const;The persistent voice's verbs, one apiece. Levels arrive clamped and handles arrive checked, so a backend implements each of these as the single call its API spells it with and nothing else.
update
Section titled “update”void update();The shell's three, and the whole of what app/ knows about audio.
update() processes audio once a frame, after the states have updated. XAudio2 retries an unavailable default output once a second while active, with an immediate attempt on the next update after resume(). Recovery drops one-shots and stops persistent voices; their handles remain valid, and the game may play them again. Other reset failures propagate as exceptions. No output is recreated while suspended.
suspend · resume
Section titled “suspend · resume”void suspend();void resume();The window was minimised, the system power-suspended or the page hidden, and then came back. Losing the foreground alone suspends nothing: a game behind another window keeps its sound. What suspension costs the platform is the platform's affair.
A one-shot asked for while suspended is dropped on every backend, for the reason the gesture paragraph below gives: a sound effect that plays late plays wrong, and the game's updates go on while it is minimised. Persistent voices keep their states and calls; what is playing is heard again after resume(), from where it stopped.
SOME PLATFORMS WITHHOLD SOUND UNTIL THE PLAYER HAS DONE SOMETHING. A browser lets a page play nothing before its first key press, click or touch, and the Web Audio backend waits for that event itself, so nothing is asked of a caller. What a caller sees before then: a one-shot from play_wave is dropped, because a sound effect that plays late plays wrong; a voice asked to play answers playing and starts from where it was when sound is allowed, which is what music started at boot wants. Every other call behaves as it always does. A platform with no audio output at all answers the same way for ever.
A GAMEPAD BUTTON IS NOT THAT EVENT. The backend hears keys, mouse buttons, pointers and touches. A pad is polled, and a browser has no event for its buttons, so nothing tells the backend one was pressed. Expect a player who uses only a pad to hear nothing until the page has had one key press, click or touch; a game meant to be played that way asks for one on its page before it starts. A browser that counts a pad press as activity on the page changes this only for a bank opened after the press, which is not something to rely on. This device does not read pads to find out: input is not audio's to depend on.
Impl* impl() const;Related types
Section titled “Related types”Named in the public declarations above: Handle, WaveBankData.
In the samples and tests
Section titled “In the samples and tests”The files that include this header directly. A file can also reach it through another header.
samples/audio/smoke_test.cpptests/assets/resource_loader_tests.cpp,wave_asset_tests.cpptests/audio/audio_resources_failure_tests.cpp,sound_bank_tests.cpp,wave_tables_tests.cpptests/audio/null/memory_bank_tests.cpp,null_tests.cpptests/audio/webaudio/webaudio_tests.cpp
Explained in
Section titled “Explained in”Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.