Table of Contents

Class AudioClient

Namespace
NAudio.CoreAudioApi
Assembly
NAudio.Wasapi.dll

Windows CoreAudio AudioClient. Wraps IAudioClient, IAudioClient2, and IAudioClient3.

public class AudioClient : IDisposable
Inheritance
AudioClient
Implements
Inherited Members

Properties

AudioCaptureClient

Gets the AudioCaptureClient service

public AudioCaptureClient AudioCaptureClient { get; }

Property Value

AudioCaptureClient

AudioClockClient

Gets the AudioClockClient service

public AudioClockClient AudioClockClient { get; }

Property Value

AudioClockClient

AudioRenderClient

Gets the AudioRenderClient service

public AudioRenderClient AudioRenderClient { get; }

Property Value

AudioRenderClient

AudioStreamVolume

Returns the AudioStreamVolume service for this AudioClient.

public AudioStreamVolume AudioStreamVolume { get; }

Property Value

AudioStreamVolume

Remarks

This returns the AudioStreamVolume object ONLY for shared audio streams.

Exceptions

InvalidOperationException

This is thrown when an exclusive audio stream is being used.

BufferSize

Retrieves the size (maximum capacity) of the audio buffer associated with the endpoint. (must initialize first)

public int BufferSize { get; }

Property Value

int

CurrentPadding

Retrieves the number of frames of padding in the endpoint buffer (must initialize first)

public int CurrentPadding { get; }

Property Value

int

DefaultDevicePeriod

Retrieves the length of the periodic interval separating successive processing passes by the audio engine on the data in the endpoint buffer. (can be called before initialize)

public long DefaultDevicePeriod { get; }

Property Value

long

MinimumDevicePeriod

Gets the minimum device period (can be called before initialize)

public long MinimumDevicePeriod { get; }

Property Value

long

MixFormat

Retrieves the stream format that the audio engine uses for its internal processing of shared-mode streams. Can be called before initialize

public WaveFormat MixFormat { get; }

Property Value

WaveFormat

SimpleAudioVolume

Returns the SimpleAudioVolume service for this AudioClient — per-session volume and mute, as shown for the application in the Windows volume mixer. Unlike MMDevice-derived session volume, this is obtained from the client itself, so it works for clients activated without a concrete endpoint (e.g. automatic stream routing).

public SimpleAudioVolume SimpleAudioVolume { get; }

Property Value

SimpleAudioVolume

StreamLatency

Retrieves the maximum latency for the current stream and can be called any time after the stream has been initialized.

public long StreamLatency { get; }

Property Value

long

SupportsAudioClient2

Whether this audio client supports IAudioClient2 features (Windows 8+)

public bool SupportsAudioClient2 { get; }

Property Value

bool

SupportsAudioClient3

Whether this audio client supports IAudioClient3 low-latency features (Windows 10 1607+)

public bool SupportsAudioClient3 { get; }

Property Value

bool

Methods

ActivateAsync(string, AudioClientProperties?)

Activate Async

public static Task<AudioClient> ActivateAsync(string deviceInterfacePath, AudioClientProperties? audioClientProperties)

Parameters

deviceInterfacePath string
audioClientProperties AudioClientProperties?

Returns

Task<AudioClient>

ActivateDefaultDeviceAsync(DataFlow)

Activates an AudioClient that follows the current default endpoint with automatic stream routing: when the user changes (or unplugs) the default device, Windows seamlessly transfers the stream to the new default device with no application code. Requires Windows 10 version 1607 or later.

public static Task<AudioClient> ActivateDefaultDeviceAsync(DataFlow dataFlow)

Parameters

dataFlow DataFlow

Whether to follow the default render or capture device.

Returns

Task<AudioClient>

Remarks

This activates the special DEVINTERFACE_AUDIO_RENDER / DEVINTERFACE_AUDIO_CAPTURE virtual endpoint via ActivateAudioInterfaceAsync. Unlike the process-loopback virtual device, the returned client is backed by the current default endpoint and behaves like a normal shared-mode client, including MixFormat.

ActivateProcessLoopbackAsync(uint, ProcessLoopbackMode)

Activates an AudioClient for process-specific loopback capture, capturing the audio rendered by the specified process (and optionally its child processes). Requires Windows 10 version 2004 (build 19041) or later.

public static Task<AudioClient> ActivateProcessLoopbackAsync(uint processId, ProcessLoopbackMode mode = ProcessLoopbackMode.IncludeTargetProcessTree)

Parameters

processId uint

The target process id.

mode ProcessLoopbackMode

Whether to include or exclude the target process tree.

Returns

Task<AudioClient>

Dispose()

Dispose

public void Dispose()

GetSharedModeEnginePeriod(WaveFormat)

Returns the range of periodicities supported by the engine for the specified stream format. Requires Windows 10 1607 or later (IAudioClient3).

