Settings Reference

Settings Reference

What is on the Settings page, in the order it renders, and what each control actually does.

Some of these settings belong to a subject that has its own page, and are documented there rather than repeated here: Operating Modes, Audio Quality, Latency, Volume, Transport Tiers, Discovery and Pairing, Web Access, Share Protocols.

---

The page at a glance

Five cards, in this order:

Card	What is in it	Documented
Mode	The three-way picker — Share, A · Driverless, B · Virtual — plus the driver status line and its Install / Update / Repair / Restart Service button	Operating Modes
Options	Changes with the selected mode. Mode A: Sync volume, Mute locally, and the audio-bridge list. Mode B: Remove on disconnect, Mark names offline, and the device inventory. Share: nothing, and says so	Volume and below
Network	Advertise on LAN, the read-only Control port and IPC port rows, then Web access, Port and Local only	Discovery and Pairing, Web Access
General	Name, Fingerprint, Start at login, Launch target, Config folder, Permissions, Shortcuts	below
About	App name, version, and a link to this wiki	—

Two controls that people look for on this page are not on it: the language menu and the appearance (theme) menu live in the top bar. See Language and appearance.

Nothing on this page is applied optimistically. A switch moves only after the audio service accepts the change, so a write that fails leaves the switch where it was rather than showing a state the service never took. If the service is too old to have a settings interface at all, the switches are disabled rather than pretending to work.

---

Mode A options

Two switches and a list, shown only while Mode A is selected.

Control	Effect
Sync volume	Follows the peer's volume rather than keeping the two independent. See Volume.
Mute locally	Mutes this machine's own output when a session opens. With Sync volume also on, the card says so in place: only the level syncs, and mute stays local.
The audio-bridge list	Read-only detection status for third-party virtual cables, plus vendor links. AudioHub never installs one for you, so there is no install button here. Choosing which bridge to use is per peer and lives on the peer's card, not here. See Operating Modes.

Each detected bridge shows one of three tags: Detected, Not an output (installed, but the service cannot open it as an output device — it will not work), or Not detected. When the service reports nothing at all you get Virtual devices not reported, Service offline, or No virtual devices instead of a list.

---

Virtual device options

Shown only while B · Virtual is selected. Both switches change what happens to the virtual devices AudioHub publishes into the system's device list.

Remove on disconnect

Off (default). A peer going offline is shown as offline; its virtual devices stay in the system's device list. They remain selectable and simply process no audio.

On. Disconnect removes them. On reconnect they come back with the same UID, so applications that remembered the device keep their selection.

The default is off because the failure it prevents is worse than the clutter it causes: an application whose selected device disappears silently falls back to the system default, and the first sign of that is a call going out of the wrong speaker.

Unpairing removes the devices regardless of this setting — see unpairing.

Mark names offline

Appends an offline marker to the device name while the peer is away. The marker is localized and follows the OS-facing language, not the interface language:

OS-facing language	Marker	Example
English	" (Offline)" — leading space, capital O	AudioHub – Studio Mac (Offline)
Chinese	"（离线）" — full-width brackets, no space	AudioHub – Studio Mac（离线）

It is an in-place rename on the same UID, so remembered device selections survive it. The complete name has to fit the driver's 127-byte limit, so a very long peer label is truncated to make room for the marker.

Turning it off keeps names constant, at the price of not being able to tell "this device is silent because the peer is gone" from "this device is silent for some other reason" while looking at the system's sound settings.

The device inventory

Under the two switches, Devices lists what the driver has actually published, with a counter beside it.

The counter is peers, not devices. Both numbers are slots in the driver's slot table, and a slot holds one peer. A machine with 16 peers reads 16 / 16 while up to 32 devices exist. The ceiling is the slot count the installed driver negotiates, at most 16; with no driver the counter reads N/A.

A peer gets up to two devices, not always two. AudioHub publishes only the directions the peer says it has: a peer with no default input gets a speaker and no microphone, and a peer that reports neither gets nothing. A peer that has not yet advertised its capabilities is given both until it answers.

Each peer's block shows its label, Slot N · Gen N, an Online / Offline tag, and a status tag:

Tag	Meaning
Published	The driver acknowledged exactly the directions that were requested, and the system really lists exactly those UIDs — no more and no fewer. A peer that only has a speaker is fully published with one device.
Not listed	The driver says the slot is bound, but the system does not list what it should. The device is not usable.
Driver pending / Removing / Unpublished / Driver status unknown	The slot is in transition, or the driver has not answered for it.

Each device row shows the name, the UID, a frame counter (and a dropped count for microphones), and one of ● In use, ○ Idle, or ○ Registering.

When the inventory is empty

The list is replaced by one sentence naming the reason:

You see	Cause
The AudioHub driver is not installed…	No driver. Install it from the Mode card.
Mode A is active, so there are no virtual devices.	Mode B was selected but has been downgraded, or Mode A is genuinely selected.
After pairing a peer, it will appear in the system audio device list.	Mode B is working; there is simply no peer yet.

