Quick Start

Run these steps on the computer where you want MusicSeed to run. Plex can live on a different machine.

1. Check the prerequisites

   You need macOS or Linux, Python 3.12 or newer with venv support, Node.js with npm, and Git for the source download below. You also need a Plex music library.

   python3 --version
   node --version
   npm --version
   git --version

   Node.js is used to build the website during installation. Starting MusicSeed afterward only needs Python.

2. Download and install

   git clone https://github.com/dafevara/musicseed.git musicseed
   cd musicseed
   ./scripts/install.sh

   Prefer a release archive? Download and unpack one from GitHub Releases. Open the source or release directory and run ./scripts/install.sh. The installer creates a Python environment, installs the app, and builds the web UI. Installation needs internet access.

3. Start the app

   musicseed --open

   Keep the terminal running. The app opens at http://127.0.0.1:8789 on this computer. If your browser does not open, enter that address yourself.

   Command not found, missing venv, or port already in use?

   If musicseed is not on your PATH, run ./.venv/bin/musicseed --open from the source directory.

   On Debian or Ubuntu, a missing venv error may require sudo apt install python3-venv python3-pip; then rerun the installer with Python 3.12 or newer.

   If port 8789 is occupied, use musicseed --port 8790 --open.

Next: connect to Plex.

The Plex connection lets MusicSeed save playlists. Database access, configured in the next guide, lets it import your library.

1. Choose your server

   After starting MusicSeed, open http://127.0.0.1:8789 on that computer and select your Plex server in the setup wizard. If discovery does not find it, enter its address in Plex server URL, for example http://nas.local:32400.

   For Plex on another computer, use that computer's reachable hostname or IP address. 127.0.0.1 refers to the computer running MusicSeed.

2. Add a Plex token if one was not detected

   In Plex Web, sign in and open your library. Open your browser's developer tools, select the Network tab, and find a Plex request containing X-Plex-Token in its headers or URL. Copy only the token value into Plex token.

   Use a token that can access this server and library. Keep it private; MusicSeed stores it locally and does not display the saved value.

3. Confirm your music library

   Enter the exact name shown in Plex under Music library name, then choose Save & re-check. A successful connection takes you to Review & initialize.

   If a readable database is already available, Continue without Plex connection lets you import and recommend locally. You can add the Plex connection in Settings before saving playlists.

Next: choose local Plex, a remote server, or a database copy.

Use this guide when Plex and MusicSeed run on the same computer.

1. Review the detected database

   In the wizard's Review & initialize step, check that Plex library database is found. MusicSeed checks common macOS and Linux Plex locations automatically.

2. Supply a path if it was not found

   In Finish your setup, leave Plex is on another machine (fetch the database over SSH) unchecked. Set Plex database path to the full path of com.plexapp.plugins.library.db in Plex's Plug-in Support/Databases folder. The user running MusicSeed must be able to read it.

   On macOS, start in ~/Library/Application Support/Plex Media Server/. On Linux, check your Plex installation's data directory.

3. Save and check the results

   Choose Save & re-check. For sonic similarity, the companion com.plexapp.plugins.library.blobs.db should be beside the library database. You can import metadata even if the blobs file is missing.

Next: import your library.

MusicSeed can fetch consistent database snapshots over SSH while Plex keeps running. You do not need to copy your music files.

1. Prepare the Plex host

   Enable SSH on the server or NAS. Your SSH user needs permission to read Plex's databases and run commands. The remote host needs python3 with its sqlite3 module and enough temporary disk space for backups of both databases. Allow space on the MusicSeed computer for the downloaded snapshots too.

   Find the directory containing com.plexapp.plugins.library.db and, when available, com.plexapp.plugins.library.blobs.db. For Plex in a container, use the path visible to your SSH session on the host.

2. Verify SSH access from the MusicSeed computer

   Replace the example user, host, and port below. Run this as the same local OS user who runs MusicSeed. Verify the server fingerprint through a trusted channel before accepting it; this records the host in ~/.ssh/known_hosts.

   ssh -p 22 your-user@nas.local

   In that remote session, check Python's SQLite support, then return to your computer:

   python3 -c 'import sqlite3; print(sqlite3.sqlite_version)'
   exit

3. Configure the remote database source

   Connect to Plex first. In Review & initialize → Finish your setup, check Plex is on another machine (fetch the database over SSH). Enter an SSH target using this format:

   your-user@nas.local:/path/to/Plex Media Server/Plug-in Support/Databases

   Replace the path with the actual directory on the remote host, not a database filename. Paste it without surrounding quotes, even when it contains spaces. Use the actual hostname; MusicSeed does not read aliases from ~/.ssh/config.

   Set SSH port if it is not 22. Use SSH password for password authentication. If no password is saved, MusicSeed uses standard SSH keys or your SSH agent. Leaving the password field blank keeps any previously saved password.

4. Re-check, then import

   Choose Save & re-check. Once the library database is found, continue to initialize and import. The import creates and downloads fresh SQLite snapshots, including committed changes from Plex's WAL files. Later imports refresh the snapshots.

   SSH works in a terminal, but the import fails?

   Check the actual host and port, host trust for the user running MusicSeed, saved password or available keys, database read permissions, Python's SQLite support, and free space on both computers. Unknown or changed host keys must be verified before reconnecting.

   If a backup times out, retry when Plex is less busy. A failed transfer keeps the last published snapshot. Do not copy live WAL or SHM files into the cache to repair it.

No SSH command access or Python on the host? Use a database copy.

Use this route when you already have consistent Plex database backups, or cannot use SSH snapshots.

1. Prepare a consistent backup

   Use a standalone SQLite backup of the library database and, if available, the blobs database. Avoid copying just the main database files while Plex is running: recent changes may still be in WAL files.

   For a manual file copy, shut down Plex cleanly first, copy the databases once it has stopped, then restart Plex. Keep the originals on the server.

2. Place the files on the MusicSeed computer

   Keep com.plexapp.plugins.library.db and the optional com.plexapp.plugins.library.blobs.db together in a readable folder. A mounted folder containing consistent backups also works. Paths refer to the computer running MusicSeed, even if you open the UI from another device.

3. Select the local copy in setup

   In Review & initialize → Finish your setup, leave the SSH checkbox unchecked. Enter the full local library file path in Plex database path and choose Save & re-check.

   This is your import source. Keep MusicSeed database path separate; its default is ~/.local/share/musicseed/musicseed.db.

4. Refresh the copy when your Plex library changes

   After any running import finishes, supply a new consistent backup and run import again. MusicSeed cannot fetch updates automatically from a manually copied database.

Next: import your library.

1. Create MusicSeed’s local database

   Return to Setup, review the source and destination, and choose Initialize database if it is shown. This creates MusicSeed's own database; Plex's source databases are only read.

2. Import your library

   Choose Start import and keep MusicSeed running while the job completes. If an import stops early, use Resume import; completed batches are kept. Wait for active jobs to finish before changing settings.

3. Add optional recommendation signals

   You can skip enrichment to start listening sooner. To add popularity data later, configure a ListenBrainz user token or Spotify credentials in Settings, then start enrichment from Library.

   For sonic similarity, Plex must already have analyzed your music. In Settings → Sonic vectors, choose Import from Plex to bring its existing analysis into MusicSeed.

4. Preview your first playlist

   Open Recommend, choose seed tracks from your imported library, and review the suggestions. Use Playlists to preview a new playlist, then confirm the tracks before saving it to Plex. Saving requires a working Plex connection and token.

Keep MusicSeed running and return to its setup wizard at http://127.0.0.1:8789. If you chose a different port, use that port instead.