1-bit-bridge

Companion server for the 1-bit iOS music player. Reach your home music library from anywhere — over Tailscale, a VPN, or a direct connection — without SMB's round-trip penalty.

Why

1-bit's built-in SMB transport is great on LAN but painful over high-latency links. Every pread on a remote share costs a round trip, so a library scan that finishes in seconds at home can take minutes over Tailscale's relay. 1-bit-bridge replaces SMB with an HTTP/2 protocol purpose-built for the app, plus a pre-built library manifest that lets the iOS side skip its two-phase scan entirely.

How it works

• Eight versioned endpoints under /v1/ — health, directory listing and stat, byte-range read, full download with HTTP range support, paginated library manifest, and album + artist artwork. Every route is bearer-authenticated except the unauthenticated /v1/health pairing probe.
• Pre-built library manifest served from SQLite. iOS fetches the full library in a paginated call (?limit, ?cursor), or a ?since=<mtime> delta in a single shot — both scan phases replaced. Tracks carry sample rate, bits per sample, DSD flag and rate, ReplayGain, and MusicBrainz IDs.
• Bit-exact, no transcoding ever. FLAC, ALAC, WAV, AIFF, MP3, AAC, DSF, DFF — served as-is. iOS still pre-caches the full DSF before playback so the DAC's DoP lock isn't at risk.
• Bearer tokens per device, with rotate / set-expiry / revoke from the admin console or the bridge token CLI. Each iOS device gets its own token; revoking one doesn't touch the others.
• TLS fingerprint pinning — captured once during pairing, enforced on every subsequent request. No CA trust needed. Cert rotation is supported (CLI-only via bridge cert rotate, by design — the operator-restart step has no safe web equivalent) and requires re-pairing affected devices.
• Bonjour discovery — bridge advertises _onebit-bridge._tcp with host and port in the TXT record so iOS finds it on the LAN automatically; the QR-code pair URL still carries the same fingerprint claim either way.
• Artwork enrichment against MusicBrainz, Cover Art Archive, and iTunes Search — rate-limited, well-behaved, cached by MusicBrainz ID. Returns 202 + Retry-After while still resolving so the iOS side knows to come back.
• Local admin console at http://127.0.0.1:7789/ (loopback only, no auth) for library roots, manual scans, pairing, token lifecycle, on-demand snapshots, opt-in auto-update, and a dashboard with cert status and expiry warnings. TLS cert rotation and snapshot restore are CLI-only by design.

Install

tar -xzf 1-bit-bridge_*_macos_arm64.tar.gz
./bridge init

tar -xzf 1-bit-bridge_*_linux_amd64.tar.gz
./bridge init

Expand-Archive -Path 1-bit-bridge_*_windows_amd64.zip -DestinationPath .
.\bridge.exe init

Downloads for every OS / arch are at the latest release page. Full install walk-through and preflight checks (bridge doctor) are in the README.

Pairing

Open the admin console's Devices page, click Pair new device, give it a name, and generate a token. The page shows a QR encoding a bridge://pair?... URL — scan it from the 1-bit iOS app, or paste the three fields (URL, token, TLS fingerprint) manually. Every further request the iOS app makes is bearer-authenticated and fingerprint-pinned. iOS also auto-discovers the bridge over Bonjour on the LAN, so you only have to type the bearer token.

Updates

The bridge polls GitHub Releases and surfaces an update banner in the admin console. Auto-install is opt-in; once enabled, you can set quiet hours (the bridge won't restart inside that window). Manual install runs the same path: download, verify the release-meta sidecar, atomic swap, with a one-tap rollback if the new build doesn't behave. The iOS app reads the bridge's protocol/version envelope on every /v1/health probe and surfaces an inline advisory when an update is available — or when the bridge requires a newer iOS app.

Backups

Configuration, paired tokens, and the indexed library all live in a single state directory. The admin console's Settings page makes timestamped snapshots on demand; periodic automatic snapshots can be turned on with a configurable rotation count. Restoring a snapshot is a CLI operation (bridge restore) that requires stopping the bridge first — kept off the web UI so an accidental click can't replace the running library mid-stream.

Protocol

See PROTOCOL.md for every endpoint, shape, and error code. Every client endpoint is prefixed /v1/; the admin console (/, /api/*, /static/*) lives on a separate loopback listener and is not part of the wire protocol. Additive fields (manifest pagination, mDNS TXT keys) ship without a protocol bump; breaking changes do bump X-Bridge-Protocol and the iOS app refuses to talk to a server it doesn't understand.

Open source

MIT-licensed. Source at github.com/acoseac/1-bit-bridge: the Go server, the embedded admin console, the protocol spec, and the release pipeline. Issues and PRs welcome — see CONTRIBUTING.md. Security reports via GitHub's private advisory flow.