# Examples

Use `music-craft-minimax` when the user provides audio, wants melody preservation, or needs the richer MiniMax-specific workflows.

For workflow details, see [`cover-workflow.md`](./cover-workflow.md), [`mashup-workflow.md`](./mashup-workflow.md), and [`emotion-analysis.md`](./emotion-analysis.md).

| Example | Use MiniMax because | First response/questions | Workflow shape |
|---|---|---|---|
| Cover from audio | The user wants the same melody with a new style, and they have source audio. | Ask for the audio file or a usable URL, plus the target style and whether lyrics should change. | `analyze audio -> cover preprocess -> generate cover` |
| YouTube cover with blocked download fallback | The user only has a YouTube link and the platform blocks direct download. | Ask for the link, then be ready to fall back to a local download or trimmed file workflow. | `attempt download -> if blocked, request file or alternate source -> preprocess -> generate` |
| Two-song mashup | The user wants Song A's content with Song B's style. | Ask which song is the content source, which is the style source, and whether either one is audio or name-only. | `analyze both sources -> extract lyrics/emotion/style -> build mashup prompt -> generate` |
| Lyrics API edit/generation | The user wants to rewrite, fix, translate, or generate lyrics before cover or standard generation. | Ask for the target language, section structure, and whether the lyrics are original, translated, or edited. | `generate or edit structured lyrics -> attach to cover or standard generation` |
| Emotion-analysis-to-prompt | The user wants the music to match a specific emotional arc from a vocal or song analysis. | Ask what emotion should lead the track and whether the arc should stay constant or evolve. | `analyze emotion -> convert to prompt descriptors -> apply to cover or standard generation` |
| Linter catch: prompt BPM vs `--bpm` conflict | The prompt says `80 BPM` but the `mmx` flags file says `--bpm 120`. | Treat the flag as the authoritative value only if the user confirms it; otherwise fix the prompt or the flag so they match. | `lint prompt + flags -> resolve bpm conflict -> generate` |
| Linter catch: key conflict | The prompt says `E minor` but the flags file says `--key C major`. | Pick one source of truth (prompt for descriptive content, flags for numeric facts) and re-align. | `lint prompt + flags -> resolve key conflict -> generate` |
| Linter catch: conflicting cover/style transfer | The user asks for both "make it a cover" and "do a style transfer" in the same request. | Ask the user to pick one: cover preserves melody, style transfer replaces it. | `surface blocker -> clarify intent -> route to minimax_cover or minimax_style_transfer` |
| Revision after a weak generation | The first generation was muddy, lost the melody, or had a flat chorus. | Identify the failure signature (see SKILL.md "Output Verification") and apply the matching revision template. | `identify signature -> apply revision template -> regenerate -> re-verify` |

Notes:
- This skill is the right choice when audio analysis matters.
- If the user has no audio and only wants a fresh song from text, route to the base skill instead.
- Use [`../scripts/lint_music_request.py`](../scripts/lint_music_request.py) when prompt text and `mmx` flags need a quick conflict check before generation. The linter returns a `retry_guidance` array with one hint per conflict.

## Canonical `mmx` Prompt Schema

When you build a prompt and an `mmx` flag set for MiniMax generation, use the canonical schema below. The schema has ten fields, each with a clear role. The linter cross-checks the prompt text against the flag values; the schema is the contract both sides agree on.

```yaml
mmx_prompt:
  intent: "cover"           # cover | mashup | style_transfer | emotion_prompt | standard
  source:
    type: "audio_file"      # audio_file | youtube_url | song_name
    path: "/tmp/song.wav"   # file path, URL, or song name
  target_style:
    genre: "french chanson"
    mood: "melancholic romantic"
    era: "1960s"
    reference: "Edith Piaf" # optional, for free-tool inference
  lyrics_policy: "original" # original | translated | rewritten | instrumental
  tempo: 80                 # BPM integer; aligns with --bpm
  key: "E minor"            # aligns with --key
  structure: "intro-verse-chorus-verse-chorus-bridge-chorus-outro"
                            # aligns with --structure
  vocal_delivery:
    mode: "vocal"           # vocal | instrumental
    timbre: "passionate"
    language: "french"
    range: "mezzo-soprano"  # optional
  mix:
    vocal_upfront: true
    stereo_width: "wide"
    density: "full"         # sparse | medium | full
    dynamics: "dynamic"     # monotone | medium | dynamic
  avoid: "sparse, a cappella, electronic, synth, autotune"
                            # aligns with --avoid
```

### Worked example: cover in a new style

