Multi-media Audio Reference

The following multi-media audio classes are implemented.

Interfaces

Name	Description
IActivateAudioInterfaceAsyncOperation	Represents an asynchronous operation activating a WASAPI interface and provides a method to retrieve the results of the activation.
IActivateAudioInterfaceCompletionHandler	Provides a callback to indicate that activation of a WASAPI interface is complete.
IAudioCaptureClient	The IAudioCaptureClient interface enables a client to read input data from a capture endpoint buffer. The client obtains a reference to the IAudioCaptureClient interface on a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioCaptureClient.The methods in this interface manage the movement of data packets that contain capture data. The length of a data packet is expressed as the number of audio frames in the packet. The size of an audio frame is specified by the nBlockAlign member of the WAVEFORMATEX (or WAVEFORMATEXTENSIBLE structure that the client obtains by calling the IAudioClient::GetMixFormat method. The size in bytes of an audio frame equals the number of channels in the stream multiplied by the sample size per channel. For example, the frame size is four bytes for a stereo (2-channel) stream with 16-bit samples. A packet always contains an integral number of audio frames.When releasing an IAudioCaptureClient interface instance, the client must call the Release method of the instance from the same thread as the call to IAudioClient::GetService that created the object.For a code example that uses the IAudioCaptureClient interface, see Capturing a Stream.
IAudioClient	The IAudioClient interface enables a client to create and initialize an audio stream between an audio application and the audio engine. A client obtains a reference to an IAudioClient interface for an audio endpoint device by following these steps: By using one of the techniques described in IMMDevice, obtain a reference to the IMMDevice interface for an audio endpoint device. Call the IMMDevice::Activate method with parameter iid set to REFIID IID_IAudioClient or IID_IAudioClient2. The application thread that uses this interface must be initialized for COM. For more information about COM initialization, see the description of the CoInitializeEx function in the Windows SDK documentation.For code examples that use the IAudioClient interface, see the following topics: Rendering a Stream Capturing a Stream
IAudioClient2	Defines a Windows Audio Session API (WASAPI) audio client for Xbox One.
IAudioClock	The IAudioClock interface enables a client to monitor a stream's data rate and the current position in the stream. The client obtains a reference to the IAudioClock interface of a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioClock.When releasing an IAudioClock interface instance, the client must call the interface's Release method from the same thread as the call to IAudioClient::GetService that created the object.
IAudioEndpointVolume	This interface represents the volume controls on the audio stream to or from an audio endpoint device.
IAudioRenderClient	The IAudioRenderClient interface enables a client to write output data to a rendering endpoint buffer. The client obtains a reference to the IAudioRenderClient interface of a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioRenderClient.The methods in this interface manage the movement of data packets that contain audio-rendering data. The length of a data packet is expressed as the number of audio frames in the packet. The size of an audio frame is specified by the nBlockAlign member of theWAVEFORMATEX structure that the client obtains by calling the IAudioClient::GetMixFormat method. The size in bytes of an audio frame equals the number of channels in the stream multiplied by the sample size per channel. For example, the frame size is four bytes for a stereo (2-channel) stream with 16-bit samples. A packet always contains an integral number of audio frames.When releasing an IAudioRenderClient interface instance, the client must call the interface's Release method from the same thread as the call to IAudioClient::GetService that created the object.For code examples that use the IAudioRenderClient interface, see the following topic: Rendering a Stream
IAudioStreamVolume	The IAudioStreamVolume interface enables a client to control and monitor the volume levels for all of the channels in an audio stream. The client obtains a reference to the IAudioStreamVolume interface on a stream object by calling the IAudioClient::GetService method with parameter riid set to REFIID IID_IAudioStreamVolume.The effective volume level of any channel, as heard at the speakers, is controlled by clients through the methods in the IAudioStreamVolume interface.The effective volume level is a value in the range 0.0 (silence) to 1.0 (no attenuation).When releasing an IAudioStreamVolume interface instance, the client must call the interface's Release method from the same thread as the call to IAudioClient::GetService that created the object.The IAudioStreamVolume interface controls the channel volumes in a shared-mode audio stream. Xbox One does not support exclusive-mode streams.
IMMDevice	The IMMDevice interface 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 devices.A client can obtain an IMMDevice interface from one of the following methods: IMMDeviceCollection::Item IMMDeviceEnumerator::GetDefaultAudioEndpoint IMMDeviceEnumerator::GetDevice For more information, see IMMDeviceCollection Interface.After obtaining the IMMDevice interface of an audio endpoint device, a client can obtain an interface that encapsulates the endpoint-specific features of the device by calling the IMMDevice::QueryInterface method with parameter iid set to REFIID IID_IMMEndpoint. For more information, see IMMEndpoint Interface.For code examples that use the IMMDevice interface, see the Rendering a Stream topic.
IMMDeviceCollection	The IMMDeviceCollection interface represents a collection of multimedia device resources. In the current implementation, the only device resources that the MMDevice API can create collections of are audio endpoint devices. A client can obtain a reference to an IMMDeviceCollection interface instance by calling the IMMDeviceEnumerator::EnumAudioEndpoints method. This method creates a collection of endpoint objects, each of which represents an audio endpoint device in the system. Each endpoint object in the collection supports the IMMDevice and IMMEndpoint interfaces. For more information, see IMMDeviceEnumerator Interface.For a code example that uses the IMMDeviceCollection interface, see Device Properties.
IMMDeviceEnumerator	The IMMDeviceEnumerator interface provides methods for enumerating multimedia device resources. In the current implementation of the MMDevice API, the only device resources that this interface can enumerate are audio endpoint devices. A client obtains a reference to an IMMDeviceEnumerator interface by calling the CoCreateInstance function.The device resources enumerated by the methods in the IMMDeviceEnumerator interface are represented as collections of objects with IMMDevice interfaces. A collection has an IMMDeviceCollection interface. The IMMDeviceEnumerator::EnumAudioEndpoints method creates a device collection.To obtain a pointer to the IMMDevice interface of an item in a device collection, the client calls the IMMDeviceCollection::Item method.For code examples that use the IMMDeviceEnumerator interface, see the following topics: Device Properties Rendering a Stream
IMMEndpoint	The IMMEndpoint interface represents an audio endpoint devices. A client obtains a reference to an IMMEndpoint interface instance by following these steps: By using one of the techniques described in IMMDevice Interface, obtain a reference to the IMMDevice interface of an audio endpoint device. Call the IMMDevice::QueryInterface method with parameter iid set to REFIID IID_IMMEndpoint.
IMMGameDVRDeviceCreator	This interface provides a single method to return the DVR device endpoint.
IMMNotificationClient	The IMMNotificationClient interface provides notifications when an audio endpoint devices 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. Unlike the other interfaces in this section, which are implemented by the MMDevice API system component, an MMDevice API client implements the IMMNotificationClient interface. To receive notifications, the client passes a pointer to its IMMNotificationClient interface instance as a parameter to the IMMDeviceEnumerator::RegisterEndpointNotificationCallback method.After registering its IMMNotificationClient interface, the client receives event notifications in the form of callbacks through the methods of the interface.Each method in the IMMNotificationClient interface receives, as one of its input parameters, an endpoint ID string that identifies the audio endpoint device that is the subject of the notification. The string uniquely identifies the device with respect to all of the other audio endpoint devices in the system. The methods in the IMMNotificationClient interface implementation should treat this string as opaque. That is, none of the methods should attempt to parse the contents of the string to obtain information about the device. The reason is that the string format is undefined and might change from one implementation of the MMDevice API system module to the next.A client can use the endpoint ID string that it receives as an input parameter in a call to an IMMNotificationClient method in two ways: The client can create an instance of the device that the endpoint ID string identifies. The client does this by calling the IMMDeviceEnumerator::GetDevice method and supplying the endpoint ID string as an input parameter. The client can compare the endpoint ID string with the endpoint ID string of an existing device instance. To obtain the second endpoint ID string, the client calls the IMMDevice::GetId method of the device instance. If the two strings match, they identify the same device. In implementing the IMMNotificationClient interface, the client should observe these rules to avoid deadlocks and undefined behavior: The methods of the interface must be nonblocking. The client should never wait on a synchronization object during an event callback. To avoid dead locks, the client should never call IMMDeviceEnumerator::RegisterEndpointNotificationCallback or IMMDeviceEnumerator::UnregisterEndpointNotificationCallback in its implementation of IMMNotificationClient methods. The client should never release the final reference on an MMDevice API object during an event callback. For a code example that implements the IMMNotificationClient interface, see Device Events.
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.
IXboxVolumeNotificationClient	Defines an Xbox One client for the title to receive notifications of volume muting and unmuting when background music plays during the playing of game media.

Functions

Name	Description
ActivateAudioInterfaceAsync	Enables apps to access existing Component Object Model (COM) interfaces in the WASAPI family.
DisableBitstreamOut	Primarily used for low latency music games, DisableBitstreamOut will override settings specified by the user in the Settings App's "Display & sound" tile.
EnableSpatialAudio	This function allows titles to access Windows Sonic by enabling spatial audio clients.
RestoreBitstreamOut	Primarily used for low latency music games, RestoreBitstreamOut will revert console audio output settings that have been overridden using DisableBistreamOut.
SetWasapiThreadAffinityMask	Sets a processor affinity mask for the WASAPI client thread.

Structures

Name	Description
AudioClientProperties	The AudioClientProperties structure is used to set the parameters that describe the properties of the client's audio stream.

Enumerations

Name	Description
_AUDCLNT_BUFFERFLAGS	The _AUDCLNT_BUFFERFLAGS enumeration defines flags that indicate the status of an audio endpoint buffer.
AUDCLNT_SHAREMODE	The AUDCLNT_SHAREMODE enumeration defines constants that indicate the mode of the audio stream.
AUDIO_STREAM_CATEGORY	Audio stream endpoint categories controlling audio focus and volume attenuation (system ducking). Xbox One allows the user to play several different audio experiences at the same time. It supports both clarity and differing consumer use scenarios by providing several system ducking functions and making some behaviors customizable. Note that the behaviors are system policies that might change in future versions of the console.
AudioSessionState	The AudioSessionState enumeration defines constants that indicate the current state of an audio session.
EDataFlow	The EDataFlow enumeration defines constants that indicate the direction in which audio data flows between an audio endpoint device and an application.
EndpointFormFactor	The EndpointFormFactor enumeration defines constants that indicate the general physical attributes of an audio endpoint device.
ERole	The ERole enumeration defines constants that indicate the role that the system has assigned to an audio endpoint device.

Error codes

There are a number of WASAPI specific HRESULT error codes. Note that many are not returned by the Game OS.

In this section

WASAPI Error Codes
Lists the WASAPI specific error codes.