Skip to content

First Run

Jump to bottom
Score2 edited this page Aug 15, 2026 · 1 revision

First Run

The first thing AudioHub shows on macOS is not the main window. It is a full-window Permissions screen that has to be cleared before anything else appears. This page explains what it asks for, what each button does, and why one of the rows never turns green no matter what you do.

On Windows there is no gate — see Windows at the bottom.

The permission gate

When it appears

The gate is shown when a required permission is both knowable and not granted. In practice exactly one row can satisfy that: Microphone. Local Network is never knowable (macOS offers no query API for it) and System Audio is not required, so neither of them can raise the gate on its own.

Two consequences that are easy to mistake for bugs:

  • Nothing is remembered. There is no "you have seen this" flag on disk. The gate is re-probed on every launch, so if you revoke the microphone grant in System Settings, the gate comes back next time you start AudioHub.
  • It does not close itself. Once the gate is up it stays up until you press Continue or Skip for now, even after the last grant lands. That is deliberate: pulling the screen away the instant you granted something would leave no chance to look at the optional rows.

The gate also waits for the local service. While the service is offline the connection overlay is shown instead — permissions cannot be probed without it — and the gate returns once the service is up.

Keyboard shortcuts are not active while the gate is on screen.

What the gate asks for

Row Required? What AudioHub uses it for Can AudioHub prompt for it?
Microphone Required Sharing this Mac's microphone with a paired host Yes — a real macOS dialog
Local Network Required Finding other AudioHub hosts and streaming to them No — see below
System Audio Optional Mode A's "send this machine's audio to the peer" direction Yes — creating the audio tap is the prompt

Each row carries a Required or Optional tag, a status tag (Granted / Denied / Undetermined / Restricted / Unknown), and one action button. Optional rows additionally get a Later button, which hides that row's buttons for the rest of the session and marks the status … · Later. Required rows never get Later — it would contradict the fact that they are holding the door shut.

Note that Microphone is required even if you never intend to share this machine's microphone. The gate does not know which mode you will pick.

The four buttons

Button What it does
Grant all Walks the required rows that AudioHub can actually prompt for and requests each in turn. In this build that set is only ever the Microphone: Local Network cannot be requested and System Audio is not required. Greyed out when that set is empty.
Recheck Re-probes every row without prompting for anything. Use it after changing something in System Settings.
Continue Enters the app. Disabled while a required row is still blocking.
Skip for now Enters the app anyway. Only visible while something is blocking.

Grant all does not fail silently. When it finishes it reports either "All required permissions granted" or "Required permissions still missing: n (names)". A single row failing does not abort the rest of the walk.

Skip for now is not remembered either. The line under the button spells out what will break, the toast repeats it, and the gate is back on the next launch.

While a system dialog is open the hint line reads "Waiting for the system permission dialog… Select 'Allow' in the window that appears." The request can sit there for as long as you leave the dialog up; that is not a hang.

Local Network usually says Unknown

The Local Network row shows Unknown with the note "Status unavailable · macOS asks on first use; enable manually if denied", and its button says Check Settings rather than Grant. That is the normal reading, and it is not a defect in AudioHub.

macOS publishes no API to query the local-network grant and none to request it. There is nothing to read and nothing to ask, so AudioHub infers the only thing it can: it sends one mDNS query and watches for an answer. An answer proves the grant is in place, and the row then reads Granted for the rest of this run of the service.

Two things follow. The probe that fills the gate does not send that query, so the row starts at Unknown every time. And an answer requires something else on the network to be advertising — on a segment where nothing is, the row stays Unknown even though the grant is fine.

Because the status can be genuinely unknowable, the gate is built so this row can never block you — treating an unknowable row as a door latch would lock every user out permanently.

So the row is informational. macOS itself raises the local-network dialog the first time AudioHub actually touches the LAN, which happens after you are already in the app.

What it costs when the grant is missing is covered in Platform Notes — and the failure does not look like a permission error, which is why it is worth reading before you go hunting.

After a denial

macOS asks once. If you answer Don't Allow, the application can never raise that dialog again — this is a system rule, not an AudioHub choice.

The row reacts accordingly: the status turns Denied, the note becomes "Denied. macOS will not show the prompt again, so enable it manually at: …", and the button changes from Grant to Open Settings. Pressing it opens the matching System Settings pane by deep link. Because a deep link can fail to open depending on the system and the webview, the written path is also shown in a toast, so you are never left without a route:

Row Path shown by the app
Microphone System Settings → Privacy & Security → Microphone → Enable AudioHub
Local Network System Settings → Privacy & Security → Local Network → Enable AudioHub
System Audio System Settings → Privacy & Security → System Audio Recording → Enable AudioHub

After flipping the switch in System Settings, come back and press Recheck.

A fourth status, Restricted, means a system policy — a configuration profile or Screen Time — is blocking the grant. AudioHub cannot request it and neither can you, from inside the app.

System audio on macOS 13.0–14.1

The System Audio row is about the Core Audio process tap, which needs macOS 14.2 or later. On 13.0–14.1 that tap does not exist, so:

  • the row sits at Unknown and pressing Grant does not move it — there is no tap to create, so there is nothing to consent to;
  • Mode A's system-audio capture still works on those versions, because AudioHub falls back to the ScreenCaptureKit backend;
  • that backend is gated on the Screen Recording permission, not on system audio recording. It is a broader grant, and macOS re-asks for it periodically.

The Screen Recording prompt is not raised by the gate. It appears later, the first time you actually start sending this machine's audio to a peer in Mode A. Below macOS 13.0 there is no system-audio backend at all.

Which backend a Mac resolves to, and how to pick one by hand, is in Platform Notes.

After the gate: the Permissions sheet

Getting past the gate does not mean every row is green — Local Network and System Audio can never block it. So the first time you land in the main window, AudioHub opens the Permissions sheet once, showing the same rows with the same buttons, plus the line "Missing access disables the features that need it."

It opens automatically only when all of the following hold: you are in the desktop app (not the browser Web UI), the service is online and probed, the gate is not on screen, at least one row is not granted, and the set of not-granted rows differs from the set you last dismissed.

That last condition matters. AudioHub stores a signature of the not-granted set, not a "don't show again" flag. Closing the sheet records the current set as seen; if a permission is later revoked or a new one appears, the signature stops matching and the sheet comes back — which is exactly when it should.

You can open it at any time from Settings › General → Permissions → Open. The row next to it summarises the count as n · m pending.

The sheet never opens by itself in the browser Web UI. Pressing Grant there would raise a system dialog on the machine running the service, and whoever clicked is usually not sitting at it.

Windows

There is no permission gate on Windows. The local service reports all three rows as granted with no authorisation needed, so nothing ever blocks and the Permissions sheet never opens by itself. The rows are still listed under Settings › General → Permissions.

What does stand between a fresh Windows install and working audio is elsewhere:

  • SmartScreen, which blocks the unsigned installer — see Installation.
  • The firewall rule, which the installer adds for Domain and Private networks only. A network Windows has classified as Public will not accept inbound connections from a peer.
  • The driver, which the installer copies but deliberately does not install. Mode B stays opt-in — see Virtual Driver.

Related

AudioHub

Start here

Using AudioHub

How it behaves

Reference

Troubleshooting and removal

This wiki describes AudioHub 1.0.0.

Clone this wiki locally