Usenet (Prowlarr and SABnzbd, NZBGet, or Tidarr)

Usenet downloads need two parts:

Prowlarr searches your Usenet indexers. Connect it in Settings > Downloads > Prowlarr.
SABnzbd or NZBGet downloads the results. Connect one of them in Settings > Downloads. You need only one.

Setup

Run Prowlarr with one or more Usenet audio indexers.
Run SABnzbd or NZBGet with a category for Aurral. The default category is aurral.
Mount the same media root in Aurral and SABnzbd or NZBGet, at the same container path, so that Aurral can read the completed files. See Filesystem and mounts.
Open Settings > Downloads > Prowlarr.
Turn on Enable Prowlarr.
Enter the Prowlarr URL and API key.
Select Test connection.
Select Refresh indexers.
Turn on each indexer that Aurral can use, and set its priority.
Open Settings > Downloads.
Turn on Enable SABnzbd or Enable NZBGet.
Enter the URL and credentials.
Select Test connection.

Settings save automatically after each change.

Prowlarr

Settings > Downloads > Prowlarr has these fields:

Server URL: the Prowlarr URL that Aurral can reach, for example http://prowlarr:9696 in Docker.
API key: the Prowlarr API key.
Music categories: the Newznab audio categories. The default is 3000.
Result limit: the most results for one search.

After the connection test, Aurral lists the Usenet indexers from Prowlarr. Open each indexer and set its Priority. A lower number has a higher priority.

Each indexer also has a Download client. Automatic sends its releases to SABnzbd, or to NZBGet when SABnzbd is not connected, or to Tidarr when neither is. Choose a client to send every release from that indexer to it, even from a manual search with another client.

SABnzbd

Settings > Downloads > SABnzbd has these fields:

Server URL: the SABnzbd URL that Aurral can reach, for example http://sabnzbd:8080 in Docker.
API key: the SABnzbd API key.
Category: the SABnzbd category for Aurral jobs. The default is aurral.
Source priority: the order among download sources. The default is 20.
Add NZBs paused: sends jobs to SABnzbd paused.

NZBGet

Settings > Downloads > NZBGet has these fields:

Server URL: the NZBGet URL that Aurral can reach, for example http://nzbget:6789 in Docker.
Username and Password.
Category: the NZBGet category for Aurral jobs. The default is aurral.
Source priority: the order among download sources. The default is 20.
NZB priority: the queue priority that Aurral sends to NZBGet.
Delete leftover files: deletes a download’s folder once Aurral is done with it. Enabled by default.
Completed download path: the folder of finished downloads. Set it only when Aurral cannot find that folder by itself.
Add NZBs paused: sends jobs to NZBGet paused.

Aurral skips NZBGet’s duplicate check for the releases it sends. Upgrading tracks one at a time can grab the same album release more than once, and NZBGet would otherwise delete the repeat as a duplicate.

If NZBGet runs on Windows and reports host paths, mount the parent folder in Aurral. Then add a mapping in Settings > Downloads > Remote path mappings, with Applies to set to NZBGet.

Tidarr

Tidarr downloads albums from Tidal. It needs Tidarr 1.2.9 or later. It works like a Usenet indexer and a SABnzbd client, so Aurral reaches it through Prowlarr.

In Prowlarr, add a Generic Newznab indexer. Set URL to the Tidarr URL, for example http://tidarr:8484, API Path to /api/lidarr, and API Key to Tidarr’s API key from Settings > Security in Tidarr.
In Aurral, open Settings > Downloads and add Tidarr with the same URL and API key.
If you also use SABnzbd or NZBGet, set the Tidarr indexer’s Download client in Settings > Downloads > Prowlarr to Tidarr.

Tidarr saves each album under /shared/nzb_downloads and reports it to Aurral under /downloads. Mount Tidarr’s /shared/nzb_downloads folder in Aurral at /downloads. To mount it elsewhere, add a mapping in Settings > Downloads > Remote path mappings from /downloads, with Applies to set to Tidarr.

Tidarr lists each album in four qualities, from FLAC 24-bit to 96 kbps M4A, and Aurral picks one with your quality profile. Tidarr removes an album’s files when Aurral removes the download.

Behavior

Aurral searches the way Lidarr does. If an indexer supports music search by artist and album, Aurral sends it one first. Then it searches all indexers for the artist and album as text. For a track, it also searches for the artist and track title, to find singles. That is at most three Prowlarr searches for each request.

Aurral cleans the text first: it drops a leading “The”, removes accents, and replaces punctuation with spaces, so AC/DC is searched as AC DC. A compilation is searched as VA with the album title, and then by the title alone.

A release matches when its title contains the artist and the album or track title. A compilation release needs only the album title. A release in another version does not match. A remix or radio edit single does not match the original track, unless the track or album you asked for names that version, or the artist is a karaoke, nightcore, or tribute act. A release whose title names a live, acoustic, instrumental, karaoke, or other version anywhere does not match the album or the track, unless the track or album you asked for names that version, or the artist is a karaoke, nightcore, or tribute act. That includes a note about extras, as in “Album (Deluxe & Live EP Bonus Edition)”, and scene names such as “Artist-Album_Live-WEB-2013-GRP”. A release group that MusicBrainz lists as live, remix, or demo names that version for both. A discography, box set, bootleg, or tribute release does not match either, and an album does not match a greatest-hits release, unless the request names one. Aurral checks every downloaded file before it imports it.

