mcpField
A
azure-speech-to-text

azure-speech-to-text

github.com/calesthio创意与媒体72.7k808 次安装今天更新
代码仓库

关于 azure-speech-to-text

azure-speech-to-text 是一项 OpenMontage 技能，用 Azure Fast Transcription 转录本地音频文件，适用于需要词级时间戳、说话人区分或语言识别的云端流程；离线时可回退到本地转录器。

主要功能

  1. 01同步转录本地音频文件
  2. 02词级时间戳
  3. 03说话人区分
  4. 04自动语言识别
  5. 05兼容本地转录器的输出

适用场景

  1. 01为字幕流程生成转录文本
  2. 02标记访谈或播客中的说话人
  3. 03优先采用云端处理时进行转录
  4. 04Azure 不可用时回退到本地转录

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/openmontage --skill azure-speech-to-text

安装后在 Claude Code 中输入/azure-speech-to-text确认已加载。

详细介绍

Azure AI Speech — 语音转文本

使用 Azure Fast Transcription 将音频转录为文本——支持同步转录、词级时间戳、说话人分离和多语言识别。在 OpenMontage 中，此功能通过 azure_stt 工具提供（capability=analysis、provider=azure）。它是一个可选的云端语音转文本提供方——配置 AZURE_SPEECH_KEY 后，优先使用它进行云端转录。本地 transcriber 工具（faster-whisper）仍是默认的离线路径，也是 Azure 不可用时的备用方案。

文档：Fast Transcription · Speech service overview

为什么选择 Fast Transcription（而不是 Batch）

Azure 提供了三种语音转文本接口。OpenMontage 使用 Fast Transcription，因为工作流转录的是本地音频文件：

接口输入延迟需要
Fast Transcription（此处使用）本地文件，multipart POST同步，低于实时速度密钥 + 区域
Batch TranscriptionURL 上的音频（Blob + SAS）异步任务 + 轮询Blob 存储配置
Speech SDK (spx)麦克风 / 流 / 文件流式原生 azure-cognitiveservices-speech 包

Fast Transcription 无需 Blob 存储、SAS URL 或原生 SDK——只需 requests 和两个环境变量。

设置

在 Azure 门户中创建一个 Speech 资源；从其 Keys and Endpoint 页面复制密钥和区域。

export AZURE_SPEECH_KEY=your_speech_resource_key
export AZURE_SPEECH_REGION=eastus          # your resource's region
# export AZURE_SPEECH_ENDPOINT=https://...  # optional: overrides region

设置 AZURE_SPEECH_KEY，以及 AZURE_SPEECH_REGION 或 AZURE_SPEECH_ENDPOINT 后，azure_stt 会报告 AVAILABLE。

在工作流中使用

除非运行必须离线，否则优先使用 azure_stt，而不是 transcriber。它的输出与 transcriber 的架构完全一致，因此可直接替代 subtitle_gen 以及任何使用转录文本的阶段。

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",
    # "language": "en",          # ISO 639-1 or BCP-47 ("en-US"); omit for auto-ID
    # "diarize": True,           # speaker labels, no HuggingFace token needed
    # "max_speakers": 4,
    "output_dir": "projects/my-video/artifacts",
})
if result.success:
    segs = result.data["segments"]          # [{id,start,end,text,words:[...]}]
    words = result.data["word_timestamps"]  # flat [{word,start,end,probability}]

如果 azure_stt 不可用（没有密钥）或出错，则回退到 transcriber（本地 whisper）——它们的 execute 签名和输出完全相同。

重要参数

  • language — 传入 ISO 代码（"en"）或完整区域设置（"en-US"）。已知语言时请指定；这比自动识别更快、更准确。
  • candidate_locales — 省略 language 时，Azure 会在此候选列表中进行语言识别。请将列表缩小到实际预期的语言；过长的列表会拖慢检测并增加误分类的可能性。
  • diarize / max_speakers — 适用于多说话人音频（采访、播客）。将 max_speakers 设为实际的说话人数上限。
  • profanity_filter — None | Masked（默认）| Removed | Tags。

响应格式（映射到 transcriber 架构）

原始 Azure 响应（包含 offsetMilliseconds / words[] 的 phrases[]）会被转换为秒，并映射到 OpenMontage 转录文本架构：

{
  "segments": [
    {"id": 0, "start": 0.0, "end": 2.4, "text": "Hello world",
     "speaker": 1,
     "words": [{"word": "Hello", "start": 0.0, "end": 0.5, "probability": 0.98}]}
  ],
  "word_timestamps": [{"word": "Hello", "start": 0.0, "end": 0.5, "probability": 0.98}],
  "language": "en-US",
  "duration_seconds": 2.4,
  "provider": "azure"
}

注意：Fast Transcription 不提供逐词置信度，因此每个词的 probability 都采用其所属短语的置信度。

限制与提示

  • 单次请求最多处理约 2 小时 / 数百 MB 的文件。对于更长的音频或批量任务，请改用 Azure Batch Transcription。
  • 请发送清晰的音频（16 kHz 以上的单声道音频即可）。如果只需要语音，请先将视频转码为音频——上传文件更小，结果相同。
  • 请核验时间信息：词级时间戳会用于 subtitle_gen 中的字幕提示。请对照源音频抽查首条和末条字幕。

评论

支持 Markdown