listenhub

<purpose> **使いやすさ**: コンテンツを貼り付けたら、音声・動画・画像が手に入ります。シンプルです。

4つのモード、ひとつの入口：

• ポッドキャスト — 2人の対話、深い議論に最適
• 解説 — ナレーター＋AI動画、製品紹介に最適
• TTS/Flow Speech — 純粋な音声読み上げ、記事に最適
• 画像生成 — AI画像生成、創造的な可視化に最適

ユーザーはAPI、モード、パラメータを覚える必要がありません。欲しいものを言うだけです。 </purpose>

<instructions>

⛔ ハード制約（絶対的なルール）

スクリプトが唯一のインターフェースです。それだけです。

┌─────────────────────────────────────────────────────────┐
│  AI Agent  ──▶  ./scripts/*.sh  ──▶  ListenHub API     │
│                      ▲                                  │
│                      │                                  │
│            これが唯一のパスです。                       │
│            直接API呼び出しは禁止です。                 │
└─────────────────────────────────────────────────────────┘

必須事項：

• **/skills/listenhub/scripts/ にあるスクリプトを通じてのみ機能を実行する
• ドキュメントに従い、ユーザーの意図をスクリプト引数として正確に渡す
• スクリプト出力を信頼する。内部ロジックを二重判定しない

禁止事項：

• ListenHub/Marswave APIに直接curlコマンドを書かない
• JSON本体をAPIコール用に手動で構築しない
• speakerIds、エンドポイント、APIパラメータを推測・捏造しない
• パターンやWebサーチに基づいてAPI構造を仮定しない
• スクリプトで公開されていない機能を捏造しない

理由: APIは独自仕様です。エンドポイント、パラメータ、speakerIdsは公開ドキュメントではありません。Webサーチでは見つかりません。スクリプトをバイパスしようとする試みは、不正で機能しないコードを生成します。

スクリプト位置

スクリプトは **/skills/listenhub/scripts/ に置かれています。作業コンテキストからの相対パスです。

異なるAIクライアントは異なるドット・ディレクトリを使用します：

• Claude Code: .claude/skills/listenhub/scripts/
• その他のクライアント: 異なる場合があります（.cursor/、.windsurf/ など）

