azure-speech-to-text

تبدیل سریع صدا و ویدیو به متن با timestamp و تفکیک گویندگان در Azure

azure-speech-to-text فایل‌های صوتی و ویدیویی را با Azure AI Speech به متن تبدیل می‌کند و timestamp سطح کلمه، تشخیص زبان و تفکیک گویندگان را ارائه می‌دهد. خروجی آن با schema استاندارد OpenMontage سازگار است و مستقیماً در تولید زیرنویس و مراحل بعدی تدوین استفاده می‌شود.

این skill برای ساخت زیرنویس دقیق، پردازش مصاحبه و پادکست و تحلیل محتوای گفتاری مفید است. اگر Azure در دسترس نباشد یا پردازش کاملاً آفلاین لازم باشد، می‌توان از faster-whisper به‌عنوان مسیر جایگزین استفاده کرد.

چه چیزی می‌گیرید

• رونویسی هم‌زمان و دقیق فایل‌های صوتی و ویدیویی با Azure Fast Transcription
• timestamp برای هر کلمه و هر بخش، مناسب ساخت subtitle و همگام‌سازی تدوین
• تفکیک گویندگان در مصاحبه‌ها و پادکست‌های چندنفره
• تشخیص خودکار زبان یا تعیین زبان و locale مشخص برای دقت بیشتر
• خروجی سازگار با ابزارهای transcriber و subtitle_gen در OpenMontage

برای چه کاری خوب است

• تولیدکنندگان ویدیو که به زیرنویس دقیق و همگام با صدا نیاز دارند
• پروژه‌های مصاحبه، پادکست و محتوای چندگوینده
• خطوط تولید ابری که Azure AI Speech و پردازش سریع فایل‌های محلی را ترجیح می‌دهند

برای چه کاری نیست

• پروژه‌هایی که باید کاملاً آفلاین و بدون ارسال فایل به سرویس ابری اجرا شوند
• فایل‌های بسیار طولانی یا پردازش حجیم که به Azure Batch Transcription نیاز دارند
• محیط‌هایی که Azure Speech resource یا دسترسی اینترنت در آن‌ها فراهم نیست

دربارهٔ این اسکیل

Azure AI Speech — Speech-to-Text

Transcribe audio to text with Azure Fast Transcription — synchronous,
word-level timestamps, speaker diarization, and multi-language identification.
In OpenMontage this is exposed through the azure_stt tool (capability=analysis,
provider=azure). It is an optional cloud STT provider — when
AZURE_SPEECH_KEY is configured, prefer it for cloud transcription. The local
transcriber tool (faster-whisper) remains the default offline path and the
fallback when Azure is unavailable.

Docs: Fast Transcription · Speech service overview

Why Fast Transcription (not Batch)

Azure exposes three STT surfaces. OpenMontage uses Fast Transcription because
the pipeline transcribes local audio files:

Fast Transcription needs no Blob storage, no SAS URLs, and no native SDK — just
requests and the two env vars.

Setup

Create a Speech resource in the Azure portal;
copy the key and region from its Keys and Endpoint page.

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_stt reports AVAILABLE once AZURE_SPEECH_KEY plus either
AZURE_SPEECH_REGION or AZURE_SPEECH_ENDPOINT are set.

Using it in a pipeline

Prefer azure_stt over transcriber unless the run must be offline. Its output
matches the transcriber schema exactly, so it is a drop-in for subtitle_gen
and any stage that consumes a transcript.

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}]

If azure_stt is unavailable (no key) or errors, fall back to transcriber
(local whisper) — its execute signature and output are identical.

Parameters that matter

• language — pass an ISO code ("en") or a full locale ("en-US"). Pin it when you know the language; it is faster and more accurate than auto-ID.
• candidate_locales — when language is omitted, Azure runs language identification across this shortlist. Narrow it to the languages you actually expect; a huge list slows detection and invites misclassification.
• diarize / max_speakers — enable for multi-speaker audio (interviews, podcasts). Set max_speakers to the real upper bound.
• profanity_filter — None | Masked (default) | Removed | Tags.

Response shape (mapped to the transcriber schema)

The raw Azure response (phrases[] with offsetMilliseconds / words[]) is
converted to seconds and the OpenMontage transcript schema:

{
  "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"
}

Note: Fast Transcription has no per-word confidence, so each word carries the
phrase confidence in probability.

Limits & tips

• Single file up to ~2 hours / a few hundred MB per request. For longer or bulk jobs, use Azure Batch Transcription instead.
• Send clean audio (16 kHz+ mono is plenty). Transcode video to audio first if you only need speech — smaller upload, same result.
• Verify timing: word timestamps drive subtitle cues in subtitle_gen. Spot-check the first and last cues against the source audio.

دانلود ZIP