guillevc/yubal

yubal

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

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

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

• 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

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

More info in the extension's README.md.

# 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

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

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

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

✅ Supported · ⚙️ Requires configuration · ❌ Not supported

ND_DEFAULTPLAYLISTPUBLICVISIBILITY=true

GONIC_MULTI_VALUE_ARTIST=multi
GONIC_MULTI_VALUE_ALBUM_ARTIST=multi

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

• 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)

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!

Built with yt-dlp and ytmusicapi.

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

MIT

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