Azure Cognitive Services Speech SDK for Python

1.49.0 · active · verified Sat Apr 11

The Microsoft Cognitive Services Speech SDK for Python (current version 1.49.0) provides robust capabilities for integrating speech-to-text, text-to-speech, and speech translation into Python applications. It supports both real-time and non-real-time scenarios across various platforms, enabling developers to build intelligent speech-enabled features. The library maintains an active release cadence with frequent updates.

Warnings

breaking Standard text-to-speech voices were retired on August 31, 2024. Applications using these voices must migrate to neural voices to avoid service disruption.
Fix: Update `speech_config.speech_synthesis_voice_name` to use a supported neural voice (e.g., `en-US-AvaMultilingualNeural`). Review the latest documentation for available neural voices.
breaking Support for Intent Recognition and Speaker Recognition has been removed due to service retirement.
Fix: Migrate to alternative services or patterns for intent and speaker recognition as described in Microsoft's documentation and sample repositories.
gotcha Network connectivity issues, including firewalls, proxies, and incorrect endpoint configurations, are common. The SDK might silently fail without clear exceptions.
Fix: Ensure outbound connections to `*.cognitiveservices.azure.com` are allowed. If behind a proxy, use `speechsdk.SpeechConfig.set_proxy()` method. Verify that the Speech resource key, region, and endpoint are correct and match your Azure deployment. Implement robust logging for SDK errors.
gotcha On Windows, the Speech SDK requires the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 to be installed.
Fix: Download and install the appropriate Visual C++ Redistributable package for your platform from the Microsoft website. A system restart might be required.
gotcha Latency issues, especially with large SSML files or certain neural voices (e.g., F1 tier), can lead to partial audio output or 'Internal Server Error' due to timeouts.
Fix: Implement retry logic for asynchronous operations. Consider breaking down large text inputs into smaller chunks. Optimize SSML structure and monitor performance in your deployment environment.
gotcha Authentication failures often stem from incorrect API keys, expired tokens, or mismatches between the specified region/endpoint in code and the actual Azure resource deployment.
Fix: Double-check `SPEECH_KEY` and `SPEECH_REGION` (or `ENDPOINT`) values. Ensure they are current and correspond to your Azure Speech resource. Avoid hardcoding credentials; use environment variables or a secure key management system.

Install

pip install azure-cognitiveservices-speech Install latest version

Imports

speechsdk

import azure.cognitiveservices.speech as speechsdk

SpeechConfig
```
speechsdk.SpeechConfig
```
AudioConfig
```
speechsdk.audio.AudioOutputConfig
```
SpeechSynthesizer
```
speechsdk.SpeechSynthesizer
```
SpeechRecognizer
```
speechsdk.SpeechRecognizer
```
ResultReason
```
speechsdk.ResultReason
```

Quickstart

This quickstart demonstrates basic text-to-speech functionality using a neural voice. It initializes the SpeechConfig with an API key and region (retrieved from environment variables), creates a SpeechSynthesizer, and then synthesizes user-provided text to the default speaker. Ensure 'SPEECH_KEY' and 'SPEECH_REGION' environment variables are set before running.

import os
import azure.cognitiveservices.speech as speechsdk

# This example requires environment variables named "SPEECH_KEY" and "SPEECH_REGION"
# (or "ENDPOINT" for custom endpoints) to be set.
# Replace with your own subscription key and service region. Example: "westus", "eastus"
speech_key = os.environ.get('SPEECH_KEY', '')
speech_region = os.environ.get('SPEECH_REGION', '') # e.g., 'westus'

if not speech_key or not speech_region:
    print("Please set the SPEECH_KEY and SPEECH_REGION environment variables.")
    exit()

speech_config = speechsdk.SpeechConfig(subscription=speech_key, region=speech_region)

# The neural multilingual voice can speak different languages based on the input text.
speech_config.speech_synthesis_voice_name='en-US-AvaMultilingualNeural'

audio_config = speechsdk.audio.AudioOutputConfig(use_default_speaker=True)
speech_synthesizer = speechsdk.SpeechSynthesizer(speech_config=speech_config, audio_config=audio_config)

print("Enter some text that you want to speak (type 'exit' to quit) >")
while True:
    text = input()
    if text.lower() == 'exit':
        break

    speech_synthesis_result = speech_synthesizer.speak_text_async(text).get()

    if speech_synthesis_result.reason == speechsdk.ResultReason.SynthesizingAudioCompleted:
        print(f"Speech synthesized for text: [{text}]")
    elif speech_synthesis_result.reason == speechsdk.ResultReason.Canceled:
        cancellation_details = speech_synthesis_result.cancellation_details
        print(f"Speech synthesis canceled: {cancellation_details.reason}")
        if cancellation_details.reason == speechsdk.CancellationReason.Error:
            if cancellation_details.error_details:
                print(f"Error details: {cancellation_details.error_details}")
            print("Did you set the speech resource key and region environment variables correctly?")

view raw JSON →