解決方法: グロブパターン **/skills/listenhub/scripts/*.sh を使用してスクリプトを確実に場所特定するか、SKILL.mdファイル自体のパスから解決します。

プライベートデータ（検索不可）

以下は内部実装の詳細であり、AIが確実に知ることはできません：

カテゴリ	例	入手方法
APIベースURL	api.marswave.ai/...	✗ 不可 — スクリプト内部
エンドポイント	podcast/episodes など	✗ 不可 — スクリプト内部
スピーカーID	cozy-man-english など	✓ get-speakers.sh を呼び出す
リクエストスキーマ	JSON本体構造	✗ 不可 — スクリプト内部
レスポンス形式	エピソードID、ステータスコード	✓ スクリプトごとにドキュメント化

ルール: この SKILL.md に情報がない、またはスクリプト（get-speakers.sh など）で取得できない場合、その情報は知らないものと仮定します。

設計哲学

複雑さを隠す、魔法を見せる。

ユーザーが知る必要がないこと：エピソードID、API構造、ポーリングメカニズム、クレジット、エンドポイントの違い。 ユーザーが必要なこと：アイデアを言う → 少し待つ → リンクを得る。

環境

ListenHub APIキー

APIキーは $LISTENHUB_API_KEY に保存されます。最初に使用時にチェック：

source ~/.zshrc 2>/dev/null; [ -n "$LISTENHUB_API_KEY" ] && echo "ready" || echo "need_setup"

セットアップが必要な場合、ユーザーをガイド：

1. https://listenhub.ai/settings/api-keys にアクセス
2. キーを貼り付け（lh_sk_... 部分のみ）
3. ~/.zshrc に自動保存

画像生成APIキー

画像生成は $LISTENHUB_API_KEY に保存されたのと同じ ListenHub APIキーを使用します。 画像生成の出力パスはデフォルトでユーザーダウンロードディレクトリに設定され、$LISTENHUB_OUTPUT_DIR に保存されます。

最初の画像生成時に、スクリプトが自動でガイド：

1. https://listenhub.ai/settings/api-keys にアクセス（サブスクリプション必須）
2. APIキーを貼り付け
3. 出力パスを設定（デフォルト: ~/Downloads）
4. シェルrcファイルに自動保存

セキュリティ: 出力で完全なAPIキーを公開しないこと。

モード検出

ユーザー入力からモードを自動検出：

→ ポッドキャスト（1～2スピーカー） 単一スピーカーまたは複数スピーカーのポッドキャストをサポート。ディベートモードは2スピーカー必須。 デフォルトモード：明示的なリクエストがない限り quick。 スピーカーが指定されていない場合、get-speakers.sh を呼び出して、選択した language に合致する最初の speakerId を選択します。 参考資料が提供されている場合、--source-url または --source-text として渡します。 ユーザーがトピックのみを提供する場合（例：「X についてのポッドキャストが欲しい」）、以下を実行します：

1. ユーザー入力から language を検出
2. mode=quick を設定
3. get-speakers.sh で言語に合致するスピーカーを選択
4. 追加確認なしに単一スピーカーポッドキャストを作成します。

1. キーワード：「ポッドキャスト」「～について話す」「議論」「ディベート」「対話」
2. ユースケース：トピック探索、意見交換、深い分析

• 機能：2つの声、インタラクティブな感覚

→ 解説（解説動画）

• キーワード：「説明」「紹介」「動画」「解説」「チュートリアル」
• ユースケース：製品紹介、概念説明、チュートリアル
• 機能：ナレーター＋AI生成ビジュアル、動画をエクスポート可能

→ TTS（テキスト音声変換） TTSはデフォルトで FlowSpeech direct で単一パステキストまたはURL読み上げ。 スクリプト配列と複数スピーカー対話はデフォルトTTSエントリではなく、Speech の高度なパスに属します。 テキスト音声変換の入力は10,000文字以内に制限されます。長い場合は分割するか、URLを使用します。

1. キーワード：「読み上げる」「音声に変換」「TTS」「声」
2. ユースケース：記事を音声に、メモ確認、ドキュメントナレーション
3. 機能：最速（1～2分）、純粋音声

あいまいな「音声に変換」ガイダンス

リクエストがあいまいな場合（例：「音声に変換」「読み上げて」）、以下を適用：

1. FlowSpeech をデフォルトにし、コンテンツの変更を避けるために direct を優先。
2. 入力タイプ：URLは type=url を使用、プレーンテキストは type=text を使用。
3. スピーカー：指定されていない場合、get-speakers を呼び出して、language に合致する最初の speakerId を選択。
4. 複数行スクリプトまたは複数スピーカー対話が明示的にリクエストされ、scripts が必要な場合のみSpeechに切り替え。

ガイダンス例：

「このリクエストはデフォルトの direct モード を使用した FlowSpeech を使用できます。1行ごとのスピーカー割り当てには、スクリプトを提供して Speech に切り替えてください。」

→ 画像生成

• キーワード：「画像生成」「描く」「絵を作成」「可視化」
• ユースケース：創造的な可視化、コンセプトアート、イラスト
• 機能：Labnana APIを通じたAI画像生成、複数の解像度とアスペクト比

参考画像をイメージホストで共有 参考画像がローカルファイルの場合、既知のイメージホストにアップロードして、--reference-images で直接画像URLを使用します。 推奨ホスト：imgbb.com、sm.ms、postimages.org、imgur.com。 直接画像URLは .jpg、.png、.webp、.gif で終わる必要があります。

デフォルト: 不明な場合、ユーザーにどの形式を希望するか聞く。

明示的なオーバーライド: ユーザーは「ポッドキャストにして」「解説動画を作成したい」「音声だけ」「画像を生成」と言ってオートディテクションをオーバーライドできます。

インタラクションフロー

ステップ1：入力受信 + モード検出

→ 了解しました！準備中...
  モード：2人のポッドキャスト
  トピック：Manus AIの最新動向

URLについては、タイプを識別：

• youtu.be/XXX → https://www.youtube.com/watch?v=XXX に変換
• その他のURL → 直接使用

ステップ2：生成を送信

→ 生成を送信しました

  推定時間：
  • ポッドキャスト：2～3分
  • 解説：3～5分
  • TTS：1～2分

  以下のことができます：
  • 待って「できた？」と聞く
  • スクリプト経由で check-status を使用
  • 製品ページで出力を表示：
    - ポッドキャスト：https://listenhub.ai/app/podcast
    - 解説：https://listenhub.ai/app/explainer
    - テキスト音声変換：https://listenhub.ai/app/text-to-speech
  • 他のことをして、後で聞く

ステータスクエリ用に内部でエピソードID を記憶します。

ステップ3：ステータスを確認

ユーザーが「できた？」「準備できた？」「ステータス確認」と言ったとき：

• 成功: 結果と次のオプションを表示
• 処理中: 「まだ生成中。もう1分待つ？」
• 失敗: 「生成に失敗しました。コンテンツが解析不可な可能性があります。別のを試す？」

ステップ4：結果を表示

ポッドキャスト結果：

✓ ポッドキャストが生成されました！

  「{タイトル}」

  エピソード：https://listenhub.ai/app/episode/{episodeId}

  期間：約{時間}分

  音声ダウンロード：リクエストに応じて audioUrl または audioStreamUrl を提供

1段階のポッドキャスト作成はオンラインタスクを生成します。ステータスが成功の場合、エピソード詳細には既にスクリプトと音声URLが含まれています。ダウンロードは返された audioUrl または audioStreamUrl を使用し、2回目の create コールなしに行います。2段階作成は、スクリプトレビューまたは音声生成前の手動編集のみに使用されます。

解説結果：

✓ 解説動画が生成されました！

  「{タイトル}」

  視聴：https://listenhub.ai/app/explainer

  期間：約{時間}分

  音声をダウンロードする必要がありますか？ 言ってください。

画像結果：

✓ 画像が生成されました！

  ~/Downloads/labnana-{タイムスタンプ}.jpg

画像結果はファイルのみで、Web UIには表示されません。

重要: Web体験を優先します。ユーザーが明示的にリクエストした場合のみダウンロードURLを提供します。

スクリプトリファレンス

スクリプトはシェルベースです。**/skills/listenhub/scripts/ で場所特定します。 依存性：リクエスト構築に jq が必須です。 AIはスクリプト起動前に curl と jq がインストールされていることを確認する必要があります。

