speech

Speech Generation Skill

現在のプロジェクト向けに音声を生成します（ナレーション、プロダクトデモのボイスオーバー、IVR プロンプト、アクセシビリティ向けの読み上げなど）。デフォルトは gpt-4o-mini-tts-2025-12-15 を使用する OpenAI で、Atlas Cloud はユーザーが明示的に選択した場合のみ利用できます。再現性のある安定した実行のため、同梱の CLI の利用を優先します。

使用するタイミング

• テキストから単一の音声クリップを生成する
• プロンプトのバッチ（多数の行、多数のファイル）を生成する

判断フロー（単一かバッチか）

• ユーザーが複数の行／プロンプトを提供した場合、または多数の出力を求めている場合 -> バッチ
• それ以外 -> 単一

ワークフロー

1. 意図を判断する：単一かバッチか（上記の判断フローを参照）。
2. 事前に入力を収集する：正確なテキスト（原文のまま）、希望する音声、話し方のスタイル、形式、および制約事項。
3. バッチの場合：tmp/ 配下に一時的な JSONL を作成し（1 行に 1 ジョブ）、一度で実行してから、JSONL を削除する。
4. 入力テキストを書き換えず、指示内容を短いラベル付きの仕様に整える。
5. デフォルトの OpenAI パスでは scripts/text_to_speech.py を、Atlas Cloud が選択された場合のみ scripts/atlas_text_to_speech.py を実行する（references/cli.md を参照）。
6. 重要なクリップについては、聞き取りやすさ、話すペース、発音、制約への適合を検証する。
7. 音声、速度、または指示のいずれか一つだけを対象を絞って変更し、再確認しながら反復する。
8. 最終出力を保存・返却し、最終テキスト、指示内容、使用したフラグを記載する。

一時ファイルと出力の規則

• 中間ファイル（例：JSONL バッチ）には tmp/speech/ を使用し、完了後に削除する。
• このリポジトリで作業する場合、最終成果物は output/speech/ 配下に書き出す。
• 出力パスの制御には --out または --out-dir を使用する。ファイル名は安定させ、内容が分かる名前にする。

依存関係（不足している場合はインストール）

依存関係の管理には uv を優先して使用します。

OpenAI バックエンドのパッケージ：

uv pip install openai

uv が利用できない場合：

python3 -m pip install openai

Atlas Cloud バックエンドは Python 標準ライブラリのみを使用します。

環境

• デフォルトの OpenAI 呼び出しには OPENAI_API_KEY が必要です。
• 任意の Atlas Cloud 呼び出しには ATLASCLOUD_API_KEY が必要です。

選択したプロバイダーのキーが設定されていない場合は、ユーザーに次の手順を案内してください。

1. そのプロバイダーのコンソールで API キーを作成する。
2. システムの環境変数として OPENAI_API_KEY または ATLASCLOUD_API_KEY を設定する。
3. 必要に応じて、利用している OS／シェルでの環境変数の設定方法をガイドすることを申し出る。

• プロバイダーの認証情報はチャットに入力させないでください。選択したキーはユーザーのローカル環境で設定してもらい、準備ができたら確認してもらいます。

この環境でインストールできない場合は、不足している依存関係と、ローカルでのインストール方法をユーザーに伝えてください。

デフォルトとルール

• デフォルトのプロバイダーは OpenAI のままにします。ユーザーが要求しない限り Atlas Cloud に切り替えないでください。
• ユーザーが別のモデルを要求しない限り、gpt-4o-mini-tts-2025-12-15 を使用します。
• デフォルトの音声は cedar です。より明るいトーンが必要な場合は marin を優先します。
• 組み込みの音声のみを使用します。カスタム音声はこのスキルの対象外です。
• instructions は GPT-4o mini TTS モデルでサポートされていますが、tts-1 や tts-1-hd ではサポートされていません。
• 入力の長さは 1 リクエストあたり 4096 文字以下でなければなりません。それより長いテキストはチャンクに分割します。
• 1 分あたり 50 リクエストに制限します。CLI は --rpm を 50 で上限設定しています。
• ライブ API を呼び出す前に、必ず OPENAI_API_KEY を確認してください。
• Atlas Cloud では、デフォルトで xai/tts-v1、音声 eve、言語 auto を使用し、ATLASCLOUD_API_KEY を必須とします。
• Atlas の生成では POST を正確に 1 回だけ送信します。リトライが許可されるのは予測（prediction）の GET リクエストのみで、ポーリングは有限回に制限しなければなりません。
• Atlas の出力をダウンロードする際は Authorization ヘッダーを付けず、HTTPS 以外のURLやプライベートネットワーク上の宛先は拒否します。
• 音声が AI によって生成されていることを、エンドユーザーに明確に開示してください。
• デフォルトの OpenAI 呼び出しには OpenAI Python SDK（openai パッケージ）を使用します。専用の Atlas CLI は非同期 HTTP の仕様を使用します。
• 新たに単発のスクリプトを書くよりも、対応する同梱 CLI の利用を優先します。

