The *arr for one-hit wonders.
For those who like Piña Coladas, Story of a Girl and Breakfast at Tiffany's, but don't need the back-catalogue.
You know the feeling. You want that song — the one everybody knows — and Lidarr hands you the artist's entire discography, three live albums and a Christmas EP to get it. Wondarr is a self-hosted *arr that thinks in songs, not albums. Tell it which songs you want; it goes and gets them, checks they're really the right recording, tags them properly, files them neatly into your library, and keeps an eye out for a better copy until it's happy with the quality.
If you've used Sonarr or Radarr, you already know how to drive it.
Developed in tandem with Claude. All architecture and security decsions human-made, code generation hand-held and reviewed. I have absolutley no intention of this project becoming cooked like Huntarr. That siad if you find anything i didn't, please create an issue or a PR.
- Finds songs where they actually are. Soulseek first (slskd is bundled, nothing to set up), then YouTube Music, then torrents and usenet via qBittorrent, SABnzbd and your indexers or Prowlarr.
- Makes sure it's the right song. Every download is checked by length and an AcoustID fingerprint, so you don't end up with a karaoke version, a live bootleg or a "Story of a Girl (Sped Up)". Fake FLACs made from MP3s get spotted and binned.
- Upgrades quietly. Set a quality profile ("320 kbps is fine" or "FLAC or bust") and Wondarr keeps looking until it gets there.
- Keeps your library tidy. Flat, per artist, artist/album, or a Plexamp layout that keeps albums together so Plex doesn't split them. Songs on compilations get a sensible home ("fewest albums" policy), and you can move one to another album whenever you like.
- Knows what you already own. Point it at your existing music as a reference library: it works out what's in there and never downloads it again (and never touches those files).
- Takes requests in bulk. Paste a list of
Artist - Titlelines, add a whole album's tracklist, or sync a Deezer / YouTube Music playlist, a Spotify CSV export, Last.fm or ListenBrainz loves. - Talks to Plex. New songs show up in Plex straight away, and playlists can be kept in sync.
- Has a page for every song. The file, where it came from, the albums it appears on, BPM, lyrics, history, and (with a free Last.fm key) listener counts, tags and similar songs.
Docker is the way. One container, everything bundled (slskd, ffmpeg, fpcalc, yt-dlp), linux/amd64 and linux/arm64:
services:
wondarr:
image: ghcr.io/wulfftech/wondarr:latest # or pin a version: :0.1
container_name: wondarr
environment:
- PUID=1000
- PGID=1000
- UMASK=002
- TZ=Etc/UTC
volumes:
- ./config:/config
- /srv/data:/data # your music and the downloads, on one mount
ports:
- "1077:1077" # the web UI
- "50300:50300" # Soulseek; forward this on your router for better results
restart: unless-stoppeddocker compose up -dThe same image is on Docker Hub as wulfftech/wondarr, with the same tags. Use it if your NAS's container app only searches Docker Hub.
Unraid? There's a template — see the Unraid guide.
- Open
http://<your-host>:1077and set a login: go to/loginonce from your own network and it asks you to create one (change it later under Settings → General). On your home network Wondarr lets you straight in anyway. - Soulseek: Settings → Soulseek, put in a Soulseek username and password. Make a fresh account just for Wondarr — Soulseek only allows one login per account.
- Your library: Settings → Library. There's a library called Music at
/data/musicalready; point it wherever your music should live and pick a layout (Plexamp is a good default). - Already have music? Settings → Reference libraries → add your existing folder. Wondarr reads it, works out what you've got, and won't fetch any of it again.
- Plex (optional): Settings → Plex, sign in, and link each library to its Plex music section.
- Add some songs: Add songs → type
Deep Blue Something - Breakfast at Tiffany's→ Add. Or paste a whole list. Then watch Activity.
Optional extras, all under Settings: YouTube (off until you turn it on), Download clients and Indexers for torrents/usenet, an AcoustID key for fingerprint checks and a Last.fm key for the fun facts on song pages (Settings → General → Metadata services).
The full manual — install, every setting, Plex, qBittorrent, SABnzbd, troubleshooting — lives at https://wulfftech.github.io/wondarr/.
| Picking the right album for a song | Keeping track of downloads |
|---|---|
 |
 |
Every part of the plan is built and it's in daily use. 0.1.15 is out (release notes), and Wondarr tells you itself when there's a newer one: an Update available badge in the header, with the release notes and the update steps under System → Updates. Found a bug or want something? Open an issue, or add a GitHub token under Settings → General → Contribute with feedback for a feedback button in the header.
C# / .NET 10 (ASP.NET Core, EF Core + SQLite) and a React 19 + Mantine front end — the same family as the other *arrs, so their GPL-3.0 parts could be ported. Port 1077 for the UI and the Lidarr-style API (/api/v1, X-Api-Key), so tools like Prowlarr, autobrr and Homepage plug in the way you'd expect.
For contributors and the curious: where everything is documented
| Read this | For |
|---|---|
The docs site (website/) |
Installing and using Wondarr |
CONTRIBUTING.md |
Prerequisites, build/test commands, repository map and contribution rules |
CHANGELOG.md |
What changed in each release |
NOTICE.md |
Ported-code attributions and the third-party programs bundled in the image |
docs/adr/ |
The architectural decisions, as ADRs |
docs/architecture/ |
Architecture, the matching engine, library output, stack, deployment, quality definitions |
docs/build/ |
Coding standards, repository layout |
GPL-3.0 (see LICENSE). slskd is redistributed unmodified under its own AGPL-3.0 licence and additional terms. See NOTICE.md for the full attribution list.