简介这是一份基于微软TTS引擎的C语音合成示例源码面向刚接触文本转语音TTS开发的初学者演示了如何通过编程调用系统语音接口将纯文本转换为真实可听的语音输出可作为语音开发入门的第一份参考代码。压缩包内仅含1个cpp源文件体积约521B结构极为精简却完整覆盖了创建语音合成对象、设置语速/音调/音量、加载语音库以及播放音频等核心流程。目前已有335人学习浏览说明这一示例在入门层面具有一定的实用参考价值。研读这份代码可以直观了解微软SAPI、Azure Text-to-Speech等接口的集成方式同时接触到语音合成引擎、发音词典、多语言支持等关键概念为后续开发语音播报、无障碍辅助、智能客服等应用打下基础。代码量小、逻辑清晰也适合作为C项目中快速集成TTS能力的最小化模板借助它可快速验证调用流程并进一步扩展到自定义语音应用。1. 微软 TTS别再找 TTS.rar云端神经语音才是正路做短视频配音、给长文转有声书、给呼叫中心加语音播报搜微软tts总会翻到 TTS.rar 这类打包资源。但微软 TTS 的主体是 Azure Speech 的神经网络语音模型在云端不是一个压缩包能装下的。它提供几十种中文音色能调语速音调还能处理数字和多音字。能落地的接入方式只有三条REST API、Speech SDK、社区维护的 edge-tts。下面把常用流程写完整密钥怎么换、最小代码怎么跑通、SSML 怎么调发音细节、批量合成先看哪些错误码。后端工程师可以直接照抄新手也能按步骤跟下来。2. 微软 TTS 接入路线选型REST、SDK、edge-tts 怎么选接入微软 TTS 前先选路线。三条路线共享同一套云端语音模型输出音色和 SSML 能力完全一致差别在调用方式和能力边界上。选错路线的代价通常不是跑不通而是后期想加流式或字幕事件时发现要换实现。2.1 三条路线的差异先用一张表定位路线典型场景依赖适合谁Azure Speech SDK生产服务、流式合成、字幕事件官方 SDK 包要长期维护的项目REST API批量脚本、一次性合成只要 curl先验证效果再投入edge-tts音色试听、本地小工具Python 网络研究阶段或学习用SDK 和 REST 都跑在 Azure 语音服务上计费和音色完全一致edge-tts 走的是 Edge 浏览器在线语音的接口社区维护免费但接口随时可能变不适合做产品底座。我的建议是先用手边最快的工具试听音色确认某个声音合适后再迁移到 SDK 写正式代码迁移成本通常只有几个小时。REST 和 SDK 是同一套后端服务的两种入口。REST 适合只要一段 mp3别的不管的场景SDK 适合需要流式音频、词边界事件、细粒度回调的场景。两者鉴权方式不一样REST 用密钥换 tokenSDK 直接拿密钥和区域初始化下面分别说清楚。2.2 REST 鉴权用密钥换 token 的两个请求REST 路线要求每次合成前先向令牌服务要一个 token有效期 10 分钟左右过期要重新换。这个设计把密钥和语音请求解耦避免每次合成把订阅密钥直接暴露出去。换 token 的请求长这样# 1) 用订阅密钥换 token返回一串 JWT 字符串 curl -X POST https://REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken \ -H Ocp-Apim-Subscription-Key: 你的密钥 \ -d {}这一步不用额外指定 Content-Typecurl 的-d会自动补表单头服务端只认 Ocp-Apim-Subscription-Key。返回的字符串就是后续请求的 Authorization 值。按我的经验它会在一段时间后失效批量任务跑得久的话每处理 500 句重新换一次就行不必做太复杂的缓存。 必须是资源实际所在的区域比如 eastasia、japaneast资源建在哪个区域就填哪个混用会出现 403。2.3 用 curl 拿第一段 mp3换到 token 后合成请求发到 TTS 端点文本用 SSML 包起来。微软 TTS 不管走哪条路线入参都是 SSML 而不是裸文本这是新手最容易漏的一步# 2) 合成语音body 是 SSML输出直接落盘 curl -X POST https://REGION.tts.speech.microsoft.com/cognitiveservices/v1 \ -H Authorization: Bearer 上一步换到的token \ -H Content-Type: application/ssmlxml \ -H X-Microsoft-OutputFormat: audio-24khz-48kbitrate-mono-mp3 \ -d speak version1.0 xml:langzh-CNvoice namezh-CN-XiaoxiaoNeural你好这是微软 TTS 的第一次发声。/voice/speak \ --output first_tts.mp3三个参数值得解释。Content-Type 必须是 application/ssmlxml写成 text/plain 会返回 400。X-Microsoft-OutputFormat 决定编码格式audio-24khz-48kbitrate-mono-mp3 是音质和体积比较均衡的组合语音提示类应用够用。voice 标签里的 name 是音色标识中文区常用 zh-CN-XiaoxiaoNeural晓晓女声、zh-CN-YunxiNeural云希男声、zh-CN-YunyangNeural云扬新闻男声。实际语种由 voice 决定xml:lang 只是声明不影响发音。听完确认音色合适就可以进 SDK 阶段了。3. 用 Python SDK 本地跑通微软 TTS 的最小实现3.1 安装与准备两个环境变量就够正式项目里我一般用 SDK。Python 生态对应 azure-cognitiveservices-speech 这个包安装和普通库没区别不要求本机有音频设备输出到文件就能在服务器上跑pip install azure-cognitiveservices-speech export AZURE_SPEECH_KEY你的密钥 export AZURE_SPEECH_REGIONeastasia密钥和区域是一对绑定的关系SDK 初始化时两个必须同时给对否则报错信息往往只说鉴权失败很难看出是密钥错还是区域错所以第一步就放进环境变量而不是写死在代码里。区域字符串不要带 https:// 前缀SDK 会自己拼服务地址写全了反而解析不出来。3.2 最小代码文本进mp3 出下面的代码把文本合成为文件是整个接入流程的骨架之后加 SSML、加事件回调都在这份骨架上扩展import os import azure.cognitiveservices.speech as speechsdk speech_config speechsdk.SpeechConfig( subscriptionos.environ[AZURE_SPEECH_KEY], regionos.environ[AZURE_SPEECH_REGION], ) speech_config.speech_synthesis_language zh-CN speech_config.speech_synthesis_voice_name zh-CN-XiaoxiaoNeural # 要输出 mp3 必须显式指定格式否则默认是 wav speech_config.set_speech_synthesis_output_format( speechsdk.SpeechSynthesisOutputFormat.Audio24Khz48KBitRateMonoMp3 ) audio_config speechsdk.audio.AudioOutputConfig(filenameoutput.mp3) synthesizer speechsdk.SpeechSynthesizer( speech_configspeech_config, audio_configaudio_config ) result synthesizer.speak_text_async( 这是微软 TTS 的中文神经语音数字和日期会自动选择合适读法。 ).get() if result.reason speechsdk.ResultReason.SynthesizingAudioCompleted: print(合成完成时长(秒), round(result.audio_duration.total_seconds(), 2)) else: details speechsdk.SpeechSynthesisCancellationDetails(result) print(失败, details.reason, details.error_details)逻辑上分四步SpeechConfig 是全局配置语言和音色在这里定AudioOutputConfig 决定音频流去向写 filename 就是落盘不写的话 Windows 会走扬声器、Linux 服务器上往往直接报错所以服务端场景务必指定文件名SpeechSynthesizer 把前两者组装speak_text_async(...).get() 是同步等待结果。失败分支里 CancellationDetails.reason 能区分是本地设备问题还是服务端拒绝error_details 通常带服务端原始错误码这是排错的第一现场。提示SDK 输出到文件时默认编码是 riff-24khz-16bit-mono-pcm 的 wav。要 mp3 必须显式调用 set_speech_synthesis_output_format否则会出现扩展名是 mp3、内容其实是 wav的假成功。3.3 三个必调参数语言、音色、输出格式参数位置取值示例不设的后果speech_synthesis_languagezh-CN默认 en-US中文按英文音素读出speech_synthesis_voice_namezh-CN-XiaoxiaoNeural跟随语言取默认音色可能不是想要的声音set_speech_synthesis_output_formatAudio24Khz48KBitRateMonoMp3格式退化为 wav体积大好几倍这三个是新建项目的固定动作。更细的格式还有 Audio48Khz192KBitRateMonoMp3 等面向音乐场景语音 24kHz 已经够用。语言和音色同时设置时以 voice_name 为准因为音色本身携带语言信息speech_synthesis_language 更多是给默认音色兜底。3.4 流式输出音频边生成边消费合成长文本时等整段读完才拿到文件延迟会线性增长。SDK 支持在事件回调里消费音频块适合边合成边推流或边存边播class StreamHandler: def __init__(self): self.audio bytearray() # 每个音频块到达就触发一次块大小约为 8KB def on_audio(self, evt): self.audio.extend(evt.result.audio_data) handler StreamHandler() synthesizer.synthesizing.connect(handler.on_audio) synthesizer.speak_text_async(这段文本会以流的方式逐个音频块回调。).get()synthesizing 事件在每生成一小块音频时触发evt.result.audio_data 是原始音频字节可以直接写管道或推给播放器。这个方案在长文本上收益最明显首包延迟能做到几百毫秒而整段合成要等全部结束。SDK 里还有 started、word_boundary、bookmark 配套事件其中 word_boundary 在字幕和对齐时很关键第 5 章会用到。4. SSML 是微软 TTS 的调音台语速、停顿、多音字与情感4.1 认识 SSML 的最小结构SDK 和 REST 最终都接受 SSMLSDK 里对应方法是 speak_ssml_async。SSML 的骨架是 speak 根节点包住 voice 节点所有修饰都写在 voice 内部speak version1.0 xmlnshttp://www.w3.org/2001/10/synthesis xmlns:msttshttp://www.w3.org/2001/mstts xml:langzh-CN voice namezh-CN-XiaoxiaoNeural prosody rate10% pitch2Hz 项目验收会下午break time300ms/三点开始。 /prosody /voice /speakxmlns:mstts 这个命名空间很多教程不写但 express-as 等微软扩展标签依赖它漏了会在解析阶段直接报 400。break 标签控制停顿单位毫秒在句读不清的合成里比加标点可靠部分标点会被引擎直接忽略。prosody 标签统一管语速、音调、响度是调整听感最直接的手段。4.2 prosody 三个参数的边界与习惯值rate 在 0.5 倍到 2 倍之间有效超出区间不报错但会被钳制在边界pitch 支持百分比或 Hz 值中文语音里 2Hz 已经能听出差别动太多会显得尖volume 范围从 -50% 到 100%语音播报一般不碰响度留给播放端控制更合理。我常用的三组预设朗读文章用 rate0%、pitch0%语音导航用 rate10%信息密度优先儿童故事用 rate-10%、pitch5%听感更亲切。写入时属性值必须带单位纯数字会被解析器拒绝。4.3 多音字、数字、称呼三种修正手段按优先级用引擎对常见多音字已经处理得不错真正出问题的是人名和特殊读法。修正手段按优先级排第一优先改写源文本第二用 say-as 标签约束数字读法最后才用 phoneme 直接指定拼音这是最高级别的强制手段speak version1.0 xml:langzh-CN voice namezh-CN-XiaoxiaoNeural 这个数字读作say-as interpret-ascardinal2048/say-as 电话是say-as interpret-astelephone13800138000/say-as。 break time200ms/ 姓氏读法由拼音指定 phoneme alphabetsapi phshan4tian2fang1单田芳/phoneme的评书。 /voice /speaksapi 音标用数字表示声调1 到 4 对应四声0 是轻声还有 ipa 音标和通用拼音可选通用拼音不带声调数字适合对声调不敏感的名字。phoneme 内的文本不会进入发音引擎所以必须和 ph 完全对应。批量处理时把这些修正整理成原文到 SSML 片段的映射表维护比在代码里写死正则直观得多。4.4 说话风格express-as 用对了才算加分神经语音带说话风格这是网上微软 TTS 演示最吸引人的部分。使用前先确认音色本身支持风格晓晓和云希支持 assistant、chat、customerservice、cheerful、sad 等云扬偏向新闻播报不支持的音色加 express-as 会返回 400。风格强度用 styledegree 调范围 0.01 到 2默认 1 已经很明显mstts:express-as stylecheerful styledegree1.2 好消息这次升级全部通过测试。 /mstts:express-as我的经验是风格标签适合短句超过三句话持续 cheerful 会显得做作严肃内容和客服话术不加风格反而自然。express-as 和 prosody 可以嵌套风格定基调prosody 微调语速两者配合才能得到及格线以上的成品。调试时先确认风格生效再固化到 SSML 模板避免每轮都做全量合成。5. 批量合成时先看这些坑错误码、音色清单与字幕对齐5.1 先看错误码再改配置批量跑的时候多路请求同时进来最容易撞上配额问题。下面几个状态码覆盖了绝大多数失败场景状态码常见原因处理方式401token 过期或密钥区域不一致重新换 token核对 REGION 与资源页403免费层 QPS 超限或权限不足降低并发或升级到标准层404音色名拼写错误调 voices/list 核对全量音色名429短时间请求太多被限流指数退避重试首次等待 1 秒400SSML 标签不合法或缺少命名空间先用 XML 解析器校验 body 再发送429 是免费层最常见的拦路虎免费层按并发和字符双限流加上退避重试后批量任务基本都能跑完。403 里还有一种情况是资源欠费或暂停去面板看比翻日志快。5.2 用官方音色清单接口做选型选音色别靠记忆官方提供的清单接口一条 curl 就能拉全量数据按语言筛选后对比音色名和风格支持情况curl -X GET https://REGION.tts.speech.microsoft.com/cognitiveservices/voices/list \ -H Ocp-Apim-Subscription-Key: 你的密钥 \ | jq .[] | select(.Localezh-CN) | {ShortName, Gender, StyleList}返回里 ShortName 是合成请求要填的音色名Gender 是性别StyleList 列出该音色支持的风格标签。建议把这份清单导出 json 放进项目做映射校验合成前先确认音色名在清单内能省掉大量 404 定位时间。5.3 用 WordBoundary 事件给音频自动打字幕配视频或做有声内容时字幕和对齐是刚需。SDK 的 word_boundary 事件提供每个词在音频里的时间偏移把这些偏移和文本合并输出就是最简单的 srtdef on_word_boundary(evt): # audio_offset 和 duration 的单位都是 100 纳秒 start_ms evt.audio_offset / 10000 dur_ms evt.duration / 10000 print(f{start_ms / 1000:.2f}s\t{evt.text}) synthesizer.set_word_boundary_event_handler(on_word_boundary)拿到 (开始时间, 文本) 二元组后按句号或停顿切分合并成字幕行再乘上播放速度的缩放系数就能生成带时间轴的 srt 文件。偏移对应合成器内部时钟后面做变速播放要按倍率重新计算时间轴不能直接沿用。批量处理时把 word_boundary 输出落成 json 和音频一起归档之后换音色重合成字幕部分可以直接复用。本文还有配套的精品资源点击获取
微软TTS接入全攻略：从REST API到Python SDK，SSML调音与批量合成实战
简介这是一份基于微软TTS引擎的C语音合成示例源码面向刚接触文本转语音TTS开发的初学者演示了如何通过编程调用系统语音接口将纯文本转换为真实可听的语音输出可作为语音开发入门的第一份参考代码。压缩包内仅含1个cpp源文件体积约521B结构极为精简却完整覆盖了创建语音合成对象、设置语速/音调/音量、加载语音库以及播放音频等核心流程。目前已有335人学习浏览说明这一示例在入门层面具有一定的实用参考价值。研读这份代码可以直观了解微软SAPI、Azure Text-to-Speech等接口的集成方式同时接触到语音合成引擎、发音词典、多语言支持等关键概念为后续开发语音播报、无障碍辅助、智能客服等应用打下基础。代码量小、逻辑清晰也适合作为C项目中快速集成TTS能力的最小化模板借助它可快速验证调用流程并进一步扩展到自定义语音应用。1. 微软 TTS别再找 TTS.rar云端神经语音才是正路做短视频配音、给长文转有声书、给呼叫中心加语音播报搜微软tts总会翻到 TTS.rar 这类打包资源。但微软 TTS 的主体是 Azure Speech 的神经网络语音模型在云端不是一个压缩包能装下的。它提供几十种中文音色能调语速音调还能处理数字和多音字。能落地的接入方式只有三条REST API、Speech SDK、社区维护的 edge-tts。下面把常用流程写完整密钥怎么换、最小代码怎么跑通、SSML 怎么调发音细节、批量合成先看哪些错误码。后端工程师可以直接照抄新手也能按步骤跟下来。2. 微软 TTS 接入路线选型REST、SDK、edge-tts 怎么选接入微软 TTS 前先选路线。三条路线共享同一套云端语音模型输出音色和 SSML 能力完全一致差别在调用方式和能力边界上。选错路线的代价通常不是跑不通而是后期想加流式或字幕事件时发现要换实现。2.1 三条路线的差异先用一张表定位路线典型场景依赖适合谁Azure Speech SDK生产服务、流式合成、字幕事件官方 SDK 包要长期维护的项目REST API批量脚本、一次性合成只要 curl先验证效果再投入edge-tts音色试听、本地小工具Python 网络研究阶段或学习用SDK 和 REST 都跑在 Azure 语音服务上计费和音色完全一致edge-tts 走的是 Edge 浏览器在线语音的接口社区维护免费但接口随时可能变不适合做产品底座。我的建议是先用手边最快的工具试听音色确认某个声音合适后再迁移到 SDK 写正式代码迁移成本通常只有几个小时。REST 和 SDK 是同一套后端服务的两种入口。REST 适合只要一段 mp3别的不管的场景SDK 适合需要流式音频、词边界事件、细粒度回调的场景。两者鉴权方式不一样REST 用密钥换 tokenSDK 直接拿密钥和区域初始化下面分别说清楚。2.2 REST 鉴权用密钥换 token 的两个请求REST 路线要求每次合成前先向令牌服务要一个 token有效期 10 分钟左右过期要重新换。这个设计把密钥和语音请求解耦避免每次合成把订阅密钥直接暴露出去。换 token 的请求长这样# 1) 用订阅密钥换 token返回一串 JWT 字符串 curl -X POST https://REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken \ -H Ocp-Apim-Subscription-Key: 你的密钥 \ -d {}这一步不用额外指定 Content-Typecurl 的-d会自动补表单头服务端只认 Ocp-Apim-Subscription-Key。返回的字符串就是后续请求的 Authorization 值。按我的经验它会在一段时间后失效批量任务跑得久的话每处理 500 句重新换一次就行不必做太复杂的缓存。 必须是资源实际所在的区域比如 eastasia、japaneast资源建在哪个区域就填哪个混用会出现 403。2.3 用 curl 拿第一段 mp3换到 token 后合成请求发到 TTS 端点文本用 SSML 包起来。微软 TTS 不管走哪条路线入参都是 SSML 而不是裸文本这是新手最容易漏的一步# 2) 合成语音body 是 SSML输出直接落盘 curl -X POST https://REGION.tts.speech.microsoft.com/cognitiveservices/v1 \ -H Authorization: Bearer 上一步换到的token \ -H Content-Type: application/ssmlxml \ -H X-Microsoft-OutputFormat: audio-24khz-48kbitrate-mono-mp3 \ -d speak version1.0 xml:langzh-CNvoice namezh-CN-XiaoxiaoNeural你好这是微软 TTS 的第一次发声。/voice/speak \ --output first_tts.mp3三个参数值得解释。Content-Type 必须是 application/ssmlxml写成 text/plain 会返回 400。X-Microsoft-OutputFormat 决定编码格式audio-24khz-48kbitrate-mono-mp3 是音质和体积比较均衡的组合语音提示类应用够用。voice 标签里的 name 是音色标识中文区常用 zh-CN-XiaoxiaoNeural晓晓女声、zh-CN-YunxiNeural云希男声、zh-CN-YunyangNeural云扬新闻男声。实际语种由 voice 决定xml:lang 只是声明不影响发音。听完确认音色合适就可以进 SDK 阶段了。3. 用 Python SDK 本地跑通微软 TTS 的最小实现3.1 安装与准备两个环境变量就够正式项目里我一般用 SDK。Python 生态对应 azure-cognitiveservices-speech 这个包安装和普通库没区别不要求本机有音频设备输出到文件就能在服务器上跑pip install azure-cognitiveservices-speech export AZURE_SPEECH_KEY你的密钥 export AZURE_SPEECH_REGIONeastasia密钥和区域是一对绑定的关系SDK 初始化时两个必须同时给对否则报错信息往往只说鉴权失败很难看出是密钥错还是区域错所以第一步就放进环境变量而不是写死在代码里。区域字符串不要带 https:// 前缀SDK 会自己拼服务地址写全了反而解析不出来。3.2 最小代码文本进mp3 出下面的代码把文本合成为文件是整个接入流程的骨架之后加 SSML、加事件回调都在这份骨架上扩展import os import azure.cognitiveservices.speech as speechsdk speech_config speechsdk.SpeechConfig( subscriptionos.environ[AZURE_SPEECH_KEY], regionos.environ[AZURE_SPEECH_REGION], ) speech_config.speech_synthesis_language zh-CN speech_config.speech_synthesis_voice_name zh-CN-XiaoxiaoNeural # 要输出 mp3 必须显式指定格式否则默认是 wav speech_config.set_speech_synthesis_output_format( speechsdk.SpeechSynthesisOutputFormat.Audio24Khz48KBitRateMonoMp3 ) audio_config speechsdk.audio.AudioOutputConfig(filenameoutput.mp3) synthesizer speechsdk.SpeechSynthesizer( speech_configspeech_config, audio_configaudio_config ) result synthesizer.speak_text_async( 这是微软 TTS 的中文神经语音数字和日期会自动选择合适读法。 ).get() if result.reason speechsdk.ResultReason.SynthesizingAudioCompleted: print(合成完成时长(秒), round(result.audio_duration.total_seconds(), 2)) else: details speechsdk.SpeechSynthesisCancellationDetails(result) print(失败, details.reason, details.error_details)逻辑上分四步SpeechConfig 是全局配置语言和音色在这里定AudioOutputConfig 决定音频流去向写 filename 就是落盘不写的话 Windows 会走扬声器、Linux 服务器上往往直接报错所以服务端场景务必指定文件名SpeechSynthesizer 把前两者组装speak_text_async(...).get() 是同步等待结果。失败分支里 CancellationDetails.reason 能区分是本地设备问题还是服务端拒绝error_details 通常带服务端原始错误码这是排错的第一现场。提示SDK 输出到文件时默认编码是 riff-24khz-16bit-mono-pcm 的 wav。要 mp3 必须显式调用 set_speech_synthesis_output_format否则会出现扩展名是 mp3、内容其实是 wav的假成功。3.3 三个必调参数语言、音色、输出格式参数位置取值示例不设的后果speech_synthesis_languagezh-CN默认 en-US中文按英文音素读出speech_synthesis_voice_namezh-CN-XiaoxiaoNeural跟随语言取默认音色可能不是想要的声音set_speech_synthesis_output_formatAudio24Khz48KBitRateMonoMp3格式退化为 wav体积大好几倍这三个是新建项目的固定动作。更细的格式还有 Audio48Khz192KBitRateMonoMp3 等面向音乐场景语音 24kHz 已经够用。语言和音色同时设置时以 voice_name 为准因为音色本身携带语言信息speech_synthesis_language 更多是给默认音色兜底。3.4 流式输出音频边生成边消费合成长文本时等整段读完才拿到文件延迟会线性增长。SDK 支持在事件回调里消费音频块适合边合成边推流或边存边播class StreamHandler: def __init__(self): self.audio bytearray() # 每个音频块到达就触发一次块大小约为 8KB def on_audio(self, evt): self.audio.extend(evt.result.audio_data) handler StreamHandler() synthesizer.synthesizing.connect(handler.on_audio) synthesizer.speak_text_async(这段文本会以流的方式逐个音频块回调。).get()synthesizing 事件在每生成一小块音频时触发evt.result.audio_data 是原始音频字节可以直接写管道或推给播放器。这个方案在长文本上收益最明显首包延迟能做到几百毫秒而整段合成要等全部结束。SDK 里还有 started、word_boundary、bookmark 配套事件其中 word_boundary 在字幕和对齐时很关键第 5 章会用到。4. SSML 是微软 TTS 的调音台语速、停顿、多音字与情感4.1 认识 SSML 的最小结构SDK 和 REST 最终都接受 SSMLSDK 里对应方法是 speak_ssml_async。SSML 的骨架是 speak 根节点包住 voice 节点所有修饰都写在 voice 内部speak version1.0 xmlnshttp://www.w3.org/2001/10/synthesis xmlns:msttshttp://www.w3.org/2001/mstts xml:langzh-CN voice namezh-CN-XiaoxiaoNeural prosody rate10% pitch2Hz 项目验收会下午break time300ms/三点开始。 /prosody /voice /speakxmlns:mstts 这个命名空间很多教程不写但 express-as 等微软扩展标签依赖它漏了会在解析阶段直接报 400。break 标签控制停顿单位毫秒在句读不清的合成里比加标点可靠部分标点会被引擎直接忽略。prosody 标签统一管语速、音调、响度是调整听感最直接的手段。4.2 prosody 三个参数的边界与习惯值rate 在 0.5 倍到 2 倍之间有效超出区间不报错但会被钳制在边界pitch 支持百分比或 Hz 值中文语音里 2Hz 已经能听出差别动太多会显得尖volume 范围从 -50% 到 100%语音播报一般不碰响度留给播放端控制更合理。我常用的三组预设朗读文章用 rate0%、pitch0%语音导航用 rate10%信息密度优先儿童故事用 rate-10%、pitch5%听感更亲切。写入时属性值必须带单位纯数字会被解析器拒绝。4.3 多音字、数字、称呼三种修正手段按优先级用引擎对常见多音字已经处理得不错真正出问题的是人名和特殊读法。修正手段按优先级排第一优先改写源文本第二用 say-as 标签约束数字读法最后才用 phoneme 直接指定拼音这是最高级别的强制手段speak version1.0 xml:langzh-CN voice namezh-CN-XiaoxiaoNeural 这个数字读作say-as interpret-ascardinal2048/say-as 电话是say-as interpret-astelephone13800138000/say-as。 break time200ms/ 姓氏读法由拼音指定 phoneme alphabetsapi phshan4tian2fang1单田芳/phoneme的评书。 /voice /speaksapi 音标用数字表示声调1 到 4 对应四声0 是轻声还有 ipa 音标和通用拼音可选通用拼音不带声调数字适合对声调不敏感的名字。phoneme 内的文本不会进入发音引擎所以必须和 ph 完全对应。批量处理时把这些修正整理成原文到 SSML 片段的映射表维护比在代码里写死正则直观得多。4.4 说话风格express-as 用对了才算加分神经语音带说话风格这是网上微软 TTS 演示最吸引人的部分。使用前先确认音色本身支持风格晓晓和云希支持 assistant、chat、customerservice、cheerful、sad 等云扬偏向新闻播报不支持的音色加 express-as 会返回 400。风格强度用 styledegree 调范围 0.01 到 2默认 1 已经很明显mstts:express-as stylecheerful styledegree1.2 好消息这次升级全部通过测试。 /mstts:express-as我的经验是风格标签适合短句超过三句话持续 cheerful 会显得做作严肃内容和客服话术不加风格反而自然。express-as 和 prosody 可以嵌套风格定基调prosody 微调语速两者配合才能得到及格线以上的成品。调试时先确认风格生效再固化到 SSML 模板避免每轮都做全量合成。5. 批量合成时先看这些坑错误码、音色清单与字幕对齐5.1 先看错误码再改配置批量跑的时候多路请求同时进来最容易撞上配额问题。下面几个状态码覆盖了绝大多数失败场景状态码常见原因处理方式401token 过期或密钥区域不一致重新换 token核对 REGION 与资源页403免费层 QPS 超限或权限不足降低并发或升级到标准层404音色名拼写错误调 voices/list 核对全量音色名429短时间请求太多被限流指数退避重试首次等待 1 秒400SSML 标签不合法或缺少命名空间先用 XML 解析器校验 body 再发送429 是免费层最常见的拦路虎免费层按并发和字符双限流加上退避重试后批量任务基本都能跑完。403 里还有一种情况是资源欠费或暂停去面板看比翻日志快。5.2 用官方音色清单接口做选型选音色别靠记忆官方提供的清单接口一条 curl 就能拉全量数据按语言筛选后对比音色名和风格支持情况curl -X GET https://REGION.tts.speech.microsoft.com/cognitiveservices/voices/list \ -H Ocp-Apim-Subscription-Key: 你的密钥 \ | jq .[] | select(.Localezh-CN) | {ShortName, Gender, StyleList}返回里 ShortName 是合成请求要填的音色名Gender 是性别StyleList 列出该音色支持的风格标签。建议把这份清单导出 json 放进项目做映射校验合成前先确认音色名在清单内能省掉大量 404 定位时间。5.3 用 WordBoundary 事件给音频自动打字幕配视频或做有声内容时字幕和对齐是刚需。SDK 的 word_boundary 事件提供每个词在音频里的时间偏移把这些偏移和文本合并输出就是最简单的 srtdef on_word_boundary(evt): # audio_offset 和 duration 的单位都是 100 纳秒 start_ms evt.audio_offset / 10000 dur_ms evt.duration / 10000 print(f{start_ms / 1000:.2f}s\t{evt.text}) synthesizer.set_word_boundary_event_handler(on_word_boundary)拿到 (开始时间, 文本) 二元组后按句号或停顿切分合并成字幕行再乘上播放速度的缩放系数就能生成带时间轴的 srt 文件。偏移对应合成器内部时钟后面做变速播放要按倍率重新计算时间轴不能直接沿用。批量处理时把 word_boundary 输出落成 json 和音频一起归档之后换音色重合成字幕部分可以直接复用。本文还有配套的精品资源点击获取