DJ mp3 sourcer

Download music from links (YouTube, Spotify, etc.) by finding the best available source. Searches across platforms in priority order: Bandcamp, Beatport, Ama...

Security Scan

The skill's behavior mostly matches its description (downloading and normalizing music), but there are mismatches in declared dependencies and implicit assumptions (missing required binaries/tools), and it instructs network searches/downloads that could expose metadata or be used to obtain copyrighted material.

Purpose & Capability

The skill's name/description align with the instructions and the included filename-normalization script — it legitimately needs yt-dlp/spotdl/ffmpeg and search to locate sources. However, the skill metadata declares no required binaries or env vars while the SKILL.md explicitly depends on several command-line tools (yt-dlp, spotdl, ffmpeg, jq, optionally bandcamp-dl). That mismatch is a design/packaging inconsistency that could cause runtime failures or conceal required privileges.

Instruction Scope

SKILL.md instructs the agent to run yt-dlp/spotdl commands, perform web_search queries (site:bandcamp.com, beatport.com, etc.), spawn sub-agents for parallel processing, and write/read local JSON tracklists and directories. Those actions are within the stated purpose (finding and downloading audio), but they do involve network searches and downloads that will transmit track metadata (artist/title/URLs) externally and fetch remote binaries/assets. The workflow also assumes jq is available (used in yt-dlp --dump-json parsing) though it's not declared.

Install Mechanism

No install spec is provided (instruction-only), which reduces on-disk installation risk. The SKILL.md recommends pip/brew installs (yt-dlp, spotdl, ffmpeg, optional bandcamp-dl) but doesn't enforce or declare them in the registry metadata. This is low risk from an install-execution attack surface perspective, but the missing machine-dependency declarations are an inconsistency.

Credentials

The skill requests no environment variables, credentials, or config paths. That is proportionate to its purpose. There is no evidence it tries to access unrelated secrets or system configs.

Persistence & Privilege

always:false and normal invocation model. The skill does not request persistent system-level changes or modification of other skills. It performs file operations limited to user-specified download directories and a provided normalize script.

What to consider before installing

This skill appears to do what it claims (find and download high-quality audio and normalize filenames) and the normalization script is straightforward and non-malicious. Before installing/using it: (1) be aware it runs network searches and downloads — that will transmit artist/title/URL data and retrieve remote content; (2) ensure you have the required tools installed (yt-dlp, spotdl, ffmpeg, jq, and optionally bandcamp-dl) — SKILL.md lists them but the registry metadata does not, so the agent may fail if they're absent; (3) consider legality: downloading copyrighted tracks may violate law or service terms; the author’s legal notice does not protect you; (4) if you are concerned about an agent autonomously downloading files, restrict autonomous invocation or review actions prior to execution. If you want to proceed, ask the skill author/maintainer to update the registry metadata to declare required binaries (including jq) and to provide an explicit install spec so dependency installation is transparent.

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:

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

For paid sources (bandcamp, beatport, amazon), surface the purchase link with price. For free sources, download directly.

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

1. Identify the track — extract artist + title:

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

2. 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"
   

3. Download or link — free sources download; paid sources return purchase URL with price
4. 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

Setting	Default	Notes
Output directory	~/Downloads/	Where files are saved (subfolder per set when used with dj-set-ripper)
Format	mp3 320k	High-bitrate MP3; configurable to flac if needed
Extended mix	always	Prefer extended/original mix over radio edit
Free only	false	When true, skip paid sources (bandcamp, beatport, amazon) — only use spotdl and yt-dlp

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