mmMusicExpert

Create music with MiniMax music models (music-2.5+, music-2.5). Use when generating songs, instrumental tracks, or chanting from lyrics and style prompts via MiniMax Music Generation API. Guides music novices through an interactive workflow to produce professional-quality music.

# MiniMax Music Expert

Generate music using MiniMax Music Generation API. Default model: **music-2.5+** (recommended).
This skill is designed to help **music novices** create professional-quality music through guided interaction.

## Environment Setup

```bash
export MINIMAX_MUSIC_API_KEY="your_api_key"
```

---

## Agent Workflow (MUST FOLLOW)

When a user requests music creation, **always** follow this 4-step interactive workflow. Do NOT skip steps or jump directly to generation.

### Step 1: Understand & Clarify Requirements

Analyze the user's input and identify which dimensions are already covered vs. missing. Then ask targeted follow-up questions to fill the gaps.

**Dimension checklist** — check which are provided, ask about the rest. Each question MUST provide lettered options (A/B/C/...) for the user to choose from:

| Dimension | Question with options |
|-----------|---------------------|
| **Type** | "这首歌的类型？ **A.** 有人声演唱的歌曲 **B.** 纯音乐/背景音乐(无人声) **C.** 哼唱/吟唱(旋律人声无歌词)" |
| **Genre/Style** | "你喜欢什么音乐风格？ **A.** 流行 **B.** 摇滚 **C.** 民谣 **D.** 电子/EDM **E.** 嘻哈/说唱 **F.** 爵士 **G.** 古风/中国风 **H.** R&B **I.** 其他(请描述)" |
| **Mood/Emotion** | "希望传达什么情绪？ **A.** 欢快活泼 **B.** 温柔抒情 **C.** 忧伤感怀 **D.** 激昂热血 **E.** 治愈放松 **F.** 大气磅礴/史诗感 **G.** 浪漫甜蜜 **H.** 其他(请描述)" |
| **Scene/Use case** | "这首歌打算用在什么场景？ **A.** 短视频/Vlog BGM **B.** 个人收藏/送人 **C.** 游戏/动画 **D.** 咖啡馆/餐厅 **E.** 婚礼/庆典 **F.** 运动/健身 **G.** 其他(请描述)" |
| **Tempo/Rhythm** | "节奏方面的偏好？ **A.** 慢速抒情(60-80 BPM) **B.** 中速舒缓(80-110 BPM) **C.** 中快轻快(110-130 BPM) **D.** 快速动感(130-160 BPM) **E.** 不确定，交给你来定" |
| **Instruments** | "有没有想要的乐器？ **A.** 钢琴为主 **B.** 吉他(民谣/电吉他) **C.** 中国民乐(笛子/琵琶/古筝/二胡) **D.** 弦乐(小提琴/大提琴) **E.** 电子合成器 **F.** 管乐(萨克斯/小号) **G.** 不确定，根据风格搭配 **H.** 其他(请描述)" |
| **Vocal** | "人声方面？(纯音乐跳过) **A.** 温柔女声 **B.** 有力女声 **C.** 温柔男声 **D.** 有力男声 **E.** 烟嗓/沙哑 **F.** 不确定，交给你来定" |
| **Lyrics** | "歌词方面？(纯音乐跳过) **A.** 我已有歌词 **B.** 我给主题/关键词，你来写 **C.** 全部交给AI自动生成" |
| **Dynamic Arc** | "歌曲的情绪走向？ **A.** 由浅入深，慢慢推向高潮 **B.** 开头就炸裂，全程高能 **C.** 先抑后扬(安静开头→爆发副歌) **D.** 起伏交替(安静→爆发→安静→更大爆发) **E.** 全程平稳舒缓 **F.** 不确定，交给你来编排" |
| **Reference** | "有没有喜欢的参考？(optional) **A.** 有，类似某个歌手/歌曲(请说明) **B.** 没有特别参考" |

**Rules:**
- 不要一次抛出所有问题。根据用户已提供的信息，只问**缺失的关键维度**（通常 2-4 个问题）
- 每个问题**必须带字母选项**(A/B/C/...)，降低用户决策成本
- 选项末尾提供"其他"或"交给你来定"的兜底选项，避免用户被选项限制
- 如果用户的需求已经很明确（覆盖了 Type + Genre + Mood + 至少一个其他维度），可以直接进入 Step 2

