Universal Video Downloader

A working full-stack video downloader: a single-file bilingual (Arabic/English) frontend and a FastAPI backend powered by yt-dlp.

universal-downloader/
├── frontend/
│   └── index.html          # Single-page bilingual UI (HTML+CSS+JS, no build step)
├── backend/
│   ├── main.py              # FastAPI app: info/download/audio endpoints
│   ├── requirements.txt
│   └── downloads/           # Temporary storage, auto-cleaned (created at runtime)
├── .env.example
└── README.md

Supported platforms: YouTube, TikTok, Instagram, Facebook, Pinterest, X/Twitter, Reddit, Dailymotion (anything yt-dlp supports for these domains).

---

1. Installation

Requirements: Python 3.10+, and ffmpeg installed on the system (required for merging video+audio streams and for MP3 audio extraction).

# Install ffmpeg (Debian/Ubuntu)
sudo apt-get install -y ffmpeg

# macOS
brew install ffmpeg

Then install the Python dependencies:

cd backend
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate
pip install -r requirements.txt

Copy the environment template and adjust as needed:

cd ..
cp .env.example .env

2. Run the Backend

cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

The API is now live at http://localhost:8000. Interactive API docs (Swagger UI) are auto-generated by FastAPI at http://localhost:8000/docs.

Confirm it's healthy:

curl http://localhost:8000/api/health
# {"status":"ok"}

3. Run the Frontend

frontend/index.html is a static file — no build tools needed. Two ways to serve it:

Option A — open directly: Just open frontend/index.html in your browser. It calls the backend at http://localhost:8000 by default.

Option B — serve over HTTP (recommended, avoids file:// quirks):

cd frontend
python -m http.server 5500
# then open http://localhost:5500

If your backend runs on a different host/port, set window.API_BASE_URL before the page's script runs, e.g. add this in <head>:

<script>window.API_BASE_URL = "https://your-backend-domain.com";</script>

and set ALLOWED_ORIGINS in .env to your frontend's origin (not *) in production.

---

4. API Documentation

GET /api/health

Health check.

{ "status": "ok" }

POST /api/info

Fetch metadata for a video URL.

Request:

{ "url": "https://www.youtube.com/watch?v=..." }

Response:

{
  "success": true,
  "platform": "youtube",
  "title": "...",
  "thumbnail": "...",
  "duration": 213,
  "uploader": "...",
  "view_count": 12345,
  "formats": [
    { "format_id": "137", "height": 1080, "label": "1080p", "ext": "mp4", "filesize": 45312000, "fps": 30 }
  ],
  "has_audio": true
}

POST /api/download

Download a specific video format (server merges best matching audio automatically).

Request:

{ "url": "https://www.youtube.com/watch?v=...", "format_id": "137" }

Response:

{
  "success": true,
  "job_id": "a1b2c3...",
  "filename": "My Video.mp4",
  "download_url": "/api/file/a1b2c3.../My%20Video.mp4",
  "size_mb": 42.7
}

The frontend then fetches download_url (prefixed with the API base) to save the file.

POST /api/audio

Download audio only, converted to MP3 (192kbps).

Request:

{ "url": "https://www.youtube.com/watch?v=..." }

Response: same shape as /api/download.

GET /api/file/{job_id}/{filename}

Serves the prepared file. job_id must be a 32-character hex UUID; path traversal is blocked by validating the resolved path stays inside the download directory.

Error format

All handled errors return:

{ "success": false, "error_code": "PRIVATE_VIDEO", "message": "This video is private and cannot be accessed." }

Possible error_code values: INVALID_URL, UNSUPPORTED_PLATFORM, FORBIDDEN_HOST, PRIVATE_VIDEO, LOGIN_REQUIRED, REGION_RESTRICTED, AGE_RESTRICTED, VIDEO_UNAVAILABLE, VIDEO_TOO_LONG, FILE_TOO_LARGE, RATE_LIMIT_EXCEEDED, SERVER_BUSY, DOWNLOAD_FAILED, SERVER_ERROR.

---

5. Security Notes

• URL scheme validation — only http:// and https:// URLs are accepted.
• Platform allow-list — URLs are matched against the supported domain list before being passed to yt-dlp; unsupported/arbitrary domains are rejected.
• SSRF protection — the hostname is DNS-resolved and checked against loopback, link-local, private, reserved, and multicast IP ranges before any request is made. localhost, 127.0.0.1, 0.0.0.0, and ::1 are explicitly blocked.
• Rate limiting — a per-client-IP minimum interval (RATE_LIMIT_SECONDS, default 3s) is enforced in-memory on every endpoint. For multi-process deployments, replace the in-memory dict with Redis.
• File size / duration limits — MAX_FILE_SIZE_MB and MAX_VIDEO_DURATION_SECONDS are enforced before and after download.
• Concurrency limits — MAX_CONCURRENT_DOWNLOADS caps simultaneous yt-dlp jobs.
• Path traversal protection — the file-serving endpoint validates the job id format and resolves the final path to confirm it's inside the download directory.
• Temporary file cleanup — each request gets its own UUID-named folder; folders older than FILE_RETENTION_SECONDS (default 30 min) are deleted opportunistically on each incoming request. For production, also run a cron/scheduled task calling the same cleanup logic, or move to a background worker.
• No API keys in the frontend — the frontend never holds secrets; all yt-dlp logic and any future third-party API keys stay server-side.
• CORS — set ALLOWED_ORIGINS in .env to your actual frontend origin(s) in production; do not leave it as * when serving real traffic.

This project does not rely on public CORS proxies or anonymous third-party "free" download APIs as its core mechanism — all downloads go through your own backend running yt-dlp, as required.

6. Known Limitations

• Login-gated or private content (private Instagram accounts, login-required Facebook videos, some age-restricted YouTube videos) cannot be downloaded without valid cookies/authentication, which this project intentionally does not implement to avoid credential handling risk. These cases surface a clear LOGIN_REQUIRED / PRIVATE_VIDEO error.
• Platform layout/API changes — social platforms frequently change their internal APIs; yt-dlp is updated very often, so keep yt-dlp upgraded (pip install -U yt-dlp) if extraction starts failing for a given site.
• In-memory rate limiting and job counters reset on restart and don't scale across multiple backend processes/instances — fine for a single-instance deployment; use Redis or a similar shared store for horizontal scaling.
• No real-time progress streaming — the current /api/download and /api/audio endpoints are synchronous (they block until the file is ready, then return a download link); the frontend shows an indeterminate progress bar rather than true byte-level progress. Adding WebSocket or Server-Sent-Events progress reporting is a natural next step.
• No persistent database — history is stored client-side in localStorage only; nothing is tracked server-side beyond the temp files.
• ffmpeg is required on the backend host for format merging and MP3 conversion; without it, downloads requesting merged/converted output will fail with DOWNLOAD_FAILED.
• Respect each platform's Terms of Service and applicable copyright law — this tool is provided for downloading content you own or have the right to download (e.g., your own uploads, or content explicitly licensed for reuse).