yubal is a self-hosted YouTube Music downloader that turns a pasted album, playlist or track link into a tidy, fully tagged music library. Rather than dropping numbered files into a folder, it writes an Artist/Year – Album structure with cover art, .lrc lyrics and ReplayGain tags, and keeps subscribed playlists in sync on a cron schedule. It ships as a Docker image with a web UI, a CLI and a browser extension for Firefox and Chrome.

Key Features

• Paste a link, get a library — albums, playlists and single tracks are written to Artist/Year – Album folders with track numbers and cover art
• Scheduled sync — subscribe to a playlist and new tracks are downloaded automatically on the cron interval you set
• Smart deduplication — a track that appears in ten playlists is stored once and referenced from each M3U file
• Web UI with job queue — real-time progress, automatic retry on failure, graceful cancellation, works on mobile
• Synced lyrics — fetches .lrc files from lrclib.net, with YouTube Music lyrics as a fallback
• ReplayGain tagging — track gain per file, plus album gain when a complete album is downloaded
• Format choice — opus (default), mp3 or m4a; direct copy when YouTube offers the format, transcoded otherwise
• Media-server ready — tested with Navidrome, Jellyfin and Gonic, with correct artist links on multi-artist tracks
• Browser extension — download tracks and subscribe to playlists without leaving YouTube Music (Firefox add-on, Chrome via manual install)
• CLI — download and inspect metadata from a terminal

Why Use yubal?

Downloading audio is the easy half; organising it is where most tools leave you with a heap of unsorted files. yubal handles the library side — consistent folder and tag conventions, lyrics, ReplayGain, deduplication and playlist files that stay valid — so the output drops straight into a media server. Everything runs in one container, configured through environment variables, with no external database.

Getting Started

Run the published image (ghcr.io/guillevc/yubal) with port 8000 exposed and two volumes — /app/data for the library and /app/config for state. Useful environment variables include PUID/PGID for file ownership, YUBAL_AUDIO_FORMAT, YUBAL_SCHEDULER_CRON for the sync interval, YUBAL_FETCH_LYRICS, YUBAL_REPLAYGAIN and YUBAL_BASE_PATH when serving under a reverse-proxy subfolder. YouTube cookies can be supplied for account-only content.

Use Cases

• Building an offline library for Navidrome, Jellyfin or Gonic
• Following playlists that change weekly without re-downloading by hand
• Keeping a home-server music collection correctly tagged with artwork

Licence

MIT License — free and open source.

Alternatives

• yt-dlp — the command-line downloader yubal is built on, if you prefer to script it yourself
• Navidrome — open source music server to stream the library yubal builds