README.md

---
title: DownTube - YouTube Downloader
emoji: ⬇️
colorFrom: red
colorTo: blue
sdk: docker
app_port: 8555
---

<div align="center">
  <br>

  # DownTube - YouTube Downloader

  **تحميل فيديوهات يوتيوب مع الترجمات بسهولة وأمان**

  [![Python](https://img.shields.io/badge/Python-3.11%2B-ff4444?style=flat-square&logo=python&logoColor=white)](https://python.org)
  [![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
  [![yt-dlp](https://img.shields.io/badge/yt--dlp-2024%2B-282828?style=flat-square&logo=youtube&logoColor=ff4444)](https://github.com/yt-dlp/yt-dlp)

  <br>

  **Invidious-First** · **Anti-Ban Protection** · **FFmpeg Merge** · **Subtitle Support**

  <br>
</div>

---

## Overview

DownTube is a powerful YouTube downloader with a web interface built with FastAPI. It downloads both **video** and **subtitles** using an Invidious-first strategy that works from cloud servers without cookies.

### Download Strategy (v2.0)

1. **Invidious** (primary): Gets video info + download URLs from Invidious instances (works from cloud IPs!)
2. **FFmpeg merge**: Downloads video+audio separately from Invidious for high quality, then merges
3. **yt-dlp** (fallback): Uses `tv_embedded` client if Invidious fails
4. **Dynamic instance discovery**: Automatically finds working Invidious instances from official API

---

## Features

| Feature | Status |
|---------|:------:|
| Video Info Fetching | ✅ |
| Video Download (360p-4K) | ✅ |
| Subtitle Download (SRT/VTT) | ✅ |
| Auto Subtitles | ✅ |
| Anti-Ban Protection | ✅ |
| Cookies Import | ✅ |
| Download Manager | ✅ |
| Dark Theme | ✅ |
| Invidious-First Strategy | ✅ |
| FFmpeg Video Merge | ✅ |
| Dynamic Instance Discovery | ✅ |

---

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/` | Web UI |
| `GET` | `/api/health` | Server health check |
| `GET` | `/api/video/info` | Fetch video metadata |
| `POST` | `/api/download` | Full download (video + subtitle) |
| `POST` | `/api/download/subtitle` | Subtitle only |
| `POST` | `/api/download/video` | Video only |
| `POST` | `/api/cancel` | Cancel current download |
| `GET` | `/api/progress` | Current progress status |
| `GET` | `/api/downloads` | List downloaded files |
| `GET` | `/api/download/file` | Download a file |
| `DELETE` | `/api/download/file` | Delete a file |
| `GET` | `/api/anti-ban/status` | Anti-ban system status |
| `POST` | `/api/anti-ban/reset` | Reset anti-ban session |
| `GET` | `/api/fallback/status` | Invidious instance status |
| `POST` | `/api/cookies/set` | Set cookies (paste) |
| `POST` | `/api/cookies/upload` | Upload cookies file |
| `GET` | `/api/cookies/status` | Cookies status |
| `DELETE` | `/api/cookies/remove` | Remove cookies |
| `WS` | `/ws` | Real-time progress updates |

---

## License

MIT License — feel free to use and modify.