Melodarr

1. Overview

Melodarr is a self-hosted music discovery and request app for Lidarr. It gives household members a simple interface for finding artists and albums, exploring personalized recommendations, and sending requests to Lidarr, while optional Plex integration prevents suggestions for music that is already in your library.

Melodarr uses MusicBrainz for music metadata and can use ListenBrainz and Last.fm listening history for recommendations. It includes private accounts, administrator-managed invitations, persistent request history, background library scans, and local metadata and artwork caches.

2. Preview

📱 Screenshots

Discover	Artist
Release Group	Linked Accounts

3. Features

• Search MusicBrainz for artists and albums, then browse discographies, releases, and tracklists.
• Search AnimeThemes for an anime's openings, endings, episode ranges, and related series, then request conservatively matched MusicBrainz releases through Lidarr. Administrators can confirm the recommended automatic recording match or supply a correction; the selected recording, artist, and release-group MBIDs are stored permanently in the local SQLite registry ahead of the disposable API cache.
• Request a complete artist or an individual release group through Lidarr.
• Apply Lidarr root folder, quality profile, metadata profile, monitoring, tag, and automatic-search defaults.
• Discover personalized artists and albums from linked ListenBrainz and Last.fm accounts.
• Filter recommendations and request controls using existing Lidarr entries, previous requests, and selected Plex music libraries.
• Browse the artists and album-level releases already available in Plex, with links back to Plex.
• Track queued Lidarr searches and album availability with automatic background jobs.
• Cache metadata and artwork locally to reduce upstream requests, while revalidating viewed artist discographies in the background.
• Create private user accounts through one-time, seven-day administrator invitations.
• Inspect job status, run maintenance jobs, and flush individual caches from the administrator dashboard.

4. Quick start

Melodarr is designed to run with Docker Compose. The included docker-compose.yml uses the published slimjimserver/melodarr:latest image and persists application data in ./data.

1. Download or copy the docker compose file from the repository.

2. Create the data directory before starting the container:

   mkdir -p data
   

   On Linux, give Melodarr's fixed container user ownership of the directory:

   chown -R 1000:1000 data
   

   The image runs directly as UID/GID 1000:1000. It does not start as root or change bind-mount ownership during startup.

3. Start Melodarr:

   docker compose up -d
   

4. Open http://localhost:5056 and create the owner account. The first account is the administrator.

5. Open Settings, connect Lidarr, test the connection, and choose the defaults for new requests. Plex is optional.

5. Configuration

Environment variables

No additional environment variables are required for the included Docker Compose setup. It already stores the main database and metadata cache beneath the persistent /app/data mount.

Unraid Community Applications

Use this volume mapping:

Host:      /mnt/user/appdata/melodarr
Container: /app/data

Do not map a host directory to /app; doing so hides Melodarr's application files. Only /app/data should be used for persistent storage.

To use Unraid's native nobody:users identity, prepare the directory once from the Unraid terminal:

mkdir -p /mnt/user/appdata/melodarr
chown -R 99:100 /mnt/user/appdata/melodarr

Then add this in the container's Extra Parameters field:

--user 99:100

Remove any PUID or PGID variables from an older template; Melodarr no longer uses them. Docker's --user override starts Melodarr directly as 99:100, without a root entrypoint.

For an HTTPS deployment, add this to the service's environment block in docker-compose.yml:

MELODARR_COOKIE_SECURE: "true"

Service configuration

Service credentials are normally configured after signing in.

• Lidarr (required for requests): hostname or IP address, port, SSL choice, API key, and optionally an external browser-facing URL. After testing the connection, choose the root folder, quality and metadata profiles, monitoring behavior, tags, and automatic-search behavior.
• Plex (optional): sign in with the Plex account that owns the server, choose one of its advertised connections, and select one or more music libraries to scan. Plex tokens are retrieved through the secure Plex PIN flow and are never pasted into Melodarr.
• ListenBrainz (optional, per user): public ListenBrainz username.
• Last.fm API access (optional, administrator-managed): the owner or an administrator saves one Last.fm API key for the whole Melodarr instance. The key is never returned by the API or shown again after it is saved.
• Last.fm listening history (optional, per user): each user can add their own public Last.fm username to receive recommendations based on their listening history. Individual users do not need Last.fm API keys.

Settings and service credentials are stored in data/settings.json when using Docker. Keep the data directory private. For a consistent backup, stop Melodarr cleanly before copying melodarr.db, settings.json, session-secret.key, and vapid-private.pem. The VAPID file is the stable Web Push identity; restore it with the database to avoid invalidating existing browser subscriptions. Set MELODARR_VAPID_PRIVATE_KEY_FILE only when placing that key in another private persistent location. If the service must remain online, back up melodarr.db with SQLite's online backup API or the SQLite shell's .backup command; do not make a raw copy of a live database because committed data may still be in its WAL file. The reproducible cache/ directory can be excluded from backups.

Melodarr is licensed under the GNU General Public License v3.0.