# 🎤 Karaoke Video Downloader - CLI Commands Reference
# Copy and paste these commands into your terminal
# Updated: v3.4 (includes parallel downloads and all refactoring improvements)

## 📥 BASIC DOWNLOADS

# Download a single channel
python download_karaoke.py https://www.youtube.com/@SingKingKaraoke/videos

# Download from a file containing multiple channel URLs
python download_karaoke.py --file data/channels.txt

# Download with custom resolution (480p, 720p, 1080p, 1440p, 2160p)
python download_karaoke.py --resolution 1080p https://www.youtube.com/@SingKingKaraoke/videos

# Limit number of downloads (fast mode with early exit)
python download_karaoke.py --limit 10 https://www.youtube.com/@SingKingKaraoke/videos

# Enable parallel downloads for faster processing (3-5x speedup)
python download_karaoke.py --parallel --workers 5 --limit 10 https://www.youtube.com/@SingKingKaraoke/videos

## 📋 SONG LIST GENERATION

# Generate song list from MP4 files in a directory (append to existing song list)
python download_karaoke.py --generate-songlist /path/to/mp4/directory

# Generate song list from multiple directories
python download_karaoke.py --generate-songlist /path/to/dir1 /path/to/dir2 /path/to/dir3

# Generate song list and create a new song list file (don't append)
python download_karaoke.py --generate-songlist /path/to/mp4/directory --no-append-songlist

# Generate song list from multiple directories and create new file
python download_karaoke.py --generate-songlist /path/to/dir1 /path/to/dir2 --no-append-songlist

## 🎵 SONGLIST OPERATIONS

# Download only songs from your songlist (uses data/channels.txt by default)
python download_karaoke.py --songlist-only

# Download only songlist songs with limit
python download_karaoke.py --songlist-only --limit 5

# Download songlist songs with fuzzy matching (more flexible matching)
python download_karaoke.py --songlist-only --fuzzy-match --limit 10

# Download songlist songs with custom fuzzy threshold (0-100, default 90)
python download_karaoke.py --songlist-only --fuzzy-match --fuzzy-threshold 85 --limit 10

# Download songlist songs with parallel processing (much faster)
python download_karaoke.py --parallel --workers 5 --songlist-only --limit 10

# Download songlist songs with parallel processing and fuzzy matching
python download_karaoke.py --parallel --workers 5 --songlist-only --fuzzy-match --fuzzy-threshold 85 --limit 10

# Focus on specific playlists by title (download only songs from these playlists)
python download_karaoke.py --songlist-focus "2025 - Apple Top 50" "2024 - Billboard Hot 100"

# Focus on specific playlists with fuzzy matching
python download_karaoke.py --songlist-focus "2025 - Apple Top 50" --fuzzy-match --fuzzy-threshold 85

# Focus on specific playlists with limit
python download_karaoke.py --songlist-focus "2025 - Apple Top 50" --limit 5

# Focus on specific playlists with parallel processing
python download_karaoke.py --parallel --workers 3 --songlist-focus "2025 - Apple Top 50" --limit 5

# Focus on specific playlists from a custom songlist file
python download_karaoke.py --songlist-focus "CCKaraoke" --songlist-file "data/my_custom_songlist.json"

# Focus on specific playlists from a custom file with force mode
python download_karaoke.py --songlist-focus "CCKaraoke" --songlist-file "data/my_custom_songlist.json" --force

# Force download from channels regardless of existing files or server duplicates
python download_karaoke.py --songlist-focus "2025 - Apple Top 50" --force

# Force download with parallel processing
python download_karaoke.py --parallel --workers 5 --songlist-focus "2025 - Apple Top 50" --force --limit 10

# Prioritize songlist songs in download queue (default behavior)
python download_karaoke.py --songlist-priority https://www.youtube.com/@SingKingKaraoke/videos

# Disable songlist prioritization
python download_karaoke.py --no-songlist-priority https://www.youtube.com/@SingKingKaraoke/videos

# Show songlist download status and statistics
python download_karaoke.py --songlist-status

## 📊 UNMATCHED SONGS REPORTS

# Generate report of songs that couldn't be found in any channel (standalone)
python download_karaoke.py --generate-unmatched-report

# Generate report with fuzzy matching enabled (standalone)
python download_karaoke.py --generate-unmatched-report --fuzzy-match --fuzzy-threshold 85

