TeleGrab Pro 🚀

High-Speed Telegram Content Downloader & Real-Time Desktop Management Dashboard

TeleGrab Pro is a desktop web application built for high-throughput downloading of videos, documents, high-resolution photos, audio, and large archives directly from Telegram channels and groups. Powered by Python, Telethon, FastAPI, and WebSockets, it interacts directly with Telegram's native MTProto protocol to deliver maximum network transfer speeds without third-party bot limits.

---

📋 Overview

The Problem

Standard Telegram web clients and bots enforce strict file size caps (e.g., 20 MB / 50 MB limits via standard Bot APIs) and often throttle download speeds when grabbing bulk media, archives, or high-definition videos.

The Solution

TeleGrab connects as a native MTProto client via Telethon, communicating directly with Telegram's data centers. It supports downloading files up to 2 GB (and up to 4 GB with Telegram Premium accounts), features single-link and bulk channel scraping modes, and streams live telemetry (MB/s, ETA, progress bars) over a persistent WebSocket connection to a modern glassmorphic interface.

---

✨ Key Features

• ⚡ Unrestricted MTProto Speeds: Communicates directly with Telegram servers, bypassing standard bot API file size caps and rate restrictions.
• 📦 Multi-Format Support:
  • Videos: MP4, MKV, AVI, WebM without size caps.
  • Documents: PDF, DOCX, XLSX, PPTX, TXT.
  • Archives & Software: ZIP, RAR, 7Z, TAR, APK, ISO.
  • Photos: Full-resolution JPG, PNG, WEBP.
  • Audio: High-bitrate MP3, FLAC, podcasts, voice notes.
  • Large Files: Seamlessly handles files up to 2 GB (4 GB with Premium).
• 🎯 Dual Download Modes:
  • Single Post Mode: Paste any public or private channel post link (t.me/channel/123 or t.me/c/12345/678), preview metadata and size, and download with one click.
  • Bulk Channel Mode: Scan entire channels or chat histories and batch download filtered media categories (e.g., download only PDFs or only videos).
• 📊 Real-Time WebSocket Telemetry:
  • Live download speed monitor (MB/s and KB/s).
  • Smooth percentage progress bars.
  • Transferred bytes vs. total file size calculation.
  • Dynamic estimated time remaining (ETA).
  • Graceful pause, resume, and cancel capabilities.
• 📂 Automated File Categorization: Automatically routes downloaded files into organized subdirectories: downloads/Videos, downloads/Photos, downloads/Documents, downloads/Archives, and downloads/Audio.
• 💻 Modern Glassmorphic UI: Neon gradient accents, dark mode palette, responsive layout, and desktop integration (Open Download Folder).

---

📸 Screenshots

