248 lines
6.4 KiB
Markdown
248 lines
6.4 KiB
Markdown
# 🎤 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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```txt
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
python download_karaoke.py --resolution 1080p https://www.youtube.com/playlist?list=XYZ
|
|
```
|
|
|
|
2. **Config File**: Edit `config.json` or use the utility
|
|
```bash
|
|
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](https://github.com/yt-dlp/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:
|
|
|
|
```bash
|
|
# View latest log
|
|
type logs\playlist_name.log
|
|
```
|
|
|
|
## 🔄 Updating
|
|
|
|
### Update yt-dlp
|
|
|
|
Download the latest `yt-dlp.exe` from [GitHub releases](https://github.com/yt-dlp/yt-dlp/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! 🎵** |