# Generate report using a specific channel file (standalone)
python download_karaoke.py --generate-unmatched-report --file data/my_channels.txt

# Generate report from a custom songlist file (standalone)
python download_karaoke.py --generate-unmatched-report --songlist-file "data/my_custom_songlist.json"

# Generate report with focus on specific playlists from a custom file (standalone)
python download_karaoke.py --songlist-focus "CCKaraoke" --songlist-file "data/my_custom_songlist.json" --generate-unmatched-report

# Download songs AND generate unmatched report (additive feature)
python download_karaoke.py --songlist-only --limit 10 --generate-unmatched-report

# Download with fuzzy matching AND generate unmatched report
python download_karaoke.py --songlist-only --fuzzy-match --fuzzy-threshold 85 --limit 10 --generate-unmatched-report

# Download from specific playlists AND generate unmatched report
python download_karaoke.py --songlist-focus "CCKaraoke" --limit 10 --generate-unmatched-report

# Generate report with custom fuzzy threshold
python download_karaoke.py --generate-unmatched-report --fuzzy-match --fuzzy-threshold 80

## ⚡ PARALLEL DOWNLOADS (v3.4)

# Basic parallel downloads (3-5x faster than sequential)
python download_karaoke.py --parallel --workers 5 --songlist-only --limit 10

# Parallel downloads with different worker counts
python download_karaoke.py --parallel --workers 3 --songlist-only --limit 10  # Conservative
python download_karaoke.py --parallel --workers 5 --songlist-only --limit 10  # Balanced
python download_karaoke.py --parallel --workers 8 --songlist-only --limit 10  # Aggressive

# Parallel downloads for latest-per-channel mode
python download_karaoke.py --parallel --workers 3 --latest-per-channel --limit 5

# Parallel downloads with fuzzy matching
python download_karaoke.py --parallel --workers 5 --songlist-only --fuzzy-match --fuzzy-threshold 85 --limit 10

# Parallel downloads with custom resolution
python download_karaoke.py --parallel --workers 5 --resolution 1080p --songlist-only --limit 10

## 🗂️ LATEST-PER-CHANNEL DOWNLOADS

# Download latest 5 videos from each channel
python download_karaoke.py --latest-per-channel --limit 5

# Download latest videos with fuzzy matching
python download_karaoke.py --latest-per-channel --limit 5 --fuzzy-match --fuzzy-threshold 85

# Download latest videos with parallel processing (much faster)
python download_karaoke.py --parallel --workers 3 --latest-per-channel --limit 5

# Download latest videos with parallel processing and fuzzy matching
python download_karaoke.py --parallel --workers 3 --latest-per-channel --limit 5 --fuzzy-match --fuzzy-threshold 85

# Download latest videos from specific channels file
python download_karaoke.py --latest-per-channel --limit 5 --file data/channels.txt

## 🔄 CACHE & TRACKING MANAGEMENT

# Show download status and statistics
python download_karaoke.py --status

# Show channel cache information
python download_karaoke.py --cache-info

# Clear cache for a specific channel
python download_karaoke.py --clear-cache SingKingKaraoke

# Clear cache for all channels
python download_karaoke.py --clear-cache all

# Set cache duration (in hours)
python download_karaoke.py --cache-duration 48

# Force refresh channel cache (ignore cached data)
python download_karaoke.py --refresh https://www.youtube.com/@SingKingKaraoke/videos

# Force refresh download plan cache (re-scan all channels for matches)
python download_karaoke.py --force-download-plan --songlist-only

# Clear server duplicates tracking (allows re-checking songs against server)
python download_karaoke.py --clear-server-duplicates

## 🧹 RESET & CLEANUP OPERATIONS

# Reset all tracking and files for a specific channel
python download_karaoke.py --reset-channel SingKingKaraoke

# Reset channel and also reset songlist songs for this channel
python download_karaoke.py --reset-channel SingKingKaraoke --reset-songlist

# Reset all songlist tracking and delete all songlist-downloaded files (GLOBAL)
python download_karaoke.py --reset-songlist-all

# Clean up orphaned tracking entries
python download_karaoke.py --cleanup

## 📊 REPORTS & SYNC

# Generate detailed report for a specific playlist
python download_karaoke.py --report PLAYLIST_ID

