XWBTool
| DirectXTK | DirectXTK12 |
|---|
The XWBTool is a command-line utility for building XACT-style wave banks for use with the DirectXTK for Audio Wave Bank class.
The command-line tools in the DirectXTK package are only built by the DirectXTK_Desktop_201x solutions since they are Win32 desktop applications.
Related tutorial: Making use of wave banks
xwbtool.exe uses the following command syntax:
xwbtool [options] [--file-list <filename>] <file-name(s)>
The file-name parameter indicates the .wav file(s) to add to the wave bank.
The command-line parsing uses Windows-style
-or/for options. It also has some POSIX-like behavior: it supports--versionand--helpcommand-line options, and the use of--disables further options parsing to support filenames that begin with-or/characters. There are 'GNU long options' style command-line parameters that use--as well.
-r: Input file names can contain wildcard characters (? or *). If this switch is used, subdirectories are also searched.
-flist filename, --file-list filename: Uses the provided filename as a text file containing a list of input files (one per line). Ignores lines that begin with # (used for comments). Does not support providing additional command-line arguments or the use of filename wildcards.
-o filename: Sets output filename for .xwb file. Otherwise, it defaults to the same base name as the first input .wav file
-l, --to-lowercase: Forces the output path & filename to all lower-case. Windows file system is case-insensitive by default, but some programs like git are case-sensitive.
-y, --overwrite: overwrite existing output file if any. By default, the tool will not overwrite a file if it exists.
-s, --streaming: Creates as streaming wave bank, otherwise defaults to in-memory wave bank
-h filename: Generates a C/C++ header file with #define symbols for each of the sounds in the bank matched to their index
-c / --compact, -nc / --no-compact: Forces creation or prevents use of compact wave banks. By default, it will try to use a compact wave bank if possible. If forcing compact and the data is too large, the operation will fail.
-f, --friendly-names: Includes entry friendly name strings in the wave bank for use with 'string' based versions of WaveBank::Play() and WaveBank::CreateInstance() rather than index-based versions. The 'friendly name' itself is just the 'stem' of the input .wav filename.
-af, --advanced-format: Indicates that streaming wave banks should use 4K alignment rather than DVD (2K) alignment. This is needed to support Advanced Format (4K native) disks with non-buffered I/O reads if there is no support for "512e". See below for more information.
Open a Command Prompt, and change to the directory containing XWBTool.exe (i.e. ...\DirectXTK\XWBTool\bin\Release)
Enter the following command-line after changing to the appropriate directory:
xwbtool -o wavebank.xwb Sound.wav Explosion.wav Music.wav
The file wavebank.xwb is generated from the three input .wav files.
xwbtool -o test.xwb C:\Windows\Media\*.wav
The file test.xwb is generated from all the .wav files in the C:\Windows\Media directory.
XACT-style wave banks come in two forms: in-memory and streaming. The in-memory form is intended to have the whole wave bank loaded into memory at once for use. This allows wave banks to be organized by use and efficiently loaded with minimal memory fragmentation. For use with SoundEffectInstance and as one-shots with WaveBank's Play method, use the in-memory form.
The streaming form is laid out such that each individual wave in the bank is aligned to 4K boundaries for use with async I/O. Only the metadata is loaded into memory, with all the wave data read on-demand from the remainder of the file. See the XAudio2AsyncStream sample code on GitHub for an example of using the streaming wave bank form.
XACT-style wave banks store meta-data in two forms: standard and compact. In the standard form, the wave-bank metadata is written using a 24-byte record per wave in the bank. In the compact form, they only requires 4-bytes per record. The Compact form requires that all waves in the bank have the same format, and the overall size of the bank's wave data must be less than 8,388,604 (~8 MB) for in-memory wave banks, or 268,433,408 bytes (~256 MBs) for streaming wave banks.
XWBTool will attempt to create a compact wave bank if the input .wav files allow, otherwise it will use the standard form. The -c and -nc command line options override this behavior.
For streaming wave banks, the layout of the file is purposely designed to support non-buffered asynchronous I/O for the wave data. By default the -s switch will align the wave data to 2048 bytes which is consistent with DVD sector alignment, and has traditionally been a multiple for all known HDD sector sizes. With the advent of newer Advanced Format (4k native) HDDs, 4096 byte alignment is becoming the norm. By using -s -af, the generated streaming wave bank will use 4K sector alignment.
Use of -af is recommended when creating streaming wave banks for Xbox Series X|S.
See Wikipedia and Microsoft Docs for more information.
Compact wave banks (-c) are not compatible with Advanced Format sector alignment (-af), so can't be used together.
The XACT3 GUI and/or the XACTBLD command-line tool in the legacy DirectX SDK (DirectX SDK) can be used to build .xwb wave banks that are compatible with DirectXTK for Audio if built for Windows (Little-endian) rather than Xbox 360 (Big-endian). XWBTool is just a simplified way to build them.
Endianness: DirectXTK for Audio does support loading Big-endian (aka Xbox 360) wave banks since those are the only kind that are generated when using the legacy tools with XMA compression when targeting the Xbox One XDK. This support is limited to XMA and 8-bit PCM data, however, as the wave data itself is not byte-swapped. XWBtool always builds Little-endian wave banks.
Known Issue: DirectX SDK (June 2010) Setup and the S1023 Error
Compact wave banks: The legacy XACT3 ENGINE only supports 'streaming' compact wave banks not 'in-memory' compact wave banks. The XACT3 GUI / XACTBLD toolset will therefore only create 'standard' in-memory wave banks. There is also a known bug in the DirectX SDK (June 2010) version of the XACT3 GUI / XACTBLD toolsets that will not attempt to create a compact wave bank if the wave data size exceeds 2,097,151 (~2 MB).
XACT-style wave banks support 8-bit and 16-bit PCM (i.e. not 32-bit IEEE float PCM), ADPCM, xWMA, and XMA2 content.
To compress to ADPCM (a variant of MS-ADPCM) .wav files, use adpcmencode.exe from the Windows SDK, Microsoft GDK, Xbox One XDK, or legacy DirectX SDK.
To compress to xWMA .wav files, use xwmaencode.exe from the Microsoft GDK with Xbox extensions, Xbox One XDK, or legacy DirectX SDK.
To compress to XMA2 .wav files, use xma2encode.exe from the Microsoft GDK with Xbox extensions or the Xbox One XDK.
This tool is also included in the XAudio2 Win32 desktop samples package.