380 lines
16 KiB
Plaintext
380 lines
16 KiB
Plaintext
# 🎤 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 |