Operating Modes

Operating Modes

AudioHub is one application with three operating modes. Exactly one is active at a time, and the choice is global to the machine — not per peer.

Mode	Picker label	Others can use this machine	This machine can use others
Share	Share	yes	no
Mode A — driverless	A · Driverless	no	yes
Mode B — virtual devices	B · Virtual	no	yes

Switching modes takes effect immediately and needs no confirmation. The control is the first card on the Settings page (Settings › Mode). The main panel has no mode control.

A fresh install is in Share mode. It is the only mode that needs neither a driver nor a system-audio permission, so a newly installed machine does nothing until someone picks Mode A or Mode B. That is intended, not a fault.

The options belonging to the selected mode are in the next card down (Settings › Options), and they change with the mode: Share has none, Mode A has the volume switches and the audio-bridge detection list, Mode B has the virtual device options.

---

Share mode

The machine offers its default microphone and default output to paired hosts.

• Its microphone can be drawn by several peers at once (fan-out).
• Several peers can send audio to it at once (mixed on arrival).
• It uses no peer's devices itself.

This is the baseline form of the application: pure user space, no driver, no special privileges.

AirPlay receiving belongs to this mode too. It is the one path that accepts audio from a device that is not an AudioHub peer at all — a phone, a tablet, some visitor's laptop. It runs only in share mode; see Share Protocols.

Leaving share mode stops the receiver, but the switch itself is remembered: return to share mode and the receiver comes back by itself, without you re-enabling it.

---

Mode A · Driverless

No driver required. Mode A works on any supported machine out of the box. Its controls are on each peer's card in the main panel.

Sending to the peer's speaker (Peer speakers). AudioHub captures this machine's system audio and sends it to the peer's default output. The audible result is that both machines play the sound — the capture is a side tap, and this machine's output device is untouched. Per peer, the Source control switches between System audio and Microphone.

There are two optional volume switches for this direction in Settings › Options (Sync volume, Mute locally); see Volume.

Taking the peer's microphone (Peer mic). This is where driverless hits a wall: without a driver, nothing can inject a new entry into the system's input device list. So Mode A offers two destinations for it:

• Monitor — play the peer's microphone through this machine's own output. Needs nothing installed.
• Audio bridge — write it into a third-party virtual cable so that other applications can select it. Described below.

They are independent: one decode can feed both at once.

AudioHub does not record. There is no record-to-file control anywhere in the application. To capture the peer's microphone to disk, bridge it to a virtual cable and point a recorder at that cable's input.

Controls a peer does not have are not shown

AudioHub only offers the directions a peer actually advertises. A peer with no default microphone shows no Peer mic toggle, no Monitor and no audio bridge; a peer with no default output shows no Peer speakers block; a peer with neither shows no audio controls at all. This is normal — check that machine's own system sound settings, not this one's.

The capture backend

Sending system audio needs a capture backend, and there is more than one. The Backend picker offers Auto, which asks the service to take the best available one, and it can be pinned per peer. Which backends exist and what each costs is platform-specific — see Platform Notes.

Two properties hold on every backend: the capture is a side tap, so this machine's output device and its volume are untouched, and you are never asked to switch your system output to some virtual device. That workflow is a project-wide red line, not an omission.

One backend is worth knowing about before you pick it: Windows Device loopback taps the render endpoint, so it also captures AudioHub's own playback. With audio flowing both ways that is a feedback path. Every other backend excludes this process tree's own output, and Process loopback — available from Windows 10 version 2004 — is preferred wherever it exists.

These per-peer choices are not remembered

The bridge target, the capture source and the capture backend are per-peer choices that live only in the running interface. Closing AudioHub loses them, and the next launch starts from the defaults again. The pairing and the daemon's own settings survive; these three do not.

---

Bridging to a third-party virtual cable

The control is called Audio bridge, on each peer's card. It is the only way a driverless install can put the peer's microphone in front of other applications: write it into a virtual cable that someone else signed and shipped.

How it works. AudioHub writes the peer's microphone into the selected card's playback side. Any application that selects that card's input side is then listening to the peer's microphone. AudioHub is a producer on one end of a loopback cable that already exists on your machine.

The interface calls third-party cables virtual devices too, which collides with the name of AudioHub's own Mode B devices. Inside the Audio bridge control, that phrase always means a third-party card. The bridge is a Mode A feature and does not involve the AudioHub driver at all.

AudioHub neither installs nor bundles them. They are third-party drivers with their own signatures and their own maintenance; shipping someone else's kernel-adjacent code inside this app is not a trade worth making. Install one, restart AudioHub, and it becomes selectable. If none is detected the picker is greyed out and two vendor links are offered instead — no nagging, no "install now" button:

Vendor	Link
BlackHole	https://existential.audio/blackhole/
VB-Cable	https://vb-audio.com/Cable/

Both links are shown on both platforms, with the one matching your platform first. Detection is not limited to those two: Voicemeeter is recognised under the VB-Cable entry, and device names matching soundflower, loopback audio, virtual audio or virtual cable are offered as well.

Which card is chosen is a per-peer choice, on the peer's card, not a global one. The set of detected cards is global; the choice is not.

The control refuses to fail silently, and the four things it can say are different problems:

