mmx-music

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
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

增加时长的方法（按效果排序）：

1. 加 [Inst]（每个约 +20~40 秒，可叠加）
2. 加 [Solo]（约 +30 秒）
3. 降低 --bpm（60~65 适合慢曲）
4. 重复 [Chorus]（让副歌出现两次）
5. 重复 [Outro]（尾声延长）
6. 在 prompt 中明确说明"不少于 X 分钟"

并发注意：同时发送两个生成请求会触发 RPM 限制导致静默失败，务必顺序执行，等第一个完成再发第二个。

注意：模型有自然时长上限，当前实测约 3:40 左右；超长曲建议事后用音频工具拼接。

---

第五步：保存草稿到本地文件（生成前必须执行）

在调用 mmx music generate 之前，必须将以下内容写入本地草稿文件：

# 文件命名规则：歌曲名_draft_YYYYMMDD.md
# 存放位置：与音频文件同目录，或用户指定目录

草稿文件格式：

# 《歌曲名》创作草稿
创建时间：YYYY-MM-DD HH:mm

## 创作思路
（用 1-3 句话记录：这首歌想表达什么，核心意象是什么，情感弧线怎么走）

## 音乐方向
- 风格：
- 情绪：
- 人声：
- 乐器：
- BPM：
- 调性：
- 时长目标：
- 音质：

## 专业提示词（--prompt）
（完整粘贴转换后的 prompt 文本）

## 歌词（含结构标签）
（完整歌词，包含所有 [Inst][Solo][Chorus] 等标签）

## 生成命令
（完整的 mmx music generate 命令）

用 Write 工具将以上内容保存为本地 .md 文件，然后才能进入第六步。

---

第六步：展示歌词给用户审核（审核通过才能生成）

草稿保存后，必须向用户展示以下内容并等待确认：

1. 完整歌词（含结构标签，逐段展示，标注每段作用）
2. 音乐方向摘要（风格/人声/乐器/BPM/时长）
3. 询问用户：

以上歌词和音乐方向是否满意？

• 直接回复"确认"或"可以" → 开始生成
• 指出需要修改的地方 → 修改后重新展示，再次确认
• 想重写某段歌词 → 按用户要求修改，更新草稿文件后再展示

收到用户明确确认信号后，才能执行 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 后重新生成

---

重复生成规则（版本保留）

禁止覆盖或删除已有音频文件。每次重新生成前，执行以下归档操作：

# 1. 创建 archived 子目录（如不存在）
mkdir -p archived

# 2. 将旧文件移入 archived，文件名加时间戳
# 示例：落星引.wav → archived/落星引_20260428_0200.wav
mv 落星引.wav archived/落星引_$(date +%Y%m%d_%H%M).wav

# 3. 草稿文件同样归档
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（按需加载）。