music

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: music
description: |
  Generate, remix, extend, edit, and analyze AI music (Mureka). Triggers on:
  "音乐", "music", "生成音乐", "generate music", "翻唱", "cover", "混音", "remix",
  "续写", "extend", "纯音乐", "instrumental", "配乐", "soundtrack", "分轨", "stem",
  "识别歌词", "recognize lyrics", "作曲", "compose",
  "create a song", "做一首歌".
metadata:
  openclaw:
    emoji: "🎵"
    requires:
      bin: ["listenhub"]
    primaryBin: "listenhub"
---

## 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 use