Changelog

[v3.4.1] - 2025-01-27

Fixed --limit parameter behavior: The --limit parameter now correctly applies to the scanning phase, not just the download execution. When using --limit N, only the first N songs are scanned against channels, significantly reducing processing time for large songlists.
Fixed --limit logging accuracy: The logging messages now accurately reflect the number of songs that will actually be processed when using --limit, rather than showing counts for all songs in the songlist.
Resolved import conflicts: Fixed inconsistencies between different extract_artist_title implementations across modules.

Enhanced fuzzy matching: Improved extract_artist_title function in fuzzy_matcher.py to handle multiple video title formats:
- "Artist - Title" format: "38 Special - Hold On Loosely"
- "Title Karaoke | Artist Karaoke Version" format: "Hold On Loosely Karaoke | 38 Special Karaoke Version"
- "Title Artist KARAOKE" format: "Hold On Loosely 38 Special KARAOKE"
Consolidated parsing logic: Removed duplicate extract_artist_title implementations and centralized all parsing logic in fuzzy_matcher.py
Better matching accuracy: Reduced false negatives for songs with non-standard title formats commonly found on YouTube karaoke channels

Eliminated code duplication: Removed duplicate extract_artist_title functions from id3_utils.py and download_planner.py
Single source of truth: All modules now import extract_artist_title from fuzzy_matcher.py for consistent behavior
Enhanced documentation: Added comprehensive docstrings and examples to the extract_artist_title function
Improved maintainability: Changes to parsing logic now only need to be made in one place

Updated PRD.md: Added section documenting recent bug fixes and improvements
Updated README.md: Enhanced feature descriptions and added recent improvements section
Enhanced code comments: Added explanatory comments for the --limit fix and import changes

Verified functionality: Successfully tested the enhanced fuzzy matching with real-world examples
Confirmed performance improvements: Validated that the --limit parameter now works as expected

Parallel downloads: Enable concurrent downloads with --parallel --workers N for significantly faster batch downloads (3-5x speedup)
Thread-safe operations: All tracking, caching, and progress operations are thread-safe
Automatic retry mechanism: Failed downloads are automatically retried with reduced concurrency

New parallel downloader module: parallel_downloader.py provides thread-safe concurrent download management
Configurable concurrency: Use --parallel to enable parallel downloads with 3 workers by default, or --parallel --workers N for custom worker count (1-10)
Real-time progress tracking: Shows active downloads, completion status, and overall progress
Backward compatibility: Sequential downloads remain the default when --parallel is not used
Integrated with all modes: Works with both songlist-across-channels and latest-per-channel download modes

Centralized file operations: file_utils.py provides single source of truth for filename handling and file validation
Centralized song validation: song_validator.py provides unified logic for checking if songs should be downloaded
Enhanced configuration management: Structured configuration with dataclasses, type safety, and validation

Eliminated code duplication: ~150 lines of duplicate code removed across modules
Enhanced type safety: Comprehensive type hints across all new modules
Better error handling: Consistent patterns via centralized utilities
Improved maintainability: Changes to file operations or song validation only require updates in one place

Download plan pre-scan: Before downloading, the tool scans all channels for songlist matches, builds a download plan, and prints stats
Latest-per-channel plan: Download the latest N videos from each channel, with a per-channel plan and robust resume
Fast mode with early exit: When a limit is set, scans channels and songs in order, downloads immediately when a match is found
Deduplication across channels: Tracks unique song keys to ensure the same song is not downloaded from multiple channels
Fuzzy matching: Uses string similarity algorithms to find approximate matches between songlist entries and video titles
Default channel file: Automatically uses data/channels.txt as the default channel list for songlist modes

Centralized yt-dlp command generation: Standardized command building and execution across all download operations
Enhanced error handling: Structured exception hierarchy with consistent error messages and formatting
Abstracted download pipeline: Reusable download → verify → tag → track process for consistent processing
Optimized scanning algorithm: High-performance channel scanning with O(n×m) complexity and pre-processed lookups
Robust interruption handling: Progress is saved after each download, preventing re-downloads if the process is interrupted