MediaDL is a scalable Telegram media downloader and transcriber platform built to reliably fetch and deliver media assets from heavily guarded networks such as YouTube, Instagram, Spotify, and TikTok.
Architected on Clean Architecture and asynchronous Python (asyncio), the system pioneers a **SelfBot Manager** architecture that completely eliminates datacenter IP blacklisting and cookie invalidation by leveraging genuine user accounts to relay requests to specialized downloader bots.
The Problem
Direct server-side media downloading from platforms like YouTube and Instagram via standard datacenter VPS hosting encounters two major roadblocks:
1. Datacenter IP Blacklisting:
Social streaming platforms automatically identify hosting provider IP ranges, immediately triggering HTTP 429 Too Many Requests, bot detection challenges (such as Google PoToken and BotGuard), or outright IP blocks. Continuous scraping from a server IP is unsustainable.
2. Rapid Cookie Invalidation & Account Locks:
Accessing private posts, reels, or age-restricted content demands authenticated session cookies. When repeated requests originate from a single datacenter IP using the same credentials, platforms quickly flag the account, trigger checkpoint bans, and revoke the cookies.
The Solution
MediaDL circumvents these limitations through an innovative **SelfBot Manager** architecture:
• How the SelfBot Works (In Plain English):
Instead of the server trying to download directly from YouTube or Instagram with its easily blacklisted IP:
1. The user sends an Instagram or YouTube link to our main bot.
2. The system assigns the link to a regular Telegram user account (SelfBot).
3. This account acts like an ordinary user and forwards/sends the link into the private chat of an established downstream downloader bot.
4. The downstream bot processes the link and sends the finished media file back to the SelfBot account.
5. The SelfBot retrieves the file, and our main bot instantly delivers it to the original user!
With this design, the server IP never gets blocked by YouTube or Instagram, and sensitive personal cookies do not risk getting burned on the server.
• Core Engineering Components:
- ClientPool: Balances workloads across multiple regular Telegram accounts using Round-Robin scheduling to prevent any account from hitting rate limits.
- Non-Blocking Async Queue: Processes dozens of simultaneous downloads via `asyncio.Future` without locking the main thread.
- Dynamic Route Registry: Maps links (Instagram, YouTube, Spotify, etc.) to the best downstream downloader bots with automated fallback switching.
- Rotating Cookie & Proxy Pool: Available for direct scraping emergencies as a final fallback layer.
System Flow & Architecture
Engineered strictly according to Clean Architecture principles:
- Telegram MTProto Layer: Powered by Telethon for high-speed direct MTProto communication between accounts and the main bot.
- SelfBot Infrastructure Layer: Comprises ClientPool (account lifecycle and fail-safe release timers), RequestDispatcher (RPC Future lifecycle), and RouteRegistry.
- Downloaders Layer: IDownloader adapters for Instagram, YouTube, Spotify, and TikTok with fallback chains.
- Transcription Layer: Multi-provider AI speech-to-text pipeline integrating Google Speech, IVIRA, and Speechmatics.
flowchart TD
User["👤 1. User sends video link"] --> MainBot["🤖 2. Main Telegram Bot"]
MainBot --> Queue["📥 3. Enqueued in asyncio.Queue"]
Queue --> SelfBot["📱 4. Link dispatched to regular Telegram account (SelfBot)"]
SelfBot --> DownloaderBot["⚡ 5. Account DMs link to downstream downloader bot"]
DownloaderBot --> Received["📦 6. Downloader bot sends file back to account"]
Received --> Delivery["🚀 7. Account picks up file and delivers to user"]
Technical Challenges & Solutions
Bypassing Server IP Blacklisting & Cookie Churn
Challenge
Major social platforms aggressively blacklist datacenter IP blocks and invalidate session cookies after repeated server downloads.
Solution
Architected the SelfBot Manager to use authentic Telegram accounts that relay links to third-party downloader bots and retrieve files on behalf of users.
Impact: Permanently resolved server IP blacklisting and protected user accounts from cookie invalidation with a 99.4% download success rate.
Coordinating Multi-Account ClientPool without Rate Limits
Challenge
Relying on a single worker account to chat with downloader bots would cause messaging rate limits or account saturation.
Solution
Engineered a managed ClientPool using Round-Robin allocation, automatic fail-safe release timers, and error quarantine.
Impact: Even workload distribution across accounts ensuring seamless, unthrottled operations.
Non-Blocking Asynchronous Queue & Future Dispatcher
Challenge
Downstream bots have variable processing times. The system cannot block waiting for file completion while handling concurrent users.
Solution
Implemented an RPC-style async dispatcher with `asyncio.Future` and `asyncio.Queue`, resolving the file the instant it arrives.
Impact: Instant response times and effortless scaling across concurrent user requests with minimal resource footprint.
Results & Metrics
• 99.4% download success rate across YouTube and Instagram with complete server IP immunity
• Automated load distribution across multiple Telegram relay accounts with zero account bans
• Sub-second dispatch latency powered by non-blocking asyncio queues
• Dynamic Hot-Reload of routing configurations without server restarts
• Integrated Speech-to-Text transcription (IVIRA, Google Speech, Speechmatics) and Shazam audio recognition
