Adding the DirectX Tool Kit for Audio

This lesson covers adding DirectX Tool Kit for Audio to your project.

Setup

First create a new project using the instructions from the first two lessons: The basic game loop and Adding the DirectX Tool Kit which we will use for this lesson.

NuGet package manager

If you used NuGet when Adding the DirectX Tool Kit, then you may already have support for DirectX Tool Kit for Audio..

directxtk_desktop_2015	This package is configured for Windows 7 Service Pack 1 support for graphics & input, but make use of Audio 2.8 for DirectX Tool Kit for Audio. Therefore audio support with NuGet requires Windows 8 or later.
directxtk_uwp directxtk12_uwp directxtk12_desktop_2015	These packages are configured for Windows 10 support for graphics, input, and make use of XAudio 2.9 for DirectX Tool Kit for Audio.

If you need Windows 7 Service Pack 1 support for audio, then use Project-to-project references instead of NuGet for graphics, input, and audio.

See this blog post for details on why it's set up this way.

Complete the steps in Adding the headers below.

Project-to-project references

If you used project-to-project references when Adding the DirectX Tool Kit, then you need to add an additional DirectX Tool Kit for Audio project to your solution. There are four (4) choices depending on your platform target and deployment requirements:

XAudio 2.9

XAudio 2.9 is built into Windows 10. Everything required is included in the operating system and the Windows 10 SDK. This version of DirectX Tool Kit for Audio is already included in those projects (DirectXTK*_Windows10_201x.vcxproj, DirectXTK*_Desktop_201x_Win10.vcxproj,) and Xbox One (DirectXTK*_XboxOneXDK_201x.vcxproj).

Complete the steps in Adding the headers below.

XAudio 2.8

XAudio 2.8 is built into Windows 8.0 or later. Everything required is included in the operating system and the Windows 10 SDK.

Right-click on your solution in the Solution Explorer, and select Add / Existing Project...
Browse into the "DirectXTK\Audio" folder and select DirectXTKAudio_Desktop_201x_Win8.vcxproj, click "Open"
If Visual Studio presents a "Security Warning", select "OK". Optional: Uncheck "Ask me for every project in this solution" first.
Right-click on your project in the Solution Explorer, and select Add / References...
Select "Add New Reference..."
Check DirectXTKAudio_Desktop_201x_Win8.vcxproj and select "OK"
Select "OK"

Add Reference (Windows 8)

Complete the steps in Adding the headers below including the additional configuration for XAudio 2.8.

XAudio2 Redistributable

There is an XAudio 2.9 redistributable package available on NuGet that supports Windows 7 SP1, Windows 8, Windows 8.1, and Windows 10 for Win32 desktop applications. The required runtime DLL is included side-by-side with your application, and avoids the need to include any legacy DirectX SDK redist package.

Right-click on your solution in the Solution Explorer, and select Add / Existing Project...
Browse into the "DirectXTK\Audio" folder and select DirectXTKAudio_Desktop_201x_Win7.vcxproj, click "Open"
If Visual Studio presents a "Security Warning", select "OK". Optional: Uncheck "Ask me for every project in this solution" first.
Right-click on your project in the Solution Explorer, and select Add / References...
Select "Add New Reference..."
Check DirectXTKAudio_Desktop_201x_Win7.vcxproj and select "OK"
Select "OK"

In addition to the reference, you'll need to add the Microsoft.XAudio2.Redist NuGet package to your project(s) to ensure you have the correct XAudio2 headers and link libraries for this option.

From the drop-down menu, select Project / Manage NuGet Packages...
Select "Browse" on the top tab, and make sure the Package source is set to "nuget.org"
In the text search field type "XAudio2" and hit enter to search for the packages
Select the package with the id **Microsoft.XAudio2.Redist
Select "Install"
When finished, close the NuGet Manager

Complete the steps in Adding the headers below.

This is the preferred option for supporting XAudio2 on Windows 7, and is also a good choice if you want xWMA format support on Windows 8.x.

