Class CoreAudioRecorder

Namespace

NAudio.Wave

Assembly

NAudio.MacOS.dll

Provides a way to capture data from an audio device based on the Apple's audio HAL framework library, namely the Core Audio Framework.
The user provides the audio device to perform recording upon and the rest are managed by this class. This class does also manage cases where the streams may be invalidated, or when the selected stream's virtual format has been changed, for which cases the recorder will dispatch the CaptureFormatChanged event.
There are also several properties that can be configured by the provided AudioDevice object during construction (applying to all the attached recorders of the device). See the AudioDevice properties and methods to see what can be configured.

public sealed class CoreAudioRecorder : IDisposable, IAsyncDisposable, IWaveLatency

Inheritance

object

CoreAudioRecorder

Implements

IDisposable

IAsyncDisposable

IWaveLatency

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

CoreAudioRecorder()

Initializes a new Core Audio recoder instance, using the default input device to capture audio data.
If a synchronization context is assigned for the thread where this instance is created to, it is used when a recording stopped event is dispatching.

public CoreAudioRecorder()

CoreAudioRecorder(AudioDevice)

Initializes a new Core Audio recoder instance from the specified device.
If a synchronization context is assigned for the thread where this instance is created to, it is used when a recording stopped event is dispatching.

public CoreAudioRecorder(AudioDevice device)

Parameters

device AudioDevice

The AudioDevice to capture data from.

Exceptions

ArgumentNullException

device is null.

Properties

AverageLatency

The steady-state latency from a sample being queued for output to it being emitted by the audio hardware, assuming uninterrupted playback. This is a property of the buffer configuration and the driver, not of the current playback state.

public TimeSpan AverageLatency { get; }

Property Value

TimeSpan

CaptureFormat

Provides the audio format the HAL uses to capture audio.
This is the format of the audio data that are provided during the dispatch of the DataAvailable event.

public WaveFormat CaptureFormat { get; }

Property Value

WaveFormat

Exceptions

InvalidOperationException

This CoreAudioRecorder instance has not yet been initialized.

CaptureState

Gets a value whether the recorder is recording from the initialized device.
Will return Stopped once disposed

public CaptureState CaptureState { get; }

Property Value

CaptureState

CurrentLatency

The time that has elapsed since the sample currently emerging from the hardware was queued for output. In steady state this is approximately equal to AverageLatency; it differs during start-up, after an underrun, or when the host is filling buffers irregularly. Implementations that cannot meaningfully distinguish from the average are permitted to return AverageLatency.

public TimeSpan CurrentLatency { get; }

Property Value

TimeSpan

Device

Gets the selected audio device where the recorder retrieves data from.

[NotNull]
public AudioDevice Device { get; }

Property Value

AudioDevice

Methods

CaptureAsync(CancellationToken)

Asynchronously captures audio data from the specified input device, initializing the recording if needed in the asynchronous code path.

public IAsyncEnumerable<CoreAudioCaptureBuffer> CaptureAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The token that can be used to manually stop recording (Although it is also possible by calling the StopRecording() method).

Returns

IAsyncEnumerable<CoreAudioCaptureBuffer>

An enumerable instance returning capture buffers in an asynchronous manner.

Exceptions

ObjectDisposedException

This recorder instance has been disposed of.

InvalidOperationException

This recorder instance is already been in use.

CoreAudioException

The device that is used by the recorder is not existing.

Dispose()

Disposes this CoreAudioRecorder instance.
Thread-safe.

public void Dispose()

Remarks

Note that this method will probably throw when the device used to initialize the recorder is gone; so, expect to catch AggregateException for this particular case.

Exceptions

AggregateException

One or more native objects were failed to be disposed of.

DisposeAsync()

Disposes this CoreAudioRecorder instance asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A new ValueTask instance providing the task to execute for freeing the held resources of this CoreAudioRecorder instance asynchronously.

InitializeRecording()

Call this method once per instance to set up the recorder for recording.

public void InitializeRecording()

Remarks

This method can be called multiple times, it is thread-safe and only the first thread that manages to take the lock will perform the initialization task.

Exceptions

InvalidOperationException

The recorder could not be set up (invalid device, invalid streams, etc.)

InitializeRecordingAsync()

Call this method once per instance to set up the recorder for recording asynchronously.

public ValueTask InitializeRecordingAsync()

Returns

ValueTask

A new ValueTask that represents the code to execute for initializing the recoder.

Remarks

This method can be called multiple times, it is thread-safe and only the first thread that manages to take the lock will perform the initialization task.

StartRecording()

Starts the recording. This API uses the DataAvailable event to pull the captured audio data.

public void StartRecording()

Exceptions

InvalidOperationException

The recorder is not initialized.

ObjectDisposedException

This recorder instance has been disposed of.

CoreAudioException

The device that is used by the recorder is not existing.

See Also

CaptureAsync(CancellationToken)

StopRecording()

Stops the recording, previously started by the StartRecording() method.

public void StopRecording()

Exceptions

InvalidOperationException

The recorder is not initialized.

ObjectDisposedException

This recorder instance has been disposed of.

CoreAudioException

The device that is used by the recorder is not existing.

Events

CaptureFormatChanged

Provides an event that is fired when the recorder's capture format has been changed.

public event CoreAudioCaptureFormatChangedHandler CaptureFormatChanged

Event Type

CoreAudioCaptureFormatChangedHandler

Remarks

If capture is already running, capture will be stopped.
If you want to restart recording, explicitly call the StartRecording() method.

DataAvailable

Provides an event that is fired when new capture data are retrieved from the HAL.

public event CoreAudioCaptureDataAvailableHandler DataAvailable

Event Type

CoreAudioCaptureDataAvailableHandler

RecordingStopped

Provides an event that is fired when the recording has been stopped.

public event EventHandler<StoppedEventArgs> RecordingStopped

Event Type

EventHandler<StoppedEventArgs>

See Also

NAudio.MacOS.CoreAudio