How janvarev/irene-voice-assistant works
Project Type and Purpose
• This is an offline voice assistant application built in Python. Its core purpose is to perform offline speech recognition (primarily using Vosk) and text-to-speech (using pyttsx-based solutions) while processing commands via a modular plugin (or “skill”) architecture.
• The README clarifies that it supports both voice interaction and text-based command simulation, with additional support for configuration via a settings manager and optional web APIs. It also explains integrations like Docker deployments, and even multi-microphone/client-server modes.
File Structure for Architectural Clues
• There are top-level components for core functionality (e.g., vacore.py, runva_cmdline.py, runva_vosk.py, runva_webapi.py) which indicate the main operational engine.
• The “lingua_franca” folder contains modules for language parsing/formatting and resource files for different languages – this forms the natural language processing (NLP) component.
• The “plugins”, “plugins_inactive”, and “plugins_vasi” directories group the skill extensions that add specialized behaviors. Also, the inclusion of “jaa.py” (the lightweight plugin engine) emphasizes that plugin orchestration is a core design pattern.
• There are supporting directories:
• “docs” for installation/deployment instructions,
• “model” for ASR models and related configuration,
• “mpcapi” for potential integration with external media players (like MPC-HC),
• “mic_client” and “webapi_client” which are front-end interfaces.
• Multiple configuration and Docker-related files (Dockerfile, options_docker etc.) indicate that the deployment and environment management are designed to be modular and containerized.
Main Components
A. Core Engine:
• The main control center is likely housed in “vacore.py” along with supporting scripts (runva_* files). This is responsible for initializing components, processing voice commands, and orchestrating responses.
• It interacts with configuration files (options/core.json) to load settings.
B. Speech Recognition:
• The project offers offline recognition primarily using Vosk (runva_vosk.py) and optionally the SpeechRecognition alternative (runva_speechrecognition.py). The “model” folder contains ASR models and resources needed for these.
• A helper component “vosk_asr_server.py” hints at a service-oriented approach for speech-to-text.
C. Text-to-Speech (TTS):
• The assistant leverages TTS engines (pyttsx, Silero, Elevenlabs, etc.) as indicated in both README and plugin implementations like “plugin_tts_*”.
D. Plugin (Skill) Engine:
E. Language Processing:
• The “lingua_franca” modules manage natural language parsing, number-to-text conversion, and language-specific formatting/expansion, crucial for correctly interpreting spoken commands.
F. External Interfaces:
• Web API integration (runva_webapi.py and the “webapi_client” folder) adds a network/HTTP layer for remote control or integration.
• The mic_client (with HTML/JS) provides an additional UI for audio input/output.
G. Configuration and Deployment:
• The “options” folder (created upon first run) and provided configuration JSON files determine runtime settings.
• Docker support is integrated (Dockerfile, docs/INSTALL_DOCKER.md, etc.) making containerized deployment central.
Relationships and Interactions
• Speech Recognition Engine (Vosk-based or SpeechRecognition alternative)
• TTS Engine(s)
• Plugin Manager (powered by Jaa.py and loading from various plugins folders)
• Language Processing Module (lingua_franca)
• The processed command then routes to the Plugin Manager which dynamically activates the corresponding plugin from the “plugins” directory.
• Data flows from the Plugin Manager to external systems (like MPC-HC via mpcapi) or web interfaces (webapi_client).
• Configuration flows: settings loaded into the core from options files.
• Deployment aspects: Docker-ized components and web manager (via runva_settings_manager.py) used for administrative tasks.
Architectural Patterns and Technologies
• The design uses a modular and pluggable architecture allowing for dynamic skill loading, which is essential for extensibility.
• The separation between core processing, speech-to-text, TTS, and plugin handling enforces the Single Responsibility Principle.
• The use of multiple deployment strategies (native Python execution and Docker containers) suggests a layered and environment-agnostic design.
• Integration with external hardware (microphones, MPC-HC) and web-based clients underscores a hybrid (client-server) design pattern in parts.