Skip to content

2. Getting Started

Jump to bottom
Markus Kuuse edited this page May 31, 2025 · 24 revisions

Installation guide and configuration parameters

Installation Guide

Prerequisites

Docker Installation

  1. Download docker-compose.yaml file to your system and configure volume mappings
  2. Make a .env file in the directory defined in docker-compose and configure it (refer to sample.env for options or check out Configuration Reference)
  3. Launch the container with docker compose up -d

Volume Mappings

Host Path Container Path Description
/path/to/.env /opt/explo/.env Environment file with configuration parameters.
/path/to/musiclibrary/explo $DOWNLOAD_DIR Directory where Explo stores downloaded music. Must match your music system's library path. It's recommended to create an explo subdirectory under your main music library.
(Only for MPD) $PLAYLIST_DIR $PLAYLIST_DIR (Right now, it is recommended to use the binary for MPD) Directory where .m3u playlists will be written. Uncomment the line and set the same path on both sides if using MPD.

Binary Installation

Ensure ffmpeg and yt-dlp are installed on the system and accessible via $PATH. Alternatively, you can specify their paths in the .env file.

  1. Download the latest release and ensure it's executable
  2. Make a .env file in the same directory as the binary and configure it (refer to sample.env for options or check out Configuration Reference)
  3. Add a Cron job to run Explo weekly:
crontab -e

Insert this to the last line to execute Explo every tuesday at 00:15 (ListenBrainz updates its discovery database on Mondays)

15 0 * * 2 cd /path/to/explo && ./explo-linux-amd64

Configuration Reference

Explo is configured using a .env file located in the project root. This file defines all environment variables used to control download preferences, music system authentication, and metadata handling.

Discovery Config

Variable Description Default
DISCOVERY_SERVICE Service which recommends songs (only ListenBrainz supported) listenbrainz
LISTENBRAINZ_USER Your ListenBrainz username (required)
LISTENBRAINZ_DISCOVERY Source where Explo takes recommendations (playlist, api) playlist

NOTES:

  1. Using api in LISTENBRAINZ_DISCOVERY is recommended when testing/debugging the system, it offers fewer (25) songs than playlist (50 songs) and the recommendations don't update often

Music System Configuration

Variable Description Required For
EXPLO_SYSTEM System you use (emby, jellyfin, mpd, plex, subsonic) All
SYSTEM_URL Base URL of media server (e.g http://127.0.0.1:4533) All except MPD
LIBRARY_NAME Name of the music library to use Emby, Jellyfin, Plex
SYSTEM_USERNAME Username for system authentication All except MPD
SYSTEM_PASSWORD Password for system authentication Subsonic (required), Plex (preferred)
API_KEY API token for systems that support it Jellyfin, Emby (required), Plex (optional)
PLAYLIST_DIR Filesystem path where .m3u playlists should be written MPD

Downloader Configuration

Variable Description Default
DOWNLOAD_DIR Folder where tracks are stored (when using docker, set the dir as data/) (required with youtube)
DOWNLOAD_SERVICES A comma-separated list (no spaces) of services to use for downloading tracks, in priority order (e.g slskd,youtube) youtube

NOTES:

  1. DOWNLOAD_SERVICES: Services are prioritized based on their order in the list. Explo attempts to download tracks using the first service; if some tracks can't be downloaded, it tries downloading them using the next service, and so on until all tracks are downloaded or all options are exhausted.
  2. DOWNLOAD_SERVICES: When using slskd as the first service, it’s recommended to list youtube as a fallback for better reliability.

Youtube Specific Variables

Variable Description Default
YOUTUBE_API_KEY YouTube Data API key (required)
FFMPEG_PATH Custom ffmpeg binary path $PATH
YTDLP_PATH Custom yt-dlp binary path $PATH
FILTER_LIST Comma-separated blacklist keywords (without spaces) live,remix,instrumental,extended

Slskd Specific Variables (Experimental)

Variable Description Default
SLSKD_URL Base URL of SLSKD instance (required)
SLSKD_API_KEY API key from SLSKD (required)
EXTENSIONS A comma-separated list (no spaces) of filename extensions to use for filtering tracks, in priority order flac,mp3
MIN_BIT_DEPTH Minimum bit depth for a track 8
MIN_BITRATE Minimum bitrate for a track 256

NOTES:

  1. A SLSKD API key can be generated using the official documentation

Metadata Configuration

Variable Description Default
SINGLE_ARTIST Merge featured artists into title instead of the artist field true
PLACEHOLDER PLACEHOLDER PLACEHOLDER

Misc Variables

Variable Description Default
SLEEP How long to sleep (in minutes) between scanning and querying tracks from your music system 2
PERSIST Whether to keep previous weeks discoveries, set to false if the parent folder only contains discovered songs (deletes every file in folder) true
DEBUG Whether to provide additional info for debugging false

Clone this wiki locally