spotDL/spotify-downloader

This system is a Python-based music downloader and library manager that retrieves audio from various sources like YouTube, SoundCloud, and BandCamp, and syncs them with Spotify playlists, albums, and artist discographies. It provides a modular architecture with distinct components for audio and lyrics fetching, metadata management, and library synchronization. The application supports both a rewritten command-line interface and a modern web UI built with FastAPI and Datastar, allowing users to search, download, and manage their music collections locally or via containerized environments.

5 changes.

The project established its foundational structure with Docker support and comprehensive test suites for core utilities. A major architectural shift replaced the multiprocessing download subsystem with an async-based implementation, introducing a programmatic API and a Rich-based user interface.

15 changes.

This period centered on the comprehensive rewrite of SpotDL for version 4, introducing a modular architecture with distinct providers for audio and lyrics, and a new type system for Spotify data. The console interface was restructured into subcommands like sync and meta, while the web UI was rebuilt using FastAPI and Datastar. Supporting changes included migrating to pyproject.toml with uv, adding Deno support, and implementing extensive test coverage for the new components.

This change introduces the foundational configuration files for the project, including a Dockerfile, docker-compose.yml, and .dockerignore, enabling containerized builds and runs. It also adds standard development tooling such as .editorconfig, .gitattributes, .gitignore, and .pylintrc, alongside a new mkdocs.yml for documentation generation and a uv.lock file to manage Python dependencies.

(repo-wide) · high confidence

The web interface has been rebuilt using the Datastar framework for server-driven interactivity and FastAPI for the backend. This change introduces new API endpoints for connecting clients, searching for songs, and initiating downloads via URL, alongside web routes that serve the UI pages (home, search, downloads) and handle client-side actions like loading client state and processing search queries through Server-Sent Events (SSE).

spotdl/web · high confidence

The project now includes \scripts/build.py\ to create a single-file executable using PyInstaller, explicitly bundling the web UI assets, locale data, and specific transitive dependencies like \spotapi\ and \curl\_cffi\. Additionally, \scripts/make\_binzip.sh\ generates a portable zip archive of the source code, and \scripts/termux.sh\ provides an automated setup script for Termux users, including a URL opener integration.

scripts · high confidence

The lyrics fetching system has been restructured into a modular provider pattern. A new base \LyricsProvider\ class handles search result matching and extraction logic, while specific providers have been implemented: AZLyrics (using a dedicated session with specific headers to avoid bot detection), Genius (integrating with the Genius API via an access token), Musixmatch (scraping search results and lyrics pages), and Synced (wrapping the \syncedlyrics\ library to fetch synchronized lyrics from sources like Deezer and NetEase). This change introduces support for synced lyrics and improves robustness against network errors and API changes in the underlying services.

spotdl/providers/lyrics · high confidence

The web UI now includes a complete set of new template components for the client-side interface. Users can search for music via a new search input and list view, manage and download completed tracks from a dedicated downloads page, and configure audio/lyrics providers and output formats through a modal settings dialog. The interface uses static assets for styling (DaisyUI, Tailwind) and icons, and integrates Datastar for client-side state management and navigation.

spotdl/web/components · high confidence

The \spotdl/types\ module has been completely rewritten to introduce a structured type system for handling Spotify data. New \Album\, \Artist\, and \Saved\ classes have been added, allowing users to download entire albums, artist discographies, and their saved tracks directly, in addition to the existing playlist support. The core \Song\ class has been expanded with new metadata fields such as \artist\_id\, \album\_type\, \popularity\, and \list\_position\. Configuration options have been centralized into \TypedDict\ structures (\SpotifyOptions\, \DownloaderOptions\, \WebOptions\) to manage settings for the Spotify client, downloader, and web server. Additionally, a new \Result\ type has been introduced to standardize search results from audio providers.

spotdl/types · high confidence

This update introduces a new \Spotdl\ Python class that allows users to integrate spotdl directly into their own applications via a programmatic API, enabling scripted searches and downloads. The release also includes improved search accuracy, the ability to preserve original audio files, and an option to use the official Spotify Web API. Version has been bumped to 4.5.2.

spotdl · high confidence

The audio provider layer has been reorganized into a modular structure under \spotdl/providers/audio\, introducing a new \base.py\ that standardizes search and download logic using \yt-dlp\ instead of the previous \pytube\ implementation. This change enables support for multiple audio sources, including new providers for BandCamp, Piped (a YouTube frontend), and SoundCloud, while retaining YouTube and YouTube Music. The \YouTubeMusic\ provider now uses the \ytmusicapi\ library with a German locale and implements retry logic with fresh clients, and the \Piped\ provider defaults to the \piped.private.coffee\ instance. Additionally, a \SliderKZ\ provider is included but immediately disabled via a critical log warning due to the service being shut down.

spotdl/providers/audio · high confidence

A new \spotdl/providers\ package has been added to the project, serving as a container for different types of data providers used by the application. This structural change organizes the various data sources into a dedicated module, laying the groundwork for multiple provider implementations.

spotdl/providers · medium confidence

