Behavioral changes:
Each wake word has its own timer.
Rapid repeats of the same phrase within the refractory window still get rejected (which is desirable).
A misfire of “Hey Jarvis” no longer locks out “Okay Nabu” immediately afterward.
If a user really wants to disable the gating, they can set:
"wake_word": {
"refractory_seconds": 0
}
and this code will treat it as “no refractory” (max(..., 0.0) above).
Summary
Add support for the ReSpeaker 2-Mic HAT momentary button as a first-class control surface for the Linux Voice Assistant. The button now behaves like:
Short press
If TTS or music is playing → stop playback (equivalent to the Stop wake word)
Otherwise → start a new conversation (equivalent to a wake word trigger)
Long press
Toggle microphone mute (wired through the existing set_mic_mute event, so MQTT state and LEDs stay in sync)
The implementation uses a polling-based GPIO loop (RPi.GPIO) instead of kernel edge-detection to avoid “Failed to add edge detection” issues on some HAT/overlay setups. Button behavior is fully configurable via config.json.
Extended the satellite state machine with a manual wake entrypoint:
Added manual_wakeup(self, phrase: str = "button"):
Mirrors the semantics of wakeup(), but does not require a wake-word model instance.
Respects the current state: only triggers from STARTING or IDLE.
If a timer alarm is ringing, calls the existing _stop_timer_alarm(...) instead of starting a new conversation (consistent with wake-word behavior).
Otherwise calls a shared helper _start_conversation(phrase).
Introduced _start_conversation(wake_word_phrase: str) to encapsulate:
Sending VoiceAssistantRequest(start=True, wake_word_phrase=...),
Transitioning to LISTENING,
Setting _is_streaming_audio = True,
Playing the configured wakeup_sound via tts_player.
Kept prior timer/alarm logic intact (including auto stop and Stop wake word behavior), so the button integrates cleanly with existing timer and TTS flows.
Imported the new ButtonController.
In _init_controllers():
Instantiated ButtonController when config.button.enabled is True.
Passed loop, event_bus, state, and config.button.
Stored the instance on state.button_controller to keep it alive for the lifetime of the process.
Left the rest of startup orchestration unchanged (audio engine, MQTT, LEDs, etc.), so the button is just an additional input surface plugged into the existing architecture.
Introduced a new ButtonController responsible for handling the ReSpeaker (or generic GPIO) button:
Uses RPi.GPIO with BCM numbering and internal pull-up (PUD_UP), assuming an active-low button.
Starts a dedicated polling thread that:
Reads the GPIO level at a configurable interval (default 10 ms / 100 Hz),
Detects press and release transitions,
Computes press duration to classify short vs long press.
Short press behavior:
If state.tts_player.is_playing or state.music_player.is_playing:
Schedules state.satellite.stop() on the asyncio loop,
Also stops music via state.music_player.stop().
Otherwise:
Schedules state.satellite.manual_wakeup("button") to start a new voice interaction (wake-like behavior without needing a model instance).
Long press behavior:
Toggles mic mute using the existing event path:
Publishes set_mic_mute on the EventBus with {"state": not state.mic_muted}.
This ensures MicMuteHandler remains the single writer for mic state, updates mic_muted_event, and syncs MQTT mute state/LEDs.
Designed to fail gracefully:
If ButtonConfig.enabled is False or RPi.GPIO is unavailable, logs a message and disables button support without affecting the rest of the system.
Added a new ButtonConfig dataclass:
enabled: bool = False
pin: int = 17 (BCM pin for the button)
long_press_seconds: float = 1.0
Extended the main Config dataclass with a button: ButtonConfig field.
Updated load_config_from_json() to construct button_config from the "button" section in config.json.
This allows enabling/disabling the button, changing the GPIO pin, and tuning the long-press threshold (and optional poll interval) without code changes.
Added a new user preference: alarm_duration_seconds (0 = infinite / Stop-only, >0 = auto-stop after N seconds).
Exposed that preference via MQTT/HA as a number entity (Alarm Duration) in seconds.
Updated the satellite timer logic so the alarm:
loops as before,
stops on the Stop wake word or wake wake word (existing semantics),
and optionally auto-stops after alarm_duration_seconds if configured.
Ensured all paths that stop the alarm cleanly restore audio state and wake word activation.
Added internal tracking for an alarm auto-stop:
self._timer_auto_stop_handle: Optional[asyncio.TimerHandle]
On VOICE_ASSISTANT_TIMER_FINISHED:
enables the Stop wake word,
starts the repeating timer_finished_sound alarm as before,
reads state.preferences.alarm_duration_seconds and, if > 0, schedules an auto-stop callback after that duration.
Centralized alarm stopping in helper methods:
_clear_timer_auto_stop() – cancels any pending auto-stop timer.
_stop_timer_alarm(reason: str) – stops the alarm sound, clears flags, unducks music, and removes the Stop wake word from active_wake_words.
_auto_stop_timer_alarm() – invoked by the scheduled timer, calls _stop_timer_alarm("auto_timeout").
Updated behavior paths:
wakeup() now stops a ringing alarm instead of starting a new conversation if a timer is active.
stop() (Stop wake word) stops a ringing alarm first; only falls back to stopping TTS if no alarm is active.
_play_timer_finished() continues to loop the sound until _timer_finished is cleared, then unducks and exits cleanly.
Added MQTT topics for the new alarm duration control:
lva/<device_id>/alarm_duration/set
lva/<device_id>/alarm_duration/state
Published a new Home Assistant number discovery config:
number.<device_id>_alarm_duration (0–3600 seconds, step 5, unit s).
On /alarm_duration/set:
validates and parses the payload as a non-negative integer,
publishes a set_alarm_duration event on the EventBus,
echoes the value back to /alarm_duration/state.
On connect, publishes the current alarm_duration_seconds from preferences to the state topic for retained startup behavior.
Updated Preferences dataclass with a new field:
alarm_duration_seconds: int = 0
Kept ServerState.save_preferences() unchanged so alarm_duration_seconds is automatically serialized into preferences.json.
Extended Preferences loading to initialize and backfill a new alarm_duration_seconds field (default 0).
Added a set_alarm_duration event handler to MicMuteHandler which:
validates and normalizes the duration value,
updates state.preferences.alarm_duration_seconds,
persists the updated preferences to disk.
Kept the existing “single writer” pattern (MicMuteHandler) for preferences/state updates.
File: linux_voice_assistant/__main__.py
In _init_basics(), the --list-output-devices block is updated so that:
It exits with 0 on success.
It exits with 1 only if an exception occurs.
Wrap the board import in a try/except and introduce a _BOARD_AVAILABLE flag.
If board (or Blinka/platformdetect) is not available or fails, log a clear warning and skip hardware LED initialization.
Keep the event subscriptions intact, but ensure all LED actions become no-ops when _is_ready is False.
Removed the home-grown backend probing / priority logic (pipewire → pulse → alsa) when no device is explicitly configured.
Kept support for explicitly specifying an audio_output_device in the config/CLI; if provided, it is passed through to mpv.
Added debug logging after mpv initialization to show:
current ao
current audio-device
the full audio-device-list
New CLI helpers
Added support for:
script/run --list-input-devices
script/run --list-output-devices
These code paths:
Initialize just enough of the audio stack to enumerate devices.
Print a clean, human-readable list of input/output devices (including PipeWire / PulseAudio virtual devices like Echo-Cancel Source and pipewire/echo-cancel-sink).
Exit cleanly with status 0 instead of trying to start the full LVA process afterward (fixing the previous CalledProcessError when --list-output-devices was used).
Behavior change
__main__.py now treats the “list devices” modes as early-exit utility modes, not “run LVA and then also print devices”.
This makes it practical to use these commands in setup docs and shell scripts.
Behavioral & logging changes
Improved the wake word processing loop to make the following clearly visible in DEBUG logs:
The current set of active wake word IDs (MWW/OWW).
When the Stop wake word:
is activated by the model,
is accepted (i.e. meets refractory timing + is currently allowed), and
is ignored because it is no longer in active_wake_words.
Ensured the special stop model:
Is only treated as “active” when state.stop_word.is_active is True.
Is flipped back to inactive immediately after satellite.stop() is called, so:
The first “Stop” that passes all checks cancels playback and alarm tones.
Subsequent detections in the same moment appear as “TRIGGERED but IGNORED” (expected and now clearly logged).
Why this matters
When the LVA is playing audio (TTS or timer alarm), you can now:
See exactly when the Stop model fires.
Confirm that playback is being canceled at the right time.
Understand why you might see multiple “Stop wake word ACTIVATED” messages even though the alarm already stopped (model still “hearing” the tail, but logically ignored).
This matches the behavior seen in your logs:
At lower volumes / with AEC, stop is reliably accepted and playback stops immediately.
At high volumes without AEC, the model sees far less “clean” speech, so activations are rare or absent.
(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.
imonlinux