Getting Started

Getting Started

This guide reflects the current public product.

1. Start from the landing

Use the official product entry:

If you are on Windows, Linux, or Android, use Building from Source.

2. Install the Desktop Hub

  1. Install the Mac desktop app.
  2. Move Music Hub into Applications.
  3. Open it and allow it in Privacy & Security if macOS warns you.

3. Add Your Library

  1. Choose one or more folders with music.
  2. Wait for the first scan to finish.
  3. Confirm that tracks, artists, albums, and playlists begin to populate.

The desktop hub is the source of truth for the whole product. The phone app does not build a separate library of its own.

4. Pair Your Phone

  1. Open the iPhone companion app.
  2. Open the desktop pairing screen.
  3. Scan the current QR code.
  4. Complete the first pairing on the same Wi-Fi when possible.

Current pairing screen behavior includes:

  • QR code
  • mobile deep link
  • countdown / expiry
  • relaunch action for a fresh pairing window

For the full connection model, see Pairing & Remote.

5. Decide How You Want to Use It

Local / Wi-Fi only

This is the simplest mode:

  • desktop hub running on your Mac
  • phone on the same network
  • no remote route needed

Remote access

If you want playback outside your local network:

  • set up a remote path from the desktop hub
  • keep the phone paired
  • use a valid desktop license for remote playback

Current remote paths:

  • Tailscale
  • public remote route from the desktop hub

Common Setup Tasks

Add more folders later

Open the desktop app and add more music folders from Settings.

Import playlists from DJ/music tools

The desktop hub currently supports:

  • Rekordbox XML
  • M3U / M3U8 / XSPF
  • Traktor NML
  • Apple Music / iTunes XML
  • Serato local crates and smart crates

Share a page publicly

The public surface is currently narrow and intentional:

  • tracks
  • albums
  • artists
  • playlists

Supported Formats

Current common formats include:

  • MP3
  • FLAC
  • M4A / AAC
  • WAV
  • OGG
  • OPUS

Runtime Paths

Current default runtime files:

  • database: ~/.music-hub/music.db
  • config: ~/.music-hub/config.json
  • log: ~/.music-hub/electron.log

If Something Fails

IntroductionFeatures