Instalar & configurar¶

Instalação automática (Raspberry Pi OS / Debian)¶

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

Isto instala sox + alsa-utils, Node.js 22, compila o whisper.cpp, instala o Ollama e faz pull de um modelo, descarrega uma voz Piper e instala o whispa-pi globalmente. Sobrepõe os defaults com variáveis de ambiente:

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

O binário piper é distribuído como download de release; se o script não o encontrar, obtém-no em https://github.com/rhasspy/piper/releases e coloca-o no PATH.

Instalação manual¶

Ver o setup dos motores do whispa para whisper.cpp, Ollama e Piper, e depois npm install -g whispa-pi.

Configuração¶

Duas formas, em camadas (env ganha ao ficheiro):

Ficheiro de config¶

cp whispa-pi.config.example.json a-minha-config.json
whispa-pi a-minha-config.json

{
  "whisperModel": "models/ggml-base.en.bin",
  "ollamaModel": "llama3.2:1b",
  "piperModel": "voices/en_US-amy-medium.onnx",
  "systemPrompt": "És um assistente de voz conciso.",
  "recorder": "sox",       // "sox" (ativado por voz) ou "arecord" (duração fixa)
  "player": "aplay",       // "aplay" ou "sox"
  "recordSeconds": 5,       // usado pelo backend arecord
  "device": "plughw:1,0"    // dispositivo ALSA opcional
}

Variáveis de ambiente¶

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

Correr no arranque (systemd)¶

sudo cp systemd/whispa-pi.service /etc/systemd/system/
sudoedit /etc/systemd/system/whispa-pi.service   # define User + caminhos
sudo systemctl enable --now whispa-pi
journalctl -u whispa-pi -f                        # ver logs

Resolução de problemas¶

Sem áudio de entrada/saída — verifica arecord -l / aplay -l e define device.
Respostas lentas — usa um LLM mais pequeno (llama3.2:1b) e whisper (tiny.en).
Nunca pára de gravar (sox) — sobe o threshold do silêncio ou reduz o ruído ambiente; por defeito a VAD pára após ~1.5 s de silêncio.