Teaching Jellyfin to feed itself with yt-dlp
A small yt-dlp and ffmpeg music downloader that tags tracks, files them by artist and album, and asks Jellyfin to take a look.
My Jellyfin library is mostly music. Playback was never the annoying part - getting new tracks into the library was. Downloads arrive as loose audio files with half the tags missing, and Jellyfin is only as good as the metadata it is given.
So the automator is a music downloader. yt-dlp fetches the audio, ffmpeg converts and tags it, and a short script puts the result where Jellyfin expects it and triggers a scan. No web UI, no database, just a few commands that do the same thing every time.
The whole pipeline
- Take a list of URLs. Albums, playlists, channels, single tracks - yt-dlp supports a lot of sites, and the script does not care which one it gets.
- Download the best audio. yt-dlp writes into a staging folder, not the live library, so Jellyfin never indexes a half-finished file.
- Let ffmpeg do the conversion. yt-dlp calls ffmpeg to extract the audio, embed the cover art and write the tags it knows about.
- Name the output. Artist / album / track number and title, following the layout Jellyfin’s music scanner expects.
- Move the finished files into the library. Only after yt-dlp exits successfully.
- Refresh Jellyfin. One API call at the end of the batch instead of rescanning the whole library after every track.
The main command is roughly this:
#!/usr/bin/env bash
set -euo pipefail
music="/srv/jellyfin/music"
staging="/srv/jellyfin/staging"
archive="$HOME/.local/state/music-archive.txt"
yt-dlp
--ignore-errors
--no-overwrites
--download-archive "$archive"
--extract-audio
--audio-format mp3
--audio-quality 0
--embed-thumbnail
--add-metadata
--output "$staging/%(artist,uploader)s/%(album,playlist_title,Singles)s/%(playlist_index,00)s - %(title)s.%(ext)s"
--batch-file urls.txt
rsync -a --remove-source-files "$staging/" "$music/"
curl -fsS -X POST "http://jellyfin:8096/Library/Refresh"
-H "X-Emby-Token: $JELLYFIN_TOKEN" That is the shape of it. The real script has a few more checks, but the work is all in those three tools.
Tags matter more than folders
Jellyfin reads embedded metadata first and uses the folder structure as a fallback. That means the important part is not a clever filename - it is making sure the file has an artist, an album, an album artist and a track number.
yt-dlp’s --add-metadata writes what the source provides. Music videos often only
have an uploader, not an artist, so the output can end up in SomeChannel/ instead
of the actual band. Two things help:
- Keep a small overrides file for channels that need a proper artist/album name.
- Run the awkward releases through MusicBrainz Picard, or set the missing fields with ffmpeg.
The folder layout I use is deliberately boring:
/music/
└── Artist/
└── Album/
├── 01 - First Track.mp3
├── 02 - Second Track.mp3
└── cover.jpg Singles go in Artist/Singles/. Multi-disc albums get a CD1, CD2 folder and the
disc tag set, otherwise Jellyfin merges the track numbers and the order breaks.
When yt-dlp cannot tag it
For files that already exist, or sources with useless metadata, ffmpeg can do the conversion and tagging directly:
ffmpeg -i track.webm -i cover.jpg
-map 0:a -map 1:v
-c:a libmp3lame -q:a 0
-c:v mjpeg -disposition:v attached_pic
-metadata artist="Artist"
-metadata album="Album"
-metadata album_artist="Artist"
-metadata title="Track"
-metadata track="1/10"
track.mp3 -disposition:v attached_pic is the part that makes the cover show up as album art
instead of a weird one-frame video stream. Without it, some players ignore the image
entirely.
What actually broke
Duplicate downloads. Filenames change between releases, so checking whether a
file exists is useless. --download-archive remembers source IDs instead and skips
anything it has already seen.
Partial files. The first version pointed yt-dlp straight at the music library. Jellyfin indexed broken files while they were still downloading. Staging plus a move after a successful exit fixed it.
Wrong artist, right song. The uploader is not the artist. A track can download perfectly and still land under the wrong name. This is a tagging problem, not a downloader problem, and no amount of filename logic fixes it.
Slashes and emoji in titles. yt-dlp sanitises the dangerous characters, but --restrict-filenames also strips accents and turns everything into ASCII soup. I
leave it off and let Jellyfin deal with Unicode.
Missing ffmpeg. yt-dlp will happily download the source file and skip the
conversion if ffmpeg is not on PATH. The script checks for both binaries before it
starts, because a silent fallback is worse than a loud failure.
Permissions. The downloader and Jellyfin do not run as the same user. New files were readable on the host and invisible to the server. A shared group and a sane umask solved it.
Scan storms. Refreshing the library after every file made Jellyfin work constantly. One refresh per batch is enough.
Extractors rot. Sites change, yt-dlp updates, downloads break. A music downloader is maintenance, not a one-time script. I keep yt-dlp current and re-run the dry run after upgrades.
What I would do differently
- Log every decision. One line per URL with the final path and the tags that were written. When an album ends up in the wrong place three weeks later, the log is the only way to find out why.
- Use
--simulatefirst. It prints what would be downloaded without touching the disk. Every change to the output template gets tested that way. - Back up the archive file. Losing it means downloading everything again.
- Do not delete the source URL list. It is the only record of what the library is supposed to contain.
The downloader runs at dl.jbugel.xyz, and the script itself is SmoothCLI/crate on GitHub. If you are building the same thing, start with the staging folder and the archive file. The ffmpeg flags are the easy part.