Skip to content

README.md

Latest commit

 

History

History
120 lines (89 loc) · 4.44 KB

README.md

File metadata and controls

120 lines (89 loc) · 4.44 KB
Raw

Music Collab Explorer

Preview screenshot of the app

The Music Collab Explorer is a web app for discovering collabs between musical artists.

Using data from the excellent MusicBrainz project, you can search for any artist and visualize their collabs in a dynamic graph.

Features

  • Search for an artist, and click one of the results to add them to the artist list.
  • Artists in the list will be shown in the graph.
    • Their collaborators will be shown in the graph as well, if the "Show only selected" checkbox is not checked.
  • Double-click on any artist in the graph to view their collabs.
  • All artists who have collabed are connected.
  • Click on any graph node or edge to view more information.
    • Clicking a node will list all the collab songs of that artist.
    • Clicking an edge will list all the collab songs between the artists connected by the edge.

Getting Started

Prerequisites

  • Deno installed.
  • A PostgreSQL database v16.1 or greater (a script is provided to help populate it with a dump from the MusicBrainz database).

Installation

Clone the repository:

git clone git@github.com:KaeruCT/music-collab-explorer.git
cd music-collab-explorer

Set up env vars:

cp .env.example .env

Modify .env as needed to configure database credentials.

Running the Application

Development Mode

deno task dev

Building for Production

deno task build

Starting the Server

deno task start

Database Setup

This application requires a local copy of the MusicBrainz database. The setup process involves downloading the MusicBrainz dump, hydrating a local database, and optionally syncing with a remote replica.

Initial Database Setup

  1. Navigate to the setup/ directory:

    cd setup/

  2. Run the database initialization script to download and import MusicBrainz data:

    ./init_db.sh

    To ensure a clean installation by removing any existing dump files first:

    ./init_db.sh --clean

    Note: This script requires PostgreSQL superuser access (connects as postgres user) to create/drop databases and users. Only run this for local database setup.

    This script will:

    • Download the latest MusicBrainz dump (several GB - takes time)
    • Create a database with the required schema
    • Import only the relevant tables for the music collab explorer
    • Create necessary indexes

  3. (Optional) Remove superuser privileges from the MusicBrainz user:

    ALTER USER musicbrainz WITH NOSUPERUSER;

Database Synchronization with Remote Replica

After setting up your local database, you can sync it with a remote replica database. This enables deploying the application on a proper server on the internet.

Prerequisites for Sync

  • Local MusicBrainz database already initialized (via init_db.sh)
  • Remote PostgreSQL database configured and accessible
  • Environment variables configured for both local and remote databases in .env

Environment Configuration

Configure your .env file based on .env.example with the necessary database connection details for both your local database and the remote replica.

Regular Replica Updates

For the recurring update process, follow setup/UPDATE_DATABASE.md.

The normal flow is:

  1. Refresh the local MusicBrainz database from the latest upstream dump with setup/init_db.sh.
  2. Run setup/debug_sync.sh to compare local and replica table state.
  3. Run setup/sync_db.sh to push new local rows to the replica.
  4. Run setup/debug_sync.sh again to verify the replica advanced.
  5. Clear ${TMPDIR:-/tmp}/app_cache and restart/redeploy API processes that point at the replica.

Important: The current sync is one-way (local → remote) and high-water-mark based. It copies rows whose primary key is greater than the replica's current max primary key. It does not update or delete existing replica rows.

Future Improvements

  • Improve artist images by using additional sources, only Wikimedia is used at the moment and it's missing many artists.
  • Allow to play tracks within the visualization. Currently, the tracks are only Youtube search links.

Acknowledgments

  • MusicBrainz for providing open music metadata. This project would be impossible without them. Please contribute!
  • vis-network for the excellent graph visualization.