Skip to content

3. Configuration Parameters

Jump to bottom
Markus Kuuse edited this page Jun 26, 2025 · 16 revisions

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 when using binary version)
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
SLSKD_DL_ATTEMPTS Number of download attempts for a track 3
SLSKD_RETRY Number of times to check search status before skipping the track 5
SLSKD_DIR (For MPD) Directory where Slskd downloads tracks required only when using MPD

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

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