Metadata-Version: 2.4
Name: telegram-turbo-downloader
Version: 0.1.1
Summary: Fast, multi-connection Telegram file downloader with a terminal UI (TUI).
Author-email: SvDp <svdp028@gmail.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/s21v1d9p/telegram-turbo-downloader
Project-URL: Repository, https://github.com/s21v1d9p/telegram-turbo-downloader
Project-URL: Issues, https://github.com/s21v1d9p/telegram-turbo-downloader/issues
Project-URL: Documentation, https://github.com/s21v1d9p/telegram-turbo-downloader#readme
Keywords: telegram,downloader,tui,textual,telethon,parallel-download,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: textual>=0.60.0
Requires-Dist: Telethon>=1.38.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: speed
Requires-Dist: cryptg>=0.4.0; extra == "speed"
Provides-Extra: proxy
Requires-Dist: PySocks>=1.7.0; extra == "proxy"
Provides-Extra: all
Requires-Dist: telegram-turbo-downloader[proxy,speed]; extra == "all"
Dynamic: license-file

<h1 align="center">telegram-turbo-downloader</h1>

<p align="center">
  <strong>Fast, multi-connection Telegram file downloader with a terminal UI (TUI).</strong><br>
  Search a channel or bot, tick the files you want, and download them in parallel — right from your terminal.
</p>

<p align="center">
  <img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-blue">
  <img alt="PyPI" src="https://img.shields.io/pypi/v/telegram-turbo-downloader.svg">
  <img alt="Textual TUI" src="https://img.shields.io/badge/UI-Textual-5a2ca0">
  <img alt="Platform" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey">
  <img alt="License" src="https://img.shields.io/badge/license-AGPL--3.0-green">
</p>

---

`telegram-turbo-downloader` is a **fast Telegram download manager** for the terminal. It downloads large files (movies, series, archives, backups) from Telegram **channels, groups, and search bots** using **multiple parallel connections**, so a 2 GB video that normally crawls at 0.3–0.5 MB/s finishes in minutes instead of hours. It ships as a clean **TUI (text user interface)** — no browser, no bloated desktop client, no manual message-ID hunting.

> **Why is downloading from Telegram so slow?** The standard Telegram client and most libraries pull a file through a **single MTProto connection**, which is heavily rate-limited on free accounts. This tool opens a **pool of connections** and fetches many chunks of the file at once, then reassembles them — dramatically increasing throughput. It also handles **cross-datacenter (cross-DC) routing** and **resumes interrupted downloads** automatically.

## Table of contents

