{"id":45830023,"url":"https://github.com/xwc9527/telebackup","last_synced_at":"2026-03-12T07:01:21.290Z","repository":{"id":339221840,"uuid":"1161064599","full_name":"xwc9527/telebackup","owner":"xwc9527","description":"High-speed Telegram file downloader SDK for Python. Multi-connection parallel downloading, checkpoint resume, cross-DC support.","archived":false,"fork":false,"pushed_at":"2026-02-24T02:37:12.000Z","size":159,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T08:54:42.582Z","etag":null,"topics":["asyncio","downloader","file-download","mtproto","parallel-download","python","sdk","telegram-api","telegram-downloader","telethon"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xwc9527.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-18T17:35:43.000Z","updated_at":"2026-02-24T02:37:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xwc9527/telebackup","commit_stats":null,"previous_names":["xwc9527/teleget","xwc9527/telebackup"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/xwc9527/telebackup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwc9527%2Ftelebackup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwc9527%2Ftelebackup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwc9527%2Ftelebackup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwc9527%2Ftelebackup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xwc9527","download_url":"https://codeload.github.com/xwc9527/telebackup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwc9527%2Ftelebackup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30417685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T06:40:58.731Z","status":"ssl_error","status_checked_at":"2026-03-12T06:40:40.296Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","downloader","file-download","mtproto","parallel-download","python","sdk","telegram-api","telegram-downloader","telethon"],"created_at":"2026-02-26T22:00:31.371Z","updated_at":"2026-03-12T07:01:21.275Z","avatar_url":"https://github.com/xwc9527.png","language":"Python","funding_links":[],"categories":["Bots"],"sub_categories":["Bot Libs"],"readme":"# [TeleBackup](https://chatdex.cc) SDK — High-Speed Telegram Download Engine\n\n[![PyPI version](https://img.shields.io/pypi/v/teleget9527)](https://pypi.org/project/teleget9527/)\n[![Python](https://img.shields.io/pypi/pyversions/teleget9527)](https://pypi.org/project/teleget9527/)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMulti-connection parallel file downloading for Telegram\u003c/strong\u003e\u003cbr\u003e\n  Built on \u003ca href=\"https://github.com/LonamiWebs/Telethon\"\u003eTelethon\u003c/a\u003e · Python 3.9+ · Windows / Linux / macOS\n\u003c/p\u003e\n\n\u003e This is the open-source download engine that powers [TeleBackup](https://chatdex.cc). If you need a full-featured desktop client with visual gallery, smart search, and one-click channel backup, visit [chatdex.cc](https://chatdex.cc).\n\n---\n\n## Why [TeleBackup](https://chatdex.cc) SDK?\n\nIf you've tried downloading large files from Telegram using Telethon's built-in `download_media()`, you've likely hit these walls:\n\n**Speed ceiling.** Telethon downloads through a single MTProto connection. On a free account this tops out around 0.3–0.5 MB/s. A 2 GB video takes over an hour — if the connection doesn't drop first.\n\n**Silent throttling.** Telegram's server silently imposes bandwidth limits per account. You won't see an error; your download just stalls repeatedly, tanking average throughput to unusable levels.\n\n**FloodWait punishment.** Send requests too fast and Telegram locks you out with a `FloodWaitError` — anywhere from 30 seconds to 24 hours. Most wrappers either ignore this or leave you to handle it manually.\n\n**No resume.** Connection drops at 95%? Start over. Telethon has no built-in checkpoint mechanism for partial downloads.\n\n**Cross-DC pain.** Files hosted on a different datacenter than your account require special handling. Telethon doesn't handle this transparently for concurrent downloads.\n\n[TeleBackup](https://chatdex.cc) SDK solves all of these with multi-connection parallel downloading, intelligent rate limiting, checkpoint resume, and automatic cross-DC routing.\n\n---\n\n## Download Performance\n\n![download result](docs/8628832b-9b8f-41ca-86e8-ba2130e2e9ac.png)\n\n\u003e 2.16 GB file, free account, same DC — **7.55 MB/s**, 2214/2214 parts, zero failures.\n\n---\n\n## Core Features\n\n- **Multi-connection parallel download** — splits files into chunks, multiple workers download simultaneously\n- **Smart rate limiting** — avoids FloodWait and server-side throttling penalties\n- **Cross-DC support** — automatically detects file datacenter and routes accordingly\n- **Checkpoint resume** — interrupted downloads pick up where they left off, not from zero\n- **Efficient disk I/O** — no temp files, no merge step\n- **Account isolation** — accounts are fully isolated, crash-safe\n- **Proxy auto-detection** — tries system proxy, common local ports, falls back to direct\n- **Multi-account management** — switch between accounts without restarting\n\n---\n\n## Looking for a Desktop App?\n\nThis repository is the **download engine core**. If you want the complete experience — visual media gallery, smart search, one-click channel backup, and local library management — check out the full desktop client:\n\n**[TeleBackup Desktop →](https://chatdex.cc)**\n\n---\n\n## Requirements\n\n| Requirement | Details |\n|-------------|---------|\n| Python | \u003e= 3.9 |\n| OS | Windows 10+, Linux, macOS |\n| Network | Telegram API accessible (direct or via proxy) |\n\n### Telegram API Credentials\n\nYou need a Telegram API ID and API Hash from [my.telegram.org](https://my.telegram.org), and at least one Telethon `.session` file.\n\n### Dependencies\n\n| Package | Purpose | Install |\n|---------|---------|---------|\n| [Telethon](https://github.com/LonamiWebs/Telethon) \u003e= 1.38.0 | Telegram MTProto client | Required |\n| [psutil](https://github.com/giampaolo/psutil) \u003e= 5.9.0 | Process monitoring | Required |\n| [cryptg](https://github.com/cher-nov/cryptg) \u003e= 0.4.0 | Encryption acceleration (~10x faster) | Recommended |\n| [PySocks](https://github.com/Anorov/PySocks) \u003e= 1.7.0 | SOCKS proxy support | Optional |\n\n---\n\n## Installation\n\n```bash\n# From PyPI\npip install teleget9527\n\n# Recommended: with encryption acceleration\npip install teleget9527[fast]\n\n# Full install (encryption + proxy)\npip install teleget9527[all]\n\n# From source\ngit clone https://github.com/xwc9527/TeleGet.git\ncd TeleGet\npip install -e \".[all]\"\n```\n\n---\n\n## Quick Start\n\n### 1. Configure\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your API credentials and session path. See `.env.example` for all available options.\n\n### 2. Session Setup\n\nPlace your Telethon `.session` file in the session directory:\n\n```\ndata/\n└── your_account_id/\n    └── session.session\n```\n\n### 3. Test Login\n\n```bash\npython test_login.py\n```\n\n### 4. Test Download\n\n```bash\npython test_real_download.py\n```\n\n### 5. SDK Usage\n\n```python\nimport asyncio\nfrom tg_downloader import TGDownloader\n\nasync def main():\n    downloader = TGDownloader(\n        api_id=12345678,\n        api_hash=\"your_api_hash\",\n        session_dir=\"./data\",\n    )\n\n    await downloader.start(\"my_account\")\n\n    request_id = await downloader.download(\n        chat_id=-1001234567890,\n        msg_id=42,\n        save_path=\"./downloads/video.mp4\",\n        progress_callback=lambda dl, total, pct: print(f\"{pct:.1f}%\"),\n    )\n\n    # Wait for completion...\n\n    await downloader.shutdown()\n\nasyncio.run(main())\n```\n\nThe SDK provides 4 async methods: `start()`, `download()`, `cancel()`, `shutdown()`.\n\n---\n\n## What [TeleBackup](https://chatdex.cc) SDK Handles\n\nIf you're building a Telegram downloader and hitting these errors, [TeleBackup](https://chatdex.cc) SDK already handles them:\n\n### Telegram API Errors — All Handled Automatically\n\n- **`FloodWaitError: A wait of X seconds is required`** — Telegram locks you out for sending requests too fast. Auto-detects and decelerates before this happens.\n- **`FloodPremiumWaitError`** — Free accounts get throttled 7–11 seconds per hit. Handles the backoff transparently.\n- **`FILE_REFERENCE_EXPIRED` / `FILE_REFERENCE_INVALID`** — File metadata goes stale after ~1 hour. Auto-refreshes without restarting the download.\n- **`AUTH_KEY_UNREGISTERED`** — DC auth key invalidated server-side. Rebuilds authorization automatically.\n- **`AuthBytesInvalidError`** — Cross-DC auth race condition that crashes most implementations. Prevented entirely.\n- **`Server closed the connection` / `ConnectionError`** — Telegram drops sockets under load. Recovers without losing progress.\n- **`0 bytes read on a total of 8 expected bytes`** — Silent connection death. Detects and reconnects.\n- **`asyncio.TimeoutError`** — Requests hang indefinitely. Enforces per-request timeouts and rotates to healthy connections.\n- **`WinError 32: The process cannot access the file`** — Windows file locking during rename. Retries automatically.\n\n### Telegram Download Challenges — All Solved\n\n- **Single-connection speed ceiling** (0.3–0.5 MB/s) → Multi-connection parallel download, 7+ MB/s on free accounts\n- **Undocumented rate limits** → Multi-layer adaptive rate limiting that auto-tunes to your account's limits\n- **FloodWait cascading failures** → Circuit breaker hierarchy isolates failures per-connection\n- **Cross-DC file download** → Automatic DC detection, dedicated connection pool per datacenter\n- **Cross-DC `AuthBytesInvalidError`** → Race condition prevention for concurrent auth exports\n- **No download resume** → Part-level checkpoint persistence, survives crashes and restarts\n- **Cross-session resume** → Switch accounts or restart app, download continues from where it left off\n- **Connection storms after \"Server closed\"** → Disconnect detection with coordinated recovery\n- **Download stalls at 99%** → Watchdog detects stuck workers and force-restarts them\n- **Disk I/O bottleneck** → Sparse file pre-allocation, direct offset writes, no temp files or merge step\n- **Multi-account auth collision** → Process-level account isolation, zero shared state\n\n---\n\n## Troubleshooting\n\n**`FloodWaitError`** — Handled automatically. If frequent, increase `rate_limiter_interval`.\n\n**`FloodPremiumWaitError`** — Free account throttling. Lower `connection_pool_size` to reduce frequency.\n\n**`FILE_REFERENCE_EXPIRED`** — Auto-refreshed up to 3 times. If persistent, the message may have been edited or deleted.\n\n**`AUTH_KEY_UNREGISTERED`** — Auto-recovered. If persistent, your `.session` file may be corrupted — re-login.\n\n**Download stalls** — Watchdog auto-recovers after 30s. Check logs for `[WATCHDOG]` entries.\n\n**`WinError 32`** — Auto-retried. If persistent, another process may be holding the file open.\n\n---\n\n## FAQ\n\n**How to maximize Telegram download speed on a free account?**\n\n[TeleBackup](https://chatdex.cc) SDK uses multi-connection parallel downloading to fully utilize the bandwidth Telegram allocates per account. By opening multiple MTProto connections and downloading different file parts simultaneously, it reaches 7+ MB/s on free accounts — compared to 0.3–0.5 MB/s with single-connection approaches like Telethon's built-in `download_media()`.\n\n**What happens when a download is interrupted?**\n\n[TeleBackup](https://chatdex.cc) SDK persists download progress at the part level. If the process crashes, the network drops, or you restart the application, the download resumes from the last completed part — not from the beginning. This works across sessions and even across account switches.\n\n**How does it handle Telegram's rate limits and FloodWait?**\n\n[TeleBackup](https://chatdex.cc) SDK implements multi-layer adaptive rate limiting with per-connection circuit breakers. It monitors server responses in real time and automatically decelerates before hitting `FloodWaitError` thresholds, keeping your account safe while maintaining maximum throughput.\n\n**Can it download files from a different Telegram datacenter?**\n\nYes. [TeleBackup](https://chatdex.cc) SDK automatically detects which datacenter hosts the target file and manages dedicated connection pools per DC. It handles cross-DC authorization seamlessly, including the `AuthBytesInvalidError` race condition that breaks most other implementations.\n\n**What is the difference between [TeleBackup](https://chatdex.cc) SDK and [TeleBackup](https://chatdex.cc) Desktop?**\n\nThis SDK is the open-source download engine — it provides the core parallel downloading capability as a Python library. [TeleBackup Desktop](https://chatdex.cc) is the full-featured desktop application built on top of this engine, adding a visual media gallery, smart search, channel browsing, and one-click backup with a graphical interface.\n\n---\n\n## License\n\nAGPL-3.0 — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxwc9527%2Ftelebackup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxwc9527%2Ftelebackup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxwc9527%2Ftelebackup/lists"}