The download subsystem has been rewritten to use native asyncio for non-blocking I/O, replacing the previous multiprocessing approach. This change introduces a new \Downloader\ class that manages audio providers (YouTube, YouTube Music, SoundCloud, BandCamp, Piped) and lyrics providers (Genius, Musixmatch, AzLyrics, Synced) via a configurable settings system. The user interface for download progress has been switched to the Rich library, providing a more granular and visually consistent progress bar and status messages in both terminal and web contexts. The module also includes improved duplicate detection, metadata embedding, and error handling for failed conversions.

spotdl/download · high confidence

The \spotdl/utils\ package has been completely rewritten for v4, introducing a modular architecture that supports new CLI operations including \sync\, \meta\, and \url\ alongside the existing \download\ and \web\ modes. This update adds native support for Deno as a JavaScript runtime for yt-dlp, with automatic download and configuration logic in \deno.py\. The configuration system now follows XDG Base Directory standards on Linux (using \\~/.config/spotdl\) while maintaining backward compatibility with the legacy \\~/.spotdl\ path. A new \Archive\ class in \archive.py\ enables persistent tracking of downloaded items to support the sync operation, and the logging system has been overhauled with a custom \MATCH\ level and Rich-based formatting for improved console output.

spotdl/utils · high confidence

The console interface has been completely rewritten for version 4, replacing the previous entry point with a modular structure in \spotdl/console\. This change introduces distinct subcommands for \download\, \sync\, \save\, \meta\, \url\, and \web\, each implemented in its own module. The new \sync\ operation allows users to maintain local libraries by downloading new tracks and removing those no longer present in source playlists, while the \meta\ operation enables scanning and updating metadata (including lyrics and album art) for existing local files. The \save\ command now supports generating M3U playlists alongside metadata files, and the \web\ module has been updated to support TLS and improved session management. This restructuring centralizes argument parsing and settings initialization in \entry\_point.py\, providing a more robust foundation for future features.

spotdl/console · high confidence

The web interface has been updated to serve external resources as local static files, improving reliability and load times. Additionally, the UI theme engine has been upgraded to DaisyUI version 5, which brings new styling capabilities and component variations to the web interface.

spotdl/web/static · high confidence

Added test coverage for lyrics providers; Added tests for Bandcamp, Piped, YouTube, and YouTube Music audio providers; Added tests for console entry point; Added unit tests for core data types; Initial test suite for spotdl; Initial test suite for spotdl utilities.

The project has replaced its previous dependency management setup with a new pyproject.toml file, adopting the hatchling build system and uv for package resolution. This change defines the core runtime dependencies (including spotipy, yt-dlp, and fastapi) and dev dependencies (such as pytest, mypy, and black) within the TOML manifest, while moving documentation requirements to a dedicated scripts/docs/requirements.txt file. The configuration also restricts the uv environment to CPython and updates the supported Python range to 3.10–3.14.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 41.

• Code Health 80
• Architecture 93
• Maturity 55
• Readiness 33
• Security 61
• Accessibility 33

• 300 commits — 222 feature/other, 78 fixes

• (repo) — 90 commits
• (root) — 64 commits
• spotdl/utils — 38 commits
• spotdl/providers — 31 commits
• spotdl/download — 17 commits
• spotdl/console — 11 commits
• spotdl/web — 8 commits
• tests/utils — 7 commits
• docs/CONTRIBUTING.md — 6 commits
• spotdl/types — 5 commits
• scripts/build.py — 4 commits
• .github/ISSUE_TEMPLATE — 3 commits
• .github/workflows — 3 commits
• docs/troubleshooting.md — 3 commits
• docs/installation.md — 2 commits
• docs/usage.md — 2 commits
• spotdl/_version.py — 2 commits
• tests/test_matching.py — 2 commits
• docs/index.md — 1 commit
• tests/providers — 1 commit

• fix: Added missing album match regression test
• fix: Bugfix for override of download url (fix found by taco-mustard)
• fix: Bugfix: added support for python3.14
• fix: Fix AZLyrics redirect-loop block and surface lyrics provider errors in debug logs (#2697)
• fix: Fix Bandcamp and Piped provider failures
• fix: Fix Bandcamp and Piped provider failures (#2724)
• fix: Fix Docker Build (#2677)
• fix: Fix FreeSpotify client
• fix: Fix KeyError when YTM link has no videoDetails
• fix: Fix KeyError: 'videoDetails' when downloading from YouTube Music links (#2744)
• fix: Fix SoundCloud result duration reported in milliseconds
• fix: Fix SoundCloud result duration reported in milliseconds (#2740)
• fix: Fix Spotify log capture test
• fix: Fix Web Player (Fix found by DavidNery)
• fix: Fix Web Player (Fix found by DavidNery) (#2679)
• fix: Fix YouTube not downloading
• fix: Fix YouTube not downloading (#2564)
• fix: Fix calc_main_artist_match docstring (wrong param names and return type)
• fix: Fix copy-pasted slider.kz docstrings in SoundCloud and BandCamp providers
• fix: Fix event loop handling in search_and_download and its async variant
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

spotDL/spotify-downloader was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.