A powerful Telegram bot for downloading videos and audio from YouTube and other platforms supported by yt-dlp.

Developed by using AntiGravity with Claude 4.5 Opus.

• Video Download - Download videos in various qualities (1080p, 720p, 480p, 240p)
• Audio Download - Extract audio in M4A format
• Playlist Download - Download entire playlists at once
• Channel Subscription - Subscribe to channels and get new videos automatically
• Large File Support - Supports files up to 2GB via Local Bot API Server
• Auto-Splitting - Automatically splits large files into parts
• Proxy Rotation - Bypass geo-restrictions with multiple proxy support
• Disk Management - Set maximum disk usage limits
• Cancel Downloads - Cancel ongoing downloads with a button
• Queue System - Process multiple downloads in sequence

YTDL/
├── bot.py              # Main entry point
├── config.py           # Configuration and environment loading
├── database.py         # SQLite database for subscriptions
├── downloader.py       # yt-dlp download functions
├── uploader.py         # Telegram upload functions
├── handlers.py         # Bot command handlers
├── queue_processor.py  # Queue processing logic
├── subscription.py     # Channel subscription monitoring
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

• Docker & Docker Compose
• A Telegram Bot Token (from @BotFather)
• Telegram API credentials (from my.telegram.org)

1. Clone the repository

   git clone https://github.com/yourusername/ytdl-telegram-bot.git
   cd ytdl-telegram-bot

2. Configure environment variables

   cp .env.example .env
   nano .env

3. Edit .env with your settings:

   BOT_TOKEN=your_bot_token_here
   ALLOWED_CHAT_IDS=               # Leave empty to allow all users
   API_URL=http://host.docker.internal:8081/bot
   PROXY=                          # Optional: single proxy
   PROXY_LIST=                     # Optional: comma-separated proxies
   MAX_DISK_GB=10                  # Maximum disk usage in GB
   SUBSCRIPTION_CHECK_INTERVAL=300 # Check for new videos every 5 minutes
   TELEGRAM_API_ID=your_api_id
   TELEGRAM_API_HASH=your_api_hash

4. Start the bot

   docker-compose up -d --build

5. Check logs

   docker-compose logs -f ytdl-bot

Simply send a video URL to download in 1080p (default):

https://www.youtube.com/watch?v=dQw4w9WgXcQ

Or use quality-specific commands:

Example:

/720 https://www.youtube.com/watch?v=dQw4w9WgXcQ

Use the /music command to download audio (M4A format):

/music https://www.youtube.com/watch?v=dQw4w9WgXcQ

Use the /mp3 command to download audio (MP3 format):

/mp3 https://www.youtube.com/watch?v=dQw4w9WgXcQ

Or click the "🎵 Download Audio" button after a video is uploaded.

Download entire playlists:

/playlist https://www.youtube.com/playlist?list=PLxxxxx

With custom quality:

/playlist https://www.youtube.com/playlist?list=PLxxxxx 720

Subscribe to a YouTube channel to get new videos automatically:

/subscribe https://www.youtube.com/@ChannelName

With custom quality:

/subscribe https://www.youtube.com/@ChannelName 720

Manage subscriptions:

/subscriptions      # List your subscriptions
/subs               # Alias for /subscriptions
/unsubscribe https://www.youtube.com/@ChannelName

During download, click the "❌ Cancel" button to stop the current download.

Single Proxy:

PROXY=http://user:pass@proxy.example.com:8080

Multiple Proxies (for geo-restriction bypass):

PROXY_LIST=http://proxy1:8080,socks5://proxy2:1080,http://proxy3:8080

The bot will try each proxy in order when encountering geo-restriction errors.

To restrict bot usage to specific users:

ALLOWED_CHAT_IDS=123456789,987654321,-100123456789

• Positive numbers = User IDs
• Negative numbers starting with -100 = Group IDs

Leave empty to allow all users.

┌─────────────────┐     ┌─────────────────────┐
│   Telegram      │────▶│  Local Bot API      │
│   Client        │     │  Server (Optional)  │
└─────────────────┘     └──────────┬──────────┘
                                   │
                        ┌──────────▼──────────┐
                        │    YTDL Bot         │
                        │  ┌───────────────┐  │
                        │  │  Queue System │  │
                        │  └───────┬───────┘  │
                        │          │          │
                        │  ┌───────▼───────┐  │
                        │  │   yt-dlp      │  │
                        │  │   + FFmpeg    │  │
                        │  └───────────────┘  │
                        │          │          │
                        │  ┌───────▼───────┐  │
                        │  │   SQLite DB   │  │
                        │  │ (Subscriptions)│  │
                        │  └───────────────┘  │
                        └─────────────────────┘

• Downloads: ./downloads/ - Downloaded video files (temporary)
• Database: ./data/subscriptions.db - Channel subscriptions (SQLite)

The Local Bot API Server allows:

• Upload files up to 2GB (vs 50MB standard limit)
• Faster uploads (direct disk access)
• Lower RAM usage (streaming uploads)

You can run automated tests to ensure everything is working correctly.

./run_tests.sh

Requires pytest and dependencies installed:

pip install -r requirements.txt  # If you create one
python -m unittest discover tests

docker-compose logs -f ytdl-bot

• Check MAX_DISK_GB setting
• Clear old downloads: rm -rf ./downloads/*

• Add proxies to PROXY_LIST
• Use VPN on your server

• Check if Local Bot API is running
• Increase timeout values in code

• Check SUBSCRIPTION_CHECK_INTERVAL setting
• Verify database exists: ls ./data/subscriptions.db

MIT License

• yt-dlp - Video downloading
• python-telegram-bot - Telegram API
• FFmpeg - Media processing