yt-dlp
yt-dlp is the built-in fallback download source. It searches YouTube Music, then 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 Library folder.
The default staging folder is /config/_staging. To use another disk, mount it in the Aurral container and set Settings > Downloads > 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 > Downloads > 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. To get single tracks fast, give yt-dlp a lower number than the other sources. A track you download on its own then comes from yt-dlp first, and an album still starts on its release.
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 first searches the songs on YouTube Music for the artist and title. YouTube Music names each song’s artists, album, and length, so Aurral can tell the album’s own audio from covers and other versions. It reads up to six songs, three at a time, and reads the next three only when the first three do not hold the requested track. This usually takes about 4 seconds. After 6 seconds, Aurral stops waiting for YouTube Music.
Aurral skips songs by another artist, such as covers and tribute acts. It also skips songs whose title has version wording that the request does not have, such as “Radio Edit”, “(Live)”, “Acoustic”, “Karaoke”, “Stereo Mix”, or “Alternate Take”. An album named for the version, such as “Pet Sounds (Stereo Mix)”, has it. Remaster, “Mono”, and “feat.” wording does not matter. A song with the same title and length on another album, such as a compilation, is used only after the requested album’s copy. Aurral checks it more strictly after the download, because an album such as a live album does not always say what it is.
If YouTube Music has no usable song, Aurral searches YouTube videos 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 videos by title, artist, and duration. It skips karaoke, covers, live versions, sped-up or slowed edits, clean edits, and similar unwanted videos.
Before Aurral accepts the download, it checks the title and artist that yt-dlp wrote into the file against the requested track. The title must match exactly. For a video, Aurral also reads the video title. It ignores upload wording such as “Official Music Video” or “(Audio)”, and it reads “Title - Artist” and “Artist「Title」” titles too. A song from the requested album on YouTube Music, and 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. Any other download must be within 2 seconds. Aurral 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.