Individual peers can also be missing from a working list. Open that peer to see the reason under Devices on its details page: the driver is absent, the slot ceiling is reached (unpair someone to free a slot), the peer is offline and Remove on disconnect is on, or the mode does not use virtual devices at all. A peer that has told AudioHub it has neither a default input nor a default output gets no Devices block at all — that is a normal answer, not a fault.

---

Startup at login

The switch is labelled Start at login. One switch, two mechanisms, because the two operating systems disagree about where a login item lives.

	macOS	Windows
What is registered	a LaunchAgent, ~/Library/LaunchAgents/com.audiohub.app.autostart.plist	a scheduled task named AudioHubDaemon
What it launches	AudioHub via /usr/bin/open -g, so LaunchServices starts it exactly as a double-click would	audiohub-app.exe, as a hidden interactive task
Turning it off	removes the plist and unloads it	deletes the task

On macOS this is deliberately a LaunchAgent rather than a Login Item: the switch has to be operable from the service side, whereas the modern Login Item API can only be driven by the app's own process. It launches through open rather than running the executable directly so that the process keeps the same code identity the microphone and local-network permissions were granted to.

It starts the app, not a headless service — but silently. Both platforms pass --background, and the app hides its window on that flag; macOS also launches without taking focus, and the Windows task is marked hidden. Audio starts working with nothing appearing on screen. Click the tray or menu-bar icon to open the window. This is the behaviour most likely to read as "I turned it on and nothing happened".

Off leaves nothing behind. No disabled entry, no orphan task. The switch and the system's own list agree.

Where the app has to live

Registration is refused unless AudioHub is in an installed layout:

• macOS — the audio service must be inside an *.app bundle, or inside the version directory the app's authenticated installer creates under /Library/Application Support/AudioHub/service/versions/. In that second case the login item always points at /Applications/AudioHub.app, so keep the app there.
• Windows — audiohub-app.exe must sit next to the audio service executable.

A development tree or a bare binary satisfies neither, which is the usual reason the switch cannot be turned on.

When the switch says something odd

It reports more than on and off, because "can this build register one" and "is one registered right now" are separate facts and all four combinations happen.

State	What you see	What to do
On / off	The ordinary pair.	—
Cannot be registered	This version cannot configure automatic startup. The switch is disabled.	Check the layout rules above. The message names no specific cause — the service works one out, but this build does not display it.
Registered, but not by this build	Installed AudioHub.app still starts at login. This build can't retarget it, but can turn it off. The switch stays usable.	This is the only way out of "something starts at login and I cannot find it". Switch it off.
Not reported	This service does not support automatic startup settings. It may be an older version.	The audio service sent nothing about startup at all, so the app cannot say whether a login item exists.

While the switch is on, a Launch target row shows the path the login item actually points at. If that is not the AudioHub you think you are running, this row is where that becomes visible.

---

Identity

Two rows in General, both about this machine rather than this program.

Name

What peers see, and the label that appears inside the virtual-device names on every peer's machine. Leave it empty to follow the computer name — the field shows Use device name as its placeholder and Default restores that.

The row says it in place: renaming also renames the virtual devices on every peer, and each peer picks the new name up on its next connection, not immediately.

If the environment variable AUDIOHUB_NAME is set, the field is read-only and says so.

Fingerprint

The full fingerprint, as a button — clicking it copies. This is the value peers pin. See fingerprints.

Reset

The Reset button beside the fingerprint generates a new key pair. It is the most destructive control in the app, so it asks twice: a sheet that shows your current fingerprint and the number of paired peers, then a confirmation dialog repeating the count.

Afterwards every peer that had you paired sees a different fingerprint and refuses the connection until you pair again — that is the pinning working, not a bug. The service may report that a restart is needed for the new identity to take effect, and if so the app says so rather than pretending it is already live.

---

Permissions

General › Permissions shows a count and a pending count, and Open raises the permission panel. It is the same panel that can appear on its own when permissions are missing, and it is the way back for anyone who skipped the first-run gate. It is also the only place that covers the permissions that gate never stops on: local network, whose state macOS will not report, and system audio, which AudioHub treats as optional.

What each permission means per platform, and how to grant one after refusing it, is on Platform Notes.

---

Keyboard shortcuts

General › Shortcuts › Open raises the shortcut sheet; so does the shortcut for it. The sheet lists five actions:

