# 🎤 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! 🎵**