Music Generator Skill (Full SOP)

---

name: music-generator

description: |

Generate AI music or lyrics from natural language with a single sentence. The system auto-detects

whether to create a vocal song or pure instrumental BGM, and automatically polls the task: it

returns a preview link first, then the final downloadable audio link.

author: Musicful

---

# Music Generator Skill (Full SOP)

Capability Overview

This skill supports the following intents:

1) Generate a full song with lyrics

2) Generate pure background music (BGM)

3) Generate lyrics only (no audio)

4) Query music generation task status

Users can describe the music they want in plain language. The system auto-determines the mode and

handles parameter inference and task tracking.

---

Triggers and Natural Language Examples

The following natural language requests will trigger this skill:

---

Execution (SOP Step‑by‑Step)

Preflight Check (Mandatory)

- If not configured (empty/missing), immediately inform the user:

- "MUSICFUL_API_KEY is not configured. Please visit https://www.musicful.ai/api/authentication/interface-key/

to obtain/purchase an interface key, then write the KEY into <skill_root>/.env under MUSICFUL_API_KEY."

- Stop subsequent calls and wait for the user to complete configuration before continuing.

The execution flow is intent‑based and incorporates a two‑stage return and a "lyrics‑first" UX:

- mode=normal (default): generate and show lyrics → submit generation → return preview (status=2) →

return final (status=0)

- mode=bgm: pure music (instrumental=1), no lyrics → preview first → then final

- mode=lyrics: return lyrics text immediately

directly and poll (preview first, then final)

---

Scenario A: Generate a Full Song with Lyrics

Typical user inputs:

Detailed Flow

**Step 1: Intent Recognition**

**Step 2: Lyrics Handling**

**Step 3: Submit Music Generation Task**

**Step 4: Automatic Task Polling (Two Stages)**

- status = 2 → preview stage complete (returns `audio_url` as preview link)

- status = 0 → full audio complete (returns `audio_url` as downloadable final link)

- others → processing or failed (use `fail_code`/`fail_reason`)

1) On first status=2: immediately announce "preview is ready" and return `audio_url` for listening;

2) Continue polling until status=0: then return "final audio is ready" with `audio_url` (download/publish).

**Step 5: Return Results to the User (Two‑Stage × Two Songs)**

two‑stage return independently:

- Stage 1: when this id reaches status=2 → return the preview link (audio_url)

- Stage 2: keep polling this id → when status=0 → return the full mp3 download link (audio_url)

- title: <title>

- prompt: <original user description>

- lyrics: <full lyrics for lyric mode; empty for BGM>

- preview: <preview link (status=2)>

- full: <final mp3 (status=0)>

---

Scenario B: Generate Pure Background Music

:white_check_mark: Typical user inputs:

Detailed Flow

**Step 1: Intent Recognition**

**Step 2: Submit Music Generation Task**

**Step 3: Automatic Task Polling (Two Stages)**

**Step 4: Return Preview & Final Links (Two Steps)**

---

Scenario C: Generate Lyrics Only

:white_check_mark: User inputs:

Process

---

Scenario D: Query Music Generation Task Status

:white_check_mark: User inputs:

Detailed Flow

1. Extract task_id from the user input;

2. GET {BASE_URL}/v1/music/tasks?ids=<task_id>

3. Return task status and audio information.

---

Parameter Inference Rules

| Parameter | Source | Default/Notes |

|-----------------|--------------------------|--------------------------------|

| `style` | Inferred from user input | Default to Pop/general if none |

| `mv` | Default high‑quality | Prefer latest high‑quality |

| `instrumental` | Set to 1 for BGM | Otherwise 0 |

| `lyrics` | User‑provided / auto | — |

| `title` | Inferred or auto‑named | — |

> BASE_URL and API Key:

> - MUSICFUL_BASE_URL (default: https://api.musicful.ai)

> - MUSICFUL_API_KEY (read from the skill folder’s .env; environment variable MUSICFUL_API_KEY is also honored if set)

> - Entry points: scripts/musicful_api.py, CLI: scripts/run_musicful.py / scripts/dispatch_music_generator.py

> - Important: ensure MUSICFUL_API_KEY is configured before calling; if missing, the server may respond with HTTP 500 (helps pinpoint auth/config issues quickly).

---

Error Handling and Fallback

1. If the request is unclear (e.g., "generate music" without clarifying lyrics vs BGM) → ask a follow‑up;

2. If the API call fails → return clear failure reason and suggestions;

3. If polling times out → prompt the user to wait or retry.

---

Unified Return Format

Success:

{ "status": "success", "data": { ... } }

Error:

{ "status": "error", "message": "<reason>" }

Example Dialogues