audioswitch/README.md

audioswitch

A global hotkey that cycles the Windows 11 default audio output, and a flyout that tells you where you landed.

No tray icon, no window, no settings dialog. One 300 KB executable that sits in GetMessageW at 0% CPU until you press the key.

Ctrl+Alt+A  ->  Casque (FiiO USB DAC)
Ctrl+Alt+A  ->  Haut-parleurs (Focusrite USB Audio)
Ctrl+Alt+A  ->  Haut-parleurs (Steam Streaming Speakers)

Behaviour

• One hotkey, forward through a list. Configure which outputs are in the cycle and in what order, or leave it unconfigured and cycle everything that is plugged in.
• Console and Multimedia roles only. Windows keeps three separate defaults; the Communications one is left alone by default, so a headset stays pinned for voice chat while media follows the hotkey. Change it with roles = if you disagree.
• Stays in sync. Switch outputs from the Windows volume flyout, or unplug a DAC, and the next press continues from what Windows actually has selected.
• Never steals focus. The flyout is click-through and non-activating, so pressing the hotkey mid-game or mid-sentence does not pull you out of what you were doing.

Build

Everything happens in the devcontainer — nothing is installed on the Windows side, and the resulting binary imports only system DLLs.

cargo build --release
# -> target/x86_64-pc-windows-gnu/release/audioswitch.exe

The container cross-compiles with mingw-w64 but cannot launch a Windows process, so deploying is a host-side step. From a WSL shell outside the container:

scripts/deploy.sh      # copies to %LOCALAPPDATA%\AudioSwitch and (re)starts it

Use

deploy.sh puts the binary at %LOCALAPPDATA%\AudioSwitch\audioswitch.exe. It is not on PATH, so out of the box every invocation is a full path. In PowerShell:

& "$env:LOCALAPPDATA\AudioSwitch\audioswitch.exe"            # run in the background
& "$env:LOCALAPPDATA\AudioSwitch\audioswitch.exe" --list     # and so on

or from cmd.exe:

"%LOCALAPPDATA%\AudioSwitch\audioswitch.exe" --list

That gets old fast. Pick one of these once and the short commands below work as written:

# A profile function - run `notepad $PROFILE` and add:
function audioswitch { & "$env:LOCALAPPDATA\AudioSwitch\audioswitch.exe" @args }

# ...or put the folder on your user PATH (affects new terminals only):
$old = [Environment]::GetEnvironmentVariable('Path', 'User')
[Environment]::SetEnvironmentVariable('Path', "$old;$env:LOCALAPPDATA\AudioSwitch", 'User')

Verbs

audioswitch                  Run in the background (single instance)
audioswitch --list           List outputs and their endpoint IDs
audioswitch --config         Create/open the config file
audioswitch --refresh        Update config device IDs to match current outputs
audioswitch --quit           Stop the running instance
audioswitch --autostart on   Start with Windows (off to undo)

--autostart records the full path of the exe as it was when you ran it, so it does not care about PATH either way.

The verbs that print borrow the terminal they were launched from. Because this is a GUI-subsystem binary, a shell may hand back the prompt before the output arrives; pipe it (audioswitch --list | Out-String) if the interleaving bothers you.

Config

%APPDATA%\audioswitch\config.ini, created by --config already populated with the outputs you have right now. Edits apply on the next hotkey press — no restart.

hotkey = ctrl+alt+a
roles = console,multimedia
osd_position = bottom-center     ; top-center, center, bottom-right, top-right
osd_duration_ms = 1400
osd_fade = false

; Cycle order. Comment out a line to drop that output.
; Delete the whole section to cycle every active output instead.
[devices]
{0.0.0.00000000}.{a51fdbbf-...} = Casque (FiiO USB DAC-E07K)
{0.0.0.00000000}.{ff879682-...} = Haut-parleurs (Focusrite USB Audio)

Windows sometimes gives a device a new endpoint ID. Plugging a DAC into a different USB port is the usual cause, and its name gains a 2- prefix as well. The old line then silently drops out of the cycle. audioswitch --refresh fixes this. It moves each stale line to the present output with the same name (ignoring that prefix), keeps your order and comments, and adds outputs the file doesn't mention yet as commented-out lines. The previous file is kept as config.ini.bak.

osd_fade is off by default. Fading needs WS_EX_LAYERED, which on some builds suppresses the acrylic backdrop that makes the flyout look like part of the shell. Turn it on and see which you prefer on your machine.

Known limitations

• Elevated windows swallow the hotkey. RegisterHotKey does not fire while a window running as administrator has focus, unless this app is elevated too. Inherent to the API.
• WASAPI exclusive-mode apps do not follow. Some DAWs and games hold an endpoint open exclusively and keep playing to the old device until restarted.
• Exclusive-fullscreen games hide the flyout. The switch still happens; a topmost window simply cannot draw over an exclusive-fullscreen swap chain.

The undocumented bit

Windows exposes no public API for setting the default audio endpoint. Like every other tool in this space, this one uses the undocumented IPolicyConfig COM interface (CLSID {870af99c-…}, IID {f8679f50-…}). It has worked from Vista through current Windows 11 builds, but it is not contractual.

It is confined to src/policy.rs — about forty lines, all of it the vtable declaration. Everything else (enumeration, change notifications, the hotkey, the flyout) is documented Win32. If a Windows update ever breaks this tool, that is the file to look at first.