(Major change) main() function completely refactored into helpers. _init_controllers now handles decoupled initialization. _process_audio loop logic was fixed to correctly initialize wake words on startup.
mic.recorder() loop is now much more robust against OS buffering issue when the microphone is muted and wakewords were detected and processed after unmute.
__init__ was completely rewritten to be decoupled. It now listens for mic_muted/mic_unmuted events to manage its own state instead of reading from ServerState.
__init__ was completely rewritten to be decoupled. It now receives loop, event_bus, config, and preferences directly and no longer has any reference to ServerState.
ServerState is now a pure data container, no longer holding controller instances. The satellite reference was re-added, as it's required by the audio thread to call satellite.wakeup(). Fixed a TypeError by re-ordering non-default fields.
(Major change) main() function completely refactored into helpers. _init_controllers now handles decoupled initialization. _process_audio loop logic was fixed to correctly initialize wake words on startup.
Replaced sounddevice with soundcard, removed the audio Queue, added the new download directory to the search path, and added the device listing arguments
Replaced sounddevice with soundcard, removed the audio Queue, added the new download directory to the search path, and added the device listing arguments
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.
Refactor: Centralize Configuration into config.json
Type: Refactor Issue: Closes #XYZ (if you have one)
Description
This pull request completes a major refactoring goal by moving all (20+) command-line arguments into a single, centralized config.json file.
The application is now launched with a single -c or --config flag pointing to this new file, dramatically simplifying startup scripts and configuration management.
Changes
NEW: linux_voice_assistant/config.py > * Adds new dataclasses (AppConfig, AudioConfig, LedConfig, etc.) to define the application's configuration structure. > * Includes a load_config_from_json() helper to parse the JSON file and provide default values for any omitted sections.
MODIFIED: linux_voice_assistant/__main__.py > * Removed all argparse.add_argument() calls, except for the new --config flag. > * The main() function now calls load_config_from_json() at startup. > * All internal logic now references the config object (e.g., config.app.name) instead of the old args object.
Changes the user mode service file to the single command needed to start LVA. All other configuration arguments are in the linux_voice_assistant/config.json file.
Removed all argparse.add_argument() calls, except for the new --config flag. The main() function now calls load_config_from_json() at startup. All internal logic now references the config object (e.g., config.app.name) instead of the old args object.
Adds new dataclasses (AppConfig, AudioConfig, LedConfig, etc.) to define the application's configuration structure. Includes a load_config_from_json() helper to parse the JSON file and provide default values for any omitted sections
Goal: You currently have dependencies listed in both pyproject.toml and requirements.txt. These files are redundant and also conflicting (they list different things). This can cause confusion and versioning problems.
The Fix: We will make pyproject.toml the single source of truth by merging all dependencies into it and then deleting the old requirements.txt file.
I merged the two unique libraries from requirements.txt (gpiozero and spidev) into the dependencies list.
This is the major change. All the _is_speaking, _run_finished, etc. flags are gone, replaced by a single self._state variable and a _set_state method. The logic is now much cleaner.
Goal: satellite.py currently uses a set of boolean flags (_is_streaming_audio, _tts_played, _run_finished, _is_speaking) to figure out what it's doing. This is hard to read and easy to break. Replaced this with a clean, formal state machine (using an Enum). This makes the logic explicit and much easier to manage.
added the SatelliteState Enum at the top and removed the media_player_entity from ServerState as it's better managed by the satellite itself
Goal: We'll apply the exact same pattern to the MqttController. The paho-mqtt library runs its _on_message callback in a separate thread. We'll stop it from modifying state directly and instead schedule a new function to run on the main asyncio loop.
Here is the complete file. The key changes are:
The _on_message function is now tiny. It just gets the topic/payload and uses self.state.loop.call_soon_threadsafe to schedule a new function.
A new function _handle_message_on_loop contains all the logic that used to be in _on_message. This new function will run safely on the main asyncio loop, eliminating the race condition.
Fix MpvMediaPlayer Race Condition
Goal: The mpv library runs in its own thread. When a track finishes, its callback (_on_idle_active) runs in that thread and tries to modify the satellite's state, creating a race condition. We will fix this by "marshaling" that callback onto the main asyncio loop.
added loop=loop to the MpvMediaPlayer constructors
Selects the best available audio output backend for mpv.
The selection follows a clear priority:
1. A fully qualified device string (e.g., 'alsa/plughw:...') is used directly.
2. A simple device name tries PipeWire, then PulseAudio, then ALSA.
3. No device specified (or 'default') tries the default for PipeWire, PulseAudio, and ALSA in order.
## Summary: Feature - Add Full MQTT Control for LEDs and Mute
This pull request 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.
## File Changes
### pyproject.toml (Modified)
Adds paho-mqtt as a core dependency to enable MQTT communication.
Pins aioesphomeapi==41.13.0 to ensure stability with the existing codebase and avoid unresolved library issues on some platforms.
### linux_voice_assistant/mqtt_controller.py (New File)
Introduces the MqttController, a new class that manages all communication with the MQTT broker.
On startup, it connects to the broker and publishes discovery configurations for all entities, automatically creating them in Home Assistant.
Subscribes to command topics to receive instructions from the HA interface.
Subscribes to state topics to read retained messages on startup, ensuring all user settings are persistent.
Acts as a bridge, translating incoming MQTT messages into internal EventBus events for other components to act upon.
### linux_voice_assistant/led_controller.py (Modified)
Refactored for Full Configurability: The controller has been re-architected to remove all hard-coded effects and colors.
Central Configuration: It now uses a central configs dictionary to store the effect, color, and brightness settings for each voice assistant state (idle, listening, etc.).
Dynamic State Management: Subscribes to new set_<state>_effect and set_<state>_color events from the event bus to update its configuration in real-time.
Applies Custom Effects: The main voice event handlers (voice_stt_start, voice_stt_end, etc.) have been simplified to look up the user's chosen configuration and apply it.
New Animations: Implements a full suite of animations (Slow/Medium/Fast Pulse, Slow/Medium/Fast Blink, Spin) to be used by the effect selectors.
### linux_voice_assistant/__main__.py (Modified)
Adds command-line arguments (--mqtt-host, --mqtt-port, etc., and --num-leds) to configure the MQTT connection and initial LED setup.
Instantiates and starts the MqttController on application startup if an MQTT host is provided.
Includes the MicMuteHandler class, which listens for mute commands, updates the global mic_muted state, and clears the audio queue on unmute to prevent processing stale audio.
Updates the process_audio loop to respect the mic_muted flag.
### linux_voice_assistant/satellite.py (Modified)
Adds a handler for the VOICE_ASSISTANT_ERROR event, publishing a voice_error event to the EventBus so the LedController can provide visual feedback.
Fixes a race condition where the "Responding" LED effect was being cancelled prematurely, ensuring it now plays for the full duration of the TTS audio.
### models.py, entity.py, api_server.py (Modified)
Includes various compatibility fixes, reversions, and clean-up from the previous development cycle to create a stable base for the MQTT implementation. This ensures the application starts reliably with the pinned aioesphomeapi version.
Includes various compatibility fixes, reversions, and clean-up from the previous development cycle to create a stable base for the MQTT implementation. This ensures the application starts reliably with the pinned aioesphomeapi version.
Includes various compatibility fixes, reversions, and clean-up from the previous development cycle to create a stable base for the MQTT implementation. This ensures the application starts reliably with the pinned aioesphomeapi version.
Includes various compatibility fixes, reversions, and clean-up from the previous development cycle to create a stable base for the MQTT implementation. This ensures the application starts reliably with the pinned aioesphomeapi version.
Adds a handler for the VOICE_ASSISTANT_ERROR event, publishing a voice_error event to the EventBus so the LedController can provide visual feedback.
Fixes a race condition where the "Responding" LED effect was being cancelled prematurely, ensuring it now plays for the full duration of the TTS audio.
Adds command-line arguments (--mqtt-host, --mqtt-port, etc., and --num-leds) to configure the MQTT connection and initial LED setup.
Instantiates and starts the MqttController on application startup if an MQTT host is provided.
Includes the MicMuteHandler class, which listens for mute commands, updates the global mic_muted state, and clears the audio queue on unmute to prevent processing stale audio.
Updates the process_audio loop to respect the mic_muted flag.
imonlinux