-
Notifications
You must be signed in to change notification settings - Fork 0
Discovery and Pairing
Two machines have to find each other, agree that they trust each other, and keep agreeing after their addresses change. This page covers all three.
47810, TCP and UDP on the same number. One port to remember, one port to open if a firewall is in the way.
| Port | Who listens | What it carries |
|---|---|---|
| 47810/TCP | the audio service, on all interfaces | control channel, TLS with fingerprint pinning |
| 47810/UDP | the audio service, on all interfaces | media, when the connection is Tier 0 |
| 5353/UDP | mDNS, only while announcing | the local-network broadcast described below |
| random | the audio service, on 127.0.0.1 only | IPC between the service and its UI |
| 47800/TCP | the app, only when you switch it on | the browser interface |
The control port is read-only in the current build — the field in Settings shows
it, and nothing changes it. The IPC port is picked at startup and written to
ipc.json in the config directory; it never leaves
the loopback interface, which is the fact that keeps
"local only" locked.
Two independent paths, and the second one always works.
Automatic (mDNS). Switch on "broadcast this machine on the local network" and other AudioHub installations on the same subnet see this machine when they scan. Nothing is published to the internet.
Manual (IP[:port]). Type the peer's address. This works across subnets,
through routed networks and through L3 VPNs, and it does not depend on the
broadcast being on at either end. If mDNS is blocked — plenty of managed
networks block it — this is the path, not a fallback.
A ws:// address may also be entered, which selects the tunnelled transport;
see the tunnel address. Pairing itself
cannot be done over a tunnel: pair over IP:port first, then set the tunnel
address on that peer's detail page.
Exactly three fields:
| Field | Why it is there |
|---|---|
| Machine name | so the scan list is readable |
| Control port | so the scanner knows where to connect |
| Identity fingerprint | so the scan list can tell this machine, already paired and stranger apart |
The fingerprint deserves a note, because publishing a cryptographic identity on a broadcast sounds worse than it is: it is a digest of the public key, and any host that can reach the control port obtains it during the handshake anyway. Broadcasting it does not disclose anything a port scan would not. What it buys is a scan list that can mark entries correctly instead of showing three identical-looking strangers.
Turning the broadcast off means this machine is no longer discoverable. It does not affect anything else: pairing by typed IP still works, inbound connections are still accepted, and scanning for other machines still works.
The UI says so rather than pretending. On macOS the usual cause is the Local Network permission: until AudioHub is allowed in System Settings → Privacy & Security → Local Network, the announcement is silently dropped by the OS. Grant it, then toggle the switch off and on — no restart needed. See Platform Notes.
Every installation generates a long-lived key pair on first run. The fingerprint is a short digest of the public half, and it is the only thing that identifies a machine — not its name, not its IP, both of which change.
- Your own is in Settings → This machine, and on the status badge in the window's top corner.
- A peer's is on its card and on its detail page.
Two places rely on it:
- Pairing. The PIN exchange binds the peer's fingerprint into the trust record. Comparing the fingerprint shown on both screens is what makes the exchange resistant to someone sitting in the middle — the PIN alone is six digits and short-lived, the fingerprint is what is remembered.
- Every later connection. TLS is verified against the pinned fingerprint, not against a certificate authority. A host that answers on the right address and port but presents a different key is refused, which is what makes reconnecting to a changed IP safe.
One side enables pairing mode and shows a six-digit PIN; the other side enters that PIN together with the address. That is the whole ceremony.
Three properties worth knowing:
- Trust is bidirectional. One side initiates, both end up trusting. After it succeeds each machine appears in the other's list — there is no second, reversed pairing to perform.
- The PIN expires. Pairing mode is a window, not a state you leave on.
- In mode B, pairing is also device creation. The moment it succeeds, the peer shows up as a pair of audio devices in the system's sound settings, ready to select. No further step.
If it fails, the message names which of the three preconditions was not met: pairing mode not enabled on the far side, PIN expired, or address unreachable.
The same exchange, if the UI is not where you are:
audiohub pair --to <ip>:<port> --pin <pin>
It talks to the local service over the same IPC contract the UI uses, so the result is identical and appears in the UI immediately.
Unpairing is not "disconnect". It is the removal of the trust record, and it is deliberately abrupt:
- Both directions of trust are revoked.
- All sessions with that peer close immediately.
- The virtual devices for that peer are removed from both systems — unconditionally, regardless of the "remove virtual devices on disconnect" setting. The peer is notified and removes its side too.
That last point is the reason unpairing is loud rather than quiet. The alternative — leaving a pair of permanently-offline devices in someone else's sound settings, with no way to work out where they came from — is the outcome worth spending a confirmation dialog to avoid.
If one of the removed devices was the system's default output or input, the OS picks another one, exactly as it does when you unplug an interface.
To use that machine again, pair again. There is no "re-trust" shortcut, on purpose: the fingerprint check is the whole point of the exercise.
Addresses change; the fingerprint does not. Each peer's detail page keeps an address history — what the service has recorded and what this UI session has observed — and reconnection tries the most recent one first, verifying the fingerprint before anything else happens.
This is why a paired laptop that moves between two networks generally reappears without being told anything.
Using it
How it behaves
Settings
Reference