Action	macOS	Windows
Peers	⌘1	Ctrl+1
Stats	⌘2	Ctrl+2
Settings	⌘,	Ctrl+,
Back	⌘[	Alt+←
Shortcuts	⌘/	Ctrl+/

⌘3 / Ctrl+3 also opens Settings. It is a fixed alias, not a listed row, so it cannot be edited — and it yields to any binding you put on that same chord. Esc always closes or cancels and cannot be rebound; the sheet lists it for that reason.

Click a key capsule and press the combination you want. Notes:

• Edits are a draft until you save. Recording, Clear, per-row Reset and Reset all all change the sheet's draft; Save commits it and Cancel throws it away.
• Shortcuts always yield to text fields. Typing a digit into the port box must not switch pages.
• At least one modifier is required, except function keys. F1 through F24 can be bound bare because no text field claims them. (The app's own error message says F1–F12; the code allows the full range.)
• The OS wins, and it is refused outright. On macOS: ⌘Q, ⌘W, ⌘M, ⌘H, ⌥⌘H, the clipboard set (⌘X ⌘C ⌘V ⌘A ⌘Z ⇧⌘Z), ⌘Space, ⌃Space, ⌘Tab, ⌥⌘Esc, ⌘`, ⇧⌘3/4/5, ⌃⌘F. On Windows: Alt+F4, Alt+Tab, Alt+Space, Ctrl+Shift+Esc, Ctrl+Alt+Del. If the recorder seems to ignore your keypress, that is why, and it says so after a moment.
• Some combinations are accepted with a warning. The ones the embedded browser normally claims — ⌘R/Ctrl+R, ⌘F/Ctrl+F, ⌘P/Ctrl+P, the zoom set, F5, F12, Ctrl+Shift+I — can be bound, but may not reach AudioHub reliably. The recorder warns instead of refusing.
• Taking a combination from another action leaves that action unset. You are asked first. The action that loses its shortcut is left with none rather than falling back to its default; use Reset on that row to get the default back.
• Clearing is not the same as resetting. A cleared shortcut stays cleared across restarts rather than quietly reverting to the default.
• Chords are matched by physical key, not by the character produced. ⌥1 on macOS produces "¡"; on a non-US layout almost everything shifts. Binding to the physical key means "the 1 key" stays the 1 key when you change layout.

They are stored per interface. The storage is the browser's, scoped to the origin, so the desktop window and a tab opened through web access keep independent sets. This is deliberate — shortcuts are a property of the machine you are typing on — but it does mean "I set that already" can be true and invisible at the same time.

---

Language and appearance

Neither control is on the Settings page. Both are in the top bar, and both are stored per interface in the browser's storage, exactly like the shortcuts above — a browser tab can render in a different language and a different theme from the desktop window.

Language offers three entries: System (the default), 简体中文, and English (US). System matches your OS language list by exact tag first and then by primary subtag, so an en-GB system gets the en-US catalogue and a zh-Hant system falls back to zh-CN. An unrecognised stored value falls back to System.

Appearance cycles System / Light / Dark.

There is a second, separate language value that is machine-wide: the one the operating system sees. It decides the language of the virtual-device names and the offline marker described above, and there is only one of each of those names in the system's device list, so it cannot be per client. Only the desktop app pushes it; a browser tab set to English will not rename anyone's devices. It is also never guessed by the audio service, because a background service's locale can differ from the interactive user's. An unrecognised value falls back to zh-CN.

---

About

App name, tagline, the build version, and a link to this wiki. The version shown here is the one to quote in a bug report. If it renders as —, the build did not have a version stamped in — AudioHub shows a dash rather than inventing one.

AudioHub has four independent version numbers (app, audio service, macOS driver ABI, Windows driver ABI) and they are deliberately not the same; this row is the app's.

---

AirPlay receiving

The AirPlay receiver has three stored settings — enabled, advertised name, and password. They are documented with the feature in Share Protocols, not here, because the password in particular carries security consequences that only make sense next to the protocol description. The receiver is off by default, and its controls appear on the Sharing tab, which exists only in Share mode.

---

Paths

General › Config folder shows the directory. Everything AudioHub keeps between runs is in it:

Platform	Default
macOS	~/Library/Application Support/AudioHub
Windows	%APPDATA%\AudioHub

File	Holds
identity.json	the key pair behind your fingerprint, and the name override
paired_peers.json	the pairing table
settings.json	the audio service's settings — mode, both virtual-device switches, the Mode A switches, advertising, the OS-facing language
peer_transport.json	per peer and per direction: latency target, quality, connection method, dial policy, tunnel address, last known address
hal_slots.json	which peer holds which virtual-device slot
airplay-password	the AirPlay receiver password, kept out of settings.json because that file is handed over the local interface routinely
airplay2-identity	the receiver's AirPlay identity, so senders that have paired with this machine stay paired
airplay2-port	the control port the AirPlay receiver settled on, so it can claim the same one next time (why it matters)
webui.json	the web access settings — they belong to the app, not the audio service
ipc.json	how the interface reaches the audio service on this machine (details)
service-installed-v1	marker written when the background service is installed
app.log, daemon.log	what the app and the audio service wrote, each rotated once to .log.1 past 1 MB

Deleting this directory discards the identity, every setting on this page, every per-peer transport choice, the slot table, the AirPlay password and the web-access configuration. Every peer that had you paired will then see a different fingerprint and refuse the connection until you pair again — the pinning working as designed rather than a bug. If discarding the identity is what you actually want, Reset does that one thing and tells you how many pairings it will destroy first.

AUDIOHUB_CONFIG_DIR overrides the location. Pointing it at a throwaway directory is how the regression suite runs a second instance without touching your real pairings. Two conditions make or break it:

• The app and the audio service each read the variable from their own environment; there is no channel that carries the value from one to the other. It has to be set in the environment that launches AudioHub — starting the app from Finder or the Start menu will not inherit a variable you exported in a terminal.
• An already-running audio service keeps the directory it started with until it is restarted.