用途
azure_stt 是 OpenMontage 中的可选云端语音转文字工具，底层使用 Azure AI Speech 的 Fast Transcription（快速转录）REST API。它主要用于把本地音频或视频文件转换为文本，也可生成带时间信息的转写结果，供字幕生成等环节使用。当运行环境配置了 AZURE_SPEECH_KEY 时，文档建议优先使用它进行云端转写；本地 transcriber（faster-whisper）仍是默认的离线路径，也是 Azure 不可用时的回退方案。
主要能力
- 同步转写本地音频文件，采用 multipart POST 方式，无需 Blob 存储、SAS URL 或原生 SDK。
- 支持词级时间戳，输出扁平化的 word_timestamps。
- 支持说话人分离（diarize）并可通过 max_speakers 设置说话人上限。
- 支持多语言识别：可指定 language，或省略后依据 candidate_locales 候选列表进行语言识别。
- 支持 profanity_filter 选项：None、Masked（默认）、Removed、Tags。
- 输出结构与本地 transcriber 完全一致，可直接替换使用，供 subtitle_gen 及任何消费转写结果的阶段使用。
使用方式
先在 Azure 门户创建 Speech 资源，从其 Keys and Endpoint 页面获取密钥和区域，然后配置环境变量：
export AZURE_SPEECH_KEY=your_speech_resource_key export AZURE_SPEECH_REGION=eastus export AZURE_SPEECH_ENDPOINT=https://... # 可选，覆盖 region
当 AZURE_SPEECH_KEY 与 AZURE_SPEECH_REGION 或 AZURE_SPEECH_ENDPOINT 任一同时存在时，azure_stt 报告为 AVAILABLE。
在流水线中通过工具注册表调用：
from tools.tool_registry import registry registry.discover() stt = registry._tools["azure_stt"]
result = stt.execute({ "input_path": "projects/my-video/assets/audio/narration.mp3", "output_dir": "projects/my-video/artifacts", }) if result.success: segs = result.data["segments"] words = result.data["word_timestamps"]
可选参数包括 language（ISO 639-1 或 BCP-47，如 en-US，省略则自动识别）、diarize、max_speakers、candidate_locales、profanity_filter。
输出会被映射为 OpenMontage 的转写结构，包含 segments（含 id、start、end、text、speaker、words）、word_timestamps、language、duration_seconds 和 provider（azure）。Azure 原始响应中的毫秒偏移会被转换为秒。需要注意，Fast Transcription 没有逐词置信度，因此每个词的 probability 沿用所在短语的置信度。
适用场景
- 将本地音频或视频批量或单个转写为文本。
- 为视频生成字幕，利用词级时间戳驱动字幕时间轴。
- 处理访谈、播客等多说话人音频，借助 diarize 和 max_speakers 标注说话人。
- 多语言音频的转写与语言识别。
限制与注意事项
- 单文件约支持 2 小时、数百 MB；更长或批量任务应改用 Azure Batch Transcription。
- 需要 Azure Speech 资源密钥与区域（或端点），未配置时不可用，需回退到本地 transcriber。
- 建议上传干净音频（16 kHz 以上单声道即可）；若只需要语音，可先将视频转码为音频以减小上传体积。
- 字幕时间轴依赖词级时间戳，建议对首尾字幕进行抽查核对。