+-----------------------------------------------------------------------------------+
|  [TeleGrab Pro]        [Single Link]   [Bulk Channel]   [Settings]   [Open Folder]|
+-----------------------------------------------------------------------------------+
|  Paste Telegram Post URL:                                                         |
|  [ https://t.me/channel_name/1042                                  ] [ Fetch ⚡ ] |
+-----------------------------------------------------------------------------------+
|  [ Media Preview Card ]                                                           |
|  File: Linux_Kernel_DeepDive.mp4 | Size: 1.42 GB | Type: Video                    |
|                                                                                   |
|  Progress: [██████████████████████░░░░░░] 74%                                     |
|  Speed: 14.8 MB/s  |  Transferred: 1.05 GB / 1.42 GB  |  ETA: 26s                 |
|  Status: Downloading...                [ ⏸ Pause ]   [ ⏹ Cancel ]                |
+-----------------------------------------------------------------------------------+

---

🛠️ Architecture & Data Flow

┌────────────────────────────────┐
│      Glassmorphic Web GUI      │
│  (HTML5, Vanilla CSS, JS)      │
└──────────────┬─────────────────┘
               │  REST API (Fetch metadata / trigger job)
               │  WebSocket (Bidirectional progress telemetry)
               ▼
┌────────────────────────────────┐
│      FastAPI Backend Server    │
│  - Endpoint routing            │
│  - Configuration management    │
└──────────────┬─────────────────┘
               │
               ▼
┌────────────────────────────────┐
│     Downloader Task Queue      │
│  - Chunked file streaming      │
│  - Speed & ETA calculation     │
│  - Auto-categorization engine  │
└──────────────┬─────────────────┘
               │
               ▼
┌────────────────────────────────┐
│   Telethon MTProto Client      │
│  (Direct Telegram API Layer)   │
└──────────────┬─────────────────┘
               │ Encrypted MTProto protocol
               ▼
┌────────────────────────────────┐
│    Telegram Cloud Servers      │
└────────────────────────────────┘

---

💻 Tech Stack

• Backend: Python 3.9+, FastAPI, Uvicorn
• Telegram Client: Telethon (MTProto API protocol)
• Real-Time Communication: WebSockets (asyncio)
• Frontend: Vanilla ES6+ JavaScript, Modern CSS3 (Glassmorphism, CSS Custom Properties), HTML5
• Configuration: JSON-based settings with template schema

---

⚡ Quick Start

1. Prerequisites

• Python 3.9+
• Telegram API Credentials (api_id and api_hash) from my.telegram.org

2. Installation

Clone the repository:

git clone https://github.com/imanandvardhan/telegrab.git
cd telegrab

Install required Python dependencies:

pip install -r requirements.txt

3. Launching

On Windows (1-Click): Double-click run.bat or run:

python main.py

On Linux / macOS:

python3 main.py

Open your browser and navigate to:

http://127.0.0.1:8000

---

🔑 Telegram MTProto Setup Guide

To connect directly to Telegram's MTProto protocol:

1. Log into my.telegram.org using your Telegram phone number and verification code.
2. Navigate to API development tools.
3. Create an application (e.g., App Title: TeleGrabApp, Short Name: telegrab).
4. Copy your api_id (integer) and api_hash (alphanumeric string).
5. Open TeleGrab's Settings tab in the browser, paste your api_id and api_hash, enter your phone number, and confirm the one-time login OTP.

Note

The MTProto session is stored locally on your machine in the data/ directory. Session files are explicitly protected by .gitignore and are never shared or committed to version control.

---

📂 Project Structure

telegrab/
├── backend/
│   ├── app.py                 # FastAPI application & REST/WebSocket routes
│   ├── config.py              # Configuration paths & file type rules
│   ├── downloader.py          # Download queue, speed math & WebSocket broadcaster
│   └── telegram_client.py     # Telethon MTProto client wrapper & link parser
├── frontend/
│   ├── index.html             # Glassmorphic dashboard markup
│   ├── css/
│   │   └── style.css          # Dark neon styling, glass cards, and layouts
│   └── js/
│       └── app.js             # WebSocket handler, progress updater & DOM logic
├── data/
│   ├── config.example.json    # Example configuration template
│   └── .gitkeep
├── downloads/                 # Local directory where organized files are saved
├── main.py                    # Server entry point
├── run.bat                    # Windows 1-click startup launcher
├── requirements.txt           # Python dependencies
├── .gitignore                 # Excludes session files and credentials
└── README.md

---

🔒 Security & Privacy Best Practices

• Zero Credential Exposure: Never commit your api_id, api_hash, or .session files to public git repositories.
• Local Data Storage: All downloads and session data remain strictly on your local filesystem.
• Direct Communication: TeleGrab communicates directly from your machine to Telegram data centers without intermediary proxy servers.

---

🎯 Roadmap

• Multi-threaded segmented downloading for parallelized chunks.
• Automated download scheduling (queue downloads during off-peak network hours).
• Exportable download history logs in JSON/CSV formats.
• Docker containerized deployment with Web UI access.

---

📜 License

This project is licensed under the MIT License.