IAudioClient::Initialize Method

The Initialize method initializes the audio stream.

Syntax

public:
HRESULT Initialize(
         AUDCLNT_SHAREMODE ShareMode,
         DWORD StreamFlags,
         REFERENCE_TIME hnsBufferDuration,
         REFERENCE_TIME hnsPeriodicity,
         const WAVEFORMATEX *pFormat,
         LPCGUID AudioSessionGuid
)  

Parameters

ShareMode
Type: AUDCLNT_SHAREMODE 

[in]

The sharing mode for the connection. Set this to AUDCLNT_SHAREMODE_SHARED. AUDCLNT_SHAREMODE_EXCLUSIVE is not supported on Xbox One.

StreamFlags
Type: DWORD 

[in]

Flags to control creation of the stream. The client should set this parameter to 0 or to the bitwise OR of one or more of the following flags.

hnsBufferDuration
Type: REFERENCE_TIME 

[in]

The buffer capacity as a time value. This parameter is of type REFERENCE_TIME and is expressed in 100-nanosecond units. This parameter contains the buffer size that the caller requests for the buffer that the audio application will share with the audio engine. If the call succeeds, the method allocates a buffer that is a least this large. For more information about REFERENCE_TIME, see the Windows SDK documentation. For more information about buffering requirements, see Remarks.

hnsPeriodicity
Type: REFERENCE_TIME 

[in]

The device period. This is the scheduling period for successive buffer accesses by the audio endpoint device (for example, a value of 500000 specifies that the device will read the buffer every 50 ms). In shared mode (which is the only mode available on Xbox One), always set this parameter to 0, which sets the device period to its default value. To obtain the default device period, call the IAudioClient::GetDevicePeriod method.

pFormat
Type: WAVEFORMATEX *

[in]

Pointer to a format descriptor. This parameter must point to a valid format descriptor of type WAVEFORMATEX (or WAVEFORMATEXTENSIBLE). For more information, see Remarks.

AudioSessionGuid
Type: LPCGUID 

[in, optional]

Pointer to a session GUID. This parameter points to a GUID value that identifies the audio session that the stream belongs to. If the GUID identifies a session that has been previously opened, the method adds the stream to that session. If the GUID does not identify an existing session, the method opens a new session and adds the stream to that session. The stream remains a member of the same session for its lifetime. Setting this parameter to NULL is equivalent to passing a pointer to a GUID_NULL value.

Return value

Type: HRESULT 

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Return codes

Refer to WASAPI error codes.

Remarks

After activating an IAudioClient interface on an audio endpoint device, the client must successfully call Initialize once and only once to initialize the audio stream between the client and the device. In the Initialize call, the client specifies the audio data format, the buffer size, and audio session for the stream.

The first use of IAudioClient to access the audio device should be on the STA thread. Calls from an MTA thread may result in undefined behavior.

If a stream is initialized to be event driven one of the stream flags that are set includes AUDCLNT_STREAMFLAGS_EVENTCALLBACK. For such a stream, the associated application must also obtain a handle by making a call to IAudioClient::SetEventHandle. When it is time to retire the stream, the audio engine can then use the handle to release the stream objects. Failure to call IAudioClient::SetEventHandle before releasing the stream objects can cause a delay of several seconds (a time-out period) while the audio engine waits for an available handle. After the time-out period expires, the audio engine then releases the stream objects.

An IAudioClient object supports exactly one connection to the audio engine or audio hardware. This connection lasts for the lifetime of the IAudioClient object.

The client should call the following methods only after calling Initialize:

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

The following methods do not require that Initialize be called first:

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

These methods can be called any time after activating the IAudioClient interface.

Before calling Initialize to set up a shared-mode connection, the client can call the IAudioClient::IsFormatSupported method to discover whether the audio engine or audio endpoint device supports a particular format in that mode. Before opening a shared-mode connection, the client can obtain the audio engine’s mix format by calling the IAudioClient::GetMixFormat method.

The endpoint buffer that is shared between the client and audio engine must be large enough to prevent glitches from occurring in the audio stream between processing passes by the client and audio engine. For a rendering endpoint, the client thread periodically writes data to the buffer, and the audio engine thread periodically reads data from the buffer. For a capture endpoint, the engine thread periodically writes to the buffer, and the client thread periodically reads from the buffer. In either case, if the periods of the client thread and engine thread are not equal, the buffer must be large enough to accommodate the longer of the two periods without allowing glitches to occur.

The client specifies a buffer size through the hnsBufferDuration parameter. The client is responsible for requesting a buffer that is large enough to ensure that glitches cannot occur between the periodic processing passes that it performs on the buffer. Similarly, the Initialize method ensures that the buffer is never smaller than the minimum buffer size needed to ensure that glitches do not occur between the periodic processing passes that the engine thread performs on the buffer. If the client requests a buffer size that is smaller than the audio engine’s minimum required buffer size, the method sets the buffer size to this minimum buffer size rather than to the buffer size requested by the client.

If the client requests a buffer size (through the hnsBufferDuration parameter) that is not an integral number of audio frames, the method rounds up the requested buffer size to the next integral number of frames.

