Send a link. Get the file back.
A lightweight Telegram bot that downloads media from 1000+ platforms with yt-dlp and uploads it straight back to your chat. Pure utility — no AI, no accounts, runs on your own box.
Features
Small, focused, and self-hosted. Everything runs in two containers on your hardware.
1000+ platforms
YouTube, SoundCloud, TikTok, Instagram, Reddit, Twitch, Vimeo, X — anything yt-dlp supports. Drop in a cookies.txt for authenticated sources.
Uploads up to 2 GB
Bundled local Telegram Bot API server lifts the 50 MB cap to 2 GB. One docker compose up.
Tagged MP3 audio
/audio mode returns a clean MP3 with embedded cover art, album-art thumbnail, and title/artist tags.
Inline-playable video
Non-MP4 sources are transcoded to streamable H.264/AAC so Telegram plays them inline, not as a download.
Allowlist access
Gate the bot to specific user IDs — works in DMs and groups they activate. Per-user rate limiting and a global concurrency cap built in.
Cleans up after itself
Temp files are removed after every upload. Optional rotating log keeps a durable download history.
Quick start
Docker Compose brings up the bot and the local Bot API server for 2 GB uploads.
Get your Telegram credentials
A bot token from @BotFather, plus an API ID + hash from my.telegram.org/apps (needed by the local API server).
Configure
cp .env.example .env # set BOT_TOKEN, TELEGRAM_API_ID, TELEGRAM_API_HASH, ALLOWED_USERS
Run
docker compose up -d docker compose logs -f bot
Pulls the prebuilt ghcr.io/antlis/tg-media-bot image — no local build. Then message your bot a URL. That's it.
Other ways to install:
Arch users — paru -S tg-media-bot (AUR, ships a systemd service).
Bare Python and systemd setup are in the installation guide.
Commands
Send any media URL (up to 3 per message) and it downloads in your active mode.
| Command | What it does |
|---|---|
/audio | Switch to audio-only — downloads become tagged MP3s |
/video | Switch to video mode (default) |
/formats <url> | Tap-to-pick a download quality (Best / 1080p / 720p / 480p / Audio) |
/status | Show your queued/active downloads and task IDs |
/cancel <id> | Cancel an active download — actually stops it mid-flight |
/help | Show help and the supported-platforms list |