Skill: spotify-download
Use this skill when the user wants to download MP3 files from a Spotify playlist.
When to Use
- User asks to download music from Spotify playlist
- User wants to convert Spotify playlist to MP3
- User provides a Spotify playlist URL and wants audio files
Setup
Requirements
- Python 3.10+ - Required
- ffmpeg - Required for audio conversion
- macOS: brew install ffmpeg - Ubuntu/Debian: sudo apt install ffmpeg - Windows: choco install ffmpeg or download from https://ffmpeg.org
Installation Options
Option 1: uvx (no install needed)
uvx spotify-download "https://open.spotify.com/playlist/..."Option 2: pip install
pip install spotify-download
spotify-download "https://open.spotify.com/playlist/..."Option 3: pipx
pipx install spotify-download
spotify-download "https://open.spotify.com/playlist/..."Option 4: Local development
git clone https://github.com/zesong/spotify-download.git
cd spotify-download
pip install -e .
spotify-download "https://open.spotify.com/playlist/..."Spotify Credentials (Optional)
Public playlists: No credentials needed - the tool uses Spotify's embed page to fetch metadata.
Private playlists or more accurate metadata: Get credentials:
- Go to https://developer.spotify.com/dashboard
- Create an app
- Copy Client ID and Client Secret
Then use either:
spotify-download "https://..." --client-id "XXX" --client-secret "YYY"Or set environment variables:
export SPOTIFY_CLIENT_ID="your-client-id"
export SPOTIFY_CLIENT_SECRET="your-client-secret"
spotify-download "https://..."Usage
Basic Command
uvx spotify-download "https://open.spotify.com/playlist/5TFrk1Wdap4jufziW7SyIh"Common Options
| Flag | Description | Default |
|---|---|---|
-o, --output | Output directory | downloads |
-w, --workers | Concurrent downloads | 4 |
-d, --delay | Search delay (seconds) | 1.0 |
--json-output | Save playlist JSON path | <output>/playlist.json |
--skip-export | Skip export, use existing JSON | - |
Examples
# Download to custom directory
uvx spotify-download "https://open.spotify.com/playlist/..." -o ~/Music/my-playlist
# Faster downloads
uvx spotify-download "https://open.spotify.com/playlist/..." -w 8
# Save playlist JSON for later
uvx spotify-download "https://open.spotify.com/playlist/..." --json-output my-playlist.json
# Re-download from saved JSON (skip export)
uvx spotify-download --skip-export --json-output my-playlist.json -o ~/Music
# With credentials for private playlist
uvx spotify-download "https://open.spotify.com/playlist/..." --client-id XXX --client-secret YYYOutput
Files saved to <output>/music/ as {Artist} - {Track Name}.mp3:
downloads/
├── playlist.json # Playlist metadata
└── music/
├── Eason Chan - 任我行.mp3
├── Mayday - 突然好想你.mp3
└── ...Troubleshooting
"ffmpeg not found"
Install ffmpeg:
- macOS:
brew install ffmpeg - Linux:
sudo apt install ffmpeg
"Could not find embedded playlist metadata"
Spotify's embed page structure may have changed. Use API credentials:
spotify-download "https://..." --client-id "your-id" --client-secret "your-secret"Some tracks fail to download
YouTube search may not find the right match. Re-run the command - it skips already-downloaded tracks.
Implementation
The tool:
- Fetches playlist metadata from Spotify (embed page for public, API for private)
- Searches YouTube for each track ("{artist} {track name}")
- Downloads best audio match as MP3 (320kbps)
- Validates - skips already-downloaded valid MP3s
Notes
- Requires ffmpeg for audio conversion to MP3
- Uses yt-dlp for YouTube search/download
- Public playlists work without any Spotify credentials
- Concurrent downloads are supported (default: 4 workers)