How to Use Piper: The Beginner's Guide (First Install, Your First Voice, First WAV, and the Voice-Quality Rule)

CodexFuse Team · 2026-11-01T10:35:45.625Z · 19 min read

What is Piper, exactly?

Piper is a free, offline neural text-to-speech engine that turns typed text into natural-sounding spoken audio on your own computer — no cloud account, no API key, no internet connection. If you want a piper tts tutorial that starts at zero, this is the whole idea: you install one Python package, download a voice model, and one command turns your sentence into a WAV file. (One quick note: this guide is about the software — the speech engine created by Michael Hansen in the Rhasspy project — not the plumber's pipe tool or the Pied Piper.)

Under the hood, Piper converts your text to phonemes with an embedded espeak-ng phonemizer, then synthesizes a waveform directly from those phonemes with a small neural voice model running on ONNX Runtime — which is why it speaks in real time on an ordinary CPU, even a Raspberry Pi. It became the default local text-to-speech engine in Home Assistant's Assist voice pipeline, so thousands of homelabbers already run it on their home servers. And if you ever want a quick online alternative instead of a local engine, CodexFuse's text-to-speech tool runs in your browser — but everything in this guide stays on your machine, which is the point of Piper.

How do you go from install to your first WAV in ten steps?

The whole beginner arc in one place:

1. Create a Python virtual environment so Piper does not touch your system packages.
2. Run pip install piper-tts — version 1.8.0 is the current release (September 2026).
3. Run python -m piper.download_voices with no arguments to list every available voice.
4. Download one voice: python -m piper.download_voices en_US-lessac-medium.
5. Confirm you have the matching pair: en_US-lessac-medium.onnx plus en_US-lessac-medium.onnx.json in the same folder.
6. Synthesize your first file: python -m piper -m en_US-lessac-medium -f hello.wav -- "Hello from your machine."
7. Play it: aplay hello.wav on Linux (or any audio player on other systems).
8. If it is not on your speakers yet, check the JSON config sits next to the .onnx file — that is the most common first-run failure.
9. Repeat with your own sentences before you change anything else.
10. When you start building, load the voice once in Python and stop calling the CLI per sentence.

How do you install Piper?

You install Piper with pip install piper-tts inside a virtual environment. That is the canonical install line from the PyPI page, and it works on Python 3.9 or newer — current Linux distributions, macOS, and Windows all qualify. The package ships a piper command, so python -m piper --help confirming without an error means you are installed.

A fresh virtual environment is the move:

python3 -m venv tts-env
source tts-env/bin/activate
pip install piper-tts

There is also a standalone binary build of Piper for systems where you would rather not touch Python at all — the classic echo "Hello" | piper --model voice.onnx --output_file hello.wav style. But the PyPI package is the maintained path in 2026: version 1.8.0 (released September 4, 2026) is what every command in this guide was tested against, and it is the one the Open Home Foundation now develops under the name OHF-Voice/piper1-gpl.

Two install paths, one honest decision:

How do you download your first voice?

You download a voice with python -m piper.download_voices en_US-lessac-medium, and Piper writes two files into your current folder. That is the entire download step — there is no account, no license key, and nothing to compile. Run the module with no arguments first if you want to browse the full voice list.

The two files are en_US-lessac-medium.onnx (the neural network, about 63 MB for a medium English voice) and en_US-lessac-medium.onnx.json (its config: sample rate, phoneme map, default settings). They are a matching pair and must stay together in the same folder — say it once and save yourself the most common beginner error. If you keep voices in a fixed location, pass --download-dir so every later command looks in the same place.

Voices live in the community-maintained rhasspy/piper-voices collection on Hugging Face, and new voices appear there over time. Each voice is trained by a different community contributor, so quality varies by voice and language — grab one, listen, and try another if it does not suit your ear. The naming pattern is language_REGION-voicename-quality, so de_DE-thorsten-medium is a German voice named Thorsten at medium quality, and es_ES-davefx-medium is its Spanish counterpart.

How do you make your first WAV?

Your first WAV is one line: python -m piper -m en_US-lessac-medium -f hello.wav -- "Hello from your machine.". The -m names the voice, -f names the output file, and the -- separates your text from the command-line options — that separator matters, because a sentence starting with a hyphen could otherwise be read as a flag.

Play hello.wav in any player and you have done the whole thing: text in, spoken audio out, nothing left your machine. If you have ffplay installed, drop the -f flag and Piper plays the audio straight to your speakers without writing a file. The classic echo-pipe form still works too:

echo "This sentence is spoken first." | piper --model en_US-lessac-medium.onnx --output_file hello.wav

If nothing comes out, check two things in order: the .onnx.json file sitting next to the .onnx file (FileNotFoundError for the config is the classic), and that you are running the command from the folder where the voice was downloaded. Both fixes take ten seconds.

What do the low, medium, and high voice labels actually mean?

The quality labels describe model size, not a quality rating — "low" voices often beat your operating system's built-in TTS. A medium English voice is roughly 60 MB; a high one is about double that, needs more CPU per second, and sounds only marginally better for most uses. That is the voice-quality rule: pick medium first, and only reach for high when you can hear a difference that matters.

The four rungs are x_low, low, medium, and high. Medium is the sweet spot the community converges on: medium voices produce 22,050 Hz audio, which is plenty for voiceovers, announcements, and narration, and Home Assistant's own docs benchmark a medium model generating 1.6 seconds of voice per second on a Raspberry Pi 4 — comfortably faster than real time. An independent 2026 test on a laptop CPU measured a real-time factor of 0.025, meaning an hour of speech in about a minute and a half.

One more honest note: voices are trained by different community members, so the same label does not guarantee the same character across languages. Always listen to a voice before you commit it to a project — the samples page for the voice collection exists exactly for this.

How do you tune speed, volume, and expressiveness?

You tune how a sentence sounds with a SynthesisConfig — no new model needed. length_scale controls speed (below 1.0 is faster, above 1.0 is slower), volume scales loudness, and noise_scale / noise_w_scale add variation to the voice and the timing of each sound, which keeps long passages from sounding monotone.

from piper import PiperVoice, SynthesisConfig
voice = PiperVoice.load("en_US-lessac-medium.onnx")
cfg = SynthesisConfig(length_scale=1.1, volume=1.0)
voice.synthesize_wav("Your order has shipped.", wav_file, syn_config=cfg)

Measured examples from a 2026 test: a length_scale of 0.8 made a sentence 13% shorter, and 1.3 made it about 25% longer. For e-learning narration, around 1.1 sounds calmer; for phone menus and spoken alerts, 0.9 feels snappier. Keep volume at 1.0 or below to avoid clipping.

When Piper mispronounces a name or a technical term, you can override it with raw phonemes: wrap IPA phonemes from espeak-ng -v en-us --ipa=3 -q <word> in double square brackets inside your text, like The [[ bˈætmæn ]] movie. Use it sparingly — rephrasing the sentence or spelling a word the way it sounds fixes most real cases.

How do you use Piper from Python?

You load the voice once and reuse the object: voice = PiperVoice.load("en_US-lessac-medium.onnx"), then voice.synthesize_wav(text, wav_file). Loading once matters because model loading dominates the cost of a short sentence — every fresh PiperVoice.load() in a loop is the performance bug beginners write first.

For audiobooks or long narration, the streaming generator is the right shape:

from piper import PiperVoice
voice = PiperVoice.load("en_US-lessac-medium.onnx")
for chunk in voice.synthesize(text):
    audio = chunk.audio_int16_array  # one sentence of audio
    play(audio, chunk.sample_rate)

Each chunk carries the audio as a NumPy array plus the sample rate and the phonemes that produced it, so you can insert your own pauses between sentences, show progress for long books, or start playing the first sentence while the rest is still generating. On multi-speaker voices such as en_US-libritts_r-medium, add speaker_id= to pick a different speaker from the same model. And if you are containerizing any of this, the Docker beginner guide walks through the container basics you will need.

Why should you stop calling the CLI in a loop?

Every CLI call reloads the voice model, so a script that shells out to piper a thousand times spends most of its time loading the same file. For anything repeated — alert scripts, narration pipelines, a voice bot — run Piper as a persistent server instead, so the model stays loaded in memory.

Piper ships its own small web server:

pip install "piper-tts[http]"
python -m piper.http_server -m en_US-lessac-medium --host 127.0.0.1 --port 5000

Then any program, in any language, gets speech with one HTTP call:

curl -X POST -H "Content-Type: application/json" \
  -d '{"text": "The server backup finished.", "length_scale": 1.1}' \
  -o alert.wav localhost:5000/synthesize

The JSON body also accepts voice, speaker_id, noise_scale, and noise_w_scale, so everything the Python API tunes is available over HTTP. Two rules from the field: never expose that port to the internet without authentication (it is a dev server, not a hardened one), and keep the host bound to localhost unless a specific machine needs it. If you are wiring spoken alerts into notification scripts, the Apprise beginner guide covers the matching notification half — Piper speaks, Apprise pings your phone.

How do you wire Piper into Home Assistant?

You install the Piper app, and Home Assistant discovers it through the Wyoming protocol — no YAML, no manual config files. Piper is the text-to-speech half of Home Assistant's fully local Assist pipeline: your command never leaves your home, and the Open Home Foundation (the nonprofit behind Home Assistant) now maintains Piper itself, which is why the integration is this smooth.

The wire-up, per the official Home Assistant docs:

1. In Home Assistant, go to Settings > Add-ons, open the add-on store, search for "Piper", and install it.
2. Start the Piper app. It hosts a Wyoming protocol server on port 10200.
3. Go to Settings > Devices & Services, add the Wyoming integration — Home Assistant discovers Piper automatically.
4. Go to Settings > Voice assistants and pick Piper as the text-to-speech engine.
5. Click Try Voice, type a sentence, and hear your server speak it.

Home Assistant's docs benchmark a medium model generating 1.6 seconds of voice per second on a Raspberry Pi 4, which is why the Pi is the classic host for this. If you would rather run Piper on a different machine than Home Assistant itself, the rhasspy/wyoming-piper Docker image takes a --voice flag and exposes the same port 10200 — Home Assistant connects over your LAN the same way. And if that voice bot ends up living on rented hardware, the what is VPS hosting guide explains where a small always-on server fits.

Piper vs Coqui vs Bark vs XTTS: which offline TTS should you pick?

Piper is the fast, light generalist; the others trade size and speed for voice cloning and expressiveness. Pick by what you actually need, not by hype:

The short version: choose Piper when you need private, fast, reliable speech on modest hardware — the Home Assistant lane. Choose XTTS when the job is cloning a specific voice from a few seconds of audio and you can afford the hardware. Choose pyttsx3 when "robotic but instant" is fine, and gTTS or an online tool when you are online anyway and want zero setup. Piper is simply the best balance for automation scripts and always-on boxes.

What mistakes do Piper beginners keep making?

The same five, in rough order of how often they appear:

Where can you take Piper next?

The natural arc after this guide is a full voice pipeline: faster-whisper listens, a local model answers, Piper speaks the reply — every byte stays on your machine. The offline voice-assistant pattern is exactly how homelabbers build private push-to-talk assistants on one modest box. From there, spoken server alerts (a cron job, the HTTP server, and your own voice), audiobook chapters with sentence-by-sentence synthesis, and narration for videos you would rather not record yourself are all one script away. And the sibling direction — turning speech back into text — is the faster-whisper lane, the STT mirror of everything you just built.

Sources

• piper-tts on PyPI (current release 1.8.0, September 4 2026; install docs, Python API, HTTP extra) — pypi.org/project/piper-tts/
• PromptQuorum Piper TTS review (September 5 2026; history from Rhasspy to the Open Home Foundation, MIT to GPL-3.0 license change, CLI/Python API, XTTS comparison) — promptquorum.com/power-local-llm/piper-tts-review
• PyInns: Text to Speech in Python with Piper (October 31 2026; tested on piper-tts 1.8.0, SynthesisConfig tuning, real-time factor 0.025, HTTP server) — pyinns.com/python/llm-and-generative-ai/text-to-speech-python-piper-tts-2026
• SSD Nodes: self-hosted speech to text and TTS (versions checked October 11 2026; voice pair rule, --data-dir, HTTP server, /synthesize endpoint) — ssdnodes.com/learn/self-hosted-speech-to-text-and-tts
• llmconfigurator: offline voice assistant (October 2026; Whisper + Ollama + Piper wiring, medium as the sweet spot, XTTS 10x slower) — llmconfigurator.com/en/guides/offline-voice-assistant
• Home Assistant official docs: fully local voice assistant (Piper app install, Wyoming discovery, 1.6s of voice per second on a Pi 4) — home-assistant.io/voice_control/voice_remote_local_assistant/
• exitcode0.net: Wyoming Piper Docker Compose (re-tested October 2026; rhasspy/wyoming-piper image, port 10200, current voice names) — exitcode0.net/posts/wyoming-piper-docker-compose/
• wyoming-piper on PyPI (OHF-Voice repository, script/run flags, port 10200) — pypi.org/project/wyoming-piper/
• rmauro.dev: Make Your Machine Talk with Piper TTS (July 2025; virtual environment, voice pair, raw streaming, --cuda option) — rmauro.dev/how-to-run-piper-tts-on-your-raspberry-pi-offline-voice-zero-internet-needed/

Frequently asked questions

Is Piper free to use?

Yes — there is no paid tier, subscription, or license fee for Piper itself; the only costs are your hardware and your time. One thing to know: the actively maintained repository (OHF-Voice/piper1-gpl) is licensed GPL-3.0-or-later, changed in 2025 from the original repo's MIT license, and each voice model carries its own license from its contributor — so check both before shipping Piper inside a commercial product.

Does Piper work offline on a Raspberry Pi?

Yes. Piper was designed for exactly this: it runs in real time on CPU-only hardware, and Home Assistant's docs benchmark a medium voice generating 1.6 seconds of speech per second on a Raspberry Pi 4. No GPU, no internet, no API key — the Pi is the classic host for Piper, especially as Home Assistant's voice pipeline.

What is the difference between Piper and Coqui, Bark, or XTTS?

Piper is the fast, light generalist: small models, real-time CPU synthesis, pre-trained voices you download once. Coqui XTTS v2 and Bark can clone a voice from a few seconds of sample audio and sound more expressive, but they are much heavier and slower on CPU. Pick Piper for private, always-on speech; pick the cloners when a specific voice matters more than speed.

Can Piper clone my voice from a short recording?

No. Piper only speaks with pre-trained voice models — there is no mechanism to generate a new voice from an audio sample of a specific person. If voice cloning is the job, XTTS v2 is built for that; Piper is built for fast, private speech from voices you choose.

Do I need a GPU to use Piper?

No. Piper is designed to run acceptably fast on CPU alone — real-time on a Raspberry Pi, roughly 40x real time on a laptop CPU in a 2026 test. GPU acceleration is optional: install the onnxruntime-gpu package and pass --cuda (CLI) or use_cuda=True (Python) if you have compatible CUDA hardware.