Class AudioController

Namespace

AudioDeviceLib

Assembly

AudioDeviceLib.dll

High-level API over the Windows Core Audio endpoints. Create one instance and reuse it. All members are Windows-only and must run on a thread able to use COM.

[PublicAPI]
public sealed class AudioController : IDisposable

Inheritance

object

AudioController

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

AudioController()

Creates a controller over the machine's Core Audio endpoints.

public AudioController()

Exceptions

PlatformNotSupportedException

Thrown when not running on Windows.

Methods

Dispose()

Releases resources held by the controller, unregistering any remaining device-notification callbacks. The controller does not own the AudioDevice instances returned by its methods; dispose of those yourself when you have accessed their volume/session features.

public void Dispose()

Remarks

Waits up to five seconds for calls already in progress on other threads to finish, because releasing the underlying COM enumerator (or the cached policy-config client) while one is running would disconnect it mid-call. If they have not finished by then the enumerator is left to the garbage collector rather than blocking any longer. Calls that start after this returns throw ObjectDisposedException.

GetDefaultPlayback(bool)

Returns a snapshot of the current default playback device or null when no default playback device is set.

public static AudioDeviceInfo? GetDefaultPlayback(bool communications = false)

Parameters

communications bool

When true, resolves the default for the communications role; when false (the default), resolves the default for the multimedia role.

Returns

AudioDeviceInfo

An immutable snapshot of the default playback endpoint.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

GetDefaultPlaybackDevice(bool)

Returns the current default playback device, or null if none is set.

public AudioDevice? GetDefaultPlaybackDevice(bool communications = false)

Parameters

communications bool

When true, resolves the default for the communications role (voice chat); when false (the default), resolves the default for the multimedia role (music, movies).

Returns

AudioDevice

The default playback AudioDevice for the requested role, or null if no default playback device is currently set.

GetDefaultRecording(bool)

Returns a snapshot of the current default recording device or null when no default recording device is set.

public static AudioDeviceInfo? GetDefaultRecording(bool communications = false)

Parameters

communications bool

When true, resolves the default for the communications role; when false (the default), resolves the default for the multimedia role.

Returns

AudioDeviceInfo

An immutable snapshot of the default recording endpoint.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

GetDefaultRecordingDevice(bool)

Returns the current default recording device, or null if none is set.

public AudioDevice? GetDefaultRecordingDevice(bool communications = false)

Parameters

communications bool

When true, resolves the default for the communications role (voice chat); when false (the default), resolves the default for the multimedia role.

Returns

AudioDevice

The default recording AudioDevice for the requested role, or null if no default recording device is currently set.

GetDeviceById(string)

Returns the endpoint with the given ID, or null if no such endpoint is present on the system.

public AudioDevice? GetDeviceById(string deviceId)

Parameters

deviceId string

The ID of the endpoint to return.

Returns

AudioDevice

The endpoint with the given ID, or null if the ID matches no endpoint currently on the system. An ID obtained from GetDevices(DataFlowFilter, DeviceStateFilter) can stop resolving at any time - the endpoint may be unplugged or disabled between the two calls - so a null result is an expected outcome of that race, not a failure. Anything that is genuinely wrong still throws.

Exceptions

ArgumentNullException

If deviceId is null or empty.

ArgumentException

Thrown when deviceId is not a well-formed endpoint ID.

COMException

Thrown when the endpoint exists but could not be read - for example when the audio service is stopping. Only Core Audio's HRESULT_FROM_WIN32(ERROR_NOT_FOUND) (0x80070490) becomes a null result; every other HRESULT is reported.

ObjectDisposedException

Thrown when this controller has been disposed.

GetDeviceInfo(string)

Returns the immutable AudioDeviceInfo snapshot of the given endpoint's identifying data, or null if no endpoint with that ID is present on the system.

public AudioDeviceInfo? GetDeviceInfo(string deviceId)

Parameters

deviceId string

The ID of the endpoint to retrieve information for.

Returns

AudioDeviceInfo

A snapshot carrying this device's information, safe to keep after this AudioDevice is disposed of, or null if the ID matches no endpoint currently on the system. See GetDeviceById(string) for why absence is an answer rather than an error.

Exceptions

ArgumentNullException

If deviceId is null or empty.

ArgumentException

Thrown when deviceId is not a well-formed endpoint ID.

COMException

Thrown when the endpoint exists but could not be read.

ObjectDisposedException

Thrown when this controller has been disposed.

GetDevices(DataFlowFilter, DeviceStateFilter)

Returns the endpoints matching the given data-flow direction and state, in enumeration order.

public IReadOnlyList<AudioDevice> GetDevices(DataFlowFilter flow = DataFlowFilter.All, DeviceStateFilter state = DeviceStateFilter.Active)

Parameters

flow DataFlowFilter

Which endpoint directions to include: Render (playback), Capture (recording), or All for both (the default).

state DeviceStateFilter

