🎬 Modex Downloader Bot

A Telegram bot that downloads media from almost any link — video, photos, image galleries and audio — and sends it straight back to the user.

🚀 Features

• Download from ~1800 sites (anything yt-dlp or gallery-dl supports)
• Handles video, single images, multi-image galleries/carousels, and audio
• Sends image sets back as Telegram albums (media groups)
• Automatic size handling (skips files over Telegram's 50 MB limit)
• Falls back yt-dlp → gallery-dl → direct download so odd links still work
• Per-download temp folders with automatic cleanup
• Download logging + per-user cooldown

---

📂 Project Structure

telegram-video-bot/
│
├── bot.py                  # entrypoint (Telegram + Flask health check)
├── config.py
├── logger.py
│
├── handlers/
│   ├── start.py            # /start /help /about /status /settings
│   ├── callbacks.py        # inline button routing
│   └── download.py         # receives a link, sends back the media
│
├── downloaders/
│   ├── __init__.py         # download_media() / download_video()
│   └── common.py           # universal engine: yt-dlp + gallery-dl + direct
│
├── utils/
│   ├── validators.py       # URL detection + friendly platform labels
│   └── cooldown.py
│
├── database/               # SQLite: users + downloads
├── keyboards/
├── downloads/              # temp working dir (git-ignored)
└── logs/

---

📦 Installation

git clone <your-repo-url>
cd telegram-video-bot

python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # Linux/macOS

pip install -r requirements.txt

ffmpeg must be installed and on PATH (used to merge/repackage video).

---

🔑 Environment Variables

Create a .env file:

BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN

---

▶ Running

python bot.py

Then send the bot any link.

---

🛠 How it works

For each link the engine tries, in order:

1. yt-dlp — best video+audio, capped at 720p / 50 MB so large links can't tie up the bot. Also pulls image posts on supported sites.
2. gallery-dl — used when yt-dlp returns nothing; covers image-first sites (Pinterest, DeviantArt, Tumblr, Reddit galleries, boorus, …).
3. Direct download — last resort for a raw .jpg / .mp4 / .mp3 URL that both extractors refuse.

Everything downloads into a unique folder under downloads/, gets sent back (single file, or batched into albums of 10), and the folder is deleted.

Image-first sites (Pinterest, DeviantArt, Tumblr, imgur, boorus, Instagram /p/ and /reel/, Reddit galleries) go to gallery-dl first; everything else tries yt-dlp first.

Cookies (Instagram / X / login-only content)

Export a logged-in cookies.txt (browser extension "Get cookies.txt LOCALLY"), then either:

• /cookie — send the file to the bot and reply to it with /cookie (restricted to ADMIN ids if ADMIN is set), or
• COOKIES_B64 — set it to base64(cookies.txt); the bot writes the file on startup.

Use a throwaway account. Cloud-server IPs are often blocked by Instagram regardless of cookies.

Limitations

• Telegram bots can't send files larger than ~50 MB — those are skipped.
• Private / age-gated / region-locked content may still fail even with cookies.
• A few multi-image posts may come back with only the first image.

---

🧰 Tech Stack

• Python 3.12
• python-telegram-bot
• yt-dlp + gallery-dl
• Flask (health check)
• SQLite

---

📄 License

MIT License

👨‍💻 Developer

Built by Modex