spotify-download 0.1.0

Download MP3 tracks from Spotify playlists via YouTube

Spotify Download

Download MP3 tracks from Spotify playlists via YouTube.

Quick Start

# Install and run with uvx (no installation required!)
uvx spotify-download "https://open.spotify.com/playlist/5TFrk1Wdap4jufziW7SyIh"

That's it! The tool will:

1. Export the Spotify playlist metadata
2. Search each track on YouTube
3. Download the best audio match as MP3 (320kbps)

Installation

Option 1: uvx (Recommended - 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/..."

Requirements

• Python 3.10+
• ffmpeg - required for audio conversion

Install ffmpeg:

• macOS: brew install ffmpeg
• Ubuntu/Debian: sudo apt install ffmpeg
• Windows: Download from ffmpeg.org or use choco install ffmpeg

Usage

Basic Usage (Public Playlists)

Public playlists work without any API credentials:

uvx spotify-download "https://open.spotify.com/playlist/5TFrk1Wdap4jufziW7SyIh"

Options

Flag	Description	Default
playlist_url	Spotify playlist URL	(required)
-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 with more workers
uvx spotify-download "https://open.spotify.com/playlist/..." -w 8

# Save playlist JSON for later use
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

Private Playlists

For private playlists or more accurate metadata, use Spotify API credentials:

uvx spotify-download "https://open.spotify.com/playlist/..." \
  --client-id "your-client-id" \
  --client-secret "your-client-secret"

Or set environment variables:

export SPOTIFY_CLIENT_ID="your-client-id"
export SPOTIFY_CLIENT_SECRET="your-client-secret"
uvx spotify-download "https://open.spotify.com/playlist/..."

To get Spotify credentials:

1. Go to Spotify Developer Dashboard
2. Create an app
3. Copy the Client ID and Client Secret

Output

Files are saved as {Artist} - {Track Name}.mp3:

downloads/
├── playlist.json          # Playlist metadata
└── music/
    ├── Eason Chan - 任我行.mp3
    ├── Mayday - 突然好想你.mp3
    └── ...

How It Works

1. Export - Fetches playlist metadata from Spotify (uses embed page for public playlists, no auth needed)
2. Search - For each track, searches YouTube for "{artist} {track name}"
3. Download - Downloads the best audio match as MP3 (320kbps)
4. Validate - Skips already-downloaded valid MP3s

Troubleshooting

"ffmpeg not found"

Install ffmpeg:

• macOS: brew install ffmpeg
• Linux: sudo apt install ffmpeg

"Could not find embedded playlist metadata"

The Spotify embed page structure may have changed. Try using API credentials:

uvx spotify-download "https://open.spotify.com/playlist/..." \
  --client-id "your-id" \
  --client-secret "your-secret"

Some tracks fail to download

This is usually due to YouTube not finding the right match. The tool will report failed tracks at the end. You can retry by re-running the command - it will skip already-downloaded tracks.

Development

# Clone and setup
git clone https://github.com/zesong/spotify-download.git
cd spotify-download

# Install dependencies
pip install -e .

# Run
spotify-download "https://open.spotify.com/playlist/..."

License

MIT