Skip to content

Reading a sound bank

Generated from engine/assets/sound_bank_loader.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.

Browse the assets module

Audience: game code.

#include "engine/assets/sound_bank_loader.h" · namespace labrador

A bank definition, parsed: what the content says a bank holds, before anything has been opened.

IT IS A TYPE RATHER THAN A LOCAL BECAUSE THE SEAM NEEDS IT FIRST. A backend with no container - engine/audio/null/ - has no name table of its own and answers wave_index out of this list, so the definition has to be read before AudioDevice::open_wave_bank is called rather than after it. ResourceLoader's built-in sound-bank kind parses the definition before calling open_wave_bank, including for optional banks. A malformed definition therefore fails before a container open is attempted (T6).

std::vector<std::string> waves;

Every wave the definition names, in the order it names them and with no duplicates: the waves array first, then any wave a sound effect instance names that the array did not list.

struct Effect
{
std::string name;
std::string wave;
};

One named effect instance and the wave it plays.

Declared as SoundBankDefinition::Effect.

std::vector<Effect> effects;

In creation order, which is handle order: the per-wave instances first if the definition asked for them, then the explicit ones.

std::string source_path;

Where this was read from, so the throws below can name it.

Reads the bank definition at json_path.

Throws std::runtime_error naming the path if the file cannot be read or parsed, is the wrong shape, or names two effect instances the same (T6). The same throw names the path and the object for an unknown key: the document accepts only waves, create_effect_instance_for_each_wave and sound_effect_instances, and each effect instance only name and wave, so a misspelt field fails here instead of being ignored.

std::unique_ptr<SoundBank> build_sound_bank(AudioDevice* device,
const SoundBankDefinition& definition);

Builds the SoundBank that plays wave_bank out of device, creating one voice per effect the definition names.

The voices are created here, against a bank the caller has already opened, which is why the handle is passed in rather than fetched back out. Throws std::out_of_range naming the definition and the wave if the bank does not hold one an effect names - which, on a backend that has a container, open_wave_bank will already have said first.

Named in the public declarations above: AudioDevice, Effect, SoundBank.

The files that include this header directly. A file can also reach it through another header.

No guide or concept page links to this header yet.

Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.

All documentation versions