pyttsx3

2.99 · active · verified Sat Apr 11

pyttsx3 is a cross-platform, offline Text-to-Speech (TTS) library for Python 3. It allows developers to convert written text into spoken audio without an internet connection, leveraging native speech engines like Sapi5 on Windows, NSSpeechSynthesizer on macOS, and eSpeak/eSpeak-NG on Linux. The library provides a simple API to control speech rate, volume, select different voices, and save synthesized speech to audio files like MP3 or WAV. It is actively maintained, with regular updates to improve platform compatibility and fix bugs.

Warnings

gotcha The `engine.runAndWait()` method is crucial for speech output. If not called, queued `engine.say()` commands will not be processed, or only the first message might be spoken before the script exits. It blocks until all queued speech is complete. In GUI applications, consider running speech in a separate thread to prevent the UI from freezing.
Fix: Always call `engine.runAndWait()` after queuing speech with `engine.say()`. For multiple `say()` calls, queue all then call `runAndWait()` once, or call `runAndWait()` after each `say()` for sequential, blocking output. For non-blocking behavior in GUIs, run the TTS operations in a dedicated thread.
gotcha Platform-specific dependencies are often required beyond `pip install pyttsx3`. On Windows, `pywin32` is frequently needed. On Linux, system packages like `espeak-ng` or `espeak` and `libespeak1` are mandatory. On macOS, `pyobjc` might be necessary for some environments or Python versions, specifically `pyobjc>=9.0.1`.
Fix: Consult the `pyttsx3` documentation or `pip` output for platform-specific installation instructions if you encounter 'No engine could be found' or driver initialization errors. Install `pywin32` via `pip` on Windows, `espeak-ng` and `libespeak1` via your system's package manager on Linux, and potentially `pyobjc` via `pip` on macOS.
breaking Recent versions of pyttsx3 (e.g., 2.99) have explicitly removed Python 2 compatibility code, making them Python 3-only. Projects relying on older `pyttsx3` versions in a Python 2 environment will break if upgraded to the latest `pyttsx3`.
Fix: Ensure your project runs on Python 3. For legacy Python 2 projects, stick to older `pyttsx3` versions (e.g., 2.6) that explicitly stated Python 2 compatibility, or migrate your project to Python 3.
gotcha In versions prior to 2.95, the `engine.save_to_file()` method on macOS (Darwin platform using the NSSS driver) could produce empty audio files. While this was addressed in v2.95, users on older versions might still encounter this bug.
Fix: Upgrade to `pyttsx3` v2.95 or newer if experiencing empty audio files when using `save_to_file()` on macOS. If upgrading is not an option, consider alternative methods for audio file generation or system-specific workarounds.
gotcha Occasional `ModuleNotFoundError` or driver initialization errors can occur due to incorrect Python environment setup (e.g., pip installing to a different Python interpreter than the one being run) or outdated `wheel` package. Using `python -m pip` can sometimes help.
Fix: Always use `python -m pip install pyttsx3` to ensure the package is installed for the correct Python interpreter. If installation errors persist, try `pip install --upgrade wheel` before installing `pyttsx3`. Consider using virtual environments to manage dependencies.

Install

pip install pyttsx3 Standard installation
pip install pywin32 Additional for Windows (if SAPI5 fails)
sudo apt-get install espeak-ng libespeak1 Additional for Linux (Debian/Ubuntu for eSpeak-NG)
pip install pyobjc>=9.0.1 Additional for macOS (if NSSpeechSynthesizer fails, specific versions)

Imports

pyttsx3
```
import pyttsx3
```

Quickstart

This quickstart demonstrates how to initialize the `pyttsx3` engine, adjust common properties like speech rate and volume, select a specific voice, queue multiple text utterances, and then process them using `runAndWait()`. It also shows how to stop the engine gracefully.

import pyttsx3

# Initialize the TTS engine
engine = pyttsx3.init()

# Get current speech rate and set a new one
rate = engine.getProperty('rate')
print(f"Current speaking rate: {rate}")
engine.setProperty('rate', 150) # words per minute

# Get current volume and set a new one (0.0 to 1.0)
volume = engine.getProperty('volume')
print(f"Current volume: {volume}")
engine.setProperty('volume', 0.9)

# Get available voices and set a female voice (if available)
voices = engine.getProperty('voices')
for voice in voices:
    if 'female' in voice.name.lower(): # Or check voice.id for specific IDs
        engine.setProperty('voice', voice.id)
        break

# Queue text to be spoken
engine.say("Hello, welcome to pyttsx3!")
engine.say("I can speak at different rates and volumes.")

# Process the speech queue and wait for it to finish
engine.runAndWait()

# Save speech to a file (requires espeak-ng on Linux to save to MP3/WAV, or other OS native capabilities)
# engine.save_to_file('Hello World', 'output.mp3')
# engine.runAndWait()

# Stop the engine when done
engine.stop()

view raw JSON →