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 § 成果物の命名を参照）

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

モードの判定

質問をする前に、ユーザーの入力からモードを自動的に判定してください。

シグナル	モード
「多角色」「脚本」「对话」「script」「dialogue」「multi-speaker」	台本
名前または役割で複数の登場人物が示されている	台本
入力に構造化されたセグメント（A: ...、B: ...）が含まれている	台本
登場人物のマーカーがない単一の段落テキスト	クイック
「读一下」「read this」「TTS」「朗读」とプレーンテキストが含まれている	クイック
判定できない場合	クイック（デフォルト）

インタラクションの流れ

ステップ -1：CLI 認証の確認

shared/cli-authentication.md に従ってください。CLI がインストールされていない場合、またはユーザーがログインしていない場合は、自動でインストールしてログインしてください。ユーザーにコマンドの手動実行を依頼してはいけません。

次に、shared/cli-authentication.md § 認証モードの判定に従って AUTH_MODE を判定し、次を設定してください。

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

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

ステップ 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 § 設定フローの質問に従ってください。

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

   • 「中文 (zh)」
   • 「English (en)」
   • 「毎回手動で選択」→ null のままにします

回答を収集したら、ただちに保存します。

NEW_CONFIG=$(echo "$CONFIG" | jq --arg m "$OUTPUT_MODE" '. + {"outputMode": $m}')
# Save language if user chose one (not "每次手动选择")
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")

生成速度

デフォルト：1.0x（元の速度）。速度について尋ねないでください。

ユーザーが明示的に速く、または遅く読むよう求めた場合にのみ --speed を指定します。 「ゆっくり」「速く」「1.25 倍速で」「もっと速く読んで」などの指示がない場合は、フラグを省略してください。

• 範囲：0.5 から 2.0 までの任意の値（小数点以下最大 2 桁）。固定の刻み幅ではなく、連続した範囲です。
• 一般的な値：0.5、0.75、1（デフォルト）、1.25、1.5、2。0.85 や 1.35 などの中間値も使用できます。
• 意味：生成された音声の話速であり、プレーヤーの再生速度ではありません。
• あいまいな表現は控えめに対応付けます：「ゆっくり」→ 0.85、「速く」→ 1.25、「かなりゆっくり」→ 0.5、「かなり速く」→ 1.75。ユーザーが指定した数値は変更せずに使用します。

速度が 1 以外の場合にのみ、確認の概要に速度を表示してください。

クイックモード — $CMD_PREFIX create --mode direct

Step 1：テキストを抽出する

変換するテキストを取得します。ユーザーがまだテキストを提供していない場合は、次のように尋ねます。

「読み上げるテキストを教えてください。」

Step 2：音声を決定する

• config.defaultSpeakers.{language}[0] が設定されている場合 → 何も伝えずに使用します（Step 4 に進みます）
• 設定されていない場合 → 検出した言語に対応する shared/speaker-selection.md の組み込みデフォルトを使用します（Step 4 に進みます）
• ユーザーが音声の変更を明示的に求めた場合にのみ、音声の選択肢を表示します

Step 3：設定を保存する

ユーザーが新しい音声を明示的に選択した後（デフォルトの使用時は除く）：

Question: "Save {voice name} as your default voice for {language}?"
Options:
  - "Yes" — update .listenhub/tts/config.json
  - "No" — use for this session only

Step 4：確認する

Ready to generate:

  Text: "{first 80 chars}..."
  Voice: {voice name}
  Speed: {speed}x        # omit this line when speed is 1

Proceed?

Step 5：生成する

短いテキストの場合は、インラインで渡します。

