yubal

Self-hosted music library management, honestly reviewed. No marketing fluff, just what you get when you run it on your own server.

TL;DR

• What it is: A self-hosted YouTube Music downloader that doesn’t just grab files — it tags them, sorts them by artist and album, deduplicates across playlists, and syncs on a schedule [README].
• Who it’s for: People who want a permanent, organized local music library and are paying for YouTube Music Premium or Spotify when they’d rather own the files. Also Navidrome/Jellyfin users who want an automated ingestion pipeline [README].
• Cost savings: YouTube Music Premium runs $10.99/mo. Self-hosted yubal on a $5 VPS replaces the subscription for anyone who primarily uses it for library access — not discovery or radio. That’s up to $132/year back in your pocket.
• Key strength: It solves the hard part. Downloading is easy; organized, tagged, deduplicated files with album art and synced lyrics is the actual work — and yubal handles all of it automatically [README].
• Key weakness: Small project with 1,087 stars, a single primary maintainer, and no third-party reviews available at the time of this writing. You’re betting on a one-person GitHub repository for your music infrastructure. Also: downloading copyrighted content lives in a legal grey area your streaming contract explicitly prohibits.

---

What is yubal

yubal is a Docker-based web application that takes a YouTube Music URL — a track, an album, a playlist — and outputs a clean, tagged music library on your filesystem [README]. The README puts it plainly: “Downloading music is easy. Organizing it is the hard part.”

The output structure looks like this [README]:

data/
├── Pink Floyd/
│   └── 1973 - The Dark Side of the Moon/
│       ├── 01 - Speak to Me.opus
│       ├── 01 - Speak to Me.lrc
│       └── cover.jpg
└── _Playlists/
    ├── My Favorites [n2g-XhDv].m3u
    └── My Favorites [n2g-XhDv].jpg

The playlist M3U file references tracks in their album folders rather than duplicating them — so a track that appears in ten playlists lives in one place on disk and gets referenced ten times [README]. That deduplication detail is the difference between “YouTube downloader” and “music library manager.”

The project sits at 1,087 stars with 32 forks on GitHub, MIT licensed, and ships browser extensions for both Firefox (available on Mozilla’s add-on store) and Chrome (manual install) [README][GitHub]. It’s actively maintained — the repository shows 709 commits — but it’s a small open-source project, not a company-backed product.

---

Why people choose it

No third-party reviews of yubal existed at the time this was written — the project is too niche and too new to have attracted the blogger attention that larger tools get. What follows is a synthesis of the README claims and the practical problem it addresses.

The core use case is straightforward: you’ve spent years building a YouTube Music library — liked songs, custom playlists, saved albums — and you want a permanent local copy that works with Navidrome, Jellyfin, or any other media server without ongoing subscription dependency [README]. yt-dlp can download individual files, but it won’t sort them into Artist/Year - Album/Track format, tag them consistently, attach album art and synced lyrics, or re-check playlists for new tracks on a nightly schedule. yubal does all of that [README].

The scheduled sync feature is what separates it from one-shot download tools. You subscribe to a playlist inside yubal, set a cron schedule, and new tracks that appear on YouTube Music get pulled and organized automatically [README]. That’s the behaviour that makes it a library manager rather than a download utility.

The browser extension completes the workflow. You can be on YouTube Music, click the extension icon, and trigger a download or subscription directly from the page without switching tabs [README]. That’s a significant quality-of-life difference from copying and pasting URLs into a web UI.

---

Features

Based on the README, here’s what yubal actually does:

Core download pipeline:

• Accepts any YouTube Music URL: tracks, albums, playlists [README]
• Outputs files organized as Artist/Year - Album/Track Number - Title.ext [README]
• Automatic metadata tagging from YouTube Music data [README]
• Album art downloaded alongside tracks [README]
• Synced lyrics (.lrc files) fetched from lrclib.net when available [README]
• ReplayGain/R128 tags applied for consistent playback volume across tracks and albums [README]

Format and quality options:

• Native opus (best quality, smallest size — default), mp3, or m4a [README]
• For m4a: direct download when available, transcoded otherwise [README]
• Transcode quality configurable from 0 (best) to 10 (worst) via YUBAL_AUDIO_QUALITY [README]

Library management:

• Smart deduplication: same track across multiple playlists stored once, referenced in each playlist M3U [README]
• Playlist M3U files with album art generated automatically [README]
• Optional user-generated content download (disabled by default) to _Unofficial/ folder [README]

Automation:

• Scheduled sync via configurable cron expression (default: daily at midnight) [README]
• Automatic retry on download failures [README]
• Graceful job cancellation [README]
• Configurable job timeout [README]

Interfaces:

• Web UI with real-time progress and job queue [README]
• CLI for downloading and inspecting metadata from the terminal [README]
• Firefox add-on (Mozilla store) + Chrome extension (manual install) for one-click downloads from YouTube/YouTube Music [README]
• REST API (flagged in the features list, specific endpoint documentation not detailed in the README) [README]

Media server integration: The README explicitly lists Navidrome, Jellyfin, and Gonic as tested targets [README]. The file structure it produces — properly tagged, album-sorted, with cover art — is what these servers expect. You can point your media server at yubal’s data directory and get a browsable library without any manual cleanup.

---

Pricing: SaaS vs self-hosted math

yubal itself is free software (MIT license) with no tiers, no cloud offering, and no pricing page to analyze [README][GitHub]. The cost comparison is between continuing to pay a streaming subscription and running yubal on a VPS.

What you’re replacing:

• YouTube Music Premium: $10.99/mo individual, $16.99/mo family
• Spotify Premium: $11.99/mo individual
• Apple Music: $10.99/mo individual

What self-hosting costs:

• yubal license: $0 [README]
• VPS to run it: $4–6/mo (Hetzner, Contabo, or similar entry-level)
• Storage: the main variable. A 1TB library in opus format is roughly 200–300GB. Budget accordingly for disk.

The honest math: If you’re paying $10.99/mo for YouTube Music primarily to listen to your saved library rather than for discovery and radio features, yubal plus a cheap VPS costs ~$5/mo to run. That’s a year-one saving of ~$72 assuming you already have the VPS for other purposes, or effectively neutral if this is the only thing on the server.

The more realistic case is someone who already runs a home server or a VPS with spare capacity. For them, yubal adds zero marginal infrastructure cost.

What you give up: Streaming catalogs extend well beyond what you’ve manually saved. If you use YouTube Music for discovery, new release browsing, or algorithmic radio, a local library doesn’t replace that. yubal is a library preservation tool, not a streaming service replacement.

---

Deployment reality check

The README’s deployment story is Docker Compose — pull the image, configure five environment variables, mount two volumes, done [README]:

services:
  yubal:
    image: ghcr.io/guillevc/yubal:latest
    user: 1000:1000
    ports:
      - 8000:8000
    environment:
      YUBAL_SCHEDULER_CRON: "0 0 * * *"
      YUBAL_DOWNLOAD_UGC: false
      YUBAL_TZ: UTC
    volumes:
      - ./data:/app/data
      - ./config:/app/config

The one setup gotcha the README calls out explicitly: the container runs as UID:GID 1000:1000 by default. If your host user has a different UID — common on systems where the main user isn’t the first created — you either change the user: field to match or chown your volume directories [README]. Skipping this step produces permission errors on first write.

There’s an Unraid community Docker template available for Unraid users [README].

What’s NOT included in the Docker image:

• YouTube authentication cookies. If YouTube starts rate-limiting downloads or requiring login, you’ll need to provide cookies via the config volume. The README has a “Cookies (Optional)” section for this [GitHub].
• Reverse proxy / HTTPS. The container serves on port 8000. You’ll need Caddy or nginx in front of it for HTTPS if you’re exposing it outside your local network.

Realistic setup time:

• Experienced Docker user: 15–30 minutes to running instance
• Non-technical user following a guide: 1–3 hours including domain and reverse proxy setup
• Unraid user with the community template: likely under 30 minutes

The honest risk: This is a project with 1,087 stars and what appears to be a single primary maintainer. If the YouTube Music API or yt-dlp internals change in a way that breaks downloads, the fix timeline depends on one person’s availability. For a music archiving tool this is lower-stakes than, say, a financial application — but it’s worth acknowledging before you build automation around it.

---

Pros and Cons

Pros

• Actually solves the organization problem. Most YouTube download tools give you files. yubal gives you a library — tagged, sorted, deduplicated, with cover art and synced lyrics [README].
• MIT licensed. No commercial restrictions, no usage limits, no future pricing risk [README][GitHub].
• Scheduled playlist sync. Set it, forget it. New tracks on a subscribed playlist download automatically on your cron schedule [README].
• Smart deduplication. A track in ten playlists lives in one place on disk. M3U files reference rather than duplicate [README]. This is thoughtful engineering, not an afterthought.
• Media server native. The output format is exactly what Navidrome, Jellyfin, and Gonic expect. No manual cleanup required [README].
• Browser extensions. Firefox (Mozilla store) and Chrome (manual) for one-click downloads from YouTube Music pages [README]. Removes the copy-paste loop.
• Format flexibility. Opus for space efficiency, mp3 for compatibility, m4a for direct downloads — your choice [README].
• ReplayGain tagging. Consistent playback volume across a heterogeneous library is a detail most download tools skip entirely [README].