- [Features](#features)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Usage](#usage)
- [How it works](#how-it-works)
- [Configuration](#configuration)
- [FAQ](#faq)
- [Credits](#credits)
- [License](#license)

## Features

- ⚡ **Parallel multi-connection downloads** — saturate your bandwidth instead of one slow MTProto stream.
- 🔎 **Search bots & browse channels** — type a query, the app sends it to the bot and harvests the files it returns; or list a channel's recent files.
- ✅ **Multi-select download queue** — tick several episodes/files and download the whole batch unattended.
- 📊 **Live TUI dashboard** — real-time per-file progress bars, speed, ETA, and part counts.
- ⏸️ **Automatic resume** — interrupted transfers continue from where they stopped (sparse `.part` scanning), no re-downloading finished chunks.
- 🌍 **Cross-DC aware** — correctly downloads files hosted on a different Telegram datacenter than your account.
- 📁 **Smart output folders** — auto-sorts files into `Show/S01/…` or `Movie (Year)/…` from the filename.
- 🖥️ **Cross-platform** — Windows, macOS, and Linux; pure terminal, works over SSH.

## Installation

Requires **Python 3.9+**.

### From PyPI (recommended)

```bash
pip install telegram-turbo-downloader

# optional extras: faster decryption + SOCKS/HTTP proxy support
pip install "telegram-turbo-downloader[all]"
```

### From source

```bash
git clone https://github.com/s21v1d9p/telegram-turbo-downloader.git
cd telegram-turbo-downloader
pip install -e ".[all]"
```

## Quick start

1. **Get Telegram API credentials** at <https://my.telegram.org> → *API development tools*. You'll get an `API_ID` and `API_HASH`.

2. **Configure** — copy the example env file and fill it in:

   ```bash
   cp .env.example .env
   # edit .env: set API_ID and API_HASH
   ```

3. **Log in once** (creates a reusable session):

   ```bash
   telegram-turbo-downloader-login
   ```

4. **Launch the app**:

   ```bash
   telegram-turbo-downloader
   ```

   (Both commands also have a short alias: `ttd-login` / `ttd`.)

## Usage

Inside the TUI:

1. **Open a channel/bot** — type a username like `@some_channel` or `@SomeSearchBot` (or a numeric `-100…` id) and press **Open** to list recent files.
2. **Search** — type a query (e.g. `Panchayat S01`) and press **Search**. The app messages the bot and collects the files it posts back.
3. **Filter** — narrow the visible list as you type.
4. **Select** — press **Space** to tick a file, **A** to select all, **N** to clear.
5. **Download** — press **D**. The dashboard shows every file downloading in parallel with live speed and ETA.

| Key | Action |
| --- | --- |
| `Space` | Select / deselect the highlighted file |
| `A` / `N` | Select all / clear selection |
| `D` | Download selected files |
| `R` | Refresh the current listing |
| `B` | Back to browse (from the dashboard) |
| `Q` | Quit |

Downloaded files are saved under `~/Downloads/` by default, auto-organized by show and season.

## How it works

```
telegram_turbo_downloader/
  app.py           terminal UI entry point (`telegram-turbo-downloader`)
  login.py         one-time session login (`telegram-turbo-downloader-login`)
  tui/             Textual screens: search/browse + live download dashboard
  core/            orchestration: connect, search bot, per-file download logic
  engine/          high-speed parallel download engine (bundled dependency)
```

The `core/` layer resolves a message's file, splits it into 1 MB parts, preallocates a sparse file, and hands the parts to a **worker pool** that fetches them concurrently across a **pool of Telegram connections**. Progress is streamed back to the TUI. Finished transfers are atomically renamed from `*.part` to the final file.

## Configuration

`.env` keys:

| Key | Description |
| --- | --- |
| `API_ID`, `API_HASH` | Your Telegram API credentials (required) |
| `SESSION_DIR` | Where session files are stored (default `./data`) |
| `DOWNLOAD_ACCOUNT` | Account label used for the session folder |
| `DOWNLOAD_CHANNEL` | Optional channel/bot to open on launch |

Environment overrides:

| Variable | Description |
| --- | --- |
| `TTD_JOBS` | Number of parallel connections/workers (default `5`). For free accounts, `5–6` is a good ceiling for cross-DC downloads. |

```bash
TTD_JOBS=6 telegram-turbo-downloader
```

## FAQ

**How do I download large files from Telegram quickly?**
Use a multi-connection downloader like this one. Single-connection downloads are rate-limited; parallel chunked downloading is far faster.

**Can it download from Telegram search bots?**
Yes. Enter the bot's username, type your query, and the app harvests the files the bot replies with.

**Does it resume interrupted downloads?**
Yes — automatically. Re-run the download and it skips already-completed chunks.

**Is a premium Telegram account required?**
No. It works on free accounts; premium accounts simply get higher throughput.

**Where are files saved?**
Under `~/Downloads/`, auto-sorted into show/season or movie folders based on the filename.

## Credits

The bundled parallel download engine in [`telegram_turbo_downloader/engine/`](telegram_turbo_downloader/engine/) is derived from the open-source **TeleBackup SDK** by [xwc9527/telebackup](https://github.com/xwc9527/telebackup) (also on PyPI as [`teleget9527`](https://pypi.org/project/teleget9527/)), redistributed under the AGPL-3.0 license. The only change from upstream is that in-code comments and log/UI strings were translated from Chinese to English; the program logic is unchanged. All credit for the download engine goes to its original authors. See [`NOTICE`](NOTICE) for details.

The terminal UI, search/browse/queue orchestration, and documentation are original work.

## License

Licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)** — see [`LICENSE`](LICENSE). Because the bundled engine is AGPL-3.0, this project (as a whole) is distributed under the same license.
