skills/kolbo/references/models/music.md

<!-- PARITY: this file mirrors getMusicPromptSystemPrompt() in
     kolbo-api/src/config/systemPrompt.js (lines ~1259–1371).
     When that function changes, update this file in the same session. -->

# Music — Prompt Rules (Suno-led)

Load this file when the user wants AI-generated **music** — full songs, lyrics, instrumentals, jingles, scores, soundtracks, lo-fi beats, trailers, ad music. Primarily Suno; the same craft applies to other music models. For TTS / voice cloning see `models/prompt-copilot.md`. For sound effects see SKILL.md "Sound Effects".

**Kolbo MCP routing:** call `generate_music`. Suno is a model option — use `list_models({ type: "music_gen" })` to see versions. Pass `instrumental` and `duration` as separate params; pass the Style/Description text as `style` and the Lyrics as `lyrics`.

**Wants an EXISTING track, not a new song?** ("background music", "stock music", "royalty-free track") → don't generate. Use `search_stock_media` with `mediaType: "music"` (semantic vibe query — "tense cinematic pulse", "uplifting corporate background") → `get_stock_asset` for download URLs. Free, no credits. The older `*_music_library` tools are deprecated adapters over the stock library — prefer the stock tools.

## CRITICAL Kolbo Platform Rules

- **Model version, duration, and instrumental toggle are MCP-tool params.** Don't write `v4.5`, `30 seconds`, or `instrumental: true` inside the prompt fields themselves.
- **Exact track length = `duration_seconds`** (clamped 5–300s). Only length-controllable models honor it (e.g. ElevenLabs Music, `music-v1`) — without it those models default to a ~10s track, so ALWAYS pass it for jingles/beds on those models. Suno ignores it and picks its own length.
- Suno generations have **two separate input fields**: a **Style / Description** field (`style` param) and a **Lyrics** field (`lyrics` param). Output your prompt as **TWO separate fenced code blocks** so the user (and the tool call) know exactly what goes where.
- Tell the user to run the prompt multiple times — Suno output varies significantly between generations, that's a feature. Use `num_generations` if the tool supports it, or fire 2–4 parallel `generate_music` calls.

## How Music Prompting Actually Works

Suno responds to **descriptive, layered prompts**, not vague ones.
- ❌ "make a pop song"
- ⚠️ "upbeat dance-pop, female vocals, glossy production, catchy chorus, summer vibe"
- ✅ "Dance-pop track, bright analog synths, female lead vocal with airy harmonies, catchy four-on-the-floor hook, 120 BPM, summer road-trip energy"

The formula: **Genre + Mood + Instrumentation + Vocal style + Tempo/BPM + Scene/era anchor**

## The Style / Description Field (`style`)

Pack these into one comma-separated descriptor line (no labels, no quotes around the whole thing — Suno reads it as a style descriptor):
- **Genre / sub-genre** — `synthwave`, `neo-soul`, `bedroom indie pop`, `drill`, `baroque trap`, `cinematic orchestral trailer`
- **Mood** — `melancholic`, `euphoric`, `tense`, `hopeful`, `hypnotic`, `nostalgic`
- **Instrumentation** — `bright analog synths`, `fingerpicked nylon guitar`, `808 sub bass`, `brushed snare`, `Rhodes electric piano`, `strings + harpsichord`, `muted brass section`
- **Vocal style** — `female lead with airy harmonies`, `whispered male falsetto`, `autotuned melodic rap`, `gospel choir backing`, `spoken-word female narrator`, `no vocals` (for instrumental)
- **Tempo / BPM** — `120 BPM`, `slow tempo 70 BPM`, `uptempo 140 BPM`
- **Era / production cue** — `80s analog warmth`, `modern polished pop production`, `lo-fi cassette tape feel`, `live-room reverb`, `bedroom production`
- **Scene anchor (optional but powerful)** — `late night highway drive`, `80s prom night`, `rainy city rooftop`, `Tokyo bullet train`

