{"id":39034719,"url":"https://github.com/lklynet/aurral","last_synced_at":"2026-04-14T02:04:30.616Z","repository":{"id":332850897,"uuid":"1135233078","full_name":"lklynet/aurral","owner":"lklynet","description":"Artist Discovery and Request Manager for Lidarr","archived":false,"fork":false,"pushed_at":"2026-04-01T16:47:51.000Z","size":3397,"stargazers_count":903,"open_issues_count":13,"forks_count":37,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-02T02:39:22.643Z","etag":null,"topics":["jellyseerr","lastfm","lidarr","music","musicbrainz","overseerr","seerr"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lklynet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"lklynet"}},"created_at":"2026-01-15T20:27:08.000Z","updated_at":"2026-04-01T21:28:22.000Z","dependencies_parsed_at":"2026-02-19T03:06:12.977Z","dependency_job_id":null,"html_url":"https://github.com/lklynet/aurral","commit_stats":null,"previous_names":["lklynet/aurral"],"tags_count":171,"template":false,"template_full_name":null,"purl":"pkg:github/lklynet/aurral","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lklynet%2Faurral","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lklynet%2Faurral/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lklynet%2Faurral/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lklynet%2Faurral/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lklynet","download_url":"https://codeload.github.com/lklynet/aurral/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lklynet%2Faurral/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31522574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jellyseerr","lastfm","lidarr","music","musicbrainz","overseerr","seerr"],"created_at":"2026-01-17T17:43:13.668Z","updated_at":"2026-04-14T02:04:30.607Z","avatar_url":"https://github.com/lklynet.png","language":"JavaScript","funding_links":["https://github.com/sponsors/lklynet"],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\" width=\"100%\"\u003e\n  \u003cimg src=\"frontend/public/arralogo.svg\" width=\"128\" height=\"128\" alt=\"Aurral Logo\" /\u003e\n\u003c/div\u003e\n\n# Aurral\n\n[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Flklynet%2Faurral-blue?logo=docker\u0026logoColor=white)](https://ghcr.io/lklynet/aurral) ![GitHub Release](https://img.shields.io/github/v/release/lklynet/aurral) ![GitHub License](https://img.shields.io/github/license/lklynet/aurral)\n[![Build](https://img.shields.io/github/actions/workflow/status/lklynet/aurral/release.yml?branch=main)](https://github.com/lklynet/aurral/actions/workflows/release.yml) ![Discord](https://img.shields.io/discord/1457052417580339285?style=flat) [![Discussions](https://img.shields.io/github/discussions/lklynet/aurral)](https://github.com/lklynet/aurral/discussions) ![GitHub Sponsors](https://img.shields.io/github/sponsors/lklynet)\n\nSelf-hosted music discovery, request management, flows, and playlist importing for Lidarr with library-aware recommendations and Navidrome integration.\n\n## Quick Links\n\n- [Docker image](https://ghcr.io/lklynet/aurral)\n- [Flows and Playlists guide](flows-and-playlists.md)\n- [Spotify import helper](https://aurral.org/aurral-convert)\n- [Discord community](https://discord.gg/cpPYfgVURJ)\n\n---\n\n## What Aurral Does\n\n- Search for artists via MusicBrainz and add them to Lidarr with granular monitoring behavior\n- Browse your library in a clean UI and jump into artist details quickly\n- Discover artists using your library, tags, trends, and Last.fm data\n- Track requests plus queue, download, and import progress\n- Build scheduled flows and static playlists without writing directly into your main library\n\nAurral is designed to be safe for your collection. Main library changes go through Lidarr's API, while flows and imported playlists write into their own separate downloads area.\n\n---\n\n## Quick Start\n\nCreate a `docker-compose.yml`:\n\n```yaml\nservices:\n  aurral:\n    image: ghcr.io/lklynet/aurral:latest\n    restart: unless-stopped\n    ports:\n      - \"3001:3001\"\n    environment:\n      - DOWNLOAD_FOLDER=${DL_FOLDER:-./data/downloads}\n    volumes:\n      - ${DL_FOLDER:-./data/downloads}:/app/downloads\n      - ${STORAGE:-./data}:/app/backend/data\n```\n\nYou 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`.\n\nStart it:\n\n```bash\ndocker compose up -d\n```\n\nOpen `http://localhost:3001` and complete onboarding.\n\n---\n\n## Flows And Playlists\n\nFlows are dynamic playlists that refresh on a schedule. Playlists are static tracklists imported from JSON or saved from an existing flow.\n\n- Create multiple flows with custom size, source mix, focus filters, and scheduled update days/hours\n- Export a generated flow to JSON, then re-import it later as a static playlist, or convert it directly in-app\n- Import shared or hand-built JSON playlists\n- Edit imported playlist names and tracklists directly inside the app\n- Use Navidrome to expose the dedicated Aurral flow library and smart playlists\n- Use the built-in Spotify import button or the [Spotify import helper](https://aurral.org/aurral-convert) to convert existing Spotify playlists into an Aurral-friendly JSON playlist\n\nRelevant links:\n\n- [Flows and Playlists guide](flows-and-playlists.md)\n- [Spotify import helper](https://aurral.org/aurral-convert)\n- [Exportify](https://exportify.net/)\n\n---\n\n## Feature Overview\n\n### Discovery\n\n- Daily Discover recommendations based on your library, tags, and trends\n\n### Lidarr Management\n\n- Add artists with granular monitor options: None, All, Future, Missing, Latest, First\n- Add specific albums from release groups\n- Review request history and queue state from the UI\n\n### Flows\n\n- Multiple scheduled flows with adjustable Discover, Mix, and Trending balance\n- Weekly or custom-day refresh scheduling with per-flow timing\n- Dedicated download output separate from your main music library\n- Optional Navidrome smart playlists in the `Aurral Weekly Flow` library\n\n### Imported Playlists\n\n- Import exported Aurral playlists, single playlist objects, raw track arrays, or multi-playlist bundles\n- Retry the exact imported tracks on failures instead of replacing them\n- Pause or resume retry cycles for incomplete imported playlists\n- Export static playlists back to JSON for sharing\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRequirements And Recommended Stack\u003c/strong\u003e\u003c/summary\u003e\n\n### Required\n\n- Lidarr reachable from Aurral\n- Last.fm API key, with username if you want scrobbling-based discovery\n- MusicBrainz contact email for the required User-Agent policy\n\n### Recommended stack for new users\n\n- Lidarr Nightly\n- Tubifarry\n- slskd\n- Navidrome\n\n### For flows and playlists\n\n- A downloads directory mounted into the container\n- Navidrome if you want library and smart playlist integration\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eScreenshots\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"frontend/images/discover.webp\" width=\"900\" alt=\"Aurral UI\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"frontend/images/recommended.webp\" width=\"440\" alt=\"Recommendations\" /\u003e\n  \u003cimg src=\"frontend/images/artist.webp\" width=\"440\" alt=\"Artist details\" /\u003e\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eData, Volumes, And Safety\u003c/strong\u003e\u003c/summary\u003e\n\n### Downloads and flow library\n\nMount a downloads folder for flows, imported playlists, and optional Navidrome integration.\n\n- Container path: `/app/downloads`\n- Flow output root: `/app/downloads/aurral-weekly-flow`\n- Typical flow track path: `/app/downloads/aurral-weekly-flow/\u003cflow-id\u003e/\u003cartist\u003e/\u003calbum\u003e/\u003ctrack\u003e`\n\n### Main library safety\n\nAurral does not write to your root music folder directly. Main collection changes happen through Lidarr add, monitor, request, and import actions.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eNavidrome Setup\u003c/strong\u003e\u003c/summary\u003e\n\nIf you want flows to appear as a separate library inside Navidrome:\n\n1. In Aurral, go to `Settings -\u003e Integrations -\u003e Navidrome`\n2. Ensure your compose config maps a host folder into `/app/downloads`\n3. Set `DL_FOLDER` once and use it for both `DOWNLOAD_FOLDER` and the `/app/downloads` volume\n\nExample:\n\n- `DL_FOLDER=/data/downloads/tmp`\n- Volume: `${DL_FOLDER}:/app/downloads`\n- Env: `DOWNLOAD_FOLDER=${DL_FOLDER}`\n\nAurral will:\n\n- Create a Navidrome library pointing to `\u003cDOWNLOAD_FOLDER\u003e/aurral-weekly-flow`\n- Write smart playlist files (`.nsp`) into the weekly flow library folder\n\nNavidrome should be configured to purge missing tracks so flow rotations do not leave stale entries:\n\n- `ND_SCANNER_PURGEMISSING=always`\n- `ND_SCANNER_PURGEMISSING=full`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAuthentication And Reverse Proxy\u003c/strong\u003e\u003c/summary\u003e\n\n### Local users\n\nAurral uses local user accounts created during onboarding. Authentication is HTTP Basic Auth at the API layer, so use HTTPS if you expose it publicly.\n\n### Reset forgotten admin password\n\nSet a specific password:\n\n```bash\nnpm run auth:reset-admin-password -- --password \"new-password\"\n```\n\nGenerate a random password:\n\n```bash\nnpm run auth:reset-admin-password -- --generate\n```\n\nThe `--` after `npm run auth:reset-admin-password` tells npm to pass the remaining flags to the reset script.\n\n### Reverse-proxy auth\n\nIf you want SSO, place Aurral behind an auth-aware reverse proxy and forward the authenticated username in a header.\n\n```bash\nAUTH_PROXY_ENABLED=true\nAUTH_PROXY_HEADER=X-Forwarded-User\nAUTH_PROXY_TRUSTED_IPS=10.0.0.1,10.0.0.2\nAUTH_PROXY_ADMIN_USERS=alice,bob\nAUTH_PROXY_ROLE_HEADER=X-Forwarded-Role\nAUTH_PROXY_DEFAULT_ROLE=user\n```\n\n### Trust proxy\n\nIf you are behind a reverse proxy, set:\n\n```bash\nTRUST_PROXY=true\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEnvironment Variables\u003c/strong\u003e\u003c/summary\u003e\n\nMost configuration is handled in the web UI, but these environment variables are still important.\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `PORT` | HTTP port | `3001` |\n| `TRUST_PROXY` | Express trust proxy setting (`true`, `false`, or number) | `1` |\n| `DOWNLOAD_FOLDER` | Flow root folder path used for Navidrome library creation | `${DL_FOLDER:-./data/downloads}` in the compose example |\n| `PUID` / `PGID` | Run container as this UID and GID when starting as root | `1001` / `1001` |\n| `LIDARR_INSECURE` | Allow invalid TLS certificates | unset |\n| `LIDARR_TIMEOUT_MS` | Lidarr request timeout | `8000` |\n| `SOULSEEK_USERNAME` / `SOULSEEK_PASSWORD` | Optional fixed Soulseek credentials | autogenerated if missing |\n| `AUTH_PROXY_*` | Reverse-proxy auth options | unset |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eNotifications\u003c/strong\u003e\u003c/summary\u003e\n\nAurral can send notifications via **Gotify** and **Webhooks** from `Settings -\u003e Notifications`.\n\n### Webhooks\n\nFor each webhook:\n\n- No body sends a `GET` request\n- A body sends a `POST` request with `Content-Type: application/json`\n- Custom headers can be added per webhook\n\nBody templates support two variables:\n\n- `$flowPath` for the music directory, empty for discovery updates\n- `$flowName` for the flow or playlist name\n\nExample:\n\n```json\n{\"src\": \"$flowPath\", \"playlist\": \"$flowName\"}\n```\n\nEvent triggers such as Discover updated and Weekly Flow done apply to all configured webhooks and are invoked sequentially in the order they are defined.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTroubleshooting\u003c/strong\u003e\u003c/summary\u003e\n\n- Lidarr connection fails: confirm the Lidarr URL is reachable and the API key is correct in `Settings -\u003e Integrations -\u003e Lidarr`\n- Discovery looks empty: add artists to Lidarr and configure Last.fm, then give the first recommendation refresh a little time\n- MusicBrainz is slow: MusicBrainz is rate-limited and first runs can take longer\n- Flows do not show in Navidrome: verify `DOWNLOAD_FOLDER` matches your host path mapping and Navidrome purge settings\n- Permission errors writing `./data`: set `PUID` and `PGID` to match your host directory ownership\n\n\u003c/details\u003e\n\n---\n\n## Support\n\n- Community and questions: [Discord](https://discord.gg/cpPYfgVURJ)\n- Bugs and feature requests: [GitHub Issues](https://github.com/lklynet/aurral/issues)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eStar History\u003c/strong\u003e\u003c/summary\u003e\n\n\u003ca href=\"https://www.star-history.com/?repos=lklynet%2Faurral\u0026type=timeline\u0026legend=bottom-right\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/image?repos=lklynet/aurral\u0026type=timeline\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/image?repos=lklynet/aurral\u0026type=timeline\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/image?repos=lklynet/aurral\u0026type=timeline\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flklynet%2Faurral","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flklynet%2Faurral","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flklynet%2Faurral/lists"}