Class AudioEndpointVolume

Namespace

AudioDeviceLib.CoreAudioApi

Assembly

AudioDeviceLib.dll

Managed wrapper over the Core Audio IAudioEndpointVolume interface. Provides master volume, per-channel volume, mute control and volume-change notifications for an endpoint.

[PublicAPI]
public sealed class AudioEndpointVolume : IDisposable

Inheritance

object

AudioEndpointVolume

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Disposal is mandatory. This type registers a callback with Core Audio when it is created, and native code holds a reference to that callback for as long as the registration is live. That reference roots this object, so an instance that is never disposed is never collected: it leaks for the lifetime of the process and keeps delivering notifications to any consumer still registered with it. The garbage collector cannot recover it, and there is deliberately no finalizer that pretends otherwise - a finalizer could not run while the registration is live, which is precisely when it would be needed.

Instances reached through Volume are owned by that device and are disposed with it; only dispose this object directly if you created it directly.

Properties

Channels

Gets the collection of per-channel volume controls for the endpoint.

public AudioEndpointVolumeChannels Channels { get; }

Property Value

AudioEndpointVolumeChannels

HardwareSupport

Gets the hardware functions (volume, mute, meter) natively supported by the endpoint.

public EndpointHardwareSupport HardwareSupport { get; }

Property Value

EndpointHardwareSupport

MasterVolumeLevel

Gets or sets the master volume level in decibels, within VolumeRange.

public float MasterVolumeLevel { get; set; }

Property Value

float

Exceptions

COMException

Thrown when the underlying Core Audio call fails.

MasterVolumeLevelScalar

Gets or sets the master volume as a normalized scalar in the range 0.0 to 1.0.

public float MasterVolumeLevelScalar { get; set; }

Property Value

float

Exceptions

COMException

Thrown when the underlying Core Audio call fails.

Mute

Gets or sets the mute state of the endpoint.

public bool Mute { get; set; }

Property Value

bool

Exceptions

COMException

Thrown when the underlying Core Audio call fails.

StepInformation

Gets the number of discrete volume steps and the current step for the endpoint.

public AudioEndpointVolumeStepInformation StepInformation { get; }

Property Value

AudioEndpointVolumeStepInformation

VolumeRange

Gets the supported volume range (minimum, maximum and step, in decibels) for the endpoint.

public AudioEndPointVolumeVolumeRange VolumeRange { get; }

Property Value

AudioEndPointVolumeVolumeRange

Methods

Dispose()

Unregisters every remaining volume-notification consumer and the underlying Core Audio callback. Safe to call more than once.

public void Dispose()

Remarks

There is no finalizer backing this up, by design. The only resource here is a Core Audio registration held through a COM callable wrapper, not a raw handle: the interop wrapper for IAudioEndpointVolume is released by the runtime on its own, and unregistering is a call into another COM object rather than a resource release - something a finalizer thread must not attempt, since finalization order between this object and that wrapper is undefined. A finalizer could not help anyway, because the live registration keeps this object reachable for exactly as long as it would have had work to do.

RegisterVolumeNotification(IAudioEndpointVolumeEvents)

Registers a consumer to receive endpoint volume and mute change notifications.

public IDisposable RegisterVolumeNotification(IAudioEndpointVolumeEvents eventConsumer)

Parameters

eventConsumer IAudioEndpointVolumeEvents

The consumer to notify. Registering the same instance twice is a no-op that returns the token from the first registration.

Returns

IDisposable

A token that unregisters this consumer when disposed. Safe to dispose more than once.

Remarks

The notification callback is registered with Core Audio once, when this object is created; registering a consumer only adds it to the managed fan-out list and makes no COM call. Disposing this AudioEndpointVolume unregisters every remaining consumer.

Exceptions

ArgumentNullException

Thrown when eventConsumer is null.

ObjectDisposedException

Thrown when this instance has been disposed.

VolumeStepDown()

Decreases the master volume by one hardware-defined step.

public void VolumeStepDown()

Exceptions

COMException

Thrown when the underlying Core Audio call fails.

VolumeStepUp()

Increases the master volume by one hardware-defined step.

public void VolumeStepUp()

Exceptions

COMException

Thrown when the underlying Core Audio call fails.