Guidelines
- To help ensure that users have the best gaming experience possible, determine if the endpoint supports multichannel audio. First, call IAudioClient::IsFormatSupported. If the preferred format isn’t supported, fall back to rendering to the mix format, IAudioClient::GetMixFormat.
- Instead of handling only 7.1 endpoints, titles must also be able to handle 2.0, 5.1, and 7.1 endpoints natively and react in real-time if formats change through audio client invalidations. If a title doesn’t want to provide three (with respect to the channel counts) different sources of audio, it can ask the OS to perform the upmixing and downmixing for it, with the AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM streamflag on Audioclient initialize. Even if the game asks the OS to perform upmixing and downmixing, it will still receive and be required to react to audio client invalidations.
- To enumerate (render and capture) audio devices, use the MMDevice API. If rendering audio to the main HDMI endpoint only, call GetDefaultAudioEndpoint
- On XBOX, render audio from one process at a time.
- XBOX Manager remote control is designed to support audio through Windows Audio Session API (WASAPI). However, it does not support audio streaming from ISpatialAudioClient (ISAC) when Dolby/DTS home theater settings are activated.
-
Many methods associated with WASAPI may return error code AUDCLNT_E_DEVICE_INVALIDATED if the audio endpoint device that the client application is using becomes invalid. Ensure that your title is responding properly to these errors which may occur if an endpoint device is changed in any way. More information on recovering from an invalid device error with WASAPI is here. An easy way to confirm that your title handles audio device invalidation correctly is by switching to the audio settings page while your title is running and changing the channel count on the HDMI device. During an invalidation scenario, the following error codes can be returned by WASAPI:
- AUDCLNT_E_DEVICE_INVALIDATED
- AUDCLNT_E_RESOURCES_INVALIDATED
- AUDCLNT_E_UNSUPPORTED_FORMAT
- AUDCLNT_E_ENDPOINT_CREATE_FAILED
-
When Spatial Sound is used by your title you will be interacting with the ISAC APIs and they also return error codes surrounding device invalidation. For ISAC, invalidation occurs when the audio endpoint is changed or the spatial rendering mode is changed during playback. More information on recovering from an invalid device error with ISAC is here. This happens when any of the following methods returns one of the following values.
Methods:
- ISpatialAudioObjectRenderStreamBase
- ISpatialAudioObjectRenderStream
- ISpatialAudioObjectRenderStreamForMetadata
- ISpatialAudioObjectRenderStreamForHrtf
- SPTLAUDCLNT_E_DESTROYED
- AUDCLNT_E_DEVICE_INVALIDATED
- AUDCLNT_E_RESOURCES_INVALIDATED
- AUDCLNT_E_UNSUPPORTED_FORMAT
- SPTLAUDCLNT_E_INTERNAL Additionally, plugging in or unplugging a headset from the controller when the console is set up to use a Spatial format (like Windows Sonic for Headphones) will likely lead to these events.
- An audio device invalidation can occur at any time after the IMMDevice is obtained from the MMDevice API. All calls including IMMDevice::Activate can return an invalidation error. Anytime the game encounters an invalidation error, it should re-create its audio streams by first obtaining a new IMMDevice through IMMDeviceEnumerator.