Aurral User Guide

A practical guide for setting up Aurral, connecting your music stack, and understanding the app once it is running.

Aurral is built around a simple idea: discovering music should be just as self-hostable as storing it. This guide covers the full app from a user perspective without turning into an API reference.

Before You Start

You can start Aurral with only Lidarr connected. The other services make recommendations, downloads, and playback much better.

Service Use it for Required?
Lidarr Library management, artist/album adds, queue and history. Yes
Last.fm Personalized discovery, tags, similar artists, richer flows. No, but recommended
ListenBrainz Optional per-user listening-history profile. No
Soulseek Downloading flow and imported playlist tracks. Only for downloads
Navidrome Playing generated flows as their own library. No
Ticketmaster Local concert recommendations. No

Docker Setup

Aurral is Docker-first. The default compose file keeps app data and generated downloads on your host machine. 

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

Optional `.env` file

Put this next to your compose file if you want explicit host paths. 

DL_FOLDER=/srv/aurral/downloads
STORAGE=/srv/aurral/data

Start it

docker compose up -d

Open http://localhost:3001 and complete onboarding.

What the folders mean

/app/backend/data is Aurral's database and settings. /app/downloads is where generated flows and imported playlists are written.

First Run

Onboarding gets the app usable quickly. You can skip optional services and return to them later from Settings.

  1. Create your first admin account.
  2. Connect Lidarr and test the connection.
  3. Optionally connect Navidrome.
  4. Optionally add a Last.fm username and API key.
  5. Sign in and finish your defaults.

Good first settings

  • In Integrations -> Lidarr, check the quality profile, tag, monitoring option, and search-on-add behavior.
  • In Integrations -> Last.fm, add an API key for stronger discovery.
  • In Account, set your own Last.fm or ListenBrainz username.
  • In Discover, choose daily, weekly, or monthly refreshes and pick a discovery mode.

App Sections

Discover

Personalized recommendations, global trends, tags, recent releases, recently added artists, and local shows.

Library

A visual browser for artists already in Lidarr, with search, sorting, images, monitoring status, and artist pages.

Flow

Scheduled flows, imported playlists, worker settings, generated track playback, and download status.

Requests

A friendlier view of Lidarr queue and history so you can see what is processing, failed, or available.

Blocklist

Artists and tags you do not want Aurral to recommend again.

Settings

Integrations, discovery behavior, notifications, accounts, users, and permissions.

Discovery

Discover is library-aware. Aurral tries to recommend artists that fit your taste while avoiding artists you already have and anything you block.

What can shape recommendations?

  • Your Lidarr library
  • Your Last.fm or ListenBrainz listening history
  • Last.fm tags and similar artists
  • Global trending pools
  • Recent releases
  • Your blocklist and feedback

Discovery modes

Mode Best for
Safer Familiar, obvious, high-confidence recommendations.
Balanced A mix of familiar picks and new exploration.
Deeper More adventurous recommendations outside the obvious lane.

Per-user listening history

Each user can set their own Last.fm or ListenBrainz username in Account settings. This lets a shared Aurral instance serve different people without mixing every preference together.

Flows

Flows are dynamic playlists. They regenerate on a schedule, download into Aurral's own folder, and can be exposed to Navidrome.

Flow controls

  • Track count
  • Update days and update hour
  • Source mix
  • Deep Dive
  • Focus tags
  • Focus related artists
  • Enabled or draft state

Flow sources

Source How it behaves
Discover Uses Aurral recommendations and excludes library artists.
Library Uses artists already in your Lidarr library.
Trending Uses broader trending pools and excludes library artists.
Focus Targets tags and related artists you choose.

Focus is its own source. If Focus is enabled, add at least one tag or related artist so Aurral knows what to target.

Want the full flow behavior?

The dedicated Flows and Playlists guide explains source mix, Focus broadening, fallback behavior, import formats, and retry behavior in more detail.

Imported Playlists

Imported playlists are static. They do not regenerate or replace tracks. If a track fails, Aurral keeps retrying that exact track.

Accepted imports

  • Aurral playlist exports
  • Single playlist objects with a tracks array
  • Raw arrays of track objects
  • Multi-playlist bundles
  • Spotify-style JSON converted from CSV exports

