Nova — Open Source Voice Assistant

A small, self-contained voice assistant built on faster-whisper (STT), pyttsx3 / macOS say (TTS), and an energy-based VAD. No cloud calls, no proprietary models — runs entirely on your machine.

Quick Start (macOS)

cd super-nova
chmod +x setup.sh
./setup.sh
source .venv/bin/activate
python quickstart.py     # verify mic, TTS, STT, recorder all work
python nova.py           # start the voice agent

Then say "Hey Nova", pause, then your command. Or say "Hey Nova, what time is it?" in one breath.

Wake words

Any of these will activate Nova:

• nova
• hey nova
• hi nova
• ok nova / okay nova

If you say just the wake word with no command, Nova will reply "Yes?" and listen for your follow-up.

Layout

super-nova/
├── nova.py              # main voice loop
├── quickstart.py        # component sanity checks
├── setup.sh             # one-command install
├── requirements.txt
├── README.md
└── engine/
    ├── __init__.py
    ├── stt.py           # WhisperSTT (faster-whisper)
    ├── tts.py           # speak() — pyttsx3 with macOS `say` fallback
    ├── vad.py           # EnergyVAD
    ├── recorder.py      # ContinuousRecorder (sounddevice + VAD)
    └── wake.py          # has_wake_word()

Plug in your own actions

Nova will import actions.handle_command(cmd: str) -> str if a top-level actions.py exists. If not, a tiny built-in fallback handles time, date, greetings, and goodbye.

# actions.py
def handle_command(cmd: str) -> str:
    if "weather" in cmd:
        return "It's lovely outside."
    return f"I heard: {cmd}"

Troubleshooting

• No mic access — On macOS, grant Terminal/iTerm "Microphone" access in System Settings → Privacy & Security → Microphone.
• pyttsx3 hangs — Nova auto-falls back to the macOS say command after a 15-second timeout.
• First Whisper run is slow — The base.en model (~140 MB) downloads on first use, then caches under ~/.cache/huggingface/.
• portaudio errors — brew install portaudio, then re-run setup.sh.

License

MIT.