skywork-music-maker

# Skywork Music Maker (Mureka API)

Generate professional-quality music using the Mureka API at `https://api.mureka.ai`. This skill covers the **complete music production workflow**: lyrics writing → song/instrumental generation.

## First-Time Setup

Before running any API command, check if `MUREKA_API_KEY` is set. If not, guide the user to get an API key at https://platform.mureka.ai/ (register → API Keys → generate key → `export MUREKA_API_KEY="..."`), then STOP — do not attempt any API calls until the key is configured.

---

## Smart Prompt Conversion (CRITICAL WORKFLOW)

**Default behavior**: When the user doesn't specify song type, always generate a **song with lyrics** (use `mureka.py song`). Only use `mureka.py instrumental` when the user explicitly asks for instrumental, BGM, background music, or "no vocals".

**Output defaults**: Use mp3 format unless the user requests otherwise. The `--output` flag specifies a directory — the script creates it and saves all results inside (audio files + `lyrics.txt` for songs). If the user doesn't specify a location, choose a user-friendly path with a descriptive folder name based on the song theme (e.g., `summer_pop_song/`).

When users provide music descriptions in **natural language** (in any language), you MUST convert them to structured Mureka API prompts using this workflow:

### Conversion Process

**User Input Examples:**
- "upbeat pop song, female vocals, guitar, perfect for summer"
- "sad piano ballad about lost love"
- "epic orchestral music for a fantasy game"
- "traditional Chinese music with bamboo flute and zither, misty atmosphere"

**Your Task:**
1. **Extract structured parameters** using the extraction rules below
2. **Validate** the prompt meets quality standards (see Quality Checklist)
3. **Present to user** for confirmation before generating
4. **Run the generation** command with the structured prompt

### Parameter Extraction Rules

When users provide natural language music descriptions, directly extract and structure the following parameters:

**Required Parameters:**
- **genres**: music genres including fusion styles (e.g., Pop, Rock, Jazz, Pop Rap Fusion, Alternative Rock, Guofeng)
- **moods**: emotional tones (e.g., Happy, Melancholic, Energetic, Nostalgic, Bright)
- **instruments**: specific instruments (e.g., Piano, Guitar, Drums, Erhu, Guzheng, Synth Pads, Dizi)
- **rhythms**: rhythm characteristics (e.g., 4/4, Slow, Syncopated, Driving, Flowing)
- **vocals**: vocal attributes (e.g., Female, Husky, Whispered, Male, Soft, Clear) or "instrumental only"
- **key**: musical key if specified (e.g., C Major, A Minor, C# Major)
- **bpm**: beats per minute (e.g., 120) or tempo descriptor (e.g., "slow groove", "uptempo")
- **description**: concise summary (under 50 words) capturing mood progression, melody, harmony, timbre, texture, dynamics

**Extraction Instructions:**
1. **Translate non-English terms**: Convert ALL non-English musical terms to English while preserving cultural and musical meaning
2. **Preserve specificity**: Keep detailed information including specific styles, subgenres, and cultural context (e.g., "Chinese traditional guofeng" not just "Chinese music")
3. **Design dynamic arc**: Include mood progression where appropriate (e.g., "sparse opening → building tension → cathartic chorus")
4. **Infer intelligently**: Make reasonable assumptions based on genre conventions when parameters are not explicitly stated
5. **English output**: Final prompt string MUST be entirely in English

**Generate Structured Prompt:**
Combine all extracted parameters into a comprehensive, natural-flowing description that captures the essence of the user's vision.

### Quality Checklist (Validate BEFORE Generation)

Before running the generation command, verify the prompt meets these criteria:

**MUST HAVE:**
- [ ] Specific genre (NOT "pop song" but "synth-pop, 2020s")
- [ ] BPM or tempo descriptor (e.g., "120 BPM" or "slow groove")
- [ ] 3-5 instruments explicitly named
- [ ] Mood/emotion descriptors (2-3 words)
- [ ] Vocal style (or "instrumental only")
- [ ] Structure tags in lyrics: [Verse], [Chorus], [Bridge], [Outro]

**WATCH OUT FOR:**
- Vague terms: "nice", "good", "beautiful" → replace with specific descriptors
- Contradictions: "slow" + "energetic", "sad" + "uplifting" → pick one direction
- Too short: <50 chars → add more detail
- Long lyric lines: >10 words per line → split into shorter lines
- No dynamic arc: add mood progression (e.g., "sparse → building → full")

**AVOID:**
- Command verbs: "create a song" → use descriptions "upbeat pop song"
- Famous artist names: "sounds like Taylor Swift" → describe qualities instead
- Unrealistic combos: melody_id cannot combine with other control options

After validation, present the generated prompt to the user for confirmation before proceeding.

---

## Core Workflow: Production Pipeline

```
1. Conceptualize → User describes in natural language → YOU convert to structured prompt
2. Validate → Check prompt quality against Quality Checklist (see above)
3. Write Lyrics → Use lyrics/generate or write manually
4. Upload References → Optional: reference track, vocal sample, melody
5. Generate → Submit song/instrumental task (async) with validated prompt
6. Evaluate → Listen to all N choices, pick best
7. Iterate → Refine prompt based on what you heard
```

**Critical Steps:**
- **Step 1 is mandatory** when user provides natural language input (especially non-English)
- **Step 2 validation** prevents 80% of common generation failures
- **Step 3**: Read `references/prompt_guide.md` for prompt crafting examples, lyrics structure rules (line length, syllable count, rhyme patterns, hook writing), and iteration best practices
- **Do NOT skip conceptualization** — jumping straight to generation without a clear concept is the #1 reason for generic results

**Your Role as AI Assistant:**
1. Convert user's natural language → structured Mureka prompt (using Smart Prompt Conversion)
2. Vali