minimax-music-playlist

MiniMax Music Playlist — 个性化播放列表生成器

扫描用户的音乐偏好，建立偏好档案，生成个性化播放列表，并创建专辑封面。此技能既支持 Agent 调用，也支持用户直接调用——请根据上下文调整交互方式。

前置条件

• mmx CLI — 用于音乐和图像生成。安装：npm install -g mmx-cli。认证：mmx auth login --api-key <key>。
• Python 3 — 用于运行临时编写的扫描脚本（仅使用标准库，无需 pip）。
• 音频播放器 — mpv、ffplay 或 afplay（macOS 内置）。

语言

根据用户的消息识别其语言。所有面向用户的文本都必须与用户提示词使用同一种语言——不要混用语言。如果用户用中文书写，所有输出（偏好档案摘要、主题建议、播放列表规划、播放信息）都必须使用中文。如果用户用英文书写，则所有输出都使用英文。

所有 mmx 生成提示词都应使用英文，以获得最佳效果。 每首歌曲的歌词语言应根据其流派决定（K-pop → 韩语、J-pop → 日语等），而不是根据用户界面语言决定。

---

工作流

1. Scan local music apps → 2. Build taste profile → 3. Plan playlist
→ 4. Generate songs (mmx music) → 5. Generate cover (mmx image) → 6. Play → 7. Save & feedback

---

第 1 步：收集音乐聆听数据

从可用来源收集用户的聆听数据。

支持的来源：

来源	方法	数据格式
Apple Music	使用 osascript 查询 Music.app（AppleScript 官方接口）	曲目名称、艺人、专辑、流派、播放次数
Spotify	用户通过 Spotify Privacy Settings 导出自己的数据	ZIP 中的 JSON 文件（Streaming_History_Audio_*.json）
手动输入	用户直接描述其偏好	自由文本

Spotify 数据导出流程： Spotify 不会在本地存储有用的数据。若要纳入 Spotify 聆听历史记录， 请先检查用户是否已有 Spotify 数据导出文件：

1. 搜索现有导出文件：find ~ -maxdepth 4 -name "my_spotify_data.zip" -o -name "Streaming_History_Audio_*.json" 2>/dev/null
2. 如果找到，询问用户是否要使用
3. 如果是 ZIP 文件，解压并找到 Spotify Extended Streaming History/Streaming_History_Audio_*.json
4. 如果未找到，打开 Spotify 隐私页面：open https://www.spotify.com/account/privacy/
5. 告诉用户登录，向下滚动到“下载你的数据”，然后点击“请求数据”
6. 暂时跳过 Spotify，继续使用其他来源——告诉用户数据导出文件收到后（通常需要几天）可以重新运行播放列表技能

Spotify 数据格式： 导出文件包含 Streaming_History_Audio_YYYY.json 文件（每年一个），每个文件都是聆听事件的 JSON 数组。需要提取的关键字段：

• master_metadata_album_artist_name — 艺人名称
• master_metadata_track_name — 曲目名称
• master_metadata_album_album_name — 专辑名称
• ms_played — 播放时长（毫秒）（用作权重：时长越长，信号越强）
• ts — 时间戳

过滤掉 ms_played < 30000 的条目（少于 30 秒，可能是跳过的曲目）。 不要使用或存储 ip_addr 或其他敏感字段。

从每种来源提取的内容：

• 曲目名称 + 艺人名称（主要信号）
• 播放列表名称及其曲目归属（例如，名为“Chinese Traditional”的播放列表说明用户偏好该流派）
• 可用时提取播放次数或流媒体播放时长（提高常听曲目的权重）
• 可用时提取场景／情绪标签

方法：

1. 检查 Apple Music 是否可用（尝试使用 osascript 查询）
2. 询问用户是否有可提供的 Spotify 数据导出 ZIP 文件
3. 如果没有可用来源，请用户手动描述其偏好

**隐私规则：**绝不向用户展示原始曲目列表。只展示汇总统计数据。

---

第 2 步：构建品味档案

根据扫描的数据，构建一份品味档案，涵盖：

• 流派分布 — 用户聆听的风格（例如，J-pop 20％、R&B 15％、古典音乐 10％）
• 情绪倾向 — 用户偏好的情绪基调（忧郁、活力、平静、浪漫等）
• 人声偏好 — 男声与女声的比例
• 节奏偏好 — 慢速／中速／轻快／快速的分布
• 语言分布 — zh、en、ja、ko 等
• 最常听的艺人 — 聆听次数最多的艺人

