Skip to main content
IntroductionBuild AgentsAgent FrontendsTest & EvaluateTelephonyRoboticsWebRTC TransportManage & DeployReferences

Azure Speech TTS plugin guide

How to use the Azure Speech TTS plugin for LiveKit Agents.

On this page

Available inPython

Overview

This plugin allows you to use Azure Speech  as a TTS provider for your voice agents.

Installation

Install the plugin from PyPI:

uv add "livekit-agents[azure]~=1.8"

Authentication

The Azure Speech plugin requires an Azure Speech key .

Set the following environment variables in your .env file:

AZURE_SPEECH_KEY=<azure-speech-key>
AZURE_SPEECH_REGION=<azure-speech-region>
AZURE_SPEECH_ENDPOINT=<azure-speech-endpoint>

Usage

Use an Azure Speech TTS within an AgentSession or as a standalone speech generator. For example, you can use this TTS in the Voice AI quickstart.

from livekit.plugins import azure
session = AgentSession(
tts=azure.TTS(
speech_key="<speech_service_key>",
speech_region="<speech_service_region>",
),
# ... llm, stt, etc.
)
Authentication options

To create an instance of azure.TTS, one of the following options must be met:

  • speech_endpoint must be set, or
  • speech_key and speech_region must both be set, or
  • speech_auth_token and speech_region must both be set.

The Azure Speech STT plugin takes different authentication parameters than the TTS plugin. Check the page for each plugin for the options it supports.

Parameters

This section describes some of the available parameters. See the plugin reference for a complete list of all available parameters.

voicestring

Voice for text-to-speech. To learn more, see Select synthesis language and voice .

languageLanguageCode

Language code for the input text. To learn more, see Select synthesis language and voice .

sample_rateintDefault: 24000

Sample rate of the generated audio in Hz. Supported values are 8000, 16000, 22050, 24000, 44100, and 48000.

prosodyProsodyConfig

Specify changes to pitch, rate, and volume for the speech output. To learn more, see Adjust prosody .

styleStyleConfig

Speaking style for the voice, with an optional degree between 0.1 and 2.0 that controls the intensity of the style. Only some voices support styles. To learn more, see Speaking styles and roles .

lexicon_uristring

URI of a custom pronunciation lexicon. To learn more, see Use custom lexicon .

speech_keystringEnv: AZURE_SPEECH_KEY

Azure Speech key. To learn more, see Azure Speech prerequisites .

speech_regionstringEnv: AZURE_SPEECH_REGION

Azure Speech region. To learn more, see Azure Speech prerequisites .

speech_endpointstringEnv: AZURE_SPEECH_ENDPOINT

Azure Speech endpoint URL. When set, the plugin uses this endpoint instead of one built from speech_region.

deployment_idstring

Deployment ID of a custom neural voice.

speech_auth_tokenstring

Azure Speech authentication token. Use it together with speech_region.

Metrics and usage labels

The Azure Speech TTS plugin builds the model value that appears in metrics and session usage from your configuration. The plugin reports provider as Azure TTS.

The model value uses the following format:

{host or region}:{voice}
{host or region}:{voice}:{deployment_id}

The format follows these rules:

  • The plugin uses the endpoint host if you configure speech_endpoint. Otherwise, it uses speech_region.
  • The plugin extracts only the hostname from speech_endpoint, so the scheme and path aren't part of the value.
  • The plugin appends :{deployment_id} if you configure deployment_id.
  • The plugin reports unknown only if you configure neither speech_endpoint nor speech_region.

The following table shows example configurations and the resulting model value:

Configurationmodel value
speech_region="eastus", default voiceeastus:en-US-JennyNeural
speech_endpoint="https://eastus.tts.speech.microsoft.com/cognitiveservices/v1", default voiceeastus.tts.speech.microsoft.com:en-US-JennyNeural
speech_endpoint="https://eastus.tts.speech.microsoft.com/cognitiveservices/v1", deployment_id="cnv-123"eastus.tts.speech.microsoft.com:en-US-JennyNeural:cnv-123

Earlier versions of the plugin always reported unknown, so a dashboard or cost report that groups by that value shows a new series for each combination of host or region, voice, and deployment. The Azure Speech STT plugin still reports unknown as its model value.

Controlling speech and pronunciation

Azure Speech TTS supports Speech Synthesis Markup Language (SSML) for customizing generated speech. To learn more, see SSML overview .

Additional resources

The following resources provide more information about using Azure Speech with LiveKit Agents.