217 lines
6.5 KiB
Markdown
217 lines
6.5 KiB
Markdown
# Music Generation Guide
|
||
|
||
## CLI Usage
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```python
|
||
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
|
||
```bash
|
||
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
|
||
```bash
|
||
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
|
||
```bash
|
||
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 |
|