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

# Comparação das APIs de áudio do XDK e do GDK

> Comparação das APIs de áudio do XBOX One Software Development Kit e do Microsoft Game Development Kit

Este tópico descreve como as APIs de áudio do XBOX One Software Development Kit foram alteradas para o Microsoft Game Development Kit (GDK).

## Diretrizes

* Para ajudar a garantir que os usuários tenham a melhor experiência de jogo possível, determine se o ponto de extremidade dá suporte a áudio multicanal. Primeiro, chame [IAudioClient::IsFormatSupported](https://learn.microsoft.com/windows/desktop/api/audioclient/nf-audioclient-iaudioclient-isformatsupported). Se o formato preferencial não tiver suporte, use como alternativa a renderização no formato de mixagem, [IAudioClient::GetMixFormat](https://learn.microsoft.com/windows/desktop/api/audioclient/nf-audioclient-iaudioclient-getmixformat).

* Em vez de lidar apenas com pontos de extremidade 7.1, os títulos também devem ser capazes de lidar nativamente com pontos de extremidade 2.0, 5.1 e 7.1 e reagir em tempo real se os formatos mudarem por meio de invalidações do cliente de áudio. Se um título não quiser fornecer três fontes de áudio diferentes (com relação às contagens de canais), ele poderá pedir ao sistema operacional que execute o upmixing e o downmixing por ele, com o sinalizador de fluxo [AUDCLNT\_STREAMFLAGS\_AUTOCONVERTPCM](https://learn.microsoft.com/windows/desktop/coreaudio/audclnt-streamflags-xxx-constants) na inicialização do Audioclient. Mesmo que o jogo peça ao sistema operacional para executar o upmixing e o downmixing, ele ainda receberá
  e precisará reagir a invalidações do cliente de áudio.

* Para enumerar dispositivos de áudio (de renderização e captura), use a [API MMDevice](https://learn.microsoft.com/windows/desktop/coreaudio/mmdevice-api). Se estiver renderizando áudio somente para o ponto de extremidade HDMI principal, chame [GetDefaultAudioEndpoint](https://learn.microsoft.com/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdeviceenumerator-getdefaultaudioendpoint)

* No XBOX, renderize áudio de um processo por vez.

* O controle remoto do XBOX Manager foi projetado para dar suporte a áudio por meio da [Windows Audio Session API ](/pt-BR/build/console-features/audio/overviews/wasapi-overview) (WASAPI). No entanto, ele não dá suporte a streaming de áudio do [ISpatialAudioClient](/pt-BR/build/console-features/audio/overviews/spatial-audio-overview) (ISAC) quando as configurações de home theater Dolby/DTS estão ativadas.

* Muitos métodos associados à WASAPI podem retornar o código de erro [AUDCLNT\_E\_DEVICE\_INVALIDATED](https://learn.microsoft.com/windows/win32/api/audioclient/nf-audioclient-iaudioclient-start) se o dispositivo de ponto de extremidade de áudio que o aplicativo cliente está usando se tornar inválido. Certifique-se de que seu título esteja respondendo adequadamente a esses erros, que podem ocorrer se um dispositivo de ponto de extremidade for alterado de qualquer forma. Mais informações sobre como se recuperar de um erro de dispositivo inválido com a WASAPI estão [aqui](https://learn.microsoft.com/windows/win32/coreaudio/recovering-from-an-invalid-device-error). Uma maneira fácil de confirmar que seu título lida corretamente com a invalidação de dispositivos de áudio é alternar para a página de configurações de áudio enquanto o título está em execução e alterar a contagem de canais no dispositivo HDMI. Durante um cenário de invalidação, os seguintes códigos de erro podem ser retornados pela WASAPI:

  * AUDCLNT\_E\_DEVICE\_INVALIDATED

  * AUDCLNT\_E\_RESOURCES\_INVALIDATED

  * AUDCLNT\_E\_UNSUPPORTED\_FORMAT

  * AUDCLNT\_E\_ENDPOINT\_CREATE\_FAILED

* Quando o Som Espacial é usado pelo seu título, você interage com as APIs do ISAC, que também retornam códigos de erro relacionados à invalidação de dispositivos. No ISAC, a invalidação ocorre quando o ponto de extremidade de áudio é alterado ou o modo de renderização espacial é alterado durante a reprodução. Mais informações sobre como se recuperar de um erro de dispositivo inválido com o ISAC estão [aqui](https://learn.microsoft.com/windows/win32/coreaudio/recovering-from-an-invalid-device-error-spatial-sound). Isso acontece quando qualquer um dos métodos a seguir retorna um dos valores a seguir.

  Métodos:

  * [ISpatialAudioObjectRenderStreamBase](https://learn.microsoft.com/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-ispatialaudioobjectrenderstreambase)

  * [ISpatialAudioObjectRenderStream](https://learn.microsoft.com/windows/win32/api/spatialaudioclient/nn-spatialaudioclient-ispatialaudioobjectrenderstream)

  * [ISpatialAudioObjectRenderStreamForMetadata](https://learn.microsoft.com/windows/win32/api/spatialaudiometadata/nn-spatialaudiometadata-ispatialaudioobjectrenderstreamformetadata)

  * [ISpatialAudioObjectRenderStreamForHrtf](https://learn.microsoft.com/windows/win32/api/spatialaudiohrtf/nn-spatialaudiohrtf-ispatialaudioobjectrenderstreamforhrtf)

  Valores:

  * SPTLAUDCLNT\_E\_DESTROYED
  * AUDCLNT\_E\_DEVICE\_INVALIDATED
  * AUDCLNT\_E\_RESOURCES\_INVALIDATED
  * AUDCLNT\_E\_UNSUPPORTED\_FORMAT
  * SPTLAUDCLNT\_E\_INTERNAL

    Além disso, conectar ou desconectar um headset do controle quando o console está configurado para usar um formato Espacial (como Windows Sonic para Fones de Ouvido) provavelmente gerará esses eventos.

* Uma invalidação de dispositivo de áudio pode ocorrer a qualquer momento depois que o [IMMDevice](https://learn.microsoft.com/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-immdevice) é obtido da [API MMDevice](https://learn.microsoft.com/windows/desktop/coreaudio/mmdevice-api). Todas as chamadas, incluindo [IMMDevice::Activate](https://learn.microsoft.com/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevice-activate), podem retornar um erro de invalidação. Sempre que o jogo encontrar um erro de invalidação, ele deverá recriar seus fluxos de áudio obtendo primeiro um novo IMMDevice por meio de [IMMDeviceEnumerator](https://learn.microsoft.com/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevice-activate).

## Alterações na API

\| Plataforma de destino| API do XBOX One Software Development Kit| API substituta do Microsoft Game Development Kit (GDK)| Descrição|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| PC e XBOX| ActivateAudioInterfaceAsync e IActivateAudioInterfaceAsync| [IMMDevice::Activate()](https://learn.microsoft.com/windows/desktop/api/mmdeviceapi/nf-mmdeviceapi-immdevice-activate)| Para ativar um cliente de áudio de forma síncrona a partir de um [IMMDevice](https://learn.microsoft.com/windows/desktop/api/Mmdeviceapi/nn-mmdeviceapi-immdevice). Use a [API MMDevice](https://learn.microsoft.com/windows/desktop/coreaudio/mmdevice-api) para enumerar pontos de extremidade.|
\| PC e XBOX| IAudioClient2::RegisterXBoxVolumeNotificationCallback e IAudioClient2::UnregisterXBoxVolumeNotificationCallback| [API AudioStateMonitor](/pt-BR/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor)| Essas APIs se destinavam anteriormente a alertar os títulos de que os fluxos de mídia do jogo foram atenuados. A nova maneira de fazer isso é usando a [API AudioStateMonitor](/pt-BR/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor).|
\| PC e XBOX| ExcludeFromGameDVRCapture| Não aplicável| Ao criar um [AudioClient](https://learn.microsoft.com/windows/desktop/api/audioclient/nf-audioclient-iaudioclient-initialize), use AUDCLNT\_STREAMFLAGS\_EXCLUDE\_FROM\_GAMEDVR\_CAPTURE como uma constante de StreamFlags. Inclua XAUDIO2XBOX.H.|
\| PC e XBOX| IMMGameDVRDeviceCreator| Não aplicável| Preterido.|
\| XBOX| IMMXBoxDevice| Não aplicável| Preterido.|
\| PC e XBOX| GetPnpId| Não aplicável| Preterido.|
\| XBOX| IMMXboxDeviceEnumerator| [IAudioClient::GetMixFormat](https://learn.microsoft.com/windows/desktop/api/audioclient/nf-audioclient-iaudioclient-getmixformat)| |
\| XBOX| GetHdAudioChannelCounts, RegisterChannelCountNotificationCallback e UnregisterChannelCountNotificationCallback| [IAudioClient::GetMixFormat](https://learn.microsoft.com/windows/desktop/api/audioclient/nf-audioclient-iaudioclient-getmixformat)| Se o formato do ponto de extremidade mudar, seus fluxos serão invalidados. A próxima chamada para [IAudioClient::GetMixFormat](https://learn.microsoft.com/windows/desktop/api/audioclient/nf-audioclient-iaudioclient-getmixformat) retornará a contagem de canais apropriada para o ponto de extremidade.|
\| XBOX| DisableBitStreamOut e RestoreBitstreamOut| Não aplicável| Preterido.|
\| PC e XBOX| EnableSpatialAudio| Não aplicável| A chamada não é mais necessária para usar o Som Espacial.|
\| PC e XBOX| SetWasapiThreadAffinityMask| Não aplicável| Preterido. Os jogos que usam o XAudio2 podem optar por ajustar o parâmetro *XAudio2Processor* com [XAudio2CreateWithSharedContexts](/pt-BR/reference/audio/xaudio2xbox/functions/xaudio2createwithsharedcontexts) para especificar em qual processador o XAudio2 é executado.|

## Documentação de referência da API

* [AudioStateMonitor (conteúdo da API)](/pt-BR/reference/audio/audiostatemonitor/audiostatemonitor_members)
* [XAudio2Xbox (conteúdo da API)](/pt-BR/reference/audio/xaudio2xbox/xaudio2xbox_members)
  * Funções
    * [XAudio2CreateWithSharedContexts](/pt-BR/reference/audio/xaudio2xbox/functions/xaudio2createwithsharedcontexts)

## Confira também

[Lista de exemplos do Microsoft Game Development Kit](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/development-downloads/gdk-samples-list)


## Related topics

- [Requisitos do XBOX para jogos do XBOX](/pt-BR/publishing/certification/xbox-requirements.md)
- [XR-015 Gerenciamento das comunicações do jogador](/pt-BR/publishing/certification/xr/xr-015.md)
- [XR-052 Estado do usuário e local de salvamento do título, roaming e dependências](/pt-BR/publishing/certification/xr/xr-052.md)
- [XR-003 Qualidade do título para envio](/pt-BR/publishing/certification/xr/xr-003.md)
- [Visão geral do XBOX Series X|S](/pt-BR/paths/series-xs/overview.md)