Class AudioDevice

Namespace

NAudio.MacOS.CoreAudio

Assembly

NAudio.MacOS.dll

The AudioDevice class is a subclass of the AudioObject. The class has four scopes, Global, Input, Output, and PlayThrough. The class has a main element and an element for each channel in each stream numbered according to the starting channel number of each stream.

public class AudioDevice : AudioObject, IEquatable<AudioObject>, IEqualityOperators<AudioObject, AudioObject, bool>

Inheritance

object

AudioObject

AudioDevice

Implements

IEquatable<AudioObject>

IEqualityOperators<AudioObject, AudioObject, bool>

Inherited Members

AudioObject.ClassID

AudioObject.BaseClassID

AudioObject.Name

AudioObject.ModelName

AudioObject.Manufacturer

AudioObject.SerialNumber

AudioObject.FirmwareVersion

AudioObject.Owner

AudioObject.OwnedObjects

AudioObject.GetHashCode()

AudioObject.Equals(AudioObject)

AudioObject.Equals(object)

AudioObject.ToString()

object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Properties

ActualSampleRate

A double that indicates the current actual sample rate of the AudioDevice as measured by its time stamps.

public double ActualSampleRate { get; }

Property Value

double

AvailableNomimalSampleRates

An array of pairs that indicates the valid ranges for the nominal sample rate of the AudioClockDevice.

public (double min, double max)[] AvailableNomimalSampleRates { get; }

Property Value

(double min, double max)[]

BufferFrameSize

A uint whose value indicates the number of frames in the IO buffers.

public uint BufferFrameSize { get; }

Property Value

uint

BufferFrameSizeRange

A pair indicating the minimum and maximum values, inclusive, for BufferFrameSize.

public (double min, double max) BufferFrameSizeRange { get; }

Property Value

(double min, double max)

CanBeDefaultSystemDevice

A bool where true means that the AudioDevice is a possible selection for kAudioHardwarePropertyDefaultSystemOutputDevice.

public bool CanBeDefaultSystemDevice { get; }

Property Value

bool

ClockDevice

A string that contains the UID for the AudioClockDevice that is currently serving as the main time base of the device.

public string ClockDevice { get; }

Property Value

string

ClockDomain

A UInt32 whose value indicates the clock domain to which this AudioDevice belongs. AudioDevices that have the same value for this property are able to be synchronized in hardware. However, a value of 0 indicates that the clock domain for the device is unspecified and should be assumed to be separate from every other device's clock domain, even if they have the value of 0 as their clock domain as well.

public uint ClockDomain { get; }

Property Value

uint

ConfigurationApplication

A string that contains the bundle ID for an application that provides a GUI for configuring the AudioDevice.
By default, the value of this property is the bundle ID for Audio MIDI Setup.

public string ConfigurationApplication { get; }

Property Value

string

ControlList

An array of AudioControl that represent the audio controls of the AudioDevice. Note that if a notification is received for this property, any cached AudioControls for the device become invalid and need to be re-fetched.

public AudioControl[] ControlList { get; }

Property Value

AudioControl[]

DeviceUID

A string that contains a persistent identifier for the AudioDevice.
An AudioDevice's UID is persistent across boots. The content of the UID string is a black box and may contain information that is unique to a particular instance of an AudioDevice's hardware or unique to the CPU. Therefore they are not suitable for passing between CPUs or for identifying similar models of hardware.

public string DeviceUID { get; }

Property Value

string

HogMode

A bool indicating the process that currently owns exclusive access to the AudioDevice or a value of false indicating that the device is currently available to all processes. If the AudioDevice is in a non-mixable mode, the HAL will automatically take hog mode on behalf of the first process to start an CoreAudioIOProcedure.

Note that when setting this property, the value passed in is ignored. If another process owns exclusive access, that remains unchanged. If the current process owns exclusive access, it is released and made available to all processes again. If no process has exclusive access (meaning the current value is true), this process gains ownership of exclusive access.

public bool HogMode { get; set; }

Property Value

bool

IOCycleUsage

A float whose range is from 0 to 1. This value indicates how much of the client portion of the IO cycle the process will use. The client portion of the IO cycle is the portion of the cycle in which the device calls the IOProcs so this property does not the apply to the duration of the entire cycle.

public float IOCycleUsage { get; set; }

Property Value

float

Icon

A Uri that indicates an image file that can be used to represent the device visually.
If no such image file is assigned for the device, this returns null.

[MaybeNull]
public Uri Icon { get; }

Property Value

Uri

IsAlive

A bool where a value of true means the device is ready and available and false means the device is unusable and will most likely go away shortly.

public bool IsAlive { get; }

Property Value

bool

IsHidden

A UInt32 where a non-zero value indicates that the device is not included in the normal list of devices provided by Devices nor can it be the default device.
Hidden devices can only be discovered by knowing their UID and using ConvertUIDToDevice(string).

