Install an isolated engine and pinned voice
Install an isolated engine and pinned voice — Local text-to-speech with Piper. Create a dedicated Linux environment; Fetch provenance before weights; Record integrity and distinguish failures. Practical assignment: Lab evidence.
Demo edition. The materials are undergoing editorial review.
Topics covered
- Create a dedicated Linux environment
- Fetch provenance before weights
- Record integrity and distinguish failures
Create a dedicated Linux environment
Use a disposable Linux practice directory rather than the system Python environment. The commands below are instructions for that learner machine; they are not executed on the author’s Mac or an existing VPS. Create a virtual environment, install the inspected Piper release and record the resolved dependency versions. Pinning Piper alone does not freeze every dependency, so preserve the freeze output and operating-system details together. Read the CLI help from the installed version before using later flags. If pip reports no matching distribution, compare Python version and CPU architecture with the published wheels. Do not solve that error by installing unreviewed packages from a search result or using administrator privileges throughout the environment. Success means the package metadata and help output are available; no synthesized audio is needed to verify installation.
The explicit .venv interpreter path avoids accidentally using a different activated environment. Save installation errors before retrying; a successful pip command in the wrong interpreter does not establish that the later Piper command uses that installation.
# Linux learner machine only; do not run on the Mac
mkdir -p piper-lab
cd piper-lab
python3 -m venv .venv
.venv/bin/python -m pip install "piper-tts==1.8.0"
.venv/bin/python -m pip freeze > requirements.lock.txt
.venv/bin/python -m pip show piper-tts > engine-version.txt
.venv/bin/python -m piper --help > cli-help.txt
Fetch provenance before weights
Download the MODEL_CARD from the inspected immutable revision first, then read its Dataset and Training sections against your rights ledger. Only after that review fetch the matching ONNX and ONNX JSON files from the same revision and directory. The model and configuration are a pair; mixing a new weight file with an old configuration can produce loading errors or incorrect audio settings. The pinned card says this voice requires Piper 1.5 or higher, which the inspected 1.8.0 release satisfies. Keep the voice’s language explicit: nl_BE is Belgian Dutch, not English. Save the downloaded card with the files even if a download helper omits it. If any URL fails, stop and inspect the upstream file tree; do not silently replace the voice with a similarly named mirror.
Do not keep several different revisions under the same active filenames. Store older pairs in revision-labeled archives and expose only the selected pair in voices, making the CLI’s filename lookup and your evidence record agree.
mkdir -p voices
voice_revision=e7229f7d33a10e145e109b886d661984201ac3c4
voice_base="https://huggingface.co/rhasspy/piper-voices/resolve/$voice_revision/nl/nl_BE/rdh/medium"
curl --fail --location "$voice_base/MODEL_CARD" -o voices/MODEL_CARD
cat voices/MODEL_CARD
# After inspecting the card, fetch the matching pair:
curl --fail --location "$voice_base/nl_BE-rdh-medium.onnx" -o voices/nl_BE-rdh-medium.onnx
curl --fail --location "$voice_base/nl_BE-rdh-medium.onnx.json" -o voices/nl_BE-rdh-medium.onnx.json
Record integrity and distinguish failures
Compute SHA-256 checksums after successful downloads and record the pinned URL next to them. Your own checksum detects later file changes; without a trusted published reference it does not independently prove who created the file. Also inspect file sizes and HTTP success: an HTML error page saved with .onnx is not a usable model. Keep installation failure, missing voice pair and malformed configuration as separate diagnoses. If the CLI cannot find the voice, check data directory and exact filename before reinstalling the engine. If loading fails only with one pair, restore the archived matching pair before changing drivers or GPU packages. Preserve the failed stderr message. The lesson’s deliverable is a complete local evidence folder, with installation metadata, card, exact pair and integrity record, rather than a claim that speech quality has already been tested.
A checksum check must use the original saved digest file, not one regenerated after an unexplained change. Otherwise the check merely blesses the changed bytes and loses its ability to reveal a replacement or corrupted download.
sha256sum voices/MODEL_CARD voices/nl_BE-rdh-medium.onnx voices/nl_BE-rdh-medium.onnx.json > voice-sha256.txt
ls -lh voices
# Later integrity check, after the recorded files are retained:
sha256sum --check voice-sha256.txt
Practical assignment
Lab evidence
Continue to learning