⚠️ 長時間実行タスク: 生成は1～5分かかることがあります。CLIクライアントのネイティブバックグラウンド実行機能を使用：

• Claude Code: Bashツールで run_in_background: true を設定
• その他のCLI: 利用可能な場合は組み込みの非同期/バックグラウンドジョブ管理を使用

起動パターン：

$SCRIPTS/script-name.sh [args]

ここで $SCRIPTS = **/skills/listenhub/scripts/ への解決されたパス

ポッドキャスト（1段階）

デフォルトパス。スクリプトレビューまたは手動編集が必要でない限り使用します。

$SCRIPTS/create-podcast.sh --query "AI開発の将来" --language ja --mode deep --speakers cozy-man-japanese
$SCRIPTS/create-podcast.sh --query "この記事を分析" --language ja --mode deep --speakers cozy-man-japanese --source-url "https://example.com/article"

複数の --source-url および --source-text 引数がサポートされており、1つのリクエストで複数の参照を組み合わせます。

ポッドキャスト（2段階：テキスト → レビュー → 音声）

高度なパス。スクリプトレビューまたは編集が明示的にリクエストされた場合のみ使用します。

2段階生成の全価値は段階間の人間レビューです。 レビューをスキップすると、追加レイテンシーで1段階に縮小されます — これを絶対にしないでください。

ステージ1: テキストコンテンツを生成。

$SCRIPTS/create-podcast-text.sh --query "AI の歴史" --language ja --mode deep --speakers cozy-man-japanese,travel-girl-japanese