**Style cap**: keep this field to roughly **8–15 descriptors**. More starts to muddy the output.

## The Lyrics Field (`lyrics`)

Use Suno's section tags to control structure. Each tag goes on its own line, content under it:
- `[Intro]`
- `[Verse]` / `[Verse 1]` / `[Verse 2]`
- `[Pre-Chorus]`
- `[Chorus]`
- `[Bridge]`
- `[Outro]`
- `[Instrumental]` / `[Solo]`

**Production tags** (inline, in brackets — Suno follows them):
- `[Bass drop]`, `[Beat switch]`, `[Tempo change]`
- `[Whisper vocals]`, `[Falsetto]`, `[Spoken word]`, `[Gospel choir]`
- `[Flute solo]`, `[Guitar riff]`, `[808 drop]`
- `[Stop]`, `[Build up]`, `[Breakdown]`
- `- crowd noise -`, `- record scratch -` (SFX in dashes)

**Emphasis**: ALL CAPS amplifies intensity / emotion on that word or line. Use sparingly for impact moments.

**Structure templates**:
- Pop / radio: Intro → Verse → Chorus → Verse → Chorus → Bridge → Chorus → Outro
- Hip-hop: Intro → Verse → Hook → Verse → Hook → Bridge → Hook → Outro
- Cinematic / score: Intro (build) → Theme A → Theme B → Climax → Resolution
- Lo-fi / chill: Intro → Loop A → Loop B → Loop A → Outro (often no vocals)

## Power Moves

- **Mix unexpected genres** — `country + EDM`, `folk + ambient synths`, `classical + trap drums`, `baroque + 808s`. Best outputs often come from contrast.
- **Scene-based language beats sound-only language** — `late-night highway drive` does more work than `atmospheric`.
- **Tags shape structure better than prose** — don't write "then there's a chorus", write `[Chorus]`.
- **No real artist names** — Suno blocks them. Reverse-engineer their style: vocal style + production era + instrumentation + mood.
- **Lean into imperfection** — Suno's quirks often produce the best moments. Don't over-correct.
- **Generate multiple times** — same prompt produces wildly different songs. Tell the user to run 3–4 takes.

## Workflow by Use Case

### Full song with vocals
- `style`: full descriptor stack
- `lyrics`: tagged structure with lyric content
- Recommend: 2–3 generations to compare

### Instrumental / score / lo-fi beat
- `style`: descriptor stack + `instrumental`, `no vocals`
- `lyrics`: structure tags only (`[Intro]`, `[Theme A]`, `[Build]`, `[Drop]`), no lyric lines. Or leave empty and pass `instrumental: true` to the tool.

### Jingle / ad music (15–30s)
- `style`: short, punchy descriptor (`upbeat retail pop jingle, female vocal, claps, glossy production, summer energy`)
- `lyrics`: 2–4 short lines max, often just chorus
- Pass the shortest `duration` the tool supports — or, on a length-controllable model (ElevenLabs Music), pass the exact `duration_seconds` (e.g. `15` or `30`).

### Cinematic trailer / score
- `style`: `cinematic orchestral trailer, swelling strings, taiko drums, hybrid choir, dramatic build, modern hybrid score`
- `lyrics`: structure tags only — `[Intro]` `[Build]` `[Drop]` `[Climax]` `[Resolution]`
- `instrumental: true`

## Output Discipline

Always output **two fenced code blocks**, clearly labeled (these map directly to `style` and `lyrics` MCP params):

```
STYLE / DESCRIPTION:
<style descriptors, comma-separated, one line>
```

```
LYRICS:
[Intro]
...
[Verse]
...
[Chorus]
...
```

When summarizing to the user, state separately:
- **Instrumental:** yes / no (the `instrumental` param)
- **Recommended duration:** short / medium / long (the `duration` param)
- **Run takes:** N generations (usually 2–4) — fire them in parallel
- **Why this works:** 1 line on the key genre / structure / instrumentation choice

If the user is in any language other than English, explanations in their language; lyric language matches what the user wants (any language works in Suno).