-
Notifications
You must be signed in to change notification settings - Fork 0
Versions and Compatibility
This wiki describes AudioHub 1.0.0.
AudioHub is not one program with one version number. It is an app, a background audio service, a driver on each platform, and two machines talking to each other — and each of those joins is a separate contract with its own version number. Every one of those checks is strict equality. None of them is a "minimum supported version", and none of them has a compatibility shim.
That is deliberate. Every mismatch in this table has a history of failing silently when it was tolerant: a setting that looked applied but was not, a device that appeared for a machine that has none, a level meter nobody reads. A loud refusal is the design.
Settings › About shows Version 1.0.0. That number comes from the app's own
build. If it is not available the card shows — rather than inventing a
plausible number, so a dash is the honest answer and not a bug.
That is the number to quote when you report a problem.
The background service's own product version is not displayed anywhere in the interface. What the interface checks is the IPC contract below; the only other numbers it ever prints are the two driver ABI numbers, and only when they disagree. None of those is a product version.
On Windows the app and the service always come from the same install directory, so they cannot drift. On macOS the service is installed as a separate, explicit step, so they can — which is what the IPC check is there to catch.
| Contract | Between | 1.0.0 | What a mismatch looks like |
|---|---|---|---|
| IPC | app ↔ audio service, on this machine | 7 | the interface refuses to connect at all |
| Peer control protocol | this machine ↔ the other machine | 5 | the connection is refused; the pairing survives |
| Driver ABI, macOS | audio service ↔ AudioHubDriver
|
3 | zero AudioHub devices in the system |
| Driver ABI, Windows | audio service ↔ AudioHubVad
|
6 | zero AudioHub devices in the system |
The interface will not talk to a service whose IPC version is not exactly its own. It does not degrade, it does not warn and continue — it stops at the handshake and shows:
Incompatible AudioHub service version This interface requires IPC protocol v7, but the local service uses another version. Update both components to the same build.
Fix: bring both to the same build. On macOS, if you updated the app but the installed service is still the old one, the startup screen offers the setup action that reinstalls the service from the copy inside the new app — see Installation › Upgrading.
There is nothing to salvage here by leaving it alone. The version has already moved for reasons like this one: an older service silently ignored a setting the newer interface believed it had applied, so the interface would have promised something the machine was not doing.
More detail, including what to check first, is in Troubleshooting.
Two paired machines check their control protocol version on every connection, in both directions. A mismatch refuses the connection and says which side speaks what:
control protocol mismatch: we speak v5, the peer speaks v4; both machines have to run the same build
A peer old enough to predate version negotiation entirely gets its own wording, because it never sent a number to quote.
Two things worth knowing:
- Your pairing is not damaged. A version mismatch never edits the pairing record on either machine. You do not need to pair again; you need to upgrade the older end.
-
You may not see the message. It comes back when you press connect. An
automatic reconnect attempt only writes it to
daemon.log— the peer just sits there offline and retrying. See Troubleshooting › Where the logs are.
Fix: run the same release on both machines.
Only relevant in Mode B · Virtual, which is the only mode that uses the driver at all. Share and Mode A never touch it.
The check is strict equality in both directions, with no compatibility layer and no plan for one. When it fails, the driver publishes nothing, so the symptom is distinctive: everything else looks healthy, Mode B is selected, and not one AudioHub device exists in the system's sound settings.
The Mode card in Settings turns red and names it:
The driver and local service versions don't match (service v3 / driver v2). No virtual devices will appear. Install the matching driver version.
Mode B stays selectable in this state rather than being greyed out. Greying it out would put the Update Driver button on that same card out of reach.
Fix: the Update Driver button on that card. See Virtual Driver.
macOS is at 3 and Windows is at 6, and neither is behind the other.
They are two separate drivers with separate histories. They share no message, no transport and no data structure — a Core Audio user-space plug-in on one side, a kernel audio driver on the other. The numbers were never synchronised and deliberately never will be; making them match would create the illusion that a bump on one platform means something on the other.
So: do not compare the two platforms. A current macOS pair is 3 and 3; a current Windows pair is 6 and 6. Seeing 3 on one machine and 6 on the other means nothing at all. The only comparison that carries information is the two numbers inside one mismatch message on one machine — and that message only appears when they already disagree.
settings.json in the configuration directory carries a format version (6 in
this release). It is not one of the four contracts — nothing refuses to run over
it — but it has one visible behaviour worth knowing about:
If you downgrade, and the service finds a settings.json written by a newer
build, it keeps every other field but resets the operating mode to Share and
writes a line to daemon.log saying so. A file from the future cannot be
trusted to mean what this build thinks it means, and silently guessing whether
you meant Mode A or Mode B is worse than putting you back on the default.
Configuration directory:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/AudioHub |
| Windows | %APPDATA%\AudioHub |
See Settings Reference for what else lives there.
The Windows installer contains the driver files and does not install them. It
never imports a certificate and never enables test signing. The AudioHubVad
driver in these builds is unsigned, and Windows will not load an unsigned kernel
driver on a normally configured machine.
The Install Driver button exists on the Mode card, asks for elevation, and then fails — on purpose. AudioHub asks Windows to install the package non-interactively, so an untrusted package fails closed rather than walking you past a trust decision.
Share mode and Mode A · Driverless are unaffected on Windows and need nothing from the driver. Details in Virtual Driver.
The macOS .dmg is ad-hoc signed and not notarised. The Windows installer is
unsigned. Gatekeeper and SmartScreen will each block their platform's build until
you explicitly override it. Nothing in the filename says so — the artifacts carry
the plain product name — so the signature is the only thing that distinguishes a
signed build from an unsigned one.
What that means, and how to decide whether to override it, is on Installation.
Upgrade every part in the same window.
- App and service on one machine: same build, always — the IPC check enforces it.
- Both machines: same release — the peer protocol check enforces it.
- Driver: after the service, from the button on the Mode card.
Your settings, machine identity and pairings survive upgrades on both platforms. See Installation › Upgrading.
- Installation — what you download, and upgrading
- Virtual Driver — installing, updating and repairing the driver
- Troubleshooting — the symptom index for all of the above
- Discovery and Pairing — the machine identity that a version mismatch does not touch
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.