```yaml
mmx_prompt:
  intent: "cover"
  source:
    type: "audio_file"
    path: "/tmp/non_je_ne_regrette_rien.ogg"
  target_style:
    genre: "reggaeton"
    mood: "energetic dramatic"
    era: "modern"
  lyrics_policy: "translated"  # French original -> Spanish translation
  tempo: 95
  key: "A minor"
  structure: "intro-verse-prechorus-chorus-verse-prechorus-chorus-bridge-chorus-outro"
  vocal_delivery:
    mode: "vocal"
    timbre: "passionate Spanish male"
    language: "spanish"
  mix:
    vocal_upfront: true
    stereo_width: "wide"
    density: "full"
    dynamics: "dynamic"
  avoid: "sparse, a cappella, ballad, soft, acoustic, english"
```

The corresponding `mmx` invocation:

```bash
mmx music cover \
  --prompt "Reggaeton cover, dembow rhythm, 808 sub-bass, synth pads, passionate Spanish male vocal, 95 BPM, A minor, intro-verse-prechorus-chorus-verse-prechorus-chorus-bridge-chorus-outro, dynamic contrast" \
  --audio-file /tmp/non_je_ne_regrette_rien.ogg \
  --lyrics "[Verse]\nNo, nada de nada\nNo, no lamento nada\n\n[Chorus]\nNi el bien que me hicieron\nNi el mal, todo me da igual..." \
  --genre "reggaeton" \
  --mood "energetic dramatic" \
  --vocals "passionate Spanish male vocal" \
  --bpm 95 \
  --key "A minor" \
  --structure "intro-verse-prechorus-chorus-verse-prechorus-chorus-bridge-chorus-outro" \
  --avoid "sparse, a cappella, ballad, soft, acoustic, english" \
  --model music-cover \
  --out /tmp/piaf_reggaeton.mp3
```

### Worked example: emotion-driven precision flags

```yaml
mmx_prompt:
  intent: "emotion_prompt"
  source:
    type: "audio_file"
    path: "/tmp/source.wav"
  target_style:
    genre: "synthwave"
    mood: "dark atmospheric hypnotic"
  lyrics_policy: "original"
  tempo: 110
  key: "A minor"
  structure: "intro-verse-prechorus-chorus-verse-chorus-bridge-chorus-outro"
  vocal_delivery:
    mode: "vocal"
    timbre: "breathy female with reverb"
    language: "english"
  mix:
    vocal_upfront: false
    stereo_width: "wide"
    density: "full"
    dynamics: "medium"
  avoid: "sparse, a cappella, acoustic, bright, cheerful, organic"
```

The corresponding `mmx` invocation:

```bash
mmx music generate \
  --prompt "Dark synthwave, retro 80s neon, urban nightscape, atmospheric pulsing" \
  --vocals "breathy female vocal with reverb" \
  --genre "synthwave" \
  --mood "dark atmospheric hypnotic" \
  --instruments "analog synth, drum machine, sub-bass, gated reverb drums, arpeggiator, pads" \
  --bpm 110 \
  --key "A minor" \
  --structure "intro-verse-prechorus-chorus-verse-chorus-bridge-chorus-outro" \
  --avoid "sparse, a cappella, acoustic, bright, cheerful, organic" \
  --model music-2.6 \
  --out /tmp/album_match.mp3
```

### Linter pass before generation

```bash
# 1. Save the prompt to a file
cat > /tmp/cover_prompt.txt <<'EOF'
Reggaeton cover, dembow rhythm, 808 sub-bass, synth pads, passionate Spanish male vocal, 95 BPM, A minor, intro-verse-prechorus-chorus-verse-prechorus-chorus-bridge-chorus-outro, dynamic contrast
EOF

# 2. Save the flags to a JSON file
cat > /tmp/cover_flags.json <<'EOF'
{
  "bpm": 95,
  "key": "A minor",
  "structure": "intro-verse-prechorus-chorus-verse-prechorus-chorus-bridge-chorus-outro",
  "vocals": "passionate Spanish male vocal",
  "language": "spanish",
  "avoid": "sparse, a cappella, ballad, soft, acoustic, english"
}
EOF

# 3. Run the linter
python3 scripts/lint_music_request.py --prompt-file /tmp/cover_prompt.txt --mmx-flags /tmp/cover_flags.json
# -> route: minimax_cover
# -> flag_conflicts: []
# -> retry_guidance: []
```

If the linter reports conflicts, follow the matching `retry_guidance` hint, re-save the files, and re-run until `flag_conflicts` is empty.