{"id":7501,"library":"piper-tts","title":"Piper TTS","description":"Piper TTS is a fast, local, and neural text-to-speech engine optimized for CPU performance, allowing speech synthesis directly on device. It is currently at version 1.4.2 and receives frequent minor updates with occasional major version changes that introduce new features and API adjustments.","status":"active","version":"1.4.2","language":"en","source_language":"en","source_url":"https://github.com/OHF-voice/piper","tags":["TTS","speech-synthesis","local","neural-networks","AI","offline"],"install":[{"cmd":"pip install piper-tts","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core inference engine for ONNX models.","package":"onnxruntime"},{"reason":"System-level C library required for phonemization unless using pre-generated phoneme IDs. While Piper embeds its Python bindings, the underlying system library is often still needed.","package":"espeak-ng","optional":false}],"imports":[{"symbol":"PiperVoice","correct":"from piper import PiperVoice"},{"note":"SynthesisConfig resides in the 'voices' submodule since v1.3.0.","wrong":"from piper import SynthesisConfig","symbol":"SynthesisConfig","correct":"from piper.voices import SynthesisConfig"}],"quickstart":{"code":"import piper\nimport os\n\n# NOTE: Model files (.onnx and .json) are NOT included with the pip package.\n# You MUST download them separately, e.g., from huggingface.co/rhasspy/piper-voices\n# Example: 'en_US-lessac-medium.onnx' and 'en_US-lessac-medium.json'\n\n# Provide paths to your downloaded model files\nmodel_path = os.environ.get('PIPER_MODEL_PATH', 'path/to/your_downloaded_model.onnx')\nconfig_path = os.environ.get('PIPER_CONFIG_PATH', 'path/to/your_downloaded_model.json')\n\nif not os.path.exists(model_path) or not os.path.exists(config_path):\n    print(f\"Error: Model files not found. Please download '.onnx' and '.json' files.\")\n    print(f\"  Expected model at: {model_path}\")\n    print(f\"  Expected config at: {config_path}\")\n    print(f\"  Download example: https://huggingface.co/rhasspy/piper-voices/tree/main\")\nelse:\n    try:\n        # Load the voice model\n        voice = piper.PiperVoice.load(model_path, config_path=config_path)\n\n        # Get default synthesis configuration\n        synthesis_config = voice.config.synthesis\n        text = \"Hello, this is a test from Piper TTS.\"\n\n        print(f\"Synthesizing: '{text}'\")\n        audio_chunks_generator = voice.synthesize(text, synthesis_config)\n\n        num_chunks = 0\n        for audio_bytes in audio_chunks_generator:\n            num_chunks += 1\n            # In a real application, you would save audio_bytes to a file\n            # or stream it for real-time playback (e.g., using 'sounddevice').\n            # Example: print(f\"Received chunk of {len(audio_bytes)} bytes.\")\n            pass # Just iterate to demonstrate generation\n\n        print(f\"Successfully generated {num_chunks} audio chunks.\")\n        print(\"Audio can be saved to a WAV file using Python's 'wave' module or 'soundfile'.\")\n\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to load a Piper TTS voice model and synthesize speech. Remember that model files (`.onnx` and `.json`) must be downloaded separately. The `synthesize` method yields audio chunks (bytes) that can then be processed, saved, or played back."},"warnings":[{"fix":"Update your code to pass a `piper.voices.SynthesisConfig` object (e.g., `voice.config.synthesis`) and iterate over the generated audio bytes: `for audio_bytes in voice.synthesize(text, synthesis_config): ...`. The `synthesize_raw` method was removed.","message":"The Python API for `PiperVoice.synthesize` changed significantly in v1.3.0. It now requires a `SynthesisConfig` object as its second argument and directly yields raw audio bytes, rather than returning a stream or requiring `synthesize_raw`.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Review the GPLv3 license terms to ensure your project's compliance if you are using Piper TTS in a commercial or distributed application.","message":"The project license changed from MIT to GPLv3 in v1.3.0. This has implications for how you can use and distribute software built with Piper TTS.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Download the desired model files (e.g., `en_US-lessac-medium.onnx` and `en_US-lessac-medium.json`) from a repository like `huggingface.co/rhasspy/piper-voices` and provide their paths when loading `PiperVoice`.","message":"Piper TTS model files (`.onnx` for the model and `.json` for its configuration) are NOT included with the pip package. You must download them separately from external sources (e.g., Hugging Face).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `espeak-ng` is installed on your operating system (e.g., `sudo apt-get install espeak-ng` on Debian/Ubuntu, `brew install espeak-ng` on macOS, or via your OS's package manager).","message":"For phonemization, Piper TTS relies on `espeak-ng`. While the Python package embeds `espeak-ng`'s Python bindings, the underlying `espeak-ng` C library binaries are still a system-level dependency for many phonemization tasks.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Download the desired model and config files (e.g., from huggingface.co/rhasspy/piper-voices) and ensure the `model_path` and `config_path` arguments to `PiperVoice.load()` are correct.","cause":"The Piper TTS model (.onnx) or its configuration file (.json) was not found at the specified path. These files are not installed with the pip package.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'path/to/model.onnx'"},{"fix":"Migrate your code to use the `PiperVoice.synthesize()` method. It now takes a `piper.voices.SynthesisConfig` object (e.g., `voice.config.synthesis`) and yields audio bytes directly.","cause":"The `synthesize_raw` method was removed in version 1.3.0 as part of an API overhaul.","error":"AttributeError: 'PiperVoice' object has no attribute 'synthesize_raw'"},{"fix":"Pass a `SynthesisConfig` object, typically obtained from the loaded voice (`voice.config.synthesis`), as the second argument: `voice.synthesize(text, voice.config.synthesis)`.","cause":"Since Piper TTS v1.3.0, the `synthesize` method requires a `piper.voices.SynthesisConfig` object as its second argument.","error":"TypeError: PiperVoice.synthesize() missing 1 required positional argument: 'config'"}]}