KaraokeVideoDownloader/README.md

🎤 Karaoke Video Downloader

A Python-based Windows CLI tool to download karaoke videos from YouTube channels/playlists using yt-dlp.exe, with advanced tracking, songlist prioritization, and flexible configuration.

✨ Features

• 🎵 Channel & Playlist Downloads: Download all videos from a YouTube channel or playlist
• 📂 Organized Storage: Each channel gets its own folder in downloads/
• 📝 Robust Tracking: Tracks all downloads, statuses, and formats in JSON
• 🏆 Songlist Prioritization: Prioritize or restrict downloads to a custom songlist
• 🔄 Batch Saving & Caching: Efficient, minimizes API calls
• 🏷️ ID3 Tagging: Adds artist/title metadata to MP4 files
• 🧹 Automatic Cleanup: Removes extra yt-dlp files
• 📈 Real-Time Progress: Detailed console and log output

📋 Requirements

• Windows 10/11
• Python 3.7+
• yt-dlp.exe (in downloader/)
• mutagen (for ID3 tagging, optional)

🚀 Quick Start

Download a Channel

python download_karaoke.py https://www.youtube.com/@SingKingKaraoke/videos

Download from a List of Channels

python download_karaoke.py --file channels.txt

Download Only Songlist Songs

python download_karaoke.py --songlist-only

Prioritize Songlist in Download Queue

python download_karaoke.py --songlist-priority

Show Songlist Download Progress

python download_karaoke.py --songlist-status

Limit Number of Downloads

python download_karaoke.py --limit 5

Override Resolution

python download_karaoke.py --resolution 1080p

🧠 Songlist Integration

• Place your prioritized song list in docs/songList.json (see example format below).
• The tool will match and prioritize these songs across all available channel videos.
• Use --songlist-only to download only these songs, or --songlist-priority to prioritize them in the queue.
• Download progress for the songlist is tracked globally in songlist_tracking.json.

Example docs/songList.json

[
  { "artist": "Taylor Swift", "title": "Cruel Summer" },
  { "artist": "Billie Eilish", "title": "Happier Than Ever" }
]

🛠️ Tracking & Caching

• karaoke_tracking.json: Tracks all downloads, statuses, and formats
• songlist_tracking.json: Tracks global songlist download progress
• channel_cache.json: Caches channel video lists for performance

📂 Folder Structure

KaroakeVideoDownloader/
├── download_karaoke.py         # Main script
├── tracking_manager.py         # Tracking logic
├── manage_tracking.py          # Tracking management utility
├── update_resolution.py        # Resolution config utility
├── config.json                 # Main config
├── downloader/yt-dlp.exe       # yt-dlp binary
├── downloads/                  # All video output
│   └── [ChannelName]/          # Per-channel folders
├── logs/                       # Download logs
├── karaoke_tracking.json       # Main tracking DB
├── songlist_tracking.json      # Songlist tracking DB
├── docs/songList.json          # Songlist for prioritization

🚦 CLI Options

• --file <channels.txt>: Download from a list of channels
• --songlist-priority: Prioritize songlist songs in download queue
• --songlist-only: Download only songs from the songlist
• --songlist-status: Show songlist download progress
• --limit <N>: Limit number of downloads
• --resolution <720p|1080p|...>: Override resolution
• --status: Show download/tracking status

📝 Example Usage

python download_karaoke.py https://www.youtube.com/@SingKingKaraoke/videos --songlist-priority --limit 10
python download_karaoke.py --file channels.txt --songlist-only
python download_karaoke.py --songlist-status

🏷️ ID3 Tagging

• Adds artist/title/album/year/genre to MP4 files using mutagen (if installed)

🧹 Cleanup

• Removes .info.json and .meta files after download

🧩 Configuration

• All options are in config.json (format, resolution, metadata, etc.)
• You can edit this file or use CLI flags to override

🐞 Troubleshooting

• Ensure yt-dlp.exe is in the downloader/ folder
• Check logs/ for error details
• Use python check_resolution.py to verify video quality

---

Happy Karaoke! 🎤