KV-DL

The ultra-fast, zero-disk, self-hosted YouTube & media downloader.
Stream merged video + audio or MP3s directly to your browser with full throttle-proof speed.
Built with a high-throughput Rust (Axum) backend, kernel FIFO pipes, and Next.js + Tailwind CSS.

Quick Start • Why KV-DL? • Comparison • Architecture • Synology NAS • Star History

---

⚡ Why KV-DL?

Traditional self-hosted downloaders save files to disk first, burn through server SSD wear, and choke under YouTube's aggressive throttle limits.

KV-DL re-engineers media extraction from scratch:

• 🚀 Throttle-Proof Pipeline: Routes audio and video streams through yt-dlp's optimized HTTP stack directly into kernel pipes (FIFOs). ffmpeg only performs muxing on-the-fly—delivering unrestricted 10–20 MB/s download speeds.
• 💾 100% Zero-Disk Footprint: Streams are multiplexed in RAM and piped straight into the HTTP response. Nothing is ever written to your server's disk or SSD.
• 🍪 Frictionless Cookie Vault: Paste Netscape cookies.txt, JSON exports, or raw Cookie: request headers directly in the UI. Stored safely in an in-memory HMAC-authenticated vault.
• 🔄 Universal Domain Swapping: Automatically transforms swapped links (youtube.<your-domain>/watch?v=...) to pre-load videos directly in the browser.
• 📺 Channel & Playlist Batching: Enumerate up to 500 items in seconds with durations and thumbnails, then trigger one-click batch downloads.
• 📦 Single Lightweight Container: Pure Rust binary embeds the compiled UI. Ships with ffmpeg, yt-dlp, and Node runtime in a single multi-arch container.

---

📊 Competitive Comparison

Capability	🚀 KV-DL	🔵 Cobalt	📁 MeTube	📦 YoutubeDL-Material
Backend Engine	Pure Rust (Axum)	Node.js / Go	Python	Node.js
Server Disk Writes	Zero (100% In-Memory FIFO)	Temp disk files	Saves to disk	Saves to disk
Download Throttling	Bypassed via Kernel FIFOs	Varies	Frequently throttled	Frequently throttled
Cookie Management	In-memory RAM vault (Paste/File)	Environment file	Mounted file	GUI file upload
Domain Swap Routing	Native (.com ⇄ domain)	❌ No	❌ No	❌ No
In-Browser Video Preview	Privacy nocookie embed	❌ No	❌ No	Basic player
Synology NAS Project	1-Click Container Manager	Manual Docker	Manual Docker	Multi-container

---

🔁 How It Works: Zero-Disk Pipeline

flowchart LR
    B["🖥️ Browser Client"]
    V[("RAM-Only Cookie Vault<br/>(HMAC Session)")]
    A["⚙️ Rust Axum API<br/>URL Normalizer"]
    U["📺 YouTube Servers"]
    Y["🐍 yt-dlp Stream Engine"]
    P1(["Kernel FIFO #1<br/>Video Stream"])
    P2(["Kernel FIFO #2<br/>Audio Stream"])
    F["🎞️ ffmpeg Muxer<br/>(Zero Disk Writes)"]

    B -- "Paste Cookies (Auto-detected)" --> V
    V -.-> A
    B ==>|"① POST /api/info"| A
    A ==>|"② Extract format metadata"| U
    U ==>|"③ Title, thumbnail & bitrates"| B
    B ==>|"④ GET /api/download"| Y
    U -->|"High-speed HTTP ranges"| Y
    Y --> P1
    Y --> P2
    P1 --> F
    P2 --> F
    F ==>|"⑤ Fragmented MP4 / MP3 HTTP chunks"| B

The data flow in one sentence:

yt-dlp ──video──▶ FIFO ─┐
                        ├──▶ ffmpeg ──▶ fragmented MP4 ──HTTP chunks──▶ 💾 Browser
yt-dlp ──audio──▶ FIFO ─┘     (muxing, zero disk touch, real-time client progress)

---

🚀 Quick Start (30 Seconds)

Option A: Run Prebuilt Image (Recommended)

Run KV-DL immediately on port 8080:

docker run -d \
  --name kv-dl \
  -p 8080:8080 \
  --restart unless-stopped \
  vndangkhoa/kv-dl:latest

Open http://localhost:8080 in your browser to start downloading.

---

Option B: Docker Compose

Create a docker-compose.yml:

services:
  kv-dl:
    image: vndangkhoa/kv-dl:latest
    # Or use GHCR:
    # image: ghcr.io/vndangkhoa/kv-dl:latest
    container_name: kv-dl
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - SECRET_KEY=change-this-to-a-secure-secret-key
      - SECURE_COOKIES=0 # Set to 1 if behind HTTPS reverse proxy
      - RATE_INFO_PER_MIN=15
      - RATE_DOWNLOAD_PER_MIN=10

Start the service:

docker compose up -d

---

🖥️ Synology NAS Deployment

Deploying on Synology DSM 7.2+ using Container Manager:

1. Open File Station and create folder /volume1/docker/kv-dl/
2. Download docker-compose.synology.yml into that folder
3. Open Container Manager ➔ Projects ➔ Create
4. Select /volume1/docker/kv-dl as the path and build the project
5. Access your downloader at http://<YOUR_NAS_IP>:8080

---

⚙️ Configuration & Environment Variables

Variable	Default	Purpose
PORT	8080	TCP listening port
SECRET_KEY	random	HMAC key for signing cookie sessions
SECURE_COOKIES	0	Set to 1 to enforce Secure cookie flag over HTTPS
RATE_INFO_PER_MIN	10	Allowed metadata queries per IP / min
RATE_DOWNLOAD_PER_MIN	10	Allowed download starts per IP / min
RATE_PLAYLIST_PER_MIN	6	Allowed playlist sweeps per IP / min
DL_CONCURRENCY_PER_IP	2	Max simultaneous active downloads per client IP
DL_CONCURRENCY_GLOBAL	8	Max simultaneous active downloads server-wide
VAULT_MAX_SESSIONS	1000	Max cookie sessions stored in RAM before eviction

---

🛡️ Built-in Abuse Protection

Public downloaders are magnets for bots and scrapers. KV-DL ships with multi-layered defenses:

• Strict Rate Limiting: Per-IP counters with 429 Too Many Requests and Retry-After headers
• Resource Concurrency Gates: Restricts active ffmpeg processes to prevent CPU/bandwidth saturation
• In-Memory Session Limits: Fixed-capacity RAM cookie vault with LRU eviction
• Hardened HTTP Headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, strict CSP

---

🌟 Support & Community

If you love the zero-disk speed of KV-DL, show your support:

• Give the project a Star ⭐ on GitHub!
• Share your setup on Reddit r/selfhosted
• Report issues or suggest formats on GitHub Issues

---

📄 License & Disclaimer

Distributed under the MIT License. See LICENSE for details.

Warning

Downloading copyrighted media may violate content provider Terms of Service. KV-DL is intended for personal archiving of content you own or content licensed for reuse.

Developed with ❤️ by Khoa Vo (@vndangkhoa).