Stream Management

Stream Management

After enumerating the audio endpoint devices in the system and identifying a suitable rendering or capture device, the next task for an audio client application is to open a connection with the endpoint device and to manage the flow of audio data over that connection. WASAPI enables clients to create and manage audio streams.

WASAPI implements several interfaces to provide stream-management services to audio clients. The primary interface is IAudioClient. A client obtains the IAudioClient interface for an audio endpoint device by calling the IMMDevice::Activate method (with parameter iid set to REFIID IID_IAudioClient) on the endpoint object.

The client calls the methods in the IAudioClient interface to do the following:

• Discover which audio formats the endpoint device supports.
• Get the endpoint buffer size.
• Get the stream format and latency.
• Start, stop, and reset the stream that flows through the endpoint device.
• Access additional audio services.

To create a stream, a client calls the IAudioClient::Initialize method. Through this method, the client specifies the data format for the stream, the size of the endpoint buffer, and whether the stream operates in shared or exclusive mode.

The remaining methods in the IAudioClient interface fall into two groups:

• Methods that can be called only after the stream has been opened by IAudioClient::Initialize.
• Methods that can be called at any time before or after the Initialize call.

The following methods can be called only after the call to IAudioClient::Initialize:

• IAudioClient::GetBufferSize
• IAudioClient::GetCurrentPadding
• IAudioClient::GetService
• IAudioClient::GetStreamLatency
• IAudioClient::Reset
• IAudioClient::Start
• IAudioClient::Stop

The following methods can be called before or after the IAudioClient::Initialize call:

• IAudioClient::GetDevicePeriod
• IAudioClient::GetMixFormat
• IAudioClient::IsFormatSupported

To access the additional audio client services, the client calls the IAudioClient::GetService method. Through this method, the client can obtain references to the following interfaces:

• IAudioRenderClient

  Writes rendering data to an audio-rendering endpoint buffer.

• IAudioCaptureClient

  Reads captured data from an audio-capture endpoint buffer.

• IAudioSessionControl

  Communicates with the audio session manager to configure and manage the audio session that is associated with the stream.

• ISimpleAudioVolume

  Controls the volume level of the audio session that is associated with the stream.

• IChannelAudioVolume

  Controls the volume levels of the individual channels in the audio session that is associated with the stream.

• IAudioClock

  Monitors the stream data rate and stream position.

In addition, WASAPI clients that require notification of session-related events should implement the following interface:

• IAudioSessionEvents

  To receive event notifications, the client passes a pointer to its IAudioSessionEvents interface to the IAudioSessionControl::RegisterAudioSessionNotification method as a call parameter.

Finally, a client might use a higher-level API to create an audio stream, but also require access to the session controls and volume controls for the session that contains the stream. A higher-level API typically does not provide this access. The client can obtain the controls for a particular session through the IAudioSessionManager interface. This interface enables the client to obtain the IAudioSessionControl and ISimpleAudioVolume interfaces for a session without requiring the client to use the IAudioClient interface to create a stream and to assign the stream to the session. A client obtains the IAudioSessionManager interface for an audio endpoint device by calling the IMMDevice::Activate method (with parameter iid set to REFIID IID_IAudioSessionManager) on the endpoint object.

The IAudioSessionControl, IAudioSessionEvents, and IAudioSessionManager interfaces are defined in header file Audiopolicy.h. All other WASAPI interfaces are defined in header file Audioclient.h.

The following sections describe how to use WASAPI to manage audio streams:

• Rendering a Stream
• Capturing a Stream
• Loopback Recording
• Exclusive-Mode Streams
• Recovering from an Invalid-Device Error