What's New in v2.5.5

✨ New Features & Optimizations

• Smart Label Filter Optimization: Filtering by label (--filter-label) now intelligently drops mismatching releases before fetching their full metadata. This drastically reduces API calls and saves massive amounts of time on large discographies. (Authored by @TomaszBojanowski)
• Smart Discography Pagination: Fixed an issue where the --smart-discography filter only parsed the first page (50 releases) of an artist's catalog, effectively ignoring the rest of massive discographies. (Authored by @TomaszBojanowski)
• Long Filename Truncation (Linux/macOS): Added intelligent middle-truncation for folder and file names exceeding the strict 255-byte limit on Linux/macOS filesystems (especially with multi-byte characters like Japanese). Prevents the entire download queue from crashing with an OSError. (Authored by @TomaszBojanowski)
• Config File UTF-8 Compatibility: The config.ini file is now strictly read and written in UTF-8 (and utf-8-sig to ignore legacy Windows BOM). This prevents UnicodeDecodeError crashes on systems with non-UTF-8 default locales. (Authored by @TomaszBojanowski)

🐛 Bugfixes

• Segmented Download Fallback (Critical Fix): Restored the missing API branch for "file/url" requests. Tracks blocked by Akamai now correctly fall back to the Web Player segmented download instead of being definitively discarded with a 400 Error. (Authored by @TomaszBojanowski)
• MP3 Tagging Perfection (Fix): Completely overhauled MP3 (ID3v2.3) tagging to match FLAC parity. Fixed missing QOBUZTRACKID/QOBUZALBUMID tags (restoring native sync and lyrics support for MP3s), fixed the missing release year (TYER/TDAT), fixed swapped ℗ and © copyright symbols, and restored proper track/disc number flags support (e.g., --no-track-number-tag). (Authored by @TomaszBojanowski)
• Incomplete Albums Database (Fix): Fixed a critical issue where failed or partially downloaded albums/tracks were being improperly recorded as "Completed" in the local database, which prevented them from being automatically retried on subsequent runs. (Authored by @TomaszBojanowski)
• Delay Logic & Doubled Pauses (Fix): Fixed the --delay flag being silently ignored during sequential downloads. Additionally, removed doubled pauses so tracks and playlists only wait the exactly requested amount of time between downloads. (Authored by @TomaszBojanowski)
• MP3 Fallback Extension (Fix): Fixed a bug where a track successfully downgraded to MP3 via fallback tiers was incorrectly saved with a .flac extension, causing playback and tagging errors. (Authored by @TomaszBojanowski)
• Strict No-Fallback (Fix): The --no-fallback flag is now strictly enforced during track downloads. If the requested quality fails, it immediately skips the track instead of silently downloading lower tiers. (Authored by @TomaszBojanowski)
• Playlist .m3u Order (Fix): Fixed a bug where downloading a playlist directly or via Last.fm would sort the .m3u alphabetically by artist instead of respecting the exact API playback order. (Authored by @TomaszBojanowski)
• Sync-Playlist Database Bypass (Fix): sync-playlist will now properly download tracks missing from the physical folder even if they were previously recorded in the SQLite downloads database. (Authored by @TomaszBojanowski)
• MusicButler Radar & OS Keyring (Fix): Fixed multiple crashes with the radar command on Linux/macOS. It now correctly reads the Qobuz Auth Token from the OS Keyring and resolves ModuleNotFoundError for headless/Docker setups. (Authored by @TomaszBojanowski)
• Pre-Flight Variable Validation (Fix): Added {quality_tag} and {albumartist} (as an alias for {album_artist}) to the allowed variables list, preventing the script from falsely exiting with an "Unknown variable" error before downloading. (Authored by @TomaszBojanowski)
• CLI Flags Overrides (Fix): Fixed the --with-credits and --no-lrc-files CLI flags not properly overriding the default values set in config.ini. (Authored by @TomaszBojanowski)
• Sync-DB Path & Quality (Fix): The --sync-db command now correctly expands the ~ path on Linux/macOS, creates the database table if it doesn't exist, and registers restored entries with the correct default_quality instead of defaulting to tier 27. (Authored by @TomaszBojanowski)
• Unsupported URL Crash (Fix): Automatically catches unsupported URLs (like Qobuz /interpreter/ pages) and prints a clean "Invalid url" message instead of crashing the entire batch queue with a traceback. (Authored by @TomaszBojanowski)
• Smart Discography RegEx (Fix): Fixed a fatal crash in the smart discography engine when processing album titles starting with a parenthesis (. (Authored by @TomaszBojanowski)