skills/frontend-dev/references/minimax-music-guide.md

Music Generation Guide

CLI Usage

# Instrumental (no vocals)
python scripts/minimax_music.py --prompt "Jazz piano, smooth, relaxing" --instrumental -o jazz.mp3

# With custom lyrics
python scripts/minimax_music.py --prompt "Indie folk, melancholic" --lyrics "[verse]\nStreetlights flicker\nOn empty roads" -o song.mp3

# Auto-generate lyrics from prompt
python scripts/minimax_music.py --prompt "Upbeat pop, energetic, summer vibes" --auto-lyrics -o pop.mp3

# From lyrics file
python scripts/minimax_music.py --prompt "Soulful blues, rainy night" --lyrics-file lyrics.txt -o blues.mp3

# Custom audio settings
python scripts/minimax_music.py --prompt "Lo-fi beats" --instrumental -o lofi.wav --format wav --sample-rate 44100 --bitrate 256000

Programmatic Usage

from minimax_music import generate_music

# Instrumental
result = generate_music(prompt="Jazz piano, smooth", is_instrumental=True)
with open("jazz.mp3", "wb") as f:
    f.write(result["audio_bytes"])

# With lyrics
result = generate_music(
    prompt="Indie folk, acoustic guitar",
    lyrics="[verse]\nWalking through the rain\n[chorus]\nI'll find my way home",
)

# Auto-generate lyrics
result = generate_music(
    prompt="Upbeat pop, summer anthem",
    lyrics_optimizer=True,
)

# Access metadata
print(f"Duration: {result['duration']}ms")
print(f"Sample rate: {result['sample_rate']}")
print(f"Size: {result['size']} bytes")

Models

Model	Features
music-2.5+	Recommended. Supports instrumental mode, complete song structures, hi-fi audio
music-2.5	Standard model. No instrumental mode

Prompt Writing

The prompt parameter describes music style using comma-separated descriptors:

Category	Examples
Genre	Blues, Pop, Rock, Jazz, Electronic, Hip-hop, Folk, Classical
Mood	Soulful, Melancholy, Upbeat, Energetic, Peaceful, Dark, Nostalgic
Scenario	Rainy night, Summer day, Road trip, Late night, Sunrise
Instrumentation	Electric guitar, Piano, Acoustic, Synthesizer, Strings
Vocal type	Male vocals, Female vocals, Soft vocals, Powerful vocals
Tempo	Slow tempo, Fast tempo, Mid-tempo, Relaxed

Example prompts:

"Soulful Blues, Rainy Night, Melancholy, Male Vocals, Slow Tempo"
"Upbeat Pop, Summer Vibes, Female Vocals, Energetic, Synth-heavy"
"Lo-fi Hip-hop, Chill, Relaxed, Instrumental, Piano samples"
"Cinematic Orchestral, Epic, Building tension, Strings and Brass"

Lyrics Format

Use structure tags in brackets to organize song sections:

Structure Tags

Tag	Purpose
[Intro]	Opening section (can be instrumental)
[Verse] / [Verse 1]	Story/narrative sections
[Pre-Chorus]	Build-up before chorus
[Chorus]	Main hook, typically repeated
[Post Chorus]	Extension after chorus
[Bridge]	Contrasting section near end
[Interlude]	Instrumental break
[Solo]	Instrumental solo (add direction: "slow, bluesy")
[Outro]	Closing section
[Break]	Short pause or transition
[Hook]	Catchy repeated phrase
[Build Up]	Tension building section
[Inst]	Instrumental section
[Transition]	Section change

Backing Vocals & Directions

Use parentheses for backing vocals or performance notes:

(Ooh, yeah)
(Harmonize)
(Whispered)
(Fade out...)

Example Lyrics

[Intro]
(Soft piano)

[Verse 1]
Streetlights flicker on empty roads
The rain keeps falling, the wind still blows
I'm walking home with nowhere to go
Just memories of what I used to know

[Pre-Chorus]
And I can feel it coming back to me
(Coming back to me)

[Chorus]
Under the neon lights tonight
I'm searching for what feels right
(Oh, feels right)
These city streets will guide me home
I'm tired of feeling so alone

[Verse 2]
Coffee shops and midnight trains
The faces change but the feeling remains
...

[Bridge]
Maybe tomorrow will be different
Maybe I'll finally understand
(Understand...)

[Solo]
(Slow, mournful, bluesy guitar)

[Outro]
(Fade out...)
Under the neon lights...

Audio Settings

Parameter	Options	Default	Notes
format	mp3, wav, pcm	mp3	WAV for highest quality
sample_rate	16000, 24000, 32000, 44100	44100	44100 recommended
bitrate	32000, 64000, 128000, 256000	256000	Higher = better quality

Generation Modes

1. Instrumental Only

python scripts/minimax_music.py --prompt "Ambient electronic, space theme" --instrumental -o ambient.mp3

• Requires music-2.5+ model
• Only prompt needed, no lyrics

2. With Custom Lyrics

python scripts/minimax_music.py --prompt "Pop ballad, emotional" --lyrics "[verse]\nYour lyrics here" -o ballad.mp3

• Provide both prompt (style) and lyrics (words + structure)

3. Auto-Generated Lyrics

python scripts/minimax_music.py --prompt "Rock anthem about freedom" --auto-lyrics -o rock.mp3

• System generates lyrics from prompt
• Good for quick generation when lyrics aren't critical

Limits

• Prompt: max 2,000 characters
• Lyrics: 1–3,500 characters
• Duration: ~25-30 seconds per generation (varies)
• URL expiration: 24 hours (when using URL output mode)

Best Practices

1. Layer style descriptors — Combine genre + mood + instrumentation for precise results
2. Use structure tags — Even simple [verse] [chorus] improves arrangement
3. Include backing vocal cues — (Ooh), (Yeah) add production polish
4. Match prompt to lyrics mood — Conflicting prompt/lyrics produce inconsistent results
5. Instrumental for backgrounds — Use --instrumental for BGM, avoiding vocal distractions
6. High bitrate for production — Use 256000 for final assets, lower for drafts

Common Use Cases

Use Case	Command
Background music	--prompt "Lo-fi, calm, ambient" --instrumental
Landing page hero	--prompt "Cinematic, inspiring, building" --instrumental
Podcast intro	--prompt "Upbeat, energetic, short" --instrumental
Demo song	--prompt "Pop, catchy" --auto-lyrics
Custom jingle	--prompt "Happy, bright, corporate" --lyrics "[hook]\nYour brand name"

Error Handling

Error Code	Meaning	Solution
1002	Rate limit	Wait and retry
1004	Auth failed	Check API key
1008	Insufficient balance	Top up account
1026	Content flagged	Rephrase prompt/lyrics
2013	Invalid parameters	Check prompt/lyrics length