tts

使用場面

• ユーザーがテキストを音声オーディオに変換したい場合
• ユーザーが「読み上げ」「TTS」「テキスト音声変換」「音声ナレーション」などを要求した場合
• ユーザーが「朗读」「配音」「语音合成」と言った場合
• ユーザーが複数話者によるスクリプト化されたオーディオまたは対話を作成したい場合

使用しない場面

• ユーザーがトピック探索を含むポッドキャストスタイルの議論を望む場合（/podcast を使用）
• ユーザーがビジュアルを含む説明動画を望む場合（/explainer を使用）
• ユーザーが画像を生成したい場合（/image-gen を使用）

目的

テキストを自然な音声オーディオに変換します。2つのモード:

1. クイックモード (--mode direct): シングル音声、低レイテンシ、同期。カジュアルチャット、スニペット読み上げ、即座音声向け。
2. スクリプトモード (--mode smart): 複数話者、セグメントごとの音声割り当て。対話、オーディオブック、スクリプト化されたコンテンツ向け。

厳しい制約

• 常に shared/cli-authentication.md に従って CLI 認証をチェック
• CLI 実行、エラー、インタラクションパターンについて shared/cli-patterns.md に従う
• CLI 呼び出しで話者 ID をハードコードしない — shared/speaker-selection.md の組み込みデフォルトをフォールバックのみとして使用し、ユーザーが音声を変更したい場合は speakers CLI から取得
• すべてのインタラクション前に shared/config-pattern.md に従って設定を常に読み込む
• 話者選択について shared/speaker-selection.md に常に従う（テキスト表 + 自由入力）
• ~/Downloads/ または /tmp/ に主要な出力としてファイルを保存しない — アーティファクトを現在の作業ディレクトリに保存し、トピックベースのわかりやすい名前を付ける（shared/config-pattern.md § Artifact Naming を参照）

<HARD-GATE> 複数選択肢の各ステップで AskUserQuestion ツールを使用する — オプションをプレーンテキストで表示しない。一度に1つの質問を質問し、次のステップに進む前にユーザーの回答を待つ。すべてのパラメータが収集された後、選択肢をまとめて確認を求める。ユーザーが明示的に確認するまで、生成 CLI コマンドを呼び出さない。 </HARD-GATE>

モード検出

ユーザーの入力からモードを 自動的に 決定してから、質問をしてください:

シグナル	モード
「多角色」「脚本」「对话」「script」「dialogue」「multi-speaker」	スクリプト
複数の文字が名前または役割で言及されている	スクリプト
入力に構造化されたセグメント (A: ..., B: ...) が含まれている	スクリプト
テキストの単一段落、文字マーカーなし	クイック
「读一下」「read this」「TTS」「朗读」とプレーンテキスト	クイック
曖昧	クイック（デフォルト）

インタラクションフロー

ステップ -1: CLI 認証チェック

shared/cli-authentication.md に従う。CLI がインストールされていないか、ユーザーがログインしていない場合は、自動インストールと自動ログインを行う — ユーザーにコマンドの実行を手動で求めない。

ステップ 0: 設定セットアップ

shared/config-pattern.md ステップ 0（ゼロクエスチョンブート）に従う。

ファイルが存在しない場合 — サイレントでデフォルトを作成して続行:

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

セットアップ質問をしない。 インタラクションフローに直接進む。

ファイルが存在する場合 — サイレントで設定を読み込んで続行:

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

セットアップフロー（ユーザーが明示的に再設定をリクエストした場合のみ）

ユーザーが明示的に再設定をリクエストした場合のみ実行。現在の設定を表示:

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

その後、以下を質問:

1. outputMode: shared/output-mode.md § Setup Flow Question に従う。

2. Language (オプション): 「默认语言？」

   • 「中文 (zh)」
   • 「English (en)」
   • 「每次手动选择」 → 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")

クイックモード — listenhub tts create --mode direct

ステップ 1: テキストを抽出

変換するテキストを取得。ユーザーがまだ提供していない場合は、質問:

「読み上げたいテキストは何ですか?」

ステップ 2: 音声を決定

• config.defaultSpeakers.{language}[0] が設定されている場合 → サイレントで使用（ステップ 4 にスキップ）
• 設定されていない場合 → 検出された言語の shared/speaker-selection.md から 組み込みデフォルト を使用（ステップ 4 にスキップ）
• ユーザーが明示的に音声を変更するよう要求した場合のみ話者選択を表示

ステップ 3: 設定を保存

ユーザーが明示的に新しい音声を選択した後（デフォルトを使用する場合ではなく）:

