2. Getting Started - LumePart/Explo GitHub Wiki
Installation guide and configuration parameters
Installation Guide
Prerequisites
Docker Installation
- Download docker-compose.yaml file to your system and configure volume mappings
- 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)
- 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.
- Download the latest release and ensure it's executable
- 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)
- 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:
- 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:
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.
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:
- 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 |