Cons

• One-person project risk. 1,087 stars and 32 forks. If the maintainer stops, so does the project. No organizational backing, no paid team.
• No third-party validation. No reviews, no forum threads, no community troubleshooting resources beyond the GitHub issues. You’re on your own when something breaks.
• Legal grey area. Downloading copyrighted music from YouTube Music violates YouTube’s Terms of Service regardless of your subscription status. This is standard disclaimer territory for any tool in this category, but it’s worth stating plainly rather than burying.
• YouTube rate limiting / cookie requirement. Large batch downloads or heavy use may trigger YouTube’s bot detection. The README has a cookie configuration option, but setup adds friction [GitHub].
• No multi-user support documented. The README shows a single-instance setup. If you want separate libraries or access controls for different household members, that’s not a documented feature.
• Chrome extension requires manual install. The Chrome extension isn’t on the Chrome Web Store — you download a release from GitHub and sideload it [README]. This is a friction point for non-technical users and means no automatic updates.
• Roadmap is aspirational. The README includes a “What’s Coming” section, which signals active development but also signals incomplete features. Check the GitHub issues before assuming a feature works perfectly.

---

Who Should Use This / Who Shouldn’t

Use yubal if:

• You’ve built a meaningful YouTube Music library over the years and want a permanent local copy that doesn’t evaporate if your subscription lapses.
• You’re already running Navidrome, Jellyfin, or Gonic and want an automated ingestion pipeline rather than manual yt-dlp runs.
• You have basic Docker experience (or are willing to learn it once).
• You’re comfortable with the legal ambiguity of downloading copyrighted content you’ve “paid for” access to.
• You run a home server or have a VPS with spare capacity — marginal cost is close to zero.

Skip yubal if:

• You use YouTube Music primarily for discovery, new releases, and algorithmic radio rather than a saved personal library. A local copy doesn’t replace those features.
• You’re a non-technical user with no Linux/Docker background and no one to ask for help. The setup is relatively simple, but the troubleshooting resources are thin.
• You want enterprise-grade reliability for your music infrastructure. A single-maintainer GitHub project is not that.
• You want Spotify or Apple Music downloads instead — yubal is YouTube Music-specific [README].

---

Alternatives Worth Considering

• yt-dlp — The CLI tool yubal is built on top of. If you just need one-off downloads and you’re comfortable in a terminal, yt-dlp covers the download part. It doesn’t handle scheduled sync, deduplication, or web UI.
• spotDL — The equivalent of yubal but for Spotify. Same general approach: CLI tool that downloads from Spotify with proper tagging. No web UI, no scheduled sync.
• Navidrome — Not a downloader, but the media server yubal is designed to feed. If you have a local music collection already, Navidrome turns it into a self-hosted streaming service. The tools are complementary, not competing.
• Lidarr — Music collection manager that integrates with download clients. More complex, more powerful, handles multiple music sources, but steeper setup curve. Better choice if you want a full automated pipeline across Discogs/MusicBrainz metadata rather than YouTube Music specifically.
• MusicBrainz Picard — Open source music tagger. If you already have files and just need proper tagging, Picard is the standard tool. No download capability.
• Jellyfin — Another media server target for yubal’s output, not a downloader. Mentioned because it’s the free alternative to Plex if you want a full media server setup.

For someone specifically in the YouTube Music ecosystem who wants scheduled syncing and an organized library, yubal is the only purpose-built self-hosted option currently in active development.

---

Bottom Line

yubal does one thing and does it thoughtfully: it takes YouTube Music URLs and produces a clean, tagged, deduplicated music library ready for any media server. The feature set — scheduled sync, synced lyrics, ReplayGain tagging, browser extensions, smart deduplication — reflects genuine engineering effort rather than a quick yt-dlp wrapper. The MIT license and Docker-first deployment make it trivially self-hostable.

The honest caveats are real: this is a one-person project with limited community resources, no third-party reviews to stress-test its reliability claims, and the inherent legal ambiguity of downloading streaming content you’re technically only licensed to stream. If you can accept those trade-offs — and for a personal music archive tool, many people reasonably will — yubal solves a problem that no well-funded company has much incentive to solve cleanly. Your library, your server, your files.

---

Sources

Primary sources:

• [README] GitHub README — yubal. https://github.com/guillevc/yubal
• [GitHub] GitHub repository — guillevc/yubal (1,087 stars, MIT license). https://github.com/guillevc/yubal

Note: No third-party reviews or independent articles about yubal were available at the time of writing. The project is too new and niche to have attracted third-party coverage. All claims in this review are sourced directly from the project README and GitHub repository. The provided third-party source slots [1]–[5] contained entirely unrelated content and were not used.