edge-tts

library7.2.8pypypi✓ verified 23d ago

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.

llm-agents ai-ml communication

pip install edge-tts

github ↗package ↗

INSTALL

IMPORT

SIG · EDGE-TTS

edge-tts

llm-agentspythonv7.2.8

Install

4.2s avg

Import

646ms

Disk

27MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v7.2.8 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.686s · 27.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.2s · import 0.606s · 30MB

27MB installed

● package 27MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

edge_tts

✓ import 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).

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())

edge-tts --version

Debug

Known issues

breakingThe 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.

affects: All versions, especially during major Microsoft API changes (e.g., around December 2025 where multiple patches were released).

breakingSupport 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.

affects: Versions 7.2.0 and later.

gotchaSince `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())`.

affects: All versions.

gotchaEncountering '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.

affects: All versions.

deprecatedThe `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.

affects: Versions 7.2.0 and later.

Errors

Common errors & fixes

No audio received. Please verify that your parameters are correct.

This error often occurs due to an invalid or unavailable voice name, network connectivity issues, or recent breaking changes in Microsoft's underlying text-to-speech service API.

fix

1. Verify that the voice name is correct and available using `edge-tts --list-voices`. 2. Ensure a stable internet connection. 3. Update the `edge-tts` library to the latest version (`pip install --upgrade edge-tts`), as updates often address API changes from Microsoft. 4. Double-check your system's date and time are correct.

ModuleNotFoundError: No module named 'edge_tts'

The `edge-tts` Python package has not been installed, or the Python interpreter being used cannot find the installed package.

fix

Install the library using pip: `pip install edge-tts`. If using multiple Python environments, ensure it's installed in the correct one or use `python -m pip install edge-tts`.

403 Forbidden Expected HTTP 101 response but was '403 Forbidden'

This error typically indicates that the request to Microsoft's TTS service was blocked, often due to changes in the API's authentication requirements or anti-abuse measures. Older versions of `edge-tts` might not handle these new requirements, leading to a forbidden access error.

fix

Update the `edge-tts` library to the latest version (`pip install --upgrade edge-tts`), as the developers frequently release updates to adapt to changes in the Microsoft API.

SSML with <mstts:express-as> style plays default text instead of provided text

The `edge-tts` library has limited support for custom SSML. Microsoft's service only permits a single `<voice>` tag with a single `<prosody>` tag inside it, and prevents the use of any SSML that could not be generated by Microsoft Edge itself.

fix

Avoid using complex or deeply nested SSML structures. Restrict SSML usage to basic `<speak>` and `<prosody>` tags for adjustments like rate, volume, and pitch, as supported directly by the library's command-line options. Ensure no special characters like '<' are unescaped if directly embedding in text.

Upgrade

Version history

7.2.8latest on PyPI · released Mar 22, 2026

Audit

Dependencies

aiohttprequiredAsynchronous HTTP client for communicating with the TTS service.

srtrequiredUsed for generating subtitle files alongside audio.

tabulaterequiredUsed for formatting output in CLI tools, like --list-voices.

mpvoptionalOptional command-line player required for the `edge-playback` CLI utility (not for the Python library itself).

Agent activity

303 hits · last 30 days

node

288

Perplexity

panscient.com

OpenAI (training)

Resources

githubhttps://github.com/rany2/edge-tts ↗

packagehttps://pypi.org/project/edge-tts/ ↗