YouTube Video + Lossless FLAC = Perfect MKV

---

Overview

YouFLAC (YouTube + FLAC) is a self-hosted web app that combines YouTube video downloads with lossless audio. Paste a YouTube (or Spotify / Tidal) URL, and YouFLAC:

1. Downloads the video via yt-dlp
2. Fetches the best available lossless FLAC from Soulseek first, with automatic fallback to Tidal, Qobuz, Amazon Music, or Bandcamp
3. Muxes video + FLAC into a single MKV file via FFmpeg

Every FLAC is verified for integrity and quality (sample rate, bit depth, true-lossless flag) before muxing. Bad files are discarded and the next source is tried automatically.

---

Screenshots

Home — paste any YouTube URL	Download Queue

Source Priority (drag-and-drop)	Soulseek Setup

---

Features

• YouTube → MKV — paste any YouTube, Spotify, or Tidal URL; yt-dlp downloads the video, Soulseek provides the FLAC, FFmpeg muxes both into a high-quality .mkv
• Playlists & Channels — batch-download full YouTube playlists or channels
• Soulseek as primary FLAC source — via slsk-batchdl (v2.6+); includes a real login connectivity test
• Multi-Source Fallback — Soulseek → Tidal → Qobuz → Amazon Music → Bandcamp, tried in your configured priority order
• FLAC Verification — integrity check + sample rate/bit depth/lossless validation before muxing; rejects fake-lossless files
• Source Priority UI — drag-and-drop reorder directly in the settings panel
• Queue System — concurrent downloads with live progress, retry, and WebSocket updates
• Playlist — auto-generates .m3u8 after batch downloads
• NFO + Lyrics — metadata files for Jellyfin/Plex/Kodi, synced lyrics from LRCLIB
• Docker + Native — ships as a single binary or Docker image (amd64 / arm64)

---

Install

Docker Compose (recommended)

git clone https://github.com/kushiemoon-dev/YouFLAC.git
cd YouFLAC
cp .env.example .env   # fill in your credentials
docker compose up -d

Access the UI at http://localhost:8080

Docker Run

docker run -d \
  --name youflac \
  -p 8080:8080 \
  -v ./config:/config \
  -v ./downloads:/downloads \
  -e SOULSEEK_USERNAME=you \
  -e SOULSEEK_PASSWORD=secret \
  ghcr.io/kushiemoon-dev/youflac:latest

Native Binary

⬇ Download Latest Release

Platform	File
Linux x86_64	youflac-server-linux-amd64.tar.gz
Linux ARM64	youflac-server-linux-arm64.tar.gz
macOS Apple Silicon	youflac-server-darwin-arm64.tar.gz
Windows x86_64	youflac-server-windows-amd64.zip

tar -xzf youflac-server-linux-amd64.tar.gz
cd youflac-server-linux-amd64
./youflac-server

Note: Native binaries require FFmpeg, ffprobe, and yt-dlp in PATH.
Soulseek requires slsk-batchdl v2.6+ (sldl binary).

---

Configuration

All options can be set via environment variables or through the web UI.

Core

Variable	Default	Description
PORT	8080	HTTP server port
OUTPUT_DIR	/downloads	Download output directory
CONFIG_DIR	/config	Config and database directory
CONCURRENT_DOWNLOADS	2	Parallel downloads (1–5)
NAMING_TEMPLATE	jellyfin	jellyfin, plex, flat, album, year
LOG_LEVEL	info	debug, info, warn, error

Sources

Variable	Default	Description
SOURCE_ORDER	soulseek,tidal,qobuz,amazon,bandcamp	Fallback order for FLAC source selection
SOULSEEK_USERNAME	(none)	Soulseek account username
SOULSEEK_PASSWORD	(none)	Soulseek account password
SOULSEEK_BINARY_PATH	(auto)	Path to sldl binary (auto-detected if in PATH)

Video

Variable	Default	Description
VIDEO_QUALITY	best	yt-dlp video quality: best, 1080p, 720p, 480p
COOKIES_BROWSER	(none)	Browser to extract cookies from for age-restricted videos: firefox, chrome, chromium, brave, opera, edge

Verification

Variable	Default	Description
VERIFY_DOWNLOADS	true	Verify every FLAC before accepting it
VERIFY_MIN_SAMPLE_RATE	44100	Reject files below this sample rate (Hz)
VERIFY_MIN_BIT_DEPTH	16	Reject files below this bit depth

Output

Variable	Default	Description
OUTPUT_DIR	~/MusicVideos	Download output directory (Docker: /downloads)
GENERATE_NFO	true	Generate NFO metadata files
EMBED_COVER_ART	true	Embed cover art in output files
LYRICS_ENABLED	false	Fetch synced lyrics automatically
LYRICS_EMBED_MODE	lrc	lrc, embed, both

---

How It Works

YouTube / Spotify / Tidal URL
        │
   ┌────┴──────────────────────────┐
   ▼                               ▼
yt-dlp (video)         Source Orchestrator (FLAC)
   │                   (SOURCE_ORDER: soulseek first)
   │                        │
   │              ┌─────────┼──────────┬───────────┐
   │              ▼         ▼          ▼           ▼
   │           Soulseek   Tidal     Qobuz    Amazon/Bandcamp
   │            (sldl)    FLAC      FLAC         FLAC
   │              └─────────┼──────────┴───────────┘
   │                        │ first success
   │                        ▼
   │                 FLAC Verification
   │                 (integrity + sample rate / bit depth)
   │                        │
   │                   pass ▼     fail ──► try next source
   └──────────────► FFmpeg mux (-f matroska)
                            │
                            ▼
                      Output .mkv
                   + NFO + Lyrics

  Note: if video download fails (geo-block, age-restrict),
  YouFLAC falls back to audio-only and outputs .flac instead.

---

Soulseek Setup

1. Install slsk-batchdl (v2.6+) and place sldl somewhere in PATH or set SOULSEEK_BINARY_PATH
2. Set SOULSEEK_USERNAME and SOULSEEK_PASSWORD (env vars or Settings UI)
3. Use the Test Login button in Settings → Sources to verify connectivity before downloading

The Docker image bundles a pre-compiled sldl for linux/amd64 and linux/arm64.

---

API

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/version	Current version
GET	/api/queue	List queue items
POST	/api/queue	Add item (URL or metadata)
POST	/api/queue/:id/pause	Pause an item
POST	/api/queue/:id/resume	Resume an item
POST	/api/queue/retry-failed	Retry all failed items
GET	/api/sources	List registered sources and status
POST	/api/soulseek/login-test	Test Soulseek credentials
GET	/api/services/status	Source service health

---

Build from Source

git clone https://github.com/kushiemoon-dev/YouFLAC.git
cd YouFLAC

# Build frontend
cd frontend && pnpm install --frozen-lockfile && pnpm build && cd ..

# Build server
go build -o youflac-server ./cmd/server

# Run
./youflac-server

Requires Go 1.25+, Node.js 22+, pnpm 11+.

---

Credits

• yt-dlp — YouTube video downloading
• slsk-batchdl — Soulseek batch downloader
• FFmpeg — Video/audio muxing and verification
• Fiber — HTTP framework
• Deezer API — ISRC enrichment during downloads
• LRCLIB — Synced lyrics

---

Disclaimer

YouFLAC is intended for personal and educational use only. It is not affiliated with Soulseek, Tidal, Qobuz, Amazon Music, Bandcamp, or Deezer. By using this tool you agree to comply with all applicable laws and the terms of service of the platforms involved. The developers assume no liability for any misuse.

---

MIT License · Releases · Issues