Yubal Playlist

YouTube Music playlist downloader with Lidarr and Navidrome integration.
No accounts required.

_{GIF is at 3x speed}

Overview

yubal-playlist is a self-hosted app for building a local music library. Paste a YouTube Music playlist URL, and yubal-playlist handles downloading, Lidarr import, and playlist syncing — automatically.

The Pipeline

                ┌─────────┐
                │ YouTube │
                └──────▲──┘
                       │
                    ┌──────────────────┐
                    │  yubal-playlist  │──────► /Channel/Playlist/
YouTube Music ─────►│                  │        ├─01 - Track.opus
Playlist URLs       │     (yt-dlp)     │        ├─02 - Track.opus
                    └──────────────────┘        ├─...
                                                └─cover.jpg

• yt-dlp: Downloads highest available quality audio streams from YouTube.

✨ Features

• Web Interface: Clean, responsive UI for submitting playlist and monitoring real-time progress.
• Job Queue: Integrated FIFO queue that processes downloads sequentially to ensure reliability and avoid rate limiting.
• Format Configuration: Optimized for opus (native YouTube quality), with optional transcoding for other formats
• Docker-ready: Multi-arch support (amd64/arm64) for easy deployment.

Quick Start

The recommended way to run yubal-playlist is via Docker Compose.

1. Copy from deploy/compose.yaml, or use the below:

services:
  yubal-playlist:
    image: ghcr.io/alexlebens/yubal-playlist:latest
    container_name: yubal-playlist
    ports:
      - 8000:8000
    environment:
      YUBAL_TZ: UTC
      # Check the Configuration section for more variables
    volumes:
      - ./data:/app/data # Where your music will be saved
      - ./ytdlp:/app/ytdlp # yt-dlp configuration (cookies)
    restart: unless-stopped

2. Run the container

docker compose up -d

3. Start Downloading

Open your browser to http://localhost:8000 and paste a YouTube Music playlist URL.

Tip

Premium Quality & Age Restrictions

To download age-restricted content or access higher bitrate audio (for Premium accounts), you must provide cookies:

1. Export your cookies using a browser extension. See yt-dlp FAQ
2. Save the file as cookies.txt.
3. Place it in your mounted ytdlp volume (or upload via the Web UI).

Configuration

yubal-playlist is configured via Environment Variables.

Variable	Description	Default (Docker)
YUBAL_HOST	Server bind address	0.0.0.0
YUBAL_PORT	Server listening port	8000
YUBAL_DATA_DIR	Destination for music.	/app/data
YUBAL_YTDLP_DIR	Location of cookies.txt	/app/ytdlp
YUBAL_AUDIO_FORMAT	Output audio codec (e.g., opus, mp3)	opus
YUBAL_AUDIO_QUALITY	Transcoding quality (VBR scale 0-10)	0 (Best)
YUBAL_TZ	Timezone (IANA format)	UTC

Note

Audio Transcoding By default, yubal-playlist keeps the original opus stream from YouTube to maintain maximum quality and processing speed. Transcoding only occurs if you change YUBAL_AUDIO_FORMAT or if the source is not natively available in your chosen format.

Acknowledgments

• Yubal: yubal by guillevc
• Color Scheme: Flexoki by Steph Ango.
• Core Tools: This project would not be possible without yt-dlp.

License

MIT

---

_{This software is for personal archiving only. Users must comply with YouTube's Terms of Service and applicable copyright laws.}