linux-voice-assistant/README.md

Linux Voice Assistant

Experimental Linux voice assistant for Home Assistant that uses the ESPHome protocol.

Runs on Linux aarch64 and x86_64 platforms. Tested with Python 3.13 and Python 3.11. Supports announcments, start/continue conversation, and timers.

Installation

Install system dependencies (apt-get):

• libportaudio2 or portaudio19-dev (for sounddevice)
• build-essential (for pymicro-features)
• libmpv-dev (for python-mpv)

Clone and install project:

git clone https://github.com/OHF-Voice/linux-voice-assistant.git
cd linux-voice-assistant
script/setup

Running

Use script/run or python3 -m linux_voice_assistant

You must specify --name <NAME> with a name that will be available in Home Assistant.

See --help for more options.

Microphone

Use --audio-input-device to change the microphone device. Use --list-input-devices to see the available microphones.

The microphone device must support 16Khz mono audio.

Speaker

Use --audio-output-device to change the speaker device. Use --list-output-devices to see the available speakers.

Sounds

Customize wake word and timer sounds (defaults are used if not specified):

python3 -m linux_voice_assistant ... \
    --wakeup-sound sounds/wake_word_triggered_old.wav \
    --timer-finished-sound sounds/timer_finished.flac

Available sounds:

• Wake sounds: wake_word_triggered.flac (default), wake_word_triggered_old.wav (classic)
• Timer sounds: timer_finished.flac (default), timer_finished_old.wav (classic)

The optional "thinking" sound plays while the assistant is processing. Enable it on startup with:

python3 -m linux_voice_assistant ... \
    --enable-thinking-sound

This enables the thinking sound by default and sets the Home Assistant switch to ON. The switch can be toggled at any time from the device page.

Wake Word

Change the default wake word with --wake-model <id> where <id> is the name of a model in the wakewords directory. For example, --wake-model hey_jarvis will load wakewords/hey_jarvis.tflite by default.

You can include more wakeword directories by adding --wake-word-dir <DIR> where <DIR> contains either microWakeWord or openWakeWord config files and .tflite models. For example, --wake-word-dir wakewords/openWakeWord will include the default wake words for openWakeWord.

If you want to add other wakewords, make sure to create a small JSON config file to identify it as an openWakeWord model. For example, download the GLaDOS model to glados.tflite and create glados.json with:

{
  "type": "openWakeWord",
  "wake_word": "GLaDOS",
  "model": "glados.tflite"
}

Add --wake-word-dir <DIR> with the directory containing glados.tflite and glados.json to your command-line.

Connecting to Home Assistant

1. In Home Assistant, go to "Settings" -> "Device & services"
2. Click the "Add integration" button
3. Choose "ESPHome" and then "Set up another instance of ESPHome"
4. Enter the IP address of your voice satellite with port 6053
5. Click "Submit"

Acoustic Echo Cancellation

Enable the echo cancel PulseAudio module:

pactl load-module module-echo-cancel \
  aec_method=webrtc \
  aec_args="analog_gain_control=0 digital_gain_control=1 noise_suppression=1"

Verify that the echo-cancel-source and echo-cancel-sink devices are present:

pactl list short sources
pactl list short sinks

Use the new devices:

# The device names may be different on your system.
# Double check with --list-input-devices and --list-output-devices
python3 -m linux_voice_assistant ... \
     --audio-input-device 'Echo-Cancel Source' \
     --audio-output-device 'pipewire/echo-cancel-sink'