AudioDeviceLib 1.0.0-rc.3

AudioDeviceLib

A small .NET library for Windows audio devices. Enumerate playback and recording endpoints, choose defaults, control volume and mute, and receive device and session notifications directly from C#.

Documentation and API reference

Table of contents

• Requirements
• Installation
• Quick start
• Working with devices
• Notifications
• Lifetime and threading
• API
• Compatibility and diagnostics
• Build and test
• Documentation
• Contributing
• License and credits

Requirements

• Windows with Core Audio support.
• A compatible .NET runtime. The package targets net48, netstandard2.0, and net8.0-windows; targeting .NET Standard does not make it cross-platform.
• No runtime NuGet dependencies. Audio access uses Windows COM interop.

Use a normal JIT deployment. Native AOT and trimming are not supported.

Installation

Install from NuGet:

dotnet add package AudioDeviceLib --prerelease

The command includes prerelease versions. Import AudioDeviceLib for the main API and AudioDeviceLib.CoreAudioApi for volume, session, property, and event types.

Quick start

Static methods handle resource cleanup and return managed results. They are useful for occasional operations; use a controller instance for repeated work.

using System;
using AudioDeviceLib;

foreach (var device in AudioController.ListDevices(AudioDeviceKind.Playback))
{
    Console.WriteLine(device);
}

var playback = AudioController.GetDefaultPlayback();
if (playback != null)
{
    AudioController.SetVolume(playback.Id, 50f);
    AudioController.SetMute(playback.Id, false);
}

Convenience methods without a device ID operate on the default playback endpoint. Volume percentages use a range of 0-100; lower-level scalar APIs use 0-1.

Working with devices

Use a controller instance for repeated operations on a live device:

using AudioDeviceLib;

using var audio = new AudioController();
using var device = audio.GetDefaultPlaybackDevice();
if (device != null)
{
    device.SetVolumePercent(50f);
    device.IsMuted = false;
}

See working with devices for enumeration, snapshots, and default-device selection.

Notifications

Subscribe to device, volume, and session changes. See the notifications guide for registration and examples.

Lifetime and threading

Dispose live audio objects and handle callbacks safely. See lifetime and threading for ownership, cleanup, and callback rules.

API

See the full API reference for public types, method signatures, overloads, and member documentation.

The quick start demonstrates static methods, while working with devices demonstrates public instance methods. For more guidance, visit the documentation website.

Compatibility and diagnostics

Device enumeration and audio controls use Windows Core Audio. Changing the default device depends on the undocumented policy-configuration interface and may be unsupported on some Windows configurations. COM must be available on the calling thread.

Callback and cleanup failures are reported through System.Diagnostics.Trace. Configure a trace listener when you need diagnostic output.

Build and test

Run from the repository root on Windows:

dotnet build AudioDeviceLib.slnx -c Release
dotnet test Library.UnitTests/Library.UnitTests.csproj -c Release -m:1

Tests cover the three shipped assets through .NET Framework 4.8, .NET 7, and .NET 8 hosts. The .NET 7 host exercises the .NET Standard asset. Run targets serially because hardware tests share the machine's audio devices.

Some integration tests change volume or mute and restore the previous settings. Session metadata tests create their own silent session. Tests that require an audio endpoint skip when none is available. Explicit race tests run separately:

dotnet test Library.UnitTests/Library.UnitTests.csproj -c Release -m:1 --filter FullyQualifiedName~ControllerDisposeRaceTests

Enable the repository's pre-commit hook in each clone:

git config core.hooksPath .githooks

The hook runs the Slopwatch code-quality check before committing.

Optional code-quality and coverage checks:

dotnet tool restore
dotnet slopwatch analyze --fail-on warning
dotnet test Library.UnitTests/Library.UnitTests.csproj -c Release -m:1 --settings coverage.runsettings --collect:"XPlat Code Coverage" --results-directory TestResults
dotnet reportgenerator -reports:"TestResults/**/coverage.opencover.xml" -targetdir:coverage -reporttypes:"Html;TextSummary"

Documentation

The documentation website includes usage guides and a generated public API reference, using DocFX's modern theme.

With the repository SDK installed, build and preview from the repository root:

dotnet tool restore
dotnet docfx docfx/docfx.json --warningsAsErrors
dotnet docfx serve _site

Open http://localhost:8080. See the documentation contributor guide for editing and GitHub Pages setup. In Settings > Pages, select GitHub Actions; .github/workflows/docs.yml validates pull requests and deploys from main.

Contributing

See the contribution guide for build, test, documentation, and release publishing notes.

License and credits

AudioDeviceLib is licensed under MIT.

The managed device API derives from AudioDeviceCmdlets by Francois Gendron (MIT). Its PowerShell layer was replaced with a plain managed API. The Core Audio interop incorporates Ray Molenkamp's wrapper under its zlib-style license.

See third-party notices for attribution and license terms, and modifications for the changes to incorporated code.