GO — Healthy across the board

• Last commit 1d ago
• 12 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 60% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

spotDL is a Python CLI and web application that downloads Spotify playlists and individual songs by finding matching videos on YouTube and extracting audio, then automatically embeds album art, lyrics, and metadata into the downloaded files. It bridges the gap between Spotify's streaming catalog and offline music libraries by automating the search-and-download workflow that would otherwise require manual YouTube hunting. Monolithic Python package under spotdl/ with clear separation: spotdl/console/ handles CLI entry points (entry_point.py, download.py, sync.py, web.py), spotdl/download/ contains core download logic. The project uses Jinja templating (19KB) likely for web UI rendering and documentation generation via mkdocs. Web UI accessible via spotdl/console/web.py.

Music enthusiasts and offline listening advocates who want to preserve Spotify playlists locally without manual YouTube searching; contributors building music download automation tools in Python; users in regions with limited streaming access who need offline backups.

Production-ready and actively maintained. The project is at v4 with 469KB of Python code across well-organized modules, has CI/CD pipelines (tests.yml, python-publish.yml, docker-hub-image-publish.yml), Docker support, and PyPI distribution. GitHub shows active issue templates and contribution guidelines, indicating stable governance.

Moderate risk: depends on external services (Spotify API, YouTube for matching/downloading) which could break with API changes; spotDL itself shows active maintenance but YouTube's ToS could threaten the core download mechanism. Single-point-of-failure on YouTube availability. Check last workflow run dates in .github/workflows/ to assess current maintenance velocity.

Active development on v4 release with web UI support (web.py console module, HTML templates), documented build/publish workflows, and Docker containerization improvements. The presence of docker-compose.yml and Docker Hub CI pipeline suggests recent containerization work. MkDocs documentation actively maintained via .readthedocs.yaml.

git clone https://github.com/spotDL/spotify-downloader.git
cd spotify-downloader
pip install uv
uv sync
uv run spotdl --help

Or for package installation: pip install spotdl. For development, use uv per scripts/build.py convention.

Daily commands: CLI mode: spotdl download <spotify_url> or spotdl sync <playlist_url>. Web mode: spotdl web (launches UI, see WEB_UI.png in docs/images/). Docker: docker run --rm -v $(pwd):/music spotdl download [trackUrl]. FFmpeg required: auto-install via spotdl --download-ffmpeg or system install.

• spotdl/console/entry_point.py: Main CLI entry point that routes all commands (download, sync, web, url conversions) via Click or argparse
• spotdl/console/download.py: Core download command logic that orchestrates Spotify parsing, YouTube matching, and file saving
• spotdl/console/web.py: Web UI server and routing, critical for non-CLI users; see docs/images/WEB_UI.png for expected feature set
• spotdl/init.py: Package initialization and public API exports; check version handling via _version.py
• spotdl/download/: Core download and metadata embedding logic; main directory to understand for video-to-audio pipeline
• pyproject.toml: Project metadata, dependencies, build configuration, and uv sync targets; defines what gets installed
• .github/workflows/tests.yml: Test suite definition; run locally to validate changes before pushing
• Dockerfile: Container image definition; ensures reproducible environment and critical for Docker Hub CI/CD
• mkdocs.yml: Documentation site structure and theme (material); changes here affect ReadTheDocs output

Adding download sources: modify spotdl/download/ modules. CLI commands: add new subcommand in spotdl/console/ (follow pattern of download.py, sync.py). Web UI features: edit spotdl/console/web.py and templates in likely spotdl/web/ or similar (check after cloning). Metadata handling: look in download modules for mutagen/metadata insertion. Documentation: add to docs/ and regenerate via mkdocs in .readthedocs.yaml.

1. FFmpeg dependency: spotDL will fail silently on audio extraction if FFmpeg is missing; users must run spotdl --download-ffmpeg or system-install it first. 2) Spotify API credentials: Not visible in file list but required; check docs/installation.md and docs/usage.md for required env vars or config file format. 3) YouTube matching brittleness: Core feature depends on yt-dlp/youtube-dl which may break with YouTube updates; no fallback video source in codebase suggests single point of failure. 4) Web UI state: web.py likely runs a local server; check if port 8080/5000 is hardcoded and conflicts with other services. 5) Metadata codec issues: mutagen or ffmpeg may fail on certain audio formats; look for error handling in spotdl/download/ modules.

