TeleDownBot

TeleDownBot is a feature-rich Telegram bot built with Python that lets authorized users download content from a wide range of sources — videos, generic files, GitHub repositories, and container images — and deliver them either directly through Telegram or via S3-compatible storage.

What It Does

Accepts any URL and downloads the file, then uploads it to Telegram or S3
Downloads videos from YouTube, TikTok, and Instagram with quality selection (Best / 1080p / 720p / 480p / 360p / Audio only)
Downloads GitHub repositories as ZIP archives, bare .git clones, or individual release assets
Pulls OCI container images from Docker Hub, GHCR, Quay, and any OCI-compatible registry — saved as portable tar archives via skopeo (no Docker daemon required)
Uploads any Telegram file, video, or voice message directly to S3 and returns a download link

Tech Stack

Area	Tools / Frameworks
Language	Python 3.12
Bot Framework	python-telegram-bot, Telegram Bot API (Polling & Webhook)
Video Downloads	yt-dlp, ffmpeg
Container Pulls	skopeo
Database	SQLite (aiosqlite)
Storage	S3-compatible (AWS S3, MinIO, Backblaze B2, Cloudflare R2)
Deployment	Docker, Docker Compose, CI/CD Pipelines

Features

Multi-source downloads — generic URLs, YouTube, TikTok, Instagram, GitHub, and OCI registries
Dual upload destination — user chooses Telegram or S3 per job
Quality selection — video quality picker for supported sites
GitHub integration — ZIP download, bare clone, or release asset picker with release notes preview
Container image pulls — daemonless registry pulls via skopeo; output is docker load-compatible
Automatic file partitioning — large files are zipped and split to fit Telegram or S3 limits
Global sequential job queue — prevents concurrent overload; live progress updates per job
Per-user access control — admin-managed allowlist with runtime add/remove commands
S3 auto-expiry — lifecycle rules + background cleanup worker for time-limited links
Cookie-based authentication — per-site Netscape cookie files for authenticated downloads
Webhook & polling modes — switchable via config for local dev or production deployment

Design

TeleDownBot is built around a global sequential job queue that serializes all downloads, preventing resource overload while giving each user live progress updates. Jobs are processed one at a time, and every download follows the same path: fetch → partition if needed → deliver to the chosen destination.

The bot supports both polling and webhook modes, making it easy to run locally during development and switch to a production webhook deployment without code changes. It is fully Dockerized for zero-dependency deployment and CI/CD ready for automated rollouts.

GitHub Integration

Three delivery options are available for any GitHub repository URL:

ZIP Archive — downloads the default branch as a ready-to-extract .zip
Bare Clone — packages the full git object store, loadable with git clone
Release Assets — browses the 10 most recent releases with notes, then downloads any chosen asset

Container Image Pulls

Container images are pulled directly from the registry without requiring a Docker daemon or host socket — fully isolated inside the bot's own container. The result is a standard tar archive that can be loaded with docker load on any machine.