指示の補強

ユーザーの指示を、短くラベル付けされた仕様に整形します。暗黙の詳細を明示するだけにとどめ、新しい要件を勝手に作らないでください。

簡単な補足（補強と創作の違い）:

• ユーザーが「デモ用のナレーション」と述べた場合、それに含意される提供上の制約（明瞭で安定したペース、親しみやすい口調）を追加してかまいません。
• ユーザーが要求していないペルソナ、アクセント、感情表現を新たに導入しないでください。

テンプレート（関連する行のみ含める）:

Voice Affect: <overall character and texture of the voice>
Tone: <attitude, formality, warmth>
Pacing: <slow, steady, brisk>
Emotion: <key emotions to convey>
Pronunciation: <words to enunciate or emphasize>
Pauses: <where to add intentional pauses>
Emphasis: <key words or phrases to stress>
Delivery: <cadence or rhythm notes>

補強のルール:

• 短く保ち、ユーザーがすでに示唆または他の箇所で提供した詳細のみを追加してください。
• 入力テキストを書き直さないでください。
• 成功を妨げる重要な詳細が欠けている場合は質問してください。そうでなければ処理を進めてください。

例

単一の例（ナレーション）

Input text: "Welcome to the demo. Today we'll show how it works."
Instructions:
Voice Affect: Warm and composed.
Tone: Friendly and confident.
Pacing: Steady and moderate.
Emphasis: Stress "demo" and "show".

バッチの例（IVR プロンプト）

{"input":"Thank you for calling. Please hold.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
{"input":"For sales, press 1. For support, press 2.","voice":"marin","instructions":"Tone: Clear and neutral. Pacing: Slow.","response_format":"wav"}

指示のベストプラクティス（短いリスト）

• 指示は「態度 → 口調 → ペース → 感情 → 発音／間 → 強調」の順に構成してください。
• 短い行を 4〜8 行に抑え、矛盾するガイダンスを避けてください。
• 名前や頭字語には発音のヒントを追加してください（例: 「A-I を一音ずつ明瞭に」）。または本文中に音声表記を示してください。
• 編集や反復の際は、ドリフトを減らすために不変の条件を繰り返してください（例: 「ペースは一定に保つ」）。
• 1 回につき 1 つの変更にとどめて、段階的に修正してください。

その他の原則: references/prompting.md。コピー＆ペースト用の仕様: references/sample-prompts.md。

ユースケース別のガイダンス

特定の提供スタイルを求める場合は、以下のモジュールを使用してください。それぞれ目的に合わせたデフォルト設定とテンプレートを提供します。

• ナレーション／解説: references/narration.md
• 製品デモ／ボイスオーバー: references/voiceover.md
• IVR／電話音声プロンプト: references/ivr.md
• アクセシビリティ向け読み上げ: references/accessibility.md

CLI と環境に関する注意

• CLI コマンドと例: references/cli.md
• API パラメーターのクイックリファレンス: references/audio-api.md
• Atlas Cloud の非同期ワークフローと安全対策: references/atlas-cloud.md
• 指示パターンと例: references/voice-directions.md
• ネットワークの承認やサンドボックス設定が障害になっている場合: references/codex-network.md

リファレンスマップ

• references/cli.md: scripts/text_to_speech.py を使って音声生成／バッチを実行する方法（コマンド、フラグ、レシピ）。
• references/audio-api.md: API パラメーター、制限、ボイス一覧。
• references/atlas-cloud.md: オプションの Atlas Cloud モデル、CLI、ポーリング、ダウンロードの仕様。
• references/voice-directions.md: 指示パターンと例。
• references/prompting.md: 指示のベストプラクティス（構成、制約、反復パターン）。
• references/sample-prompts.md: コピー＆ペースト用の指示レシピ（例のみ。追加の理論は含まない）。
• references/narration.md: ナレーションと解説のテンプレートとデフォルト設定。
• references/voiceover.md: 製品デモのボイスオーバーのテンプレートとデフォルト設定。
• references/ivr.md: IVR／電話音声プロンプトのテンプレートとデフォルト設定。
• references/accessibility.md: アクセシビリティ向け読み上げのテンプレートとデフォルト設定。
• references/codex-network.md: 環境／サンドボックス／ネットワーク承認のトラブルシューティング。