xiaoshuai/qwen-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): 添加 minimax-music-gen Skill

Browse Source
This commit is contained in:
宋康帅
2026-05-13 00:38:22 +08:00
parent d6343b4061
commit 6daff302d4
2 changed files with 537 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
minimax-music-gen/SKILL.md
+404
View File
@@ -0,0 +1,404 @@
---
name: minimax-music-gen
description: >
Use when user wants to generate music, songs, or audio tracks. Triggers on any request
involving music creation, song writing, lyrics generation, audio production, or covers.
Also triggers when user provides lyrics and wants them turned into a song, or describes
a mood/scene and wants background music. Supports multilingual triggers — match equivalent
phrases in any language. Do NOT use for music playback of existing files, music theory
questions, or music recommendation without generation.
license: MIT
metadata:
version: "1.1"
category: creative
---
# MiniMax Music Generation Skill
Generate songs (vocal or instrumental) using the MiniMax Music API. Supports two creation
modes: **Basic** (one-sentence-in, song-out) and **Advanced Control** (edit lyrics, refine
prompt, plan before generating).
## Prerequisites
- **mmx CLI** (required): Music generation uses the `mmx` command-line tool.
**Check if installed:**
```bash
command -v mmx && mmx --version || echo "mmx not found"
```
**Install (requires Node.js):**
```bash
npm install -g mmx-cli
```
**Authenticate (first time only):**
```bash
mmx auth login --api-key <your-minimax-api-key>
```
The API key can be obtained from [MiniMax Platform](https://platform.minimaxi.com/).
Credentials are saved to `~/.mmx/credentials.json` and persist across sessions.
**Verify:**
```bash
mmx quota show
```
- **Audio player** (recommended): `mpv`, `ffplay`, or `afplay` (macOS built-in) for local
playback. `mpv` is preferred for its interactive controls.
## CLI Tool
This skill uses the `mmx` CLI for all music generation:
- **Music Generation**: `mmx music generate` — model: `music-2.6-free`
- Supports `--lyrics-optimizer` to auto-generate lyrics from prompt
- Supports `--instrumental` for instrumental tracks
- Supports `--lyrics` for user-provided lyrics
- Structured params: `--genre`, `--mood`, `--vocals`, `--instruments`, `--bpm`, `--key`, `--tempo`, `--structure`, `--references`
- **Cover**: `mmx music cover` — model: `music-cover-free`
- Takes reference audio via `--audio-file <path>` or `--audio <url>`
- `--prompt` describes the target cover style
**Agent flags**: Always add `--quiet --non-interactive` when calling mmx from agents.
**Pipeline**:
- Vocal: `User description -> mmx music generate --lyrics-optimizer -> MP3`
- Instrumental: `User description -> mmx music generate --instrumental -> MP3`
- Cover: `Source audio + style -> mmx music cover -> MP3`
## Storage
All generated music is saved to `~/Music/minimax-gen/`. Create the directory if it doesn't
exist. Files are named with a timestamp and a short slug derived from the prompt:
`YYYYMMDD_HHMMSS_<slug>.mp3`
---
## Language & Interaction
Detect the user's language from their first message and respond in that language for the
entire session. This applies to all interaction text, questions, confirmations, and feedback
prompts.
**User-facing text localization rule**:
- ALL text shown to the user — including preview labels, field names, confirmations, status
messages, playback info, feedback prompts, **and the prompt/description preview** — MUST
be fully translated into the user's language.
- The **API prompt** sent to the model should always be written in English for best
generation quality. However, when previewing the prompt to the user, show a localized
description in the user's language instead of the raw English prompt. The English prompt
is an internal implementation detail — the user does not need to see it.
- The templates below are written in English as reference. At runtime, translate every label
and message into the user's detected language.
**Lyrics language rule**:
- Default lyrics language = the user's language. A Chinese-speaking user gets Chinese lyrics;
an English-speaking user gets English lyrics.
- Only generate lyrics in a different language if the user **explicitly** requests it.
- When a different lyrics language is needed, embed it naturally into the vocal or genre
description in the prompt. For example, instead of appending "with Korean lyrics", use
"featuring a Korean female vocalist" or specify a genre that implies the language (e.g.,
"K-pop", "J-rock", "Mandopop", "Latin pop").
---
## Workflow
### Step 0: Detect Intent
Parse the user's message to determine:
1. **Song category**: vocal (with lyrics), instrumental (no vocals), or cover
2. **Creation mode preference**: did they provide detailed requirements (Advanced) or a
casual one-liner (Basic)?
If ambiguous, ask using this decision tree:
```
Q1: What type of music?
- Vocal (with lyrics)
- Instrumental (no vocals)
- Cover
Q2: Creation mode?
- Basic — one-line description, auto-generate
- Advanced — edit lyrics, refine prompt, plan
```
If the user gives a clear one-liner like "make me a sad piano piece", skip the questions —
infer instrumental + basic mode and proceed.
---
### Step 1: Basic Mode
**Goal**: User provides a short description, the skill auto-generates everything, then calls
the API.
1. **Expand the description into a prompt**: Take the user's one-liner and expand it into a
rich music prompt. Refer to the **Prompt Writing Guide** appendix at the end of this
document for style vocabulary, genre/instrument references, and prompt structure.
**The API prompt should always be written in English** for best generation quality,
regardless of the user's language.
Follow this pattern:
```
A [mood] [BPM optional] [genre] song, featuring [vocal description],
about [narrative/theme], [atmosphere], [key instruments and production].
```
2. **Show the user a preview** before generating. Translate all labels AND the prompt
description into the user's language. The English prompt is only used internally when
calling the API — the user should never see it. Example template (English reference —
localize everything at runtime):
```
About to generate:
Type: Vocal / Instrumental
Description: indie folk, melancholy, acoustic guitar, gentle female voice
Lyrics: Auto-generated (--lyrics-optimizer)
Confirm? (press enter to confirm, or tell me what to change)
```
3. **Call mmx**: Generate the music directly.
---
### Step 2: Advanced Control Mode
**Goal**: User has full control over every parameter before generation.
1. **Lyrics phase**:
- If user provided lyrics: display them formatted with section markers, ask for edits.
The final lyrics will be passed via `--lyrics` to mmx.
- If user has a theme but no lyrics: will use `--lyrics-optimizer` to auto-generate.
- Support iterative editing: "change the second chorus" -> only rewrite that section.
- User can also write lyrics themselves and pass via `--lyrics`.
2. **Prompt phase**:
- Generate a recommended prompt based on the lyrics' mood and content.
- Present it as editable tags the user can add/remove/modify.
- Refer to the **Prompt Writing Guide** appendix for the full vocabulary.
3. **Advanced planning** (optional, offer but don't force):
- Song structure: verse-chorus-verse-chorus-bridge-chorus or custom
- BPM suggestion (encode in prompt as tempo descriptor)
- Reference style: "something like X style" -> map to prompt tags
- Vocal character description
4. **Final confirmation**: Show complete parameter summary, then generate.
---
### Step 3: Call mmx
Generate music using the mmx CLI:
**Vocal with auto-generated lyrics:**
```bash
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
```
**Vocal with user-provided lyrics:**
```bash
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
```
**Instrumental (no vocal):**
```bash
mmx music generate \
--prompt "<prompt>" \
--instrumental \
--genre "<genre>" --mood "<mood>" --instruments "<instruments>" \
--out ~/Music/minimax-gen/<filename>.mp3 \
--quiet --non-interactive
```
Use structured flags (`--genre`, `--mood`, `--vocals`, `--instruments`, `--bpm`, `--key`,
`--tempo`, `--structure`, `--references`, `--avoid`, `--use-case`) to give the API
fine-grained control instead of cramming everything into `--prompt`.
Display a progress indicator while waiting. Typical generation takes 30-120 seconds.
---
### Step 4: Playback
After generation, detect an available audio player and play the file.
**Detect player:**
```bash
command -v mpv || command -v ffplay || command -v afplay
```
**Play based on detected player (in priority order):**
| Player | Command | Controls |
|--------|---------|----------|
| `mpv` (preferred) | `mpv --no-video ~/Music/minimax-gen/<filename>.mp3` | space = pause/resume, q = quit, left/right = seek |
| `ffplay` | `ffplay -nodisp -autoexit ~/Music/minimax-gen/<filename>.mp3` | q = quit |
| `afplay` (macOS) | `afplay ~/Music/minimax-gen/<filename>.mp3` | Ctrl+C = stop |
| None found | Do not attempt playback | Show file path only |
After starting playback, tell the user (localize all text):
```
Now playing: <filename>.mp3
Saved to: ~/Music/minimax-gen/<filename>.mp3
```
Do NOT show playback controls (e.g. keyboard shortcuts) — they don't work in this
environment since the player runs in the background.
If no player is found (localize all text):
```
No audio player detected.
File saved to: ~/Music/minimax-gen/<filename>.mp3
Tip: Install mpv for the best playback experience (brew install mpv).
```
---
### Step 5: Feedback & Iteration
After playback, ask for feedback:
```
How was this song?
1. Love it, keep it!
2. Not quite, adjust and regenerate
3. Fine-tune lyrics/style then regenerate
4. Don't want it, start over
```
Based on feedback:
- **Satisfied**: Done. Mention the file path again.
- **Adjust & regenerate**: Ask what to change (prompt? lyrics? style?), apply edits,
re-run generation. Keep the old file with a `_v1` suffix for comparison.
- **Fine-tune**: Enter Advanced Control Mode with the current parameters pre-filled.
- **Delete & restart**: Remove the file, go back to Step 0.
---
## Cover Mode
Generate a cover version of a song based on reference audio. Model: `music-cover-free`.
**Reference audio requirements**: mp3, wav, flac — duration 6s to 6min, max 50MB.
If no lyrics are provided, the original lyrics are extracted via ASR automatically.
### Workflow
When the user selects Cover mode:
1. Ask for the source audio — a local file path or URL
2. Ask for the target cover style (e.g., "acoustic cover, stripped-down, intimate vocal")
3. Optionally ask for custom lyrics or lyrics file
### Commands
**Cover from local file:**
```bash
mmx music cover \
--prompt "<cover style description>" \
--audio-file <source.mp3> \
--out ~/Music/minimax-gen/<filename>.mp3 \
--quiet --non-interactive
```
**Cover from URL:**
```bash
mmx music cover \
--prompt "<cover style description>" \
--audio <source_url> \
--out ~/Music/minimax-gen/<filename>.mp3 \
--quiet --non-interactive
```
**With custom lyrics (text):**
```bash
mmx music cover \
--prompt "<style>" \
--audio-file <source.mp3> \
--lyrics "<custom lyrics>" \
--out ~/Music/minimax-gen/<filename>.mp3 \
--quiet --non-interactive
```
**With custom lyrics (file):**
```bash
mmx music cover \
--prompt "<style>" \
--audio-file <source.mp3> \
--lyrics-file <lyrics.txt> \
--out ~/Music/minimax-gen/<filename>.mp3 \
--quiet --non-interactive
```
### Optional flags
| Flag | Description |
|------|-------------|
| `--seed <number>` | Random seed 0-1000000 for reproducible results |
| `--channel <n>` | `1` (mono) or `2` (stereo, default) |
| `--format <fmt>` | `mp3` (default), `wav`, `pcm` |
| `--sample-rate <hz>` | Sample rate (default: 44100) |
| `--bitrate <bps>` | Bitrate (default: 256000) |
### After generation
Proceed with normal playback and feedback flow (Step 4 & 5).
---
## Error Handling
| Error | Action |
|-------|--------|
| mmx not found | `npm install -g mmx-cli` |
| mmx auth error (exit code 3) | `mmx auth login` |
| Quota exceeded (exit code 4) | Report quota limit, suggest waiting or upgrading |
| API timeout (exit code 5) | Retry once, then report failure |
| Content filter (exit code 10) | Adjust prompt to avoid filtered content |
| Invalid lyrics format | Auto-fix section markers, warn user |
| No audio player found | Save file and tell user the path, suggest installing mpv |
| Network error | Show error detail, suggest checking connection |
---
## Important Notes
- **Never reproduce copyrighted lyrics.** When doing covers, always write original lyrics
inspired by the song's theme. Explain this to the user.
- **Prompt language**: The API prompt works best with English tags. Chinese tags are also
acceptable. Mixing is OK.
- **Section markers in lyrics**: The API recognizes `[verse]`, `[chorus]`, `[bridge]`,
`[outro]`, `[intro]`. Always include them when providing `--lyrics`.
- **File management**: If `~/Music/minimax-gen/` has more than 50 files, suggest cleanup
when starting a new session.
- **Structured params**: Prefer using `--genre`, `--mood`, `--vocals`, `--instruments`,
`--bpm` etc. over embedding everything in `--prompt`. This gives the API better control.
- **Lyrics language via style**: When the user wants lyrics in a specific language, express
it through the vocal description or genre (e.g., "Japanese female vocalist", "Mandopop
ballad") rather than appending a language directive to the prompt.
---
## Appendix: Prompt Writing Guide
See [references/prompt_guide.md](references/prompt_guide.md) for the complete prompt writing guide,
including genre/vocal/instrument references and BPM tables.
minimax-music-gen/references/prompt_guide.md
+133
View File
@@ -0,0 +1,133 @@
# Prompt Writing Guide
This reference helps construct high-quality music generation prompts.
## Core Principle
**Write prompts as vivid English sentences, not comma-separated tags.**
The API responds best to descriptive, narrative-style prompts that paint a complete picture
of the song. Each prompt should read like a creative brief for a musician.
## Prompt Structure
A complete prompt follows this sentence pattern:
```
A [mood/emotion] [BPM optional] [genre + sub-genre] [song/piece/track].
[Vocal description OR "Instrumental with..." description].
[Narrative/theme — what the song is about].
[Atmosphere/scene details].
[Key instruments and production elements].
```
**Vocal Track Example:**
```
A melancholic yet defiant Pop-House song, featuring emotional vocals, about
lighting a torch in the cold dark night as a form of romantic rebellion,
energetic rhythm with synth elements.
```
**Instrumental Example:**
```
A warm and uplifting 100 BPM indie folk instrumental piece, evoking a sunny
afternoon stroll through a small town market, featuring bright acoustic guitar
fingerpicking, gentle ukulele strums, light hand claps, and a whistled melody
that feels like pure contentment.
```
## How to Build a Prompt Step by Step
**1. Open with mood + genre (required)**
| Pattern | Example |
|---------|---------|
| Single mood | "A melancholic R&B song" |
| Contrasting moods | "A melancholic yet defiant Pop-House song" |
| With BPM | "A smoky 74 BPM Neo-Soul fusion" |
| With era/region | "A laid-back 90 BPM Island Reggae" |
| Genre blend | "An Avant-Garde Jazz and Neo-Soul fusion" |
**2. Describe the vocals (for vocal tracks)**
Good vocal descriptions:
- "featuring smooth emotional vocals"
- "Vocals: Ultra-low, gravelly baritone with authentic phrasing"
- "Vocals: Sultry, sophisticated male baritone with smooth jazz inflections and breathy delivery"
- "Vocals: Ethereal, crystal-clear Enya-style vocals with lush reverb"
- "Vocals: Relaxed, soul-flavored vocals with ad-libs and melodic scats"
Bad (too vague): "female vocal"
**3. Add narrative/theme (recommended)**
- "about lighting a torch in the cold dark night as a form of romantic rebellion"
- "about letting go of perfectionism and embracing your true self like flowing water"
For instrumentals, describe the scene: "evoking a sunrise drive along a coastal highway"
**4. Set the mood/atmosphere (recommended)**
- "bittersweet but healing mood"
- "empowering and self-loving mood"
**5. Specify production elements (recommended)**
- "mellow beats with lo-fi elements"
- "featuring a warm fretless bassline, shimmering Rhodes piano, and brushed jazz drums"
## Genre Reference
| Category | Genres |
|----------|--------|
| Pop & Dance | Pop, Dance Pop, Electropop, Synth-pop, Dream Pop, K-pop, J-pop, C-pop, City Pop, House, Future Bass, EDM |
| Rock & Alt | Rock, Indie Rock, Pop Rock, Post-Rock, Shoegaze, Punk, Metal, Alternative |
| R&B/Soul/Funk | R&B, Neo-Soul, Contemporary R&B, Funk, Gospel, Soul |
| Hip-Hop | Hip-Hop, Trap, Boom Bap, Lo-fi Hip-Hop, Cloud Rap, Drill, Afrobeats |
| Electronic | Ambient, Techno, Drum and Bass, Chillwave, Vaporwave, Amapiano |
| Folk/Acoustic | Folk, Indie Folk, Country, Chinese Traditional, Celtic Folk |
| Jazz/Blues | Jazz, Smooth Jazz, Jazz Fusion, Bossa Nova, Blues, Avant-Garde Jazz |
| Classical | Classical, Orchestral, Cinematic, Film Score, Epic, Neoclassical, Piano Solo |
| World | Reggae, Latin, Waltz, Tango, Flamenco |
## Vocal Style Reference
| Style | Prompt phrase |
|-------|--------------|
| Smooth & emotional | "smooth emotional vocals" |
| Raw & unpolished | "raw, unpolished vocals shifting between whispers and screams" |
| Breathy & intimate | "breathy delivery with intimate phrasing" |
| Powerful & soulful | "powerful soulful vocals with gospel inflections" |
| Sultry & sophisticated | "sultry, sophisticated baritone with jazz inflections" |
| Ethereal & clear | "ethereal, crystal-clear vocals with lush reverb" |
| Aggressive & intense | "aggressive vocal delivery with rhythmic intensity" |
## Instrument & Production Reference
| Category | Examples |
|----------|---------|
| Strings & Guitar | acoustic guitar fingerpicking, electric guitar riffs, fretless bass, violin, cello, erhu, guzheng, pipa |
| Keys & Synth | piano, Rhodes piano, synth pad, synth lead, arpeggiator, music box, organ |
| Drums & Percussion | brushed jazz drums, electronic drums, 808 hi-hats, trap percussion, cajon, bongos |
| Wind & Brass | saxophone, trumpet, flute, harmonica, bamboo flute, xiao |
| Texture & Effects | vinyl crackle, tape hiss, ambient pads, glitch elements, rain sounds |
## BPM Reference
| Feel | BPM | Use in prompt |
|------|-----|---------------|
| Very slow, meditative | 40-60 | "a meditative 50 BPM..." |
| Slow ballad | 60-80 | "a slow 70 BPM ballad..." |
| Mid-tempo groove | 80-110 | "a groovy 95 BPM..." |
| Upbeat, energetic | 110-130 | "an upbeat 120 BPM..." |
| Fast, driving | 130-160 | "a driving 140 BPM..." |
## Tips for High-Quality Prompts
1. **Write sentences, not tag lists**: "A melancholic R&B song about..." beats "R&B, sad, slow, piano".
2. **Be vivid and specific**: "salvaging memory fragments in space-time" > "sad memories".
3. **Describe vocals as a character**: "Sultry baritone with jazz inflections" not "male vocal".
4. **Include a scene or vibe**: "A high-end rooftop lounge at night" gives the model a coherent world.
5. **Mix detail levels**: Specify 2-3 key instruments precisely, leave the rest to the model.
6. **English prompts work best**: Chinese scene descriptions can be mixed in for flavor.
7. **For instrumentals**: Replace vocal descriptions with instrument focus and scene narrative.