Registry /
azure / azure-cognitiveservices-speech
Install & Compatibility
Where this runs
tested against v1.51.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.412s · 31MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
speechsdk
✓ import azure.cognitiveservices.speech as speechsdk
SpeechConfig
✓ speechsdk.SpeechConfig
AudioConfig
✓ speechsdk.audio.AudioOutputConfig
SpeechSynthesizer
✓ speechsdk.SpeechSynthesizer
SpeechRecognizer
✓ speechsdk.SpeechRecognizer
ResultReason
✓ speechsdk.ResultReason
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?")
Debug
Known issues
breakingStandard text-to-speech voices were retired on August 31, 2024. Applications using these voices must migrate to neural voices to avoid service disruption.fixUpdate `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.
affects: <= 1.47.0 (prior to August 2024)
breakingSupport for Intent Recognition and Speaker Recognition has been removed due to service retirement.fixMigrate to alternative services or patterns for intent and speaker recognition as described in Microsoft's documentation and sample repositories.
affects: All versions (service retirement)
gotchaNetwork connectivity issues, including firewalls, proxies, and incorrect endpoint configurations, are common. The SDK might silently fail without clear exceptions.fixEnsure 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.
affects: All versions
gotchaOn Windows, the Speech SDK requires the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 to be installed.fixDownload and install the appropriate Visual C++ Redistributable package for your platform from the Microsoft website. A system restart might be required.
affects: All versions on Windows
gotchaLatency 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.fixImplement retry logic for asynchronous operations. Consider breaking down large text inputs into smaller chunks. Optimize SSML structure and monitor performance in your deployment environment.
affects: All versions
gotchaAuthentication failures often stem from incorrect API keys, expired tokens, or mismatches between the specified region/endpoint in code and the actual Azure resource deployment.fixDouble-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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.cognitiveservices.speech'
The 'azure-cognitiveservices-speech' package is not installed or not accessible in the current Python environment.
fixInstall the package using pip: 'pip install azure-cognitiveservices-speech'.
ImportError: libasound.so.2: cannot open shared object file: No such file or directory
The 'libasound2' library, required by the Speech SDK, is missing on the system.
fixInstall the missing library on Ubuntu: 'sudo apt-get install libasound2'.
FileNotFoundError: Could not find module '.../Microsoft.CognitiveServices.Speech.core.dll'
The Speech SDK's core DLL file is missing or not found in the specified path.
fixEnsure the DLL file exists in the specified directory and that the application has permission to access it.
OSError: dlopen(.../libMicrosoft.CognitiveServices.Speech.core.dylib, 6): no suitable image found.
The Speech SDK's core dynamic library is incompatible with the current macOS version.
fixEnsure the macOS version meets the SDK's requirements and that the correct library version is installed.
ERROR: Could not find a version that satisfies the requirement azure-cognitiveservices-speech==1.13.0
The specified version of the package is not available for the current Python version or platform.
fixVerify the Python version and platform compatibility, and install a compatible version of the package.
Upgrade
Version history
1.51.2latest on PyPI · released Aug 20, 2026
Audit
Dependencies
Microsoft Visual C++ Redistributable for Visual Studio 2015-2022optionalRequired for Windows platforms for the underlying native SDK components.
libssl1.0.0 or libssl1.0.2, libasound2optionalRequired for certain Linux distributions (e.g., Ubuntu, Debian) for SSL and audio functionality.