Audio
The audio sample is a playable sound board:
two short tones, a direct-WAV copy of the ping and a looping drone, with volume,
pitch and stereo pan controls. Its original PCM sounds and built XWB 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.
Press A for the ping loaded directly from a PCM WAV, without a bank-packing step.
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.
A gamepad button is not that gesture. The backend listens for key, mouse, pointer and touch events. 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 picks up a pad and never touches the keyboard, mouse or screen to hear nothing for as long as they play that way. That is read from the backend’s code and has not been tried with a pad in a browser; a browser that counts a pad press as activity on the page would change it only for a bank opened after the press. The engine does not work around this. The audio sample’s page tells the player to press a key or click, and starts without waiting for it. If your game is played on pads, have its page ask for one key press, click or tap before the game starts.
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 sounds from an XWB bank puts these bank 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”For a first sound, load one PCM WAV directly without
a bank-packing tool. Generated or already decoded sounds can use
AudioDevice::open_memory_bank
with owned WaveBankData.
The input contract and qualification record
state supported formats, loop frames, ownership and memory costs.
A sound_bank asset has two files: a JSON definition and the XAudio2 backend’s
.xwb container. The sample also declares one wave asset, whose standalone
PCM WAV becomes its own one-wave bank. The manifest names each asset without
its file extension:
{ "assets": [ { "kind": "font", "directory": "./fonts/", "names": ["jetbrains_mono_bold_16"] }, { "kind": "sound_bank", "directory": "./sounds/", "names": ["tones"], "optional": false }, { "kind": "wave", "directory": "./waves/", "names": ["ping_wav"], "optional": false } ]}samples/audio/content/manifest.json at aceb130
Both audio assets are 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 reports the reason through the diagnostic callback
(standard error by default), substitutes a silent bank and cannot demonstrate playback. A required bank
with a misspelt wave also fails during loading.
An optional-bank warning already goes to standard error in v0.3.0; replacing that destination
through this callback requires the newer API.
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 aceb130
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 21–22 at aceb130
The sound board resolves its wave and effect names in its constructor:
{ if (this->bank_ == nullptr || !this->bank_->audible()) { throw std::runtime_error("The sample 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 23–32 at aceb130
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 39–42 at aceb130
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 49–53 at aceb130
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 55–65 at aceb130
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, an infinity included, and throws std::invalid_argument for a NaN
level, as does AudioResources::set_group_volume. 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 72–76 at aceb130
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: Windows refuses a
streaming bank, made with xwbtool’s -s, when it loads (is a streaming bank). 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 XWB reader does not judge the rate; the browser does, when the bank loads, and the load fails naming the bank and wave while preserving the browser’s buffer-refusal reason. The direct WAV and memory-bank routes check 8,000 to 96,000 Hz before calling the backend.
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.
A loop region inside a wave
Section titled “A loop region inside a wave”A looping effect repeats its whole wave unless the wave carries a loop region: a first frame
and a length, kept in the bank beside the wave. With one, play_effect(effect, true) plays from
the start of the wave and then repeats the region, which is how a music track keeps an
introduction that is heard once. stop_effect(effect) without true leaves the loop and lets
the rest of the wave play. An effect played without the loop flag ignores the region, and so does
every play_wave one-shot. The sample’s three waves carry none, and its drone loops whole.
The region comes from the WAV. A WAV can hold a sampler chunk, smpl, whose loop names a first
and a last sample; XWBTool copies the first forward loop it finds there into the bank’s entry.
Its source looks for a DLS wsmp chunk before smpl and takes a loop from that one when it
finds one; only a smpl chunk has been packed here. A compact entry cannot hold one; the standard entries -nc writes can. The engine’s reader
refuses a region that runs past the end of its wave, naming the entry.
What has been checked, and what has not:
- Packing. XWBTool from the
may2026release packed a mono 16-bit PCM WAV whosesmplchunk loops samples 1,000 to 2,999 into an entry that loops 2,000 frames from frame 1,000. The result matched, byte for byte apart from the tool’s build time, the bank make_loop_bank.py writes for the engine’s tests; that script writes the WAVs and makes the comparison. Which audio editors write asmplchunk on export has not been checked, and neither has a region on an MS-ADPCM wave. - In a browser. The engine’s reader reads the region and the Web Audio backend hands it to the
source node as its
loopStartandloopEnd.AudioTestsholds those values, and where a paused loop resumes from, against a stand-in for Web Audio under Node. No browser played that bank. - On Windows. DirectX Tool Kit’s reader hands the same region to XAudio2 as the buffer’s
LoopBeginandLoopLength, with an unending loop count when the effect loops. That is read from themay2026source, inWaveBank.cppandSoundEffectInstance.cpp. The native audio sample’s finite check separately opens an owned PCM bank with a region at frame 32 for 128 frames, releases the caller’s containers, and checks playing, paused, resumed and stopped states through the real XAudio2 backend. That endpoint check passed on 17 November 2026; it does not qualify the unplayed XWB loop fixture or its audible region boundaries. - By ear. Nobody has listened to a region loop on either platform.
The -null presets keep the XWB route’s name-only recording. A memory-built
bank, including a direct WAV asset, instead records its owned samples and
frame-based region; it still has no playback clock.
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 sounds from an XWB bank. 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: the starter’s page is written to say The game could not be loaded. under the canvas, 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.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.