music

• User wants to generate original AI music from a prompt
• User wants to create a cover from reference audio
• User says "音乐", "music", "生成音乐", "generate music", "翻唱", "cover", "作曲", "compose", "create a song", or "做一首歌"

• 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 audio to text (use

  /asr

  )

1. Generate (original): Create a new song from a text prompt, with optional style, title, and instrumental-only options.
2. Cover: Transform a reference audio file into a new version, with optional style modifications.

• 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
• Audio file constraints for cover mode: mp3, wav, flac, m4a, ogg, aac; max 20MB
• Long timeout: 600s default. Use

  run_in_background: true

  with

  timeout: 660000

当前配置 (music)：
  输出方式：{inline / download / both}
  语言偏好：{zh / en / 未设置}

1. outputMode: Follow

   shared/output-mode.md

   § Setup Flow Question.
2. Language (optional): "默认语言？"
   • "中文 (zh)"
   • "English (en)"
   • "每次手动选择" → keep

     null

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")

"请描述你想要的歌曲（主题、情绪、歌词片段等）："

--prompt

"请提供参考音频文件路径或 URL："

--audio

• If a local path: verify the file exists and check the extension is one of:

  mp3

  ,

  wav

  ,

  flac

  ,

  m4a

  ,

  ogg

  ,

  aac

• If a URL: accept as-is (the CLI will validate)
• Check file size does not exceed 20 MB for local files:
  bash

  FILE_SIZE=$(stat -f%z "{path}" 2>/dev/null || stat -c%s "{path}" 2>/dev/null)
  if [ "$FILE_SIZE" -gt 20971520 ]; then
    echo "File exceeds 20 MB limit"
  fi

"指定音乐风格？（如 pop、rock、jazz、电子、古风等，留空则由 AI 自动选择）"

--style

"歌曲标题？（留空则自动生成）"

--title

1. Submit (background): Run the CLI command with

   run_in_background: true

   and

   timeout: 660000

   :
   Generate mode:
   bash

   listenhub music generate \
     --prompt "{prompt}" \
     --style "{style}" \
     --title "{title}" \
     --instrumental \
     --json

   Cover mode:
   bash

   listenhub music cover \
     --audio "{path-or-url}" \
     --prompt "{prompt}" \
     --style "{style}" \
     --title "{title}" \
     --instrumental \
     --json

   Flag notes:

   • --prompt

     — text description of the music (required for generate, optional for cover)

   • --audio

     — reference audio file path or URL (cover mode only, required)

   • --style

     — optional style/genre hint; omit if not provided

   • --title

     — optional track title; omit if not provided

   • --instrumental

     — add this flag for instrumental-only (no vocals); omit if not selected
   • Omit

     --prompt

     in cover mode if not provided
   The CLI handles polling internally. Music generation takes up to 10 minutes.
2. Tell the user the task is submitted and that they will be notified when it finishes.
3. When notified of completion, present the result:
   Parse the CLI JSON output for key fields:
   bash

   AUDIO_URL=$(echo "$RESULT" | jq -r '.audioUrl')
   TITLE=$(echo "$RESULT" | jq -r '.title // "Untitled"')
   DURATION=$(echo "$RESULT" | jq -r '.duration // empty')
   CREDITS=$(echo "$RESULT" | jq -r '.credits // empty')

   Read

   OUTPUT_MODE

   from config. Follow

   shared/output-mode.md

   for behavior.

   inline

   or

   both

   : Display audio URL as a clickable link.

   音乐已生成！
   
   标题：{title}
   在线收听：{audioUrl}
   时长：{duration}s
   消耗积分：{credits}

   download

   or

   both

   : Also download the file. Generate a slug from the title following

   shared/config-pattern.md

   § Artifact Naming.
   bash

   SLUG="{slug}"  # e.g. "summer-breeze"
   NAME="${SLUG}.mp3"
   # Dedup: if file exists, append -2, -3, etc.
   BASE="${NAME%.*}"; EXT="${NAME##*.}"; i=2
   while [ -e "$NAME" ]; do NAME="${BASE}-${i}.${EXT}"; i=$((i+1)); done
   curl -sS -o "$NAME" "{audioUrl}"

   Present:

   已保存到当前目录：
     {NAME}

if [ -n "$LANGUAGE" ]; then
  NEW_CONFIG=$(echo "$CONFIG" | jq --arg lang "$LANGUAGE" '. + {"language": $lang}')
  echo "$NEW_CONFIG" > "$CONFIG_PATH"
fi

• Music generation: 5-10 minutes

• CLI authentication:

  shared/cli-authentication.md

• CLI patterns:

  shared/cli-patterns.md

• Config pattern:

  shared/config-pattern.md

• Output mode:

  shared/output-mode.md

• Invokes: nothing
• Invoked by: content-planner (Phase 3)

"帮我做一首关于夏天海边的歌"

1. Detect: generate mode ("做一首歌")
2. Read config (first run: create defaults with

   outputMode: "download"

   )
3. Infer: mode = generate, prompt = "夏天海边的歌"
4. Ask: style? title? instrumental?
5. Confirm summary → user confirms

listenhub music generate \
  --prompt "关于夏天海边的歌" \
  --json

{slug}.mp3

"用这个音频翻唱一下 demo.mp3，jazz 风格"

1. Detect: cover mode ("翻唱")
2. Validate:

   demo.mp3

   exists, is a supported format, under 20 MB
3. Infer: style = "jazz" from user input
4. Ask: title? instrumental?
5. Confirm summary → user confirms

listenhub music cover \
  --audio "demo.mp3" \
  --style "jazz" \
  --json

{slug}.mp3

"Create an instrumental electronic track for a game intro"

1. Detect: generate mode ("Create ... track")
2. Infer: style = "electronic", instrumental = yes
3. Ask: title?
4. Confirm summary → user confirms

listenhub music generate \
  --prompt "instrumental electronic track for a game intro" \
  --style "electronic" \
  --instrumental \
  --json

{slug}.mp3