linux-voice-assistant/README.md

Linux-Voice-Assistant

Experimental Linux-Voice-Assistant for Home Assistant that uses the ESPHome protocol.

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:

We have different installation methods available (Docker, systemd), each with its own dedicated instructions.

See Linux-Voice-Assistant - Installation.

Parameter overview:

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] [--port PORT]
                   [--enable-thinking-sound] [--debug]

Parameter	Description	Default
--name	Name of the voice assistant device (required)	-
--audio-input-device	Soundcard name for input device	System default microphone
--audio-input-block-size	Audio input block size in samples	1024
--audio-output-device	mpv name for output device	System default speaker
--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	Address for ESPHome server	0.0.0.0
--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.