tidal-dl/docs/feature_hover_info.md

Hover Info Feature

Quick Preview on Hover

TIDAL Downloader NG includes a revolutionary hover preview system that displays track metadata instantly when you hover over tracks in the results list.

Features

• Instant Display: Track information appears immediately on hover (no clicks required)
• Tabbed Interface:
  • Details Tab: Shows comprehensive track metadata
  • Cover Art Tab: Displays album artwork
• Smart Debouncing: 350ms delay prevents UI flickering when moving the mouse
• Zero Extra API Calls: Uses pre-loaded track data from search results
• Efficient Caching: Previously viewed tracks display instantly

Displayed Information

Basic Information (Instant)

• Title: Track name
• Version: Track version/remix info (if available)
• Artists: Track artists
• Track #: Track number in album
• Album: Album name
• Duration: Track length (mm:ss)
• Codec: Audio quality (LOSSLESS, AAC, etc.)
• Bitrate: Audio bitrate (or N/A for variable bitrate)
• Release Date: Album release date
• Popularity: Track popularity score
• ISRC: International Standard Recording Code

Enhanced Information (Async)

• BPM: Beats per minute ⏳ (loaded asynchronously from API)
  • Shows ⏳ Loading... while fetching (~100-500ms)
  • Displays actual BPM value when available
  • Shows — if not available

Cover Art Display

• Automatic Loading: Album covers are loaded in the background
• Smart Caching: Covers are cached for instant display on re-hover
• Preloading: First 50 tracks in playlists are preloaded for better UX
• Fallback: Default album image shown if cover is unavailable

Technical Details

Architecture

User hovers over track
    ↓
HoverManager detects hover (debounced 350ms)
    ↓
InfoTabWidget receives update signal
    ↓
_populate_track_details() displays basic info instantly
    ↓
_request_track_extras_if_needed() triggers async fetch
    ↓
Worker thread fetches BPM from TIDAL API
    ↓
Qt Signal invokes callback in main thread
    ↓
_update_extras_ui() updates BPM label

Performance Optimizations

1. LRU Cache: 256-entry cache for track extras
2. Cover Cache: 100-entry cache for album covers
3. Thread-Safe: All background operations are thread-safe
4. Event Filtering: Precise hover detection on tree view viewport
5. Graceful Degradation: Handles missing metadata gracefully

User Experience

On First Hover

Title:        Fortuna       ✅ Instant
Artists:      Asco          ✅ Instant
Duration:     03:40         ✅ Instant
Codec:        LOSSLESS      ✅ Instant
BPM:          ⏳ Loading... ⏱️ Loading indicator (~200ms)
              ↓
BPM:          136           ✅ Loaded!

On Subsequent Hover (Same Track)

Title:        Fortuna       ✅ Instant
Artists:      Asco          ✅ Instant
Duration:     03:40         ✅ Instant
BPM:          136           ✅ Instant (from cache)

Limitations

Due to TIDAL API limitations, the following fields are not applicable in this hover view (they are generally not provided by the public API and thus not displayed):

• ❌ Genres
• ❌ Label
• ❌ Producers
• ❌ Composers

See missing_metadata.md for detailed information about API limitations.

Code Components

• InfoTabWidget: Main widget for displaying track information
• HoverManager: Manages hover events on tree view
• CoverManager: Handles cover art loading and caching
• TrackInfoFormatter: Formats track metadata for display
• TrackExtrasCache: LRU cache for async-loaded metadata

Configuration

The hover delay is configurable in the code:

# In hover_manager.py
self.hover_delay = 350  # milliseconds

Lower values = more responsive but may flicker Higher values = more stable but less responsive

Troubleshooting

BPM not displaying?

• Check console for API errors
• Verify track has BPM in TIDAL (not all tracks do)
• Cache may have stale data (restart application)

Cover not loading?

• Check network connection
• Some tracks may not have cover art
• Default image will be shown as fallback

Hover not working?

• Ensure you're hovering over the results tree view
• Check that the application has focus
• Debounce delay may need adjustment