Skip to content

Add device priority chain with automatic failover - #72

Open
MaximKotliar wants to merge 4 commits into
briankendall:masterfrom
MaximKotliar:feature/device-priority-chain
Open

MaximKotliar wants to merge 4 commits into
briankendall:masterfrom
MaximKotliar:feature/device-priority-chain

Conversation

@MaximKotliar

@MaximKotliar MaximKotliar commented Jun 29, 2026 •

Copy link
Copy Markdown

Summary

Adds a device priority chain to the Proxy Audio Device. Instead of proxying to a single fixed output device, you configure an ordered list of devices and the driver automatically routes audio to the highest-priority one that is currently available — falling through to the next when a device disconnects, and (optionally) switching back up when a higher-priority device returns.

It also makes volume smarter: the proxy now drives the target device's own hardware volume when it has one, and remembers each device's volume so switching restores the level you last used.

This is useful when you regularly move between outputs (e.g. a USB DAC / audio interface at your desk, Bluetooth headphones, and the built-in speakers as a last resort) and want the proxy to "just follow" your preferred device without manual reconfiguration.

Behavior

Priority chain

  • The proxy routes to the highest-priority device that is present and alive.
  • When the active device is removed or goes not-alive, it advances down the chain immediately.
  • Automatically switch back to higher-priority devices (checkbox, on by default): when a higher-priority device returns, switch back up to it. Turn it off for "sticky" behavior — stay on the current device until it too becomes unavailable.
  • When no listed device is available, it falls back to the current system default output device (excluding the proxy itself), so audio is never silently dropped. This fallback is never sticky — as soon as any listed device returns, the proxy switches to it.
  • Existing hide when unavailable still works; with the fallback in place it now only triggers when there is no output device available at all.

Volume

  • If the active device exposes a settable hardware volume, the proxy drives that directly, so the system volume keys change the real device's volume. Devices without hardware volume keep using the existing software attenuation. Software gain is bypassed whenever hardware volume is in use, so the signal is never attenuated twice.
  • Per-device volume memory: each device's level is remembered by UID. Switching to a device (including via automatic failover) restores the volume it was last left at and updates the system volume display. The first time a device is seen, the current level carries over and is then remembered.
  • Mute is always applied in software so it works regardless of the device.

Implementation

Driver (proxyAudioDevice/)

  • The single stored output-device UID becomes an ordered chain of UIDs — a CFArray in plugin-host storage, serialized newline-delimited over the existing identify/name configuration channel.
  • New selection step walks the chain, picks the highest-priority present-and-alive device, honors the auto-failback/sticky setting among listed devices, and falls back to the system default otherwise.
  • The per-device kAudioDevicePropertyDeviceIsAlive listener now re-evaluates the chain immediately (a dying device does not always disappear from the device list, so we can't rely solely on the device-list listener).
  • Volume: AudioDevice gains hasSettableVolumeControl() / setVolumeScalar(); the IO proc bypasses software gain when hardware volume is active; per-device levels are stored as a UID→volume dictionary in plugin-host storage and restored on each device switch.
  • New ConfigTypes: outputDevicePriorityList, outputDeviceAutoFailback, and read-only currentActiveOutputDevice (so the settings app can mark the active row).

Settings app (ProxyAudioDeviceSettings/)

  • The output-device combo box is replaced with an editable, ordered list (NSTableView) plus add / remove / move-up / move-down controls and the auto-failback checkbox (built programmatically).
  • Each row shows its status (Available / Unavailable / ● Active) using the same present-and-alive test as the driver.
  • Display names are cached in the app's own preferences, so devices that are currently disconnected still show a friendly name instead of a raw UID.
  • The list refreshes on device-change notifications and via a light poll, but only redraws when the displayed data actually changes, so the table keeps its selection/focus while you reorder.

Notes for the maintainer

  • Deployment target raised to macOS 14.6. The project no longer builds against the 10.11 SDK on current Xcode, so I bumped it to get a clean build. The new code itself doesn't require a floor this high — please lower it to whatever you can actually test/support. I don't have a setup to verify older macOS versions.
  • No migration: existing users' previously-selected single device is not carried over into the new chain; they'll pick their devices once after updating. Happy to add a one-line fallback that seeds the chain from the old outputDeviceUID storage key if you'd prefer.
  • Tested locally: ad-hoc-signed build installed to /Library/Audio/Plug-Ins/HAL, verified failover down, failback up, the system-default fallback, hardware + software volume, per-device volume restore, and the live status/active updates by connecting/disconnecting real devices.

Screenshot

Proxy Audio Device Settings 2026-06-29 14 48 24

Replace the single target output device with an ordered priority chain.
The driver routes audio to the highest-priority device that is currently
present and alive, advancing down the chain when the active device is
removed or dies, and switching back up when a higher-priority device
returns. When no listed device is available it falls back to the system
default output device (excluding the proxy itself), which is never sticky.

- Store the chain as an ordered list of device UIDs: a CFArray in plugin
  storage, newline-delimited over the existing configuration channel
- New ConfigTypes: outputDevicePriorityList, outputDeviceAutoFailback
  (default on), and read-only currentActiveOutputDevice for the UI
- The device-is-alive listener now advances the chain immediately instead
  of only deinitializing, so a dying active device fails over at once
- Auto-failback governs preemption among listed devices only; the
  system-default fallback is always abandoned as soon as a listed device
  returns
Replace the single output-device combo box with an editable, ordered
priority list (NSTableView) plus add / remove and move up / down
controls, and an "Automatically switch back to higher-priority devices"
checkbox.

- Each row shows its status (Available / Unavailable / Active) using the
  same present-and-alive test the driver uses to select a device
- Device display names are remembered in the app's own preferences so
  disconnected devices still show a friendly name rather than a raw UID
- The list refreshes on device changes and via a light poll, but only
  redraws when the displayed data actually changes, so the table keeps
  its selection and focus while reordering
@MaximKotliar
MaximKotliar marked this pull request as ready for review June 29, 2026 13:03
@briankendall

Copy link
Copy Markdown
Owner

This is a big change, so I'll try to take a look at the contents of the PR soon. However, there is at least one major issue with it, which is increasing the minimum macOS version to 14.6. I routinely use ProxyAudioDevice on systems older than macOS 14 so in order to merge this I'd need you to fix that. If there are any APIs you are using that require a newer release of macOS than 10.11 let me know and I'll consider increasing the minimum system requirement, though at the moment I'd prefer not to raise it past 10.13, and given this is an AppKit application and using longstanding CoreAudio APIs I don't see why that would be necessary on first glance. (I'm persnickety about supporting older versions of macOS!)

