diff --git a/README.md b/README.md index 788daf3..dba393e 100644 --- a/README.md +++ b/README.md @@ -1,248 +1,127 @@ -# ๐ŸŽค Karaoke Playlist Downloader +# ๐ŸŽค Karaoke Video Downloader -A Python-based Windows command-line tool that wraps `yt-dlp.exe` to batch-download karaoke videos from YouTube playlists. +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 - -- ๐Ÿš€ **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 +- ๐ŸŽต **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** (tested on Windows 10/11) -- **Python 3.7+** (included in the project) -- **yt-dlp.exe** (included in `downloader/` folder) +- **Windows 10/11** +- **Python 3.7+** +- **yt-dlp.exe** (in `downloader/`) +- **mutagen** (for ID3 tagging, optional) ## ๐Ÿš€ Quick Start -### 1. Download a Single Playlist - +### Download a Channel ```bash -python download_karaoke.py https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID +python download_karaoke.py https://www.youtube.com/@SingKingKaraoke/videos ``` -### 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: - +### Download from a List of Channels ```bash -python download_karaoke.py --file playlists.txt +python download_karaoke.py --file channels.txt ``` -## ๐Ÿ“ Project Structure +### Download Only Songlist Songs +```bash +python download_karaoke.py --songlist-only +``` +### Prioritize Songlist in Download Queue +```bash +python download_karaoke.py --songlist-priority +``` + +### Show Songlist Download Progress +```bash +python download_karaoke.py --songlist-status +``` + +### Limit Number of Downloads +```bash +python download_karaoke.py --limit 5 +``` + +### Override Resolution +```bash +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` +```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 # Advanced tracking system +โ”œโ”€โ”€ tracking_manager.py # Tracking logic โ”œโ”€โ”€ 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 +โ”œโ”€โ”€ update_resolution.py # Resolution config utility +โ”œโ”€โ”€ config.json # Main config +โ”œโ”€โ”€ downloader/yt-dlp.exe # yt-dlp binary โ”œโ”€โ”€ downloads/ # All video output -โ”‚ โ””โ”€โ”€ [playlist_name]/ # Folders per playlist -โ”œโ”€โ”€ logs/ -โ”‚ โ””โ”€โ”€ [playlist_name].log # Download logs -โ””โ”€โ”€ karaoke_tracking.json # Advanced tracking database +โ”‚ โ””โ”€โ”€ [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 ``` -## ๐ŸŽฏ Usage Examples - -### Basic Usage +## ๐Ÿšฆ CLI Options +- `--file `: 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 `: Limit number of downloads +- `--resolution <720p|1080p|...>`: Override resolution +- `--status`: Show download/tracking status +## ๐Ÿ“ Example 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 +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 ``` -### Tracking Management +## ๐Ÿท๏ธ ID3 Tagging +- Adds artist/title/album/year/genre to MP4 files using mutagen (if installed) -```bash -# Show overall statistics -python manage_tracking.py --stats +## ๐Ÿงน Cleanup +- Removes `.info.json` and `.meta` files after download -# List all playlists -python manage_tracking.py --list-playlists +## ๐Ÿงฉ Configuration +- All options are in `config.json` (format, resolution, metadata, etc.) +- You can edit this file or use CLI flags to override -# 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 +## ๐Ÿž 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! ๐ŸŽต** \ No newline at end of file +**Happy Karaoke! ๐ŸŽค** \ No newline at end of file diff --git a/docs/PRD.md b/docs/PRD.md index d1fea3d..9bb4a8e 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -1,74 +1,110 @@ -# ๐ŸŽค Karaoke Playlist Downloader โ€“ PRD (v1.0) +# ๐ŸŽค Karaoke Video Downloader โ€“ PRD (v2.0) ## โœ… Overview -A Python-based Windows command-line tool that wraps `yt-dlp.exe` to batch-download karaoke videos from YouTube playlists. +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 -- Quickly download full YouTube playlists containing karaoke videos. -- Organize downloads by playlist. -- Avoid re-downloading the same videos. +## ๐Ÿ“‹ 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 -- Tech-savvy users, developers, or power users familiar with command-line tools. -- Use case: Karaoke DJs, home karaoke setups, offline playlist prep. +- 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 tool (CLI) -- **Tech Stack:** Python + yt-dlp.exe +- **Interface:** Command-line (CLI) +- **Tech Stack:** Python 3.7+, yt-dlp.exe, mutagen (for ID3 tagging) --- ## ๐Ÿ“ฅ Input -- Accepts YouTube playlist URLs via command line. -- Optional: Accept a text file containing multiple playlist URLs (one per line). +- 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 +### Example Usage ```bash -python download_karaoke.py https://www.youtube.com/playlist?list=XYZ -python download_karaoke.py --file playlists.txt +python download_karaoke.py https://www.youtube.com/@SingKingKaraoke/videos +python download_karaoke.py --file channels.txt +python download_karaoke.py --songlist-only ``` --- ## ๐Ÿ“ค Output -- Downloads videos as **MP4** using `yt-dlp.exe`. -- Each playlist gets its own folder: `downloads//` -- Filenames are preserved as per the original YouTube video title. +- MP4 files in `downloads//` subfolders +- All videos tracked in `karaoke_tracking.json` +- Songlist progress tracked in `songlist_tracking.json` +- Logs in `logs/` --- ## ๐Ÿ› ๏ธ Features -- โœ… Skips already downloaded videos (uses video ID log). -- โœ… Logs each download to `logs/.log`. -- โœ… Shows progress and errors in the terminal. -- โœ… Lightweight and fast to execute. +- โœ… 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 (Suggested) +## ๐Ÿ“‚ Folder Structure ``` -karaoke_downloader/ -โ”œโ”€โ”€ download_karaoke.py # main script -โ”œโ”€โ”€ yt-dlp.exe # downloader binary -โ”œโ”€โ”€ playlists.txt # optional playlist list -โ”œโ”€โ”€ downloads/ # all video output -โ”‚ โ””โ”€โ”€ [playlist_name]/ # folders per playlist -โ””โ”€โ”€ logs/ - โ””โ”€โ”€ [playlist_name].log # download log +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 ``` --- -## ๐Ÿš€ Future Enhancements (Optional) -- [ ] `--audio` flag to extract MP3 only. -- [ ] Smart filename cleanup (`[Karaoke]` tag). -- [ ] Graceful skip of unavailable/private videos. -- [ ] Retry logic for failed downloads. +## ๐Ÿšฆ CLI Options (Summary) +- `--file `: 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 `: 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