Like Lidarr, Aurral downloads the NZB from Prowlarr itself and sends the file to SABnzbd or NZBGet, so the download client does not need to reach Prowlarr. If the indexer returns an error page instead of an NZB, Aurral tries the next release. If the indexer answers that it has reached its limit (HTTP 429), Aurral asks it for no more NZBs, for any track, until the time it gives, or for one hour when it gives none. Releases from other indexers are still tried.

Aurral watches SABnzbd or NZBGet for as long as the client holds the download, including while it is paused. If the download leaves the client without a history entry, Aurral tries the next release.

For a track whose album Aurral knows, Aurral first searches for the album alone, even for a single track, a playlist track, a flow track, or an upgrade. A Re-search replacement skips this step. A release title does not show the tracklist, so Aurral downloads the NZB and then checks the downloaded files against the requested release. The download counts only when it holds every track of the release, each within 2 seconds of the track’s length on the release, no other song, and no unreadable audio file. Aurral then imports the tracks you want and deletes the rest. A download that is not exactly the release imports nothing, and Aurral does not offer that NZB again for any of the tracks. Aurral then tries the next release, and then the next download source that can supply the release.

When no source has the release, Aurral searches for each track on its own. Among matching releases in one quality tier, a release of the requested album comes before a single. A release title does not show a track’s length, so Aurral can check a release only after it downloads the NZB. To spare your indexers’ grab limits, a track search downloads at most two NZBs, and then Aurral tries the next download source. A request counts when the indexer answers with a file, even one that is not a valid NZB, because the indexer may count it as a grab. A request does not count when the indexer answers with an error status or a Newznab error, or when Aurral skips the indexer while it waits after HTTP 429.

A release that fails to download, or that holds no file for the track, is not offered again for that track.

After Aurral imports a download, or the download fails, it removes the item from the client’s queue and history and deletes the files that Aurral did not import. For NZBGet, turn off Delete leftover files to keep those files. Aurral deletes only the folder NZBGet created for the download. If a post-processing script moved the files elsewhere, Aurral leaves them and the history item in place. When two NZBGet downloads have the same name, NZBGet puts both in one folder, and Aurral removes that folder only with the last of them.

If a file has the requested title but its length or artist credit is a little off, Aurral holds it and tries the other releases and download sources first. If none of them verifies, the file waits in Activity > Queue, where you can preview, approve, or deny it. Aurral keeps the rest of that download until you approve, deny, or remove the song. Automatic upgrades never wait for review. See Track matching for the rules.

Upgrades that start together look for their album’s release together and share one download of it, even when the tracks came from different requests or playlists. Automatic upgrades and Search all start all upgrades of an album together. An upgrade that starts while another upgrade downloads a release of the same album waits for that download to end, for up to 30 minutes, and then downloads its release in full. NZBGet puts two downloads of one NZB in one folder, and a release title does not name the pressing, so two releases of one album can be the same NZB. Upgrades that go on to search for their tracks one by one share one download of a release they all pick.

Quality and upgrades

The quality profile in Settings > Downloads > Quality profile sets the accepted tiers and the cutoff. Aurral reads each downloaded file before it accepts its quality. A quality rejection does not go to Queue review.

Usenet can supply missing tracks and upgrades. See Track upgrades.

Download source priority and fallback

Aurral can use slskd, Usenet, deemix, and yt-dlp together. Each source has a Source priority, and Aurral tries lower numbers first. The defaults are:

Source	Default priority
slskd	`10`
deemix	`15`
SABnzbd, NZBGet, or Tidarr	`20`
yt-dlp	`50`

If a source fails, Aurral tries the next source for the same track. To try another source first, give it a lower number.

Before Aurral searches for a single track, it looks for the exact release of the track’s album on slskd, Usenet, and deemix, in priority order. It does this for Library albums, static playlists, flows, single tracks, and quality upgrades whose album Aurral knows. Re-search replacements skip this step. yt-dlp cannot supply a release, so this step passes over it. When you download one track, or a playlist or flow adds one, and yt-dlp ranks above slskd, Usenet, and deemix, Aurral searches yt-dlp for the track first and looks for the release only if yt-dlp has no match. An album you download never starts on yt-dlp.

The release is the edition that Aurral asked for, with its full tracklist. A source supplies it only when its folder, album, or download holds every track of that release and no other song. A deluxe edition with a bonus track and a shorter edition are different releases. A second copy of a song in another format is fine. Aurral downloads or imports only the tracks you want from it. Tracks that no release fills continue on their own through all sources, in priority order. If the metadata service cannot be reached before the release step, Aurral checks again each minute for up to 30 minutes, then searches for each track. If it cannot be reached after a release has finished downloading, Aurral keeps the download and checks again each minute for up to 30 minutes before it searches for each track.

See Activity to follow the downloads.