Class AudioDevice

Namespace

AudioDeviceLib

Assembly

AudioDeviceLib.dll

A single Windows audio endpoint: its identity, its state, and its volume, metering and session controls.

[PublicAPI]
public sealed class AudioDevice : IDisposable, IEquatable<AudioDevice>

Inheritance

object

AudioDevice

Implements

IDisposable

IEquatable<AudioDevice>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

Identity (Id, Name, Kind) and State are captured when the instance is created and cost nothing to read afterward. Call Refresh() to re-read them or register for change notifications with RegisterDeviceNotification(IAudioDeviceEvents).

Dispose an instance once you are done with it. That tears down any endpoint-volume or session callbacks it activated; the identity snapshot stays readable afterward, but every other member throws ObjectDisposedException.

Volume, SessionManager, Meter and Properties activate their underlying Core Audio interface on first access, and doing so is thread-safe: concurrent first readers all receive the same instance, and Dispose() is synchronized against them. This matters because device notifications are documented to arrive on arbitrary threads and concurrently, so reading a device's volume from a notification callback is a normal thing to do.

Properties

Id

Endpoint ID, e.g. "{0.0.0.00000000}.{c4aadd95-...}".

public string Id { get; }

Property Value

string

IsActive

Gets whether the endpoint was active as of construction or the last Refresh().

public bool IsActive { get; }

Property Value

bool

IsDefault

True if this endpoint is the current default device for its kind (multimedia role).

public bool IsDefault { get; }

Property Value

bool

IsDefaultCommunication

True if this endpoint is the current default communications device for its kind.

public bool IsDefaultCommunication { get; }

Property Value

bool

IsMuted

Gets or sets the mute state of the endpoint.

public bool IsMuted { get; set; }

Property Value

bool

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

Kind

Whether this is a playback (render) or recording (capture) endpoint.

public AudioDeviceKind Kind { get; }

Property Value

AudioDeviceKind

Meter

Gets the peak-meter information for this endpoint (activated on first access).

public AudioMeterInformation Meter { get; }

Property Value

AudioMeterInformation

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

COMException

Thrown when the interface cannot be activated.

Name

Friendly name, e.g. "Speakers (Realtek High Definition Audio)".

public string Name { get; }

Property Value

string

Properties

Gets the property store for this endpoint (opened on first access).

public PropertyStore Properties { get; }

Property Value

PropertyStore

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

COMException

Thrown when the property store cannot be opened.

SessionManager

Gets the audio session manager for this endpoint (activated on first access).

public AudioSessionManager SessionManager { get; }

Property Value

AudioSessionManager

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

COMException

Thrown when the interface cannot be activated.

State

State of the endpoint as of construction or the last Refresh().

public DeviceState State { get; }

Property Value

DeviceState

Volume

Gets the volume and mute control for this endpoint (activated on first access).

public AudioEndpointVolume Volume { get; }

Property Value

AudioEndpointVolume

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

COMException

Thrown when the interface cannot be activated.

Methods

Dispose()

Releases the endpoint-volume and session callbacks this instance registered, and the property store and meter it activated.

public void Dispose()

Remarks

The identity snapshot (Id, Name, Kind, State, ToDeviceInfo(), ToString()) stays readable after disposal; every member that talks to Core Audio throws ObjectDisposedException.

Equals(AudioDevice?)

Compares endpoint IDs without regard to case.

public bool Equals(AudioDevice? other)

Parameters

other AudioDevice

The endpoint to compare.

Returns

bool

Whether both instances identify the same endpoint.

Equals(object?)

Determines whether the given object is the same endpoint, compared by Id.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with.

Returns

bool

true if obj is an AudioDevice with the same ID.

GetHashCode()

Serves as the hash function, derived from Id.

public override int GetHashCode()

Returns

int

A hash code for this endpoint.

GetPeakValue()

Instantaneous master peak level in the range 0..1 (0 when silent).

public float GetPeakValue()

Returns

float

The current master peak meter value between 0 (silent) and 1 (full scale).

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

GetVolumePercent()

Master volume as a percentage in the range 0..100.

public float GetVolumePercent()

Returns

float

The current master volume scalar expressed as a percentage between 0 and 100.

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

Refresh()

Re-reads Name and State from the endpoint.

public void Refresh()

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

COMException

Thrown when the underlying Core Audio call fails.

SetVolumePercent(float)

Sets master volume from a percentage in the range 0..100 (values are clamped).

public void SetVolumePercent(float percent)

Parameters

percent float

The desired master volume as a percentage. Values below 0 are clamped to 0, and values above 100 are clamped to 100.

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

ToDeviceInfo()

Creates an immutable AudioDeviceInfo snapshot of this device's identifying data.

public AudioDeviceInfo ToDeviceInfo()

Returns

AudioDeviceInfo

A snapshot carrying this device's information, safe to keep after this AudioDevice is disposed of.

ToString()

Returns a human-readable description of this endpoint.

public override string ToString()

Returns

string

A string in the form Name (Kind), optionally suffixed with [Default] and/or [DefaultComm] when this endpoint is a current default device.

ToggleMute()

Inverts the current mute state.

public bool ToggleMute()

Returns

bool

The mute state after the change.

Exceptions

ObjectDisposedException

Thrown when this instance has been disposed of.

Operators

operator ==(AudioDevice?, AudioDevice?)

Compares endpoint identities.

public static bool operator ==(AudioDevice? left, AudioDevice? right)

Parameters

left AudioDevice

right AudioDevice

Returns

bool

operator !=(AudioDevice?, AudioDevice?)

Compares endpoint identities for inequality.

public static bool operator !=(AudioDevice? left, AudioDevice? right)

Parameters

left AudioDevice

right AudioDevice

Returns

bool