speech

音声生成スキル

現在のプロジェクト向けに、ナレーション、製品デモのナレーション、IVR プロンプト、アクセシビリティ向け読み上げなどの音声を生成します。デフォルトでは gpt-4o-mini-tts-2025-12-15 と組み込み音声を使用し、再現性のある決定的な実行を優先して、同梱の CLI を使用します。

使用する場面

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

判断基準（単一か一括か）

• ユーザーが複数の行やプロンプトを提示した場合、または多数の出力を希望する場合 -> 一括
• それ以外 -> 単一

ワークフロー

1. 目的を判断します。単一か一括かを選びます（上記の判断基準を参照）。
2. 必要な情報を最初に集めます。正確なテキスト（原文どおり）、希望する音声、話し方、形式、制約を確認します。
3. 一括の場合は、tmp/ の下に一時的な JSONL を作成し（1 行につき 1 件）、一度実行した後、JSONL を削除します。
4. 入力テキストを書き換えずに、指示を短いラベル付き仕様にまとめます。
5. 適切なデフォルトを使用して、同梱の CLI（scripts/text_to_speech.py）を実行します（references/cli.md を参照）。
6. 重要なクリップについては、明瞭さ、ペース、発音、制約への準拠を検証します。
7. 変更点を 1 つ（音声、速度、または指示）に絞って反復し、再確認します。
8. 最終出力を保存または返し、使用した最終テキスト、指示、フラグを記録します。

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

• 中間ファイル（JSONL の一括処理など）には tmp/speech/ を使用し、完了後に削除します。
• このリポジトリで作業する場合、最終成果物は output/speech/ の下に保存します。
• 出力先の指定には --out または --out-dir を使用し、ファイル名は安定したわかりやすいものにします。

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

依存関係の管理には uv を優先してください。

Python パッケージ：

uv pip install openai

uv を利用できない場合：

python3 -m pip install openai

環境

• ライブ API 呼び出しには OPENAI_API_KEY を設定する必要があります。

キーがない場合は、次の手順をユーザーに案内します。

1. OpenAI プラットフォーム UI で API キーを作成します：https://platform.openai.com/api-keys
2. システムの環境変数として OPENAI_API_KEY を設定します。
3. 必要であれば、使用している OS／シェルでの環境変数の設定方法を案内します。

• チャットでキー全体を貼り付けるようユーザーに求めてはいけません。ローカルで設定し、準備ができたら知らせてもらいます。

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

デフォルトとルール

• ユーザーが別のモデルを希望しない限り、gpt-4o-mini-tts-2025-12-15 を使用します。
• デフォルトの音声は cedar です。より明るいトーンを希望する場合は、marin を優先します。
• 使用できるのは組み込み音声のみです。このスキルではカスタム音声は対象外です。
• instructions は GPT-4o mini TTS モデルでサポートされていますが、tts-1 または tts-1-hd ではサポートされていません。
• リクエストごとの入力は 4096 文字以下にする必要があります。これを超えるテキストは分割します。
• 1 分あたりのリクエスト数は 50 件に制限します。CLI の --rpm の上限は 50 です。
• ライブ API を呼び出す前に OPENAI_API_KEY が設定されていることを必ず確認します。
• 音声が AI によって生成されたことを、エンドユーザーに明確に伝えます。
• すべての API 呼び出しには OpenAI Python SDK（openai パッケージ）を使用します。生の HTTP は使用しません。
• 新たな使い捨てスクリプトを作成するより、同梱の CLI（scripts/text_to_speech.py）を優先します。
• scripts/text_to_speech.py は絶対に変更しません。不足している機能がある場合は、ほかの作業をする前にユーザーに確認します。

指示の補足

ユーザーの指示を、短いラベル付き仕様にまとめます。暗黙の詳細を明示する場合に限り、明示してください。新たな要件を追加してはいけません。

簡単な確認（補足と創作の違い）：

• ユーザーが「デモのナレーション」と言った場合、明瞭で一定のペース、親しみやすいトーンなど、暗黙の話し方の条件を補足できます。
• ユーザーが求めていない新しいペルソナ、アクセント、感情的なスタイルを加えてはいけません。

テンプレート（該当する行のみ含めます）：

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つだけ変更して反復します。

その他の原則：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
• 指示のパターンと例：references/voice-directions.md
• ネットワークの承認やサンドボックスの設定が妨げになっている場合：references/codex-network.md

リファレンス一覧

• references/cli.md：scripts/text_to_speech.pyを使って音声生成や一括処理を実行する方法（コマンド、フラグ、レシピ）。
• references/audio-api.md：API パラメーター、制限、音声一覧。
• 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：環境、サンドボックス、ネットワーク承認に関するトラブルシューティング。