• Fuzzy Audio Matching (Spotify → YouTube) — Core spotDL algorithm that finds the correct YouTube video for a Spotify track given only metadata (artist, title); understanding false positives/negatives is critical for PR reviews
• ID3/Metadata Tagging — spotDL embeds album art, lyrics, and track metadata into downloaded MP3/M4A files; requires understanding ID3v2 or similar formats that mutagen manipulates
• Playlist State Synchronization — spotdl/console/sync.py implements playlist diff-and-reconcile to detect added/removed/modified tracks; critical for incremental updates without re-downloading
• Audio Format Transcoding (via FFmpeg) — spotDL converts YouTube's native format (often webm/vp9) to user-desired output (mp3/m4a) using FFmpeg; understanding codec selection impacts file size and compatibility
• CLI Subcommand Routing — spotdl/console/entry_point.py dispatches to download, sync, web, url handlers; understanding Click/argparse patterns is essential for adding new commands
• Rate Limiting & API Quota Management — Spotify and YouTube both have rate limits; spotDL must batch requests and implement backoff to avoid IP bans or quota exhaustion
• Containerization & Multi-Platform Distribution — Dockerfile, docker-compose.yml, and GitHub Actions docker-hub-image-publish.yml enable users to run spotDL without Python/FFmpeg setup; critical for user experience on non-technical users

• yt-dlp/yt-dlp — spotDL's video source backend; understanding yt-dlp's API and limitations is critical for debugging download failures
• spotipy-dev/spotipy — Likely dependency for Spotify API interaction; check pyproject.toml for this or similar SDK
• ytmusicapi/ytmusicapi — Alternative music source backend some users request; competing approach to YouTube Music instead of YouTube
• MusicBrainz/musicbrainz-server — Metadata enrichment source that spotDL could integrate for more accurate track info than YouTube provides
• nick-cd/youtubedl-material — Web UI paradigm for yt-dlp; architecturally similar web wrapper around a command-line tool

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for audio providers (YouTube, Piped, SoundCloud, Bandcamp)

The repo has audio providers in spotdl/providers/audio/ but no corresponding test files visible in the structure. Given the critical role these providers play in downloading songs, adding unit tests would improve reliability and make refactoring safer. This is especially important since multiple providers exist with different APIs.

• [ ] Create tests/providers/audio/ directory structure
• [ ] Add unit tests for spotdl/providers/audio/youtube.py covering search, metadata extraction, and error handling
• [ ] Add unit tests for spotdl/providers/audio/piped.py and spotdl/providers/audio/ytmusic.py
• [ ] Add mocking fixtures for external API calls to avoid rate limiting during tests
• [ ] Update .github/workflows/tests.yml to ensure audio provider tests run in CI

Add integration tests for lyrics providers with cached responses

The lyrics providers (genius.py, azlyrics.py, musixmatch.py) in spotdl/providers/lyrics/ appear to have no visible test coverage. These interact with external services and are prone to scraping/API changes. Adding integration tests with VCR cassettes (cached HTTP responses) would catch regressions early.

• [ ] Create tests/providers/lyrics/ directory with base test fixtures
• [ ] Add integration tests for spotdl/providers/lyrics/genius.py using responses library to mock API
• [ ] Add integration tests for spotdl/providers/lyrics/azlyrics.py and musixmatch.py with cached HTML responses
• [ ] Create a conftest.py to share fixtures across lyrics tests
• [ ] Document how to regenerate cached responses when providers update

Add API documentation for console commands using mkdocstrings with examples

The docs/usage.md exists but the console modules (spotdl/console/download.py, sync.py, save.py, web.py) lack auto-generated API docs. Given the repo uses mkdocstrings-python, adding proper docstrings and nav generation would help users understand CLI options and developers understand command implementations.

• [ ] Add comprehensive Google-style docstrings to spotdl/console/download.py, sync.py, save.py, url.py functions
• [ ] Create docs/api/console-commands.md with mkdocstrings reference blocks for each command module
• [ ] Update mkdocs.yml nav section to include generated console API docs
• [ ] Add practical examples in docstrings showing usage of each command class/function
• [ ] Run scripts/docs/gen_ref_nav.py and verify auto-generated navigation is correct