public AudioClientPeriodInfo GetSharedModeEnginePeriod(WaveFormat format)

Parameters

format WaveFormat

Returns

AudioClientPeriodInfo

Initialize(AudioClientShareMode, AudioClientStreamFlags, long, long, WaveFormat, Guid)

Initializes the Audio Client

public void Initialize(AudioClientShareMode shareMode, AudioClientStreamFlags streamFlags, long bufferDuration, long periodicity, WaveFormat waveFormat, Guid audioSessionGuid)

Parameters

shareMode AudioClientShareMode

Share Mode

streamFlags AudioClientStreamFlags

Stream Flags

bufferDuration long

Buffer Duration

periodicity long

Periodicity

waveFormat WaveFormat

Wave Format

audioSessionGuid Guid

Audio Session GUID (can be null)

InitializeSharedAudioStream(AudioClientStreamFlags, uint, WaveFormat, Guid)

Initializes a shared audio stream with the specified periodicity. Requires Windows 10 1607 or later (IAudioClient3).

public void InitializeSharedAudioStream(AudioClientStreamFlags streamFlags, uint periodInFrames, WaveFormat waveFormat, Guid audioSessionGuid)

Parameters

streamFlags AudioClientStreamFlags
periodInFrames uint
waveFormat WaveFormat
audioSessionGuid Guid

IsFormatSupported(AudioClientShareMode, WaveFormat)

Determines whether if the specified output format is supported

public bool IsFormatSupported(AudioClientShareMode shareMode, WaveFormat desiredFormat)

Parameters

shareMode AudioClientShareMode

The share mode.

desiredFormat WaveFormat

The desired format.

Returns

bool

True if the format is supported

IsFormatSupported(AudioClientShareMode, WaveFormat, out WaveFormat)

Determines if the specified output format is supported in shared mode

public bool IsFormatSupported(AudioClientShareMode shareMode, WaveFormat desiredFormat, out WaveFormat closestMatchFormat)

Parameters

shareMode AudioClientShareMode

Share Mode

desiredFormat WaveFormat

Desired Format

closestMatchFormat WaveFormat

The closest supported format, or null if there is none. Shared mode only — always null in exclusive mode.

Returns

bool

True if the format is supported

Reset()

Resets the audio stream Reset is a control method that the client calls to reset a stopped audio stream. Resetting the stream flushes all pending data and resets the audio clock stream position to 0. This method fails if it is called on a stream that is not stopped

public void Reset()

SetClientProperties(AudioStreamCategory)

Sets the audio stream category for this client via IAudioClient2. Must be called before Initialize(AudioClientShareMode, AudioClientStreamFlags, long, long, WaveFormat, Guid). The category influences stream routing, ducking and — for capture streams opened as Communications — which audio processing (such as acoustic echo cancellation) the system applies.

public void SetClientProperties(AudioStreamCategory category)

Parameters

category AudioStreamCategory

The audio stream category to request.

Exceptions

InvalidOperationException

Thrown when the underlying device does not support IAudioClient2 (for example the process-loopback virtual device).

SetClientProperties(AudioStreamCategory, AudioClientStreamOptions)

Sets the audio stream category and stream options for this client via IAudioClient2. Must be called before Initialize(AudioClientShareMode, AudioClientStreamFlags, long, long, WaveFormat, Guid). Use Raw to open a 'raw' stream that bypasses signal processing (audio enhancements / APO effects) applied by the system, leaving only endpoint-specific always-on processing in the APO, driver, and hardware.

public void SetClientProperties(AudioStreamCategory category, AudioClientStreamOptions options)

Parameters

category AudioStreamCategory

The audio stream category to request.

options AudioClientStreamOptions

The stream options to request (e.g. Raw).

Exceptions

InvalidOperationException

Thrown when the underlying device does not support IAudioClient2 (for example the process-loopback virtual device).

SetEventHandle(nint)

Set the Event Handle for buffer synchro.

public void SetEventHandle(nint eventWaitHandle)

Parameters

eventWaitHandle nint

The Wait Handle to setup

Start()

Starts the audio stream

public void Start()

Stop()

Stops the audio stream.

public void Stop()

TryGetAcousticEchoCancellationControl()

Attempts to get the acoustic echo cancellation (AEC) control for this capture stream, which lets you set the render endpoint used as the reference stream for echo cancellation.

public AcousticEchoCancellationControl TryGetAcousticEchoCancellationControl()

Returns

AcousticEchoCancellationControl

The AcousticEchoCancellationControl, or null if the endpoint does not support controlling the AEC reference endpoint (GetService returns E_NOINTERFACE).

Remarks

The audio client must be initialized before calling this. AEC itself is performed by an audio processing object in the capture pipeline; this control only chooses the loopback reference endpoint. It is available only on Windows 11 build 22621 or later, and only when the capture endpoint's AEC effect supports controlling the reference endpoint.

Edit this page