public bool IsHidden { get; }

Property Value

bool

IsRunning

A bool where a value of false means the AudioDevice is not performing IO and a value of true means that it is. Note that the device can be running even if there are no active IOProcs such as by calling AudioDeviceStart() and passing a NULL IOProc. Note that the notification for this property is usually sent from the AudioDevice's IO thread.

public bool IsRunning { get; }

Property Value

bool

IsRunningSomewhere

A bool where true means that the AudioDevice is running in at least one process on the system and false means that it isn't running at all.

public bool IsRunningSomewhere { get; }

Property Value

bool

ModelUID

A string that contains a persistent identifier for the model of an AudioDevice. The identifier is unique such that the identifier from two AudioDevices are equal if and only if the two AudioDevices are the exact same model from the same manufacturer. Further, the identifier has to be the same no matter on what machine the AudioDevice appears.

public string ModelUID { get; }

Property Value

string

NominalSampleRate

A double that indicates the current nominal sample rate of the AudioDevice.

public double NominalSampleRate { get; }

Property Value

double

ProcessMute

A bool where a true value indicates that the current process's audio will be zeroed out by the system. Note that this property does not apply to aggregate devices, just real, physical devices.

public bool ProcessMute { get; set; }

Property Value

bool

RelatedDevices

An array of AudioDevices for devices related to the AudioDevice.
For IOAudio-based devices, AudioDevices are related if they share the same IOAudioDevice object.

public AudioDevice[] RelatedDevices { get; }

Property Value

AudioDevice[]

UsesVariableBufferFrameSizes

A uint that, if implemented by a device, indicates that the sizes of the buffers passed to an IOProc will vary by a small amount. The value of this property will indicate the largest buffer that will be passed and BufferFrameSize will indicate the smallest buffer that will get passed to the IOProc. The usage of this property is narrowed to only allow for devices whose buffer sizes vary by small amounts greater than BufferFrameSize. It is not intended to be a license for devices to be able to send buffers however they please. Rather, it is intended to allow for hardware whose natural rhythms lead to this necessity.

public uint UsesVariableBufferFrameSizes { get; }

Property Value

uint

Methods

ConstructControlListChangedEvent()

Provides the way for creating an event handle when the contents of the ControlList property do change.

public PropertyListenerHandle ConstructControlListChangedEvent()

Returns

PropertyListenerHandle

A new PropertyListenerHandle that can be used to listen to changes of the ControlList property.
It's OriginatingObject property value is this AudioDevice instance.

ConstructIOStoppedAbnormallyEvent()

Provides the way for creating an event handle when I/O has been abnormally stopped.

public PropertyListenerHandle ConstructIOStoppedAbnormallyEvent()

Returns

PropertyListenerHandle

A new PropertyListenerHandle that can be used to listen to an event that is fired when the AudioDevice has it's I/O abnormally stopped.
It's OriginatingObject property value is this AudioDevice instance.

ConstructIsAliveChangedEvent()

Provides the way for creating an event handle when the value of the IsAlive property do change.

public PropertyListenerHandle ConstructIsAliveChangedEvent()

Returns

PropertyListenerHandle

A new PropertyListenerHandle that can be used to listen to changes of the IsAlive property.
It's OriginatingObject property value is this AudioDevice instance.

ConstructProcessorOverloadedEvent()

Provides the way for creating an event handle when an I/O procedure in this audio device has been run past it's deadline.

public PropertyListenerHandle ConstructProcessorOverloadedEvent()

Returns

PropertyListenerHandle

A new PropertyListenerHandle that can be used to listen to an event that is fired when the AudioDevice is having a CoreAudioIOProcedure that has run past it's deadline.
It's OriginatingObject property value is this AudioDevice instance.

ConstructStreamsChangedEvent(AudioObjectPropertyScope)

Provides the way for creating an event handle when the contents of the GetStreams(AudioObjectPropertyScope) method do change.

public PropertyListenerHandle ConstructStreamsChangedEvent(AudioObjectPropertyScope scope)

Parameters

scope AudioObjectPropertyScope

The AudioObjectPropertyScope of the device's scope to query

Returns

PropertyListenerHandle

A new PropertyListenerHandle that can be used to listen to changes of the GetStreams(AudioObjectPropertyScope) method.
It's OriginatingObject property value is this AudioDevice instance.

GetCanBeDefaultDevice(AudioObjectPropertyScope)

A bool where true means that the AudioDevice is a possible selection for kAudioHardwarePropertyDefaultInputDevice or kAudioHardwarePropertyDefaultOutputDevice depending on the scope.

public bool GetCanBeDefaultDevice(AudioObjectPropertyScope scope)

Parameters

scope AudioObjectPropertyScope

The scope to define the search for. Can only be Input or Output.

Returns

bool

A value whether the current AudioDevice is a possible selection for an input/output device, depending on the used constant.

