imonlinux
28c4ade611
Refactor: Sync with Upstream Architectural Changes (Nov 2025) Type: Refactor / Feat Description This PR ports several major architectural changes and new features from the upstream OHF-Voice/linux-voice-assistant repository. Because our codebase has been significantly refactored (config file, state machine), these changes were ported manually to integrate them cleanly with our new architecture. This brings our fork up-to-date with the upstream's core logic and dependencies, ensuring we benefit from future bug fixes in those externalized libraries. Key Changes Audio Library Replaced: Replaced the sounddevice library with soundcard. New Audio Capture Loop: The entire audio processing pipeline in __main__.py has been rewritten. It no longer uses a Queue and a sounddevice callback. Instead, the process_audio thread now runs a blocking mic.recorder() loop from the soundcard library, which is the new architecture adopted by the upstream project. External Wake Word Libraries: All local wake word code (microwakeword.py, openwakeword.py, wakeword.py) and the lib/ directory have been deleted. They are replaced by new pip dependencies: pymicro-wakeword and pyopen-wakeword. New Feature: External Wake Words: Ported the feature to allow Home Assistant to provide custom, external wake words. The LVA will now download models sent from HA to a new local/ directory. New Feature: List Devices: Ported the --list-input-devices and --list-output-devices CLI helpers from upstream. Dependency Updates: > * Bumped aioesphomeapi to 42.7.0 and updated api_server.py to use AuthenticationRequest (from ConnectRequest). > * Constrained zeroconf to <1. > * Updated dev dependencies (black, flake8, etc.) Cleanup: Updated .gitignore to include the new /local/ download directory and mypy.ini for the new libraries.
Linux Voice Assistant
Experimental Linux voice assistant (LVA) for Home Assistant that uses the ESPHome protocol/API (via aioesphomeapi).
Runs on Linux aarch64 and x86_64 platforms. Tested with Python 3.13 and Python 3.11.
Supports announcments, start/continue conversation, and timers.
See the tutorial to build a satellite using a Raspberry Pi Zero 2 W and a ReSpeaker 2Mic HAT.
What's working:
- This fork is from https://github.com/OHF-Voice/linux-voice-assistant Release v1.0.0 which introduces the ablity to use both MicroWakeWord and OpenWakeWord detections models.
- Refactor: Sync with Upstream Architectural Changes (Nov 2025) incudes the 7 commits since the release of v1.0.0.
- Updated to support LED Events including GPIO based LED controls. Defaults to the ReSpeaker 2Mic Hat SPI leds, but you can use the Grove port GPIO12/13 by updating the config.json file.
- Updated to support running either APA102 or WS2812B LEDs from the SPI interface using a Micro Connectors 40-pin GPIO 1 to 2 Expansion Board. See the tutorial for instructions.
- Now supports ALSA, PulseAudio and PipeWire playback backends using the updated
linux_voice_assistant/mpv_player.py. - LVA will detect PipeWire, PulseAudio, and Alse audio backends and automatically use them in this order. You can override the by using the config.json file.
- You can choose between all MWW and OWW wake word within HA after the VLA is registered. Choosen wake words are saved to preferences.json in the linux-voice-assistant folder.
- The volume control is now persistant between connections and reboots. The volume setting gets stored in prefernces.json and loaded when LVA starts.
Add Full MQTT Control for LEDs and Mute
-
This branch introduces a comprehensive MQTT integration to bypass limitations in the pinned aioesphomeapi library and provide full remote control over the voice satellite's features and appearance.
-
It uses MQTT Discovery to automatically create and configure a device and its associated entities within Home Assistant. This allows for real-time control from the HA interface and enables powerful automations.
Key Features:
-
A switch entity to mute and unmute the microphone.
-
A full suite of select and light entities to customize the effect, color, and brightness for each voice assistant state (Idle, Listening, Thinking, Responding, Error).
-
A number entity to configure the number of LEDs in the strip, allowing for use with custom hardware.
-
All settings are persistent, retained by the MQTT broker and re-applied whenever the application restarts.
See the tutorial to enable MQTT Controls.
Installation
Install system dependencies (apt-get):
libportaudio2(forsounddevice)build-essential(forpymicro-features)libmpv-dev(forpython-mpv)mpv(for testing)libmpv-dev(for building spidev)
Clone and install project:
git clone https://github.com/imonlinux/linux-voice-assistant.git
cd linux-voice-assistant
script/setup
Running
Use script/run or python3 -m linux_voice_assistant
See linux_voice_assistant/config.json.example for more options.
Connecting to Home Assistant if not auto detected
- In Home Assistant, go to "Settings" -> "Device & services"
- Click the "Add integration" button
- Choose "ESPHome" and then "Set up another instance of ESPHome"
- Enter the IP address of your voice satellite with port 6053
- Click "Submit"
ToDo:
- Implement echo-cancellation filter in PipeWire. (Improves wake word detection when audio is being played)
Merge jianyu-li's PR from source project to add mute switch function in this branchImplement MQTT entities to support advanced controls of the LVA.Configure LVA to advertise on Zeroconf/mDNS via Avahi for HA to auto detect (in progress)(Not needed as Release v1.0.0 implemented in code)Implement a single LVA systemd unit file that can be addapted using profiles and drop-ins (in progress)- Implement OWW model validation checks and error handling so that a bad model doesn't crash OWW
Make the selection of the right ALSA ar PA device more scriptedMake a Docker of the projectAlready done in parent repo.Add sensor entity that displays which wake word engine is being used for HA(Not needed as you can use both at the same time)- Could this be an DEB package?
Implement Stop for OWW(Not needed, Stop with MWW works even when using OWW detection models)- Stretch goal: create a smart installer full of validation and sanity checks