edge-tts: Microsoft Edge voices from a Python script, no API key required

The problem edge-tts solves for Python developers

Cloud text-to-speech normally means an account, a key, a billing relationship and a client library for each vendor. edge-tts takes a different route. It speaks to the same online service Microsoft Edge uses for its read-aloud feature, so a developer with Python and an internet connection can generate speech without registering anything. The README's description is blunt about the scope: use Microsoft Edge's online text-to-speech service from Python without needing Microsoft Edge or Windows or an API key.

The audience is narrow but real. It fits scripts that turn articles into MP3 files, prototypes that need narration before a vendor is chosen, and small tools where a per-character bill is unwelcome. It does not fit anything that must run without a network. The package is a client for a hosted service, so the audio is produced remotely and streamed back.

How the client talks to Microsoft's speech endpoint

edge-tts is a thin Python layer, not a speech engine. The repository's setup.py lists four runtime dependencies: aiohttp, certifi, tabulate and typing-extensions. aiohttp handles the WebSocket connection to the service, certifi supplies the certificate bundle, and tabulate formats the voice listing. There is no model file, no local inference and no bundled audio data.

The architecture follows from that dependency list. The library opens a network connection, sends the text plus parameters such as voice, rate, volume and pitch, and receives audio chunks that it writes to disk or yields to the caller. The examples directory reflects this: async_audio_streaming_with_predefined_voice_and_subtitles.py and sync_audio_streaming_with_predefined_voice_subtitles.py show streaming variants, while async_audio_gen_with_dynamic_voice_selection.py picks a voice at runtime. Because the work is I/O bound rather than CPU bound, an async interface is the natural shape, and the repository ships both async and sync examples.

The subtitle output is generated from the same stream. When you pass --write-subtitles, the CLI writes an SRT file alongside the audio, which is why the flag pairs naturally with the media flag in every README example.

Installing edge-tts and generating your first MP3

Installation is a single pip command. The README also suggests pipx when only the command line tools matter, because pipx keeps the package out of your project environment.

pip install edge-tts

or, for the commands alone:

pipx install edge-tts

After installation the README's basic example produces both audio and a subtitle file. Run it and you should get hello.mp3 next to hello.srt in the working directory.

edge-tts --text "Hello, world!" --write-media hello.mp3 --write-subtitles hello.srt

To pick a different voice, list what the service currently offers and then pass the identifier. The README shows the listing as a table with Name, Gender, ContentCategories and VoicePersonalities columns.

edge-tts --list-voices
edge-tts --voice ar-EG-SalmaNeural --text "مرحبا كيف حالك؟" --write-media hello_in_arabic.mp3 --write-subtitles hello_in_arabic.srt

Rate, volume and pitch take percentage or hertz values. The README warns that a negative value must be attached with an equals sign, otherwise the argument parser reads it as an option.

edge-tts --rate=-50% --text "Hello, world!" --write-media hello_with_rate_lowered.mp3
edge-tts --pitch=-50Hz --text "Hello, world!" --write-media hello_with_pitch_lowered.mp3

For playback instead of files, edge-playback accepts the same options except --write-media, --write-subtitles and --list-voices. On non-Windows systems it needs the mpv command line player installed, per the README.

Custom SSML is gone, and that constrains the API

The most important limitation is documented rather than hidden. The README states that support for custom SSML was removed because Microsoft prevents the use of any SSML that could not be generated by Microsoft Edge itself. In practice the service permits a single voice tag with a single prosody tag inside it. Anything more elaborate, such as multiple voices in one request or phoneme-level control, cannot be sent.

The project's answer is that the useful prosody knobs are already exposed as flags: rate, volume and pitch. That covers a lot of ground, but it means edge-tts will never be the tool for fine-grained pronunciation control, and no amount of wrapper code changes the server side restriction. If your pipeline depends on SSML features beyond those three parameters, this library is the wrong layer.

The second constraint is the network. There is no offline mode in the README, and the package's dependencies are all HTTP and formatting libraries, so nothing is synthesized locally. A build machine without outbound access cannot use it. The third is longevity: the client targets a service Microsoft controls, and the README's own note about SSML shows how quickly the terms can change. Pinning a version protects you from API drift in the client, not from changes at the endpoint.

edge-tts versus a local engine like Piper

The obvious alternative for Python users who need speech without a vendor is a local neural engine such as Piper. The difference is architectural, not cosmetic. Piper ships model weights and runs inference on your CPU, so it works on a plane, inside an air-gapped build, and at a fixed cost per sentence forever. edge-tts ships no weights and does no inference; it borrows Microsoft's voices over the network.

That trade decides the choice. Piper gives you reproducibility and offline operation but you manage model files, and voice quality and language coverage depend on which models you download. edge-tts gives you a large multilingual voice list with no setup and no account, but every request depends on a remote service that can rate-limit, change or disappear. For batch generation inside a container with no egress, Piper is the correct tool and edge-tts simply is not an option. For a quick narration of a document in a language you do not have a model for, edge-tts is faster to reach.

A second comparison point sits inside the same repository: edge-playback is the same engine with local playback through mpv instead of file output, useful for checking a voice before committing it to a pipeline.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-03-22, which is also the date of release 7.2.8. Earlier releases 7.2.7 and 7.2.6 landed in December 2025. The repository is not archived, so the project has a visible release history, but the gaps between releases are measured in months rather than weeks, and the version numbers in the 7.2.x line suggest incremental fixes rather than a rewrite in progress.

Upgrade cost is low by design. The public surface is a CLI plus a Python module, and the dependency ranges in setup.py are wide: aiohttp below 4.0.0, tabulate below 1.0.0, typing-extensions below 5.0.0, and certifi with a floor rather than a ceiling. That means pip can resolve edge-tts alongside most modern stacks without conflict, and a minor upgrade is unlikely to break an import. The risk sits at the other end, in the remote service, where a change in Microsoft's behaviour would surface as a runtime failure rather than a version conflict.

The licence needs attention. The repository carries a gpl-3.0.txt file at the top level, while the package metadata reported for the project is NOASSERTION, meaning the machine-readable classifier does not state a licence. Two signals point at GPL-3.0, but they are not the same signal, and the README does not discuss licensing at all. If you plan to redistribute edge-tts inside a closed product, read the LICENSE file in the repository and get your own advice rather than inferring from the classifier.

Editorial conclusion

Adopt edge-tts if you want Edge's neural voices inside a Python pipeline and you can accept an online dependency with no API key. Skip it if you need offline synthesis, custom SSML, or a guaranteed speech interface: the README states that custom SSML support was removed because Microsoft blocks SSML that Edge itself would not generate. Before committing, run edge-tts --list-voices and confirm the voice you need is still served, then test your longest input for truncation, because the README does not describe what happens to oversized requests.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. rany2/edge-tts on GitHub
4. README
5. Releases