Skip to content

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.

Terminal window
cd /d C:\dev\mygame\external\labrador
cmake --preset x64-debug
cmake --build --preset x64-debug --target AudioSample
out\build\x64-debug\samples\audio\AudioSample.exe

Press 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.

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.

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:

samples/audio/content/manifest.json
{
"assets": [
{
"kind": "font",
"directory": "./fonts/",
"names": ["jetbrains_mono_bold_16"]
},
{
"kind": "sound_bank",
"directory": "./sounds/",
"names": ["tones"],
"optional": false
}
]
}

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:

samples/audio/content/sounds/tones.json
{
"waves": ["ping", "chime", "drone"],
"create_effect_instance_for_each_wave": false,
"sound_effect_instances": [
{"name": "drone_loop", "wave": "drone"}
]
}

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.

After loading the manifest, the state borrows the bank from AudioResources:

samples/audio/audio_state.cpp
SoundBank* bank = this->app_->audio_resources()->sound_bank("tones");
this->board_ = std::make_unique<SoundBoard>(bank);

The sound board resolves its wave and effect names in its constructor:

samples/audio/sound_board.cpp
SoundBoard::SoundBoard(labrador::SoundBank* bank) : bank_(bank)
{
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");
}

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.

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:

samples/audio/sound_board.cpp
void SoundBoard::play_ping() const
{
this->bank_->play_wave(this->ping_, this->volume_, this->pitch_, this->pan_);
}

Use an effect instance when the voice must persist. The loop flag belongs to the play call, not the bank definition:

samples/audio/sound_board.cpp
void SoundBoard::start_loop() const
{
this->bank_->play_effect(this->drone_, true,
this->volume_, this->pitch_, this->pan_);
}

The same instance can be paused and resumed without starting a second voice:

samples/audio/sound_board.cpp
void SoundBoard::toggle_pause() const
{
if (this->loop_state() == labrador::SoundState::playing)
{
this->bank_->pause_effect(this->drone_);
}
else if (this->loop_state() == labrador::SoundState::paused)
{
this->bank_->resume_effect(this->drone_);
}
}

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.

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:

samples/audio/sound_board.cpp
void SoundBoard::set_volume(float volume)
{
this->volume_ = labrador::clamp(volume, 0.0f, 1.0f);
this->bank_->set_effect_volume(this->drone_, this->volume_);
}

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.

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:

Terminal window
xwbtool -f -nc -y -o tones.xwb ping.wav chime.wav drone.wav

It 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.

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 (-nc above).
  • 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 AudioBuffer accepts. 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 with wave '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:

Terminal window
ffmpeg -i source.wav -ac 1 -ar 22050 -c:a pcm_s16le ping.wav

winget 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:

Terminal window
mkdir pcm
move ping.wav pcm\ping.wav
adpcmencode3 pcm\ping.wav ping.wav

It 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:

Terminal window
ffmpeg -i pcm\ping.wav -af asetnsamples=n=128 -c:a pcm_s16le pcm\ping128.wav
adpcmencode3 pcm\ping128.wav ping.wav

A 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.

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.

All documentation versions