GetDeviceHasChangedEvent()

Provides the way for creating an event handle when the audio device has been changed.

public PropertyListenerHandle GetDeviceHasChangedEvent()

Returns

PropertyListenerHandle

A new PropertyListenerHandle that can be used to listen to an event that is fired when the device configuration has been altered.
It's OriginatingObject property value is this AudioDevice instance.

GetDeviceLatency(AudioObjectPropertyScope)

A uint containing the number of frames of latency in the AudioDevice. Note that input and output latency may differ. Further, the AudioDevice's AudioStreams may have additional latency so they should be queried as well. If both the device and the stream say they have latency, then the total latency for the stream is the device latency summed with the stream latency.

public uint GetDeviceLatency(AudioObjectPropertyScope scope)

Parameters

scope AudioObjectPropertyScope

Returns

uint

GetPreferredChannelLayout(AudioObjectPropertyScope, out bool, out bool)

A Speakers value that indicates how each channel of the AudioDevice should be used.

public Speakers GetPreferredChannelLayout(AudioObjectPropertyScope scope, out bool needsResampling, out bool needsExtensible)

Parameters

scope AudioObjectPropertyScope

needsResampling bool

needsExtensible bool

Returns

Speakers

GetPreferredChannelsForStereo(AudioObjectPropertyScope)

An array of two uint, the first for the left channel, the second for the right channel, that indicate the channel numbers to use for stereo IO on the device. The value of this property can be different for input and output and there are no restrictions on the channel numbers that can be used.

public uint[] GetPreferredChannelsForStereo(AudioObjectPropertyScope scope)

Parameters

scope AudioObjectPropertyScope

Returns

uint[]

GetSafetyOffset(AudioObjectPropertyScope)

A uint whose value indicates the number for frames in ahead (for output) or behind (for input the current hardware position that is safe to do IO.

public uint GetSafetyOffset(AudioObjectPropertyScope scope)

Parameters

scope AudioObjectPropertyScope

The direction to use (input/output)

Returns

uint

The safety offset, as described above.

Exceptions

ArgumentException

scope not Input or Output.

GetStreamUsage(CoreAudioIOProcedure, AudioObjectPropertyScope)

A bool array which details the stream usage of a given I/O procedure. If a stream is marked as not being used (which the value of that array element will be false), the given CoreAudioIOProcedure will see a corresponding NULL buffer pointer in the AudioBufferList passed to its IO proc. Note that the number of streams detailed in the bool array must include all the streams of that direction on the device.

public bool[] GetStreamUsage(CoreAudioIOProcedure procedure, AudioObjectPropertyScope scope)

Parameters

procedure CoreAudioIOProcedure

The Core Audio I/O procedure to query the usage for.

scope AudioObjectPropertyScope

The scope that the stream usage is to be retrieved for.

Returns

bool[]

A bool array that indicates which streams are enabled and which are not. Use the GetStreams(AudioObjectPropertyScope) method to map each index to an AudioStream object.

Exceptions

ArgumentNullException

procedure is null.

InvalidOperationException

The specified procedure is invalid.

GetStreams(AudioObjectPropertyScope)

An array of AudioStreams that represent the AudioStreams of the AudioDevice. Note that if a notification is received for this property, any cached AudioStreamIDs for the device become invalid and need to be re-fetched.

public AudioStream[] GetStreams(AudioObjectPropertyScope scope)

Parameters

scope AudioObjectPropertyScope

Returns

AudioStream[]

GetTransportType(AudioObjectPropertyScope)

A TransportType whose value indicates how the AudioDevice is connected to the CPU.
Constants for some of the values for this property can be found in the enum TransportTypeConstants.

public TransportType GetTransportType(AudioObjectPropertyScope scope)

Parameters

scope AudioObjectPropertyScope

The Property Scope to query the transport type for

Returns

TransportType

A TransportType value.

SetStreamUsage(CoreAudioIOProcedure, AudioObjectPropertyScope, bool[])

Set a bool array which details the stream usage of a given I/O procedure. If a stream is marked as not being used (which the value of that array element will be false), the given CoreAudioIOProcedure will see a corresponding NULL buffer pointer in the AudioBufferList passed to its IO proc. Note that the number of streams detailed in the bool array must include all the streams of that direction on the device.

public void SetStreamUsage(CoreAudioIOProcedure procedure, AudioObjectPropertyScope scope, bool[] streamsToEnableOrDisable)

Parameters

procedure CoreAudioIOProcedure

The Core Audio I/O procedure to assign the usage for.

scope AudioObjectPropertyScope

The scope that the stream usage is to be retrieved for.

streamsToEnableOrDisable bool[]

The streams to enable/disable.

Exceptions

ArgumentNullException

procedure and/or streamsToEnableOrDisable are null.

InvalidOperationException

The specified procedure is invalid.