Audio
The audio sample is a playable sound board:
two short tones and a looping drone, with volume, pitch and stereo pan controls.
Its original PCM sounds and the built wave bank are in the repository. The sample is in the
engine’s folder, not in your game, and your game’s build does not make it. In the
x64 Native Tools Command Prompt, these commands go to the
engine’s folder in a starter project, configure and build there,
and start the sample. From a clone, the first line is cd /d C:\dev\Labrador instead.
Run the samples says how long each step takes, what it prints, and what
each failure means.
cd /d C:\dev\mygame\external\labradorcmake --preset x64-debugcmake --build --preset x64-debug --target AudioSampleout\build\x64-debug\samples\audio\AudioSample.exePress 1 for a ping, 2 for an ascending chime and 3 to start the drone.
Space pauses or resumes the drone; S stops it. Hold Up/Down for volume,
Left/Right for stereo pan and Q/E for pitch. Escape quits. The screen
shows the current values and loop state. An active Windows audio output is
required to hear the normal XAudio2 build; -null presets record calls without
sound and label that mode on screen.
Browser audio and the first gesture
Section titled “Browser audio and the first gesture”The same sample builds for a browser with the wasm-debug and wasm-release
presets, as AudioSample.html, and plays through Web Audio. A browser plays
nothing until the page receives a key press, click or touch that grants user
activation. Escape does not count. The backend waits for that gesture
itself, and the key that allows sound is still read by the sample: a first
press of 1 plays the ping. The
sample’s README has the
commands to build and serve it.
This also applies to your game’s own sounds. A one-shot requested through
SoundBank::play_wave before that gesture is dropped and will never play
later. An effect instance requested through play_effect, including a looping
effect, reports playing but waits to start until audio is allowed. Pausing it
or calling stop_effect(effect, true) cancels its pending start. If a
title-screen jingle must be heard, play it after the player starts the game, or use a persistent
effect instance that can wait for the gesture.
Play a sound in your game puts these sounds into a starter project step by step, with no tools, then a WAV of your own: the files, the manifest, the build file’s lines and the code, with what each failure means. The sections below show the sample’s code for using a bank. If a build fails after you put some of it into your own game, Read a build error shows how to read the error.
Declare a required bank
Section titled “Declare a required bank”A bank has two files: a JSON definition and the XAudio2 backend’s .xwb wave
container. The manifest names their shared stem, without either extension:
{ "assets": [ { "kind": "font", "directory": "./fonts/", "names": ["jetbrains_mono_bold_16"] }, { "kind": "sound_bank", "directory": "./sounds/", "names": ["tones"], "optional": false } ]}samples/audio/content/manifest.json at 0f4f503
This bank is required. A missing or unreadable container stops loading with its
path in the error. optional: true is only for content a game can run without:
it substitutes a silent bank and cannot demonstrate playback. A required bank
with a misspelt wave also fails during loading.
The definition lists waves and persistent effect instances:
{ "waves": ["ping", "chime", "drone"], "create_effect_instance_for_each_wave": false, "sound_effect_instances": [ {"name": "drone_loop", "wave": "drone"} ]}samples/audio/content/sounds/tones.json at 0f4f503
ping and chime need only waves. The named drone_loop instance retains a
voice so it can loop, pause and change levels. Several named instances may use
the same wave when a game needs separately controlled voices. Setting
create_effect_instance_for_each_wave to true instead creates an instance with
each wave’s own name.
The sample’s content target
copies the bank beside the executable on every build, including asset-only
edits; a browser build embeds the same files in the module at the same paths. Application::load_manifest("./manifest.json") resolves the manifest
relative to the executable, and its directories relative to that manifest.
Resolve names once
Section titled “Resolve names once”After loading the manifest, the state borrows the bank from AudioResources:
this->board_ = std::make_unique<SoundBoard>(bank);samples/audio/audio_state.cpp, lines 20–21 at 0f4f503
The sound board resolves its wave and effect names in its constructor:
{ if (this->bank_ == nullptr || !this->bank_->audible()) { throw std::runtime_error("AudioSample requires the tones wave bank."); } this->ping_ = this->bank_->resolve_wave("ping"); this->chime_ = this->bank_->resolve_wave("chime"); this->drone_ = this->bank_->resolve_effect("drone_loop");}samples/audio/sound_board.cpp, lines 9–18 at 0f4f503
Keep the handles, and play through them during update(). Wave and effect
handles are different types: a one-shot wave is not a persistent voice. The
borrowed bank must outlive the board; Application keeps audio resources alive
until its states are destroyed.
audible() distinguishes a loaded bank from the missing-content substitute.
It is also true on the null backend and says nothing about speakers, mute
settings or whether the machine has an active audio output.
One-shots and a looping instance
Section titled “One-shots and a looping instance”play_wave starts a separate voice each time, useful for hits, jumps and menu
clicks. There is no handle for stopping or adjusting that individual playback:
void SoundBoard::play_ping() const{ this->bank_->play_wave(this->ping_, this->volume_, this->pitch_, this->pan_);}samples/audio/sound_board.cpp, lines 25–28 at 0f4f503
Use an effect instance when the voice must persist. The loop flag belongs to the play call, not the bank definition:
void SoundBoard::start_loop() const{ this->bank_->play_effect(this->drone_, true, this->volume_, this->pitch_, this->pan_);}samples/audio/sound_board.cpp, lines 35–39 at 0f4f503
The same instance can be paused and resumed without starting a second voice:
void SoundBoard::toggle_pause() const{ { this->bank_->pause_effect(this->drone_); } else if (this->loop_state() == labrador::SoundState::paused) { this->bank_->resume_effect(this->drone_); }}samples/audio/sound_board.cpp, lines 41–51 at 0f4f503
stop_effect(effect, true) stops immediately. With the default false, a
loop exits its loop and the platform can finish its tails; the observed state
can remain playing briefly. The sample uses immediate stop and also stops the drone on
state destruction.
Levels and lifecycle
Section titled “Levels and lifecycle”Volume is in [0, 1], pitch in [-1, 1] (one octave down to one octave up),
and pan in [-1, 1] (left to right). SoundBank clamps values at the engine
boundary. The sample also clamps its own displayed settings:
void SoundBoard::set_volume(float volume){ this->bank_->set_effect_volume(this->drone_, this->volume_);}samples/audio/sound_board.cpp, lines 58–62 at 0f4f503
Changing a retained voice takes effect while it plays. One-shots take their levels when launched, so new settings affect the next one-shot. The sample pauses a playing loop on deactivation and resumes only that loop when focus returns; a loop paused by the player stays paused.
A settings screen’s music and effects sliders are sound groups.
AudioResources::add_sound_group("music") makes one at load, and
set_wave_group and set_effect_group on a bank put a wave or an effect in
it. From then on the bank sends every level for that sound multiplied by the
group’s volume, so the level each call asks for stays the authored one and the
player’s setting is one set_group_volume(music, 0.5f). The same rule holds
for a group as for a level: a one-shot already playing keeps the level it was
launched with, and the next one takes the new volume, while a playing or paused
effect in the group takes it at once. A sound in no group is at full group
volume. Which sounds are music, fades and ducking stay the game’s; a fade or a
duck is the game’s own factor multiplied into set_effect_volume, which
combines with the group’s. The
Settings and saves guide
shows the bank assignments and a copied slider’s 0-to-100 callback scaled into
set_group_volume.
Application updates the audio device every tick and owns its lifetime. A
client that uses AudioDevice directly must update it and keep it alive longer
than all the banks that borrow it; the sample’s
finite audio check shows
that order without creating a graphics device.
Make sound content and verify it
Section titled “Make sound content and verify it”The three checked-in WAV files were synthesized by a Python standard-library script; they use no third-party audio and carry the repository’s MIT licence. The sample README records the exact tool version, provenance, regeneration commands and content verifier. Neither Python nor an authoring tool is needed to run the existing example.
For your own bank, Microsoft’s
XWBTool combines WAV files.
Install the content tools downloads it to
C:\dev\tools\xwbtool.exe; the command below assumes it can be found by its short name, as
that page’s Typing the programs’ names
sets up:
xwbtool -f -nc -y -o tones.xwb ping.wav chime.wav drone.wavIt prints a reading line for each WAV, with its format, and then
writing in-memory wavebank tones.xwb w/ 3 entries. -y replaces an existing
tones.xwb; without it xwbtool stops with ERROR: Output file tones.xwb already exists, use -y to overwrite! and writes nothing. Write the bank into the folder the manifest’s group names,
beside a .json definition of the same name whose waves are the WAV files’ names without
.wav.
The -f is required: it retains each file’s stem as a friendly name in the
bank, which is how Labrador checks and resolves waves. So is -nc: without
it XWBTool writes compact entries whenever the waves fit them. Windows plays a
compact bank, but the browser build reads banks with the engine’s own reader,
which refuses one by name (uses compact entries, which this engine does not read). Use an in-memory bank for this API; streaming banks are
outside this example. The command was checked with XWBTool from the may2026
DirectX Tool Kit release, packing the sample’s three WAVs into a bank the
engine’s reader loads.
AudioSample.exe --smoke-test loads the packaged required bank, plays both
one-shots, and verifies loop play, pause, resume and immediate stop before
exiting. Run the normal x64-debug or x64-release executable for actual
XAudio2 coverage. A missing bank or unavailable output fails that check.
Under a null preset the same check records the calls and reports no playback;
it cannot validate the container or sound quality. AudioSampleTests also
checks the real definition, and under null audio asserts exactly which waves
the sound board requests and the levels it sends.
Exporting sounds both platforms play
Section titled “Exporting sounds both platforms play”A wave bank holds WAVs as they were exported. Windows plays it through XAudio2, and a browser build reads it with the engine’s reader, so a sound has to suit both:
- Accepted: PCM at 8 or 16 bits, and MS-ADPCM.
- Refused by the engine’s reader, each by name at load, so they fail in the
browser build: xWMA, XMA, and compact entries (
-ncabove). - Channels: mono or stereo. The reader refuses MS-ADPCM with more than two channels, and pan is a stereo control.
- Sample rate: one a browser’s
AudioBufferaccepts. The Web Audio standard promises 8,000 to 96,000 Hz, and browsers differ outside that. The engine’s reader does not judge the rate; the browser does, when the bank loads, and the load fails naming the wave. Headless Chrome, given a bank at 2,000 Hz, fails withwave 'ping' is 2000 Hz, which this browser's Web Audio cannot hold.
The default to pick is the sample’s: mono, 16-bit PCM at 22,050 Hz. It is exact, it is the format XWBTool packs as it is, and it is half the size of the same sound at 44,100 Hz, which short effects rarely need. An audio editor’s “WAV, signed 16-bit PCM” export gives it, or FFmpeg from any source file:
ffmpeg -i source.wav -ac 1 -ar 22050 -c:a pcm_s16le ping.wavwinget install Gyan.FFmpeg installs FFmpeg; a prompt opened afterwards finds it, and
ffmpeg -version checks it.
Sounds xwbtool will not take has the
install and the conversion step by step, with their messages.
MS-ADPCM is the choice when the download matters more than the memory. It is
about a quarter the size of 16-bit PCM in the bank and slightly lossy. XWBTool
does not encode it. adpcmencode3 does, from the Windows SDK that Visual
Studio installs, on the Native Tools prompt’s path beside fxc; it reads a PCM
WAV and writes an ADPCM one, so give the output the name the bank should use. Keep the PCM
files in a folder of their own, here pcm, so the two do not share a name:
mkdir pcmmove ping.wav pcm\ping.wavadpcmencode3 pcm\ping.wav ping.wavIt prints Encoding pcm\ping.wav (PCM mono 22050Hz 16bit, ...) to ping.wav (ADPCM 128 samples/block). and the number of bytes it produced.
It writes 128 samples a block, and XAudio2 makes a voice only when that count
is a multiple of 32. FFmpeg’s adpcm_ms encoder cannot write such a block, so
a bank of its output passes the engine’s reader and fails on Windows when it
plays. adpcmencode3 fits a
wave to a whole number of blocks by changing its sample rate, so export each
sound a multiple of 128 samples long, or XWBTool’s reading line will show a
rate a little off the one exported and the sound will play that much sharp or
flat. FFmpeg pads a sound with silence to a whole number of 128-sample blocks; run it on the PCM
file before encoding:
ffmpeg -i pcm\ping.wav -af asetnsamples=n=128 -c:a pcm_s16le pcm\ping128.wavadpcmencode3 pcm\ping128.wav ping.wavA quarter-second sound of 5,512 samples at 22,050 Hz, encoded as it was, read back at 22,018 Hz; padded to 5,632 samples first, it read back at 22,050 Hz.
Music, bank memory and the page download
Section titled “Music, bank memory and the page download”Labrador loads wave banks into memory on both platforms, including every music track in the bank. Looping a long track keeps its full wave available throughout playback. On Windows, XAudio2 plays the bank in its stored format. In a browser the reader decodes every wave to 16-bit samples at load, and Web Audio keeps each wave in 32-bit float channel buffers: twice the size of 16-bit PCM, four times 8-bit PCM, and about eight times MS-ADPCM.
For scale, three minutes of stereo, 44,100 Hz, 16-bit PCM is about 30.3 MiB of wave data. Its browser float buffers use about 60.6 MiB, in addition to the bank file in Emscripten’s in-memory filesystem and temporary data during loading. Those figures exclude container overhead and are not a peak-memory budget. Compression reduces the download; the browser still needs the decoded buffers. Load only the banks the game needs and budget their combined size.
The minimal template and audio sample use --embed-file, so their content
travels inside the wasm module even when a player never starts a particular
track. The browser asset policy
recommends switching to --preload-file when total content passes about
1 MB. Replace the existing embed options in your game’s browser target
while keeping the same source-to-filesystem mappings. Ship the generated
.data file beside the page, JavaScript and wasm and keep its URL resolvable
by the generated loader.
In a starter project that is one word in game\CMakeLists.txt. Search for --embed-file,
inside if(EMSCRIPTEN), and change it to --preload-file, so that the line reads:
"SHELL:--preload-file ${CMAKE_CURRENT_SOURCE_DIR}/content@/"Build wasm-debug again as Build for the browser does. The build
folder out\build\wasm-debug\game then has a fourth file beside MyGame.html, MyGame.js
and MyGame.wasm: MyGame.data, which holds the content folder, 99,711 bytes for a starter with
the tones bank of Play a sound in your game. Serve and open the
page as before, or run that guide’s page check; the game starts as it did, and the server’s
window shows a GET /MyGame.data line. Copy MyGame.data with the other three wherever you
put the page. Without it the game never starts, and the browser’s console, opened with F12,
shows Failed to load resource: the server responded with a status of 404 (Not Found) for
MyGame.data, then an uncaught Error: 404: with its address.
The browser build was checked this way on 31 October 2026 in a starter project with the tones
bank: the page built, passed the page check from Build for the browser, and with MyGame.data
moved away the check reported the 404 above and failed.
Preloading separates the content download from the wasm module. The generated
loader still fetches that data before startup, and load_manifest still reads
whole banks from the same filesystem paths. It does not wait until the track’s
first play or reduce its decoded memory cost. Changing that loading policy
requires game-specific work beyond replacing the linker option.
This API uses in-memory banks; streaming banks and an asynchronous streaming loader are outside its scope. The current synchronous path keeps ownership and failure handling simple (T3). A concrete game’s content and memory needs must justify that extra lifecycle before the engine adds it.
Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.