speech

speech 技能概览

speech 技能能做什么

speech 技能可以把文本转成可朗读的音频，适用于旁白、配音、IVR 提示词、无障碍朗读和批量生成语音。它最适合需要从提示词中稳定产出可复现音频的场景，而不是那种笼统的“把它做得更好听一点”的需求。

适合谁使用

如果你需要 speech 安装后能真正融入实际工作流，就应该用它：比如产品演示、应用引导、无障碍素材，或者从结构化文本批量生成很多短音频。它在你关心音色选择、语速节奏、输出格式，以及多次运行结果一致性时，尤其合适。

它有什么不同

speech 指南围绕 OpenAI Audio API 和随附的 CLI 构建，因此更偏向确定性用法，而不是临时起意式的提示。它使用内置音色，支持单条或批量任务，并且在正式生成时需要 OPENAI_API_KEY。自定义音色创建不在这个仓库的范围内。

如何使用 speech 技能

安装并找到工作流

使用 npx skills add openai/skills --skill speech 安装。安装后，先读 SKILL.md，然后再看 references/cli.md 了解命令细节，查看 references/audio-api.md 了解模型和参数限制，再参考 references/prompting.md 或 references/voice-directions.md 来写更好的指令。想快速建立上下文，可以再看 agents/openai.yaml 和 references/sample-prompts.md。

把粗略目标变成可用提示词

speech 的使用方式最适合你把“要读什么内容、用什么声音、什么表达风格、什么输出格式、有没有发音限制”都说清楚。一个更好的请求会像这样：Generate a 45-second product demo voiceover from this script, use cedar, keep it warm and steady, output mp3, and emphasize the product name on first mention. 这比“让它听起来专业一点”有效得多，因为前者给了技能明确的合成控制参数。

单条流程与批量流程的区别

这个技能为两种路径而设计：生成一条音频，或者生成多条音频。如果你有多行文案、多个提示词或多个文件，就按批量处理，先在 tmp/ 下准备一个临时 JSONL 文件，然后一次性运行 CLI，使用完再删除 JSONL。如果只有一个脚本，就走单文件路径。这个选择很重要，因为输出量不同，技能的结构和校验步骤也会随之变化。

运行前要检查什么

想要最好效果，先逐字核对文本，而不只是确认主题。检查音色、文件格式、语速，以及输出到底需要偏中性、偏表现力，还是优先满足无障碍阅读。执行时主要需要查看的仓库文件是 scripts/text_to_speech.py；除非仓库维护者明确要求，不要自行修改它。

speech 技能 FAQ

speech 技能只适合旁白吗？

不是。speech 技能同样适用于配音、无障碍朗读、IVR 提示词，以及简短音频提示。它不太适合自定义声音克隆或创意化的音色设计，这个 repo 也不覆盖这些内容。

使用 speech 一定要用 CLI 吗？

如果你想稳定地使用 speech，答案是要。随附的 CLI 是正式进行实时生成的预期路径，而 --dry-run 适合在不发起 API 调用的情况下检查调用形状。如果你只写一个泛泛的提示词，就会失去让这个技能可复现的结构。

这个技能适合新手吗？

适合，只要你能提供准确文本和基本的声音方向。speech 的安装并不复杂，但输出质量取决于你把语速、语气、格式和发音要求说得多清楚。新手通常从短音频和单一音色开始，成功会更快。

什么情况下不该用这个技能？

如果你需要自定义音色创建、重度后期制作，或者依赖修改随附脚本的工作流，就不要用 speech。若你无法使用联网的 OpenAI API 调用，或者没有 OPENAI_API_KEY，它也不是合适选择。

如何改进 speech 技能

减少歧义，让技能少猜

speech 技能输出质量提升最大的方式，就是减少猜测空间。请提供完整原文，不要只给摘要；说明目标听众是谁；并明确这段朗读应该像旁白、客服消息、无障碍朗读，还是 IVR 提示词。如果某个词难读，就直接拼写出来，或者补充发音说明。

一次只调整一个变量

如果第一版已经接近预期但还不够好，就一次只改一项：音色、语速，或者指令风格。这样迭代会比重写整段提示词更清晰。比如，如果节奏听起来太赶，就保持文本和音色不变，只把语速从 1.0 调到 0.95。

使用真正有用的输出约束

当约束是可操作的，而不是空泛的，speech 指南的效果会更好。可以直接说“用 mp3 便于快速播放”、“用 wav 便于审听”，或者“无障碍场景要保持稳定、克制、偏中性”。如果是批量任务，每一行都要尽量聚焦，才能让技能在多个输出之间保持一致的表达。

先读对参考资料

如果你想把 speech 用在 Design Implementation 上，优先看 references/accessibility.md 了解中性朗读，查看 references/voiceover.md 了解演示型表达，再参考 references/sample-prompts.md 把提示词写对。这些文件能帮助你写出 CLI 和 API 都能直接执行、而不需要额外猜测的指令。