byted-music-generate

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: byted-music-generate
description: Generate music using Volcengine Imagination API. Supports vocal songs, instrumental BGM, and lyrics generation. Use when the user wants to create songs, background music, soundtracks, write lyrics, or mentions "music generation", "BGM", or "songwriting".
license: Complete terms in LICENSE
---

# Music Generate Skill

Generate music using the [Volcengine Music Generation API](https://www.volcengine.com/docs/84992). Supports vocal songs, instrumental BGM, and AI lyrics generation.

## Trigger Conditions

1. User wants to generate a song (with lyrics or a text prompt)
2. User needs background music, instrumental tracks, or soundtracks
3. User wants AI-generated lyrics
4. User mentions "write a song", "music generation", "BGM", "background music", "lyrics"

## Environment Variables

Two authentication methods are supported (gateway takes priority):

**Option 1: API Gateway (recommended)**
- `ARK_SKILL_API_BASE` — API gateway base URL
- `ARK_SKILL_API_KEY` — API gateway authentication key

**Option 2: Direct AK/SK**
- `VOLCENGINE_ACCESS_KEY` — AccessKey ID
- `VOLCENGINE_SECRET_KEY` — AccessKey Secret
- How to obtain: [Volcengine Console](https://console.volcengine.com/) → Account → Key Management → Create Key

## Usage

1. Determine user intent and select the mode (`song` / `bgm` / `lyrics`).
2. `cd` to the skill directory: `skills/byted-music-generate`.
3. Run the script. The script polls the API internally and may take **several minutes** to complete (typically 1–5 minutes for song/bgm).
4. **Monitor execution**: If the runtime environment moves the command to background, you MUST periodically (every 10 seconds) read the terminal output to check whether the script has finished. The script prints polling progress to stderr and outputs a single JSON line to stdout upon completion.
5. Once completed, return the `audio_url` or `lyrics` from the JSON output to the user.

## Three Modes

### 1. song — Vocal Song

User provides lyrics (Lyrics) or a text prompt (Prompt) to generate a vocal song.

```bash
# With text prompt
python scripts/music_generate.py song --prompt "A song about summer at the beach" --genre Pop --gender Female

# With lyrics
python scripts/music_generate.py song --lyrics "[verse]\nMoonlight on the windowsill\nMemories flowing like water\n[chorus]\nYou are my moonlight" --genre Folk --mood "Sentimental/Melancholic/Lonely"
```

**Note**: `--lyrics` and `--prompt` are mutually exclusive; lyrics takes priority. If the user hasn't provided lyrics, you can first use the `lyrics` mode to generate them, then pass the result to the `song` mode.

### 2. bgm — Instrumental BGM

Describe the desired music in natural language. The v5.0 model does not require Genre/Mood parameters — just describe everything in the `--text` field.

```bash
python scripts/music_generate.py bgm --text "Relaxed coffee shop ambiance music with piano and guitar" --duration 60

# With song structure segments
python scripts/music_generate.py bgm --text "Epic game soundtrack" --segments '[{"Name":"intro","Duration":10},{"Name":"chorus","Duration":30}]'
```

### 3. lyrics — Lyrics Generation

Returns synchronously (no polling needed). Can be used standalone or as a pre-step for the `song` mode.

```bash
python scripts/music_generate.py lyrics --prompt "A song about graduation farewell" --genre Folk --mood "Sentimental/Melancholic/Lonely" --gender Female
```

### Manual Task Query (timeout fallback)

```bash
python scripts/music_generate.py query --task-id "202601397834584670076931"
```

## Mode Detection Logic

```
User Request
    ↓
Contains "instrumental/BGM/background music/soundtrack"?
    ├─ Yes → bgm mode
    └─ No → Contains "lyrics/write lyrics" and does NOT request audio?
        ├─ Yes → lyrics mode
        └─ No → song mode
            ├─ User provided lyrics → --lyrics
            └─ User only described a theme → --prompt (or lyrics first, then song)
```

## Script Parameters

### song mode

| Paramete