speech

语音生成技能

为当前项目生成语音音频（旁白、产品演示配音、IVR 提示词、无障碍朗读）。默认使用 gpt-4o-mini-tts-2025-12-15 和内置语音，并优先使用捆绑的 CLI，以确保运行结果确定且可复现。

适用场景

• 根据文本生成单条语音片段
• 批量生成提示词（多行、多文件）

决策树（单条还是批量）

• 如果用户提供多行/多个提示词，或需要大量输出 -> 批量
• 否则 -> 单条

工作流

1. 判断意图：单条还是批量（参见上方决策树）。
2. 提前收集输入：准确文本（逐字照录）、所需语音、表达风格、格式和任何约束。
3. 如果是批量：在 tmp/ 下编写临时 JSONL（每行一个任务），运行一次，然后删除 JSONL。
4. 将指示补充整理成简短的带标签规范，不要改写输入文本。
5. 使用合理的默认值运行捆绑的 CLI（scripts/text_to_speech.py）（参见 references/cli.md）。
6. 对重要片段进行验证：清晰度、节奏、发音，以及是否遵守约束。
7. 只针对一项内容进行调整（语音、速度或指示），然后重新检查。
8. 保存/返回最终输出，并注明最终文本、指示和使用的标志。

临时文件和输出约定

• 使用 tmp/speech/ 存放中间文件（例如 JSONL 批次文件）；完成后删除。
• 在此仓库中工作时，将最终产物写入 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. 如有需要，可提供帮助，指导其为所用操作系统/命令行 Shell 设置环境变量。

• 切勿要求用户在聊天中粘贴完整密钥。请用户在本地设置，并在准备就绪后确认。

如果无法在此环境中安装依赖项，请告知用户缺少哪项依赖项，以及如何在本地安装。

默认值和规则

• 除非用户要求其他模型，否则使用 gpt-4o-mini-tts-2025-12-15。
• 默认语音：cedar。如果用户想要更明亮的音色，优先使用 marin。
• 仅使用内置语音。自定义语音不在此技能的范围内。
• GPT-4o mini TTS 模型支持 instructions，但 tts-1 或 tts-1-hd 不支持。
• 每次请求的输入长度必须 <= 4096 个字符。较长文本应拆分成多个片段。
• 每分钟最多 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。如果缺少所需功能，先询问用户，再进行其他操作。

指示补充

将用户的指示重新整理成简短的带标签规范。只明确隐含细节；不要凭空添加新要求。

快速澄清（补充 vs 臆造）：

• 如果用户说“为演示配旁白”，可以补充隐含的表达要求（清晰、节奏平稳、语气友好）。
• 不要添加用户未要求的人设、口音或情绪风格。

模板（仅包含相关行）：

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 读清楚”），或在文本中提供音标拼写。
• 对于编辑/迭代，重复不变的要求（例如，“保持节奏稳定”），以减少偏移。
• 通过后续提示，每次只做一项更改。

更多原则：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：环境/沙盒/网络审批故障排查。