-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
A symptom index. Find the thing you are seeing, not the subsystem you suspect.
Several messages in AudioHub end with "Check the service log." This page is also where that log lives — see Where the logs are.
This is the most misleading failure in the product, and it has cost real debugging time.
Symptom. AudioHub cannot reach a peer. daemon.log fills with lines like:
[audiohubd] peer 4f2a…: reconnect attempt 3 failed (connect 10.130.32.30:47810: No route to host (os error 65)); retry in 4.0s
Meanwhile nc -z 10.130.32.30 47810 from a terminal on the same machine
succeeds, ping is fine, and the peer is demonstrably listening.
Cause. The Local Network permission is no longer matching the code
identity AudioHub is running under — typically after an update, a reinstall, or
a re-signed build. macOS does not report this as a permission error. It
fabricates EHOSTUNREACH and lets the app believe the network is broken.
The diagnostic rule: if AudioHub cannot reach a host:port that another process on the same machine reaches fine, suspect the privacy grant before you suspect the network.
Fix. Re-enable AudioHub under System Settings → Privacy & Security → Local Network, then restart the audio service. When this was reproduced during development, the restarted service was back online within five seconds and its sessions rebuilt themselves.
The same grant governs outbound connections and mDNS scanning. Being discoverable does not depend on it — see Platform Notes.
Two files, two owners, same folder.
| File | Written by | Carries |
|---|---|---|
app.log |
the interface (the AudioHub window) | web access, driver install, service install, starting and stopping the audio service, tray problems |
daemon.log |
the audio service | everything else: network, peers, AirPlay, audio devices, the virtual driver bridge |
Both live in the configuration folder documented at Settings Reference → Paths:
| Platform | Folder |
|---|---|
| macOS | ~/Library/Application Support/AudioHub |
| Windows | %APPDATA%\AudioHub |
If you set AUDIOHUB_CONFIG_DIR, the logs move with it.
Four properties of these files that will otherwise confuse you:
-
Rotation is single and lazy. Past 1 MB the file is renamed to
app.log.1ordaemon.log.1and a fresh one starts. There is only ever one old copy, so check.log.1too when the interesting event was a while ago. -
daemon.logis only rotated when the service is started. A service that has been running for weeks keeps appending to the same file regardless of its size, because nothing may truncate a file a live process is writing to. -
daemon.logaccumulates every run, one after another. It is not one session per file. -
Timestamps are relative, not wall-clock. Each line is prefixed with
seconds since that service process started logging —
[ 1234.567]. A counter jumping back to near zero is where one run ended and the next began. It is the same time base as the Uptime figure on the Stats tab, so a log line and a reading can be lined up directly.
Quitting the interface does not stop daemon.log from growing. The audio
service outlives the window on purpose.
Failure screens in the interface deliberately do not print the underlying error. The service's own messages contain paths and, in this release, some untranslated text; rather than mix that into the interface, it is left in the log. So the log is not a second opinion — for these failures it is the only copy of the reason.
| What you see | Go to |
|---|---|
| The window shows a startup screen and never reaches the dashboard | The interface never connects |
| "AudioHub service port is in use" | Port 47810 is taken |
| "Incompatible AudioHub service version" | The interface and the service disagree about the protocol |
| The status dot in the top corner stays grey | The status dot stays grey |
| A machine you paired is not in the list, or a scan finds nothing | A peer never appears |
| The peer is online, and there is still no sound | Connected, but silent |
| The AudioHub device disappeared from the system's sound settings | The virtual device vanished |
| "Receiver startup failed. Check the service log." | AirPlay will not start |
The startup screen names the failure. Each name maps to a different next step, so read the title rather than clicking Retry twice.
| Screen | What happened | What to do |
|---|---|---|
| Starting the AudioHub service… / Connecting… | normal, briefly | wait |
| AudioHub service not found | the app is missing its service payload | reinstall AudioHub |
| Set up the AudioHub service | the background service is not installed yet | run the setup it offers; on macOS it asks for system approval |
| AudioHub service is stopped | installed, not running | start it from the same screen |
| Service setup failed | signing, installing or registering the service failed | retry; then read app.log
|
| Couldn't start the AudioHub service | the binary was found but the process did not start — file permissions or an OS security control | reinstall; or run audiohub daemon in a terminal to see the real error |
| AudioHub service port is in use | see below | free the port |
| AudioHub service conflict | another unverified or unresponsive process owns the service endpoint | quit it, then retry |
| AudioHub service timed out | it started but was not ready within 8 seconds | retry; then read daemon.log
|
| Incompatible AudioHub service version | see below | update both halves together |
| Missing connection parameters | a browser tab opened without ?port= and &token=
|
use the address the service prints, or the desktop window |
There is no fallback. The service binds TCP and UDP on the same port number, and when it is given a port — which it always is, because the default is 47810 and the app never overrides it — a busy port is a fatal error, not a hint to try another one. The process exits.
In daemon.log:
[audiohubd] start failed: bind tcp :47810: Address already in use (os error 48)
The usual occupant is an older AudioHub service that outlived its window.
Three ways out, in order of preference:
-
audiohub ctl shutdown— asks the running service to exit. - Find and stop whatever holds the port (
lsof -nP -i:47810on macOS,netstat -ano | findstr 47810on Windows). - Start the service on a different port:
audiohub daemon --port 50000. This is the only way to change the control port — the field in Settings → Network is read-only, and the app always launches the service with the default. Note that the port is part of how peers reach you, so every peer has to be told the new one; see Discovery and Pairing → Ports.
The audiohub command ships inside the application:
| Platform | Path |
|---|---|
| macOS | /Applications/AudioHub.app/Contents/MacOS/audiohub |
| Windows | C:\Program Files\AudioHub\audiohub.exe |
The interface and the audio service check their IPC protocol version for exact equality. Not "at least"; not "compatible with". One number off and the interface refuses to connect and says so.
This is deliberate. The two halves have already shipped changes where an older service would silently ignore a setting the newer interface believed it had applied — the interface would promise something the machine was not doing. A refused connection is the honest outcome.
Fix: update the interface and the audio service to the same build. On macOS, if the app was updated but the installed service was not, use the setup action the startup screen offers; that reinstalls the service from the copy inside the app.
This is one of four independent version numbers in AudioHub. The others — the two driver ABIs — fail differently; see The virtual device vanished.
The dot in the window's top corner is the interface's view of the audio service, not of any peer. Grey and labelled Offline means the interface is not talking to the service.
It is the same condition as The interface never connects — open the dot for the machine name, fingerprint and control port it last knew, and read the startup screen for the reason.
If the dot is grey but the audio is still playing, the service is alive and only the interface lost its connection. Nothing is broken in the audio path; the window is a client.
Separate two cases first: a scan finds nothing, and a peer you already paired stays offline.
| Cause | How to tell | Fix |
|---|---|---|
| The other machine is not advertising | its Advertise on LAN switch is off | turn it on — it is on by default, so it was turned off |
| The two machines are on different subnets | different network prefixes, or a routed VPN | mDNS does not cross subnets. Type the address instead: IP[:port] works across routed networks |
| The network blocks multicast | common on managed and guest Wi-Fi | same — type the address |
| macOS: Local Network not granted | scanning is one of the things that permission governs | grant it, see the top of this page |
| Windows: the network profile is Public | Settings → Network & Internet shows the network as Public | see below |
Typing the address always works. It is not a fallback for a broken scan; it is the path that does not depend on multicast at all. It is also the only path that works across subnets.
The installer adds one inbound firewall rule:
AudioHub daemon (Domain, Private) dir=in action=allow profile=domain,private
It covers the Domain and Private profiles only. If Windows classified the network as Public, inbound connections to the audio service are blocked and other machines cannot reach it — while this machine can still dial out and still appears to be working from its own screen.
Fix by setting that network to Private in Windows' network settings, or by adding a Public-profile rule yourself if the network genuinely is public and you accept that.
- Reconnection uses one address, the one remembered for that peer. The address history on the peer's detail page is a record of what has been seen; it is not a list of candidates to work through. If the peer moved, set its address.
- The fingerprint is what is checked, not the name or the address. A host answering on the right address with a different key is refused — that is the pinning working. If you reinstalled the other machine and its configuration folder was deleted, its identity changed and you must pair again.
- macOS: read the top of this page before investigating the network.
The peer is online and there is still no audio. Work down this list.
This catches almost every fresh installation. Share is the default on both machines, and Share mode means "I lend my devices out" — it does not use anyone else's. Two freshly installed machines therefore sit paired, online, and completely inert.
The three modes are mutually exclusive, and the exclusion is the point: the machine that shares must not also use another machine's devices, or it becomes an unwitting relay. See Operating Modes.
One side has to stop sharing and start using. Switch it to Mode A or Mode B in Settings → Mode. The other stays in Share.
If the peer is itself using someone else's devices, it cannot serve you. Its card shows an Unavailable badge and says so:
This host is in Mode A and is using another host's devices. Switch it to Share mode.
In Mode A the audio does not start because a peer is online. It starts because you turned on a direction, per peer, on that peer's card:
| Switch | Direction |
|---|---|
| Peer mic | take the peer's default input |
| Peer speakers | send this machine's audio to the peer's default output |
| Monitor | also play the incoming peer mic on this machine's own output |
| Audio bridge | route the peer mic into a third-party virtual cable so other apps can select it |
All of them start off.
If a switch is not shown at all, the peer has advertised that it has no default device in that direction. AudioHub shares the peer's default input and output; if that machine has no default microphone, there is nothing to offer and the row is omitted rather than shown broken.
In Mode B there is no "start" button, by design. The session is driven by the system's device selection. The device exists and does nothing until an application or the system picks it.
Check the device row on the peer's card or in Settings:
| Row reads | Meaning |
|---|---|
| ● In use | audio is flowing |
| ○ Idle | published and findable, but nothing has selected it |
| ○ Registering | not yet confirmed by the driver — wait, then see below |
Idle is the answer to "why is it silent". Select AudioHub – <peer> as the
output or input, in the system's sound settings or in the application itself.
Two things about that name that cause "I picked the wrong one" reports:
- Both directions carry the same label. There is no "Speaker" or "Microphone" word in it. Which one you are looking at is carried by the system's own device class — the input list shows the microphone, the output list shows the speaker. This is deliberate, not a bug.
-
An offline peer's name gains a suffix,
" (Offline)"in English or"（离线）"in Chinese, following the language the operating system is being shown. It is a rename on the same device, so applications keep their selection. Turn it off with Mark names offline in Settings.
Check both ends. A muted or zeroed device on the far side produces exactly the same silence as a broken link, and the two ends' sliders do not necessarily represent the same loudness — see Volume.
That is a transport problem, not a routing one. Open the Stats tab and read
Current path: Direct (UDP), TCP relay or Single-link mux. The two
degraded paths buffer far more and stutter under load;
Transport Tiers explains what each one
costs.
Virtual devices only exist in Mode B. Five distinct causes, and the interface names the one that applies.
| Cause | What the app says | What to do |
|---|---|---|
| The driver is not installed | No AudioHub driver was detected, so Mode B is unavailable. Mode B is greyed out | install it from Settings → Mode |
| The driver and the service versions differ | The driver and local service versions don't match (service v… / driver v…). No virtual devices will appear. | update the driver from the same card. Mode B stays selectable here — greying it out would put the update button out of reach |
| The driver is registered but its bridge is not ready | The driver is registered, but its bridge connection isn't ready. Published devices remain in the system but aren't processing audio. | wait a moment, then use the Restart Service button on that same card |
| "Remove on disconnect" is on | Removed by "Remove on disconnect" · Returns with the same UID on reconnect | expected. This setting is off by default; see Settings Reference |
| Capacity | The 16-device limit has been reached. Unpair another peer to free a slot. | unpair a peer you no longer use |
The limit in that last message counts peers, not devices: the driver owns sixteen slots and one paired peer occupies one slot regardless of whether it publishes a speaker, a microphone, or both. The message's wording is wrong; the number is right.
Two more things that look like a vanished device but are not:
- The mode was switched. Leaving Mode B removes every AudioHub virtual device, and the app says so at the moment of the switch.
- Unpairing. It removes that peer's devices unconditionally on this machine, regardless of the "Remove on disconnect" setting. See unpairing.
The two drivers carry different ABI numbers on purpose — macOS is at 3, Windows at 6. They are separate implementations with separate histories. Do not compare them across platforms and conclude something is out of date.
The signature of a mismatch is specific: everything else looks healthy, the app says Mode B is selected, and not one AudioHub device exists in the system. The machine falls back to Mode A behaviour in the meantime, which is why audio may still be working through the app while nothing appears in the system's sound settings.
The status row reads "Receiver startup failed. Check the service log." and
nothing more. The actual reason is only in daemon.log; the interface does not
render it.
The AirPlay receiver is off by default and needs several ports beyond 47810.
Start with Share Protocols, then read daemon.log
around the moment you switched it on.
Closing the window does not do it, and neither does one of the two quit items. The audio service is a separate process that outlives the interface on purpose. The tray menu has both:
| Tray item | Effect |
|---|---|
| Quit App (Audio Stays On) | closes the interface; audio keeps running |
| Stop Audio & Quit | stops the audio service, then quits |
So to restart the service: Stop Audio & Quit, then open AudioHub again. The
app starts a fresh service, and that is also when daemon.log is rotated if it
has grown past 1 MB.
From a terminal, audiohub ctl shutdown does the same stop — it is what the
tray item runs.
A Restart Service button also appears on the Mode card in Settings, but only in the narrow case it is meant for: the driver is installed and the service has lost contact with it. When the driver is healthy that same button reads Repair Driver instead, which is a different action.
Two levels, in increasing order of destruction:
Restart the service, as above. Fixes a detached driver bridge and a service that has got itself into a bad state. Loses nothing.
Use a throwaway configuration folder. Set AUDIOHUB_CONFIG_DIR to an empty
directory and start the service. You get a clean machine — new identity, no
pairings, default settings — while your real folder is untouched. Unset it to
come back.
Do not delete the configuration folder as a first resort. It holds the machine's identity, and deleting it means every peer that had you paired sees a different fingerprint and refuses to connect until you pair again. It also holds your settings, the per-peer transport choices, and the virtual-device slot table. See Settings Reference → Paths.
Neither is a fault.
- Rows with a zero counter are not rendered. A healthy link has nothing to show in the degradation list. An absent row means "this did not happen", not "this is not measured".
-
A total prefixed with
≥is a total with a term missing. Where a component of the latency cannot be read, AudioHub reports the sum it can prove and marks it as a lower bound rather than quietly reporting an optimistic number. See Latency.
Include:
- Which platform and which mode each machine was in.
- What the Current path on the Stats tab said.
- The relevant window of
daemon.logfrom the machine that misbehaved — remembering that its timestamps are seconds since that service process started, and that the file may contain several runs. -
app.logas well, if the problem was installing, starting, or the browser interface.
Start here
Using AudioHub
- Window and tray
- Operating Modes
- Virtual Driver
- Discovery and Pairing
- Peer detail page
- Share Protocols (Sharing tab)
- Web Access
How it behaves
Reference
- Settings Reference
- Platform Notes
- Firewall and network
- CLI Reference
- Versions and Compatibility
- Glossary
- Licenses and Attribution
Troubleshooting and removal
This wiki describes AudioHub 1.0.0.