RESULT=$($CMD_PREFIX create --text "{text}" --mode direct --speaker "{name}" --lang {lang} [--speed {0.5-2.0}] --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'
Long text content goes here...
ENDCONTENT

RESULT=$($CMD_PREFIX create --text "$(cat /tmp/lh-content.txt)" --mode direct --speaker "{name}" --lang {lang} [--speed {0.5-2.0}] --json)
AUDIO_URL=$(echo "$RESULT" | jq -r '.audioUrl')

rm -f /tmp/lh-content.txt

Step 6：結果を提示する

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

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

次のように提示します。

Audio generated!

在线收听：{audioUrl}

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

SLUG="{topic-slug}"  # e.g. "server-maintenance-notice"
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" "$AUDIO_URL"

次のように提示します。

Audio generated!

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

---

スクリプトモード — $CMD_PREFIX create --mode smart

Step 1：スクリプトを取得する

ユーザーがすでにスクリプトの配列を用意しているかどうかを判断します。

• すでに提供されている（JSON または明確に区切られたセグメント）：解析して確認用に表示します

• まだ提供されていない：セグメントの構成をユーザーに案内します。次のように尋ねます。

  「話者の割り当てを含むスクリプトを入力してください。形式：各行を SpeakerName: text content のように記述します。こちらで変換します。」

  ユーザーがスクリプトを入力したら、話者情報付きテキストに解析します。

Step 2：登場人物ごとに音声を割り当てる

スクリプト内の固有の登場人物ごとに、次のように処理します。

• config.defaultSpeakers.{language} に保存済みの音声がある場合 → 登場人物の順番に 1 人ずつ、何も伝えずに自動で割り当てます
• 設定されていない場合 → shared/speaker-selection.md の組み込みデフォルトを使用します（最初の登場人物には Primary、2 人目には Secondary）
• ユーザーが音声の変更を明示的に求めた場合にのみ、音声の選択肢を表示します

Step 3：設定を保存する

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

Question: "Save these voice assignments for future sessions?"
Options:
  - "Yes" — update defaultSpeakers in .listenhub/tts/config.json
  - "No" — use for this session only

Step 4：確認する

Ready to generate:

  Characters:
    {name}: {voice}
    {name}: {voice}
  Segments: {count}
  Speed: {speed}x        # omit this line when speed is 1
  Title: (auto-generated)

Proceed?

Step 5：生成する

スクリプトテキストに話者マーカーを付けて送信します。複数話者のスクリプトでは、テキスト内に話者名を含めます。スクリプトモードは時間がかかる場合があるため、run_in_background: true を指定して実行します。

**送信（フォアグラウンド）**では --no-wait を指定します。

RESULT=$($CMD_PREFIX create --text "{formatted script with speaker markers}" --mode smart --speaker "{name1}" --speaker "{name2}" --lang {lang} [--speed {0.5-2.0}] --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=$($CMD_PREFIX create --text "$(cat /tmp/lh-content.txt)" --mode smart --speaker "{name1}" --speaker "{name2}" --lang {lang} [--speed {0.5-2.0}] --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

Step 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}"  # e.g. "welcome-dialogue"
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" "$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 にしてください：サーバーは午前 0 時にメンテナンスのため停止します。」

1. 判定：クイックモード（プレーンテキスト、「TTS にしてください」）
2. 設定を読み込みます：defaultSpeakers.en は空です
3. 組み込みのデフォルトを使用します：Mars（cozy-man-english）
4. 確認 → ユーザーが承認
5. 生成：

   RESULT=$($CMD_PREFIX 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 をリンクとして表示します（インラインモード）

スクリプトモード：

「2 人の会話の吹き替えを作って。A は「皆さん、ようこそ」、B は「お招きいただきありがとうございます」と話します」

1. 判定：スクリプトモード（「2 人の会話」）
2. セグメントを解析します：A -> 「皆さん、ようこそ」、B -> 「お招きいただきありがとうございます」
3. 設定を読み込みます：defaultSpeakers.zh は空です
4. 組み込みのデフォルトを使用します：原野（プライマリ）＋ 高晴（セカンダリ）
5. 確認 → ユーザーが承認
6. 生成：

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

7. 完了するまでバックグラウンドでポーリングします
8. 提示：audioUrl、subtitlesUrl、再生時間