music

Files (2)

• SKILL.md
• music-api.md · references/

SKILL.md (first lines)

## When to Use

- User wants to generate original AI music from a prompt and/or lyrics
- User wants to remix / re-create an existing song with new lyrics
- User wants a pure instrumental, or a soundtrack scored to an image or video
- User wants to extend a song or isolate/generate a single track
- User wants to analyze audio — recognize lyrics, describe a song, or split stems
- User says "音乐", "music", "生成音乐", "generate music", "翻唱"/"混音"/"remix", "续写"/"extend", "纯音乐"/"instrumental", "配乐"/"soundtrack", "分轨"/"stem", "识别歌词", "作曲", "compose", "create a song", or "做一首歌"

## When NOT to Use

- User wants text-to-speech reading (use `/speech`)
- User wants a podcast discussion (use `/podcast`)
- User wants an explainer video with narration (use `/explainer`)
- User wants to transcribe spoken audio to text — not song lyrics (use `/asr`)

## Purpose

Full ListenHub music toolkit, powered by the **Mureka** provider via the `listenhub music` CLI. Capabilities:

**Generation (async — return a task to poll):**

1. **generate** — text and/or lyrics → a new song. Optional style, title, instrumental, and a cloned `--vocal-id`.
2. **remix** — an existing song + new lyrics → a re-creation. Input is one of an audio file, an audio URL, or a provider song ID.
3. **instrumental** — a pure instrumental from a prompt, or guided by a reference audio.
4. **soundtrack** — music scored to an image or a video.
5. **track** — isolate or generate a single instrument/vocal track from a song.
6. **extend** — make a song longer.
7. **cover** *(deprecated)* — older cover flow; prefer **remix**.

**Analysis (sync — return results immediately):**

8. **recognize** — lyrics with line-level timestamps.
9. **describe** — description, tags, genres, instruments.
10. **stem** — split a song into separated stems (ZIP download URLs).

**Task management:** `list` (recent tasks) and `get <taskId>` (status/result of one task).

Models for generation commands: `auto` (default), `mureka-7.6`, `mureka-8`, `mureka-9`, `mureka-o2`. See `references/music-api.md` for the full per-command parameter reference.

## Hard Constraints

- Always read config following `shared/config-pattern.md` before any interaction
- Follow `shared/cli-patterns.md` for execution modes, error handling, and interaction patterns
- Always follow `shared/cli-authentication.md` for auth checks
- Never save files to `~/Downloads/` or `.listenhub/` — save artifacts to the current working directory with friendly topic-based names (see `shared/config-pattern.md` § Artifact Naming)
- No speakers involved — music generation does not use speaker selection
- File limits (all max 10 MB): audio mp3/m4a (`track` also accepts wav); image jpg/jpeg/png/webp; video mp4/mov/avi/mkv/webm
- All time-range flags are in **seconds** (`--generate-start/--generate-end`)
- For async generation commands, use a long timeout: `run_in_background: true` with `timeout: 660000` (600s+). Sync commands (`recognize`, `describe`, `stem`) return immediately
- `cover` is deprecated — steer users to `remix` unless they explicitly ask for `cover`

<HARD-GATE>
Use the AskUserQuestion tool for every multiple-choice step — do NOT print options as plain text. Ask one question at a time. Wait for the user's answer before proceeding to the next step. After all parameters are collected, summarize the choices and ask the user to confirm. Do NOT call any CLI command until the user has explicitly confirmed.

</HARD-GATE>

## Step -1: CLI Auth Check

Follow `shared/cli-authentication.md`. If the CLI is not installed or the user is not logged in, auto-install and auto-login — never ask the user to run commands manually.

## Step 0: Config Setup

Follow `shared/config-pattern.md` Step 0 (Zero-Question Boot).

**If file doesn't exist** — silently create with defaults and proceed:
```bash
mkdir -p ".listenhub/music"
echo '{"outputMode":"download","language":null}' > ".listenhub/music/config.json"
CONFIG_PATH=".listenhub/music/config.json"
CONFIG=$(cat "$CONFIG_PATH")
```
**Do NOT ask any setup questions.** Proceed directly to the Interaction Flow.

**If file exists** — read config silently and proceed:
```bash
CONFIG_PATH=".listenhub/music/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/music/config.json"
CONFIG=$(cat "$CONFIG_PATH")
```

### Setup Flow (user-initiated reconfigure only)

Only run when the user explicitly asks to reconfigure. Display current settings:
```
当前配置 (music)：
  输出方式：{inline / download / both}
  语言偏好：{zh / en / 未设置}
```

Then ask:

1. **outputMode**: Follow `shared/output-mode.md` § Setup Flow Question.

2. **Language** (optional): "默认语言？"
   - "中文 (zh)"
   - "English (en)"
   - "每次手动选择" → keep `null`

After collecting answers, save immediately:
```bash
NEW_CONFIG=$(echo "$CONFIG" | jq --arg m "$OUTPUT_MODE" '. + {"outputMode": $m}')
if [ "$LANGUAGE" != "null" ]; then
  NEW_CONFIG=$(echo "$NEW_CONFIG" | jq --arg lang "$LANGUAGE" '. + {"language": $lang}')
fi
echo "$NEW_CONFIG" > "$CONFIG_PATH"
CONFIG=$(cat "$CONFIG_PATH")
```

## Interaction Flow

### Step 1: Capability

Pick the capability. Skip the question if the user's intent is already clear (e.g., "翻唱"/"混音"/"remix" → remix; "作曲"/"compose"/"做一首歌" → generate; "纯音乐"/"instrumental" → instrumental; "续写"/"extend" → extend; "分轨"/"stem" → stem; "识别歌词" → recognize).

```
Question: "想做什么？"
Options:
  - "原创 (Generate)" — 用文字 / 歌词生成全新歌曲

From marswaveai/skills, MIT.

More from marswaveai/skills