A bit mask of endpoint states to include. Defaults to Active; combine flags or pass All to include disabled, not-present and unplugged endpoints too.

Returns

IReadOnlyList<AudioDevice>

A read-only list of the matching AudioDevice endpoints. The list is empty if no endpoints match.

Remarks

The caller owns the returned endpoints and should dispose of them. An endpoint that becomes unreadable while the list is being built - unplugged, or its driver torn down - is omitted rather than failing the whole call, so the result can be shorter than the number of endpoints the system reported.

Exceptions

ObjectDisposedException

Thrown when this controller has been disposed.

GetPlaybackDevices(DeviceStateFilter)

Returns all active playback (render) endpoints.

public IReadOnlyList<AudioDevice> GetPlaybackDevices(DeviceStateFilter state = DeviceStateFilter.Active)

Parameters

state DeviceStateFilter

A bit mask of endpoint states to include. Defaults to Active;

Returns

IReadOnlyList<AudioDevice>

A read-only list of the active endpoints whose Kind is Playback.

GetRecordingDevices(DeviceStateFilter)

Returns all active recording (capture) endpoints.

public IReadOnlyList<AudioDevice> GetRecordingDevices(DeviceStateFilter state = DeviceStateFilter.Active)

Parameters

state DeviceStateFilter

A bit mask of endpoint states to include. Defaults to Active;

Returns

IReadOnlyList<AudioDevice>

A read-only list of the active endpoints whose Kind is Recording.

GetVolume()

Returns the master volume of the default playback device, as a percentage in 0..100.

public static float GetVolume()

Returns

float

The current master volume between 0 and 100.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

InvalidOperationException

Thrown when no default playback device is set.

GetVolume(string)

Returns the master volume of the given endpoint, as a percentage in 0..100.

public static float GetVolume(string deviceId)

Parameters

deviceId string

The ID of the endpoint to read.

Returns

float

The current master volume between 0 and 100.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

ArgumentNullException

Thrown when deviceId is null or empty.

ArgumentException

Thrown when deviceId is not a well-formed endpoint ID.

COMException

Thrown when no endpoint has that ID.

IsMuted()

Returns whether the default playback device is muted.

public static bool IsMuted()

Returns

bool

true when the endpoint is muted.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

InvalidOperationException

Thrown when no default playback device is set.

IsMuted(string)

Returns whether the given endpoint is muted.

public static bool IsMuted(string deviceId)

Parameters

deviceId string

The ID of the endpoint to read.

Returns

bool

true when the endpoint is muted.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

ArgumentNullException

Thrown when deviceId is null or empty.

ArgumentException

Thrown when deviceId is not a well-formed endpoint ID.

COMException

Thrown when no endpoint has that ID.

ListDevices()

Returns snapshots of all active endpoints, in enumeration order.

public static IReadOnlyList<AudioDeviceInfo> ListDevices()

Returns

IReadOnlyList<AudioDeviceInfo>

A read-only list of snapshots of the active playback and recording endpoints.

Remarks

Returns active endpoints only. Use an AudioController instance and GetDevices(DataFlowFilter, DeviceStateFilter) to include disabled, not-present or unplugged endpoints. Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

ListDevices(AudioDeviceKind)

Returns snapshots of the active endpoints of the given kind, in enumeration order.

public static IReadOnlyList<AudioDeviceInfo> ListDevices(AudioDeviceKind kind)

Parameters

kind AudioDeviceKind

Whether to list playback or recording endpoints.

Returns

IReadOnlyList<AudioDeviceInfo>

A read-only list of snapshots of the matching active endpoints.

Remarks

Returns active endpoints only. Use an AudioController instance and GetDevices(DataFlowFilter, DeviceStateFilter) to include disabled, not-present or unplugged endpoints. Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

RegisterDeviceNotification(IAudioDeviceEvents)

Registers a callback to receive audio endpoint change notifications.

public IDisposable RegisterDeviceNotification(IAudioDeviceEvents consumer)

Parameters

consumer IAudioDeviceEvents

The consumer that will receive IAudioDeviceEvents callbacks.

Returns

IDisposable

A token that unregisters the callback when disposed. Disposing the token (or the controller) is the way to stop notifications.

Remarks

THREADING: the consumer's callbacks are raised by Windows Core Audio on arbitrary, non-UI threads and may arrive concurrently, so the implementation must be fast and thread-safe. Registering the same consumer again returns the same token for the existing registration without registering twice.

Exceptions

ArgumentNullException

Thrown when consumer is null.

ObjectDisposedException

Thrown when this controller has been disposed.

COMException

Thrown when the underlying Core Audio call fails.

SetDefaultDevice(AudioDevice, DefaultRole)

Sets the given device as the default for the requested role(s).

public void SetDefaultDevice(AudioDevice device, DefaultRole roles = DefaultRole.Default)

Parameters

device AudioDevice

The endpoint to make default. Must not be null.

roles DefaultRole