質問: 「{voice name} を {language} のデフォルト音声として保存しますか?」
オプション:
  - 「はい」 — .listenhub/tts/config.json を更新
  - 「いいえ」 — このセッションのみ使用

ステップ 4: 確認

生成準備完了:

  テキスト: 「{最初の 80 文字}...」
  音声: {voice name}

進行しますか?

ステップ 5: 生成

短いテキストの場合、インラインで渡す:

RESULT=$(listenhub tts create --text "{text}" --mode direct --speaker "{name}" --lang {lang} --json 2>/tmp/lh-err)
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  ERROR=$(cat /tmp/lh-err)
  case $EXIT_CODE in
    2) echo "Auth error: run 'listenhub auth login'" ;;
    3) echo "Timeout: try --no-wait" ;;
    *) echo "Error: $ERROR" ;;
  esac
  rm -f /tmp/lh-err
fi
rm -f /tmp/lh-err

AUDIO_URL=$(echo "$RESULT" | jq -r '.audioUrl')

長いテキストの場合、最初に一時ファイルに書き込む（shared/cli-patterns.md § Long Text Input を参照）:

cat > /tmp/lh-content.txt << 'ENDCONTENT'
長いテキストコンテンツはここに行く...
ENDCONTENT

RESULT=$(listenhub tts create --text "$(cat /tmp/lh-content.txt)" --mode direct --speaker "{name}" --lang {lang} --json)
AUDIO_URL=$(echo "$RESULT" | jq -r '.audioUrl')

rm -f /tmp/lh-content.txt

ステップ 6: 結果を表示

設定から OUTPUT_MODE を読む。shared/output-mode.md の動作に従う。

inline または both: audioUrl をクリック可能なリンクとして表示。

表示:

Audio generated!

在线收听：{audioUrl}

download または both: ファイルもダウンロード。shared/config-pattern.md § Artifact Naming に従ってテキストコンテンツからトピックスラグを生成。

SLUG="{topic-slug}"  # 例: "server-maintenance-notice"
NAME="${SLUG}.mp3"
# 重複排除: ファイルが存在する場合は -2, -3 を追加
BASE="${NAME%.*}"; EXT="${NAME##*.}"; i=2
while [ -e "$NAME" ]; do NAME="${BASE}-${i}.${EXT}"; i=$((i+1)); done
curl -sS -o "$NAME" "$AUDIO_URL"

表示:

Audio generated!

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

---

スクリプトモード — listenhub tts create --mode smart

ステップ 1: スクリプトを取得

ユーザーが既にスクリプト配列を持っているかどうかを判断:

• 既に提供されている (JSON または明確なセグメント): 解析して確認用に表示

• まだ提供されていない: ユーザーがセグメントを構造化するのを支援。質問:

  「スピーカー割り当て付きのスクリプトを提供してください。形式: 各行を SpeakerName: text content として。変換します。」

  ユーザーがスクリプトを提供したら、話者注釈付きテキストに解析。

ステップ 2: 文字ごとに音声を割り当て

スクリプト内の各ユニーク文字に対して:

• config.defaultSpeakers.{language} に保存済み音声がある場合 → サイレントで自動割り当て（文字の順序で 1 つずつ）
• 設定されていない場合 → shared/speaker-selection.md の 組み込みデフォルト を使用（最初の文字にプライマリ、次にセカンダリ）
• ユーザーが明示的に音声を変更するよう要求した場合のみ話者選択を表示

ステップ 3: 設定を保存

すべての音声が割り当てられた後（新しい音声がある場合）:

質問: 「これらの音声割り当てを今後のセッションのために保存しますか?」
オプション:
  - 「はい」 — .listenhub/tts/config.json の defaultSpeakers を更新
  - 「いいえ」 — このセッションのみ使用

ステップ 4: 確認

生成準備完了:

  文字:
    {name}: {voice}
    {name}: {voice}
  セグメント: {count}
  タイトル: (自動生成)

進行しますか?

ステップ 5: 生成

話者マーカー付きのスクリプトテキストをフォーマットして送信。複数話者スクリプトの場合、スピーカー名をテキストにインライン含める。スクリプトモードはより時間がかかる可能性があるため、run_in_background: true で実行。

送信（フォアグラウンド） --no-wait 付き:

RESULT=$(listenhub tts create --text "{話者マーカー付きフォーマット済みスクリプト}" --mode smart --speaker "{name1}" --speaker "{name2}" --lang {lang} --no-wait --json)
ID=$(echo "$RESULT" | jq -r '.id')
echo "Submitted: $ID"

長いスクリプトの場合、最初に一時ファイルに書き込む:

cat > /tmp/lh-content.txt << 'ENDCONTENT'
SpeakerA: First line of dialogue
SpeakerB: Second line of dialogue
...
ENDCONTENT

