explainer

使用する場面

• ユーザーが解説動画やチュートリアル動画を作成したい場合
• ユーザーが何かを動画形式で「説明」してほしい場合
• ユーザーが AI 生成ビジュアル付きのナレーションコンテンツを求めている場合
• ユーザーが「解説動画」、「解说视频」、「チュートリアル動画」と言った場合

使用しない場面

• ユーザーがビジュアルのない音声のみのコンテンツを求めている場合（/speech または /podcast を使用）
• ユーザーがポッドキャスト形式のディスカッションを求めている場合（/podcast を使用）
• ユーザーが単体の画像を生成したい場合（/image-gen を使用）
• ユーザーが動画なしでテキストを読み上げてほしい場合（/speech を使用）

目的

1 人のナレーターによるナレーションと AI 生成ビジュアルを組み合わせた解説動画を生成します。製品紹介、概念の説明、チュートリアルに最適です。テキストのみのスクリプト生成と、テキストと動画を組み合わせた完全な出力に対応しています。

厳守事項

• どのようなやり取りの前にも、必ず shared/config-pattern.md に従って設定を読み込んでください
• 実行モード、エラー処理、やり取りのパターンについては、shared/cli-patterns.md に従ってください
• 認証チェックは必ず shared/cli-authentication.md に従ってください
• 話者 ID をハードコードしないでください。ユーザーが音声を変更したい場合は、必ず speakers CLI から取得してください
• ~/Downloads/ または .listenhub/ にファイルを保存しないでください。アーティファクトは現在の作業ディレクトリに、トピックに基づいたわかりやすい名前で保存してください（shared/config-pattern.md § Artifact Naming を参照）
• 解説動画で使用する話者は必ず 1 人です
• モードは info（Info スタイルの場合）または story（Story スタイルの場合）にしてください。slides は使用しないでください（代わりに /slides スキルを使用）

選択肢が複数ある手順では、必ず AskUserQuestion ツールを使用してください。選択肢をプレーンテキストで表示してはいけません。一度に 1 つの質問をし、次の手順に進む前にユーザーの回答を待ってください。すべてのパラメーターを収集した後、選択内容を要約してユーザーに確認してください。ユーザーが明示的に確認するまで、CLI コマンドを実行してはいけません。

Step -1: CLI 認証チェック

shared/cli-authentication.md § Auth Check に従ってください。CLI がインストールされていない場合、またはユーザーがログインしていない場合は、自動でインストールおよびログインしてください。ユーザーに手動でコマンドを実行するよう求めてはいけません。

次に、shared/cli-authentication.md § Auth Mode Detection に従って AUTH_MODE を判定し、次のように設定してください。

if [ "$AUTH_MODE" = "openapi" ]; then
  CMD_PREFIX="listenhub openapi storybook"
else
  CMD_PREFIX="listenhub explainer"
fi

以降の CLI 呼び出しでは、ハードコードされた listenhub explainer の代わりに $CMD_PREFIX を使用してください。

注： OpenAPI コマンドは explainer ではなく storybook です。バックエンドは同じですが、名称が異なります。

Step 0: 設定

shared/config-pattern.md の Step 0（Zero-Question Boot）に従ってください。

ファイルが存在しない場合 — デフォルト設定で何も表示せずに作成し、そのまま進めてください。

mkdir -p ".listenhub/explainer"
echo '{"outputMode":"inline","language":null,"defaultStyle":null,"defaultSpeakers":{}}' > ".listenhub/explainer/config.json"
CONFIG_PATH=".listenhub/explainer/config.json"
CONFIG=$(cat "$CONFIG_PATH")

設定に関する質問はしないでください。 そのまま対話フローに進んでください。

ファイルが存在する場合 — 設定を何も表示せずに読み込み、そのまま進めてください。

CONFIG_PATH=".listenhub/explainer/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/explainer/config.json"
CONFIG=$(cat "$CONFIG_PATH")