如何从艺人名称推断流派／情绪： 大多数原始数据只有艺人和曲目名称，没有流派标签。可通过以下方式补充信息：

1. 在本地映射表 <SKILL_DIR>/data/artist_genre_map.json 中查询艺人 — 此表涵盖 20,000 位热门艺人，并预先映射了流派、声部类型和语言
2. 对于映射表中没有的艺人，查询 MusicBrainz API： https://musicbrainz.org/ws/2/artist/?query=artist:<name>&fmt=json — 从响应中提取流派标签；遵守速率限制（1 req/sec） — 将结果缓存到 <SKILL_DIR>/data/artist_cache.json，避免重复查询
3. 如果 MusicBrainz 没有返回结果，则跳过该艺人

档案缓存：

• 将档案保存到 <SKILL_DIR>/data/taste_profile.json
• 如果存在未满 7 天的档案，则重复使用（提供重新扫描选项）
• 如果档案已超过 7 天或不存在，则重新构建

向用户展示摘要：

Your Music Profile:
  Sources: Apple Music 230 | Spotify 140
  Genres: J-pop 20% | R&B 15% | Classical 10% | Indie Pop 9%
  Moods: Melancholic 25% | Calm 20% | Romantic 18%
  Vocals: Female 65% | Male 35%
  Top artists: Faye Wong, Ryuichi Sakamoto, Taylor Swift, Jay Chou, Taeko Onuki

如果由 Agent 使用明确参数调用，则跳过确认并继续。 如果由用户直接调用，则在继续之前询问档案是否准确。

---

第 3 步：规划播放列表

生成前先询问用户主题／场景。 这是工作流中唯一的 交互步骤。其他步骤都会自动运行。

如果调用时已提供主题（例如，Agent 或用户说“生成一份深夜舒缓播放列表”）， 则直接使用该主题并跳过提问。 否则，询问：

What theme would you like for your playlist? Here are some suggestions:

- "Late night chill" — relaxing slow songs
- "Commute" — upbeat and energizing
- "Rainy day" — melancholic & cozy
- "Surprise me" — random based on your taste

Or tell me your own vibe!

用户选定主题后，自动继续生成、制作封面、播放和保存 — 无需进一步确认。

确定播放列表参数：

• 主题／情绪 — 根据用户输入，或默认为档案中的首要情绪
• 歌曲数量 — 根据用户输入，或默认为 5
• 流派组合 — 按档案加权，并确保多样性

每首歌的歌词语言根据流派确定：

流派	歌词语言
K-pop、韩国 R&B／抒情歌	韩语
J-pop、city pop、J-rock	日语
C-pop、华语风格、Mandopop	中文
西方流行／独立／摇滚／爵士／R&B	英语
拉丁流行、bossa nova	西班牙语／葡萄牙语
纯音乐、lo-fi、氛围音乐	无歌词（--instrumental）

通过人声描述，将语言自然地融入 mmx 提示词：

• 好的示例："A melancholy Chinese R&B ballad with a gentle introspective male voice, electric piano, bass, slow tempo"
• 不好的示例："R&B ballad, melancholy... sung in Chinese"

生成前向用户展示播放列表计划。 每首歌显示两行： 第一行显示流派、情绪和人声／语言标签；第二行显示歌曲的简短描述。 所有面向用户的文本（计划、描述、情绪、标签）都必须使用与用户提示相同的语言。 只有传递给 mmx 的实际 --prompt 才应使用英语 — 这是内部内容，不应展示给 用户。示例：

Playlist Plan: Late Night Chill (5 songs)

1. Neo-soul R&B — introspective  English/male vocal
   A mellow neo-soul R&B ballad with warm baritone, electric piano, smooth bass

2. Lo-fi hip-hop — dreamy  Instrumental
   Dreamy lo-fi with sampled piano, vinyl crackle, soft electronic drums

3. Smooth jazz — romantic  English/female vocal
   Silky female voice, saxophone, piano, romantic starlit night

4. Indie folk — melancholic  English/male vocal
   Tender male voice, acoustic guitar, harmonica, quiet solitude