**示例交互：**
> 用户: "帮我做一首关于杭州的歌"
> Agent: "好的！关于这首杭州之歌，我还想确认几个方面，你可以直接回复选项字母：
>
> 1. 🎵 **风格**：**A.** 中国风民谣 **B.** 流行 **C.** 古风 **D.** R&B **E.** 其他
> 2. 🎤 **情绪**：**A.** 温柔抒情 **B.** 大气磅礴 **C.** 欢快明朗 **D.** 忧伤怀旧
> 3. 🎶 **人声**：**A.** 温柔女声 **B.** 有力女声 **C.** 温柔男声 **D.** 有力男声
> 4. 🎭 **情绪走向**：**A.** 由浅入深慢慢推向高潮 **B.** 先抑后扬 **C.** 全程舒缓 **D.** 起伏交替
> 5. ✍️ **歌词**：**A.** 我已有歌词 **B.** 我给主题你来写 **C.** AI自动生成
>
> 直接回复如 `1A 2B 3A 4A 5B` 即可！"

### Step 2: Design Song Blueprint & Present Draft

**This is the most important step.** Do NOT write a flat prompt. First design a **Song Blueprint** (段落蓝图) that plans each section's musical characteristics, then derive the prompt and lyrics from it.

#### Step 2a: Create Song Blueprint

Based on gathered requirements, plan the section-by-section musical journey. Each section should have distinct characteristics.

**Blueprint format:**

```
🎼 **歌曲蓝图**

| 段落 | 情绪/能量 | 乐器/编曲 | 人声表现 | 制作特点 |
|------|-----------|-----------|----------|----------|
| [Intro] | ... | ... | ... | ... |
| [Verse 1] | ... | ... | ... | ... |
| [Pre Chorus] | ... | ... | ... | ... |
| [Chorus] | ... | ... | ... | ... |
| ... | ... | ... | ... | ... |
```

**Blueprint example** (用户需求: "一首关于杭州的中国风民谣，温柔开头，副歌大气"):

```
🎼 **歌曲蓝图**

| 段落 | 情绪/能量 | 乐器/编曲 | 人声表现 | 制作特点 |
|------|-----------|-----------|----------|----------|
| [Intro] | 宁静悠远 ⚡① | 古筝独奏琶音 | — | 空间感大，远处水声质感 |
| [Verse 1] | 细腻叙述 ⚡② | +笛子旋律，轻拨琵琶 | 温柔低吟，呼吸感 | 亲密感，少混响 |
| [Verse 2] | 情感渐浓 ⚡③ | +二胡加入，节奏轻启 | 声线渐开，带感情 | 开始加宽声场 |
| [Pre Chorus] | 蓄势待发 ⚡⑤ | 弦乐铺底渐强，鼓点加入 | 力度上升，情绪推动 | 渐强(crescendo) |
| [Chorus] | 大气磅礴 ⚡⑧ | 全编制爆发：弦乐+鼓+笛+琵琶 | 高亢嘹亮，饱满和声 | "音墙"，宽广声场 |
| [Bridge] | 回归内省 ⚡③ | 仅钢琴+古筝 | 轻声吟唱 | 突然安静，对比反差 |
| [Chorus] | 最终爆发 ⚡⑨ | 全编制+合唱层叠 | 全力释放，高音 | 最高能量 |
| [Outro] | 渐归平静 ⚡② | 古筝回归独奏 | — | 渐弱收尾 |
```

⚡① ~ ⚡⑩ = energy level, 用于可视化段落间的能量变化曲线。

**Blueprint design principles:**
- **段落间必须有对比**：相邻段落的能量/乐器/人声至少有一项明显不同
- **能量曲线要有起伏**：避免全程同一能量级。典型曲线：低→中→高→低→最高→低
- **Chorus 必须是能量峰值**：确保副歌和主歌之间有显著的编曲差异
- **Bridge 通常是"呼吸空间"**：在两次 Chorus 之间提供反差

#### Step 2b: Derive Prompt from Blueprint

将蓝图中的信息转化为 prompt。好的 prompt 需要**同时描述整体基调和段落间的动态变化**。

