---

🚀 Quick Start

# Clone the repository
git clone https://github.com/MohammadKobirShah/DLHUB.git
cd DLHUB

# Start the stack
docker compose -f compose/docker-compose.yml up -d

# Access the API
curl http://localhost:8000

---

📋 Table of Contents

• About
• Features
• Technology Stack
• Architecture
• Installation
• Configuration
• API Documentation
• Usage Examples
• YouTube Optimization
• Quality Presets
• Media Processing
• WebSocket Real-Time
• Development
• Environment Variables
• License
• Credits
• Connect

---

📖 About

DLHUB is a production-grade, enterprise-ready open media downloading platform powered by yt-dlp and FFmpeg. It provides a robust REST API for downloading videos, audio, and playlists from YouTube and 1000+ other websites.

Built with modern technologies including FastAPI, PostgreSQL, Redis, and Docker, DLHUB offers high performance, scalability, and reliability for self-hosted media processing.

---

✨ Features

Category	Features
Downloads	Video, Audio, Playlist, Channel, Custom Format
Quality	144p, 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p, Best
Formats	MP4, MKV, WEBM, MP3, M4A, FLAC, WAV, AAC, OGG
Embedding	Thumbnails, Metadata, Chapters, Subtitles, Tags
Processing	Transcode, Merge, Trim, Normalize, Extract Audio
Queue	Priority Queue, Retry Logic, Job Management
API	REST API, Swagger UI, ReDoc, OpenAPI Schema
Real-Time	WebSocket Progress, Event Streaming
Monitoring	Prometheus Metrics, Health Checks, Analytics
Security	SSRF Protection, Rate Limiting, Path Traversal Prevention
Storage	PostgreSQL Jobs, Redis Cache, Local/S3 Storage
Deployment	Docker, Docker Compose, Nginx, Non-root Container

---

🛠 Technology Stack

---

🏗 Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                                   DLHUB ARCHITECTURE                           │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐   │
│  │   Client    │────▶│   Nginx     │────▶│  FastAPI   │────▶│   Redis     │   │
│  │  (cURL/UI)  │     │    Proxy    │     │    API      │     │    Queue    │   │
│  └─────────────┘     └─────────────┘     └──────┬──────┘     └─────────────┘   │
│                                                  │                               │
│                            ┌──────────────────────┴──────────────────────┐     │
│                            │                                              │     │
│                    ┌──────▼──────┐                              ┌──────▼──────┐ │
│                    │ PostgreSQL   │                              │  Workers    │ │
│                    │   (Jobs)     │                              │ (yt-dlp)   │ │
│                    └─────────────┘                              └─────────────┘ │
│                                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────────┐  │
│  │                        MEDIA PROCESSING                                  │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │  │
│  │  │ FFmpeg   │  │ Transcode│  │  Merge   │  │  Trim    │  │ Normalize│    │  │
│  │  │Process   │  │          │  │          │  │          │  │          │    │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

---

📦 Installation

Prerequisites

Requirement	Minimum	Recommended
Docker	20.10+	24.0+
Docker Compose	2.0+	2.20+
RAM	2 GB	4 GB
Disk	10 GB	50 GB

Quick Start

# 1. Clone the repository
git clone https://github.com/MohammadKobirShah/DLHUB.git
cd DLHUB

# 2. Start all services
docker compose -f compose/docker-compose.yml up -d

# 3. Check service status
docker compose -f compose/docker-compose.yml ps

# 4. View logs
docker compose -f compose/docker-compose.yml logs -f api

Access Points

Service	URL	Description
🌐 API	http://localhost:8000	Main API endpoint
📚 Swagger	http://localhost:8000/api/v1/docs	Interactive API docs
📖 ReDoc	http://localhost:8000/api/v1/redoc	Alternative API docs
❤️ Health	http://localhost:8000/health	Health check
📊 Metrics	http://localhost:8000/api/v1/system/metrics	Prometheus metrics

---

⚙️ Configuration

Copy .env.example to .env and customize:

# Database
DATABASE_URL=postgresql://dlhub:dlhub123@postgres:5432/dlhub

# Redis
REDIS_URL=redis://redis:6379/0

# Download Settings
DOWNLOAD_DIR=/downloads
MAX_CONCURRENT_DOWNLOADS=50
MAX_DOWNLOAD_SIZE=5GB
MAX_DURATION=7200

# yt-dlp Settings
YTDLP_FORMAT=bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best
YTDLP_EMBED_THUMBNAIL=true
YTDLP_ADD_METADATA=true

# Security
ENABLE_RATE_LIMIT=false
ENABLE_SSRF_PROTECTION=true

