WASAPI

WASAPI Overview

The Windows Audio Session API (WASAPI) enables client applications to manage the flow of audio data between the application and an audio endpoint device.

The header files Audioclient.h defines the WASAPI interfaces. Only a subset of the interfaces available on Windows are implemented for the Xbox One Game OS.

In Windows, every audio stream is a member of an audio session. However, for the Xbox One Game OS there are no sessions.

The audio engine is the user-mode audio component through which applications share access to an audio endpoint device. The audio engine transports audio data between an endpoint buffer and an endpoint device. To play an audio stream through a rendering endpoint device, an application periodically writes audio data to a rendering endpoint buffer. The audio engine mixes the streams from the various applications. To record an audio stream from a capture endpoint device, an application periodically reads audio data from a capture endpoint buffer.

WASAPI consists of several interfaces. The most important of these is the IAudioClient interface. To access the WASAPI interfaces, a client first obtains a reference to the IAudioClient interface of an audio endpoint device by calling the IMMDevice::Activate method with parameter iid set to REFIID IID_IAudioClient. The client calls the IAudioClient::Initialize method to initialize a stream on an endpoint device. After initializing a stream, the client can obtain references to the other WASAPI interfaces by calling the IAudioClient::GetService method.

Note You will receive an AUDCLNT_E_DEVICE_IN_USE error when attempting to run Activate on a capture device unless your manifest includes the capabilities “kinectAudio” and “kinectGamechat”. This is required for all audio capture devices, including the Kinect.

Many of the methods in WASAPI return error code AUDCLNT_E_DEVICE_INVALIDATED if the audio endpoint device that a client application is using becomes invalid. Frequently, the application can recover from this error. For more information, see the Windows article Recovering from an Invalid-Device= Error.

Titles can specify thread affinity for WASAPI. See SetWasapiThreadAffinityMask (declared in mmdeviceapi.h). XAudio2 will implicitly set the mask to match its own (though a title can override by calling SetWasapiThreadAffinityMask after creating an XAudio2 instance).

Default Xbox One Endpoints

The default endpoint for rendering is the eight channel virtual HdAudio endpoint. This virtual endpoint does an automatic downmix and multicast render to both HDMI and SPDIF.

The default WASAPI capture device is the Kinect sensor.

Endpoint strings

On Xbox One, the system generates endpoint ID strings to identify the audio endpoint devices in the system. An endpoint ID string is a null-terminated wide-character string. The endpoint ID string for a particular audio endpoint device uniquely identifies the device among all audio endpoint devices in the system.

In order to get the endpoint for use with the WASAPI API set, use the GetDefaultAudioEndpoint method.

The format of an ID string is {PnPId}.{GUID}.

If a system contains two or more identical audio adapter devices, the corresponding audio endpoint devices will have identical friendly names, but each endpoint device will have a unique endpoint ID string.

After obtaining an IMMDevice interface instance for an audio endpoint device, a client can call the IMMDevice::GetId method to obtain the endpoint ID string for the device. A client can use the endpoint ID string to create an instance of the audio endpoint device at a later time or in a different process by calling the IMMDeviceEnumerator::GetDevice method.

A client can arrange to receive a notification when the status of any audio endpoint device changes. To receive notifications, the client implements an IMMNotificationClient interface and registers that interface with the MMDevice API. When the status of an endpoint device changes, the MMDevice API calls the appropriate method defined by the client’s EDataFlow value. One of the input parameters to the method is the endpoint ID string that identifies the endpoint device whose status has changed.

The lifetime of an endpoint ID string is tied to the device installation. The endpoint ID string of a device changes if the user upgrades the device driver, or if the user uninstalls the device, and installs it again. However, the endpoint ID string remains unchanged across system restarts, and the endpoint ID string of a USB audio device remains unchanged if the user unplugs the device and plugs it back in.

Note

The user manager has its own independent definition of an audio ID.

Audio Interface Id is the term used by the WinRT MediaDevice to define an endpoint string. The user manager requires an ID that could reference the same device in both the Game OS and the System OS. This ID is called the Audio Device Id (refer to IUser.AudioDevices Property).

Changing HDMI and SPDIF Output

Two interfaces, IMMXboxNotificationClient and IMMXboxDeviceEnumerator, specific to Xbox One handle the situation where HDMI or SPDIF outputs are changed, for example unplugging the output to a TV and switching the output to a 7.1 surround sound A/V device.

Register for a state change callback using RegisterChannelCountNotificationCallback.

Developers may choose to alter their titles audio behavior based on these reported values (for example, to create a stereo-optimized mix) though note that there is no programmatic way to determine whether the user is listening through the optical or HDMI outputs. In general, titles should either target a consistent 7.1 mix (allowing the system to downmix as appropriate), or the highest reported channel count of the two audio outputs.

For more information on channels and volume metering, refer to the white paper:

WASAPI Interfaces

Interface Description
IAudioCaptureClient Enables a client to read input data from a capture endpoint buffer.
IAudioClient Enables a client to create and initialize an audio stream between an audio application and the audio engine or the hardware buffer of an audio endpoint device.
IAudioClient2 The IAudioClient2 interface is derived from the IAudioClient interface, with a set of additional methods that enable a WASAPI audio client to do the following: opt in for offloading, query stream properties, and get information from the hardware that handles offloading.
IAudioClock Enables a client to monitor a stream’s data rate and the current position in the stream.
IAudioRenderClient Enables a client to write output data to a rendering endpoint buffer.
IMMDevice Encapsulates the generic features of a multimedia device resource. In the current implementation of the MMDevice API, the only type of device resource that an IMMDevice interface can represent is an audio endpoint device.
IMMDeviceCollection Represents a collection of multimedia device resources.
IMMDeviceEnumerator Provides methods for enumerating multimedia device resources.
IMMEndpoint Represents an audio endpoint device.
IMMGameDVRDeviceCreator Provides a single method to return the DVR device endpoint.
IMMNotificationClient Provides notifications when an audio endpoint device is added or removed, when the state or properties of an endpoint device change, or when there is a change in the default role assigned to an endpoint device.
IMMXboxDevice Provides methods for identifying 3rd party audio devices on Xbox One.
IMMXboxDeviceEnumerator Enumerates the HDMI and SPDIF devices currently attached to the Xbox One.
IMMXboxNotificationClient Provides a method for handling a change in the HDMI or SPDIF modes.

Sample code

Refer to the source code for the SimpleWASAPIPlaySound sample, which demonstrates how to play an in-memory WAV file using WASAPI.

This Xbox One sample can be downloaded from XGD Samples.