Following the Initialize call, the client should call the IAudioClient::GetBufferSize method to get the precise size of the endpoint buffer. During each processing pass, the client will need the actual buffer size to calculate how much data to transfer to or from the buffer. The client calls the IAudioClient::GetCurrentPadding method to determine how much of the data in the buffer is currently available for processing.

To achieve the minimum stream latency between the client application and audio endpoint device, the client thread should run at the same period as the audio engine thread. The period of the engine thread is fixed and cannot be controlled by the client. Making the client’s period smaller than the engine’s period unnecessarily increases the client thread’s load on the processor without improving latency or decreasing the buffer size. To determine the period of the engine thread, the client can call the IAudioClient::GetDevicePeriod method. To set the buffer to the minimum size required by the engine thread, the client should call Initialize with the hnsBufferDuration parameter set to 0. Following the Initialize call, the client can get the size of the resulting buffer by calling IAudioClient::GetBufferSize.

A client has the option of requesting a buffer size that is larger than what is strictly necessary to make timing glitches rare or nonexistent. Increasing the buffer size does not necessarily increase the stream latency. For a rendering stream, the latency through the buffer is determined solely by the separation between the client’s write pointer and the engine’s read pointer. For a capture stream, the latency through the buffer is determined solely by the separation between the engine’s write pointer and the client’s read pointer.

The loopback flag (AUDCLNT_STREAMFLAGS_LOOPBACK) enables audio loopback. A client can enable audio loopback only on a rendering endpoint with a shared-mode stream. Audio loopback is provided primarily to support acoustic echo cancellation (AEC).

An AEC client requires both a rendering endpoint and the ability to capture the output stream from the audio engine. The engine’s output stream is the global mix that the audio device plays through the speakers. If audio loopback is enabled, a client can open a capture buffer for the global audio mix by calling the IAudioClient::GetService method to obtain an IAudioCaptureClient interface on the rendering stream object. If audio loopback is not enabled, then an attempt to open a capture buffer on a rendering stream will fail. The loopback data in the capture buffer is in the device format, which the client can obtain by querying the device’s PKEY_AudioEngine_DeviceFormat property.

A pull-mode capture client does not receive any events when a stream is initialized with event-driven buffering (AUDCLNT_STREAMFLAGS_EVENTCALLBACK) and is loopback-enabled (AUDCLNT_STREAMFLAGS_LOOPBACK). If the stream is opened with this configuration, the Initialize call succeeds, but relevant events are not raised to notify the capture client each time a buffer becomes ready for processing. To work around this, initialize a render stream in event-driven mode. Each time the client receives an event for the render stream, it must signal the capture client to run the capture thread that reads the next set of samples from the capture endpoint buffer.

For more information about audio loopback, see Loopback Recording.

The AUDCLNT_STREAMFLAGS_EVENTCALLBACK flag indicates that processing of the audio buffer by the client will be event driven. WASAPI supports event-driven buffering to enable low-latency processing of shared-mode streams.

To enable event-driven buffering, the client must provide an event handle to the system. Following the Initialize call and before calling the IAudioClient::Start method to start the stream, the client must call the IAudioClient::SetEventHandle method to set the event handle. While the stream is running, the system periodically signals the event to indicate to the client that audio data is available for processing. Between processing passes, the client thread waits on the event handle by calling a synchronization function such as WaitForSingleObject. For more information about synchronization functions, see the Windows SDK documentation.

For a shared-mode stream that uses event-driven buffering, the caller must set both hnsPeriodicity and hnsBufferDuration to 0. The Initialize method determines how large a buffer to allocate based on the scheduling period of the audio engine. Although the client’s buffer processing thread is event driven, the basic buffer management process, as described previously, is unaltered. Each time the thread awakens, it should call IAudioClient::GetCurrentPadding to determine how much data to write to a rendering buffer or read from a capture buffer. A shared-mode stream requires a single buffer.

As explained in Audio Sessions, the default behavior for a session that contains rendering streams is that its volume and mute settings persist across system restarts. The AUDCLNT_STREAMFLAGS_NOPERSIST flag is not supported on Xbox One.

Only a session that connects to a rendering endpoint device can have persistent volume and mute settings. The first stream to be added to the session determines whether the session’s settings are persistent. Thus if AUDCLNT_STREAMFLAGS_LOOPBACK flag is set during initialization of the first stream, the session’s settings are not persistent. Otherwise, they are persistent. Their persistence is unaffected by additional streams that might be subsequently added or removed during the lifetime of the session object.

After a call to Initialize has successfully initialized an IAudioClient interface instance, a subsequent Initialize call to initialize the same interface instance will fail and return error code E_ALREADY_INITIALIZED.

If the initial call to Initialize fails, subsequent Initialize calls might fail and return error code E_ALREADY_INITIALIZED, even though the interface has not been initialized. If this occurs, release the IAudioClient interface and obtain a new IAudioClient interface from the MMDevice API before calling Initialize again.

For code examples that call the Initialize method, see the following topics:

• Rendering a Stream
• Capturing a Stream

Requirements

Header: Declared in audioclient.h.

Library: Use mmdevapi.lib.

See also

IAudioClient

IAudioClient Members