azure-text-to-speech

Azure AI Speech — 文本转语音

使用 Azure 神经网络 TTS 生成旁白，支持高质量多语言语音、SSML 韵律控制和 express-as 风格，并通过 REST /cognitiveservices/v1 端点同步提供服务（无需令牌交换、Blob 存储或任务 轮询）。在 OpenMontage 中，此功能通过 azure_tts 工具提供 （capability=tts、provider=azure）。它是可选的云端 TTS 提供方—— 配置 AZURE_SPEECH_KEY 后，优先使用它生成高质量云端 旁白。本地 piper_tts 仍是默认的离线路径，也是 Azure 不可用时的 后备选项；克隆语音则使用 elevenlabs_tts。

文档：REST 文本转语音 · 语音库

设置

与 azure_stt 使用同一个 Speech 资源——一个密钥／区域即可启用两个方向 （STT 和 TTS）。在 Azure 门户中创建 Speech 资源；从其 密钥和终结点页面复制密钥和区域。

export AZURE_SPEECH_KEY=your_speech_resource_key
export AZURE_SPEECH_REGION=eastus        # your resource's region
# export AZURE_TTS_ENDPOINT=https://...  # optional: full custom TTS host
#   (the TTS host is https://<region>.tts.speech.microsoft.com — a different
#    subdomain than the STT endpoint, hence the separate override var)

设置 AZURE_SPEECH_KEY，并设置 AZURE_SPEECH_REGION 或 AZURE_TTS_ENDPOINT 之一后，azure_tts 会报告 AVAILABLE。

在流水线中使用

像往常一样通过 tts_selector 路由（它会自动发现 azure_tts），或者在用户已批准使用 Azure 时直接调用提供方工具：

from tools.tool_registry import registry
registry.discover()
tts = registry._tools["azure_tts"]

result = tts.execute({
    "text": "Every design decision in this dashboard has a reason.",
    "voice": "andrew",                 # alias or full Azure short name
    "rate": "-4%",                     # slightly slower for narration
    # "style": "narration-professional",  # for voices that support styles
    "output_path": "projects/my-video/assets/audio/seg_001.mp3",
    "output_format": "mp3",            # or "wav" (48kHz PCM) for mixing
})

如果 azure_tts 不可用（没有密钥）或出错，请按其声明的链路回退：elevenlabs_tts → openai_tts → piper_tts。

语音选择

精选列表（voice 参数接受别名）：

别名	语音	特点
andrew	en-US-AndrewMultilingualNeural	温暖、自信、自然，默认语音；适合创始人／讲解者的语气
brandon	en-US-BrandonMultilingualNeural	音色较低、语速沉稳
ava	en-US-AvaMultilingualNeural	自信、明亮的女声
guy	en-US-GuyNeural	权威感强
jenny	en-US-JennyNeural	亲切、清晰

也可以直接传入任何有效的 Azure 语音短名称（例如 de-DE-KatjaNeural）；Multilingual 语音对非英语文本的处理效果很好—— 将 locale 设为与文本语言一致，以确保 SSML 正确。

重要参数

• rate / pitch — SSML 韵律。旁白通常略微放慢会更自然 （"-4%" 到 "-8%"）；除非要修正语音，否则将音高保持为 "0%"。
• style — 支持该功能的语音可使用 express-as 风格 （narration-professional、calm、newscast）。Azure 会静默忽略不支持的风格，因此批量运行前请先试听样例。
• output_format — 交付时使用 mp3（48kHz/192kbit）；当片段要交给 audio_mixer 进一步处理时，使用 wav（48kHz PCM）。
• 确定性：固定语音和 SSML 重新渲染后，生成的音频基本一致—— 可以安全地单独重新生成片段，无需重录整组内容。

费用

Azure 神经网络 TTS 标准层的费用约为每 1M 个字符 $16（每 1k 个字符约 $0.016；一段 150 词的旁白约 $0.015）。工具会报告每次调用的 cost_usd，供费用跟踪器使用。当前费率请参阅 Azure AI Speech 定价。

限制与提示

• 一次 execute 调用对应一个旁白片段。应按脚本章节生成（遵循素材阶段的惯例），而不是生成一大段文本——较短的片段更容易与场景时间对齐，也便于低成本重新生成。
• 同步端点将单次请求限制为 10 分钟音频，远高于 OpenMontage 生成的任何片段。
• 文本会自动进行 XML 转义；请勿预先转义或包装为 SSML——传入纯文本以及 rate／pitch／style 参数即可。
• 检查质量：批量运行完整脚本前，先试听生成的第一个片段（语音／风格是否合适属于创意决策——根据《决策沟通契约》，应在提案阶段明确提出）。