tts

テキスト読み上げ

${CLAUDE_SKILL_DIR}/scripts/tts のランチャーを実行します。これは、このスキルのディレクトリ内にある scripts/tts です。以下では tts と表記します。初回実行時に約 7 MB のバイナリをダウンロードし、実行前に SHA-256 を検証します。

各 tts コマンドは、それぞれ個別の Bash 呼び出しとして実行してください。;、&&、パイプで連結しないでください。これにより、スキルで事前承認された権限の範囲内に保たれます。

用途は 2 つあります。

• 動画のナレーション： tts render を使います。ファイルと、動画の残りの制作工程で使うタイミングマニフェストを生成します。
• 音声での読み上げ： tts "text" を使います。スピーカーから音声を再生し、すぐに戻ります。

動画のナレーション

1. スクリプトを作成する

シーンまたはショットごとに 1 セグメントを作成し、音声と映像のタイミングが合うよう、動画のシーン ID を再利用します。

{
  "provider": "elevenlabs",
  "voice": "JBFqnCBsd6RMkjVDRZzb",
  "instructions": "warm, confident product narrator",
  "pause": 0.5,
  "segments": [
    {"id": "01-intro",   "text": "Meet the new Insights dashboard."},
    {"id": "02-filters", "text": "Filter any chart in one click: by team, by service, or by release."},
    {"id": "03-alerts",  "text": "Set an alert once, and we'll tell you the moment a metric drifts.", "pause": 1.0},
    {"id": "04-outro",   "text": "Insights is available today, on every plan."}
  ]
}

• トップレベルのフィールド（provider、voice、model、instructions、speed、pause）は、すべてのセグメントに適用されます。各セグメントでは、voice、model、instructions、speed、pause を上書きできます。pause は、結合したトラックでそのセグメントの後に入る無音時間です。
• 動画全体でプロバイダーと音声を統一します。 1 人のナレーターが話しているように聞こえます。
• 耳で聞いてわかりやすい文章にします。 文は短くし、数字は読み上げる形（「forty percent」「version two」など）にし、Markdown は使いません。製品名が正しく発音されない場合は、text に発音を表す綴りを記載します。
• プロバイダーと音声を選ぶ。 スクリプトにプロバイダーが設定されておらず、tts config show に voiceover_provider もない場合は、使用するプロバイダーと音声をユーザーに確認します。比較できるよう、tts -o sample-NAME.wav -p PROVIDER -v VOICE "One line of the script." で短いサンプルを生成します。選択内容を保存する場合は、tts config set voiceover_provider NAME と tts config set NAME.voice VOICE を案内します。Kokoro と system は無料でローカルで動作します。それ以外は有料です。最も自然に聞こえるのは、ElevenLabs、instructions を指定した OpenAI、Gemini です。

2. レンダリングする

"${CLAUDE_SKILL_DIR}/scripts/tts" render script.json -o voiceover/

次のファイルが出力されます。

• 各セグメントの voiceover/<id>.wav。先頭と末尾の無音部分は、再生時間が正確になるようにトリミングされます。
• すべてのセグメントを間のポーズとともに結合した voiceover/voiceover.wav。
• 字幕の voiceover/voiceover.srt。
• voiceover/manifest.json。このファイルの内容は標準出力にも表示されます。

{"provider": "elevenlabs", "sample_rate": 24000, "channels": 1, "duration": 17.08,
 "combined": {"file": "/abs/voiceover/voiceover.wav", "duration": 17.08},
 "captions": "/abs/voiceover/voiceover.srt",
 "segments": [{"id": "01-intro", "file": "/abs/voiceover/01-intro.wav", "duration": 3.872,
               "start": 0, "end": 3.872, "text": "...", "voice": "...", "cached": false}, ...]}

レンダリングオプション：

• --format mp3|m4a は、結合トラックの形式を指定します。
• --no-combine は、セグメントごとのファイルのみを出力します。
• -p/-v/-i/-s は、スクリプトで指定されていない項目のデフォルトを設定します。
• --jobs N は並列実行数を設定します。

render は、モデルが指定されていない場合、各プロバイダーの最高品質モデルを使用します。対象は eleven_multilingual_v2 と gemini-3.8-flash-tts です。

3. タイミングを使用する