What the control says	What it means	What to do
"…" is not currently detected	A card you had selected has been uninstalled or failed to load. The selection is kept in the list, marked (missing), and audio is not bridged.	Pick another card, or reinstall that one and restart AudioHub.
Detected but unavailable as a system output	The card is installed and visible, but the system does not offer it as an output AudioHub can open. Usually a partial or failed driver install.	Reinstall the cable and confirm it appears in the OS sound output list.
No virtual device	Nothing matching was found.	Install one of the two above.
Not reported	The service did not report virtual devices at all.	The service is old or not answering; check that it is running.

Settings › Options carries the same detection as a read-only list, tagging each known card Detected, Not an output or Not detected.

---

Mode B · Virtual devices

With the AudioHub driver installed, each paired host appears in the system audio device list as up to two devices — a speaker and a microphone named after that host. Any application can select them from its normal device menu; nothing needs to know AudioHub exists.

Publishing is per direction, not per pair. The service asks each peer what default endpoints it has: a peer with no default input publishes no virtual microphone, a peer with no default output publishes no virtual speaker, and a peer with neither publishes nothing. A missing microphone on a headless peer is the expected outcome, not a fault.

Both devices of a peer carry the same visible name; the operating system's own device class distinguishes input from output. See device naming.

Semantics unique to Mode B:

• Devices appear on pairing, not on first use — with conditions; see pairing.
• Adjusting the virtual device's volume adjusts the peer's real device — except when that device has no volume control of its own (a macOS aggregate or multi-output device is the standard case), where the slider moves AudioHub's own send-side gain instead and the peer's device is never touched. See Volume.
• When a peer disconnects, the devices by default stay in the list, passing no audio, with an offline marker appended to their names — Mark names offline, on by default. Remove on disconnect makes disconnection remove them instead; either way they return under the same UID on reconnect, so applications do not lose a remembered selection. Both switches are in Settings › Options; see virtual device options.
• Unpairing removes them unconditionally on the machine you do it from. The peer is told as well, but only if it is connected at that moment — an offline peer keeps its copy until it next dials you. See unpairing.

Capacity

Up to 16 peers, so up to 32 virtual devices — the exact number is whatever the installed driver offers, and the Devices row in Settings › Options shows used / capacity. A peer beyond the limit stays paired but gets no devices, and its card says so: "The 16-device limit has been reached. Unpair another peer to free a slot."

When the driver is not ready

Mode B's availability is reported on the Mode card itself, and the states are not interchangeable:

State	Mode B selectable?	What you see	What to do
Service disconnected	no	Driver availability can't be determined yet	Wait for the service to come up
Driver absent	no, greyed out	No AudioHub driver was detected, so Mode B is unavailable	Install the driver — the button is on this same card
Version mismatch	yes, card turns red	The driver and service versions don't match, with both numbers shown. Not one AudioHub device appears in the system while everything else looks healthy	Press Update Driver on the same card
Detached	yes	Driver registered, bridge connection not ready. Published devices stay in the system list but pass no audio	Wait a moment, or Restart Service
Ready	yes	Driver connected	—

A version mismatch is deliberately not greyed out: greying it would put the Update Driver button out of reach of the person who needs it. It is also the one driver fault a restart cannot clear — the symptom is an empty system device list with no error anywhere else, which is unguessable unless the card says so.

When Mode B is selected but the driver is absent, the machine falls back to Mode A and says so: "Mode B is selected but unavailable, so AudioHub is temporarily running in Mode A."

The driver is installed from inside AudioHub. The Mode card carries an Install / Update / Repair button next to the mode picker. It asks for system authorization and briefly pauses system audio while the driver loads; on Windows it can require a restart to finish. See Platform Notes for what "driver available" means on each OS — on Windows, the honest answer for end users is currently not available.

---

Why the modes are mutually exclusive

This is the part that surprises people, so it is worth the space.

A machine that both shares and consumes creates two concrete failures.

Silent relay

Host X shares its default microphone with host Y. X is also in Mode B, and X's default input happens to be "AudioHub – Z".

Y now receives Z's microphone, not X's. X has become a relay without anyone choosing that, and without any screen saying so. The same applies in the speaker direction: audio Y sends to X's default output lands on Z's virtual speaker and is forwarded onward.

Loop

If Z is in turn using X, the path closes on itself. Audio circulates, and latency grows without bound until some buffer stage saturates. Nothing in the pipeline pushes back on this; it is a topological problem, not a tuning problem.

The consequences of the rule

Three follow directly, and all three are user-visible:

1. Mode is advertised to peers. A host in Mode A or Mode B is listed as Unavailable rather than failing when you try, with the reason spelled out — "This host is in Mode A and is using another host's devices. Switch it to Share mode." — because "that machine is in Mode B" and "that machine is switched off" deserve different next steps. The advertisement is a courtesy that lets the interface grey an entry out early; the actual refusal is enforced by the machine being asked.
2. Switching mode disconnects. The switch closes every session the new mode does not permit and tells the peers on the other end. AudioHub does not refuse the switch; it performs it and says what happened.
3. Mode B's virtual devices exist only under Mode B. Switching away removes them from the system list rather than leaving them present and silent.

It is stricter than strictly necessary

We know. There are safe configurations this rule forbids — X sharing its real microphone while consuming Z's speaker involves two paths that never intersect, and is harmless.

The rule is still absolute, because which device is being shared depends on the system default device. A user changing one system setting can turn a safe configuration into a relay, and AudioHub observes that change only passively. Detecting loops at runtime is more complex and more prone to false positives than declining to enter the situation at all.

If this proves too restrictive in practice it can be relaxed later to per-direction adjudication plus runtime loop detection. It should not be the first version's behaviour.