設定フロー（ユーザーが再設定を求めた場合のみ）

ユーザーが明示的に再設定を求めた場合にのみ実行してください。現在の設定を表示します。

当前配置 (explainer)：
  输出方式：{inline / download / both}
  语言偏好：{zh / en / 未设置}
  默认风格：{info / story / 未设置}
  默认主播：{speakerName / 使用内置默认}

次に質問します。

1. outputMode：shared/output-mode.md § Setup Flow Question に従ってください。

2. Language（任意）：「デフォルトの言語は何ですか？」

   • 「中国語 (zh)」
   • 「英語 (en)」
   • 「毎回手動で選択」→ null のままにする

3. Style（任意）：「デフォルトのスタイルは何ですか？」

   • 「Info — 情報提示型」
   • 「Story — 物語形式」
   • 「毎回手動で選択」→ null のままにする

回答を収集したら、すぐに保存してください。

NEW_CONFIG=$(echo "$CONFIG" | jq --arg m "$OUTPUT_MODE" '. + {"outputMode": $m}')
echo "$NEW_CONFIG" > "$CONFIG_PATH"
CONFIG=$(cat "$CONFIG_PATH")

対話フロー

Step 1: トピック／コンテンツ

自由入力。ユーザーに次のように尋ねてください。

何について説明または紹介しますか？

入力として受け付けるもの：トピックの説明、テキストコンテンツ、説明したい概念。

Step 2: 言語

config.language が設定されている場合は、選択内容にあらかじめ入力して要約に表示し、この質問を省略してください。 設定されていない場合は、次のように尋ねてください。

Question: "What language?"
Options:
  - "Chinese (zh)" — Content in Mandarin Chinese
  - "English (en)" — Content in English
  - "Japanese (ja)" — Content in Japanese

Step 3: スタイル

config.defaultStyle が設定されている場合は、選択内容にあらかじめ入力して要約に表示し、この質問を省略してください。 設定されていない場合は、次のように尋ねてください。

Question: "What style of explainer?"
Options:
  - "Info" — Informational, factual presentation style
  - "Story" — Narrative, storytelling approach

ステップ 4：話者の選択

shared/speaker-selection.md に従います。

• config.defaultSpeakers.{language} が設定されている場合 → 保存済みの話者を使用し、ユーザーには通知しません
• 設定されていない場合 → その言語の shared/speaker-selection.md に記載されている組み込みのデフォルトを使用します
• 確認の概要（ステップ 6）に話者を表示します。ユーザーは必要に応じてここで変更できます
• ユーザーが声の変更を明示的に求めた場合に限り、話者の全リストを表示します

話者の検索方法については、話者の一覧表示と絞り込みを説明している shared/cli-speakers.md を参照してください。

解説動画では、話者は 1 人のみサポートされます。

ステップ 5：出力タイプ

Question: "What output do you want?"
Options:
  - "Text script only" — Generate narration script, no video
  - "Text + Video" — Generate full explainer video with AI visuals

ステップ 6：確認して生成

選択内容をすべて要約します。

Ready to generate explainer:

  Topic: {topic}
  Language: {language}
  Style: {info/story}
  Speaker: {speaker name}
  Output: {text only / text + video}

  Proceed?

CLI コマンドを実行する前に、明示的な確認を待ちます。

ワークフロー

run_in_background: true と timeout: 660000 を指定して CLI コマンドを実行します。CLI は生成が完了するまで処理を続け、最終結果を JSON で返します。

$CMD_PREFIX create \
  --query "{topic}" \
  --mode {info|story} \
  --lang {en|zh|ja} \
  --speaker "{name}" \
  --speaker-id "{id}" \
  --timeout 600 \
  --json

コマンドが失敗した場合（終了コードが 0 以外の場合）、stderr でエラーの詳細を確認します。終了コードと一般的なエラーについては、shared/cli-patterns.md の「§ Error Handling」を参照してください。

