spotdl

Download songs from the provided URLs and embed metadata

$ spotdl [open.spotify.com/playlist/playlistId1 open.spotify.com/track/trackId2 ...]

$ spotdl web

$ spotdl save [open.spotify.com/playlist/playlistId1 open.spotify.com/track/trackId2 ...] --save-file [path/to/save_file.spotdl]

spotdl [OPTIONS] [URL_OR_QUERY...]
spotdl search [OPTIONS] QUERY...

--help, -h
    Show the help message and exit.

--version, -v
    Show the program's version number and exit.

--output, -o
    Specify the output directory or a template for downloaded files.

--quality, -q
    Set the audio quality for downloads (e.g., '192k', '320k').

--bitrate
    Set the target audio bitrate (e.g., '320k').

--log-level, -L
    Set the logging level (e.g., 'DEBUG', 'INFO', 'WARNING').

--threads
    Number of threads to use for parallel downloads.

--ffmpeg, --no-ffmpeg
    Specify the path to FFmpeg executable or disable automatic FFmpeg download.

--save-file
    Save the Spotify URLs/queries to a file for later processing.

--load-file
    Load Spotify URLs/queries from a previously saved file.

--lyrics
    Embed lyrics into the downloaded audio file if available.

--overwrite, --no-overwrite
    Force overwriting existing files or prevent it.

--audio, --video
    Choose to download audio only (default) or video.

--search-query
    Use a custom search query when looking up songs on YouTube.

--yt-dlp-args
    Pass additional arguments directly to the yt-dlp backend.

--config
    Path to a custom configuration file.

--exclude-tags
    Exclude specific metadata tags from being embedded.

--client-id, --client-secret, --user-auth
    Spotify API credentials for authenticated access, improving reliability.

--preload
    Preload data and exit without downloading, useful for checking.

--scan-for-songs
    Scan the output directory for songs already downloaded by spotdl and skip them.

spotdl is a powerful command-line interface (CLI) tool designed to download songs, albums, and playlists directly from Spotify. Unlike typical music downloaders, spotdl intelligently searches for the corresponding audio on YouTube, downloads it using yt-dlp (a robust YouTube downloader), and then processes the audio using ffmpeg. This process includes embedding Spotify's comprehensive metadata, such as album art, artist information, and track details, directly into the downloaded audio file. This ensures high-quality audio files with rich, accurate metadata, making them perfect for offline listening and integration into personal music libraries. spotdl automates the complex task of matching Spotify tracks to YouTube sources, handling various Spotify URLs, and organizing downloaded content efficiently. It offers flexibility through various output formats and quality settings, making it an indispensable tool for music enthusiasts aiming to curate a local collection of their Spotify favorites.

Copyright and Legality: Downloading copyrighted material may be illegal in some jurisdictions. Users are solely responsible for ensuring their usage complies with applicable laws and Spotify's terms of service.
Reliance on YouTube: spotdl depends on YouTube for audio sources. If a song is unavailable or removed from YouTube, spotdl might fail to find or download it.
FFmpeg Requirement: spotdl requires ffmpeg for audio processing and metadata embedding. While it often downloads ffmpeg automatically, manual installation may be necessary.
Spotify API Limits: Extensive use without Spotify API authentication (client ID/secret) may lead to rate limits.

spotdl automatically embeds comprehensive metadata from Spotify into the downloaded audio files. This includes track title, artist, album, genre, year, and high-resolution album art, ensuring downloaded files are well-organized and fully functional in music players.

spotdl supports various Spotify URLs as input, including individual tracks, full albums, and entire playlists. It also allows direct search queries, intelligently finding and downloading the closest matching song even without a specific Spotify URL.

For persistent settings, spotdl supports a configuration file (e.g., in ~/.config/spotdl/config.json), allowing users to define default output paths, quality, authentication details, and other preferences without re-typing them for every command.

spotdl originated as a Python script designed to simplify the process of downloading Spotify tracks. Its development has been community-driven, focusing on improving the accuracy of Spotify-to-YouTube matching, enhancing metadata embedding, and adding robust features like playlist/album support, concurrent downloads, and a flexible configuration system. Over time, it has evolved from a basic utility to a comprehensive solution for managing local Spotify music libraries, gaining significant popularity due to its ease of use and rich feature set, leveraging powerful backends like yt-dlp and ffmpeg.

yt-dlp(1), ffmpeg(1), youtube-dl(1)