yubal

Self-hosted YouTube Music downloader. Paste a link, get a tagged, organized library.

Scheduled sync. Smart deduplication. Media server ready. Browser extension included.

📖 How It Works

Downloading music is easy. Organizing it is the hard part.

yubal takes a YouTube Music URL and produces a clean, tagged music library:

data/
├── Pink Floyd/
│   └── 1973 - The Dark Side of the Moon/
│       ├── 01 - Speak to Me.opus
│       ├── 01 - Speak to Me.lrc
│       ├── 02 - Breathe.opus
│       ├── 02 - Breathe.lrc
│       └── cover.jpg
│
├── Radiohead/
│   └── 1997 - OK Computer/
│       ├── 01 - Airbag.opus
│       ├── 01 - Airbag.lrc
│       ├── 02 - Paranoid Android.opus
│       ├── 02 - Paranoid Android.lrc
│       └── cover.jpg
│
└── _Playlists/
    ├── My Favorites [n2g-XhDv].m3u
    └── My Favorites [n2g-XhDv].jpg

When downloading a playlist, each track lives in its album folder; the M3U file references it:

#EXTM3U
#EXTINF:239,Pink Floyd - Breathe
../Pink Floyd/1973 - The Dark Side of the Moon/02 - Breathe.opus
#EXTINF:386,Radiohead - Paranoid Android
../Radiohead/1997 - OK Computer/02 - Paranoid Android.opus

✨ Features

• Web UI — Real-time progress, job queue, works on mobile
• Albums, playlists & tracks — Paste any YouTube Music link, get organized files
• Scheduled sync — Subscribe to playlists; new tracks appear in your library automatically
• Smart deduplication — Same track across 10 playlists? Stored once, referenced everywhere
• Reliable downloads — Automatic retry on failures, graceful cancellation
• Automatic lyrics — Synced .lrc files for karaoke-style playback in supported players
• ReplayGain tagging — Track gain for consistent volume; album gain when downloading complete albums
• Format options — opus (best quality/size), mp3, or m4a — direct download when available, transcoded otherwise
• Media server ready — Tested with Navidrome, Jellyfin, and Gonic
• CLI — Download and inspect metadata from the terminal

🧩 Browser Extension

Download tracks and subscribe to playlists directly from YouTube and YouTube Music without leaving the page.

More info in the extension's README.md.

🚀 Quick Start

# compose.yaml
services:
  yubal:
    image: ghcr.io/guillevc/yubal:latest
    container_name: yubal
    ports:
      - 8000:8000
    environment:
      PUID: 1000
      PGID: 1000
      YUBAL_SCHEDULER_CRON: "0 0 * * *"
      YUBAL_DOWNLOAD_UGC: false
      YUBAL_TZ: UTC
    volumes:
      - ./data:/app/data
      - ./config:/app/config
    restart: unless-stopped

[!TIP] Volume permissions: Set PUID/PGID to match your host user (run id to check). This also ensures compatibility with podman rootless. If /app/data is an NFS/Unraid mount that does not allow chown, make sure it is already writable by the configured PUID/PGID.

docker compose up -d
# Open http://localhost:8000

Unraid? Use the community Docker template by @SerpentDrago (unraid forum thread).

⚙️ Configuration

🔌 Media Server Integration

Tested with Navidrome, Jellyfin, and Gonic. Artists link correctly, even on tracks with multiple artists.

✅ Supported · ⚙️ Requires configuration · ❌ Not supported

[!TIP] Recommended stack: yubal + Navidrome gives you a self-hosted music streaming setup. Add a client like Symfonium (Android), Amperfy or Arpeggi (iOS), or Supersonic (desktop) to listen anywhere.

ND_DEFAULTPLAYLISTPUBLICVISIBILITY=true

GONIC_MULTI_VALUE_ARTIST=multi
GONIC_MULTI_VALUE_ALBUM_ARTIST=multi

🍪 Cookies (Optional)

Need age-restricted content, private playlists, your Liked Music (list=LM), or Premium quality? Add your cookies:

1. Export https://www.youtube.com/ cookies with a browser extension (yt-dlp guide)
2. Place at config/ytdlp/cookies.txt or upload via the web UI

[!CAUTION] Cookie usage may trigger stricter rate limiting and could put your account at risk. See #3 and yt-dlp wiki.

🗺️ Roadmap

• Flat folder mode
• Post-download webhooks
• New music automatic discovery
• Browser extension (v0.7.0)
• UGC tracks — remixes, unofficial content (v0.5.0)
• Auto-sync playlists (v0.4.0)
• Automatic lyrics (.lrc) (v0.3.0)
• Single track downloads (v0.3.0)
• Playlist support with M3U generation (v0.2.0)

💜 Support

yubal is free, open-source, and built by one person. If it saves you time, consider supporting development:

A ⭐ also helps others find the project!

📈 Star History

🙏 Acknowledgments

Built with yt-dlp and ytmusicapi.

Thanks to everyone who's starred, shared, reported bugs, suggested features, or supported the project 💝

License

MIT

_{For personal archiving only. Comply with YouTube's Terms of Service and applicable copyright laws.}