DJ mp3 sourcer

通过查找最佳可用来源从链接（YouTube、Spotify 等）下载音乐。 按优先顺序跨平台搜索：Bandcamp、Beatport、Amazon Music、Spotify（通过 spotdl）、 YouTube（通过 yt-dlp）。当用户发送音乐链接并想要下载高质量音频文件时使用， 或者从混合源批量下载曲目时。处理单个曲目或批次列表。 Surfaces 付费平台的购买链接，直接从免费来源下载。 默认输出为 MP3 320k。支持完全跳过付费平台的“仅限免费”模式。

# 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

```bash
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:
   ```bash
   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
```bash
spotdl download "<spotify-url>" --output "{artist} - {title}" --format mp3 --bitrate 320k
```

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

---

## 中文说明

# DJ MP3 Sourcer

面向 DJ 的音乐下载技能。接收任意音乐链接，找到最佳可用来源，优先获取加长混音版（extended mix）和 MP3 320k 输出。

> **⚠️ 法律声明：** 本技能旨在下载你有权访问的音乐 —— 已购买的、免费发布的、知识共享（creative commons）等。请遵守你所在司法辖区的版权法律。作者不对滥用行为负责。

## 依赖项

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

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

## 来源优先级

按以下顺序搜索 —— 命中第一个匹配即停止：

1. **Bandcamp** —— 可直接支持艺术家，常有加长混音版
2. **Beatport** —— DJ 标准平台，带有 BPM/调性元数据、加长混音版
3. **Amazon Music** —— 数字购买选项
4. **Spotify**（通过 `spotdl`）—— 元数据/标签质量好，320k MP3
5. **YouTube**（通过 `yt-dlp`）—— 兜底方案，始终可用

对于付费来源（bandcamp、beatport、amazon），呈现带价格的购买链接。对于免费来源，直接下载。

如果启用了 **free only** 模式，则跳过第 1-3 步，直接进入 spotdl → yt-dlp。

## 核心规则：优先选择加长混音版

**始终优先选择加长混音版而非电台剪辑版（radio edit）。** 来自较低优先级来源的加长混音版优于来自较高优先级来源的电台剪辑版。

示例：YouTube 上的加长混音版 > Spotify 上的电台剪辑版。

搜索时，在查询中追加 "extended mix"。如果只存在电台剪辑版，在输出中注明。

## 工作流

1. **识别曲目** —— 提取艺术家 + 标题：
   ```bash
   yt-dlp --dump-json "<url>" | jq '{title, artist: .artist // .uploader, duration}'
   ```
2. **搜索每个来源**，使用 web_search：
   ```
   "<artist> <title> extended mix site:bandcamp.com"
   "<artist> <title> extended mix site:beatport.com"
   "<artist> <title> site:amazon.com/music"
   ```
3. **下载或提供链接** —— 免费来源下载；付费来源返回带价格的购买 URL
4. **为文件打标签** —— 艺术家、标题、专辑、封面图。如果 beatport 提供了 BPM/调性，一并注明。

## 下载命令

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

### yt-dlp
```bash
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>"
```

## 下载后处理：文件名规范化

yt-dlp 的文件名通常很杂乱（`NA -` 前缀、`(Official Video)` 后缀、厂牌名、错误的艺术家署名）。下载完成后**务必**运行规范化脚本。

**用法：**
```bash
# 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
```

该脚本将目录中的每个 mp3 模糊匹配到曲目列表中的某一条目，并重命名为干净的 `Artist - Title.mp3` 格式。未匹配的文件保持不变。

**曲目列表才是文件名的事实来源**，而非 YouTube 元数据。

## 配置

| 设置 | 默认值 | 说明 |
|---------|---------|-------|
| 输出目录 | `~/Downloads/` | 文件保存位置（与 dj-set-ripper 配合使用时，每个 set 一个子文件夹） |
| 格式 | mp3 320k | 高比特率 MP3；如需可配置为 flac |
| 加长混音版 | always | 优先选择加长/原始混音版而非电台剪辑版 |
| Free only | false | 为 true 时跳过付费来源（bandcamp、beatport、amazon）—— 仅使用 spotdl 和 yt-dlp |

## 批量处理

给定多个链接时，使用子代理（`sessions_spawn`）并行处理。每个曲目完成时即报告结果。

## 边界情况

- **DJ 混音 / 长 set** —— 直接通过 yt-dlp 下载，跳过来源搜索
- **不可用曲目** —— 清楚报告，如找到替代方案则建议
- **区域锁定内容** —— 注明限制，尝试替代来源
- **混音版 vs 原版** —— 如果链接是特定的混音版，搜索该确切混音版，而非原版