Skip to content

Voice

AEGIS has an integrated voice layer: Whisper for speech-to-text (you speak → AEGIS hears), Piper for text-to-speech (AEGIS replies → you hear it), and an optional wake-word service so you can talk hands-free.

How it works

You speak  →  Whisper STT  →  AEGIS processes  →  Piper TTS  →  You hear the reply

Whisper transcribes your speech. AEGIS processes the text as a normal chat message. Piper converts the reply to audio and plays it through your speakers or headphones.

Prerequisites

Whisper (STT)

Two options — pick one:

Option A — Cloud (OpenAI Whisper API): Set OPENAI_API_KEY in .env. AEGIS will use the whisper-1 model via the API. No local GPU needed; costs a small per-minute fee.

Option B — Local (faster-whisper): Install faster-whisper and set WHISPER_MODEL in .env (e.g. base.en for fast English-only, medium for better accuracy). Runs offline; needs a reasonable CPU or GPU.

Piper (TTS)

Download a Piper voice model and set PIPER_MODEL_PATH in .env. Piper voices are available here — the en_US-lessac-medium model is a good default.

Set PIPER_BINARY_PATH to the path of the piper executable (or piper.exe on Windows).

Enabling voice

In .env, set:

AEGIS_VOICE_STT=whisper          # or: faster-whisper
AEGIS_VOICE_TTS=piper

Restart AEGIS. The microphone button appears in the chat interface and the Settings → Voice section becomes active.

Using voice in the chat

  1. Click the microphone button (or press your wake word) to start speaking
  2. Speak your message naturally — there's no need to push-and-hold
  3. Whisper detects silence and transcribes automatically
  4. AEGIS processes the transcript and streams the reply
  5. Piper reads the reply aloud

During a reply: you can interrupt — say "stop", "cancel", "quiet", "never mind", or "thanks" to silence Piper immediately.

Follow-up conversation window

After AEGIS finishes speaking, a follow-up window stays open for 8 seconds. During that window: - You can continue speaking without re-triggering the wake word - AEGIS is listening, mic indicator stays lit - After 8 seconds of silence the window closes; the next utterance needs a wake word (or a mic button tap)

Wake word (hands-free)

A wake word lets you start a conversation without touching your device — say the word, hear a chime, then speak your message.

Default engine (web/desktop): Vosk local keyword model

  1. Install vosk (pip install vosk)
  2. Set AEGIS_WAKE_WORD=hey aegis (or any phrase) in .env
  3. Set VOSK_MODEL_PATH to a small Vosk model directory (e.g. vosk-model-small-en-us-0.15)

Native Android wake (optional): Picovoice Porcupine

The Android app supports a native foreground wake service that listens even with the screen off:

  1. Get a free access key from console.picovoice.ai
  2. Set PICOVOICE_ACCESS_KEY in .env
  3. In the Android app: Settings → Voice → enable "Native wake word"
  4. Default keyword is "porcupine" (built-in). For a custom "Hey AEGIS" keyword, train a .ppn file at the Picovoice console and drop it in the app's cache directory as wake.ppn

Echo cancellation

When Piper is speaking and the microphone is open, Whisper may pick up AEGIS's own voice and loop. AEGIS mutes the microphone while Piper is playing and re-opens it after the audio finishes — no hardware echo-cancellation module required.

Troubleshooting

No microphone button visible: Check that AEGIS_VOICE_STT and AEGIS_VOICE_TTS are both set in .env and that AEGIS was restarted after editing.

Whisper not transcribing: - Cloud: verify OPENAI_API_KEY is valid and has Whisper API access - Local: check that WHISPER_MODEL is spelled correctly and the model has been downloaded

Piper not speaking: - Verify PIPER_BINARY_PATH points to the actual piper executable (not the directory) - Verify PIPER_MODEL_PATH points to the .onnx model file (not the directory)

Wake word not triggering: - Vosk: confirm the VOSK_MODEL_PATH points to an unpacked model directory - Porcupine: confirm PICOVOICE_ACCESS_KEY is set server-side (the APK never bundles the key; it fetches it from GET /config)

Android: wake word stops after a few minutes: Ensure the AEGIS app has been exempted from battery optimization (Android Settings → Apps → AEGIS → Battery → Unrestricted). The foreground service is killed by aggressive battery management on some devices.