• User wants to create an explainer or tutorial video
• User asks to "explain" something in video form
• User wants narrated content with AI-generated visuals
• User says "explainer video", "解说视频", "tutorial video"

• User wants audio-only content without visuals (use

  /speech

  or

  /podcast

  )
• User wants a podcast-style discussion (use

  /podcast

  )
• User wants to generate a standalone image (use

  /image-gen

  )
• User wants to read text aloud without video (use

  /speech

  )

• No shell scripts. Construct curl commands from the API reference files listed in Resources
• Always read

  shared/authentication.md

  for API key and headers
• Follow

  shared/common-patterns.md

  for polling, errors, and interaction patterns
• Always read config following

  shared/config-pattern.md

  before any interaction
• Never hardcode speaker IDs — always fetch from the speakers API
• Never save files to

  ~/Downloads/

  — use

  .listenhub/explainer/

  from config
• Explainer uses exactly 1 speaker
• Mode must be

  info

  (for Info style) or

  story

  (for Story style) — never

  slides

  (use

  /slides

  skill instead)

1. outputMode: Follow

   shared/output-mode.md

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

     null

3. Style (optional): "默认风格？"
   • "Info — 信息展示型"
   • "Story — 故事叙述型"
   • "每次手动选择" → keep

     null

undefined

What would you like to explain or introduce?

shared/speaker-selection.md

• Default from

  config.defaultSpeakers.{language}

  (skip step if set)
• Text table + free-text input
• Input matching and re-prompt on no match

1. Submit (foreground):

   POST /storybook/episodes

   with content, speaker, language, mode → extract

   episodeId

2. Tell the user the task is submitted
3. Poll (background): Run the following exact bash command with

   run_in_background: true

   and

   timeout: 600000

   . Do NOT use python3, awk, or any other JSON parser — use

   jq

   as shown:
   bash

   EPISODE_ID="<id-from-step-1>"
   for i in $(seq 1 30); do
     RESULT=$(curl -sS "https://api.marswave.ai/openapi/v1/storybook/episodes/$EPISODE_ID" \
       -H "Authorization: Bearer $LISTENHUB_API_KEY" 2>/dev/null)
     STATUS=$(echo "$RESULT" | tr -d '\000-\037\177' | jq -r '.data.processStatus // "pending"')
     case "$STATUS" in
       success|completed) echo "$RESULT"; exit 0 ;;
       failed|error) echo "FAILED: $RESULT" >&2; exit 1 ;;
       *) sleep 10 ;;
     esac
   done
   echo "TIMEOUT" >&2; exit 2

4. When notified, download and present script:
   Read

   OUTPUT_MODE

   from config. Follow

   shared/output-mode.md

   for behavior.

   inline

   or

   both

   : Present the script inline.
   Present:

   解说脚本已生成！
   
   「{title}」
   
   在线查看：https://listenhub.ai/app/explainer/{episodeId}

   download

   or

   both

   : Also save the script file.
   • Create

     .listenhub/explainer/YYYY-MM-DD-{episodeId}/

   • Write

     {episodeId}.md

     from the generated script content
   • Present the download path in addition to the above summary.
5. If video requested:

   POST /storybook/episodes/{episodeId}/video

   (foreground) → poll again (background) using the exact bash command below with

   run_in_background: true

   and

   timeout: 600000

   . Poll for

   videoStatus

   , not

   processStatus

   :
   bash

   EPISODE_ID="<id-from-step-1>"
   for i in $(seq 1 30); do
     RESULT=$(curl -sS "https://api.marswave.ai/openapi/v1/storybook/episodes/$EPISODE_ID" \
       -H "Authorization: Bearer $LISTENHUB_API_KEY" 2>/dev/null)
     STATUS=$(echo "$RESULT" | tr -d '\000-\037\177' | jq -r '.data.videoStatus // "pending"')
     case "$STATUS" in
       success|completed) echo "$RESULT"; exit 0 ;;
       failed|error) echo "FAILED: $RESULT" >&2; exit 1 ;;
       *) sleep 10 ;;
     esac
   done
   echo "TIMEOUT" >&2; exit 2

6. When notified, download and present result:

OUTPUT_MODE

shared/output-mode.md

inline

both

解说视频已生成！

视频链接：{videoUrl}
音频链接：{audioUrl}
时长：{duration}s
消耗积分：{credits}

download

both

DATE=$(date +%Y-%m-%d)
JOB_DIR=".listenhub/explainer/${DATE}-{jobId}"
mkdir -p "$JOB_DIR"
curl -sS -o "${JOB_DIR}/{jobId}.mp3" "{audioUrl}"

NEW_CONFIG=$(echo "$CONFIG" | jq \
  --arg lang "{language}" \
  --arg style "{info/story}" \
  --arg speakerId "{speakerId}" \
  '. + {"language": $lang, "defaultStyle": $style, "defaultSpeakers": (.defaultSpeakers + {($lang): [$speakerId]})}')
echo "$NEW_CONFIG" > "$CONFIG_PATH"

• Text script only: 2-3 minutes
• Text + Video: 3-5 minutes

• Speaker list:

  shared/api-speakers.md

• Speaker selection guide:

  shared/speaker-selection.md

• Episode creation:

  shared/api-storybook.md

• Polling:

  shared/common-patterns.md

  § Async Polling
• Config pattern:

  shared/config-pattern.md

• Invokes: speakers API (for speaker selection); may invoke

  /speech

  for voiceover
• Invoked by: content-planner (Phase 3)

1. Topic: "Claude Code introduction"
2. Ask language → "English"
3. Ask style → "Info"
4. Fetch speakers, user picks "cozy-man-english"
5. Ask output → "Text + Video"

curl -sS -X POST "https://api.marswave.ai/openapi/v1/storybook/episodes" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{"type": "text", "content": "Introduce Claude Code: what it is, key features, and how to get started"}],
    "speakers": [{"speakerId": "cozy-man-english"}],
    "language": "en",
    "mode": "info"
  }'