Skip to content

7. Development

Jump to bottom
Markus Kuuse edited this page May 18, 2026 · 3 revisions

Design Philosophy

Explo started as a simple personal Go script in 2023: fetch recommendations from ListenBrainz, find the tracks on Youtube, and create playlists in Navidrome (Subsonic). It was initially meant to be run as a single binary on a server. Its core goal has stayed the same, but many features have been developed to fit user requests.

Explo now fits into different environments. It can be run as a single binary or deployed via Docker, depending on user preference.

Explo is designed to be a set-and-forget solution. Once configured, it should run with minimal user intervention, continuously requesting music and creating playlists. Additional features may contain optional interaction, but automation remains the default.

Compatibility has been a priority from the start and also supports the set-and-forget design. Changes should be backward compatible whenever possible, with deprecation notices communicated before removing a feature.

Pull Requests

Pull requests should start with an issue about the bug or feature request. If an issue already exists, comment there before beginning work.

Please avoid large refactors or major changes without prior discussion (either in issues or our Discord).

Contributors do not need to know every part of the codebase, but you should be familiar with the languages you are working with.

AI usage

AI usage is fine when used — for example:

  • rubber ducking
  • reviewing code
  • generating small, well-understood helper functions (that are actually needed)
  • helping understand unfamiliar parts of the codebase (i.e if you're unfamiliar with the backend, but know frontend)

Contributors should understand and test their code. Large AI-generated implementations or refactors are discouraged, as they often require cleanup.

Build from source

Prerequisites

  • Go >1.24.1
  • ffmpeg and yt-dlp installed and available in $PATH(or custom paths defined in .env)

To build Explo from source:

1. Clone the repository

Clone the repository and switch to the desired branch:

git clone https://github.com/LumePart/Explo.git
cd Explo
git checkout <branch name>

2. Set up environment

Copy the sample configuration and modify it (you can also refer to the Configuration Reference):

cp sample.env .env
nano .env

If testing functionality, set LISTENBRAINZ_DISCOVERY to api (downloads less songs)

3. Build

Build Explo with this command:

go build -o explo ./src/main

Clone this wiki locally