spotify-download

Download MP3s from Spotify playlists by fetching metadata, searching YouTube for tracks, and converting audio using ffmpeg with optional Spotify API credenti...

Security Scan

The skill's instructions match its stated purpose, but the registry metadata omits required tools and installation sources (ffmpeg, yt-dlp, Python, PyPI/GitHub), and it points to external installers—this mismatch and use of third-party installs warrants caution.

Purpose & Capability

The SKILL.md behavior (fetch Spotify metadata, search YouTube, download/convert with yt-dlp and ffmpeg) is coherent with the name/description. However, the registry metadata declares no required binaries or env vars while the instructions clearly require Python 3.10+, ffmpeg, and yt-dlp and reference optional Spotify credentials. The discrepancy between metadata and SKILL.md is noteworthy.

Instruction Scope

Instructions stay within the stated task: fetch playlist metadata (embed or API), search YouTube, download audio, and convert to MP3. They do not direct the agent to read unrelated system files or exfiltrate arbitrary data. They do reference setting SPOTIFY_CLIENT_ID/SECRET as environment variables (optional) which are relevant to the task but were not declared in the registry metadata.

Install Mechanism

There is no install spec in the registry, but SKILL.md instructs users to install a third-party 'spotify-download' package via pip/pipx or clone a GitHub repo (https://github.com/zesong/spotify-download.git). It also references 'uvx' as an invocation method. Installing packages from PyPI or cloning arbitrary GitHub repos executes external code and is higher risk; the skill metadata should have declared these dependencies or an install mechanism to allow review. The lack of an official homepage and unknown owner increases the need for caution.

Credentials

The only credentials mentioned are optional Spotify Client ID/Secret, which are proportional to the stated need for accessing private playlists or improving metadata. However, the registry did not list these env vars as optional fields even though SKILL.md instructs how to set them. No other credentials are requested, which is appropriate. Users should avoid supplying long-lived production credentials unless necessary.

Persistence & Privilege

The skill is not always-enabled and does not request elevated or persistent platform privileges. It does not ask to modify other skills or system-wide configs. Autonomous model invocation is enabled by default but is not, on its own, a red flag here.

What to consider before installing

This skill's runtime instructions align with its purpose, but the registry metadata omits key requirements and it directs you to install third-party packages and a GitHub repo. Before installing or running: 1) Confirm the source: inspect the referenced GitHub repo (https://github.com/zesong/spotify-download.git) and the PyPI package code to ensure no unexpected behavior. 2) Install supporting binaries (ffmpeg, yt-dlp) from trusted package managers (Homebrew, apt, Chocolatey or official project sites). 3) Avoid supplying your primary Spotify credentials unless necessary; use a disposable app/client if possible and revoke it after use. 4) Be aware of legal/terms-of-service issues when downloading copyrighted music—this may be prohibited in your jurisdiction or by service terms. 5) Ask the publisher to update registry metadata to declare required binaries and optional env vars so the skill's footprint is clear. Additional evidence (packaged code, a verified homepage, or a trustworthy publisher) would raise confidence.

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

1. Python 3.10+ - Required
2. 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:

1. Go to https://developer.spotify.com/dashboard
2. Create an app
3. 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 YYY

Output

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:

1. Fetches playlist metadata from Spotify (embed page for public, API for private)
2. Searches YouTube for each track ("{artist} {track name}")
3. Downloads best audio match as MP3 (320kbps)
4. 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)