---

📡 API Documentation

100+ Endpoints Available

Category	Endpoints	Description
Download	10	Video, Audio, Playlist, Custom
System	18	Health, Version, Stats, Storage
Files	8	List, Download, Stream, Delete
Queue	12	Add, Status, Pause, Resume
Media	15	Transcode, Merge, Trim
YouTube	12	Video, Playlist, Channel Info
Admin	15	Overview, Analytics, Cleanup
WebSocket	4	Progress, Events, Jobs
Total	100+	Full-featured API

---

💡 Usage Examples

Download Video (Best Quality)

curl -X POST "http://localhost:8000/api/v1/download/video" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "quality": "best",
    "format": "mp4"
  }'

Download Video (1080p)

curl -X POST "http://localhost:8000/api/v1/download/video" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "quality": "1080p",
    "format": "mp4"
  }'

Download Audio (MP3)

curl -X POST "http://localhost:8000/api/v1/download/audio" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "format": "mp3"
  }'

Download Playlist

curl -X POST "http://localhost:8000/api/v1/download/playlist" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/playlist?list=PL123456789",
    "quality": "720p",
    "max_items": 50
  }'

Get Job Status

curl "http://localhost:8000/api/v1/download/{job_id}"

List Downloaded Files

curl "http://localhost:8000/api/v1/files"

System Health Check

curl "http://localhost:8000/api/v1/system/health"

---

🎯 YouTube Optimization

DLHUB includes enterprise-grade YouTube optimizations:

• ✅ DASH Merging - Combine video + audio for best quality
• ✅ Fragment Concurrency - Faster downloads with parallel fragments
• ✅ Anti-Throttling - Smart rate limiting bypass
• ✅ Subtitle Auto-Download - Multi-language subtitles
• ✅ Chapter Embedding - Preserve video chapters
• ✅ SponsorBlock Support - Remove sponsored segments
• ✅ Live Stream Support - Capture live broadcasts
• ✅ Cookie Support - Age-restricted video access
• ✅ Resume Support - Continue interrupted downloads

---

📺 Quality Presets

Quality	Resolution	Use Case
best	Any	Highest available quality
2160p	4K UHD	Ultra HD content
1440p	2K QHD	High resolution
1080p	Full HD	Standard HD
720p	HD	High quality
480p	SD	Standard definition
360p	Low	Mobile devices
240p	Very Low	Slow connections
144p	Minimal	Minimal bandwidth

---

🎬 Media Processing

DLHUB provides powerful FFmpeg-based media processing:

Operation	Endpoint	Description
Transcode	/api/v1/media/transcode	Convert to different format
Extract Audio	/api/v1/media/extract-audio	Pull audio from video
Merge	/api/v1/media/merge	Combine multiple videos
Trim	/api/v1/media/trim	Cut specific segment
Normalize	/api/v1/media/normalize	Audio loudness normalization
Waveform	/api/v1/media/waveform	Generate audio visualization
Preview	/api/v1/media/preview	Create short preview clip
GIF	/api/v1/media/gif	Convert video to GIF
Screenshot	/api/v1/media/screenshot	Capture frame at timestamp

---

🔄 WebSocket Real-Time

Connect for live progress updates:

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8000/ws/progress');

// Listen for progress updates
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Progress: ${data.data.progress}%`);
};

// Subscribe to specific job
ws.send(JSON.stringify({
  action: 'subscribe',
  job_id: 'your-job-id'
}));

---

👨‍💻 Development

Local Development Setup

# Create virtual environment
python -m venv venv

# Activate (Linux/Mac)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run development server
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Docker Build

# Build the image
docker build -t dlhub/api -f docker/Dockerfile .

# Run the container
docker run -d -p 8000:8000 --name dlhub dlhub/api

Environment Variables

Variable	Default	Description
APP_NAME	DLHUB	Application name
API_PORT	8000	API server port
DATABASE_URL	postgresql://...	PostgreSQL connection
REDIS_URL	redis://...	Redis connection
DOWNLOAD_DIR	/downloads	Download storage path
MAX_CONCURRENT_DOWNLOADS	50	Maximum parallel downloads
WORKER_COUNT	4	Background worker count

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

💎 Credits

Built with ❤️ by Md Kobir Shah

Powered By

Technology	Description
yt-dlp	YouTube/media downloader
FastAPI	Modern Python web framework
FFmpeg	Media processing
PostgreSQL	Database
Redis	Queue & Cache
Nginx	Reverse proxy

---

🔗 Connect

---

_{DLHUB © 2024 - High-Performance Open Media Downloading Platform}