Class WasapiRecorderBuilder
Fluent builder for creating a WasapiRecorder.
public class WasapiRecorderBuilder- Inheritance
-
WasapiRecorderBuilder
- Inherited Members
Methods
Build()
Builds the WasapiRecorder with the configured settings.
public WasapiRecorder Build()Returns
Exceptions
- InvalidOperationException
Thrown when WithProcessLoopback(uint, ProcessLoopbackMode) was configured — process loopback is activated asynchronously, so BuildAsync() must be used instead.
BuildAsync()
Builds the WasapiRecorder with the configured settings. Required when WithProcessLoopback(uint, ProcessLoopbackMode) is used, since that activation path is asynchronous; for all other configurations this simply wraps Build().
public Task<WasapiRecorder> BuildAsync()Returns
WithBufferLength(int)
Set the internal buffer length in milliseconds. Default is 100ms. Lower values reduce latency but increase CPU usage.
public WasapiRecorderBuilder WithBufferLength(int milliseconds)Parameters
millisecondsint
Returns
WithCommunicationsMode()
Opens the capture stream in the communications signal-processing mode (Communications). This requests the system's communications audio pipeline — acoustic echo cancellation, noise suppression and automatic gain control — where the endpoint and OS provide it, and is what makes the WithEchoCancellationReferenceEndpoint(MMDevice) control available on most devices.
public WasapiRecorderBuilder WithCommunicationsMode()Returns
Remarks
Requires IAudioClient2 (Windows 8+); it is not applied to process-loopback capture. The exact effects applied depend on the capture endpoint and the installed audio processing objects.
WithDefaultDeviceStreamRouting()
Follow the default capture device with automatic stream routing (Windows 10 version 1607 or later). When the user changes the default recording device — or unplugs the current one — Windows seamlessly transfers capture to the new default device with no application code.
public WasapiRecorderBuilder WithDefaultDeviceStreamRouting()Returns
Remarks
Activation is asynchronous, so the recorder must be created via BuildAsync() rather than Build(). Routing is standard shared mode only: do not combine it with WithDevice(MMDevice), WithExclusiveMode(), WithLowLatency(bool), WithLoopbackCapture(), or WithProcessLoopback(uint, ProcessLoopbackMode).
WithDevice(MMDevice)
Use the specified audio device for capture.
public WasapiRecorderBuilder WithDevice(MMDevice device)Parameters
deviceMMDevice
Returns
WithEchoCancellationReferenceEndpoint(MMDevice)
Sets the render endpoint used as the reference stream for acoustic echo cancellation (AEC) on the capture stream. Pass the render device whose output should be cancelled out of the microphone signal, or null (the default) to let Windows pick the loopback reference itself.
public WasapiRecorderBuilder WithEchoCancellationReferenceEndpoint(MMDevice referenceRenderDevice = null)Parameters
referenceRenderDeviceMMDeviceThe render device to use as the reference stream, or null to let Windows choose automatically.
Returns
Remarks
AEC is performed by an audio processing object in the capture pipeline; this only selects the loopback reference endpoint. StartRecording() throws NotSupportedException if the capture endpoint does not support controlling the AEC reference endpoint. Requires Windows 11 build 22621 or later.
WithEventSync()
Use event-based synchronization (default).
public WasapiRecorderBuilder WithEventSync()Returns
WithExclusiveMode()
Use exclusive mode for lower latency capture.
public WasapiRecorderBuilder WithExclusiveMode()Returns
WithFormat(WaveFormat)
Request a specific capture format. If not set, uses the device's mix format. In shared mode with AutoConvertPcm, the engine will convert to this format.
public WasapiRecorderBuilder WithFormat(WaveFormat format)Parameters
formatWaveFormat
Returns
WithLoopbackCapture()
Capture audio from a render device in loopback mode (what the device is playing). Pass a render endpoint via WithDevice(MMDevice); if no device is set the default render device is used.
public WasapiRecorderBuilder WithLoopbackCapture()Returns
WithLowLatency(bool)
Request low-latency shared-mode capture via IAudioClient3 if available. This opens the capture stream at the engine's minimum supported period rather than the configured buffer length, which is useful for real-time scenarios such as live visualization or monitoring.
public WasapiRecorderBuilder WithLowLatency(bool required = false)Parameters
requiredboolWhen false (the default), capture silently falls back to standard shared mode if low latency can't be honoured — inspect LowLatencyActive and LowLatencyUnavailableReason afterwards to see what you got. When true, StartRecording() (or CaptureAsync(CancellationToken)) instead throws an InvalidOperationException if low latency can't be achieved.
Returns
Remarks
Low latency requires shared mode, event-driven synchronization (the default), no loopback, and a capture format matching the device mix format — so do not combine it with WithFormat(WaveFormat) requesting a different format, WithLoopbackCapture(), WithExclusiveMode(), WithPollingSync(), or WithProcessLoopback(uint, ProcessLoopbackMode). It also needs IAudioClient3 (Windows 10 version 1607 or later).
WithMmcssThreadPriority(string)
Elevate the capture thread priority via MMCSS. Common task names: "Pro Audio", "Audio", "Capture".
public WasapiRecorderBuilder WithMmcssThreadPriority(string taskName = "Pro Audio")Parameters
taskNamestring
Returns
WithPollingSync()
Use polling-based synchronization.
public WasapiRecorderBuilder WithPollingSync()Returns
WithProcessLoopback(uint, ProcessLoopbackMode)
Capture audio from a specific process (and optionally its child processes). Requires Windows 10 2004 (build 19041) or later. This uses ActivateAudioInterfaceAsync with AUDIOCLIENT_PROCESS_LOOPBACK_PARAMS.
public WasapiRecorderBuilder WithProcessLoopback(uint processId, ProcessLoopbackMode mode = ProcessLoopbackMode.IncludeTargetProcessTree)Parameters
processIduintThe process ID to capture audio from.
modeProcessLoopbackModeWhether to include or exclude the target process tree.
Returns
WithRawMode()
Open a 'raw' capture stream that bypasses the system signal-processing pipeline — the capture audio enhancements / APO effects Windows applies by default. Only endpoint-specific, always-on processing in the APO, driver and hardware remains. Use this when you want the microphone signal unaltered by system effects.
public WasapiRecorderBuilder WithRawMode()Returns
Remarks
Requires IAudioClient2 (Windows 8.1+); StartRecording() throws InvalidOperationException if the device does not support it. Compatible with shared and exclusive mode, low latency, loopback capture, event/polling sync and default-device stream routing. It is the opposite of WithCommunicationsMode() / WithEchoCancellationReferenceEndpoint(MMDevice) (which request signal processing), so it cannot be combined with them, nor with WithProcessLoopback(uint, ProcessLoopbackMode) (whose virtual device has no IAudioClient2).
WithSharedMode()
Use shared mode (default).
public WasapiRecorderBuilder WithSharedMode()