🎬 WhatsApp Video Downloader Bot (v3)

🚀 Download Videos from YouTube, Instagram, TikTok, X (Twitter), Reddit, Facebook & Threads directly inside WhatsApp!

Convert, compress, and deliver high-speed social media videos straight to your WhatsApp chats.
Powered by Node.js Baileys, multi-threaded Python engines, and GPU hardware acceleration!

Quick Start • Supported Platforms • Local vs Cloud • Architecture • Web Dashboards

---

🌟 Key Highlights

🛠️ Automated Self-Healing System Features dynamic WhatsApp protocol version fetching, automatic session purge on 405/401 errors, auto-reconnect backoffs, and background yt-dlp auto-updaters!	🔗 Multi-Link Extraction Paste multiple social media links into a single WhatsApp message and the bot will automatically extract, queue, and download each video!
🔍 Cache Integrity Validation Uses ffprobe to verify cached video integrity before serving—automatically purging corrupt or zero-byte files from unexpected shutdowns.	⚡ Playwright Startup Pre-Warming Pre-warms the headless Chromium browser in a background thread on Flask boot up, eliminating launch latency for Instagram fallback downloads.
🔒 In-Flight Deduplication Lock Concurrent requests for the same URL automatically pause and wait on a shared thread lock—eliminating duplicate downloads and saving 50%+ bandwidth.	📊 Live Dashboards & Health APIs Live dashboard at http://localhost:5005/stats plus diagnostic endpoints at http://localhost:5006/health & http://127.0.0.1:5005/health.

---

🌐 Supported Platforms & Features

Platform	Format Supported	Auto-Detection	High-Quality Audio	Quality Selection
YouTube (Videos & Shorts)	🎥 .mp4 / 🎵 .mp3	✅ Yes	✅ 320kbps	✅ 1080p, 720p, 480p
Instagram (Reels & Posts)	🎥 .mp4	✅ Yes	✅ Included	✅ 720p, 480p
TikTok (No-Watermark Reels)	🎥 .mp4	✅ Yes	✅ Included	✅ Auto
X / Twitter	🎥 .mp4	✅ Yes	✅ Included	✅ Auto
Reddit (v.redd.it)	🎥 .mp4	✅ Yes	✅ Included	✅ Auto
Threads	🎥 .mp4	✅ Yes	✅ Included	✅ Auto
Facebook (Public & Watch)	🎥 .mp4	✅ Yes	✅ Included	✅ Auto

---

💻 Local PC vs ☁️ Cloud Hosting

Important

💻 Local PC Hosting (Default - Recommended)

• Runs on Your Laptop/PC: The bot operates whenever your computer is turned ON and connected to Wi-Fi.
• PC Sleep / Shutdown: If your laptop shuts down or goes to sleep, the bot safely pauses.
• Auto Catch-Up: As soon as you turn your PC back on, the bot automatically fetches and downloads any links sent to WhatsApp while you were away!
• Best for Personal Use: Free to run, uses your fast local GPU, and avoids social media cloud IP blocks.

Tip

☁️ Cloud Hosting (True 24/7 Always-On)

• Want the bot running 24/7 without keeping your laptop on? You can host it on a Cloud Server / VPS (DigitalOcean, AWS, Linode, Docker, Render, Railway).
• Cloud Tip: Social networks often restrict datacenter IPs. When hosting in the cloud, supply a cookies.txt file or use a residential proxy in yt-dlp for 100% download reliability.

---

🏗️ Architecture & How It Works

graph TD
    %% Styling
    classDef user fill:#25D366,stroke:#128C7E,stroke-width:2px,color:#fff;
    classDef node fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#fff;
    classDef python fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff;
    classDef hw fill:#831843,stroke:#ec4899,stroke-width:2px,color:#fff;

    A[📱 WhatsApp User]:::user -->|1. Sends Link s in Chat| B[🌉 Node.js Baileys Bridge]:::node
    B -->|2. HTTP API /incoming| C[🐍 Python Flask Server]:::python
    
    subgraph Core Processing Pipeline
        C -->|3. IO ThreadPool Download| D[🎬 yt-dlp / Playwright]:::python
        D -->|4. CPU ThreadPool Compression| E[⚡ FFmpeg Hardware Encoder]:::hw
    end

    E -->|5. HTTP Session Pool /send| B
    B -->|6. Instant WhatsApp Delivery| A

Loading

---

📱 Web Dashboards & Health Monitoring

• WhatsApp Web QR Pairing Dashboard: http://localhost:5006/qr
• Live System Performance Dashboard: http://localhost:5005/stats
• Bridge Diagnostics API: http://localhost:5006/health
• Server Health API: http://127.0.0.1:5005/health

How to Pair Your Device:

1. Start the bot on your computer.
2. Open http://localhost:5006/qr in your browser.
3. Open WhatsApp on your phone → Settings → Linked Devices → Link a Device.
4. Scan the QR code. You're ready to go! 🎉

---

🚀 Quick Start Guide

1️⃣ Clone the Repository

git clone https://github.com/yash161004/whatsapp-video-bot.git
cd whatsapp-video-bot

2️⃣ Install Dependencies

Node.js Bridge Setup:

cd bridge
npm install
cd ..

Python Server Setup:

cd server
python -m venv venv

# Windows:
venv\Scripts\activate
# Linux / macOS:
source venv/bin/activate

pip install -r requirements.txt
cd ..

3️⃣ Environment Configuration

Create a .env file in the bridge/ directory:

PORT=5006
API_KEY=default_secret
MAX_CACHE_GB=5.0

---

🚦 How to Run

Option 1: 1-Click Windows Launcher ⚡

Simply double-click start_bot.bat or run:

start_bot.bat

Option 2: Production PM2 Background Manager 🛡️

Keep the bot running seamlessly in the background with auto-restarts:

npm install -g pm2
pm2 start ecosystem.config.js
pm2 save

Useful PM2 Control Commands:

pm2 status       # Check status of processes
pm2 logs         # View live download & bot logs
pm2 restart all  # Clean restart all services
pm2 stop all     # Pause the bot

---

📜 License

Distributed under the MIT License. See LICENSE for more details.

---

⭐ Enjoying the bot? Give this repository a star to support the project! ⭐