• シーンの長さ： 各シーンは、そのセグメントの duration 以上の長さにします。間に少し余裕を持たせるか、シーンを伸ばして長さを合わせます。
• 音声の配置： 各セグメントのファイルを対応するシーンの開始時刻に配置するか、voiceover.wav を単一のトラックとして使い、start／end をオフセットとして指定します。
• ffmpeg での多重化：
  • トラック全体の場合：ffmpeg -i video.mp4 -i voiceover/voiceover.wav -map 0:v -map 1:a -c:v copy -c:a aac -shortest out.mp4
  • 4.47 秒の位置に 1 つのセグメントを配置する場合は、入力に -i voiceover/02-filters.wav を追加し、続けて -filter_complex "[1]adelay=4470:all=1[a]" -map 0:v -map "[a]" を指定します。

4. 調整を繰り返す

スクリプトを編集し、同じコマンドを再実行します。テキスト、音声、モデル、スタイル、速度が前回のレンダリングから変わっていないセグメントは再利用されます（"cached": true）。変更されたセグメントのみが再レンダリングされ、課金対象になります。すべてを再レンダリングするには --force を使います。一部のセグメントが失敗しても、ほかのセグメントは保持されます。再実行すると、失敗したセグメントのみが再試行されます。

音声で読み上げる

"${CLAUDE_SKILL_DIR}/scripts/tts" "The build passed and all 214 tests are green."
"${CLAUDE_SKILL_DIR}/scripts/tts" <<'EOF'
Longer text, or anything with quotes, goes on stdin.
EOF

音声の再生が始まるとコマンドは終了し、再生はバックグラウンドで続きます。新しい読み上げを開始すると現在の読み上げは中断されます。-q を指定するとキューに追加され、tts stop を実行するとすべての再生が停止します。

その他のオプション：

• -p プロバイダー、-v 音声、-i "style"、-s 速度を指定します。
• -w を指定すると、再生が終わるまで待機します。
• -o FILE [--json] を指定すると、再生の代わりにファイルへ出力します。--json を指定すると、再生時間とパスが表示されます。

読み上げるときは：

• 要約して読み上げ、全文をそのまま読み上げないでください。 全文の読み上げを求められた場合を除き、読み上げる文は2〜4文にしてください。
• コードは読み上げず、言葉で説明してください。 Markdown とコードブロックは自動的に除去されます。
• 通知は短くし、 続けて通知する場合は -q を使ってください。

プロバイダー、費用、プライバシー

• 設定済みのデフォルト（tts config show）を使用してください。ユーザーまたはスクリプトがプロバイダーを指定した場合に限り、-p を渡します。
• system と kokoro はこのマシン上で動作し、無料です。その他のプロバイダーはテキストを各社に送信し、ユーザーのアカウントに請求します。確認せずにデフォルトのプロバイダーを変更してはいけません。
• シークレット、認証情報、個人データをクラウドプロバイダーに送信してはいけません。
• 有料プロバイダーは、1コマンドあたり20,000文字を超える新規テキストを受け付けません。テキストを短くするか、すべてを読み上げたい場合は --max-chars N を渡してください。

セットアップとトラブルシューティング

• tts doctor を実行すると、音声出力、デフォルトのプロバイダー、利用可能なプロバイダーが表示されます。
• tts providers と tts voices -p NAME [filter] を実行すると、プロバイダーと音声の一覧が表示されます。
• tts config set KEY VALUE でデフォルトを設定します。キーは provider、voiceover_provider、max_chars、および NAME.voice|model|speed|instructions|base_url です。
• API キーが見つからない場合： 環境変数（例：ELEVENLABS_API_KEY）を設定するか、自身のターミナルで tts auth set elevenlabs を実行するようユーザーに伝えてください。チャットにキーを貼り付けるよう求めたり、コマンドラインにキーを指定したりしてはいけません。
• 未テストのクラウドプロバイダー： openai、gemini、cartesia、deepgram は、まだ実際の API でテストされていません。テスト済みなのは system、kokoro、elevenlabs のみです。これらの未テストのプロバイダーが、リクエスト自体に関するエラー（不明なフィールド、無効なパラメーター、予期しない応答）で失敗した場合、ユーザーの操作ではなく、このスキルのバグである可能性が高いです。正確なエラーをユーザーに示し、github.com/captjt/skill-tts/issues への報告を提案して、代替手段として kokoro または system を案内してください。推測したパラメーターで再試行を続けてはいけません。認証エラー（401/403）とクォータエラー（429）は、通常どおりユーザー側で解決する必要があります。
• Kokoro に接続できない場合： docker run -d --name kokoro -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.9.0 を実行して起動します。
• 音声デバイスがない場合（SSH、コンテナー）：render または -o を使ってください。スピーカーは不要です。

各プロバイダーの音声、モデル、オプションについては、references/providers.md を参照してください。