ytdl - Interactive YouTube Downloader

A feature-rich, interactive CLI for downloading YouTube videos and playlists with ease.

Built on top of yt-dlp with an intuitive menu system powered by questionary.

Features • Installation • Quick Start • Documentation • Contributing

✨ Features

• 🎯 Interactive Menu System - Easy-to-use interface with questionary
• 📋 Playlist Auto-Detection - Automatically detects and organizes playlists
• ⚡ Quick Default Download - One-click download with optimal settings
• 🎨 Advanced Configuration - Fine-tune every aspect of your downloads
• 📁 Smart Naming Templates - Multiple presets + custom template support
• 🎵 Audio Extraction - Download and convert to MP3
• 🖼️ Rich Post-Processing - Thumbnails, subtitles, metadata embedding
• 🚀 SponsorBlock Integration - Automatically remove sponsors and ads
• 🌍 Geo-Bypass & Proxy Support - Download region-restricted content
• 📊 Real-time Progress - Live download progress and speed display

📦 Installation

From PyPI (Recommended)

pip install ytdl-interactive

From Source

# Clone the repository
git clone https://github.com/abd3lraouf/ytdl.git
cd ytdl

# Install in development mode
pip install -e .

Requirements

• Python 3.9 or higher
• FFmpeg (for video/audio processing)

Installing FFmpeg

macOS (Homebrew):

brew install ffmpeg

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

Windows (Chocolatey):

choco install ffmpeg

Or download from ffmpeg.org

🚀 Quick Start

Basic Usage

# Download a single video
ytdl https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Download a playlist
ytdl "https://www.youtube.com/playlist?list=PLxxxxxx"

# Download from a channel
ytdl https://www.youtube.com/@channelname

Command-line Options

ytdl [URL]                    # Start interactive mode with URL
ytdl --version                # Show version information
ytdl --help                   # Display help message

📖 Usage Guide

Main Menu

After providing a URL, you'll see the main menu:

1. Quick Default Download (Recommended)
   └─ Downloads with optimal settings:
      - Best quality video + audio
      - Saved to ./downloads/
      - Auto-organized playlists

2. Advanced Download Settings
   └─ Customize every aspect:
      - Format selection
      - Output paths and naming
      - Post-processing options
      - Network settings

3. Exit

Quick Default Download

The quickest way to download with optimal settings:

• Format: Best quality video + audio (automatically merged)
• Output: ./downloads/
• Single videos: Title.ext
• Playlists: PlaylistName/001 - VideoTitle.ext

Example output structure:

downloads/
├── My Awesome Playlist/
│   ├── 001 - First Video.mp4
│   ├── 002 - Second Video.mp4
│   └── 003 - Third Video.mp4
└── Single Video Title.mp4

Advanced Settings

1. Download Type/Format

• Video (Best Quality) - bestvideo*+bestaudio/best
• Audio Only (MP3) - Extracts and converts to MP3 (192 kbps)
• List Formats - View all available formats and select custom format codes

2. Output Path & Naming

Preset Templates:

Template	Format	Example
Default	%(title)s.%(ext)s	My Video.mp4
Rich Metadata	%(upload_date)s - %(channel)s - %(title)s.%(ext)s	20231215 - Channel Name - My Video.mp4
Minimalist	%(id)s.%(ext)s	dQw4w9WgXcQ.mp4
Custom	Your template	Define your own!

Playlist Auto-Organization: All templates automatically organize playlists into subfolders with zero-padded indices.

Custom Template Variables:

%(title)s          - Video title
%(id)s             - Video ID
%(ext)s            - File extension
%(upload_date)s    - Upload date (YYYYMMDD)
%(channel)s        - Channel name
%(uploader)s       - Uploader name
%(playlist)s       - Playlist name
%(playlist_index)s - Video index in playlist
%(duration)s       - Video duration
%(view_count)s     - View count

3. Post-Processing Options

• Embed Thumbnail - Embed video thumbnail in the file
• Embed Subtitles - Download and embed subtitles (English/Arabic)
• Add Metadata - Add rich metadata to the file
• SponsorBlock - Automatically remove sponsor segments and ads

4. Networking Options

• Proxy Support - Route downloads through a proxy

  http://proxy.example.com:8080
  socks5://proxy.example.com:1080
  

• Geo-Bypass - Bypass geographic restrictions

💡 Examples

Download a single video with defaults

ytdl https://www.youtube.com/watch?v=dQw4w9WgXcQ
# Select: 1. Quick Default Download

Download playlist as MP3s

ytdl "https://www.youtube.com/playlist?list=PLxxxxxx"
# Select: 2. Advanced Settings
# → Select Download Type → Audio Only (MP3)
# → Start Download

Custom output with metadata

ytdl https://www.youtube.com/watch?v=VIDEO_ID
# Select: 2. Advanced Settings
# → Output Path → Select "Rich Metadata"
# → Post-Processing → Check all options
# → Start Download

Download with proxy

ytdl https://www.youtube.com/watch?v=VIDEO_ID
# Select: 2. Advanced Settings
# → Networking → Enter proxy URL
# → Start Download

🏗️ Project Structure

ytdl/
├── ytdl.py              # Main application
├── pyproject.toml       # Package configuration
├── requirements.txt     # Dependencies
├── README.md            # This file
├── LICENSE              # MIT License
└── .gitignore          # Git ignore rules

🤖 Automated Releases

This project uses automated versioning and CI/CD:

• Automatic versioning via setuptools_scm (based on git tags)
• Automated PyPI publishing on new releases
• CI testing on all PRs and pushes
• Release drafts auto-generated from commits

Creating a New Release

1. Go to Actions → Bump Version → Run workflow
2. Select version type (patch/minor/major)
3. Workflow automatically:
   • Creates git tag
   • Generates changelog
   • Creates GitHub release
   • Publishes to PyPI

See CONTRIBUTING.md for detailed release process.

🛠️ Development

Setup Development Environment

# Clone repository
git clone https://github.com/abd3lraouf/ytdl.git
cd ytdl

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Code Structure

# Main components:
DownloadConfig          # Configuration container
progress_hook()         # Real-time download progress
postprocessor_hook()    # Post-processing status
detect_playlist()       # Playlist detection
execute_download()      # Download execution
show_main_menu()        # Interactive menu system

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest

# Code formatting
black ytdl.py

# Type checking
mypy ytdl.py

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Guidelines

• Follow PEP 8 style guidelines
• Add comments for complex logic
• Update README for new features
• Test thoroughly before submitting

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• yt-dlp - The powerful downloader this tool is built upon
• questionary - Beautiful interactive prompts
• All contributors and users of this project

⚠️ Disclaimer

This tool is for personal use only. Please respect copyright laws and YouTube's Terms of Service. Only download content you have permission to download.

🐛 Bug Reports & Feature Requests

Found a bug or have a feature request? Please open an issue on GitHub.

📮 Contact

• GitHub: @abd3lraouf
• Issues: GitHub Issues

🗺️ Roadmap

• Configuration file support (~/.ytdlrc)
• Download queue management
• Resume interrupted downloads
• Batch download from file
• GUI wrapper (tkinter/PyQt)
• Docker support
• Download scheduler

---

Made with ❤️ by developers, for developers