Metadata-Version: 2.4
Name: spotify-download
Version: 0.1.0
Summary: Download MP3 tracks from Spotify playlists via YouTube
Project-URL: Repository, https://github.com/zesong/spotify-download
Requires-Python: >=3.10
Requires-Dist: mutagen>=1.47.0
Requires-Dist: requests<3.0.0,>=2.32.0
Requires-Dist: yt-dlp>=2024.0.0
Description-Content-Type: text/markdown

# Spotify Download

Download MP3 tracks from Spotify playlists via YouTube.

## Quick Start

```bash
# 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)

```bash
uvx spotify-download "https://open.spotify.com/playlist/..."
```

### Option 2: pip install

```bash
pip install spotify-download
spotify-download "https://open.spotify.com/playlist/..."
```

### Option 3: pipx

```bash
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](https://ffmpeg.org/download.html) or use `choco install ffmpeg`

## Usage

### Basic Usage (Public Playlists)

Public playlists work **without any API credentials**:

```bash
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

```bash
# 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:

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

Or set environment variables:
```bash
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](https://developer.spotify.com/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:
```bash
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

```bash
# 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