Pairing & Remote

This page explains how connection, pairing, and remote access fit together in the current product (0.3.0+).

For topology, Personal Private Network, and how devices reach the hub, see Network Documentation.

The Basic Model

Tape Music Hub works best when you think about it this way:

the desktop app is the hub
the phone app is the paired client
pairing creates a private relationship between that phone and that hub

First Pairing

The safest default is still:

open the hub locally, either in the desktop app or Docker web UI
open Connections (sidebar › System, or the QR icon in the top bar) and choose New connection
scan the QR code from the mobile app
complete the first connection on the same Wi-Fi

On iPhone, the first scan asks for Local Network access — allow it. The app asks as soon as the hub preview opens, so the connection itself is not held up. If it was denied, enable it in Settings › Privacy & Security › Local Network › Tape.

A normal pairing QR is timed (5 minutes) and single-use: its code travels inside the QR, and it stops working once a phone has paired or the window expires. If the phone says the QR expired or was already used, open New connection again and scan the new QR.

During an active pairing window, the desktop can expose:

a QR code (includes hub identity for Personal Private Network (Iroh))
a share link (HTTPS, for WhatsApp and chat)
an app deep link (musichub://connect?...) used after the share page opens the app
a countdown/expiry time
a relaunch action for a fresh pairing window

Update desktop and mobile together before relying on remote listening.

Share link (chat)

musichub:// links are poor for messaging apps (often not clickable). While pairing is armed, desktop Copy / Share uses an HTTPS URL on the product landing, not on your hub’s public remote hostname:

https://tapemusicsuite.com/mobile-pair?server=https%3A%2F%2Fyour-hub.example&name=...&pair=...

Flow:

Recipient opens the link in the phone browser (landing).
They tap Open in Tape → musichub://connect?... with the same parameters as the QR.
The hub still validates the pairing code on POST /api/auth/pair.

The hub’s public remote URL (when configured) remains the API endpoint (server in the query). The landing only mediates deep linking; it does not grant access by itself.

Desktop env override if your landing host differs: MUSIC_HUB_PAIRING_LANDING_ORIGIN (origin only, no path).

Connection Priority

The phone keeps one hub identity and moves between routes as needed.

Current priority:

local Wi‑Fi / LAN
Personal Private Network (Iroh)
public remote route (Cloudflare / public link), when configured

Pair once on Wi‑Fi. Later, away from home, the phone can use Personal Private Network (Iroh) without Tailscale.

Every pairing stores the hub's Personal Private Network identity — also when the first pairing happened over a public link — so the phone can fall back to Iroh after the public link is turned off.

Pairing away from home

First pairing without the same Wi‑Fi is off by default and needs a licensed hub:

In New connection, turn on Connect without the same Wi-Fi. The phone can then pair over Personal Private Network (or a public link, if you run one).
With Keep pairing open, the QR and share link carry only the hub identity, not the code. After scanning, the phone asks for the pairing code shown on the desktop — share them through different channels. Pairing stays open until you close it in Connections.
If Connect without the same Wi-Fi is off, the hub refuses the first pairing over Personal Private Network or a public link; pair on the same Wi‑Fi instead.

Remote Access Options

Local Wi‑Fi

fastest path
best default for first pairing
no internet dependency if both devices are on the same network

Personal Private Network (Iroh)

always on in Settings → Remote (0.3.0+)
built into the hub (Iroh); no Tailscale app, no inbound port-forward
treated as remote for licensing
pairing QR embeds hub identity so reconnect works after the first pair
on Docker, needs UDP 42424 published and MUSIC_HUB_ADVERTISED_LOCAL_IP set — see Docker Setup

Public remote route

optional Cloudflare / public link from the desktop hub
useful for first-time pairing off Wi‑Fi when you share a public URL + pairing code
still not anonymous private library access; the phone must complete pairing/auth

Note: Tailscale is no longer a Tape Music Hub Settings path. If you previously depended on Tailscale alone, update to 0.3.0 and re-pair the phone.

Keep the Desktop Hub Available

The desktop app is the hub: remote routes and phone playback work only while it is running.

In Settings → General, you can enable Keep Tape running in the tray when the window closes. Closing the window then hides it while the local server and remote routes keep running. Use Quit in the tray menu or Cmd/Ctrl+Q to stop the hub completely.
In Settings → Remote, Keep this hub active is on by default and prevents the Tape Music Hub process from being suspended. If you turn it off, the desktop header shows a warning that opens that setting again.
This does not override a closed laptop lid, logout, low-battery shutdown, or your operating system's power policy. Keep the computer connected to power when you need dependable long remote sessions.

Public Scope vs Private Mobile Access

One of the most important product rules:

Shared pages only limits the public web/share surface
it does not remove private access from a phone that is already paired

So if your phone was already paired correctly, it should still be able to browse and play through the private mobile API even when the public share scope is narrow.

Public hub root vs share links

If someone opens the hub’s public base URL (for example your stable Cloudflare hostname) without a /share/... path, what they get depends on Public web access / publicRemoteScope on the desktop:

Shared pages only (standalone_only): the hub returns a small HTML splash page (not the full web app). It explains that visitors need an explicit share link to hear anything, and points people who want to host their own library to tapemusicsuite.com (opens in a new tab) for downloads and setup.
/share/playlist|album|artist|track/... URLs still load the interactive standalone player for that shared item. That surface is separate from “browsing the whole hub in a browser.”

The hub pill on standalone share pages opens an overlay that reuses the same messaging and primary CTA as that splash (Get Tape → tapemusicsuite.com (opens in a new tab)).

Licensing and Remote

Current product rule:

LAN / Wi-Fi remains available without remote entitlement
remote playback requires a valid desktop license

If remote is blocked by license:

the phone should still work on Wi‑Fi
the app should tell you remote needs a valid desktop license
it should not look like a random generic network failure

Common Failure Modes

`pairing_not_armed` / "This QR code has expired or was already used"

The desktop has a route, but pairing is not open — the timed window expired, or its single-use code was already used by a phone.

What to do:

open the desktop app locally
open Connections › New connection again
scan the new QR

On the same Wi‑Fi, but the phone "could not reach the computer"

The phone is on Wi‑Fi but its first request to the hub failed — on iPhone this is almost always Local Network permission.

iPhone: Settings › Privacy & Security › Local Network › Tape on; Android: allow nearby/local network devices if asked
check both devices are on the same network (not a guest network or client isolation)
scan a fresh QR

Old QR or stale route

If the phone is using an old QR or stale public route:

rescan the latest desktop QR
confirm the hub still exposes the expected routes
update desktop and mobile if one side is below 0.3.0

Remote works, but browse/search/playback fail

That usually means:

auth is stale, or
remote is present but the mobile private-access path is not healthy

Start by reconnecting from the latest QR and checking the desktop remote state.

Features Licenses & modules