When the active output device exposes a settable hardware volume, drive
that directly from the proxy's volume control instead of attenuating in
software, so the system volume keys change the real device's volume. On
devices without a hardware volume control, attenuation continues in
software as before. Software attenuation is bypassed whenever hardware
volume is in use so the signal is never attenuated twice.

Each device's level is also remembered by UID: switching to a device
(including via automatic failover) restores the volume it was last left
at and updates the system volume display. The first time a device is seen
its current level carries over and is then remembered. Mute is always
applied in software so it works regardless of the device.
The priority-list UI used +[NSTextField labelWithString:],
+[NSButton checkboxWithTitle:...] and +[NSButton buttonWithTitle:...],
which are all 10.12+. Build the label, checkbox, and push buttons with
alloc/init and property setters instead, so the project's deployment
target stays at macOS 10.11 (no bump required).
@MaximKotliar
MaximKotliar force-pushed the feature/device-priority-chain branch from 57d337e to 189691f Compare June 30, 2026 09:24
@MaximKotliar

Copy link
Copy Markdown
Author

Thanks for taking a look, and sorry about the version bump — you're right that it wasn't actually necessary. It crept in because the Xcode I'm on dropped the 10.11 SDK and refused to build the project, so I bumped the target locally to get a clean build and it ended up in the PR. That was the wrong fix.

I've now:

  • Dropped the deployment-target change entirely — the project stays at macOS 10.11 (the project.pbxproj diff vs master is back to zero).
  • The only APIs that required newer than 10.11 were three AppKit convenience constructors in the new settings UI — +[NSTextField labelWithString:], +[NSButton checkboxWithTitle:target:action:] and +[NSButton buttonWithTitle:target:action:] (all 10.12+). I've rewritten those to plain alloc/init + property setters, which are 10.11-era. Everything else is longstanding AppKit/CoreAudio, as you expected.

One caveat: because my Xcode won't target anything below 11.0, I couldn't do a local build at the 10.11 deployment target to confirm there are no remaining unguarded-availability errors — I verified by auditing API availability instead. If you're able to build it on your setup, I'd appreciate a sanity check that it's clean at 10.11. Happy to adjust if anything else turns up.

@briankendall

Copy link
Copy Markdown
Owner

Great, thanks. Also, I gather you've used AI in some capacity to make these changes and write these messages. Can you say more about how you used it and how closely you've personally reviewed and tested these changes?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants