Install & configure¶

Automated install (Raspberry Pi OS / Debian)¶

curl -fsSL https://raw.githubusercontent.com/marcelogdomingues/whispa-pi/main/scripts/install-pi.sh | bash

This installs sox + alsa-utils, Node.js 22, builds whisper.cpp, installs Ollama and pulls a model, downloads a Piper voice, and installs whispa-pi globally. Override defaults with env vars:

WHISPER_MODEL=small.en OLLAMA_MODEL=qwen2.5:3b PIPER_VOICE=en_US-amy-medium \
  bash scripts/install-pi.sh

The piper binary is distributed as a release download; if the script can't find it, grab it from https://github.com/rhasspy/piper/releases and put it on your PATH.

Manual install¶

See whispa's engine setup for whisper.cpp, Ollama and Piper, then npm install -g whispa-pi.

Configuration¶

Two ways, layered (env wins over file):

Config file¶

cp whispa-pi.config.example.json my-config.json
whispa-pi my-config.json

{
  "whisperModel": "models/ggml-base.en.bin",
  "ollamaModel": "llama3.2:1b",
  "piperModel": "voices/en_US-amy-medium.onnx",
  "systemPrompt": "You are a concise voice assistant.",
  "recorder": "sox",       // "sox" (voice-activated) or "arecord" (fixed length)
  "player": "aplay",       // "aplay" or "sox"
  "recordSeconds": 5,       // used by the arecord backend
  "device": "plughw:1,0"    // optional ALSA device
}

Environment variables¶

WHISPA_WHISPER_MODEL, WHISPA_OLLAMA_MODEL, WHISPA_OLLAMA_HOST, WHISPA_PIPER_MODEL, WHISPA_SYSTEM_PROMPT, WHISPA_RECORDER, WHISPA_PLAYER, WHISPA_RECORD_SECONDS, WHISPA_DEVICE.

Run at boot (systemd)¶

sudo cp systemd/whispa-pi.service /etc/systemd/system/
sudoedit /etc/systemd/system/whispa-pi.service   # set User + paths
sudo systemctl enable --now whispa-pi
journalctl -u whispa-pi -f                        # watch logs

Troubleshooting¶

No audio in/out — check arecord -l / aplay -l and set device.
Replies are slow — use a smaller LLM (llama3.2:1b) and whisper (tiny.en).
It never stops recording (sox) — raise the silence threshold or lower ambient noise; the VAD stops after ~1.5 s of silence by default.