Getting Started

Getting Started

This guide reflects the current public product.

Docker (NAS / Server)

Run Music Hub on a NAS, Linux server, seedbox, or Docker Desktop without the Electron app. Docker is available now and treated as a testing channel while more server setups are covered; if anything behaves unexpectedly, join Telegram (opens in a new tab) or WhatsApp (opens in a new tab) and report it.

curl -O https://music-hub.gordo.design/docker-compose.yml
docker compose up -d

Then open http://localhost:38472 on the server, or http://<server-ip>:38472 from another device on the same LAN.

volumes:
  - ./data:/data
  - /path/to/your/music:/music:ro
environment:
  - MUSIC_FOLDER=/music

You can also skip MUSIC_FOLDER and add /music later from Settings → Folders.

For the full compose file, LAN pairing, Docker Desktop address setup, and NAS notes, see Docker Setup.

1. Start from the landing

Use the official product entry:

For Docker/NAS setup, start with Docker Setup. For source builds and unreleased desktop installers, see Building from Source.

2. Install the Desktop Hub

  1. Install the current desktop hub build for your platform, or run the Docker server.
  2. On macOS, move Music Hub into Applications.
  3. Open the hub 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 Music Hub mobile 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.

iOS is distributed through TestFlight. Android is currently in closed beta through Google Play testing.

Current pairing screen behavior includes:

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

If someone sends you a pairing link instead of showing a QR:

  1. open the HTTPS link on your phone
  2. tap Open in Music Hub
  3. let the app connect to the hub
  4. if asked, confirm the pairing code shown by the hub owner

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 app or Docker server running on your local network
  • 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

Use Import playlists from the playlist area or the folder/import flow. When Music Hub detects folders that are not already part of your library, it will ask you to review them before exposing new folder trees.

Add notes to a track

  1. Open a track detail view on desktop.
  2. Find Notes.
  3. Add the note you want to keep with that track.

Playlist-specific notes are separate. A note added to a track inside a playlist stays attached to that playlist context and does not automatically appear everywhere else the track is used.

Make a collaborative playlist

  1. Create or open a normal playlist on desktop.
  2. Choose Make collaborative.
  3. Copy the invite link.
  4. Send it to another Music Hub owner.
  5. They accept the invite from their hub.

Collaborative playlists require remote-capable hubs and a valid license for remote/collaboration features. Your phone still connects to your own hub; hub-to-hub sync happens behind the scenes.

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
  • electron log: ~/.music-hub/electron.log (legacy path)
  • desktop log: ~/Library/Logs/Music Hub/desktop.log (v0.1.41+ standard path)
  • Docker data: /data inside the container, usually mounted to ./data on the host

If Something Fails

IntroductionDocker Setup