Minimum track shape

{
  "artistName": "Burial",
  "trackName": "Archangel"
}

Use the Spotify Import helper if you are starting from an Exportify CSV file.

Navidrome

Navidrome is optional, but it is the cleanest way to play generated flows. Aurral can create a separate Aurral Weekly Flow library and write smart playlists for your flows and imported playlists.

Recommended setup

  1. Mount your Aurral downloads folder into the container.
  2. Set DOWNLOAD_FOLDER to the host path Navidrome can scan.
  3. Connect Navidrome in Aurral's Integrations settings.
  4. Let Aurral write the flow library and playlist files.
ND_SCANNER_PURGEMISSING=always

Purging missing tracks helps Navidrome clean up old flow entries after a flow rotates.

File Reuse

Aurral can reuse tracks it already downloaded and tracks that already exist in Lidarr. This is useful for imported playlists and repeated tracks across flows.

Mode Behavior
Download Always download a new file into the Aurral library.
Hardlink Try to hardlink a match, then copy if hardlinking is not possible.
Copy Copy a matched file into the playlist folder.

Lidarr-aware reuse requires Aurral to see Lidarr's root directory the same way Lidarr sees it. In Lidarr, find this at Settings -> Media Management -> Root Folders -> Path. If your Lidarr root folder is /data, mount that same host library path into Aurral as /data. 

volumes:
  - /srv/aurral/downloads:/app/downloads
  - /srv/music:/data:ro

Users And Auth

Aurral creates a local admin user during onboarding. Admins can add users and choose what each user can do.

Permissions

  • Access flows and playlists
  • Add artists
  • Add albums
  • Change monitoring
  • Delete artists
  • Delete albums

Other auth options

  • Local-network auto-login for single-admin home setups
  • Reverse-proxy authentication for SSO setups
  • Command-line admin password reset

Storage And Backups

Aurral keeps app state and generated music separate.

Path Contains
/app/backend/data Database, settings, users, sessions, cache state, flow jobs.
/app/downloads Generated flows, imported playlists, staging, and playlist files.

Back up

  • Your mounted backend data folder
  • Your mounted downloads folder if you want generated files preserved
  • Your compose file and `.env` file

Aurral does not directly write into your main music library. Artist and album changes go through Lidarr. Generated files stay in Aurral's own output folder.

Environment Variables Most Users Touch

Most configuration happens in the web UI. These are the deployment variables a normal install may need.

Variable Why you might set it
DOWNLOAD_FOLDER Host path Navidrome should use for the Aurral flow library.
PUID / PGID Run the container as the same user that owns your mounted folders.
TRUST_PROXY Use behind a reverse proxy when client IP forwarding matters.
AUTH_PROXY_* Use only when your reverse proxy handles login for Aurral.
SOULSEEK_USERNAME / SOULSEEK_PASSWORD Optional fixed Soulseek credentials.
AURRAL_VERBOSE_LOGS Turn on more server logs while troubleshooting.

Troubleshooting

Lidarr will not connect

  • Use the URL Aurral can reach, not necessarily your browser URL.
  • In Docker, that is often http://lidarr:8686.
  • Confirm the Lidarr API key.

Discovery is empty

  • Make sure Lidarr is connected and has artists.
  • Add a Last.fm API key for stronger discovery.
  • Set your listening-history username in Account settings.
  • Refresh discovery from Settings.
  • Check whether your blocklist is too broad.

Flows are not downloading

  • Check the Flow worker settings.
  • Rotate or set Soulseek credentials.
  • Disable strict format matching if matches are scarce.
  • Try MP3 if FLAC matches are hard to find.
  • Check the job states on the Flow page.

Files do not appear in Navidrome

  • Confirm /app/downloads is mounted to a real host folder.
  • Confirm DOWNLOAD_FOLDER points to that host folder.
  • Confirm Navidrome can read the same folder.
  • Enable missing-track purging in Navidrome.

Permission errors

  • Make sure mounted folders are writable by the container user.
  • Set PUID and PGID to match the host owner.

Special Thanks

Special thanks to the BrainzMash team for the metadata work that helps make Aurral's artist and album discovery feel rich. Their open-source work is available at statichum/brainzmash-hearring-aid.