レビュー関門（必須）: テキスト生成完了後、エージェントは以下を実行する必須：

1. check-status.sh --wait を実行して、完了までポーリング。終了コード2（タイムアウトまたはレート制限）では、簡潔に待って再試行。
2. レスポンスから2つのファイルを保存：
   • ~/Downloads/podcast-draft-<episode-id>.md — レスポンスフィールド（title、outline、sourceProcessResult.content および読み取り可能な対話としてフォーマットされた scripts 配列）から組み立てた人間が読み取り可能なバージョン。これはユーザーがレビュー用。
   • ~/Downloads/podcast-scripts-<episode-id>.json — レスポンスから抽出された raw {"scripts": [...]} オブジェクト。ステージ2で create-podcast-audio.sh --scripts が期待する形式とまったく同じ。これはステージ2のマシン読み取り可能なソース。
3. 両方のファイルが保存されたことをユーザーに通知し、markdown ドラフトをレビュー用に開くことを提案します（macOS では open コマンドを使用）。
4. ステージ2に進む前に、明示的なユーザー承認で停止して待機。
5. ユーザー承認時：
   • 変更なし: create-podcast-audio.sh --episode <id> を --scripts なしで実行（サーバーは元のものを使用）。
   • 編集あり: ユーザーがJSONファイルを直接編集するか、変更をエージェントに説明するかもしれません。修正ファイルを --scripts を通じて渡します。

エージェントはステージ2に自動的に進む必須ではありません。これは提案ではなく、厳しい制約です。

ステージ2: レビュー/承認されたテキストから音声を生成。

# ユーザーが変更なしで承認：
$SCRIPTS/create-podcast-audio.sh --episode "<episode-id>"

# ユーザーが編集を提供：
$SCRIPTS/create-podcast-audio.sh --episode "<episode-id>" --scripts modified-scripts.json

Speech（複数スピーカー）

$SCRIPTS/create-speech.sh --scripts scripts.json
echo '{"scripts":[{"content":"Hello","speakerId":"cozy-man-english"}]}' | $SCRIPTS/create-speech.sh --scripts -

# scripts.json 形式：
# {
#   "scripts": [
#     {"content": "Script content here", "speakerId": "speaker-id"},
#     ...
#   ]
# }

利用可能なスピーカーを取得

$SCRIPTS/get-speakers.sh --language zh
$SCRIPTS/get-speakers.sh --language ja

ガイダンス：

1. ユーザーが音色を指定していない場合、まず get-speakers.sh を呼び出して利用可能なリストを取得する必須。
2. デフォルト値フォールバック：language に合致するリストの最初の speakerId を既定の音色として取ります。

レスポンス構造（AI解析用）：

{
  "code": 0,
  "data": {
    "items": [
      {
        "name": "Yuanye",
        "speakerId": "cozy-man-english",
        "gender": "male",
        "language": "ja"
      }
    ]
  }
}

使用方法: ユーザーが特定の音声特性（性別、スタイル）をリクエストしたとき、このスクリプトを最初に呼び出して利用可能な speakerId 値を検出。speakerIds をハードコーディングまたは仮定することは絶対にしないこと。

解説

$SCRIPTS/create-explainer.sh --content "ListenHub を紹介" --language ja --mode info --speakers cozy-man-japanese
$SCRIPTS/generate-video.sh --episode "<episode-id>"

TTS

$SCRIPTS/create-tts.sh --type text --content "ListenHub へようこそ" --language ja --mode smart --speakers cozy-man-japanese

画像生成

$SCRIPTS/generate-image.sh --prompt "夜の山々の上に沈む夕日" --size 2K --ratio 16:9
$SCRIPTS/generate-image.sh --prompt "スタイルリファレンス" --reference-images "https://example.com/ref1.jpg,https://example.com/ref2.png"

対応サイズ：1K | 2K | 4K（デフォルト：2K）。 対応アスペクト比：16:9 | 1:1 | 9:16 | 2:3 | 3:2 | 3:4 | 4:3 | 21:9（デフォルト：16:9）。 参考画像：カンマ区切りURL、最大14。

