Arquitetura

O whispa-pi é a camada de appliance por cima do whispa. Injeta um gravador, o pipeline do whispa e um leitor num loop Appliance, por isso o loop em si é puro e testável enquanto o I/O de áudio faz shell-out para sox/ALSA.

flowchart LR
  MIC(["🎙 mic"]) --> REC["Gravador<br/>(sox VAD / arecord)"]
  REC --> P["whispa VoicePipeline<br/>whisper.cpp → Ollama → Piper"]
  P --> PL["Leitor<br/>(aplay / sox)"]
  PL --> SPK(["🔊 coluna"])
  P -. loop .-> REC

Mapa de módulos

Módulo	Responsabilidade
appliance.ts	O loop Appliance (runOnce, loop), injetado com gravador/pipeline/leitor
audio.ts	SoxVadRecorder / ArecordRecorder, AplayPlayer / SoxPlayer
config.ts	Config em camadas: defaults → ficheiro JSON → variáveis WHISPA_*
main.ts	Liga os motores reais do whispa + áudio e corre o loop (o bin whispa-pi)

Princípios de design

• Loop puro, I/O injetado — o Appliance depende de interfaces, por isso é testado com fakes; sem hardware necessário para os testes.
• Reutilizar, não bifurcar — a orquestração STT/LLM/TTS vem do whispa (dependência git).
• Qualquer trigger — o runOnce() pode ser acionado por VAD, wake word ou botão GPIO.
• Pronto para arranque — inclui um unit systemd e um script de instalação idempotente para Raspberry Pi OS.