Use XAudio2 to play a sound

Use XAudio2 to load and play a .wav file on XBOX One. The following sections describe how to use XAudio2 to load and play a sound on the XBOX One Development Kit.

Important XAudio2 data types
Initializing XAudio2
Loading a .wav file
Setting a file path to a .wav file
Playing a .wav file
Terminating a .wav file

For a working XAudio2 sample, download the SimplePlaySound sample from the Microsoft Game Development Kit (GDK) samples.

Important XAudio2 data types

XAudio2 provides several data types to help you play sound effects on XBOX One. To play a .wav file, you need at least the following data types.

IXAudio2: This is the interface for the XAudio2 object that manages all Audio Engine states, the audio processing thread, the voice graph, and more.
IXAudio2SourceVoice: Use a source voice to submit audio data to the XAudio2 processing pipeline. To be heard, voice data must be sent to a mastering voice.
IXAudio2MasteringVoice: Use this data type to represent the audio output device. Data buffers can’t be submitted directly to mastering voices. However, to be heard, data submitted to other types of voices must be directed to a mastering voice.

In addition, you might find the following data types useful.

PlaySoundVoiceContext: Use this data type to free up the audio buffer after processing.
IXAudio2VoiceCallback: This data type contains methods that notify the client when certain events happen in a specific IXAudio2SourceVoice.

Initializing XAudio2

CoInitializeEx() initializes the Component Object Model (COM) for use by the current thread. Set the first parameter to NULL. Set the second parameter to COINIT_MULTITHREADED. XAudio2Create() creates a new XAudio2 object and returns a pointer to its IXAudio2 interface. Ensure that XAUDIO2_PROCESSOR is set to a valid value. The value XAUDIO2_USE_DEFAULT_PROCESSOR is recommended to let the OS choose the ideal processor based on the hardware platform. IXAudio2::CreateMasteringVoice() creates and configures a mastering voice and points to it with the user-provided pointer.

C++

CoInitializeEx( NULL, COINIT_MULTITHREADED );

// Create an XAudio2 device.
DX::ThrowIfFailed( XAudio2Create( &m_pXAudio2, 0, XAUDIO2_USE_DEFAULT_PROCESSOR, NULL ) );

// Create an XAudio2 mastering voice, and store the result.
DX::ThrowIfFailed( m_pXAudio2->CreateMasteringVoice( &m_pMasteringVoice ) );  

Loading a .wav file

To access the audio file, use an instance of the WaveFile class.

To open a .wav file and retrieve some information stored in the file’s header, call WaveFile::Open(LPCWSTR strFileName).
To determine the format of the .wav file, call WaveFile::GetFormat().
To determine the number of bytes and samples in the .wav file, call WaveFile::GetDuration().
To read the sample data into memory, call WaveFile::ReadSample().

C++

// Read the .wav file.
WaveFile WaveFile;

// Append the file name and location to the end of the installation location.
WCHAR FilenameAndLocation[ 1024 ];
_snwprintf_s( FilenameAndLocation, _countof( FilenameAndLocation ), _TRUNCATE, L"%s%s", g_strCommonFileRoot, szFilename );

DX::ThrowIfFailed( WaveFile.Open( FilenameAndLocation ) );

// Read the format header.
BYTE header[64];
WAVEFORMATEX* pbWfx = reinterpret_cast<WAVEFORMATEX*>(header);

DX::ThrowIfFailed( WaveFile.GetFormat( pbWfx, sizeof(header) ) );

// Calculate the number of bytes and samples in the .wav file. 
DWORD cbWaveSize = WaveFile.GetDuration();

// Read the sample data into memory.
BYTE* pbWaveData = new BYTE[ cbWaveSize ];
DX::ThrowIfFailed( WaveFile.ReadSample( 0, pbWaveData, cbWaveSize, &cbWaveSize ) );  

Setting a file path to a .wav file

To load and use audio files, use the following code to find the installation location of your project on the local device. Store the installation location in a string. Append the location of the audio file to the end of the installation location string.

C++

std::wstring installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation->Path->Data();  

Playing a .wav file

Create an IXAudio2::CreateSourceVoice() class, and then use it to submit audio data to the XAudio2 processing pipeline. For voice data to be heard, you must send it to a mastering voice directly or through intermediate submix voices. To store the details of the audio file, create an XAUDIO2_BUFFER. After you create and initialize the XAudio2 buffer and source voice, call IXAudio2SourceVoice::SubmitSourceBuffer() to add the audio buffer to the voice input queue. Note that the audio data pointed to by XAUDIO2_BUFFER::pAudioData must remain valid until XAudio2 has finished playing the contents of the buffer. After the voice input queue is populated, call IXAudio2SourceVoice::Start() to play the next sound in the queue.

C++

// Play the .wav file by using a new XAudio2SourceVoice.
// Create the source voice.
DX::ThrowIfFailed( pXaudio2->CreateSourceVoice( &m_pSourceVoice, pbWfx, 0, XAUDIO2_DEFAULT_FREQ_RATIO, &m_VoiceContext ) );

// Submit the .wav sample data by using an XAUDIO2_BUFFER structure.
XAUDIO2_BUFFER buffer = {0};
buffer.pAudioData     = pbWaveData;
buffer.Flags          = XAUDIO2_END_OF_STREAM;
buffer.AudioBytes     = cbWaveSize;
buffer.pContext       = pbWaveData;

// Add the audio buffer to the voice input queue.
DX::ThrowIfFailed( m_pSourceVoice->SubmitSourceBuffer( &buffer ) );

// Play the next audio buffer in the queue.
DX::ThrowIfFailed( m_pSourceVoice->Start( 0 ) );  

Terminating a .wav file

To determine whether a .wav file has been played to completion, you’ll need the current state of the source voice. Create an XAUDIO2_VOICE_STATE struct, and then call IXAudio2SourceVoice::GetState(). If the audio has been played to completion, call IXAudio2SourceVoice::DestroyVoice().

C++

// Determine whether the sound effect has been played to completion, and handle an appropriate termination.
XAUDIO2_VOICE_STATE state;
m_pSourceVoice->GetState( &state, XAUDIO2_VOICE_NOSAMPLESPLAYED );
if( state.BuffersQueued == 0 )
{
  // Destroy the current sound effect.
  m_pSourceVoice->DestroyVoice();
}  

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Important XAudio2 data types

Initializing XAudio2

C++

Loading a .wav file

C++

Setting a file path to a .wav file

C++

Playing a .wav file

C++

Terminating a .wav file

C++

See also

​Important XAudio2 data types

​Initializing XAudio2

​C++

​Loading a .wav file

​C++

​Setting a file path to a .wav file

​C++

​Playing a .wav file

​C++

​Terminating a .wav file

​C++

​See also

Important XAudio2 data types

Initializing XAudio2

C++

Loading a .wav file

C++

Setting a file path to a .wav file

C++

Playing a .wav file

C++

Terminating a .wav file

C++

See also