name: minimax-music-gen
description: 当用户想要生成音乐、歌曲或音频曲目时使用。触发任何涉及音乐创作、歌曲写作、歌词生成、音频制作或翻唱的请求。当用户提供歌词并希望将其转化为歌曲，或描述某种情绪/场景并希望获得背景音乐时，也会触发。支持多语言触发——匹配任何语言中的等效短语。请勿用于现有文件的音乐播放、乐理问题或没有生成过程的音乐推荐。
license: MIT
metadata:
    version: "1.1"
    category: creative

MiniMax 音乐生成技能

使用 MiniMax Music API 生成歌曲（人声或器乐）。支持两种创作模式：基础模式（一句话输入，生成歌曲）和高级控制模式（编辑歌词、优化提示词、生成前规划）。

前置条件

• mmx CLI（必需）：音乐生成使用 mmx 命令行工具。

检查是否已安装：

  command -v mmx && mmx --version || echo "mmx not found"

安装（需要 Node.js）：

  npm install -g mmx-cli

身份验证（仅首次需要）：

  mmx auth login --api-key <你的-minimax-api-key>

可从 MiniMax 平台 获取 API 密钥。凭据会保存到 ~/.mmx/credentials.json，跨会话持久生效。

验证：

  mmx quota show

• 音频播放器（推荐）：mpv、ffplay 或 afplay（macOS 内置）用于本地播放。推荐使用 mpv，支持交互式控制。

CLI 工具

本技能使用 mmx CLI 进行所有音乐生成：

• 音乐生成：mmx music generate — 模型：music-2.6-free
• 支持 --lyrics-optimizer 根据提示词自动生成歌词
• 支持 --instrumental 生成纯器乐
• 支持 --lyrics 使用用户提供的歌词
• 结构化参数：--genre、--mood、--vocals、--instruments、--bpm、--key、--tempo、--structure、--references

• 翻唱：mmx music cover — 模型：music-cover-free
• 通过 --audio-file <路径> 或 --audio <URL> 传入参考音频
• --prompt 描述目标翻唱风格

代理标志：当从代理调用 mmx 时，始终添加 --quiet --non-interactive。

流程：

• 人声：用户描述 -> mmx music generate --lyrics-optimizer -> MP3
• 器乐：用户描述 -> mmx music generate --instrumental -> MP3
• 翻唱：源音频 + 风格 -> mmx music cover -> MP3

存储

所有生成的音乐保存到 ~/Music/minimax-gen/。如果目录不存在则创建。文件以时间戳和提示词派生出的短标识符命名：YYYYMMDD_HHMMSS_<slug>.mp3

---

语言与交互

从用户的第一条消息开始检测用户语言，并在整个会话中使用该语言回复。这适用于所有交互文本、问题、确认和反馈提示。

面向用户文本本地化规则：

• 所有向用户展示的文本——包括预览标签、字段名称、确认信息、状态消息、播放信息、反馈提示，以及提示词/描述预览——都必须完全翻译为用户语言。
• 发送给模型的 API 提示词应始终使用英文以获得最佳生成质量。但是，当向用户预览提示词时，应使用用户语言的本地化描述替代原始英文提示词。英文提示词是内部实现细节——用户无需看到。
• 下面的模板使用英文作为参考。运行时，将所有标签和消息翻译为用户检测到的语言。

歌词语言规则：

• 默认歌词语言 = 用户语言。中文用户得到中文歌词；英文用户得到英文歌词。
• 仅当用户明确要求时，才生成其他语言的歌词。
• 当需要不同语言的歌词时，将其自然地嵌入到人声或流派描述中。例如，不要附加“带韩语歌词”，而是使用“由韩国女歌手演唱”或指定一种暗示该语言的流派（如“K-pop”、“J-rock”、“Mandopop”、“Latin pop”）。

---

工作流程

第 0 步：识别意图

解析用户的消息以确定：

1. 歌曲类别：人声（带歌词）、器乐（无演唱）或翻唱
2. 创作模式偏好：他们提供了详细需求（高级）还是随意的单行描述（基础）

如果不明确，使用以下决策树询问：

Q1: 什么类型的音乐？
  - 人声（带歌词）
  - 器乐（无演唱）
  - 翻唱

Q2: 创作模式？
  - 基础 —— 一行描述，自动生成
  - 高级 —— 编辑歌词，优化提示词，规划

如果用户给出明确的一句话，如“给我做一个悲伤的钢琴曲”，则跳过问题——推断为器乐+基础模式并继续。

---

第 1 步：基础模式

目标：用户提供简短描述，技能自动生成一切，然后调用 API。

1. 将描述扩展为提示词：取用户的一句话并将其扩展为丰富的音乐提示词。参考本文档末尾的提示词编写指南附录，了解风格词汇、流派/乐器参考和提示词结构。API 提示词应始终使用英文以获得最佳生成质量，无论用户语言如何。

遵循以下模式：

   A [mood] [BPM optional] [genre] song, featuring [vocal description],
   about [narrative/theme], [atmosphere], [key instruments and production].

1. 在生成前向用户展示预览。将所有标签和提示词描述翻译为用户语言。英文提示词仅在调用 API 时内部使用——用户永远不应看到它。示例模板（英文参考——运行时本地化所有内容）：

   即将生成：
   类型：人声 / 器乐
   描述：独立民谣，忧郁，原声吉他，温柔女声
   歌词：自动生成 (--lyrics-optimizer)
   
   确认？（按回车确认，或告诉我需要修改什么）

1. 调用 mmx：直接生成音乐。

---

第 2 步：高级控制模式

目标：用户在生成前完全控制每个参数。

