Aurral
Artist Discovery and Request Manager for Lidarr
Install / Use
/learn @lklynet/AurralREADME
Aurral
Self-hosted music discovery and request management for Lidarr with library-aware recommendations, granular monitoring controls, and optional Weekly Flow playlists powered by Soulseek + Navidrome.
What is Aurral?
- Search for artists via MusicBrainz and add them to Lidarr with the monitoring behavior you want
- Browse your existing library in a clean UI
- Discover new artists using recommendations derived from your library and (optionally) Last.fm
- Track requests and download/import progress
- Generate weekly playlists and download the tracks into a separate “Weekly Flow” library
Aurral is designed to be safe for your collection: it does not write into your main music library directly. Library changes go through Lidarr’s API, and Weekly Flow writes into its own directory.
Quick Start (Docker Compose)
Create a docker-compose.yml:
services:
aurral:
image: ghcr.io/lklynet/aurral:latest
restart: unless-stopped
ports:
- "3001:3001"
environment:
- DOWNLOAD_FOLDER=${DL_FOLDER:-./data/downloads}
volumes:
- ${DL_FOLDER:-./data/downloads}:/app/downloads
- ${STORAGE:-./data}:/app/backend/data
You can optionally set DL_FOLDER and STORAGE in a .env file next to your compose file. If you leave them unset, Aurral uses ./data/downloads and ./data.
Start it:
docker compose up -d
Open: http://localhost:3001
Requirements & Recommended Stack
Required
- Lidarr (reachable from Aurral)
- Last.fm API key (api key required, username needed for scrobbling)
- A MusicBrainz contact email (used for the MusicBrainz User-Agent policy)
Recommended stack for new users
- Lidarr Nightly
- Tubifarry
- slskd
- Navidrome
For Weekly Flow
- Navidrome (optional but recommended if you want playlist/library integration)
- A downloads directory mounted into the container (for the Weekly Flow library)
Features
Discovery
- Daily Discover recommendations based on your library, tags, and trends
Lidarr Management
- Add artists with granular monitor options (None / All / Future / Missing / Latest / First)
- Add specific albums from release groups
- Library view with quick navigation into artist details
- Request tracking with queue/history awareness
Weekly Flow (Optional)
Weekly Flow generates playlists from your library and listening context, then downloads tracks via a built-in Soulseek client into a dedicated folder.
- Multiple flows with adjustable mix (Discover / Mix / Trending) and size
- Automatic weekly refresh scheduling
- Optional Navidrome smart playlists and a dedicated “Aurral Weekly Flow” library
Screenshots
<p align="center"> <img src="frontend/images/discover.webp" width="900" alt="Aurral UI" /> </p> <p align="center"> <img src="frontend/images/recommended.webp" width="440" alt="Recommendations" /> <img src="frontend/images/artist.webp" width="440" alt="Artist details" /> </p>Data, Volumes, and Safety
Downloads and Weekly Flow library
Mount a downloads folder for Weekly Flow and optional Navidrome integration:
- Container path:
/app/downloads - Weekly Flow output:
/app/downloads/aurral-weekly-flow/<flow-id>/<artist>/<album>/<track>
A note on your main library
Aurral does not write to your root music folder directly. Changes to your main collection happen via Lidarr (add/monitor/request/import).
Weekly Flow + Navidrome Setup (Optional)
If you want Weekly Flow to appear as a separate library inside Navidrome:
- In Aurral: Settings → Integrations → Navidrome (URL, username, password)
- Ensure your compose config maps a host folder into
/app/downloads - Set
DL_FOLDERonce and use it for bothDOWNLOAD_FOLDERand the/app/downloadsvolume
Example:
DL_FOLDER=/data/downloads/tmp- Volume:
${DL_FOLDER}:/app/downloads - Env:
DOWNLOAD_FOLDER=${DL_FOLDER}
Aurral will:
- Create a Navidrome library pointing to
<DOWNLOAD_FOLDER>/aurral-weekly-flow - Write smart playlist files (
.nsp) into the Weekly Flow library folder
Navidrome should be configured to purge missing tracks so Weekly Flow rotations don’t leave stale entries:
ND_SCANNER_PURGEMISSING=always(orfull)
Authentication & Reverse Proxy
Local users (default)
Aurral uses local user accounts created in onboarding. Authentication is HTTP Basic Auth at the API layer. Use HTTPS when exposing it publicly.
Reset forgotten admin password (terminal)
If you forget your admin password, you can reset it from the terminal:
npm run auth:reset-admin-password -- --password "new-password"
Or generate a random password:
npm run auth:reset-admin-password -- --generate
The -- after npm run auth:reset-admin-password tells npm to pass the remaining flags to the reset script.
Reverse-proxy auth (OAuth2/OIDC)
If you want SSO, place Aurral behind an auth-aware reverse proxy and forward the authenticated username in a header.
Environment variables:
AUTH_PROXY_ENABLED=true
AUTH_PROXY_HEADER=X-Forwarded-User
AUTH_PROXY_TRUSTED_IPS=10.0.0.1,10.0.0.2
AUTH_PROXY_ADMIN_USERS=alice,bob
AUTH_PROXY_ROLE_HEADER=X-Forwarded-Role
AUTH_PROXY_DEFAULT_ROLE=user
Proxy headers (trust proxy)
If you are behind a reverse proxy, set TRUST_PROXY so Aurral interprets X-Forwarded-* correctly:
TRUST_PROXY=true
Configuration Reference (Environment Variables)
Most configuration is done in the web UI, but some settings are controlled by environment variables.
| Variable | Purpose | Default |
|---|---|---|
| PORT | HTTP port | 3001 |
| TRUST_PROXY | Express trust proxy setting (true/false/number) | 1 |
| DOWNLOAD_FOLDER | Weekly Flow root folder path used for Navidrome library creation | ${DL_FOLDER:-./data/downloads} (in compose example) |
| PUID / PGID | Run container as this UID/GID (when starting as root) | 1001/1001 |
| LIDARR_INSECURE | Allow invalid TLS certificates (true/1) | unset |
| LIDARR_TIMEOUT_MS | Lidarr request timeout | 8000 |
| SOULSEEK_USERNAME / SOULSEEK_PASSWORD | Optional fixed Soulseek creds | autogenerated if missing |
| AUTH_PROXY_* | Reverse-proxy auth options (above) | unset |
Troubleshooting
- Lidarr connection fails: confirm Lidarr URL is reachable and API key is correct (Settings → Integrations → Lidarr)
- Discovery looks empty: add some artists to Lidarr and/or configure Last.fm; initial discovery refresh can take a bit
- MusicBrainz is slow: MusicBrainz is rate-limited; Aurral respects it and may take longer on first runs
- Weekly Flow does not show in Navidrome: verify
DOWNLOAD_FOLDERmatches your host path mapping and Navidrome purge settings - Permission errors writing
./data: setPUID/PGIDto match your host directory ownership
Support
- Community + questions: https://discord.gg/cpPYfgVURJ
- Troubleshooting + help: https://github.com/lklynet/aurral/discussions
- Bugs + feature requests: https://github.com/lklynet/aurral/issues