5. Ambient electronic — calm  Instrumental
   Soft synth pads, gentle arpeggios, dreamy atmosphere

展示计划后，直接开始生成 — 无需确认。 用户已经选定主题；展示计划是为了让过程透明，而不是征求批准。

---

步骤 4：生成歌曲

使用 mmx music generate 创建所有歌曲。并行生成（最多同时生成 5 首）。

# Example: 5 songs in parallel
mmx music generate --prompt "<english_prompt_1>" --lyrics-optimizer \
  --out ~/Music/minimax-gen/playlists/<name>/01_desc.mp3 --quiet --non-interactive &
mmx music generate --prompt "<english_prompt_2>" --instrumental \
  --out ~/Music/minimax-gen/playlists/<name>/02_desc.mp3 --quiet --non-interactive &
# ... more songs ...
wait

关键标志：

• --lyrics-optimizer — 根据提示词自动生成歌词（用于人声曲目）
• --instrumental — 无人声
• --vocals "<description>" — 人声风格（例如，“温暖的中国男中音”）
• --genre、--mood、--tempo、--instruments — 精细控制
• --quiet --non-interactive — 批处理模式下禁止交互式输出
• --out <path> — 保存到文件

文件命名： <NN>_<short_desc>.mp3（例如，01_rnb_midnight.mp3）

输出目录： ~/Music/minimax-gen/playlists/<playlist_name>/

如果歌曲生成失败，重试一次后再跳过。记录错误并继续处理其余歌曲。

---

步骤 5：生成专辑封面

与歌曲同时生成专辑封面（步骤 4），不要等歌曲生成完毕后再生成。 与歌曲生成调用并行启动 mmx image generate 调用。

编写能体现播放列表主题、情绪和混合曲风的提示词。图像应有专辑封面的感觉——富有艺术感、引人遐想，而非写实。

mmx image generate \
  --prompt "<cover description based on playlist theme and mood>" \
  --aspect-ratio 1:1 \
  --out-dir ~/Music/minimax-gen/playlists/<playlist_name>/ \
  --out-prefix cover \
  --quiet

提示词指南：

• 抽象／艺术风格最适合作为专辑封面
• 描述主要情绪和曲风（例如，“梦幻的深夜城市景观、霓虹倒影、低保真美学”）
• 请勿在图像提示词中包含文字或歌曲标题
• 长宽比应为 1:1（正方形，标准专辑封面尺寸）

---

步骤 6：播放

检测可用的播放器，并按顺序播放播放列表：

播放器	命令	控制
mpv	mpv --no-video <file>	q 跳过，空格键暂停，方向键跳转
ffplay	ffplay -nodisp -autoexit <file>	q 跳过
afplay	afplay <file>	Ctrl+C 跳过

按文件名顺序播放播放列表目录中的所有 .mp3 文件。 只播放本次会话生成的歌曲——如果目录中有之前运行遗留的文件，请先清理或按已知文件名筛选。 如果找不到播放器，只显示文件路径。

---

步骤 7：保存并收集反馈

将播放列表元数据保存到 <playlist_dir>/playlist.json：

{
  "name": "Late Night Chill",
  "theme": "late night chill",
  "created_at": "2026-04-11T22:00:00",
  "song_count": 5,
  "cover": "cover_001.png",
  "songs": [
    {"index": 1, "filename": "01_rnb_midnight.mp3", "prompt": "...", "rating": null}
  ]
}

如果用户在场，请征求反馈（针对每首歌曲或整体）。将用户喜欢／不喜欢的曲风和提示词更新到品味档案的反馈部分，以改进后续播放列表。

---

重新播放播放列表

如果用户要求播放之前的播放列表：运行 ls ~/Music/minimax-gen/playlists/，展示可用播放列表，并播放选定的播放列表。

---

备注

• Agent 与用户调用的区别：主题／场景问题（步骤 3）是唯一的交互环节。如果调用中已提供主题，则跳过提问。其余步骤均自主运行。
• 不要使用硬编码脚本：根据需要临时编写扫描／分析脚本。仅使用 Python 标准库。缓存结果以避免重复工作。
• 技能目录：<SKILL_DIR> = 包含此 SKILL.md 文件的目录。数据／缓存文件存放在 <SKILL_DIR>/data/。
• 所有 mmx 提示词均使用英文，以获得最佳生成质量。