AI-powered music discovery and playlist sync for Navidrome. Syncs your listening history, enriches metadata, generates AI mixtapes, and discovers similar artists — all self-hosted.
- Playlist Sync — Sync Spotify and Last.fm playlists to your Navidrome library with fuzzy track matching
- Vibes Engine — AI-powered mixtape generation with customizable DJ personas
- Similar Artists — Discover related artists within your own library using AI
- Metadata Enrichment — Pull artist/album/track data from MusicBrainz, Spotify, Last.fm, Fanart.tv, and Lidarr
- Real-time Updates — SSE push notifications, no polling required
- Navidrome Auth — Log in with your existing Navidrome credentials
docker run -p 8080:8080 \
-e SPOTTER_NAVIDROME_BASE_URL=https://your-navidrome-instance \
-e SPOTTER_OPENAI_API_KEY=sk-... \
-v ./data:/app/data \
ghcr.io/joestump/spotter:latestgit clone https://github.com/joestump/spotter.git
cd spotter
make deps && make runSpotter is configured via environment variables. The only required ones to get started:
| Variable | Description |
|---|---|
SPOTTER_NAVIDROME_BASE_URL |
URL of your Navidrome instance |
SPOTTER_OPENAI_API_KEY |
OpenAI (or LiteLLM-compatible) API key |
Spotter supports multiple database backends. SQLite is the default and requires no additional setup.
| Driver | SPOTTER_DATABASE_DRIVER |
SPOTTER_DATABASE_SOURCE example |
|---|---|---|
| SQLite (default) | sqlite3 |
file:./data/spotter.db?_fk=1 |
| PostgreSQL | postgres |
host=localhost port=5432 dbname=spotter user=spotter password=secret sslmode=disable |
| MariaDB / MySQL | mysql |
user:pass@tcp(localhost:3306)/spotter?parseTime=true&charset=utf8mb4 |
Note: PostgreSQL and MySQL drivers require CGO to be enabled at build time. The official Docker image includes all three drivers.
Ready-to-use Compose files are provided for PostgreSQL and MariaDB:
# PostgreSQL
docker compose -f docker-compose.postgres.yml up
# MariaDB
docker compose -f docker-compose.mariadb.yml upFor the full configuration reference, see the documentation site.
make test # run tests
make css # rebuild Tailwind CSS
make run # run with hot reloadSee the architecture docs for the full list of ADRs and the spec docs for detailed specifications.
Spotter was written almost entirely by Claude Code (Anthropic's AI assistant). The human provided product direction and reviewed the output. This project is shared openly as an experiment in AI-assisted software development.
Use at your own risk. No warranty is provided, express or implied.
MIT