# 🎤 Karaoke Video Downloader - CLI Commands Reference
# Copy and paste these commands into your terminal
# Updated: v3.4.4 (includes macOS support, all videos download mode, manual video collection, channel parsing rules, and all previous 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

## 🎤 MANUAL VIDEO COLLECTION (v3.4.3)

# Download from manual videos collection (data/manual_videos.json)
python download_karaoke.py --manual --limit 5

# Download manual videos with fuzzy matching
python download_karaoke.py --manual --fuzzy-match --fuzzy-threshold 85 --limit 10

# Download manual videos with parallel processing
python download_karaoke.py --parallel --workers 3 --manual --limit 5

# Download manual videos with songlist matching
python download_karaoke.py --manual --songlist-only --limit 10

# Force download from manual videos (bypass existing file checks)
python download_karaoke.py --manual --force --limit 5

# Add a video to manual collection (interactive)
python add_manual_video.py add "Artist - Song Title (Karaoke Version)" "https://www.youtube.com/watch?v=VIDEO_ID"

# List all manual videos
python add_manual_video.py list

# Remove a video from manual collection
python add_manual_video.py remove "Artist - Song Title (Karaoke Version)"

## 🎬 ALL VIDEOS DOWNLOAD MODE (v3.4.4)

# Download ALL videos from a specific channel (not just songlist matches)
python download_karaoke.py --channel-focus SingKingKaraoke --all-videos

# Download ALL videos with parallel processing for speed
python download_karaoke.py --channel-focus SingKingKaraoke --all-videos --parallel --workers 10

# Download ALL videos with limit (download first N videos)
python download_karaoke.py --channel-focus SingKingKaraoke --all-videos --limit 100

# Download ALL videos with parallel processing and limit
python download_karaoke.py --channel-focus SingKingKaraoke --all-videos --parallel --workers 5 --limit 50

# Download ALL videos from ZoomKaraokeOfficial channel
python download_karaoke.py --channel-focus ZoomKaraokeOfficial --all-videos

# Download ALL videos with custom resolution
python download_karaoke.py --channel-focus SingKingKaraoke --all-videos --resolution 1080p

## 📋 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

# 7. Download from manual video collection
python download_karaoke.py --manual --limit 5

# 7b. Fast parallel manual video download
python download_karaoke.py --parallel --workers 3 --manual --limit 5

# 7c. Manual videos with fuzzy matching
python download_karaoke.py --manual --fuzzy-match --fuzzy-threshold 85 --limit 10

## 🍎 macOS SETUP COMMANDS

# Automatic macOS setup (detects OS and installs yt-dlp + FFmpeg)
python3 setup_macos.py

# Test macOS setup and functionality
python3 src/tests/test_macos.py

# Manual macOS setup options
# Install yt-dlp via pip
pip3 install yt-dlp

# Download yt-dlp binary for macOS
mkdir -p downloader && curl -L -o downloader/yt-dlp_macos https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos && chmod +x downloader/yt-dlp_macos

# Install FFmpeg via Homebrew
brew install ffmpeg

## 🔧 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.json (channel configuration with parsing rules, preferred)
# - data/channels.txt (legacy channel list, backward compatibility)
# - data/manual_videos.json (manual video collection)
# - 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.json if available, falls back to 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
# - Supports manual video collection via --manual parameter

# 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
# - macOS users: Run `python3 setup_macos.py` for automatic setup

# 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 