tidal-dl/CHANGELOG.md

# v0.31.5 (Unreleased)

## New Features

- **Quick View on Hover** (GUI): Revolutionary hover preview system for track metadata

  - Tabbed interface with Details and Cover Art tabs
  - Instant metadata display on hover (no clicks required)
  - Debounced events (350ms) to prevent UI flickering
  - Zero additional API calls - uses pre-loaded track data
  - Displays: Title, Artists, Album, Codec, Bitrate, Duration, BPM, ISRC, Release Date, Popularity
  - **BPM Loading Indicator**: Shows `⏳ Loading...` while fetching BPM asynchronously
  - Graceful handling of missing metadata

- **Enhanced BPM Support** (GUI):
  - BPM now loaded asynchronously from TIDAL API raw JSON data
  - Visual loading indicator (`⏳ Loading...`) while fetching
  - Smart caching prevents redundant API calls
  - Thread-safe callback system using Qt signals
  - Displays actual BPM value (e.g., "136") when available
  - Shows `—` when BPM is not provided by TIDAL

## Improvements

- **Code Cleanup & Optimization**:

  - **Removed all debug logs** from console output for production-ready experience
  - Application now runs silently with clean console (only "All setup." message)
  - Removed unused code: `_extract_from_raw()` method and redundant helper functions
  - Simplified error handling with silent exceptions for expected errors (widgets deleted, etc.)
  - **Removed 150+ lines of debug/logging code** across multiple files

- **Code Refactoring & Architecture**:

  - Created `helper/metadata_utils.py` module for reusable metadata utilities
  - Created `cache.py` module for LRU cache implementations
  - Created `ui/media_details_helper.py` for media details population
    ét - Created `gui_covers.py` with `CoverManager` class for cover management
  - Removed ~340 lines of duplicated code from `info_tab_widget.py`
  - Extracted helper functions: `safe_str()`, `find_attr()`, `search_in_data()`, `extract_names_from_mixed()`
  - Improved maintainability and testability of metadata extraction logic
  - **gui.py reduced from 2828 to ~2640 lines (-188 lines, -6.6%)**
  - All cover-related logic centralized in CoverManager

- **Performance & Stability**:

  - Thread-safe track extras cache with automatic cleanup
  - **Cover pixmap cache (LRU, 100 entries)** for instant display on re-hover
  - **Background cover preloading** when opening playlists (first 50 tracks)
  - Smart cache checks before launching download threads
  - Skip re-display if cover already shown (0ms overhead)
  - Graceful shutdown handling for background workers
  - Proper cleanup of event filters on application exit
  - Better error handling for widget lifecycle and API failures
  - Protected against RuntimeError when widgets deleted during shutdown
  - **Fixed BPM display issue**: BPM callback now properly invoked in main thread using Qt signals

- **UI/UX Improvements**:
  - BPM field shows loading state instead of blank placeholder
  - Immediate visual feedback when hovering tracks
  - Smooth asynchronous data loading without blocking UI
  - Cache system ensures instant display on re-hover

## Bug Fixes

- **Fixed BPM not displaying**: Corrected callback invocation from worker thread to main thread
- **Fixed Qt threading issues**: Replaced `QMetaObject.invokeMethod` with direct signal-based approach
- **Fixed "widgets deleted during extras apply"**: Changed from QueuedConnection to direct call
- **Fixed race conditions**: Proper thread-safe callback storage and invocation

## Not Displayed (API Limitations)

Certain metadata fields are **not displayed** because they are generally **not provided** by the public TIDAL API and are therefore **not applicable** in this interface:

- ❌ Genres
- ❌ Label
- ❌ Producers
- ❌ Composers

For details, see `docs/missing_metadata.md`.

## Technical Details

- New components: `InfoTabWidget`, `HoverManager`, `TrackInfoFormatter`, `CoverManager`
- Event filtering on tree view viewport for precise hover detection
- Signal-based architecture for decoupled communication
- Qt Signal (`s_invoke_callback`) for thread-safe callback invocation
- Worker thread pattern for async API calls without blocking UI
- Full conformance to AGENTS.md standards (type hints, docstrings, tests)

## Documentation

- Updated `docs/missing_metadata.md` with current API limitations
- Created `docs/feature_hover_info.md` with comprehensive feature documentation
- Added technical architecture diagrams and troubleshooting guides
- Documented BPM loading flow and caching strategy

# v0.4.11

- Fixes regarding empty metadata tags (also fixes #1).
- CLI downloader extended to handle playlists and mixes.
- `Download.track()` now handles logger functions.
- GUI build for macOS and asset upload.

# v0.4.9

- Fixed: Exception on missing file read (config, token) instead of creation.

# v0.4.8

- Fixed: GUI dependencies are treated as extra now (pip).

# v0.4.7

- Fixed: GUI dependencies are treated as extra now (pip).

# v0.4.6

- GUI dependencies are treated as extra now (pip).

# v0.4.5

- Fixed "Mix" download.
- Fixed relative imports.
- Fixed PyPi build.
- Fixed crash on lyrics error.

# v0.4.2

- Added more basic features.

# v0.4.1

- Initial featured running version.