| name | mmx-music |
| description | 使用 mmx CLI 通过 MiniMax AI 生成音乐和歌曲翻唱。当用户想要创作音乐、生成歌曲、制作背景音乐（BGM）、创作器乐曲、翻唱歌曲，或提到"生成音乐"、"作曲"、"BGM"、"music generate"、"music cover"时使用。 |
MiniMax 音乐生成技能
使用 mmx music 命令通过 MiniMax AI 生成原创音乐和歌曲翻唱。
默认原则：把用户当小白，用对话引导需求，再转换成专业提示词。不要一上来就问参数，先问故事和感觉。
工作流总览
用户描述需求
↓
【第一步】引导需求（5个问题）
↓
【第二步】转换专业提示词
↓
【第三步】确认歌词方案
↓
【第四步】确认音质 + 时长
↓
【第五步】保存草稿到本地文件 ← 必须执行，生成前留档
↓
【第六步】展示歌词给用户审核 ← 必须等用户确认才能继续
↓
【第七步】生成并验证
强制规则：第五步和第六步不可跳过。未保存草稿、未获得用户确认，禁止调用 mmx music generate。
第一步：引导需求（小白友好对话）
用自然语言问用户以下问题，不要直接问参数名：
| 问题 | 目的 | 用户回答示例 → 转换 |
|---|
| 这首歌想讲什么故事/传达什么感觉？ | 确定主题和情绪 | "星星坠落凡间" → 仙侠叙事 |
| 想要什么音乐风格？（古风/流行/民谣/电子…） | 确定流派 | "古代武侠那种" → 古风仙侠 |
| 有歌词吗？还是让 AI 帮你写？还是纯音乐？ | 决定生成模式 | "我有词" / "帮我写" / "纯乐" |
| 想要男声还是女声？还是都要？ | 确定人声 | "仙气女声" → 清冷仙气女声 |
| 想要多长？（参考：2分钟=短、3分钟=标准、4分钟+=长曲） | 控制时长 | "至少4分钟" |
第二步：将用户需求转换为专业提示词
需求翻译对照表
| 用户说 | 转换为专业 prompt |
|---|
| 古风、仙侠、武侠 | 中国古风仙侠叙事曲，洞箫、二胡、古筝、琵琶、编钟 |
| 有点悲、伤感 | 悲而不绝，空灵飘渺，情深意远 |
| 有点燃、激动 | 磅礴大气，弦乐全奏，情绪层层递进 |
| 安静、冥想 | 极慢如诉如梦，空灵，留白极多 |
| 爱情故事 | 情深缱绻，月下相逢，缘聚缘散 |
| 仙气、空灵 | 若有若无，编钟点拨，洞箫飘渺 |
| 史诗感 | 宏大叙事，弦乐铺底，鼓点铿锵 |
| 欢快、愉悦、轻松 | 明亮轻盈，欢快活泼，情绪上扬，弦乐轻快 |
人声翻译
| 用户说 | 转换 |
|---|
| 仙气女声 | 清冷仙气女声，吐字清晰，副歌加轻柔和声，尾声渐弱如诉 |
| 大叔男声 | 低沉沧桑男声，情感内敛，副歌爆发 |
| 男女合唱 | 清亮女声主唱，低沉男声和声，副歌二重唱交织 |
| 童声 | 清澈童声，纯真质朴 |
第三步：歌词方案
默认歌词生成技能：使用 mmx-lyrics-gen（直接调用 /v1/lyrics_generation API），更快速轻量。如需精细控制，可用 mmx-lyrics 通过 mmx text chat 创作。
3a. 用户没有歌词 → 用 mmx-lyrics-gen 生成
调用歌词生成 API：
API_KEY=$(cat ~/.mmx/config.json | grep -o '"api_key": *"[^"]*"' | sed 's/"api_key": *"\([^"]*\)"/\1/')
curl -s --request POST \
--url https://api.minimaxi.com/v1/lyrics_generation \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data '{"mode": "write_full_song", "prompt": "中文歌词，主题描述"}'
prompt 建议：
- 包含主题 + 风格 + 情绪 + "中文歌词"
- 示例：
"中文歌词，一首关于夏日海边的轻快情歌"、"中文歌词，古风仙侠，讲述星落凡间的故事，空灵悲情"
API 返回格式：
{
"song_title": "歌曲标题",
"style_tags": "风格标签",
"lyrics": "[Intro]\n...\n[Verse]\n...\n[Chorus]\n...",
"base_resp": {"status_code": 0, "status_msg": "success"}
}
注意：API 有时返回英文歌词，务必在 prompt 中明确"中文歌词"。
3b. 歌词初稿生成后，可选生成参考变体
若用户需要多个版本对比，用 mmx-lyrics-gen 的 edit 模式：
curl -s --request POST \
--url https://api.minimaxi.com/v1/lyrics_generation \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data '{"mode": "edit", "prompt": "改得更清冷空灵", "lyrics": "原歌词内容"}'
展示格式：
【原版】API 生成的初稿
【版本A】清冷空灵风 — edit 模式生成
【版本B】情深婉转风 — edit 模式生成
请选择哪个版本（或综合修改），或直接说"用原版"继续。
3c. 用户有歌词 → 添加结构标签
将用户提供的歌词，按段落加上结构标签（标签内不能有描述文字，只能有歌词）：
[Intro] 前奏/引子（有人声）
[Inst] 纯器乐段（无人声，每个约 20-40 秒）
[Solo] 独奏段（无人声，约 30 秒）
[Verse] 主歌
[Pre Chorus] 预副歌（副歌前的铺垫）
[Chorus] 副歌
[Transition] 过渡段
[Bridge] 桥段
[Build Up] 积累段（情绪爆发前）
[Outro] 结尾
[Post Chorus] 副歌后段
[Hook] 钩子段（反复强调的短句）
[Break] 间歇段
[Interlude] 间奏
3d. 古风歌词结构参考
[Intro] 引子：交代背景（4句）
[Inst] 器乐前奏（撑时间）
[Verse] 第一段：主角登场（4句）
[Verse] 第二段：情节发展（4句）
[Transition] 过渡：情感转折（4句）
[Pre Chorus] 诉衷情：内心独白（4句）
[Chorus] 副歌：情感高潮（6句）
[Inst] 器乐间奏（二胡独奏）
[Solo] 独奏
[Verse] 第三段：转折（4句）
[Bridge] 桥段：情绪爆发（4句）
[Build Up] 积累：高潮前
[Chorus] 副歌再现（6句）
[Outro] 终章（6句）
[Outro] 尾声镜像（重复引子，末句改变）
古风歌词创作技巧（来自《落星引》实战经验）
1. 韵脚规律（强制要求）
- 每段必须押韵：同一段落内所有句子押同一韵脚
- 韵韵不同：段落之间使用不同韵脚，避免重复
- 韵脚选择原则：按情绪走——欢快用 ang/iang/uang，悲情用 an/ian，逍遥用 ei/ui，豪放用 e/uo
- 同韵脚内避免重复用字（如"空风梦中"全不同字）
- 示例（四韵递进）：
- Intro: 天/山/巅/烟（an）
- Verse: 弦/暖/气/眠（ian）
- Chorus: 行/盈/程（ing）
- Bridge: 巍/催/贵（ui）
2. 镜像结构（尾声技巧）
- 尾声前三句与引子完全相同
- 末句改一个词，完成人物蜕变
- 示例：引子"一颗星子望烟中" → 尾声"只是斯人已不同"
3. 七字句 vs 五字句
- 五字句：节奏轻快，适合主歌
- 七字句：情感丰富，适合副歌和桥段
- 四字句：古朴庄重，适合引子
4. 情绪弧线
- 引子：空灵孤寂 → 主歌：人间好奇 → 过渡：情感初动
- 副歌：深情誓重 → 桥段：无路可退 → 终章：壮烈归去
- 欢快曲情绪弧线：轻盈开场 → 逍遥自在 → 飞行畅快 → 江湖雀跃
第四步：音质 + 时长设置
模型选择
CN 区用户注意：credentials.json 中 base_url 为 https://api.minimaxi.com（CN 区端点）的账号，不支持 --output-format url，无论使用哪个模型。统一使用 --out 文件名 直接写盘（已验证可用）。
| 参数 | 模型 | 特点 |
|---|
--model music-2.6 | music-2.6（付费） | 更高质量，写盘输出 |
--model music-2.6-free | music-2.6-free | 免费无限制（需 Max 计划） |
标准生成命令（写盘，无 URL）：
mmx music generate --model music-2.6 --prompt "..." --lyrics "..." --out song.wav --format wav --sample-rate 44100 --quiet
CN 区账号：只支持 --out 写盘，不支持 URL 输出。如需 URL 分享能力，需更换为支持 URL 的全球 API 端点（需新 API Key）。
音质预设（推荐直接用）
| 预设名 | 用途 | 参数 | 文件大小/分钟 |
|---|
| demo | 试听、草稿 | --format mp3 --bitrate 128000 | ~1MB |
| 标准 | 日常分享 | --format mp3 --bitrate 256000 | ~2MB |
| hi-fi | 正式作品、发布 | --format wav --sample-rate 44100 | ~10MB |
实测：generate 的 --format wav 有效，可直接输出 WAV（help 说明有误）。cover 支持 mp3 / wav / pcm。
时长控制方法（无 --duration 参数，间接控制）
核心规律（实测数据，music-2.6-free）：
| 结构 | BPM | 实测时长 |
|---|
| 基础歌词，无 [Inst] | 68 | 2:44 |
| +2个 [Inst] | 66 | 3:26 |
| +2个 [Inst] +1个 [Solo] +双 [Outro] | 60 | 3:39 |
| 14段（含2[Inst]+[Solo]+[Build Up]+双[Outro]） | 74 | 3:17 |
增加时长的方法（按效果排序）：
- 加
[Inst]（每个约 +20~40 秒，可叠加）
- 加
[Solo]（约 +30 秒）
- 降低
--bpm（60~65 适合慢曲）
- 重复
[Chorus]（让副歌出现两次）
- 重复
[Outro]（尾声延长）
- 在 prompt 中明确说明"不少于 X 分钟"
并发注意：同时发送两个生成请求会触发 RPM 限制导致静默失败，务必顺序执行，等第一个完成再发第二个。
注意：模型有自然时长上限，当前实测约 3:40 左右；超长曲建议事后用音频工具拼接。
第五步：保存草稿到本地文件（生成前必须执行）
在调用 mmx music generate 之前，必须将以下内容写入本地草稿文件：
草稿文件格式：
# 《歌曲名》创作草稿
创建时间：YYYY-MM-DD HH:mm
## 创作思路
（用 1-3 句话记录：这首歌想表达什么，核心意象是什么，情感弧线怎么走）
## 音乐方向
- 风格：
- 情绪：
- 人声：
- 乐器：
- BPM：
- 调性：
- 时长目标：
- 音质：
## 专业提示词（--prompt）
（完整粘贴转换后的 prompt 文本）
## 歌词（含结构标签）
（完整歌词，包含所有 [Inst][Solo][Chorus] 等标签）
## 生成命令
（完整的 mmx music generate 命令）
用 Write 工具将以上内容保存为本地 .md 文件，然后才能进入第六步。
第六步：展示歌词给用户审核（审核通过才能生成）
草稿保存后，必须向用户展示以下内容并等待确认：
- 完整歌词（含结构标签，逐段展示，标注每段作用）
- 音乐方向摘要（风格/人声/乐器/BPM/时长）
- 询问用户：
以上歌词和音乐方向是否满意？
- 直接回复"确认"或"可以" → 开始生成
- 指出需要修改的地方 → 修改后重新展示，再次确认
- 想重写某段歌词 → 按用户要求修改，更新草稿文件后再展示
收到用户明确确认信号后，才能执行 mmx music generate 命令。
第七步：生成命令
CN 区账号统一使用 --out 文件名 直接写盘。 不支持 --output-format url。
7a. 古风叙事长歌（完整模板）
mmx music generate \
--model music-2.6 \
--prompt "中国古风仙侠叙事长曲，空灵飘渺，情绪层层递进，整曲舒展宏大不少于四分钟。引子编钟+洞箫极慢空灵，长器乐前奏古筝铺垫，主歌琵琶+古筝轻快，过渡段二胡入场情感转折，副歌弦乐全奏推向高潮，长器乐间奏二胡独奏，终章星落归天磅礴，长尾声极弱渐至寂灭" \
--lyrics "[Intro]
引子歌词
[Inst]
[Verse]
主歌歌词
[Chorus]
副歌歌词
[Inst]
[Solo]
[Bridge]
桥段歌词
[Chorus]
副歌再现
[Outro]
终章歌词
[Outro]
尾声镜像" \
--vocals "清冷仙气女声，吐字清晰，副歌加入轻柔和声，尾声渐弱如诉" \
--instruments "洞箫, 二胡, 古筝, 琵琶, 编钟, 弦乐" \
--genre "古风仙侠" \
--mood "空灵, 悲而不绝, 情深意远" \
--bpm 60 \
--key "D minor" \
--format wav \
--sample-rate 44100 \
--out 歌曲名.wav \
--quiet
7b. 流行歌曲（自动生成歌词）
mmx music generate \
--model music-2.6 \
--prompt "中文流行，关于城市夜晚的孤独，轻柔忧郁" \
--lyrics-optimizer \
--vocals "清亮女声，温柔细腻" \
--genre "pop" \
--mood "melancholic" \
--bpm 85 \
--format mp3 \
--out city_night.mp3 \
--quiet
7c. 纯器乐 BGM
mmx music generate \
--model music-2.6 \
--prompt "史诗交响乐，紧张感逐渐积累，适合电影配乐" \
--instrumental \
--instruments "弦乐, 铜管, 定音鼓" \
--tempo "moderate to fast" \
--format mp3 \
--out bgm.mp3 \
--quiet
7d. 歌曲翻唱
mmx music cover \
--prompt "民谣风格，木吉他，温暖男声" \
--audio-file original.mp3 \
--lyrics-file lyrics.txt \
--format wav \
--sample-rate 44100 \
--out folk_cover.wav \
--quiet
验证步骤
生成后用 ffprobe 检查时长：
ffprobe -v quiet -show_entries format=duration,size -of default=noprint_wrappers=1 输出文件.wav
duration 单位是秒，除以 60 = 分钟- 如时长不足，追加
[Inst] 段落并降低 BPM 后重新生成
重复生成规则（版本保留）
禁止覆盖或删除已有音频文件。每次重新生成前，执行以下归档操作：
mkdir -p archived
mv 落星引.wav archived/落星引_$(date +%Y%m%d_%H%M).wav
mv 落星引_draft_*.md archived/ 2>/dev/null || true
完整规则：
| 场景 | 操作 |
|---|
| 第一次生成 | 直接输出到当前目录 |
| 重新生成（调整歌词/BPM/风格） | 先归档旧文件，再生成新文件 |
| 用户说"保留两个版本比较" | 归档旧文件，新文件用新名（如 落星引_v2.wav） |
| 用户说"直接覆盖" | 仍然归档（保护原则，不覆盖） |
归档后告知用户：旧版本已移至 archived/落星引_YYYYMMDD_HHMM.wav
参考案例：《落星引》完整提示词
这是一首古风仙侠叙事词，四韵回环，尾声镜像引子，约 3:39（加更多 [Inst] 可再延长）。
歌词结构：[Intro] 引子 → [Inst] → [Verse] 一段 → [Verse] 二段 → [Transition] 过渡 → [Pre Chorus] 诉衷情 → [Chorus] 副歌 → [Inst][Solo] → [Verse] 三段 → [Bridge] 桥段 → [Build Up] → [Chorus] 副歌再现 → [Outro] 终章 → [Outro] 尾声镜像
Prompt 核心：中国古风仙侠叙事长曲，空灵飘渺，情绪层层递进，不少于四分钟，BPM 60，D minor，洞箫二胡古筝琵琶编钟弦乐
注意事项
- 模型默认：
music-2.6（CN 区写盘模式）
--lyrics-optimizer 和 --instrumental 不能与 --lyrics 同用- 歌词最长约 3500 字符
[Inst] [Solo] 等标签内不要写文字，模型会把文字唱出来- 始终加
--quiet 避免进度条干扰输出
- WAV 文件约 10MB/分钟，mp3 约 2MB/分钟
古风调性/乐器经验与限额备选方案见 references/music-extended-guide.md（按需加载）。
