azure-text-to-speech

Azure AI Speech — Text-to-Speech

Generate narration with Azure neural TTS — high-quality multilingual voices, SSML prosody control, and express-as styles, served synchronously by the REST /cognitiveservices/v1 endpoint (no token exchange, Blob storage, or job polling). In OpenMontage this is exposed through the azure_tts tool (capability=tts, provider=azure). It is an optional cloud TTS provider — when AZURE_SPEECH_KEY is configured, prefer it for high-quality cloud narration. The local piper_tts remains the default offline path and the fallback when Azure is unavailable; elevenlabs_tts remains the choice for voice cloning.

Docs: REST text to speech · Voice gallery

Setup

Same Speech resource as azure_stt — one key/region unlocks both directions (STT and TTS). 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_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_tts reports AVAILABLE once AZURE_SPEECH_KEY plus either AZURE_SPEECH_REGION or AZURE_TTS_ENDPOINT are set.

Using it in a pipeline

Route through tts_selector as usual (it auto-discovers azure_tts), or call the provider tool directly when the user has approved 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
})

If azure_tts is unavailable (no key) or errors, fall back per its declared chain: elevenlabs_tts → openai_tts → piper_tts.

Voice selection

Curated shortlist (aliases accepted by the voice param):

Any valid Azure voice short name may be passed verbatim (e.g. de-DE-KatjaNeural); the Multilingual voices handle non-English text well — set locale to match the text's language for correct SSML.

Parameters that matter

• `rate` / `pitch` — SSML prosody. Narration usually reads best slightly

slowed ("-4%" to "-8%"); leave pitch at "0%" unless correcting a voice.

• `style` — express-as style for voices that support it

(narration-professional, calm, newscast). Unsupported styles are silently ignored by Azure, so listen to a sample before batch runs.

• `output_format` — mp3 (48kHz/192kbit) for delivery, wav (48kHz PCM)

when the segment feeds audio_mixer for further processing.

• Determinism: a fixed voice + SSML re-renders effectively identical audio —

safe to regenerate individual segments without re-recording the whole set.

Cost

Azure neural TTS Standard tier bills roughly $16 per 1M characters (~$0.016 per 1k chars; a 150-word narration segment ≈ $0.015). The tool reports per-call cost_usd for the cost tracker. See Azure AI Speech pricing for current rates.

Limits & tips

• One execute call = one narration segment. Generate per script section (the

asset stage convention) rather than one giant paragraph — smaller segments align cleanly to scene timings and are cheap to regenerate.

• The synchronous endpoint caps a request at 10 minutes of audio — far above

any segment OpenMontage generates.

• Text is XML-escaped automatically; do not pre-escape or wrap in SSML — pass

plain text plus the rate/pitch/style params.

• Verify quality: listen to the first generated segment before batch-running a

full script (voice/style fit is a creative decision — surface it at the proposal stage per the Decision Communication Contract).