3. Configuration Parameters

Configuration Reference

Explo is mainly configured using a .env file located in the project root, some additional parameters can be passed as flags. 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	This is only needed on the binary version, in docker it's set through volume mapping
USE_SUBDIRECTORY	Download/move tracks to a subdirectory named after the playlist	true
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.
3. When USE_SUBDIRECTORY and --persist are set to false, tracks are not deleted from the system.

---

Youtube Specific Variables

Variable	Description	Default
YOUTUBE_API_KEY	YouTube Data API key	optional
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,clean,acapella

NOTES:

1. FILTER_LIST is shared with slskd

---

Slskd Specific Variables

Variable	Description	Default
SLSKD_URL	Base URL of SLSKD instance	(required)
SLSKD_API_KEY	API key from SLSKD	(required)
MIGRATE_DOWNLOADS	Whether to move downloads under the DOWNLOAD_DIR or not	false
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
FILTER_LIST	Comma-separated blacklist keywords (without spaces)	live,remix,instrumental,extended,clean,acapella
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 binary version)	Directory where Slskd downloads tracks	This is only needed on the binary version, in docker it's set through volume mapping

NOTES:

1. A SLSKD API key can be generated using the official documentation
2. FILTER_LIST is shared with youtube

---

Metadata Configuration (Youtube)

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
LOG_LEVEL	Log detail. Supported values: DEBUG, INFO, WARN, ERROR	INFO
CLIENT_HTTP_TIMEOUT	Custom HTTP timeout for music servers (in seconds)	10

---

Flags

Explo supports flags that allow you to customize each run — for example, choosing which playlist to import, whether to skip or force downloads, and filtering out tracks that are already present locally.

In Docker, flags are defined in docker-compose.yaml

Flag	Description	Default
--config, -c	Path of the configuration file	.env
--playlist, -p	ListenBrainz playlist to import. Supported values: weekly-exploration, weekly-jams, daily-jams	weekly-exploration
--download-mode, -d	Download mode: • normal → download only if the track is not found locally • skip → skip downloading, only use locally found tracks • force → always download, ignore local tracks	normal
--exclude-local, -e	Exclude locally found tracks from the imported playlist	false
--persist	Whether to keep previously generated playlists (and tracks)	true
--help, -h	prints out a similar table	not set

NOTES:

1. To enable daily-jams generation you must follow troi-bot in ListenBrainz. The playlist should be created the next day.
2. When using weekly-jams or daily-jams, it is recommended to use --download-mode=skip. These playlists usually contain songs you have already listened to, so they should already exist in your music server.
3. weekly-jams and daily-jams will not work if you are using MPD (Music Player Daemon) with skip downloads enabled.