RESULT=$(listenhub tts create --text "$(cat /tmp/lh-content.txt)" --mode smart --speaker "{name1}" --speaker "{name2}" --lang {lang} --no-wait --json)
ID=$(echo "$RESULT" | jq -r '.id')

rm -f /tmp/lh-content.txt

ポーリング（バックグラウンド） run_in_background: true と timeout: 600000 で:

ID="<id-from-above>"
for i in $(seq 1 60); do
  RESULT=$(listenhub creation get "$ID" --json 2>/dev/null)
  STATUS=$(echo "$RESULT" | jq -r '.status // "processing"')

  case "$STATUS" in
    completed) echo "$RESULT"; exit 0 ;;
    failed) echo "FAILED: $RESULT" >&2; exit 1 ;;
    *) sleep 10 ;;
  esac
done
echo "TIMEOUT" >&2; exit 2

ステップ 6: 結果を表示

バックグラウンドタスクが完了したら、結果を解析:

AUDIO_URL=$(echo "$RESULT" | jq -r '.audioUrl')
SUBTITLES_URL=$(echo "$RESULT" | jq -r '.subtitlesUrl // empty')
DURATION=$(echo "$RESULT" | jq -r '.audioDuration // empty')
CREDITS=$(echo "$RESULT" | jq -r '.credits // empty')

設定から OUTPUT_MODE を読む。shared/output-mode.md の動作に従う。

inline または both: audioUrl と subtitlesUrl をクリック可能なリンクとして表示。

表示:

Audio generated!

在线收听：{audioUrl}
字幕：{subtitlesUrl}
时长：{audioDuration / 1000}s
消耗积分：{credits}

download または both: ファイルもダウンロード。shared/config-pattern.md § Artifact Naming に従ってトピックスラグを生成。

SLUG="{topic-slug}"  # 例: "welcome-dialogue"
NAME="${SLUG}.mp3"
# 重複排除: ファイルが存在する場合は -2, -3 を追加
BASE="${NAME%.*}"; EXT="${NAME##*.}"; i=2
while [ -e "$NAME" ]; do NAME="${BASE}-${i}.${EXT}"; i=$((i+1)); done
curl -sS -o "$NAME" "$AUDIO_URL"

表示:

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

---

設定を更新

設定を保存する場合、.listenhub/tts/config.json にマージする — 変更されていないキーを上書きしない。

• クイック音声: defaultSpeakers.{language}[0] を選択された speakerId に設定
• スクリプト音声: defaultSpeakers.{language} をこのセッションで割り当てられた完全な配列に設定
• 言語: ユーザーが明示的に指定した場合は language に設定

API リファレンス

• CLI 実行パターン: shared/cli-patterns.md
• CLI 認証: shared/cli-authentication.md
• スピーカーリスト: shared/cli-speakers.md
• 話者選択ガイド: shared/speaker-selection.md
• 設定パターン: shared/config-pattern.md
• 出力モード: shared/output-mode.md

合成可能性

• 呼び出す: speakers CLI（話者選択用）
• 呼び出される: explainer（ボイスオーバー用）

例

クイックモード:

「TTS this: The server will be down for maintenance at midnight.」

1. 検出: クイックモード（プレーンテキスト、「TTS this」）
2. 設定を読む: defaultSpeakers.en は空
3. 組み込みデフォルトを使用: Mars (cozy-man-english)
4. 確認 → ユーザーが承認
5. 生成:

   RESULT=$(listenhub tts create --text "The server will be down for maintenance at midnight." --mode direct --speaker "Mars" --lang en --json)
   AUDIO_URL=$(echo "$RESULT" | jq -r '.audioUrl')
   

6. 表示: audioUrl をリンクとして表示（インラインモード）

スクリプトモード:

「帮我做一段双人对话配音，A说：欢迎大家，B说：谢谢邀请」

1. 検出: スクリプトモード（「双人对话」）
2. セグメントを解析: A -> 「欢迎大家」、B -> 「谢谢邀请」
3. 設定を読む: defaultSpeakers.zh は空
4. 組み込みデフォルトを使用: 原野（プライマリ）+ 高晴（セカンダリ）
5. 確認 → ユーザーが承認
6. 生成:

   RESULT=$(listenhub tts create --text "A: 欢迎大家
   B: 谢谢邀请" --mode smart --speaker "原野" --speaker "高晴" --lang zh --no-wait --json)
   ID=$(echo "$RESULT" | jq -r '.id')
   

7. 完了までバックグラウンドでポーリング
8. 表示: audioUrl、subtitlesUrl、期間