Root cause: When album downloads completed, the frontend immediately closed
the modal and called /api/playlists/cleanup_batch, which deleted the batch
from memory. The wishlist processing thread (submitted to executor) would
then try to access the batch and fail silently because it was already deleted.
This explains why:
- Wishlist auto-processing worked (different timing/3-second delay)
- Manual "Add to Wishlist" button worked (different code path, before downloads)
- Album modal failed tracks didn't get added (race condition)
The fix prevents batch cleanup until wishlist processing completes:
Backend (web_server.py):
1. Mark wishlist_processing_started=True when submitting processing job
2. Mark wishlist_processing_complete=True when processing finishes
3. Block cleanup endpoint if processing in progress (return 202)
Frontend (script.js):
4. Handle 202 response and retry cleanup after 2-second delay
This eliminates the race condition while maintaining async processing and
ensuring all failed/cancelled tracks are properly added to the wishlist.
Updated startMissingTracksProcess in script.js to recognize discover_album_ IDs as album downloads. This ensures that albums downloaded from the Discover page (e.g., Recent Releases) are correctly organized into "Artist/Album" folders instead of being treated as flat playlists.
Library page was using album data from discography listing while Artists page used track.album from API. With iTunes, these could have different track counts, causing different album_type classifications.
- Updated handleAddToWishlist to use track.album data like Artists page does
- Added album_type copying to owned releases in merge_discography_data
- Added global currentMusicSourceName variable to track active source
- Updated discovery modal to show "Apple Music" when iTunes is active
- Replaced hardcoded "Spotify" in modal titles, headers, and descriptions
- Discovery modals now automatically reflect the correct music source (Spotify/Apple Music)
- Display "Apple Music" instead of "Spotify" in UI when iTunes is active source
- Enhanced connection test messages to indicate Spotify config/auth status
- Fixed similar artists requiring Spotify re-scan when Spotify becomes available
- Fixed hero slider buttons failing for iTunes-only artists
- Updated activity feed items to show correct source name dynamically
- Add similar artists fetching to web UI scan loop
- Add database migration for UNIQUE constraint on similar_artists table - Add source-agnostic /api/discover/album endpoint for iTunes support
- Fix NOT NULL constraint on discovery_recent_albums blocking iTunes albums
- Add fallback to watchlist artists when no similar artists exist
- Add /api/discover/refresh and /api/discover/diagnose endpoints
- Add retry logic with exponential backoff for iTunes API calls
- Ensure cache_discovery_recent_albums runs even when pool population skips
- Fix platform detection to include is_listenbrainz_playlist check when generating fix buttons
- Update openDiscoveryFixModal to check both listenbrainzPlaylistStates and youtubePlaylistStates
- Update searchDiscoveryFix to detect discovery_source and use appropriate search API
- Add /api/itunes/search_tracks endpoint for manual track search when using iTunes source
- Update selectDiscoveryFixTrack state lookup to include ListenBrainz
Fix button now works correctly for all platforms (YouTube, ListenBrainz, Tidal, Beatport) with both Spotify
and iTunes discovery sources.
Implements lazy loading of artist images in search results, artist pages, and similar artist bubbles to improve performance and user experience. Updates the iTunes client to prefer explicit album versions and deduplicate albums accordingly. Adds a new API endpoint to fetch artist images, and updates frontend logic to asynchronously fetch and display images where missing.
Adds iTunes fallback to SpotifyClient for search and metadata when Spotify is not authenticated. Updates album type logic to distinguish EPs, singles, and albums more accurately. Refactors watchlist database methods to support both Spotify and iTunes artist IDs. Improves deduplication and normalization of album names from iTunes. Updates web server and frontend to use new album type logic and support both ID types. Adds artist bubble snapshot example data.
Added backend support for reporting current auto-processing state and cycle in the wishlist stats API. Updated frontend to detect and handle auto-processing start, close modals, and notify users, as well as improved countdown timer updates and conflict handling when starting manual processing.
Enhanced wishlist and watchlist processing to deduplicate tracks during both sanitization and filtering, preventing duplicate downloads and processing. Added explicit resets of next run timer variables to ensure accurate scheduling after each cycle. Updated countdown timer display in the UI to show '0s' when timer reaches zero instead of hiding it.
Introduces new filters for live versions, remixes, acoustic versions, and compilation albums to the watchlist artist configuration. Updates the database schema, backend API, and web UI to support these options, allowing users to customize which content types are included for each artist in their watchlist.
Adds critical fixes to reschedule timers after stuck flag recovery for wishlist and watchlist processes, preventing deadlocks and ensuring continuity. Refines album classification by prioritizing Spotify's album_type over track count heuristics, and ensures album_type is included in API responses. Updates frontend logic to pass and use fresh album/artist context for discover_album modals, improving metadata accuracy and display.
Refines album/single classification in get_wishlist_stats by considering explicit 'album' type for short multi-track releases. Also updates openDownloadModalForRecentAlbum to include total_tracks and album_type in album data for more accurate processing.
Enhanced download status and post-processing logic to properly handle YouTube downloads alongside Soulseek transfers. Improved file organization for simple downloads, moving singles without album info directly to the Transfer root. Added a new generic Spotify search API endpoint. Updated frontend logic to correctly display YouTube download titles and results, and improved filename parsing for YouTube tracks.
Enhances streaming logic to better support YouTube as a download source, including improved filename handling, fuzzy file matching, and search query generation. Updates format checks in the frontend to skip them for YouTube (always MP3). Refactors backend to use a unified download status API for both Soulseek and YouTube, and improves service test messaging based on the active download mode.
Introduces a DownloadOrchestrator class to route downloads between Soulseek and YouTube based on user-configurable modes (Soulseek only, YouTube only, Hybrid with fallback). Updates web server and UI to support new download source settings, including hybrid mode options and YouTube confidence threshold. Refactors YouTube client for thread-safe download management and bot detection bypass. Ensures quality filtering is skipped for YouTube results and improves file matching and post-processing logic for YouTube downloads.
Introduces a help button to the Discover page UI, styled for visibility and accessibility. Adds comprehensive help content explaining all Discover page features, including MusicMap integration, playlist types, seasonal content, and sync/download options.
Introduces a toggle button in the downloads header to show or hide the download manager side panel. The toggle state is persisted in localStorage, and responsive styles are added for better usability on small screens. Updates HTML structure, JavaScript initialization, and CSS for the new toggle functionality and improved mobile experience.
Introduces the $year variable for album, single, and playlist path templates, allowing users to include the release year in file organization. Updates the backend to extract and provide the year, adjusts the web UI to document the new variable, and updates validation logic to recognize $year as valid in templates.
Increases Spotify search result limits for artists and albums. Adds dynamic glow effects to artist, album, and track cards in the UI using image-based colors. Significantly upgrades the CSS for enhanced dropdowns, cards, and lists with a premium, vibrant, and responsive design.
Introduces a backend API endpoint and frontend logic to allow users to stream individual tracks directly from enhanced search results. Updates the UI to include a play button for each track, adjusts the search mode toggle to default to enhanced search, and refines related styles for improved user experience.
Updated the enhanced search button to toggle showing/hiding previous results, with dynamic icon and text changes. Prevented duplicate event listeners by ensuring single initialization. Improved dropdown visibility logic and user feedback when no results are available.
Implements a persistent search bubble system for tracking album and track downloads in enhanced search. Adds backend API endpoints for saving and hydrating search bubble snapshots, frontend state management for search download bubbles, UI for displaying and managing active/completed downloads, and associated styles for search bubble cards. This enables users to resume and manage search downloads across page refreshes.
Updated artist selection actions to log navigation events and use more direct navigation functions. Navigating to library artist details now uses navigateToArtistDetail, and Spotify artist details use selectArtistForDetail after a short delay, improving consistency and user experience.
Implements an enhanced search endpoint in the backend that unifies Spotify and local database results, returning categorized artists, albums, and tracks. Updates the frontend with a new dropdown overlay for live search, debounced input, categorized result rendering, and direct integration with the main results area for album/track selection. Adds new CSS for the dropdown and result cards, and updates the Track dataclass to include image URLs for richer UI display.
Introduces a search mode toggle in the downloads UI, allowing users to switch between basic and enhanced search modes. Adds new HTML structure, JavaScript logic, and CSS styles for the enhanced search interface (currently placeholder functionality). In the backend, implements a retry system for file discovery after download completion to handle race conditions, with cleanup of stale retry attempts to prevent memory leaks.
Introduces 'search_timeout' and 'search_timeout_buffer' options to Soulseek settings in the config, backend, and web UI. The backend now uses these values to control search duration and polling, allowing users to fine-tune how long searches run and how long to wait for late results.
Enhanced the music matching engine to use stricter version handling, rebalance title/artist/duration weights, and raise confidence thresholds to reduce false positives. Updated string normalization to better handle separators and special characters. In the web UI, improved album ID sanitization and added a placeholder for missing album images in the wishlist view.
Ensures the loading overlay is always hidden when opening the wishlist modal, including on error or early return. Updates CSS to allow vertical scrolling in the modal while keeping horizontal overflow hidden.
Introduces an optional 'limit' query parameter to the /api/wishlist/tracks endpoint for improved performance when fetching tracks. Updates the frontend to use this parameter, limiting requests to 50 tracks per category when fetching album and single covers.
Introduces a dynamic mosaic grid background with scrolling album covers for the wishlist category cards in the overview modal. Adds supporting JavaScript functions to extract unique cover images and generate the mosaic HTML, and updates CSS to style and animate the mosaic, including fallbacks and hover effects for improved visual appeal.
Enhanced the logic for extracting artist name and ID to handle both object and string formats from Spotify API and sanitized data. Added fallbacks to ensure artist information is correctly retrieved from multiple possible data structures.
Eliminates hardcoded source prefixes (e.g., [Tidal], [YouTube], [Beatport], [ListenBrainz]) from playlist names in both backend and frontend code. Source detection is now handled via virtualPlaylistId prefixes, improving consistency and simplifying playlist name handling throughout the application.
Adds robust track-to-track matching for album and single downloads, enabling enhanced metadata enrichment using Spotify data. Updates both backend and frontend to support matching Soulseek tracks to Spotify tracks, sending full Spotify track objects for improved organization and post-processing. Simplifies context handling for simple downloads and removes legacy flags, ensuring more accurate and consistent metadata for matched downloads.
Introduces a template-based file organization system for downloads, allowing users to define custom folder and filename structures for albums, singles, and playlists. Updates the backend, config example, web UI, and client-side validation to support template editing, resetting, and error checking. Improves consistency in file placement and metadata handling across all download modes.
Added checks to prevent starting multiple syncs for the same playlist and updated the sync button state immediately for better user feedback. The sync button is now disabled and shows a loading state while syncing is in progress.
Enhanced handling of artist data to support both string and object formats across the database, sync service, and web server. The sync process now preserves full album and artist objects for tracks, enabling wishlist additions with album cover art. The frontend and API were updated to use the full artist objects, and the UI now formats artist names correctly.
Introduces API endpoints and UI elements to view and change the application's log level from the web interface. Log level changes are applied immediately and persisted in the database. Updates backend logic, logging utilities, and frontend scripts to support this feature.
Introduces backend API endpoints to remove individual tracks or all tracks from an album in the wishlist. Updates the frontend to display delete buttons for tracks and albums, with confirmation modals before removal, and styles these new UI elements for clarity and usability.
Introduces backend and frontend functionality to list and select Jellyfin music libraries. Adds API endpoints, updates the client logic, and provides a UI selector for users to choose their preferred Jellyfin music library.
Adds support for sending specific track IDs from the frontend to the backend when starting wishlist missing downloads. This ensures only the tracks currently visible to the user are processed, preventing race conditions if the wishlist changes between modal open and analysis start. Category filtering remains for backward compatibility.
Implements manual track matching (discovery fix modal) for YouTube, Tidal, and Beatport platforms, allowing users to search and select Spotify tracks for unmatched results. Adds backend endpoints and frontend logic for updating matches, improves conversion of discovery results for sync/download, and updates Dockerfile/entrypoint for dynamic PUID/PGID/UMASK support. Includes a new DOCKER_PERMISSIONS.md guide.
Introduces backend scraping and API endpoint for Beatport genre Top 10 and Hype Top 10 tracks, with 1-hour caching. Updates frontend to load and display these lists in the genre browser modal, matching main page structure and click handling for chart discovery.
Introduces a 'Beatport Top 100' button to each genre page, allowing users to fetch and view the top 100 tracks for a selected genre. Includes new event handling logic in script.js and corresponding styles in style.css for the button and its container.
Refactored polling logic for YouTube, Beatport, and Tidal playlists to immediately fetch current status before starting interval polling. Enhanced modal and state restoration to resume both discovery and sync polling as appropriate, ensuring consistent behavior across all supported platforms.
Introduces a new API endpoint to scrape tracks from multiple Beatport release URLs and integrates hero slider click handling on the rebuild page. The frontend now extracts release URLs from the hero slider and fetches track data using the new backend endpoint, improving rebuild page functionality.
Removed genre and year metadata from Beatport slider track cards in script.js. Increased slider height and track info max-width in style.css to improve layout and visual presentation.
Introduces text cleaning for track, artist, and label fields in both Python and JS to ensure proper spacing and formatting. Adds logic to the frontend for handling Beatport Top 10 and Hype Top 10 containers on the rebuild page, including DOM extraction and card creation, following the Browse Charts pattern.
Redirect URIs for Spotify and Tidal OAuth are now configurable via the web UI and settings. Updated backend clients to use the configured redirect URI if provided, improving flexibility for deployments with custom callback URLs.
Introduces web server routes and UI buttons for initiating Spotify and Tidal OAuth authentication flows, with dedicated callback servers for token exchange. Updates Docker ports for OAuth callbacks and refines PKCE handling for Tidal. Improves user experience by allowing authentication directly from the web UI.
Introduces a metadata updater backend in web_server.py, including API endpoints for starting, stopping, and checking status, and a threaded worker for updating artist metadata from Spotify. Updates script.js to add UI controls, polling, and progress display for the metadata updater, with logic to hide the tool when Jellyfin is the active server.
Introduces activity item logging for settings saves, connection tests, auto-detects, authentication flows, searches, batch cancellations, and discovery operations in web_server.py. Updates dashboard connection test API and UI to use a new endpoint and function, ensuring user actions are tracked and surfaced in the activity feed.
Introduces a global activity feed system with API endpoints for recent activities and toasts, and integrates activity tracking for key backend events (downloads, syncs, database updates, etc.). Updates the dashboard frontend to periodically fetch and display activity feed items and show toasts for recent actions. Improves error logging and reduces noise for expected 404s in Soulseek client. Adds related CSS for activity feed separators.
Introduces a new /api/system/stats endpoint in web_server.py to provide system statistics such as uptime, memory usage, download speed, and sync counts. Enhances the dashboard in script.js to periodically fetch and display service connection status and system stats, including response times for Spotify, media server, and Soulseek.
Introduces a watchlist system for tracking artists, including backend API endpoints for managing the watchlist and scanning for new releases. Updates the frontend to allow users to add/remove artists to/from the watchlist from both artist cards and detail pages, view and scan their watchlist via a modal, and see real-time scan progress. Adds related styles for watchlist UI components.
Introduces backend logic to automatically remove tracks from the wishlist if they already exist in the database after downloads or database updates. Adds a new API endpoint and frontend button for manual wishlist cleanup, allowing users to remove already-owned tracks from the wishlist. Enhances reliability and user experience by keeping the wishlist up-to-date.
Sanitizes wishlist track data for consistent backend/frontend handling, enhances wishlist process state reporting for better UI sync, and refactors frontend modal logic to prevent auto-show conflicts and ensure user-driven visibility. Also improves polling and rehydration to keep frontend state in sync with server-side auto-processing.
Introduces a new atomic cancel system (V2) for download tasks, ensuring single-step cancellation with proper worker slot management and backend-driven state. Updates both backend (web_server.py) and frontend (script.js) to support V2 cancel API, persistent cancel state, and improved UI handling for cancelling tasks, eliminating race conditions and dual state management.
Introduces backend API endpoints and frontend logic to persist and restore artist download bubble state across page refreshes. Snapshots are saved and hydrated with live download status, ensuring continuity of user progress and UI state. Includes debounce logic for efficient snapshot saving and automatic cleanup of outdated or invalid snapshots.
Refactored download monitor to handle error and timeout retries directly and consistently, removing legacy retry methods. Improved batch completion logic to ensure batches are only marked complete when all tasks are truly finished, preventing premature completion. Updated client-side polling to never stop automatically, using exponential backoff on failures, and fixed worker counting to exclude post-processing tasks. Enhanced post-processing and verification workflows to avoid double completion callbacks and ensure proper task state transitions.
Introduces a new post-processing workflow in web_server.py that verifies file existence and integrity before marking download tasks as completed. Updates status handling to include a 'post_processing' state and reflects this in the frontend UI, ensuring users see accurate progress and preventing premature completion status for downloads.
Adds server-side validation and healing for download batch worker counts to prevent ghost workers and orphaned tasks, including periodic batch state checks and recovery logic. Enhances thread safety with batch-specific locks and improves error handling in worker slot management. On the frontend, implements exponential backoff for polling failures, validates server responses, and logs worker count discrepancies for better debugging and UI consistency.
Added debounced updates for the artist downloads section to prevent rapid UI refreshes. Enhanced debug logging and error handling for download status changes and bulk completion. Introduced a utility to force refresh all artist download statuses. Updated CSS for better spacing and overflow handling in artist bubble containers and images.
Introduces backend API and frontend integration for downloading missing tracks from artist albums and singles. Adds artist download bubbles, management modal, and related state/UI logic to script.js, with supporting styles in style.css. Also refactors some type hints in web_server.py for consistency.
