DJ MP3 Sourcer

DJ-oriented music downloading skill. Takes any music link and finds the best available source, prioritizing extended mixes and MP3 320k output.

⚠️ Legal Notice: This skill is intended for downloading music you have the right to access — purchases, free releases, creative commons, etc. Respect copyright laws in your jurisdiction. The author is not responsible for misuse.

Dependencies

pip install yt-dlp spotdl
brew install ffmpeg  # needed by yt-dlp for audio extraction

# optional
pip install bandcamp-dl  # for free bandcamp downloads

Source Priority

Search in this order — stop at the first match:

• Bandcamp — supports artists directly, often has extended mixes
• Beatport — DJ-standard, has BPM/key metadata, extended mixes
• Amazon Music — digital purchase option
• Spotify (via spotdl) — good metadata/tagging, 320k MP3
• YouTube (via yt-dlp) — fallback, always works

If free only mode is enabled, skip steps 1-3 and go straight to spotdl → yt-dlp.

Core Rule: Prefer Extended Mixes

Always prefer the extended mix over radio edits. An extended mix from a lower-priority source beats a radio edit from a higher-priority one.

Example: extended mix on YouTube > radio edit on Spotify.

When searching, append "extended mix" to queries. If only a radio edit exists, note it in the output.

Workflow

• Identify the track — extract artist + title:

yt-dlp --dump-json "<url>" | jq '{title, artist: .artist // .uploader, duration}'

• Search each source using web_search:

"<artist> <title> extended mix site:bandcamp.com"
   "<artist> <title> extended mix site:beatport.com"
   "<artist> <title> site:amazon.com/music"

• Download or link — free sources download; paid sources return purchase URL with price
• Tag the file — artist, title, album, cover art. Note BPM/key if available from beatport.

Download Commands

spotdl

spotdl download "<spotify-url>" --output "{artist} - {title}" --format mp3 --bitrate 320k

yt-dlp

yt-dlp -x --audio-format mp3 --audio-quality 0 \
  --embed-thumbnail --add-metadata \
  --metadata-from-title "%(artist)s - %(title)s" \
  -o "%(artist)s - %(title)s.%(ext)s" "<url>"

Post-Download: Filename Normalization

yt-dlp filenames are often messy (NA - prefixes, (Official Video) suffixes, label names, wrong artist credits). Always run the normalization script after downloads complete.

Usage:

# 1. Write the tracklist as JSON (from the parsed tracklist in step 2)
cat > /tmp/tracklist.json << 'EOF'
[{"artist": "Karol G", "title": "Ivonny Bonita"}, {"artist": "Doja Cat", "title": "Woman (Never Dull's Disco Rework)"}]
EOF

# 2. Run the normalize script
scripts/normalize-filenames.sh ~/Downloads/set-name /tmp/tracklist.json

The script fuzzy-matches each mp3 in the directory to a tracklist entry and renames to clean Artist - Title.mp3 format. Unmatched files are left untouched.

The tracklist is the source of truth for filenames, not YouTube metadata.

Configuration

Batch Processing

When given multiple links, process in parallel using sub-agents (sessions_spawn). Report results as each track completes.

Edge Cases

• DJ mixes / long sets — download via yt-dlp directly, skip source searching
• Unavailable tracks — report clearly, suggest alternatives if found
• Region-locked content — note restriction, try alternative sources
• Remix vs original — if the link is a specific remix, search for that exact remix, not the original