speech

语音生成技能

为当前项目生成语音音频（旁白、产品演示配音、IVR 提示、无障碍朗读）。OpenAI 仍是默认选项，使用 gpt-4o-mini-tts-2025-12-15；只有用户明确选择 Atlas Cloud 时才可使用。优先使用随附的 CLI，以确保运行结果确定且可复现。

适用场景

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

决策树（单条与批量）

• 如果用户提供了多行文本／多个提示词，或需要多个输出 → 批量
• 否则 → 单条

工作流

1. 确定需求：单条还是批量（见上方决策树）。
2. 提前收集输入：确切文本（逐字照录）、所需语音、表达风格、格式及任何限制。
3. 如果是批量：在 tmp/ 下写入临时 JSONL（每行一个任务），运行一次，然后删除 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. 如有需要，可提供协助，指导他们为其操作系统／shell 设置环境变量。

• 不要在聊天中泄露提供方凭据。请用户在本地设置所选密钥，并在准备就绪后确认。

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

默认设置与规则

• 默认使用 OpenAI。除非用户提出要求，否则不要切换到 Atlas Cloud。
• 除非用户要求使用其他模型，否则使用 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。
• 对于 Atlas Cloud，默认使用 xai/tts-v1、语音 eve、语言 auto，并且必须确保存在 ATLASCLOUD_API_KEY。
• Atlas 生成只提交一次 POST。只有预测 GET 请求可以重试，并且轮询必须有次数限制。
• 下载 Atlas 输出时不要附带 Authorization 标头，并拒绝非 HTTPS 或指向私有网络的目标。
• 明确告知最终用户语音由 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”），或在文本中提供音标拼写。
• 对于编辑/迭代，重复不变要求（例如“保持节奏平稳”），以减少偏移。
• 通过每次只做一项更改的后续指示进行迭代。

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