Codex 语音指令编写指南用 Voice Directions 精确控制 TTS 语音合成效果【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南以本仓库 Speech 技能skills/.curated/speech中维护的voice-directions参考文档为核心系统讲解如何为 OpenAI Audio API 的文本转语音TTS合成编写语音指令Voice Directions包括标准化指令模板的八个字段、编写最佳实践、六类典型场景的完整示例以及这些指令在仓库自带 CLIscripts/text_to_speech.py中的实际落地方式。读完本文你将能够为解说旁白、产品演示配音、IVR 电话提示、无障碍朗读等场景写出可复用、可迭代、效果稳定的指令块。什么是 Voice DirectionsTTS 里的导演手记在代码仓库的语音生成工作流中instructions是调用POST /v1/audio/speech接口时可选传入的一段风格指引文本用于控制合成语音的表演方式气质、语气、语速、情绪、停顿等而不改变输入文本本身。仓库用一份专门文档 voice-directions.md 定义了这套指令的书写规范SKILL.md 也将其定义为instruction patterns examplesSKILL.md。它的核心定位可以概括为一句话指令只负责怎么读文本只负责读什么。二者解耦之后同一段文案可以快速换一种声线、换一种节奏重新合成而无需改动原文非常适合产品 Demo 旁白、多版本试音、A/B 对比等场景。值得注意的是指令能力有模型兼容性边界仓库 CLI 的实现 scripts/text_to_speech.py 中_maybe_drop_instructions()会检测模型名如果使用tts-1或tts-1-hd会打印警告并丢弃instructions只有 GPT-4o mini 系列 TTS 模型如默认的gpt-4o-mini-tts-2025-12-15才支持指令。标准指令模板八个字段逐行拆解根据原文档所有语音指令应统一采用如下标签化模板按需取用所需行不必全写Voice Affect: overall character and texture Tone: attitude, formality, warmth Pacing: slow, steady, brisk Emotion: key emotions to convey Pronunciation: words to enunciate or emphasize Pauses: where to insert brief pauses Emphasis: key phrases to stress Delivery: cadence or rhythm notes八个字段的职责分别是字段控制维度填写的典型取值Voice Affect声音整体气质与质感character textureCalm and composed / Low and suspenseful / High energy and upbeatTone态度、正式度、温度Sincere and empathetic / Motivational and encouraging / Formal and welcomingPacing语速与节奏Slow / Steady / BriskEmotion需要传达的关键情绪Warmth and genuine care / Restrained intensity / EnthusiasmPronunciation需要吐字清晰或强调的词汇Clear, with emphasis on key reassurances / Precise and consistentPauses有意插入停顿的位置After apologies / After suspenseful moments / After breathing cuesEmphasis需要重读的关键短语Key sensory details / Action verbs and countdownsDelivery韵律、节拍等节奏性提示Classic cadence / Even and controlled仓库的 prompting.md 进一步给出了推荐书写顺序affect - tone - pacing - emotion - pronunciation/pauses - emphasis - delivery即先定气质再定态度再定速度与情绪最后处理发音、停顿与重音。对于复杂需求坚持用短标签行而非长段落这样既便于模型解析也便于人类阅读和后续迭代。编写最佳实践避免形容词堆砌原文档给出了五条核心实践并结合 prompting.md 可以归纳为四个要点控制在 48 行避免冲突指令。行数太少表达不完太多则可能互相干扰尤其禁止出现fast and slowformal and casual这类自相矛盾的表述。宁可少而准不可多而乱。用具体描述替代空泛形容词。与其写读得温柔一点不如明确写出Pacing: Slow and steady、Tone: Warm and empathetic。原文档的原话是 Prefer concrete guidance over adjectives alone——具体指导永远优于孤立形容词。不要在指令里改写输入文本。指令只负责引导演绎方式guide delivery一旦把原文复制进指令就可能引发重复朗读或语义漂移。如果需要语言或口音直接在输入文本里用那种语言书写即可。迭代时重复关键约束。当需要反复调整例如再慢一点时每次都要重新声明不可变更的约束比如反复强调 slow and steady防止模型在多次迭代中逐渐漂移drift。此外针对发音与专有名词prompting.md 补充了两个实用技巧对于缩写词acronym把发音提示直接写进文本例如用 A-I 替代 AI对于名字或品牌若清晰度至关重要可在输入文本中附上简单音标若要强调某个词则必须在Emphasis行中逐字重复该词。六类场景示例从安抚客服到复古播音员原文档提供了六个可直接照抄的短示例覆盖了从低语悬疑到高能健身的不同演绎风格全部继承如下。Calm support安抚式客服Voice Affect: Calm and composed, reassuring. Tone: Sincere and empathetic. Pacing: Steady and moderate. Emotion: Warmth and genuine care. Pronunciation: Clear, with emphasis on key reassurances. Pauses: Brief pauses after apologies and before requests.适用场景客服致歉、售后安抚、敏感信息告知。核心是真诚 平稳在道歉之后与提出请求之前各留一个短停顿给听者消化情绪的时间。Dramatic narrator戏剧化旁白Voice Affect: Low and suspenseful. Tone: Serious and mysterious. Pacing: Slow and deliberate. Emotion: Restrained intensity. Emphasis: Highlight sensory details and cliffhanger lines. Pauses: Add pauses after suspenseful moments.适用场景有声书、悬疑短片旁白。注意情绪是克制的强度restrained intensity而非大呼小叫——悬念靠留白与停顿制造不靠音量。Fitness instructor健身教练Voice Affect: High energy and upbeat. Tone: Motivational and encouraging. Pacing: Fast and dynamic. Emotion: Enthusiasm and momentum. Emphasis: Stress action verbs and countdowns.适用场景训练课程配音、打卡挑战语音。关键是把动词如 pushgo和倒数数字countdowns重读出来带动节奏与动作。Serene guide宁静引导Voice Affect: Soft and soothing. Tone: Calm and reassuring. Pacing: Slow and unhurried. Emotion: Peaceful warmth. Pauses: Gentle pauses after breathing cues.适用场景冥想引导、正念练习、放松音频。在呼吸提示词之后安排轻停顿让听者有时间真正执行动作。Robot agent机器人客服/系统语音Voice Affect: Monotone and mechanical. Tone: Neutral and formal. Pacing: Even and controlled. Emotion: None; strictly informational. Pronunciation: Precise and consistent.适用场景系统通知、机器人语音助手。注意Emotion: None; strictly informational.这一行直接声明不要情绪配合机械质感与精确发音塑造纯信息播报的人设。Old-time announcer复古播音员Voice Affect: Refined and theatrical. Tone: Formal and welcoming. Pacing: Steady with a classic cadence. Emotion: Warm enthusiasm. Pronunciation: Crisp enunciation with vintage flair.适用场景复古电台、节日问候、庆典开场。通过经典节拍classic cadence与复古韵味vintage flair还原老式广播腔。让指令生效结合仓库 CLI 的落地方式指令编写完成后需要传给 TTS 生成程序才能真正生效。仓库提供的统一入口是 scripts/text_to_speech.py它封装了 OpenAI Audio API并明确要求优先使用捆绑 CLI而不是临时自写脚本见 SKILL.md。单条合成--instructions 参数最直接的方式是通过--instructions参数把指令块原样传入示例来自 cli.mduv run --with openai python $TTS_GEN speak \ --input Today is a wonderful day to build something people love! \ --voice cedar \ --instructions Voice Affect: Warm and composed. Tone: upbeat and encouraging. \ --response-format mp3 \ --out speech.mp3其中$TTS_GEN指向技能 CLI 的稳定路径$CODEX_HOME/skills/speech/scripts/text_to_speech.py。从源码看text_to_speech.pyspeak子命令会把--instructions读入并放入请求 payload 的instructions字段与model、voice、input、response_format、speed一起发送。指令内容较长时也可以改用--instructions-file参数从文件读取。批量合成JSONL 中按任务覆盖指令如果有多条提示词如整段 IVR 菜单推荐走speak-batch子命令用 JSONL 文件逐行定义任务并支持按任务单独覆盖指令示例来自 cli.mdcat tmp/speech/jobs.jsonl JSONL {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} JSONL python $TTS_GEN speak-batch --input tmp/speech/jobs.jsonl --out-dir out --rpm 50从源码结构看text_to_speech.py每个 JSONL 任务都可以覆盖model、voice、response_format、speed、instructions等字段未覆盖的字段沿用命令行全局默认值运行后应删除临时 JSONL 文件规范约定中间文件放在tmp/下见 SKILL.md。注意--rpm默认 50 且上限 50源码 text_to_speech.py 会强制封顶避免触发 API 限流。指令的模型兼容性提醒合成前务必确认模型是否支持instructions。如前面所述tts-1/tts-1-hd会忽略指令而默认模型gpt-4o-mini-tts-2025-12-15支持。另外输入文本单次不得超过 4096 字符源码常量MAX_INPUT_CHARS 4096见 text_to_speech.py超长文本需拆分或走批量流程。直接可用的速查与进阶资源写指令前可以先python $TTS_GEN list-voices查看当前内置音色清单默认音色cedar想要更明亮的音色可换marin见 SKILL.md。仓库内还有更多与指令编写直接相关的素材references/sample-prompts.md可直接复制粘贴的五套指令配方产品演示、客服安抚、IVR 菜单、无障碍朗读、活力开场与本文示例互为补充references/prompting.md指令编写原则、结构与迭代模式的完整论述references/audio-api.mdinstructions参数与其他 API 参数speed0.254.0、六种response_format的快速参考references/cli.mdCLI 全量命令目录与常见配方按场景选择 narration.md、voiceover.md、ivr.md、accessibility.md 获取对应场景的默认值与专用模板。最后提醒一点合规要求无论使用哪种风格指令最终面向终端用户时都必须明确披露该语音由 AI 生成见 audio-api.md 与 SKILL.md。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