**Prompt construction formula:**
```
[整体风格/BPM] + [人声描述 + 段落间变化] + [核心乐器] + [动态弧线描述] + [声场/制作特点]
```

**Example** (based on the 杭州 blueprint above):
```
A poetic and cinematic Chinese folk pop at 78 BPM, featuring a tender female vocal that transitions from intimate whispering in the verses to powerful soaring belting in the choruses with layered harmonies. The arrangement builds from a solo guzheng intro, gradually adding dizi (bamboo flute), pipa, and erhu through the verses, swelling to a full orchestral "wall of sound" with strings and percussion in the choruses, before retreating to a quiet guzheng outro. The production shifts from a dry, intimate space in the verses to a wide, reverberant arena soundscape in the choruses.
```

Key: The prompt explicitly describes **what changes between sections** — not just a flat list of attributes.

#### Step 2c: Write Lyrics with Section Directions

Write lyrics using **annotated structure tags** and **parenthetical directions** to reinforce the blueprint:

```
[Intro]
（古筝琶音，空灵悠远）

[Verse 1: 温柔低吟]
西湖 烟雨 朦胧了 谁的眼
断桥 残雪 化作 心头的暖

[Verse 2: 情感渐浓]
（笛声加入，轻柔的鼓点）
三潭 映月 点亮了 千年夜
灵隐 钟声 唤醒 梦中的蝶

[Pre Chorus: 情绪递进]
（弦乐渐强 / Rising strings）
这片土地 承载了 多少故事
每一寸 都是 我的根

[Chorus: 大气爆发]
（Full band kicks in / 全编制爆发）
杭州 我的杭州
你是 我心中 永远的歌
...

[Bridge: 回归平静]
（Music drops to piano and guzheng only / 仅剩钢琴与古筝）
闭上眼 你还在那里
...

[Chorus: 最终高潮]
（Maximum energy / 最高能量，加入合唱层）
杭州 我的杭州
...

[Outro: 渐弱收尾]
（古筝独奏，渐弱 / Guzheng solo, fading out）
```

#### Step 2d: Present Complete Draft

Combine all above into the final presentation:

```
📋 **生成方案**

**模式**：Standard Song

🎼 **歌曲蓝图**：
[the blueprint table]

**Prompt**：
[the full prompt — with dynamic arc description]

**歌词**：
[the full lyrics — with annotated tags and parenthetical directions]

**说明**：[1-2 sentences on creative choices]

---
请确认是否满意，或告诉我需要调整的地方（如某段落的情绪、乐器、歌词等）。
```

**Rules:**
- **Always create the blueprint first**, then derive prompt and lyrics from it
- Prompt must describe **section transitions**, not just a flat style
- Lyrics must use **annotated structure tags** (e.g., `[Chorus: 大气爆发]`) and **parenthetical directions** (e.g., `（Full band kicks in）`) to control each section's sound
- Show the complete blueprint, prompt, and lyrics — never hide details
- Wait for explicit user confirmation before proceeding to Step 3

### Step 3: Generate Music

After user confirms (or after applying their revisions and getting re-confirmation):

1. Determine the output file name from context (e.g., `./audio/杭州之歌.mp3`)
2. Run the generation command:

```bash
python scripts/generate_music.py \
  --lyrics "<final_lyrics>" \
  --prompt "<final_prompt>" \
  --output ./audio/<filename>.mp3
```

For instrumental mode, add `--is-instrumental true` and omit `--lyrics`.
For auto-lyrics mode, add `--lyrics-optimizer true` and omit `--lyrics`.

3. Inform user that generation is in progress (API call may take 30-120 seconds)

### Step 4: Post-Generation Feedback

After the audio file is generated:

1. Tell the user the file location and invite them to listen
2. Ask for feedback:

```
🎵 音乐已生成！文件保存在：`./audio/<filename>.mp3`

请试听后告诉我你的感受：
- ✅ 满意，完成
- 🔄 需要调整（请告诉我具体想改什么，比如节奏太快、想换个风格、歌词某处要改等）
```

3. If user requests changes:
   - Analyze what needs modification (prompt, lyrics, or both)
   - Return to **Step 2** with the revised draft
   - Repeat until user is satisfied

**Common revision patterns:**

| User feedback | Action |
|---------------|--------|
| "节奏太快/太慢" | Adjust BPM in prompt |
| "风格不对" | Revise