> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usar o XAudio2 para reproduzir um som

> Usar o XAudio2 para reproduzir um som

Use o `XAudio2` para carregar e reproduzir um arquivo .wav no XBOX Series X|S.

As seções a seguir descrevem como usar o `XAudio2` para carregar e reproduzir um som no XBOX One Development Kit.

* [Tipos de dados importantes do XAudio2](#ID4ELB)
* [Inicializando o XAudio2](#ID4EXC)
* [Carregando um arquivo .wav](#ID4E1D)
* [Definindo um caminho de arquivo para um arquivo .wav](#ID4E2H)
* [Reproduzindo um arquivo .wav](#ID4EAF)
* [Encerrando um arquivo .wav](#ID4E2F)

Para obter um exemplo funcional do `XAudio2`, baixe o exemplo SimplePlaySound dos exemplos do Microsoft Game Development Kit (GDK).

## Tipos de dados importantes do XAudio2

O `XAudio2` fornece vários tipos de dados para ajudar você a reproduzir efeitos sonoros no XBOX Series X|S. Para reproduzir um arquivo .wav, você precisa no mínimo dos tipos de dados a seguir.

* `IXAudio2`: esta é a interface do objeto `XAudio2` que gerencia todos os estados do Audio Engine, o thread de processamento de áudio, o grafo de vozes e muito mais.

* `IXAudio2SourceVoice`: use uma voz de origem para enviar dados de áudio ao pipeline de processamento do `XAudio2`. Para serem ouvidos, os dados de voz devem ser enviados a uma voz de masterização.

* `IXAudio2MasteringVoice`: use este tipo de dados para representar o dispositivo de saída de áudio. Buffers de dados não podem ser enviados diretamente às vozes de masterização. No entanto, para serem ouvidos, os dados enviados a outros tipos de vozes devem ser direcionados a uma voz de masterização.

Além disso, os tipos de dados a seguir podem ser úteis.

* `PlaySoundVoiceContext`: use este tipo de dados para liberar o buffer de áudio após o processamento.

* `IXAudio2VoiceCallback`: este tipo de dados contém métodos que notificam o cliente quando determinados eventos ocorrem em um `IXAudio2SourceVoice` específico.

## Inicializando o XAudio2

`CoInitializeEx()` inicializa o Component Object Model (COM) para uso pelo thread atual. Defina o primeiro parâmetro como `NULL`. Defina o segundo parâmetro como `COINIT_MULTITHREADED`.

`XAudio2Create()` cria um novo objeto `XAudio2` e retorna um ponteiro para sua interface `IXAudio2`. Verifique se `XAUDIO2_PROCESSOR` está definido com um valor válido. O valor `XAUDIO2_USE_DEFAULT_PROCESSOR` é recomendado para permitir que o sistema operacional escolha o processador ideal com base na plataforma de hardware.

`IXAudio2::CreateMasteringVoice()` cria e configura uma voz de masterização e aponta para ela com o ponteiro fornecido pelo usuário.

### C++

```cpp theme={null}
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 ) );  
```

## Carregando um arquivo .wav

Para acessar o arquivo de áudio, use uma instância da classe `WaveFile`.

* Para abrir um arquivo .wav e recuperar algumas informações armazenadas no cabeçalho do arquivo, chame `WaveFile::Open(LPCWSTR strFileName)`.
* Para determinar o formato do arquivo .wav, chame `WaveFile::GetFormat()`.
* Para determinar o número de bytes e amostras no arquivo .wav, chame `WaveFile::GetDuration()`.
* Para ler os dados de amostra na memória, chame `WaveFile::ReadSample()`.

### C++

```cpp theme={null}
// 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 ) );  
```

## Definindo um caminho de arquivo para um arquivo .wav

Para carregar e usar arquivos de áudio, use o código a seguir para encontrar o local de instalação do seu projeto no dispositivo local. Armazene o local de instalação em uma cadeia de caracteres. Acrescente o local do arquivo de áudio ao final da cadeia de caracteres do local de instalação.

### C++

```cpp theme={null}
std::wstring installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation->Path->Data();  
```

## Reproduzindo um arquivo .wav

Crie uma classe `IXAudio2::CreateSourceVoice()` e use-a para enviar dados de áudio ao pipeline de processamento do `XAudio2`. Para que os dados de voz sejam ouvidos, você deve enviá-los a uma voz de masterização diretamente ou por meio de vozes de submix intermediárias. Para armazenar os detalhes do arquivo de áudio, crie um `XAUDIO2_BUFFER`.

Depois de criar e inicializar o buffer do `XAudio2` e a voz de origem, chame `IXAudio2SourceVoice::SubmitSourceBuffer()` para adicionar o buffer de áudio à fila de entrada da voz. Observe que os dados de áudio apontados por `XAUDIO2_BUFFER::pAudioData` devem permanecer válidos até que o `XAudio2` termine de reproduzir o conteúdo do buffer.

Depois que a fila de entrada da voz for preenchida, chame `IXAudio2SourceVoice::Start()` para reproduzir o próximo som da fila.

### C++

```cpp theme={null}
// 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 ) );  
```

## Encerrando um arquivo .wav

Para determinar se um arquivo .wav foi reproduzido até o fim, você precisará do estado atual da voz de origem. Crie um struct `XAUDIO2_VOICE_STATE` e chame `IXAudio2SourceVoice::GetState()`. Se o áudio tiver sido reproduzido até o fim, chame `IXAudio2SourceVoice::DestroyVoice()`.

### C++

```cpp theme={null}
// 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();
}  
```

## Confira também

[Visão geral do XAudio2](https://docs.xbox.com/pt-BR/build/console-features/audio/overviews/xaudio2-overview.md)
[Visão geral do ADPCM](https://docs.xbox.com/pt-BR/build/console-features/audio/overviews/adpcm-overview.md)
[Codificador de linha de comando ADPCM](https://docs.xbox.com/pt-BR/build/console-features/audio/tools/adpcmencoder-tools.md)


## Related topics

- [Codificador de linha de comando ADPCM](https://docs.xbox.com/pt-BR/build/console-features/audio/tools/adpcmencoder-tools.md)
- [Visão geral do ADPCM](https://docs.xbox.com/pt-BR/build/console-features/audio/overviews/adpcm-overview.md)
- [Visões gerais](https://docs.xbox.com/pt-BR/build/console-features/audio/overviews/index.md)
- [Visão geral do xWMA](https://docs.xbox.com/pt-BR/build/console-features/audio/overviews/xwma-overview.md)
- [XAudio2CreateWithSharedContexts](https://docs.xbox.com/pt-BR/reference/audio/xaudio2xbox/functions/xaudio2createwithsharedcontexts.md)