# Changelog

## [v3.4.1] - 2025-01-27

### 🐛 Bug Fixes
- **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.

### ✨ Enhancements
- **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

### 🔧 Code Quality
- **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

### 📚 Documentation
- **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

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

---

## [v3.4.0] - 2025-01-XX

### ✨ New Features
- **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

### 🔧 Improvements
- **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

---

## [v3.3.0] - 2025-01-XX

### ✨ New Features
- **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

### 🔧 Improvements
- **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

---

## [v3.2.0] - 2025-01-XX

### ✨ New Features
- **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

### 🔧 Improvements
- **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