• Add integration tests for spotdl/console/sync.py that verify playlist download tracking and resume capability; currently only download.py likely has tests based on test workflow presence
• Create docs/TROUBLESHOOTING.md entries for common FFmpeg installation failures per OS (Windows PowerShell, macOS Homebrew, Linux apt/pacman); see docs/images/POWERSHELL.png suggests Windows pain point
• Add validation in spotdl/console/download.py to warn users when Spotify URL is private/offline playlist before attempting YouTube matching, reducing wasted API calls

• High · Unrestricted Docker Volume Mount — docker-compose.yml - volumes section. The docker-compose.yml mounts the entire current directory (.) as a volume at /music without any restrictions. This could allow container escape or unauthorized access to the host filesystem if the application is compromised. Fix: Restrict volume mounts to specific directories only. Use ./downloads:/music:ro for read-only access where appropriate, or create a dedicated music directory.
• High · Missing Security Headers in Web Interface — spotdl/console/web.py. The codebase includes a web interface (spotdl/console/web.py) but the provided code snippets don't show security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.). This could expose the web UI to XSS and clickjacking attacks. Fix: Implement comprehensive security headers. Add Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and other relevant headers to all HTTP responses.
• High · External API Dependencies Without Certificate Validation Verification — spotdl/providers/ (audio and lyrics providers). The application fetches data from Spotify, YouTube, SoundCloud, and other external APIs. Without visible certificate pinning or strict validation, man-in-the-middle attacks are possible. Fix: Ensure all external API calls use proper SSL/TLS certificate validation. Consider implementing certificate pinning for critical API endpoints. Verify that requests library is configured with proper verification.
• Medium · Potential Path Traversal in File Operations — spotdl/utils/downloader.py, spotdl/download/downloader.py. The application handles file downloads and metadata storage. Without proper path validation, attackers could use malicious playlist/song names to write files outside intended directories. Fix: Implement strict path validation and sanitization. Use os.path.abspath() and verify resolved paths are within the intended directory. Sanitize all user-controlled filenames.
• Medium · Missing Input Validation on URLs — spotdl/console/url.py, spotdl/console/download.py. The application processes Spotify URLs, YouTube URLs, and other user inputs. Insufficient validation could lead to SSRF (Server-Side Request Forgery) attacks. Fix: Implement strict URL validation using a whitelist approach. Validate URL schemes, domains, and formats. Use a URL parsing library and check against expected patterns.
• Medium · Unencrypted Storage of Spotify Credentials — spotdl/utils/config.py, spotdl/types/options.py. The application appears to store Spotify API credentials and user tokens. No evidence of encryption at rest is visible in the configuration. Fix: Store credentials in encrypted format using libraries like cryptography. Implement secure credential storage, never log credentials, and consider using environment variables instead of config files.
• Medium · Alpine Linux with Outdated Package Manager Cache — Dockerfile. The Dockerfile uses apk add --no-cache which is good, but doesn't pin specific package versions. This could introduce vulnerabilities from newer package versions. Fix: Pin specific package versions (e.g., ffmpeg=5.1.2-r0). Add RUN apk update && apk upgrade after package installation. Implement regular security scanning of base image.
• Medium · No User Privilege Separation in Docker — Dockerfile. The Dockerfile doesn't create a non-root user. The application runs as root, increasing impact of any potential compromises. Fix: Create a non-root user and switch to it before running the application. Example: RUN addgroup -g 1000 spotdl && adduser -D -u 1000 -G spotdl spotdl && USER spotdl
• Low · Potential Dependency Vulnerabilities in Documentation — scripts/docs/requirements.txt and pyproject.toml (dev dependencies). mkdocs and related documentation dependencies may contain vulnerabilities. These are development dependencies but could be exploited in CI/CD pipelines. Fix: Regularly update and

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/spotDL/spotify-downloader shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live spotDL/spotify-downloader repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/spotDL/spotify-downloader.

What it runs against: a local clone of spotDL/spotify-downloader — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in spotDL/spotify-downloader | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of spotDL/spotify-downloader. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/spotDL/spotify-downloader.git
#   cd spotify-downloader
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of spotDL/spotify-downloader and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "spotDL/spotify-downloader(\\.git)?\\b" \\
  && ok "origin remote is spotDL/spotify-downloader" \\
  || miss "origin remote is not spotDL/spotify-downloader (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/spotDL/spotify-downloader"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.