NEWS: This project is now hosted on GitHub https://github.com/Microsoft/DirectXTK. This site is being maintained for now, but please move to using GitHub https://github.com/Microsoft/DirectXTK/wiki/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 the wave bank can then be played back as one-shot sounds or via SoundEffectInstance.

See XWBTool for more information on building .xwb files.

Note: DirectXTK for Audio uses XAudio 2. It does not make use of the legacy XACT Engine, XACT Cue, or XACT SoundBank.

Header

#include <Audio.h>

Initialization

std::unique_ptr<WaveBank> wb( new WaveBank( audEngine.get(), L"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 the 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 XACTBLD3 to avoid 'magic numbers' in your code:

#include "wavebank.h"

wb->Play( XACT_WAVEBANK_WAVEBANK_BANG );

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

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

Content support

XAudio 2.9 on Windows 10 supports PCM, ADPCM, and xWMA.

XAudio 2.8 on Windows 8.x and Windows phone support PCM and ADPCM formats.

XAudio 2.7 on Windows Vista or later via the legacy DirectX End-User Runtime Redistribution (aka DirectSetup) supports PCM, ADPCM, and xWMA.

XAudio on Xbox One supports PCM, ADPCM, and xWMA. Xbox One exclusive app developers can also make use of XMA2.

XACT-style wave banks support 8-bit and 16-bit PCM (i.e. not 32-bit IEEE float PCM), ADPCM, xWMA, and XMA2 content.

XWB File Format

To aid in debugging, here is a simple console program for dumping out the content of a XWB in a human-readable form.
xwbdump.cpp

Further reading

http://msdn.microsoft.com/en-us/library/windows/desktop/dd757712.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/dd757713.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/dd743663.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/dd757714.aspx
http://msdn.microsoft.com/en-us/library/bb203879(v=xnagamestudio.40).aspx

Last edited Jul 28, 2015 at 7:05 PM by walbourn, version 30