How rhasspy/wyoming-satellite works
Project Type & Purpose
• This is a Python-based remote voice satellite that uses the Wyoming protocol to handle audio streaming, wake word detection, and voice activity detection (VAD). It can integrate with Home Assistant and other voice assistant platforms. The satellite can work with various audio sources (microphone commands via ALSA) and supports both local and remote wake word detection modes.
• It also includes audio enhancements (using webrtc noise suppression and gain control), event command triggers (for start/stop streaming, wake detection, transcription, etc.), and is packaged with containerization (Docker and docker-compose files).
Analyzing the File Structure
• Core source files live in the “wyoming_satellite” directory, which includes modules for the main satellite process, event handlers, settings, and utility functions.
• The “installer” directory contains logic for setting up drivers, services (like microphone and speakers), and configuration scripts – essentially handling initial deployment concerns.
• The “examples” directory provides various example services (2mic and 4mic setups, commands for different operations) and even an example for a websocket service. These show how external commands and interactions are expected to work.
• The “script” directory comprises build, run, test, and setup scripts that serve as command-line entry points.
• Docker files, docker-compose, and additional configuration files point to the containerized deployment option.
Main Components
a. Audio Input/Output:
• Microphone Input – represents the capture via external commands (e.g., arecord) and can incorporate multiple profiles (2-mic, 4-mic, USB mic).
• Speaker Output – corresponds to playback commands (e.g., aplay) with options for volume or audio file triggers (awake, done, timer finished).
b. Audio Processing:
• Voice Activity Detection (VAD) – optionally activates streaming when speech is detected.
• Wake Word Detection – either local (via an external wake word service such as wyoming-openwakeword) or remote detection.
• Audio Enhancements – processing modules leveraging webrtc-noise-gain for automatic gain control, noise suppression, and volume scaling.
c. Control & Communication:
• Main Satellite Module (“wyoming_satellite”) – core logic that handles event processing, audio streaming to the server, and interfacing with the Wyoming protocol.
• Event Command Handler – triggers commands for various events like detection, starting/stopping streaming, transcript processing, errors, etc.
• Remote Communication Interface – uses TCP endpoints (e.g., “tcp://0.0.0.0:10700” and “tcp://127.0.0.1:10400”) for exchanging data with Home Assistant or another external server.
d. Installation & Deployment:
• Installer Scripts (“installer” directory) – manage dependencies, driver installations (for devices like the ReSpeaker HAT), and overall setup.
• Docker/Containerization – includes Dockerfile and docker-compose for containerized deployment of the satellite.
• Utility Modules – supporting configuration (settings, constants) and common functions (audio utilities, misc functions) found within the “wyoming_satellite/utils” directory.
Relationships and Interactions
• Audio flows from the microphone service into the processing pipeline. Based on configuration (command-line arguments like --vad, --wake-uri, etc.), processing determines whether to trigger wake word detection.
• Once a wake word is detected or VAD criteria are met, the event command handler activates corresponding commands (e.g., launching a transcript command, playing sound notifications).
• The main satellite module receives and sends data to an external server over TCP; this communication channel is essential for integration with Home Assistant.
• The installer and Docker-related components are part of the deployment/management layer, ensuring that the running instance has all dependencies and is properly isolated.
Architectural Patterns and Design Principles
• Modular design: separate modules for core satellite logic, audio processing, installer functionality, and external integrations.
• Event-driven architecture: using a series of event commands (startup, detection, streaming start/stop, etc.) to handle asynchronous operations.
• Containerization: support for running the entire system inside Docker for easier deployment and testing.
• Command-line/Script driven launch: entrypoint scripts in the “script” directory that abstract away underlying complexity for end-users.