See Microsoft Docs.

XAudio 2.7

XAudio 2.7 supports Windows 7 and older operating systems. It is deployed by the legacy DirectX End User Runtime package and requires the legacy DirectX SDK (June 2010) to develop with. Due to some technical issues, it must be installed to the 'default' location of C:\Program Files (x86)\Microsoft DirectX SDK (June 2010). To install the legacy DirectX SDK on your development system, see this post and be sure to read this article for a known issue with the installer.

Right-click on your solution in the Solution Explorer, and select Add / Existing Project...
Browse into the "DirectXTK\Audio" folder and select DirectXTKAudio_Desktop_201x_DXSDK.vcxproj, click "Open"
If Visual Studio presents a "Security Warning", select "OK". Optional: Uncheck "Ask me for every project in this solution" first.
Right-click on your project in the Solution Explorer, and select Add / References...
Select "Add New Reference..."
Check DirectXTKAudio_Desktop_201x_DXSDK.vcxproj and select "OK"
Select "OK"

Add Reference (DirectX SDK)

Complete the steps in Adding the headers below including the additional configuration for XAudio 2.7.

This option is not recommended, but is included for completeness. Xaudio 2.7 has a number of known bugs.

Adding the headers

Now that we have the DirectX Tool Kit for Audio usable in your project, the next step is to include the library header into your project.

//
// pch.h
// Header for standard system include files.
//

#pragma once

...

#include "Audio.h"

...

XAudio 2.9

For a desktop application that requires Windows 10, in your pch.h modify the following section:

#include <winsdkver.h>
#define _WIN32_WINNT 0x0A00
#include <sdkddkver.h>

For Windows 10 platforms other than Windows desktop, you do not need to explicitly set _WIN32_WINNT as it's already set appropriately.

XAudio 2.8

If you are using XAudio 2.8, then your application should be built to require Windows 8.0 or later. In pch.h modify the following section:

#include <winsdkver.h>
#define _WIN32_WINNT 0x0602
#include <sdkddkver.h>

XAudio 2.7

If you are using XAudio 2.7 for Windows 7 compatibility (_WIN32_WINNT set to 0x0601), we also need to add the legacy DirectX SDK include and library paths to your project. First go to Project / Properties and select "VC++ Directories" on the left. Then set Configuration to "All Configurations" and Platform to "x86". Add to the end of these paths:

Include Directories: ;$(DXSDK_DIR)Include
Library Directories: ;$(DXSDK_DIR)Lib\x86

Click "Apply".

VC++ Directories (x86)

Then set Configuration to "All Configurations" and Platform to "x64". Add to the end of these paths:

Include Directories: ;$(DXSDK_DIR)Include
Library Directories: ;$(DXSDK_DIR)Lib\x64

Click "Apply".

VC++ Directories (x64)

It is important that the legacy DirectX SDK paths be after the existing path since are making use of the Windows 8.1 / 10 SDK. See Where is the DirectX SDK? for more details.

Troubleshooting: If you get a compilation error indicating you are missing comdecl.h, then you have incorrectly configured your VC++ Directory include paths. If you get a link error indicating you are missing x3daudio.lib then you incorrectly configured your VC++ Directory library paths.

Troubleshooting: If you get a compilation error indicating you are missing comdecl.h, then you have incorrectly configured the _WIN32_WINNT variable. See Using the Windows Headers.

Deployment

If you are using XAudio 2.8, then your application has a dependency on Windows 8.0 or later. If using XAudio 2.9, your application will only run on Windows 10 devices.

If you are using the XAudio2 Redistributable, then you will need to include the XAUDIO2_9REDIST.DLL from the NuGet package as part of your application.

If you are using XAudio 2.7, then your application has a dependency on the DirectX End-User Runtime. See Not So DirectSetup for information on using this package. Again, this is not recommended for use.

Next lesson: Adding audio to your project