DJ Set Ripper

从 DJ 混音集（DJ set）中提取曲目列表，并单独下载每一首曲目。

⚠️ 法律声明：本功能仅用于下载您拥有合法访问权限的音乐内容——例如已购商品、免费发行作品、遵循知识共享协议（Creative Commons）的作品等。请严格遵守您所在司法管辖区的版权法律法规。作者不对任何滥用行为承担责任。

依赖项

与 dj-mp3-sourcer 相同（即需安装 yt-dlp、ffmpeg/ffprobe、spotdl）。无额外依赖。

工作流程

1. 提取网页内容

获取混音集 URL 并提取原始文本（包括简介、元数据、评论等）：

YouTube：

yt-dlp --dump-json "" | jq -r '.description'

SoundCloud / Mixcloud：
使用 web_fetch 以 Markdown 模式抓取页面内容。

1001Tracklists：
使用 web_fetch —— 此来源结构化程度最高，若可用请优先选用。

2. 解析曲目列表（由大语言模型驱动）

将原始网页内容传入模型，并使用如下提示模板：

从该 DJ 混音集描述中提取全部曲目。返回一个 JSON 数组，每个元素为对象：
[{"number": 1, "timestamp": "0:00", "artist": "Artist Name", "title": "Track Title (Mix Name)"}]

规则：
- 在 title 字段中保留 remix/mix 名称（例如 "Original Mix"、"Extended Mix"、"Remix"）
- 若某曲目标注为 "ID - ID" 或 "ID"，则 artist 和 title 均设为 "ID"
- 若仅有时间戳而无曲目信息，则跳过该条目
- 标准化艺人名称（如修复全大写格式等）
- 若无时间戳，则 timestamp 设为 null
- 曲目编号从 1 开始顺序递增

Raw content:
"""
{description_text}
"""

若解析结果为空（即未提取到任何曲目），请告知用户无法提取曲目列表，并建议：

• 手动查阅 1001Tracklists
• 直接粘贴曲目列表文本

3. 下载每首曲目

对每个已解析的曲目（跳过 artist 与 title 均为 "ID" 的条目）执行以下操作：

1. 复用 dj-mp3-sourcer 工作流：按优先级顺序搜索音源，优先选择 Extended Mix；若可下载则执行下载，否则提供购买链接
2. 使用 sessions_spawn 并行下载（每次批量处理 3–5 首，避免触发限速）
3. 保存路径为：~/Downloads/{set-name}/

其中 {set-name} 由混音集标题生成（经文件系统安全清洗）。

4. （可选）下载完整混音集

询问用户是否还需下载整套混音集。若用户确认：

yt-dlp -x --audio-format mp3 --audio-quality 0 
  --embed-thumbnail --add-metadata 
  -o "~/Downloads/{set-name}/{set-name} [Full Mix].%(ext)s" ""

5. 标准化文件名

在所有下载任务完成之后（注意：不是每批下载后单独执行，而是等待所有子代理全部结束），统一运行一次标准化脚本：

# 1. 将已解析的曲目列表写入 JSON 文件
cat > /tmp/tracklist.json << 'EOF'
[{"artist": "Artist", "title": "Title"}, ...]
EOF

# 2. 执行标准化
scripts/normalize-filenames.sh ~/Downloads/{set-name} /tmp/tracklist.json

该脚本通过模糊匹配将每个 MP3 文件关联至曲目列表中的对应条目，并重命名为标准格式 Artist - Title.mp3。可自动处理诸如 NA - 前缀、(Official Video) 垃圾信息、错误艺人署名、厂牌名嵌入等问题。

关键说明：此步骤必须在主代理（parent agent）中、全部子批次返回后再执行 —— 切勿交由子代理分别重命名。已解析的曲目列表是文件命名的唯一可信来源（source of truth）。

6. 生成日志文件

创建日志文件：~/Downloads/{set-name}/{timestamp}.log，格式如下：

DJ Set Ripper Log
=================
Set: {set title}
URL: {original url}
Date: {ISO timestamp}
Tracks found: {total}

#   | Artist              | Title                          | Status         | Source   | Bitrate | Size  | File/Link
----|---------------------|--------------------------------|----------------|----------|---------|-------|----------
01  | Argy                | Aria (Original Mix)            | ✅ downloaded   | spotdl   | 320k    | 8.2MB | Argy - Aria (Original Mix).mp3
02  | ID                  | ID                             | ⬛ unidentified | —        | —       | —     | —
03  | Massano             | Odyssey                        | ✅ downloaded   | youtube  | 271k    | 6.5MB | Massano - Odyssey.mp3
04  | Boris Brejcha       | Gravity (Extended Mix)         | 🛒 purchase     | beatport | —       | —     | https://...
05  | Some Bootleg        | Unreleased VIP                 | ❌ not found    | —        | —       | —     | —

Summary: 3 downloaded, 1 purchase link, 1 not found, 1 unidentified
Total size: ~XXM (individual tracks) + XXM (full mix)
Full mix: ✅ downloaded → {set-name} [Full Mix].mp3

Notes:
- Bitrate via `ffprobe -v quiet -show_entries format=bit_rate -of csv=p=0 ""`
- File size via `ls -lh`

边界情况（Edge Cases）

• 简介中无曲目列表 —— 使用 web_search 查询 1001Tracklists："{set title}" site:1001tracklists.com
• "ID - ID" 曲目 —— 记录为未识别（unidentified），不尝试下载
• Bootleg / Mashup —— 仍尝试搜索，但预期失败率较高；记录为 not found 并附加说明
• B2B 混音集 —— 混音集标题含多位艺人时，应优雅兼容处理
• 重复曲目 —— 下载前依据 artist+title 去重
• 超长混音集（50+ 首） —— 每次分组处理 5 首，各批次完成后报告进度

配置项