mbrucedogs/KaraokeVideoDownloader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
53b90a3027
KaraokeVideoDownloader/docs/PRD.md

4.1 KiB
Raw Blame History

🎤 Karaoke Video Downloader – PRD (v2.0)

✅ Overview

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.

📋 Goals

  • Download karaoke videos from YouTube channels or playlists.
  • Organize downloads by channel (or playlist) in subfolders.
  • Avoid re-downloading the same videos (robust tracking).
  • Prioritize and track a custom songlist across channels.
  • Allow flexible, user-friendly configuration.

🧑‍💻 Target Users

  • Karaoke DJs, home karaoke users, event hosts, or anyone needing offline karaoke video libraries.
  • Users comfortable with command-line tools.

⚙️ Platform & Stack

  • Platform: Windows
  • Interface: Command-line (CLI)
  • Tech Stack: Python 3.7+, yt-dlp.exe, mutagen (for ID3 tagging)

📥 Input

  • YouTube channel or playlist URLs (e.g. https://www.youtube.com/@SingKingKaraoke/videos)
  • Optional: channels.txt file with multiple channel URLs (one per line)
  • Optional: docs/songList.json for prioritized song downloads

Example Usage

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

📤 Output

  • MP4 files in downloads/<ChannelName>/ subfolders
  • All videos tracked in karaoke_tracking.json
  • Songlist progress tracked in songlist_tracking.json
  • Logs in logs/

🛠️ Features

  • ✅ Channel-based downloads (with per-channel folders)
  • ✅ Robust JSON tracking (downloaded, partial, failed, etc.)
  • ✅ Batch saving and channel video caching for performance
  • ✅ Configurable download resolution and yt-dlp options (config.json)
  • ✅ Songlist integration: prioritize and track custom songlists
  • ✅ Songlist-only mode: download only songs from the songlist
  • ✅ Global songlist tracking to avoid duplicates across channels
  • ✅ ID3 tagging for artist/title in MP4 files (mutagen)
  • ✅ Real-time progress and detailed logging
  • ✅ Automatic cleanup of extra yt-dlp files

📂 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 (Summary)

  • --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

🧠 Logic Highlights

  • Tracking: All downloads, statuses, and formats are tracked in JSON files for reliability and deduplication.
  • Songlist: Loads and normalizes docs/songList.json, matches against available videos, and prioritizes or restricts downloads accordingly.
  • Batch/Caching: Channel video lists are cached to minimize API calls; tracking is batch-saved for performance.
  • ID3 Tagging: Artist/title extracted from video title and embedded in MP4 files.
  • Cleanup: Extra files from yt-dlp (e.g., .info.json) are automatically removed after download.

🚀 Future Enhancements

  • Web UI for easier management
  • More advanced song matching (fuzzy, multi-language)
  • Download scheduling and retry logic
  • More granular status reporting