WaveBank

DirectXTK	Audio

WaveBank is a container class for an XACT-style wave bank that contains individual waves packaged together for more efficient loading and memory management. Sounds in an in-memory wave bank can then be played back as one-shot sounds or via SoundEffectInstance. Streaming wave banks can be played with SoundStreamInstance using non-buffering asynchronous I/O.

The WaveBank objects always owns the audio data. It must be kept 'alive' until all playing or streaming sounds using it have been stopped.

See XWBTool for more information on building .xwb files.

DirectXTK for Audio uses XAudio2. It does not make use of the legacy XACT Engine, XACT Cue, or XACT SoundBank.

Related tutorial: Making use of wave banks

Header

#include <Audio.h>

Initialization

std::unique_ptr<WaveBank> wb;
wb = std::make_unique<WaveBank>( audEngine.get(), "wavebank.xwb" ) );

For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr or std::shared_ptr

Note that in-memory banks may still be loading the wave data asynchronously after the return of this constructor. You can see if the wave data has completed loading by calling IsPrepared. If you call Play or CreateInstance before the wave data has loaded, then the thread will wait until the load is complete before returning.

Play one-shot sounds

To play a sound in a in-memory wave bank as a 'fire and forget' sound:

wb->Play( index );

index is 0-based

To play the sound in the bank as a 'fire and forget' sound with volume, a pitch-shift, and/or pan setting:

wb->Play( index, volume, pitch, pan );

volume default is 1
pitch ranges from -1 to +1, playback defaults to 0 (which is no pitch-shifting)
pan -1 is fully left, +1 is fully right, and 0 is balanced.

If the wave bank contains 'entry friendly names', you can also use them to trigger a one-shot:

wb->Play( "Bang" );
wb->Play( "Bang", 0.8f, 0.f, 1.f );

You can also make use of the C/C++ header generated by XWBTool or the legacy XACTBLD3 to avoid 'magic numbers' in your code:

#include "wavebank.h"

wb->Play( XACT_WAVEBANK_WAVEBANK_BANG );

If using literal values for the index, you may get error 2668: ambiguous call to overloaded function. Forcing the literal to an unsigned value will resolve it: wb->Play(1u);.

Note a C++ exception is thrown if attempting to play a one-shot sound from a streaming wavebank.

If the specified index or name is not found, then no one-shot is played and there is no C++ exception thrown.

Playing the sound

To play a sound from an in-memory wave bank with full control, looping, and dynamic pitch-shifting/volume control/pan settings:

auto effect = wb->CreateInstance( 2 );
if ( !effect )
    // Index not found in wave bank

To play a sound with positional 3D audio:

auto effect = wb->CreateInstance( 2,
    SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters);
if ( !effect )
    // Index not found in wave bank

If the wave bank contains 'entry friendly names', you can also use them to create an instance:

auto effect = wb->CreateInstance( "Bang" );
if ( !effect )
    // Name not found in wave bank

auto effect = wb->CreateInstance( "Bang",
    SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters);
if ( !effect )
    // Name not found in wave bank

You can also make use of the C/C++ header generated by XWBTool or legacy XACTBLD3 to avoid 'magic numbers' in your code:

#include "wavebank.h"

auto effect = wb->CreateInstance( XACT_WAVEBANK_WAVEBANK_BANG );
if ( !effect )
    // Index not found in wave bank

auto effect = wb->CreateInstance( XACT_WAVEBANK_WAVEBANK_BANG,
    SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters);
if ( !effect )
    // Index not found in wave bank

Note a C++ exception is thrown if attempting to create a sound instance from a streaming wavebank.

If the specified index or name is not found, then CreateInstance returns a 'nullptr'. Client code should be sure to check for this condition. This is done because typically games do not consider missing audio content to be a fatal error during development.

See SoundEffectInstance.

Play streaming waves

To play waves from a streaming wave bank, create a stream instance:

auto stream = wb->CreateStreamInstance( 2 );
if ( !stream )
    // Index not found in wave bank

If the wave bank contains 'entry friendly names', you can also use them to create an stream instance:

auto stream = wb->CreateStreamInstance( "Bang" );
if ( !stream )
    // Name not found in wave bank

You can also create the stream instance with 3D effects just as above for sound instances.

Note a C++ exception is thrown if attempting to create a sound stream instance from a in-memory wavebank.

See SoundStreamInstance.

Properties

IsPrepared: Returns true if the WaveBank has completed loading the wave data. For streaming buffers, they are always prepared after the constructor returns (only the metadata is loaded into memory).
IsInUse: Returns true if the WaveBank is currently playing as a one-shot or there are SoundEffectInstances referencing it.
IsStreamingBank: Returns true if the wave bank is a streaming type, false if it is an in-memory wave bank.
GetSampleSizeInBytes ( index ): Returns the size of the wave data in bytes. This will return 0 if the index is invalid.
GetSampleDuration ( index ): Returns the wave data duration in samples. This does not include any loops. This will return 0 if the index is invalid.
GetSampleDurationMS ( index ): Returns the wave data duration in milliseconds. This does not include any loops. This will return 0 if the index is invalid.
GetFormat ( index, WAVEFORMATEX* wfx, size_t maxsize ): Fills out a WAVEFORMATEX structure that describes the wave data format. This will return nullptr if the index is invalid, otherwise it returns a pointer to wfx. Since the format can be variable length, the caller provides the buffer and maxsize. See Wave Formats.

At least 64 bytes is recommended as this is large enough to contain WAVEFORMAT, PCMWAVEFORMAT, WAVEFORMATEX, ADPCMWAVEFORMAT with coefficients, WAVEFORMATEXTENSIBLE, or a XMA2WAVEFORMATEX.

char formatBuff[ 64 ] = {};
auto wfx = reinterpret_cast<WAVEFORMATEX*>( formatBuff );

wb->GetFormat( 2, wfx, 64 );

Find ( const char* name ): Returns the index, or -1 if not found or if there are no entry friendly names present in the wave bank.

Low-level access

FillSubmitBuffer is used internally, but can also be used when implementing your own XAudio2 source voices using the low-level interface access. Note that LoopCount is set to 0 by this function and should be set to a non-zero value by the caller. If looping is not desired, be sure to set LoopBegin and LoopLength to zero as well.

Care needs to be taken to ensure that any referenced WaveBank is not deleted while a source voice is actively playing back content from it or has pending buffers referencing it.