オプションのフラグ（該当する場合に追加します）。

• --source-url "{url}" — ユーザーが参照 URL を指定した場合
• --skip-audio — テキストのみの出力（動画なし）の場合
• --image-size {2K|4K} — 画像の解像度（デフォルト：2K）
• --aspect-ratio {16:9|9:16|1:1} — 動画のアスペクト比（デフォルト：16:9）
• --style "{style}" — AI 生成画像のビジュアルスタイル

タスクが送信されたことをユーザーに伝えます。完了通知を受け取ったら、結果を解析して提示します。

CLI の JSON 出力から主要なフィールドを解析します。

EPISODE_ID=$(echo "$RESULT" | jq -r '.episodeId')
AUDIO_URL=$(echo "$RESULT" | jq -r '.audioUrl // empty')
VIDEO_URL=$(echo "$RESULT" | jq -r '.videoUrl // empty')
CREDITS=$(echo "$RESULT" | jq -r '.credits // empty')

設定から OUTPUT_MODE を読み取ります。動作については shared/output-mode.md に従います。

テキストのみの出力の場合：

inline または both：スクリプトをインラインで提示します。

以下を提示します。

解说脚本已生成！

「{title}」

在线查看：https://listenhub.ai/app/explainer/{episodeId}

download または both：スクリプトファイルも保存します。shared/config-pattern.md の「§ Artifact Naming」に従ってトピックのスラッグを生成します。

• カレントディレクトリに {slug}-explainer.md として保存します（存在する場合は重複しない名前にします）
• 上記の概要に加えて、保存先のパスを提示します

テキスト＋動画の出力の場合：

inline または both：動画 URL と音声 URL をクリック可能なリンクとして表示します。

以下を提示します。

解说视频已生成！

视频链接：{videoUrl}
音频链接：{audioUrl}
消耗积分：{credits}

download または both：ファイルも保存します。shared/config-pattern.md の「§ Artifact Naming」に従ってトピックのスラッグを生成します。

• {slug}-explainer/ フォルダーを作成します（存在する場合は重複しない名前にします）
• その中に script.md を書き込みます
• 音声をダウンロードします。

  listenhub download "{audioUrl}" -o "{slug}-explainer/audio.mp3"
  

• 以下を提示します。

  現在のディレクトリに保存しました：
    {slug}-explainer/
      script.md
      audio.mp3
  

生成成功後

このセッションで選択した内容を設定に反映します。

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"

所要時間の目安：

• テキストスクリプトのみ：2～3 分
• テキスト＋動画：5～10 分

リソース

• CLI 認証：shared/cli-authentication.md
• CLI パターン：shared/cli-patterns.md
• 話者の検索：shared/cli-speakers.md
• 話者選択ガイド：shared/speaker-selection.md
• 設定パターン：shared/config-pattern.md
• 出力モード：shared/output-mode.md

構成可能性

• 呼び出すもの：話者選択用の speakers CLI。ナレーション用に /speech を呼び出す場合があります
• 呼び出し元：content-planner（フェーズ 3）

例

ユーザー：「Claude Code を紹介する解説動画を作成して」

エージェントのワークフロー：

1. トピック：「Claude Code の紹介」
2. 言語を尋ねる → 「英語」
3. スタイルを尋ねる → 「情報」
4. デフォルトの話者「Mars」（cozy-man-english）を使用
5. 出力を尋ねる → 「テキスト＋動画」

# Run with run_in_background: true, timeout: 660000
$CMD_PREFIX create \
  --query "Introduce Claude Code: what it is, key features, and how to get started" \
  --mode info \
  --lang en \
  --speaker "Mars" \
  --speaker-id "cozy-man-english" \
  --timeout 600 \
  --json

結果から episodeId、audioUrl、videoUrl、credits を解析し、ユーザーに提示します。