# Only sync playlist without downloading (update tracking)
python download_karaoke.py --sync https://www.youtube.com/@SingKingKaraoke/videos

# Show version information
python download_karaoke.py --version

## 🎯 ADVANCED COMBINATIONS

# Fast songlist download with fuzzy matching and high quality
python download_karaoke.py --songlist-only --limit 20 --fuzzy-match --fuzzy-threshold 85 --resolution 1080p

# Latest videos per channel with fuzzy matching
python download_karaoke.py --latest-per-channel --limit 3 --fuzzy-match --fuzzy-threshold 90 --file data/channels.txt

# Force refresh everything and download songlist
python download_karaoke.py --songlist-only --force-download-plan --refresh --limit 10

# High-quality download with custom cache duration
python download_karaoke.py --resolution 1080p --cache-duration 72 --limit 5 https://www.youtube.com/@SingKingKaraoke/videos

## 📋 COMMON WORKFLOWS

# 1. Quick songlist download (most common)
python download_karaoke.py --songlist-only --limit 10

# 1b. Fast parallel songlist download (3-5x faster)
python download_karaoke.py --parallel --workers 5 --songlist-only --limit 10

# 1b. Focus on specific playlists (fast targeted download)
python download_karaoke.py --songlist-focus "2025 - Apple Top 50" --limit 5

# 1c. Force download from specific playlists (bypass all existing file checks)
python download_karaoke.py --songlist-focus "2025 - Apple Top 50" --force --limit 5

# 2. Latest videos from all channels
python download_karaoke.py --latest-per-channel --limit 5

# 2b. Fast parallel latest videos download
python download_karaoke.py --parallel --workers 3 --latest-per-channel --limit 5

# 3. High-quality single channel download
python download_karaoke.py --resolution 1080p --limit 20 https://www.youtube.com/@SingKingKaraoke/videos

# 4. Fuzzy matching for better song discovery
python download_karaoke.py --songlist-only --fuzzy-match --fuzzy-threshold 80 --limit 15

# 4c. Fast parallel fuzzy matching
python download_karaoke.py --parallel --workers 5 --songlist-only --fuzzy-match --fuzzy-threshold 80 --limit 15

# 4b. Focused fuzzy matching (target specific playlists with flexible matching)
python download_karaoke.py --songlist-focus "2025 - Apple Top 50" --fuzzy-match --fuzzy-threshold 80 --limit 10

# 4c. Force download with fuzzy matching (bypass all existing file checks)
python download_karaoke.py --songlist-focus "2025 - Apple Top 50" --force --fuzzy-match --fuzzy-threshold 80 --limit 10

# 5. Reset and start fresh
python download_karaoke.py --reset-channel SingKingKaraoke --reset-songlist

# 6. Check status and clear cache if needed
python download_karaoke.py --status
python download_karaoke.py --clear-cache all

## 🔧 TROUBLESHOOTING COMMANDS

# Check if everything is working
python download_karaoke.py --version

# Force refresh everything
python download_karaoke.py --force-download-plan --refresh --clear-cache all

# Reset everything and start fresh
python download_karaoke.py --reset-songlist-all
python download_karaoke.py --clear-server-duplicates

## 📝 NOTES

# Default files used:
# - data/channels.txt (default channel list for songlist modes)
# - data/songList.json (your prioritized song list)
# - data/config.json (download settings)

# Resolution options: 480p, 720p (default), 1080p, 1440p, 2160p

# Fuzzy threshold: 0-100 (higher = more strict matching, default 90)

# The system automatically:
# - Uses data/channels.txt if no --file specified in songlist modes
# - Caches channel data for 24 hours (configurable)
# - Tracks all downloads in JSON files
# - Avoids re-downloading existing files
# - Checks for server duplicates

# For best performance:
# - Use --parallel --workers 5 for 3-5x faster downloads
# - Use --limit for faster downloads
# - Use --fuzzy-match for better song discovery
# - Use --refresh sparingly (forces re-scan)
# - Clear cache if you encounter issues

# Parallel download tips:
# - Start with --workers 3 for conservative approach
# - Use --workers 5 for balanced performance
# - Use --workers 8-10 only on fast connections
# - Monitor system resources during parallel downloads
# - Reduce workers if you experience connection issues