1. 歌词阶段：

• 如果用户提供了歌词：显示带段落标记的格式化歌词，询问修改意见。最终的歌词将通过 --lyrics 传递给 mmx。
• 如果用户有主题但没有歌词：将使用 --lyrics-optimizer 自动生成。
• 支持迭代编辑：“修改第二段副歌” -> 仅重写该部分。
• 用户也可以自己编写歌词并通过 --lyrics 传入。

1. 提示词阶段：

• 根据歌词的情感和内容生成建议提示词。
• 以可编辑标签的形式呈现，用户可以添加/删除/修改。
• 参考提示词编写指南附录，获取完整词汇表。

1. 高级规划（可选，提供但不强制）：

• 歌曲结构：主歌-副歌-主歌-副歌-桥段-副歌 或自定义
• BPM 建议（在提示词中编码为速度描述）
• 参考风格：“类似 X 风格” -> 映射到提示词标签
• 人声角色描述

1. 最终确认：显示完整的参数摘要，然后生成。

---

第 3 步：调用 mmx

使用 mmx CLI 生成音乐：

带自动生成歌词的人声：

mmx music generate \
  --prompt "<prompt>" \
  --lyrics-optimizer \
  --genre "<genre>" --mood "<mood>" --vocals "<vocal style>" \
  --instruments "<instruments>" --bpm <bpm> \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

带用户提供歌词的人声：

mmx music generate \
  --prompt "<prompt>" \
  --lyrics "<lyrics with section markers>" \
  --genre "<genre>" --mood "<mood>" --vocals "<vocal style>" \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

器乐（无演唱）：

mmx music generate \
  --prompt "<prompt>" \
  --instrumental \
  --genre "<genre>" --mood "<mood>" --instruments "<instruments>" \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

使用结构化参数（--genre、--mood、--vocals、--instruments、--bpm、--key、--tempo、--structure、--references、--avoid、--use-case）为 API 提供精细控制，而不是将所有内容塞入 --prompt。

在等待时显示进度指示器。典型生成时间 30-120 秒。

---

第 4 步：播放

生成后，检测可用的音频播放器并播放文件。

检测播放器：

command -v mpv || command -v ffplay || command -v afplay

根据检测到的播放器播放（按优先级排序）：

开始播放后，告知用户（本地化所有文本）：

正在播放: <filename>.mp3
保存至: ~/Music/minimax-gen/<filename>.mp3

不要显示播放控制键（如键盘快捷键）——它们在此环境中不起作用，因为播放器在后台运行。

如果未找到播放器（本地化所有文本）：

未检测到音频播放器。
文件保存至: ~/Music/minimax-gen/<filename>.mp3
提示：安装 mpv 以获得最佳播放体验（brew install mpv）。

---

第 5 步：反馈与迭代

播放后，询问反馈：

这首歌曲怎么样？
  1. 很喜欢，保留它！
  2. 不太对，调整并重新生成
  3. 微调歌词/风格后重新生成
  4. 不想要，重新开始

根据反馈：

• 满意：完成。再次提及文件路径。
• 调整并重新生成：询问要修改什么（提示词？歌词？风格？），应用修改，重新运行生成。保留旧文件并添加 _v1 后缀以便比较。
• 微调：以当前参数预填充进入高级控制模式。
• 删除并重新开始：删除文件，返回第 0 步。

---

翻唱模式

基于参考音频生成歌曲的翻唱版本。模型：music-cover-free。

参考音频要求：mp3、wav、flac — 时长 6 秒至 6 分钟，最大 50MB。如果未提供歌词，则自动通过 ASR 提取原始歌词。

工作流程

当用户选择翻唱模式时：

1. 询问源音频——本地文件路径或 URL
2. 询问目标翻唱风格（例如，“不插电翻唱，精简，亲密的演唱”）
3. 可选地询问自定义歌词或歌词文件

命令

从本地文件翻唱：

mmx music cover \
  --prompt "<cover style description>" \
  --audio-file <source.mp3> \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

从 URL 翻唱：

mmx music cover \
  --prompt "<cover style description>" \
  --audio <source_url> \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

带自定义歌词（文本）：

mmx music cover \
  --prompt "<style>" \
  --audio-file <source.mp3> \
  --lyrics "<custom lyrics>" \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

带自定义歌词（文件）：

mmx music cover \
  --prompt "<style>" \
  --audio-file <source.mp3> \
  --lyrics-file <lyrics.txt> \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

可选参数

生成后

按正常的播放和反馈流程继续（第 4 步和第 5 步）。

---

错误处理

---

重要说明

• 绝不复制受版权保护的歌词。 制作翻唱时，始终基于歌曲主题编写原创歌词。向用户解释这一点。
• 提示词语言：API 提示词使用英文标签效果最佳。中文标签也可接受。混合使用没问题。
• 歌词中的段落标记：API 支持 [verse]、[chorus]、[bridge]、[outro]、[intro]。在使用 --lyrics 时始终包含它们。
• 文件管理：如果 ~/Music/minimax-gen/ 中的文件超过 50 个，建议在开始新会话时进行清理。
• 结构化参数：优先使用 --genre、--mood、--vocals、--instruments、--bpm 等，而不是将所有内容嵌入 --prompt。这可以给 API 更好的控制。
• 通过风格设置歌词语言：当用户希望以特定语言创作歌词时，通过人声描述或流派来表达（例如，“日本女歌手”、“Mandopop 情歌”），而不是在提示词中附加语言指令。

---

附录：提示词编写指南

完整的提示词编写指南（包括流派/人声/乐器参考和 BPM 表格）请参见 [references/prompt_guide.md](references/prompt_guide.md)。