Linux-Voice-Assistant
Experimental Linux-Voice-Assistant for Home Assistant that uses the ESPHome protocol/API (via aioesphomeapi).
Features:
- Works with Home Assistant
- Local wake word detection using integrated OpenWakeWord or MicroWakeWord
- Supports multiple architectures (linux/amd64 and linux/aarch64)
- Automated builds with artifact attestation for security
- Supports multiple wake words and languages
- Supports announcments, start/continue conversation, and timers
- Tested with Python 3.13 and Python 3.11.
- Prebuild docker image available on GitHub Container Registry
- Prebuild Raspberry Pi image
Usage:
Hardware:
You can for example use the Raspberry Pi Zero 2W with the Satellite1 Hat Board, the Respeaker Lite or the Respeaker 2Mic_Hat.
A list for possible compatible hardware can be found in the PiCompose documentation but basically any microphone that works with Pipewire can be used with the prebuild image.
Software:
Installation:
For Raspberry Pi users, we provide a prebuild image that can be flashed to a SD card. See PiCompose.
For all other users we have different installation methods available (Docker, systemd), each with its own dedicated instructions. See Linux-Voice-Assistant - Installation.
Parameter overview:
💡 Note: There is a environment variable for each parameter if you use docker or systemd based setup.
usage: __main__.py [-h] [--name NAME] [--audio-input-device AUDIO_INPUT_DEVICE] [--list-input-devices] [--audio-input-block-size AUDIO_INPUT_BLOCK_SIZE] [--audio-output-device AUDIO_OUTPUT_DEVICE] [--list-output-devices] [--wake-word-dir WAKE_WORD_DIR]
[--wake-model WAKE_MODEL] [--stop-model STOP_MODEL] [--download-dir DOWNLOAD_DIR] [--refractory-seconds REFRACTORY_SECONDS] [--wakeup-sound WAKEUP_SOUND] [--timer-finished-sound TIMER_FINISHED_SOUND] [--processing-sound PROCESSING_SOUND]
[--mute-sound MUTE_SOUND] [--unmute-sound UNMUTE_SOUND] [--preferences-file PREFERENCES_FILE] [--host HOST] [--network-interface NETWORK_INTERFACE] [--port PORT] [--enable-thinking-sound] [--debug]
| Parameter | Description | Default |
|---|---|---|
--name |
Name of the voice assistant device (required) | Autogenerated (lva-MAC-ADDRESS) |
--audio-input-device |
Soundcard name for input device | Autodetected |
--audio-input-block-size |
Audio input block size in samples | 1024 |
--audio-output-device |
mpv name for output device | Autodetected |
--wake-word-dir |
Directory with wake word models (.tflite) and configs (.json) | wakewords/ |
--wake-model |
ID of active wake word model | okay_nabu |
--stop-model |
ID of stop model | stop |
--download-dir |
Directory to download custom wake word models, etc. | local/ |
--refractory-seconds |
Seconds before wake word can be activated again | 2.0 |
--wakeup-sound |
Sound file played when wake word is detected | sounds/wake_word_triggered.flac |
--timer-finished-sound |
Sound file played when timer finishes | sounds/timer_finished.flac |
--processing-sound |
Sound played while assistant is processing | sounds/processing.wav |
--mute-sound |
Sound played when muting the assistant | sounds/mute_switch_on.flac |
--unmute-sound |
Sound played when unmuting the assistant | sounds/mute_switch_off.flac |
--preferences-file |
Path to preferences JSON file | preferences.json |
--host |
IP-Address for ESPHome server, use 0.0.0.0 for all | Autodetected |
--network-interface |
Network interface for ESPHome server | Autodetected |
--port |
Port for ESPHome server | 6053 |
--enable-thinking-sound |
Enable thinking sound on startup | False |
--debug |
Print DEBUG messages to console | False |
Build Information:
Image builds can be tracked in this repository's Actions tab, and utilize artifact attestation to certify provenance.
The Docker images are built using GitHub Actions, which provides:
- Automated builds for different architectures
- Artifact attestation for build provenance verification
- Regular updates and maintenance
The documentation for the build process can be found in the GitHub Actions Workflows file.