byted-music-generate — Claude Code skill
The byted-music-generate skill generates vocal songs, instrumental background music, and song lyrics using the Volcengine Imagination API. Use it when you need to create music for a project, compose a soundtrack, or write lyrics.
Apache-2.0 103 installs ★ 494 updated 2026-10-22
npx skills add bytedance/agentkit-samples --skill byted-music-generate -a claude-codeWhat byted-music-generate does
The skill operates in three modes. Song mode generates vocal tracks from either written lyrics or a text description—you provide the song structure or theme, and the skill handles genre and voice selection. BGM mode creates instrumental music from natural language: describe the vibe (calm coffee shop ambient, epic game soundtrack) and optionally split it into segments. Lyrics mode synchronously outputs text only and works standalone or as a first step before vocal generation.
You'll need Volcengine credentials: either an API gateway (variables ARK_SKILL_API_BASE and ARK_SKILL_API_KEY) or direct AccessKey ID and Secret from the Volcengine console. Song and BGM generation run asynchronously and typically take 1–5 minutes; the skill polls the API internally and outputs a JSON result when ready. If the process moves to the background, check terminal output every 10 seconds to verify completion.
Song mode accepts parameters for genre, mood, voice gender, timbre, duration, key, tempo, instruments, and language. BGM uses model v5.0 by default; songs use v4.3. BGM duration ranges from 30–120 seconds; songs from 30–240.
What it helps with
- compose a vocal track from a theme description or existing lyrics
- generate instrumental background music or a soundtrack for a project
- write song lyrics based on a concept
- build structured BGM with intro, verses, and chorus segments
Example prompts for the agent
- Generate a pop song about summer beaches with a female voice
- Create a 60-second relaxing instrumental track with piano and guitar
- Write lyrics for a farewell song in folk style with a melancholic mood
How to install byted-music-generate
1Skills CLI (Vercel)
npx skills add bytedance/agentkit-samples --skill byted-music-generate -a claude-code2Manually: put the files in place
~/.claude/skills/byted-music-generate/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/byted-music-generate/
1Skills CLI (Vercel)
npx skills add bytedance/agentkit-samples --skill byted-music-generate -a codex2Manually: put the files in place
.agents/skills/byted-music-generate/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add bytedance/agentkit-samples --skill byted-music-generate -a cursor2Manually: put the files in place
.cursor/skills/byted-music-generate/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install bytedance/agentkit-samples skills/byted-music-generate2Manually: put the files in place
.github/skills/byted-music-generate/SKILL.md1Skills CLI (Vercel)
npx skills add bytedance/agentkit-samples --skill byted-music-generate -a gemini-cli2Platform CLI
gemini skills install https://github.com/bytedance/agentkit-samples --path skills/byted-music-generateManually: put the files in place
.devin/skills/byted-music-generate/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add bytedance/agentkit-samples --skill byted-music-generate -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about byted-music-generate
How do I install byted-music-generate in Claude Code?
Run npx skills add bytedance/agentkit-samples --skill byted-music-generate -a claude-code, then open ~/.claude/skills/byted-music-generate/SKILL.md.
What does byted-music-generate do?
It generates music through Volcengine's API: vocal songs from text or prompts, instrumental tracks for background use, and song lyrics. Generation runs asynchronously and typically completes in 1–5 minutes.
What credentials do I need to use this skill?
You need Volcengine API credentials: either an API gateway (set ARK_SKILL_API_BASE and ARK_SKILL_API_KEY) or AccessKey ID and Secret from the Volcengine console. Gateway takes priority.
Source text
SKILL.md · Apache-2.0
---
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
| Parameter | Required | Description |
|-------------------|----------|------------------------------------------------------|
| `--lyrics` | either | Lyrics with structure tags |
| `--prompt` | either | Text prompt (Chinese, 5-700 chars) |
| `--model-version` | no | `v4.0` or `v4.3` (default: v4.3) |
| `--genre` | no | Music genre |
| `--mood` | no | Music mood |
| `--gender` | no | `Female` / `Male` |
| `--timbre` | no | Vocal timbre |
| `--duration` | no | Duration in seconds [30-240] |
| `--key` | no | Musical key (v4.3 only) |
| `--kmode` | no | `Major` / `Minor` (v4.3 only) |
| `--tempo` | no | Tempo (v4.3 only) |
| `--instrument` | no | Instruments, comma-separated (v4.3 only) |
| `--genre-extra` | no | Secondary genres, comma-separated, max 2 (v4.3 only) |
| `--scene` | no | Scene tags, comma-separated (v4.3 only) |
| `--lang` | no | Language (v4.3 only) |
| `--vod-format` | no | `wav` / `mp3` (v4.3 only) |
| `--billing` | no | `prepaid` / `postpaid` (default: postpaid) |
| `--timeout` | no | Max wait seconds (default: 300) |
### bgm mode
| Parameter | Required | Description |
|--------------------------|----------|----------------------------------------|
| `--text` | yes | Natural language description |
| `--duration` | no | Duration in seconds [30-120] |
| `--segments` | no | JSON array of song structure segments |
| `--version` | no | Model version (default: v5.0) |
| `--enable-input-rewrite` | no | Enable prompt rewriting |
| `--billing` | no | `prepaid` / `postpaid` (default: postpaid) |
| `--timeout` | no | Max wait seconds (default: 300) |
### lyrics mode
| Parameter | Required | Description |
|-----------|----------|------------------------------------------|
| `--prompt` | yes | Lyrics prompt (Chinese only, <500 chars) |
| `--genre` | no | Music genre |
| `--mood` | no | Music mood |
| `--gender` | no | `Female` / `Male` |
## Script Return Info
The script outputs JSON with the following fields:
```json
{
"status": "success | timeout | error",
"mode": "song | bgm | lyrics | query",
"task_id": "...",
"audio_url": "https://...",
"duration": 46.0,
"lyrics": "...",
"error": null
}
```
Return the `audio_url` to the user for download or playback. URLs are valid for approximately 1 year, but users should save the file promptly.
## Error Handling
- IF the script raises `PermissionError: Authentication not configured ...`, inform the user to configure either API gateway (`ARK_SKILL_API_BASE` + `ARK_SKILL_API_KEY`) or direct AK/SK (`VOLCENGINE_ACCESS_KEY` + `VOLCENGINE_SECRET_KEY`) environment variables. Write them to the workspace environment variable file, then retry.
- IF `status` is `"timeout"`, the task is still generating. Provide the user with the `task_id` and the manual query command from the output.
- IF copyright check fails (code 50000001), suggest the user enrich the description or increase the audio duration, then retry.
## References
- Available parameter values (Genre/Mood/Timbre/Instrument etc.): [references/parameters.md](references/parameters.md)
- [Volcengine Music Generation Docs](https://www.volcengine.com/docs/84992)
- [API Signature Guide](https://www.volcengine.com/docs/6369/67269)
© bytedance · Apache-2.0 · bytedance/agentkit-samples