🎤 Karaoke Playlist Downloader

A Python-based Windows command-line tool that wraps yt-dlp.exe to batch-download karaoke videos from YouTube playlists.

✨ Features

• 🚀 Fast Batch Downloads: Download entire YouTube playlists with a single command
• 📁 Organized Storage: Each playlist gets its own folder with proper naming
• 🔄 Smart Skipping: Avoid re-downloading videos you already have
• 📝 Comprehensive Logging: Detailed logs for each playlist download
• 🎵 Multiple Formats: Download as MP4 video or extract MP3 audio
• 📊 Progress Tracking: Real-time progress updates and error handling

📋 Requirements

• Windows (tested on Windows 10/11)
• Python 3.7+ (included in the project)
• yt-dlp.exe (included in downloader/ folder)

🚀 Quick Start

1. Download a Single Playlist

python download_karaoke.py https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID

2. Download Multiple Playlists

Create a playlists.txt file with your playlist URLs (one per line):

https://www.youtube.com/playlist?list=PLAYLIST1_ID
https://www.youtube.com/playlist?list=PLAYLIST2_ID
https://www.youtube.com/playlist?list=PLAYLIST3_ID

Then run:

python download_karaoke.py --file playlists.txt

📁 Project Structure

KaroakeVideoDownloader/
├── download_karaoke.py         # Main script
├── tracking_manager.py         # Advanced tracking system
├── manage_tracking.py          # Tracking management utility
├── update_resolution.py        # Resolution configuration utility
├── config.json                 # Configuration file
├── yt-dlp.exe                  # Downloader binary (in downloader/)
├── playlists.txt               # Sample playlist list
├── downloads/                  # All video output
│   └── [playlist_name]/        # Folders per playlist
├── logs/
│   └── [playlist_name].log     # Download logs
└── karaoke_tracking.json       # Advanced tracking database

🎯 Usage Examples

Basic Usage

# Download a single playlist (720p MP4)
python download_karaoke.py https://www.youtube.com/playlist?list=PLxxxxxxxx

# Download with specific resolution
python download_karaoke.py --resolution 1080p https://www.youtube.com/playlist?list=PLxxxxxxxx

# Download from file
python download_karaoke.py --file playlists.txt

# Show download status and statistics
python download_karaoke.py --status

# Generate playlist report
python download_karaoke.py --report PLAYLIST_ID

# Clean up orphaned tracking entries
python download_karaoke.py --cleanup

# Show help
python download_karaoke.py --help

Tracking Management

# Show overall statistics
python manage_tracking.py --stats

# List all playlists
python manage_tracking.py --list-playlists

# Show playlist details
python manage_tracking.py --playlist PLAYLIST_ID

# Show failed songs
python manage_tracking.py --failed

# Show partial downloads
python manage_tracking.py --partial

# Clean up orphaned entries
python manage_tracking.py --cleanup

# Export database backup
python manage_tracking.py --export backup.json

Resolution Management

# Show current resolution setting
python update_resolution.py --show

# Update to 1080p resolution
python update_resolution.py --resolution 1080p

# Update to 720p resolution (default)
python update_resolution.py --resolution 720p

Advanced Features

The tool automatically:

• ✅ Creates organized folder structure
• ✅ Skips already downloaded videos
• ✅ Logs all activities
• ✅ Handles errors gracefully
• ✅ Shows real-time progress
• ✅ Extracts metadata and thumbnails
• ✅ Downloads subtitles when available

📊 Output Format

Video Files

• Format: MP4 (720p by default, configurable)
• Resolution: 720p (upgradeable to 1080p, 1440p, 2160p)
• Naming: Original YouTube video title
• Location: downloads/[playlist_name]/

Additional Files

• Metadata: JSON files with video info
• Thumbnails: Video thumbnails
• Subtitles: English SRT files (if available)
• Logs: Detailed download logs

🔧 Configuration

Customizing Download Options

The script uses optimized yt-dlp settings for karaoke videos:

• Format: 720p MP4 by default (configurable via config.json or --resolution)
• Resolution Options: 480p, 720p, 1080p, 1440p, 2160p
• Audio: MP3 extraction as fallback
• Metadata: Full metadata embedding
• Subtitles: English SRT format
• Error Handling: Graceful error recovery

Resolution Configuration

You can easily change the video resolution:

1. Command Line: Use --resolution flag

   python download_karaoke.py --resolution 1080p https://www.youtube.com/playlist?list=XYZ
   

2. Config File: Edit config.json or use the utility

   python update_resolution.py --resolution 1080p
   

3. Supported Resolutions: 480p, 720p, 1080p, 1440p, 2160p

File Locations

• Downloads: downloads/ folder
• Logs: logs/ folder
• Tracking: downloaded_videos.json

🐛 Troubleshooting

Common Issues

1. yt-dlp.exe not found

   • Ensure yt-dlp.exe is in the downloader/ folder
   • Download from yt-dlp releases

2. Permission errors

   • Run as administrator if needed
   • Check folder write permissions

3. Network issues

   • Check internet connection
   • Try again later (YouTube rate limiting)

4. Playlist not found

   • Verify playlist URL is correct
   • Ensure playlist is public

Log Files

Check the log files in logs/ for detailed error information:

# View latest log
type logs\playlist_name.log

🔄 Updating

Update yt-dlp

Download the latest yt-dlp.exe from GitHub releases and replace the file in downloader/.

Update Script

The Python script is self-contained and doesn't require additional dependencies.

📝 License

This project is open source. Feel free to modify and distribute.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

🆘 Support

For issues and questions:

1. Check the troubleshooting section
2. Review log files for errors
3. Ensure all requirements are met
4. Try with a simple playlist first

---

Happy Karaoke! 🎵