YouTube Downloader

A powerful, modern Python application for downloading YouTube videos, playlists, and entire channels with ease.

---

🚀 Features

• 📥 Multi-Source Downloads: Download single videos, entire playlists, or complete channels
• 🎬 Video & Audio: Choose between MP4 (video) or MP3 (audio only with metadata)
• 📁 Smart Organization: Automatically creates folders named after playlist/channel titles
• ⚡ High Quality: Downloads best available quality with automatic format selection
• 🖥️ CLI & GUI: Both command-line interface and graphical user interface available
• 📊 Progress Tracking: Real-time download progress and status updates
• 🔄 Resume Support: Skip already downloaded videos
• 🏷️ Metadata Embedding: Embeds thumbnails and metadata in MP3 files
• 📦 Portable Executables: Build standalone executables for distribution

📂 Project Structure

youtube-playlist-downloader-3.0/
├── src/
│   └── app/
│       ├── __init__.py
│       ├── __main__.py
│       ├── __version__.py
│       ├── cli/                    # Command-line interface
│       │   ├── __init__.py
│       │   ├── command_line.py
│       │   └── interactive.py
│       ├── core/                   # Core utilities
│       │   ├── __init__.py
│       │   ├── constants.py
│       │   └── utils.py
│       ├── downloader/             # Download logic
│       │   ├── __init__.py
│       │   ├── progress.py
│       │   └── youtube_downloader.py
│       ├── gui/                    # Graphical interface
│       │   ├── __init__.py
│       │   ├── main_window.py
│       │   └── workers.py
│       └── web/                    # Web interface
│           ├── __init__.py
│           ├── server.py
│           ├── static/
│           │   └── css/
│           │       └── style.css
│           └── templates/
│               ├── base.html
│               ├── index.html
│               ├── about.html
│               ├── history.html
│               └── error.html
├── scripts/                        # Setup and build scripts
│   ├── setup.sh / setup.bat
│   ├── start.sh / start.bat
│   ├── start-gui.sh / start-gui.bat
│   └── compile.sh / compile.bat
├── docs/                           # Documentation
├── requirements.txt
├── requirements-gui.txt
├── requirements-dev.txt
├── setup.py
└── README.md

🛠️ Installation

Option 1: Quick Setup (Recommended)

Linux/macOS

# Clone the repository
git clone https://github.com/zVictorium/youtube-downloader.git
cd youtube-downloader

# Run setup script
chmod +x scripts/setup.sh
./scripts/setup.sh

Windows

# Clone the repository
git clone https://github.com/zVictorium/youtube-downloader.git
cd youtube-downloader

# Run setup script
scripts\setup.bat

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/zVictorium/youtube-downloader.git
cd youtube-downloader

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate.bat  # Windows

# Install dependencies
pip install -r requirements.txt

# For GUI support (optional)
pip install -r requirements-gui.txt

# Install package
pip install -e .

Prerequisites

• Python 3.8+
• FFmpeg (required for merging video/audio streams)
  • Ubuntu/Debian: sudo apt install ffmpeg
  • macOS: brew install ffmpeg
  • Windows: Download from ffmpeg.org

🎯 Usage

Interactive Mode (Recommended for Beginners)

# Start interactive mode
python -m app

# Or using the installed command
yt-downloader

Command Line Interface

# Download auto-detecting URL type (video/playlist/channel)
yt-downloader download "https://www.youtube.com/watch?v=VIDEO_ID"
yt-downloader download "https://www.youtube.com/playlist?list=PLAYLIST_ID"
yt-downloader download "https://www.youtube.com/@ChannelName"

# Specify format
yt-downloader download -f mp3 "https://youtube.com/playlist?list=PLxxx"
yt-downloader download -f mp4 "https://youtube.com/watch?v=xxx"

# Download specific content type
yt-downloader video "https://youtube.com/watch?v=xxx" -f mp4
yt-downloader playlist "https://youtube.com/playlist?list=xxx" -f mp3
yt-downloader channel "https://youtube.com/@ChannelName" -f mp4

# Show help
yt-downloader --help
yt-downloader download --help

Graphical User Interface

# Start the GUI
python -m app.gui.main_window

# Or use the start script
./scripts/start-gui.sh  # Linux/macOS
scripts\start-gui.bat   # Windows

Web Interface

# Start the web server
yt-downloader web

# With custom port
yt-downloader web --port 8080

# Without auto-opening browser
yt-downloader web --no-browser

# Enable debug mode
yt-downloader web --debug

Then open your browser at http://127.0.0.1:5000

📸 Screenshots

🔧 Building Executables

Create standalone executables that don't require Python installation:

# Linux/macOS
./scripts/compile.sh

# Windows
scripts\compile.bat

Executables will be created in the dist/ folder:

• yt-downloader / yt-downloader.exe - CLI executable
• YouTube Downloader - GUI executable (if PyQt5/PyQt6 installed)

📚 API Usage

You can also use the downloader as a Python library:

from app.downloader import YouTubeDownloader

# Create downloader instance
downloader = YouTubeDownloader(format_type='mp4')

# Download a single video
success, title = downloader.download_single_video(
    "https://youtube.com/watch?v=VIDEO_ID",
    output_dir="my_videos"
)

# Download a playlist
downloader.download_playlist("https://youtube.com/playlist?list=PLAYLIST_ID")

# Download a channel
downloader.download_channel("https://youtube.com/@ChannelName")

# Auto-detect and download
downloader.download("https://youtube.com/...")

⚙️ Configuration

Download Formats

Format	Description
mp4	Best quality video + audio merged into MP4 container
mp3	Audio only with embedded metadata (title, artist, thumbnail)

Output Template

Files are named using the pattern: YY·MM·DD - Title.ext

Example: 25·01·24 - My Video Title.mp4

❗ Known Limitations

• Age-Restricted Videos: Cannot download without authentication
• Private Videos: Not accessible for download
• Geographic Restrictions: Some videos may be unavailable in certain regions
• Rate Limiting: YouTube may temporarily block excessive requests

🐛 Troubleshooting

Common Issues

1. FFmpeg not found

   • Ensure FFmpeg is installed and in your system PATH
   • Run ffmpeg -version to verify installation

2. PyQt5 installation fails

   • Try installing PyQt6 instead: pip install PyQt6
   • Use the CLI version which doesn't require GUI dependencies

3. Download fails with format error

   • Update yt-dlp: pip install --upgrade yt-dlp
   • Some videos may have restricted formats

📄 License

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

🙏 Acknowledgments

• yt-dlp - The powerful download engine
• PyQt5 - GUI framework
• FFmpeg - Media processing

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📞 Support

• 📋 Issues: Report bugs or request features
• 📦 Releases: Download latest version

---

Made with ❤️ for YouTube enthusiasts

GUI

• Unresponsive Behavior:

The GUI may appear unresponsive during long downloads. This is due to heavy processing in the background thread. Please be patient while the process completes; the GUI logs and final success message indicate completion.

Additional Notes

• The project now uses yt_dlp for improved compatibility and performance compared to the legacy pytube library.
• For cross-platform builds, remember that executables are OS specific. Currently, only the Ubuntu executable is provided (built with PyInstaller on Ubuntu).

Resources

• yt_dlp Documentation
• PyQt5 Documentation