Class WasapiPlayerBuilder

Namespace

NAudio.Wave

Assembly

NAudio.Wasapi.dll

Fluent builder for creating a WasapiPlayer.

public class WasapiPlayerBuilder

Inheritance

object

WasapiPlayerBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

Build()

Builds the WasapiPlayer with the configured settings.

public WasapiPlayer Build()

Returns

WasapiPlayer

Exceptions

InvalidOperationException

Thrown when WithDefaultDeviceStreamRouting() was configured — automatic stream routing is activated asynchronously, so BuildAsync() must be used instead.

BuildAsync()

Builds the WasapiPlayer with the configured settings. Required when WithDefaultDeviceStreamRouting() is used, since that activation path is asynchronous; for all other configurations this simply wraps Build().

public Task<WasapiPlayer> BuildAsync()

Returns

Task<WasapiPlayer>

WithCategory(AudioStreamCategory)

Set the audio stream category, used by Windows for audio policy decisions (ducking, routing, priority). Requires IAudioClient2 (Windows 8+).

public WasapiPlayerBuilder WithCategory(AudioStreamCategory category)

Parameters

category AudioStreamCategory

Returns

WasapiPlayerBuilder

WithDefaultDeviceStreamRouting()

Follow the default render device with automatic stream routing (Windows 10 version 1607 or later). When the user changes the default playback device — or unplugs the current one — Windows seamlessly transfers playback to the new default device with no application code.

public WasapiPlayerBuilder WithDefaultDeviceStreamRouting()

Returns

WasapiPlayerBuilder

Remarks

Activation is asynchronous, so the player must be created via BuildAsync() rather than Build(). Routing is standard shared mode only: do not combine it with WithDevice(MMDevice), WithExclusiveMode(), or WithLowLatency(bool). Because there is no fixed endpoint, DeviceVolume is unavailable (use Volume/SessionVolume instead).

WithDevice(MMDevice)

Use the specified audio device for playback.

public WasapiPlayerBuilder WithDevice(MMDevice device)

Parameters

device MMDevice

Returns

WasapiPlayerBuilder

WithEventSync()

Use event-based synchronization (default). More efficient than polling.

public WasapiPlayerBuilder WithEventSync()

Returns

WasapiPlayerBuilder

WithExclusiveMode()

Use exclusive mode. The application has sole access to the audio device. Lower latency is possible but other applications cannot play audio.

public WasapiPlayerBuilder WithExclusiveMode()

Returns

WasapiPlayerBuilder

WithLatency(int)

Set the desired latency in milliseconds. Default is 200ms. In shared mode with IAudioClient3, the engine may use a lower period if WithLowLatency(bool) is also specified.

public WasapiPlayerBuilder WithLatency(int milliseconds)

Parameters

milliseconds int

Returns

WasapiPlayerBuilder

WithLowLatency(bool)

Request low-latency shared mode via IAudioClient3 if available.

public WasapiPlayerBuilder WithLowLatency(bool required = false)

Parameters

required bool

When false (the default), playback silently falls back to standard shared mode if low latency can't be honoured (e.g. the source sample rate doesn't match the engine, or IAudioClient3 isn't supported) — inspect LowLatencyActive afterwards to see what you got. When true, Init(IWaveProvider) instead throws an InvalidOperationException if low latency can't be achieved.

Returns

WasapiPlayerBuilder

WithMmcssThreadPriority(string)

Elevate the audio thread priority via MMCSS (Multimedia Class Scheduler Service). Common task names: "Pro Audio", "Audio", "Playback".

public WasapiPlayerBuilder WithMmcssThreadPriority(string taskName = "Pro Audio")

Parameters

taskName string

Returns

WasapiPlayerBuilder

WithPollingSync()

Use polling-based synchronization instead of events.

public WasapiPlayerBuilder WithPollingSync()

Returns

WasapiPlayerBuilder

WithRawMode()

Open a 'raw' audio stream that bypasses the system signal-processing pipeline — the audio enhancements / APO effects (loudness equalization, bass boost, virtual surround, downmixing, etc.) that Windows applies by default. Only endpoint-specific, always-on processing in the APO, driver and hardware remains. Use this when you need the device to receive your samples unaltered, for example to keep stereo channels isolated rather than mixed toward mono.

public WasapiPlayerBuilder WithRawMode()

Returns

WasapiPlayerBuilder

Remarks

Requires IAudioClient2 (Windows 8.1+); Init(IWaveProvider) throws InvalidOperationException if the device does not support it. Compatible with shared and exclusive mode, low latency, event/polling sync, a stream category and default-device stream routing. In exclusive mode the engine is already bypassed, so raw mode mainly affects any remaining driver/APO processing.

WithSharedMode()

Use shared mode (default). Audio is mixed with other applications.

public WasapiPlayerBuilder WithSharedMode()

Returns

WasapiPlayerBuilder