Microsoft Edge TTS Python Library

7.2.8 · active · verified Sat Apr 11

edge-tts is a Python library (current version 7.2.8) that provides access to Microsoft Edge's online text-to-speech (TTS) service. It allows developers to convert text into natural-sounding speech without needing the Edge browser, Windows, or an API key, by leveraging the same cloud voices used by Edge. The library maintains an active release cadence, frequently updating to address changes in the underlying Microsoft service.

Warnings

breaking The library relies on a reverse-engineered Microsoft API, which is subject to unannounced changes by Microsoft. This can lead to sudden breakages or requiring rapid updates to the `edge-tts` library to maintain functionality.
Fix: Always keep the `edge-tts` library updated to the latest version to incorporate fixes for upstream API changes. Monitor the GitHub repository for immediate updates.
breaking Support for custom SSML (Speech Synthesis Markup Language) beyond basic prosody (rate, volume, pitch) was removed because Microsoft's service only permits SSML that could be generated by Microsoft Edge itself, limiting advanced custom tags.
Fix: Avoid using complex or custom SSML tags. Only basic prosody adjustments (rate, volume, pitch) are reliably supported. For advanced speech customization, consider official Azure Cognitive Services TTS which offers full SSML support.
gotcha Since `edge-tts` uses `asyncio`, all calls to `Communicate` methods (like `save()` or `stream()`) must be `await`ed within an `async` function, and the main execution flow needs `asyncio.run()`.
Fix: Ensure your code structure uses `async def` for functions interacting with `edge_tts` and invokes the main async function using `asyncio.run(your_async_function())`.
gotcha Encountering 'NoAudioReceived' errors or unexpected silence is common. This often indicates issues with the chosen voice, network connectivity, or temporary service unavailability on Microsoft's end.
Fix: Verify the voice name is exact and currently available using `edge-tts --list-voices`. Check your internet connection. Implement error handling and retry logic, or try a different voice/locale if the issue persists.
deprecated The `merge_cues` support and `words-in-cue` functionality were dropped as `SentenceBoundary` metadata became the default and rendered them obsolete.
Fix: Migrate any code relying on `merge_cues` or `words-in-cue` to use `SentenceBoundary` events for cue synchronization. The library now defaults to `SentenceBoundary` cues.

Install

pip install edge-tts Install stable version

Imports

edge_tts
```
import edge_tts
```
The package name is `edge-tts` for installation, but the module name for import is `edge_tts` (using an underscore).

Quickstart

This quickstart demonstrates how to convert a text string into an MP3 audio file using a specified voice. It uses `asyncio` for asynchronous operations, which is fundamental to how `edge-tts` works. Replace 'en-US-JennyNeural' with your desired voice; you can list all available voices using the command-line tool `edge-tts --list-voices`.

import asyncio
import edge_tts
import os

TEXT = "Hello, this is a test of the Microsoft Edge Text-to-Speech library."
VOICE = "en-US-JennyNeural" # You can list available voices with `edge-tts --list-voices`
OUTPUT_FILE = "hello.mp3"

async def main():
    print(f"Generating speech for: '{TEXT}' with voice '{VOICE}'")
    try:
        communicate = edge_tts.Communicate(text=TEXT, voice=VOICE)
        await communicate.save(OUTPUT_FILE)
        print(f"Audio saved to {OUTPUT_FILE}")
    except Exception as e:
        print(f"An error occurred: {e}")
        print("Ensure you have a stable internet connection and the voice name is correct.")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →