yt-dlp
yt-dlp is the built-in fallback download source. It searches YouTube for the artist and title of a track.
yt-dlp extracts the audio with ffmpeg. Aurral writes the audio to a staging folder outside your media folders, checks it, tags it, and then moves it into the Downloads Folder.
The default staging folder is /config/_staging. To use another disk, mount it in the Aurral container and set Settings > Download clients > yt-dlp > Staging path. Keep this folder outside every media server library.
yt-dlp needs no separate service. The Docker image includes yt-dlp, ffmpeg, and Node. Aurral uses Node as the JavaScript runtime that yt-dlp needs for YouTube.
For an installation without Docker, install yt-dlp and ffmpeg on the host. Also install a JavaScript runtime such as Node or Deno for YouTube. Make sure that yt-dlp and the runtime are on PATH.
- Open Settings > Download clients > yt-dlp.
- Leave Enable yt-dlp on. It is on by default.
- If necessary, set Source priority or Staging path.
- Select Test connection.
The default priority of yt-dlp is 50. The other sources have lower numbers, so Aurral tries them first.
Behavior
Section titled “Behavior”yt-dlp downloads the tracks that the other sources cannot find. It can also be your only download source. It always downloads one track at a time. It never downloads a whole album at once.
Aurral searches YouTube for the artist and title, then for the artist and title with “official audio” until it finds the artist’s own audio upload. A compilation track is searched by its own artist. If neither search finds anything, Aurral searches for the title and artist.
Aurral prefers the release audio on the artist’s own channel, such as the “Artist - Topic” uploads, then ranks the other results by title, artist, and duration. It skips karaoke, covers, live versions, sped-up or slowed edits, clean edits, and similar unwanted results.
Before Aurral accepts the download, it checks the artist and title that yt-dlp wrote into the file, together with the video title, against the requested track. It ignores upload wording such as “Official Music Video” or “(Audio)”, and it reads “Title - Artist” and “Artist「Title」” titles too. The title must match exactly. The release audio on the artist’s channel, including its lyric videos and visualizers, may differ from the requested length by up to 10 seconds, like another edition of the album. A music video or an upload on another channel must be within 2 seconds. It does not use the file name, because yt-dlp names files by video ID.
If YouTube refuses a download with HTTP 403, Aurral runs it once more with fresh links before it tries the next result.
Aurral then applies the quality profile. It rejects the file if its measured M4A quality is not an enabled tier.
After the checks, Aurral writes the title, artist, album, album artist, year, and track number into the file. Tag-based servers such as Navidrome can then sort the track correctly.
Aurral stores its own identity marker in an AURRAL_IDS tag, so Navidrome does not show it as the track description and your grouping tag stays yours. Older versions wrote the marker into the comment or grouping tag. After an update, Aurral moves it to its own tag once, in the files that it downloaded. It changes the comment or grouping tag only when it holds the marker.
If the file matches the requested track except for its length or part of its title, Aurral holds it in Activity > Queue while it tries the other results and sources. If none of them verifies, you can preview, approve, or deny it.
YouTube audio is usually lossy. For higher quality, prefer slskd, Usenet, or deemix. yt-dlp can supply the first file for a track, but Aurral does not use yt-dlp for upgrades.