The role(s) to assign. Defaults to Default (multimedia + communications). Each set flag maps to one Role assignment.

Remarks

Roles are applied sequentially (console, multimedia, communications). If a later assignment fails, earlier assignments remain in effect; no rollback is attempted. The cached endpoint ID can be used after its wrapper is disposed and across controllers. Windows validates whether that ID still exists when applying each role.

Exceptions

ArgumentNullException

Thrown when device is null.

ArgumentException

Thrown when roles specifies no role.

ObjectDisposedException

Thrown when this controller has been disposed.

NotSupportedException

Thrown when this system does not expose the undocumented policy-config API that changing the default endpoint requires.

SetDefaultDevice(string, DefaultRole)

Sets the endpoint with the given ID as the default for the requested role(s).

public static void SetDefaultDevice(string deviceId, DefaultRole roles = DefaultRole.Default)

Parameters

deviceId string

The ID of the endpoint to make default.

roles DefaultRole

The role(s) to assign. Defaults to Default (multimedia + communications).

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

ArgumentNullException

Thrown when deviceId is null or empty.

ArgumentException

Thrown when roles specifies no role.

NotSupportedException

Thrown when this system does not expose the undocumented policy-config API that changing the default endpoint requires.

SetDefaultPlaybackByName(string, DefaultRole)

Sets the first playback endpoint whose name contains name as the default for the requested role(s). Matching is case-insensitive and takes the first match.

public static AudioDeviceInfo? SetDefaultPlaybackByName(string name, DefaultRole roles = DefaultRole.Default)

Parameters

name string

A substring of the endpoint's friendly name, e.g. "Speakers".

roles DefaultRole

The role(s) to assign. Defaults to Default (multimedia + communications).

Returns

AudioDeviceInfo

A snapshot of the endpoint that was made default, or null if no playback endpoint matched name.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

ArgumentNullException

Thrown when name is null or empty.

ArgumentException

Thrown when roles specifies no role.

NotSupportedException

Thrown when this system does not expose the undocumented policy-config API that changing the default endpoint requires.

SetDefaultRecordingByName(string, DefaultRole)

Sets the first recording endpoint whose name contains name as the default for the requested role(s). Matching is case-insensitive and takes the first match.

public static AudioDeviceInfo? SetDefaultRecordingByName(string name, DefaultRole roles = DefaultRole.Default)

Parameters

name string

A substring of the endpoint's friendly name, e.g. "Microphone".

roles DefaultRole

The role(s) to assign. Defaults to Default (multimedia + communications).

Returns

AudioDeviceInfo

A snapshot of the endpoint that was made default, or null if no recording endpoint matched name.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

ArgumentNullException

Thrown when name is null or empty.

ArgumentException

Thrown when roles specifies no role.

NotSupportedException

Thrown when this system does not expose the undocumented policy-config API that changing the default endpoint requires.

SetMute(bool)

Sets the mute state of the default playback device.

public static void SetMute(bool mute)

Parameters

mute bool

true to mute, false to unmute.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

InvalidOperationException

Thrown when no default playback device is set.

SetMute(string, bool)

Sets the mute state of the given endpoint.

public static void SetMute(string deviceId, bool mute)

Parameters

deviceId string

The ID of the endpoint to change.

mute bool

true to mute, false to unmute.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

ArgumentNullException

Thrown when deviceId is null or empty.

ArgumentException

Thrown when deviceId is not a well-formed endpoint ID.

COMException

Thrown when no endpoint has that ID.

SetVolume(float)

Sets the master volume of the default playback device from a percentage in 0..100.

public static void SetVolume(float percent)

Parameters

percent float

The desired volume. Values outside 0..100 are clamped.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

InvalidOperationException

Thrown when no default playback device is set.

SetVolume(string, float)

Sets the master volume of the given endpoint from a percentage in 0..100.

public static void SetVolume(string deviceId, float percent)

Parameters

deviceId string

The ID of the endpoint to change.

percent float

The desired volume. Values outside 0..100 are clamped.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

ArgumentNullException

Thrown when deviceId is null or empty.

ArgumentException

Thrown when deviceId is not a well-formed endpoint ID.

COMException

Thrown when no endpoint has that ID.

ToggleMute()

Inverts the mute state of the default playback device.

public static bool ToggleMute()

Returns

bool

The resulting mute state: true when the endpoint is now muted.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

InvalidOperationException

Thrown when no default playback device is set.

ToggleMute(string)

Inverts the mute state of the given endpoint.

public static bool ToggleMute(string deviceId)

Parameters

deviceId string

The ID of the endpoint to change.

Returns

bool

The resulting mute state: true when the endpoint is now muted.

Remarks

Creates and disposes an AudioController per call. For repeated operations, create one instance and reuse it.

Exceptions

ArgumentNullException

Thrown when deviceId is null or empty.

ArgumentException

Thrown when deviceId is not a well-formed endpoint ID.

COMException

Thrown when no endpoint has that ID.