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
# optional but recommended for phone pairing:
# echo 'MUSIC_HUB_ADVERTISED_LOCAL_IP=192.168.1.40' > .env
docker compose up -d

Then open http://<server-ip>:38472 from a device on the same LAN (prefer the LAN IP over localhost for pairing).

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

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

For ports (38472 + UDP 42424), pairing, and away-from-home setup, 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 release commands, see Building from Source.

2. Install the Desktop Hub

Download the latest production build for your platform from the support page (opens in a new tab):

Or run the Docker server instead of the desktop app.

  1. Install the build for your platform.
  2. On macOS, move Music Hub into Applications.
  3. On Windows or Linux, run the installer or AppImage and open the hub.
  4. Allow the app in Privacy & Security (macOS) or your system firewall if prompted.

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. Install the Mobile Companion

  1. iPhone: install Tape Music Hub from the App Store (opens in a new tab).
  2. Android: submit the beta signup form (opens in a new tab), then install from Google Play closed testing (opens in a new tab).

Pre-release mobile builds may also appear on the landing beta page (opens in a new tab) or TestFlight (opens in a new tab).

5. Pair Your Phone

  1. Open the Tape 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.

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.

6. 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:

  • Personal Private network (always on in Settings → Remote)
  • optional public remote route / Cloudflare from the desktop hub

Update desktop and mobile together (0.3.0+) before relying on remote listening. Tailscale is no longer a Music Hub setup path.

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