telegram-dl 2.0.1

A production-ready Python CLI tool to download videos from Telegram channels

telegram-dl

Download videos from your own Telegram channels and groups easily.

This tool uses Telegram's official API - the same way the Telegram app works. It's 100% legal according to Telegram's Terms of Service.

Installation

pip install telegram-dl

Quick Start (3 Steps)

Step 1: Get Telegram API Credentials (Free)

1. Go to my.telegram.org
2. Login with your phone number
3. Click "API development tools"
4. Click "Create application"
5. Copy your API ID and API Hash

Step 2: Find Your Channel ID

# Run this command with your credentials
telegram-dl --api-id YOUR_API_ID --api-hash YOUR_API_HASH --phone [phone] --list-channels

You'll see a list like:

Available channels and groups:

  [Channel] -1001234567890 | My Learning Videos
  [Channel] -1009876543210 | Course Materials
  [Group]   -1001112223334 | Study Group

Step 3: Download Videos

# Download all videos from a channel
telegram-dl --api-id 12345 --api-hash abc123 --phone [phone] --channel -1001234567890

Is This Legal?

Yes, absolutely!

This tool uses Telegram's Official API, which is the same API used by:

• The official Telegram app
• Telegram Desktop
• Telegram Web
• Many other Telegram clients

What this means:

• ✅ Downloads videos from channels you are a member of
• ✅ Uses MTProto protocol (Telegram's official protocol)
• ✅ Your credentials stay on your device
• ✅ No data is sent to third parties

What you can do:

• ✅ Download your own content
• ✅ Download content from channels you joined
• ✅ Backup your purchased courses

What you cannot do:

• ❌ Download from private channels you're not a member of
• ❌ Redistribute copyrighted content
• ❌ Violate channel/group rules

Read more: Telegram API Terms

Features

For Users

• Easy to use - Just 3 commands to get started
• Progress tracking - See download progress with progress bars
• Skip existing - Don't re-download files you already have
• Multiple retry - Automatically retries failed downloads
• Custom output - Save to any folder you want

For Developers (Interview Ready!)

• Production-Ready Code - Clean architecture with SOLID principles
• Design Patterns - Builder, Factory, Observer, Repository, Strategy
• Type Safety - Full Pydantic validation
• Well Tested - 27 unit tests
• Documented - Comprehensive docstrings
• Extensible - Easy to add new features

How It Works

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                        You (User)                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    CLI Interface                            │
│            (Commands: --list-channels, --download)          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  TelegramDownloader                        │
│    - Manages connection                                    │
│    - Handles downloads                                     │
│    - Notifies progress                                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              Telethon Library (Official API)                │
│    - MTProto Protocol                                      │
│    - Encryption                                             │
│    - Session Management                                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Telegram Servers                          │
└─────────────────────────────────────────────────────────────┘

Data Flow

1. You provide credentials
         ↓
2. Tool connects to Telegram (using MTProto)
         ↓
3. Tool authenticates you (same as Telegram app)
         ↓
4. Tool fetches your channel list
         ↓
5. You select channel to download
         ↓
6. Tool iterates through messages
         ↓
7. For each video:
   - Check if already downloaded
   - Download video file
   - Update progress
         ↓
8. Done! Videos saved to your computer

Code Examples

Simple Usage

from telegram_dl import TelegramDownloader, TelegramCredentials
import asyncio

async def main():
    # Your credentials
    credentials = TelegramCredentials(
        api_id=12345,
        api_hash="abc123def456",
        phone="[phone]"
    )
    
    # Download videos
    async with TelegramDownloader(credentials) as dl:
        results = await dl.download_all_videos(-1001234567890)
        
    print(f"Downloaded {len(results)} videos!")

asyncio.run(main())

With Progress Bar

from telegram_dl import TelegramDownloader
from telegram_dl.patterns import ProgressBarObserver

downloader = TelegramDownloader(credentials)
downloader.attach_observer(ProgressBarObserver())

async with downloader as dl:
    await dl.download_all_videos(-1001234567890)

Using Builder Pattern

from telegram_dl import DownloaderBuilder

downloader = (
    DownloaderBuilder()
    .with_credentials(api_id, api_hash, phone)
    .with_output_dir("./my_videos")
    .with_retry_strategy("exponential", max_attempts=5)
    .with_progress_bar()
    .with_logging()
    .build()
)

Design Patterns Used

Pattern	Where Used	Why
Builder	DownloaderBuilder	Flexible configuration
Factory	RetryStrategyFactory	Create retry strategies
Observer	ProgressBarObserver	Notify progress updates
Repository	VideoRepository	Manage video data
Strategy	Retry strategies	Swap algorithms easily

SOLID Principles

Principle	Implementation
Single Responsibility	Each class has one job
Open/Closed	Add features without modifying existing code
Liskov Substitution	Swap implementations easily
Interface Segregation	Small, focused interfaces
Dependency Inversion	Depend on abstractions

Project Structure

telegram-dl/
├── telegram_dl/
│   ├── __init__.py          # Package exports
│   ├── cli.py               # Command-line interface
│   ├── client.py            # Main downloader class
│   ├── exceptions.py        # Custom exceptions
│   ├── models.py            # Pydantic data models
│   └── patterns.py          # Design patterns
├── tests/
│   ├── conftest.py          # Test fixtures
│   └── test_telegram_dl.py  # Unit tests (27 tests)
├── pyproject.toml           # Package configuration
└── README.md                # This file

Building From Source

# Clone the repository
git clone https://github.com/kuldeep27396/telegram-dl
cd telegram-dl

# Install dependencies
pip install -e .

# Run tests
pytest tests/ -v

# Build package
rm -rf dist/
python -m build

# Publish to PyPI
twine upload dist/*

Requirements

• Python 3.10 or higher
• Telegram API credentials (free from my.telegram.org)

Dependencies

Package	Purpose
telethon	Telegram API client
pydantic	Data validation
tenacity	Retry logic
tqdm	Progress bars

CLI Options

# Required
--api-id          Your Telegram API ID
--api-hash        Your Telegram API Hash
--phone           Your phone number ([phone])

# Optional
--channel         Channel ID to download from
--output          Output directory (default: ./telegram_videos)
--session         Session name (default: telegram_dl_session)
--list-channels   Show all your channels
--with-progress   Show progress bars
--log-level       Logging level (DEBUG, INFO, WARNING, ERROR)

Error Handling

The tool handles these errors gracefully:

Error	What Happens
Wrong credentials	Prompts to check API ID/Hash
2FA enabled	Prompts for password
Channel not found	Shows available channels
Network error	Auto-retries with backoff
Download failed	Logs error, continues with next

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run tests: pytest tests/ -v
4. Submit a pull request

License

MIT License - free to use, modify, and distribute.

Links

• PyPI: https://pypi.org/project/telegram-dl/
• GitHub: https://github.com/kuldeep27396/telegram-dl
• Report Issues: https://github.com/kuldeep27396/telegram-dl/issues

---

Made with ❤️ for developers who want to learn from Telegram courses