🎵 Media Downloader

A powerful web-based media downloader for YouTube, YouTube Music, and X.com Spaces

---

✨ Features

• 🎯 Multi-Platform Support: Download from YouTube, YouTube Music, and X.com Spaces
• 🎵 Audio & Video: Support for MP3, MP4, and other formats
• 📁 Smart Organization: Automatic folder creation with metadata-based naming
• 🎨 Beautiful UI: Modern, responsive web interface with real-time progress
• 📋 Playlist Support: Download entire playlists with customizable limits
• 🏷️ Metadata Tagging: Automatic MP3 metadata and cover art embedding
• 📊 Progress Tracking: Real-time download progress with detailed status
• 📦 Batch Downloads: Download multiple files with ZIP export
• 🔄 Resume Support: Continue interrupted playlist downloads
• 📱 Mobile Friendly: Responsive design works on all devices

🚀 Quick Start

Prerequisites

# Python 3.7+ required
python --version

# Install required packages
pip install flask yt-dlp mutagen requests

Installation

1. Clone the repository

   git clone https://github.com/[username]/media-downloader.git
   cd media-downloader

2. Run the application

   python web_downloader.py

3. Open your browser

   http://localhost:5000
   

🎮 Usage

Basic Download

1. Enter a YouTube, YouTube Music, or X.com Spaces URL
2. Choose your preferred format (Audio/Video)
3. Select download directory
4. Click "Start Download" and watch the magic happen! ✨

Advanced Features

• Playlist Downloads: Check "Download Playlist" for entire playlists
• Format Selection: Choose between audio (MP3) or video (MP4)
• Custom Limits: Set playlist item limits to control download size
• Batch Export: Download entire folders as ZIP files

🛠️ Technical Stack

Component	Technology	Purpose
Backend	Flask	Web framework and API
Download Engine	yt-dlp	Media extraction and downloading
Audio Processing	mutagen	MP3 metadata and cover art
Frontend	HTML/CSS/JS	Modern responsive UI
File Management	Python os/shutil	File operations and organization

📁 Project Structure

media-downloader/
├── web_downloader.py      # Main Flask application
├── templates/
│   └── index.html         # Web interface
├── downloads/             # Downloaded content
│   ├── Music/            # Audio files
│   └── Videos/           # Video files
└── README.md             # This file

🎯 Key Features Explained

Smart File Organization

• Automatic Naming: Uses uploader and title for folder names
• Metadata Extraction: Pulls title, artist, album info from sources
• Sanitized Filenames: Removes invalid characters automatically

Real-time Progress

• Live Updates: See download progress in real-time
• Status Tracking: Monitor current download status
• Error Handling: Graceful error recovery and reporting

Advanced Download Options

• Format Selection: Choose audio quality and video resolution
• Playlist Management: Download entire playlists with progress tracking
• Resume Capability: Continue interrupted downloads

🔧 Configuration

Environment Variables

# Optional: Set default download directory
export MEDIA_DOWNLOADER_PATH="/path/to/downloads"

# Optional: Set Flask debug mode
export FLASK_DEBUG=1

Customization

• Modify web_downloader.py to add new platforms
• Update templates/index.html for UI changes
• Add new format options in the download function

📊 Performance

• Concurrent Downloads: Threaded download processing
• Memory Efficient: Streams large files without loading into memory
• Fast Metadata: Quick playlist and video info extraction
• Optimized UI: Responsive design with minimal resource usage

🤝 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

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

# Format code
black web_downloader.py

📝 License

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

🙏 Acknowledgments

• yt-dlp - The amazing download engine
• Flask - The web framework
• mutagen - Audio metadata handling

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the open source community

---

⭐ Star this repository if you found it helpful!