{"id":3782,"library":"pyttsx3","title":"pyttsx3","description":"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.","status":"active","version":"2.99","language":"en","source_language":"en","source_url":"https://github.com/nateshmbhat/pyttsx3","tags":["text-to-speech","tts","audio","offline","speech-synthesis"],"install":[{"cmd":"pip install pyttsx3","lang":"bash","label":"Standard installation"},{"cmd":"pip install pywin32","lang":"bash","label":"Additional for Windows (if SAPI5 fails)"},{"cmd":"sudo apt-get install espeak-ng libespeak1","lang":"bash","label":"Additional for Linux (Debian/Ubuntu for eSpeak-NG)"},{"cmd":"pip install pyobjc>=9.0.1","lang":"bash","label":"Additional for macOS (if NSSpeechSynthesizer fails, specific versions)"}],"dependencies":[{"reason":"Often required for the SAPI5 driver to function correctly on Windows, especially in virtual environments or specific system configurations.","package":"pywin32","optional":true},{"reason":"The underlying TTS engine for Linux. Needs to be installed at the system level (e.g., via apt, dnf, pacman). `espeak` is an older alternative.","package":"espeak-ng","optional":true},{"reason":"May be required for the NSSpeechSynthesizer driver on macOS, particularly for older Python versions or specific setups. Version `9.0.1` or higher is sometimes recommended.","package":"pyobjc","optional":true}],"imports":[{"symbol":"pyttsx3","correct":"import pyttsx3"}],"quickstart":{"code":"import pyttsx3\n\n# Initialize the TTS engine\nengine = pyttsx3.init()\n\n# Get current speech rate and set a new one\nrate = engine.getProperty('rate')\nprint(f\"Current speaking rate: {rate}\")\nengine.setProperty('rate', 150) # words per minute\n\n# Get current volume and set a new one (0.0 to 1.0)\nvolume = engine.getProperty('volume')\nprint(f\"Current volume: {volume}\")\nengine.setProperty('volume', 0.9)\n\n# Get available voices and set a female voice (if available)\nvoices = engine.getProperty('voices')\nfor voice in voices:\n    if 'female' in voice.name.lower(): # Or check voice.id for specific IDs\n        engine.setProperty('voice', voice.id)\n        break\n\n# Queue text to be spoken\nengine.say(\"Hello, welcome to pyttsx3!\")\nengine.say(\"I can speak at different rates and volumes.\")\n\n# Process the speech queue and wait for it to finish\nengine.runAndWait()\n\n# Save speech to a file (requires espeak-ng on Linux to save to MP3/WAV, or other OS native capabilities)\n# engine.save_to_file('Hello World', 'output.mp3')\n# engine.runAndWait()\n\n# Stop the engine when done\nengine.stop()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"v2.99 and later (Python 2 compatibility removed around v2.99)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Prior to v2.95"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}