Questions
The things people ask before installing it. If yours isn't here, open an issue.
Why not just use Apple Music or Spotify for this?
Familiar isn't a streaming service — it plays the files you already own. If you've got a folder of MP3s/FLACs going back to 2002, Apple Music either won't accept them or will iCloud-Match them to its own catalog versions (sometimes the wrong remaster, occasionally DRM-locked, occasionally just gone). Spotify only plays its own catalog; its Local Files feature syncs from a desktop to a phone on the same network, not remotely. Neither runs semantic search or AI playlists across your library — only theirs. Familiar runs on your hardware, leaves your files alone, and points its AI at your collection.
Do I need an API key?
No. Familiar holds no API key and calls no model. If you want to ask questions in plain language you connect your own MCP host — Claude Desktop, say — and whatever that costs is between you and them. Everything else, including search, Mood Grid, Music Map and the 3D Explorer, is local.
What hardware do I need?
See the Requirements callout above. A small NAS works — the author runs a 23k-track library on an OpenMediaVault box. Analysis is the heaviest workload; once a track is analyzed it doesn't need to be re-analyzed.
Does my music or listening data leave my network?
No. The opt-in community cache shares only one-way SHA-256 hashes of audio fingerprints — no track titles, artists, file paths, or listening history. You cannot reconstruct a library from the hashes. If you connect an MCP host, whatever you ask it goes wherever that host sends it — that is your choice and your account. Your audio files never leave your server.
What happens if Claude is down?
Everything keeps working. Browsing, searching, playback, similarity, smart playlists and analysis are all local — Familiar makes no outbound call to run. An MCP host you have connected is the only part that needs the internet, and only for its own sake.
How long does analysis take?
Roughly 1 second per track on modern hardware, so a 20,000-track library is around 6 hours. The community cache short-circuits tracks that have been analyzed elsewhere, which can reduce a cold-start scan to minutes for popular music.
What are the alternatives to Tailscale?
Cloudflare Tunnel if you want a stable public hostname routed through Cloudflare without opening a port. WireGuard if you would rather run your own VPN and use the LAN address. A reverse proxy — nginx, Caddy, Traefik — on a box that already has a domain and a certificate. Or any VPN you already run: anything that puts your phone on the same network as the server will do. What you should not do is port-forward 4400 to the open internet.
Can I listen away from home?
Yes — see Listen from anywhere. Tailscale plus HTTPS is the easiest path: install the iOS app, point it at your server's Tailscale hostname in Settings, and it works on cellular like any other music app.
Is there an iOS app?
Yes, and it is where listening on a phone is meant to happen — Familiar Player is on the App Store, with a Mac app alongside it. It asks for your server's address the first time you open it, so you need Familiar running somewhere before the app is useful. A Tailscale HTTPS address works well and is what the placeholder shows. (The Mac app starts with a demo address already filled in — that is there so Apple's reviewers have something to connect to, and you should replace it with your own.)
Get started
One compose up against the music you already own.