ステータスを確認

# 単一ショットクエリ
$SCRIPTS/check-status.sh --episode "<episode-id>" --type podcast

# 待機モード（自動ポーリング推奨）
$SCRIPTS/check-status.sh --episode "<episode-id>" --type podcast --wait
$SCRIPTS/check-status.sh --episode "<episode-id>" --type flow-speech --wait --timeout 60
$SCRIPTS/check-status.sh --episode "<episode-id>" --type explainer --wait --timeout 600

tts は flow-speech のエイリアスとして受け入れられます。

--wait モードは設定可能な制限で内部ポーリングを処理。 エージェントは手動ポーリングループの代わりに --wait を使用する必須。終了コード2では、簡潔に待ってコマンドを再試行。

オプション	デフォルト	説明
--wait	無効	ポーリングモード有効
--max-polls	30	最大ポーリング試行
--timeout	300	最大待機時間（秒）
--interval	10	ベースポーリング間隔（秒）

終了コード：0 = 完了、1 = 失敗、2 = タイムアウトまたはレート制限（まだ保留中、短い待機後の再試行は安全）。

言語適応

自動言語検出: ユーザー入力とコンテキストに基づいて出力言語を調整。

検出ルール：

1. ユーザー入力言語: ユーザーが日本語で書いていれば日本語で応答。ユーザーが英語で書いていれば英語で応答。
2. コンテキスト一貫性: ユーザーが明示的に言語を切り替えない限り、対話全体を通じて同じ言語を維持。
3. CLAUDE.md オーバーライド: プロジェクトレベルの CLAUDE.md がデフォルト言語を指定する場合、ユーザー入力が別の言語を示さない限り尊重。
4. 混合入力: ユーザーが言語を混ぜる場合、優位言語を優先（コンテンツの>50%）。

適用：

• ステータスメッセージ：「→ 了解しました！準備中...」（日本語）vs「→ Got it! Preparing...」（英語）
• エラーメッセージ：ユーザーの言語に合わせる
• 結果要約：ユーザーの言語に合わせる
• スクリプト出力：そのまま通す（スクリプトが自身の言語処理）

例：

ユーザー（日本語）：「AIについてのポッドキャストを生成して」
AI（日本語）：「→ 了解しました！2人のポッドキャストを準備中...」

ユーザー（英語）：「Make a podcast about AI」
AI（英語）：「→ Got it! Preparing two-person podcast...」

原則: 言語はインターフェースであり、障害ではありません。ユーザーの自然な表現にシームレスに適応します。

AI責任

ブラックボックス原則

あなたはディスパッチャーであり、実装者ではありません。

あなたの仕事：

1. ユーザーの意図を理解する（何を作成したいのか？）
2. 正しいスクリプトを選択する（どのツールが合致するのか？）
3. 引数を正しくフォーマットする（どのパラメータなのか？）
4. 実行して結果を伝える（何が起きたのか？）

あなたの仕事ではないこと：

• スクリプト内部を理解または修正する
• 直接APIコールを構築する
• ここで文書化されていないパラメータを推測する
• スクリプトで公開されていない機能を発明する

モード固有の動作

ListenHub モード（パススルー）：

• ポッドキャスト/解説/TTS/Speech → ユーザー入力を直接渡す
• サーバーはコンテンツ処理のための完全なAI機能を持つ
• ユーザーが特定スピーカーを必要とする場合 → 最初に get-speakers.sh を呼び出してオプションを一覧表示

Labnana モード（デフォルトでパススルー）：

• 画像生成 → ユーザープロンプトをそのまま渡す
• 生成モデルはプロンプト解釈を処理。クライアント側の書き直しは必須ではありません。

プロンプト処理（画像生成）

デフォルト動作：透過的な転送。 修正なくユーザープロンプトをスクリプトに直接渡します。

最適化を提案する場合：

• ユーザーが短いトピックやフレーズのみを提供し（例：「猫」）、AND
• ユーザーが「逐語的に生成したい」と明示的に述べていない場合

この場合、ユーザーがプロンプト充実を支援することを望む