Azure Text-to-Speech

Overview

Azure Cognitive Services provides high-quality text-to-speech synthesis with two service implementations: AzureTTSService (WebSocket-based) for real-time streaming with low latency, and AzureHttpTTSService (HTTP-based) for batch synthesis. AzureTTSService is recommended for interactive applications requiring streaming capabilities.

Azure TTS API Reference

Pipecat’s API methods for Azure TTS integration

Example Implementation

Complete example with streaming synthesis

Azure Speech Documentation

Official Azure Speech Services documentation

Voice Gallery

Browse available voices and languages

Installation

To use Azure services, install the required dependencies:

uv add "pipecat-ai[azure]"

Prerequisites

Azure Account Setup

Before using Azure TTS services, you need:

Azure Account: Sign up at Azure Portal
Speech Service: Create a Speech resource in your Azure subscription
API Key and Region: Get your subscription key and service region
Voice Selection: Choose from available voices in the Voice Gallery

Required Environment Variables

AZURE_SPEECH_API_KEY: Your Azure Speech service API key
AZURE_SPEECH_REGION: Your Azure Speech service region (e.g., “eastus”). With Private Link, pass the endpoint URL as private_endpoint instead

Configuration

AzureTTSService

str

required

Azure Cognitive Services subscription key.

str

Azure region identifier (e.g., "eastus", "westus2"). Required unless private_endpoint is provided. Raises ValueError when neither is set.

str

Custom endpoint URL for Azure Speech Services (e.g., "https://my-resource.cognitiveservices.azure.com/"). Use this when connecting via Private Link or a custom domain. When region is also set, region is ignored. See Azure Private Link documentation.

str

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=AzureTTSService.Settings(voice=...) instead.

int

default:"None"

Output audio sample rate in Hz. When None, uses the pipeline’s configured sample rate. Must be 8000, 16000, 22050, 24000, 44100, or 48000: at any other rate Azure returns 24 kHz audio, which plays at the wrong speed.

TextAggregationMode

default:"None"

Controls how incoming text is aggregated before synthesis. SENTENCE (used when None) buffers text until sentence boundaries, producing more natural speech. TOKEN streams tokens directly for lower latency. Import from pipecat.services.tts_service.

bool

default:"None"

deprecated

Deprecated since 0.0.104, removed in 2.0.0. Use text_aggregation_mode instead.

InputParams

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=AzureTTSService.Settings(...) instead.

AzureTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

AzureHttpTTSService

The HTTP service accepts the same parameters as the streaming service, including text_aggregation_mode:

str

required

Azure Cognitive Services subscription key.

str

Azure region identifier. Required unless private_endpoint is provided.

str

Custom endpoint URL for Azure Speech Services. Use this when connecting via Private Link or a custom domain. See Azure Private Link documentation.

str

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=AzureHttpTTSService.Settings(voice=...) instead.

int

default:"None"

Output audio sample rate in Hz. The same supported rates apply as for AzureTTSService.

InputParams

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=AzureHttpTTSService.Settings(...) instead.

AzureHttpTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

Settings

Runtime-configurable settings passed via the settings constructor argument using AzureTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
`model`	`str`	`None`	Not sent by this service; reported only as the model name in metrics and traces. (Inherited.)
`voice`	`str`	`"en-US-SaraNeural"`	Voice identifier. (Inherited.)
`language`	`Language \| str`	`"en-US"`	Language for synthesis. (Inherited.)
`effect`	`str`	`None`	Audio effect processor that compensates for playback distortion on a target device: `"eq_car"` for enclosed vehicles, `"eq_telecomhp8k"` for narrowband telephony (pair it with an 8 kHz pipeline). Azure ignores unrecognized values.
`emphasis`	`str`	`None`	Emphasis level for SSML.
`force_locale`	`bool`	`False`	Wraps text in SSML `<lang>` to force the configured `language` accent instead of auto-detection.
`pitch`	`str`	`None`	Pitch adjustment.
`rate`	`str`	`None`	Speaking rate.
`role`	`str`	`None`	Role for SSML. Applied only when `style` is set.
`style`	`str`	`None`	Speaking style.
`style_degree`	`str`	`None`	Degree of the speaking style. Applied only when `style` is set.
`voice_parameters`	`str`	`None`	Model parameters for HD voices, as SSML’s semicolon-separated `parameters` attribute on `<voice>` (e.g., `"temperature=0.7;top_p=0.8;top_k=22;cfg_scale=1.4"` or `"enhancePronunciation=true"`). Standard voices ignore.
`volume`	`str`	`None`	Volume level.

Usage

Basic Setup

import os

from pipecat.services.azure.tts import AzureTTSService

tts = AzureTTSService(
    api_key=os.getenv("AZURE_SPEECH_API_KEY"),
    region=os.getenv("AZURE_SPEECH_REGION"),
    settings=AzureTTSService.Settings(
        voice="en-US-SaraNeural",
    ),
)

With Voice Customization

from pipecat.transcriptions.language import Language

tts = AzureTTSService(
    api_key=os.getenv("AZURE_SPEECH_API_KEY"),
    region="eastus",
    settings=AzureTTSService.Settings(
        voice="en-US-JennyMultilingualNeural",
        language=Language.EN_US,
        style="cheerful",
        style_degree="1.5",
        rate="1.1",
    ),
)

HTTP Service

from pipecat.services.azure.tts import AzureHttpTTSService

tts = AzureHttpTTSService(
    api_key=os.getenv("AZURE_SPEECH_API_KEY"),
    region=os.getenv("AZURE_SPEECH_REGION"),
    settings=AzureHttpTTSService.Settings(voice="en-US-SaraNeural"),
)

With Private Endpoint

from pipecat.services.azure.tts import AzureTTSService

tts = AzureTTSService(
    api_key=os.getenv("AZURE_SPEECH_API_KEY"),
    private_endpoint="https://my-resource.cognitiveservices.azure.com/",
    settings=AzureTTSService.Settings(
        voice="en-US-SaraNeural",
    ),
)

Notes

Streaming vs HTTP: The streaming service (AzureTTSService) provides word-level timestamps and lower latency, making it better for interactive conversations. The HTTP service is simpler but returns the complete audio at once.
SSML support: Both services automatically construct SSML from the Settings. Special characters in text are automatically escaped.
Word timestamps: AzureTTSService supports word-level timestamps for synchronized text display. CJK languages receive special handling to merge individual characters into meaningful word units.
8kHz workaround: At 8kHz sample rates, Azure’s reported audio duration may not match word boundary offsets. The service uses word boundary offsets for timing in this case.

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Azure Text-to-Speech

Overview

Azure TTS API Reference

Example Implementation

Azure Speech Documentation

Voice Gallery

Installation

Prerequisites

Azure Account Setup

Required Environment Variables

Configuration

AzureTTSService

AzureHttpTTSService

Settings

Usage

Basic Setup

With Voice Customization

HTTP Service

With Private Endpoint

Notes

​Overview

Azure TTS API Reference

Example Implementation

Azure Speech Documentation

Voice Gallery

​Installation

​Prerequisites

​Azure Account Setup

​Required Environment Variables

​Configuration

​AzureTTSService

​AzureHttpTTSService

​Settings

​Usage

​Basic Setup

​With Voice Customization

​HTTP Service

​With Private Endpoint

​Notes

Overview

Installation

Prerequisites

Azure Account Setup

Required Environment Variables

Configuration

AzureTTSService

AzureHttpTTSService

Settings

Usage

Basic Setup

With Voice Customization

HTTP Service

With Private Endpoint

Notes