mm-music-maker

# MiniMax Music Maker

Use this skill to generate music with MiniMax's Music Generation API. All usage and outputs are designed for **music-2.5** unless specified otherwise.

## Quick start

1) Set the API key:
```bash
export MINIMAX_MUSIC_API_KEY="your_api_key"
```

2) Generate music from lyrics (and optional prompt):
```bash
python scripts/generate_music.py \
  --lyrics "[Verse]\n...\n[Chorus]\n..." \
  --prompt "indie folk, melancholic, introspective" \
  --output ./output.mp3
```

## Script location

- `scripts/generate_music.py` — main generator (lyrics + prompt → audio)
- `scripts/utils_audio.py` — hex decoding + save helpers

## References

Read **references/minimax_music_api.md** for:
- Endpoint, auth header, payload schema
- Required/optional fields
- Output formats (hex/url) and constraints

## Core Modes

This skill supports **3 generation modes**:

### 1. Standard Song (with lyrics)
- User provides or wants lyrics + music
- Use structured lyrics with prompt for style

### 2. Pure Music (Instrumental)
- User requests: "纯音乐", "纯音乐，无人声", "pure music", "instrumental"
- No lyrics, just instrumental arrangement
- See "Pure Music Generation" section below

### 3. Melodic Chanting/Humming
- User requests: "哼唱", "吟唱", "humming", "chanting"
- Music with vocal syllables instead of full lyrics
- See "Melodic Chanting Generation" section below

## Notes

- `lyrics` is **required** by the API.
- `prompt` is optional for `music-2.5`.
- `output_format` defaults to `hex` (inline audio). Use `url` if you prefer a download URL.
- URLs expire (24h). Download immediately if using `url`.

## Prompt crafting (Important)

**Core Principles**: Use "descriptions" instead of "commands", keep it structured, clear, and parseable.

### Required Elements (Recommended)
- **Genre/Subgenre** (with era or region)
- **Mood/Emotion** (2-3 emotional descriptors)
- **Tempo/BPM** (specify BPM if possible)
- **Key Instruments** (3-5 key instruments/timbres)
- **Vocals** (vocal typ...