Pairing & Remote

Pairing & Remote

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

The Basic Model

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:

  1. open the hub locally, either in the desktop app or Docker web UI
  2. arm pairing if needed
  3. scan the current QR code from the mobile app
  4. complete the first connection on the same Wi-Fi

During an active pairing window, the desktop can expose:

  • a QR code
  • 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

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://tape-music-hub.gordo.design/mobile-pair?server=https%3A%2F%2Fyour-hub.example&name=...&pair=...

Flow:

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

The hub’s Cloudflare/Tailscale URL 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 tries to keep one hub identity and move between routes as needed.

Current priority is:

  1. local Wi-Fi / LAN
  2. Tailscale
  3. public remote route

That means one successful Wi-Fi pairing can continue working later through remote routes if the hub already exposes them.

Remote Access Options

Local Wi-Fi

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

Tailscale

  • private remote path between your devices
  • good for stable personal remote access
  • treated as remote for licensing purposes

Public remote route

  • useful when a public remote path is configured on the desktop hub
  • still not anonymous private library access; the phone must already be paired/authenticated

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 music-hub.gordo.design (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 Music Hub → the marketing/docs site).

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

The desktop has a route, but pairing is not currently armed.

What to do:

  1. open the desktop app locally
  2. arm pairing again
  3. refresh the QR and rescan it

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

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.

FeaturesFAQ