# rhasspy/wyoming-satellite architecture

> Architecture diagram of the GitHub repository rhasspy/wyoming-satellite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rhasspy/wyoming-satellite
- Repository: https://github.com/rhasspy/wyoming-satellite

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Audio Capture Subgraph
    subgraph "Audio Capture"
        MI["Installer Microphone"]:::input
        M2["2Mic Service"]:::input
        M4["4Mic Service"]:::input
        MUSB["USB Mic Service"]:::input
    end

    %% Audio Processing Subgraph
    subgraph "Audio Processing & Enhancement"
        VAD["VAD"]:::processing
        WWD["Wake Word Detection"]:::processing
        AE["Audio Enhancements"]:::processing
    end

    %% Core Satellite Subgraph
    subgraph "Core Satellite Engine"
        CSE["Core Satellite Engine"]:::core
        ECH["Event Command Handler"]:::core
        RCI["Remote Communication Interface"]:::core
    end

    %% Speaker Output Subgraph
    subgraph "Speaker Output"
        SI["Speaker Installer"]:::output
        AN["Awake Notification"]:::output
        DN["Done Notification"]:::output
        TN["Timer Finished Notification"]:::output
    end

    %% Utility Modules Node
    UTL["Utility Modules"]:::util

    %% Deployment Subgraph
    subgraph "Installation & Deployment"
        INS["Installer Scripts"]:::deployment
        RD["Respeaker Drivers"]:::deployment
        subgraph "Containerization & Deployment"
            DF["Dockerfile"]:::deployment
            DC["docker-compose"]:::deployment
            RDS["Run Docker Script"]:::deployment
            BDS["Build Docker Script"]:::deployment
            SS["Setup Script"]:::deployment
            RS["Run Script"]:::deployment
            R2["2Mic Run Script"]:::deployment
            R4["4Mic Run Script"]:::deployment
            RUSB["USB Mic Run Script"]:::deployment
        end
    end

    %% External Integration
    HA["Home Assistant"]:::external

    %% Data Flow Connections
    MI -->|"captures audio"| VAD
    M2 --> VAD
    M4 --> VAD
    MUSB --> VAD

    VAD -->|"processes audio"| WWD
    WWD --> AE
    AE -->|"enhanced signal"| CSE

    CSE -->|"triggers events"| ECH
    ECH -->|"activates notifications"| SI
    SI --> AN
    SI --> DN
    SI --> TN

    CSE -->|"sends data"| RCI
    RCI -->|"communicates with"| HA

    UTL --- CSE

    %% Deployment influences Core System
    INS --- CSE
    RD --- INS
    DF --- RD
    DC --- RD
    RDS --- RD
    BDS --- RD
    SS --- RD
    RS --- RD
    R2 --- RD
    R4 --- RD
    RUSB --- RD

    %% Styling Definitions
    classDef input fill:#f9e79f,stroke:#B9770E,stroke-width:2px;
    classDef processing fill:#aed6f1,stroke:#2874A6,stroke-width:2px;
    classDef core fill:#abebc6,stroke:#229954,stroke-width:2px;
    classDef output fill:#d2b4de,stroke:#8E44AD,stroke-width:2px;
    classDef deployment fill:#f5b7b1,stroke:#C0392B,stroke-width:2px;
    classDef util fill:#d6eaf8,stroke:#2471A3,stroke-width:2px;
    classDef external fill:#f7dc6f,stroke:#B7950B,stroke-width:2px;

    %% Click Events for Audio Input
    click MI "https://github.com/rhasspy/wyoming-satellite/blob/master/installer/microphone.py"
    click M2 "https://github.com/rhasspy/wyoming-satellite/blob/master/examples/2mic_service.py"
    click M4 "https://github.com/rhasspy/wyoming-satellite/blob/master/examples/4mic_service.py"
    click MUSB "https://github.com/rhasspy/wyoming-satellite/blob/master/examples/usbmic_service.py"

    %% Click Events for Speaker Output
    click SI "https://github.com/rhasspy/wyoming-satellite/blob/master/installer/speakers.py"
    click AN "https://github.com/rhasspy/wyoming-satellite/blob/master/sounds/awake.wav"
    click DN "https://github.com/rhasspy/wyoming-satellite/blob/master/sounds/done.wav"
    click TN "https://github.com/rhasspy/wyoming-satellite/blob/master/sounds/timer_finished.wav"

    %% Click Events for Audio Processing
    click VAD "https://github.com/rhasspy/wyoming-satellite/blob/master/wyoming_satellite/vad.py"
    click WWD "https://github.com/rhasspy/wyoming-satellite/blob/master/installer/wake_word.py"
    click AE "https://github.com/rhasspy/wyoming-satellite/blob/master/wyoming_satellite/webrtc.py"

    %% Click Events for Core Satellite
    click CSE "https://github.com/rhasspy/wyoming-satellite/blob/master/wyoming_satellite/satellite.py"
    click ECH "https://github.com/rhasspy/wyoming-satellite/blob/master/wyoming_satellite/event_handler.py"
    click RCI "https://github.com/rhasspy/wyoming-satellite/blob/master/wyoming_satellite/example_event_client.py"

    %% Click Event for Utility Modules
    click UTL "https://github.com/rhasspy/wyoming-satellite/tree/master/wyoming_satellite/utils/"

    %% Click Events for Deployment
    click INS "https://github.com/rhasspy/wyoming-satellite/tree/master/installer/"
    click RD "https://github.com/rhasspy/wyoming-satellite/blob/master/etc/install-respeaker-drivers.sh"
    click DF "https://github.com/rhasspy/wyoming-satellite/tree/master/Dockerfile"
    click DC "https://github.com/rhasspy/wyoming-satellite/blob/master/docker-compose.yml"
    click RDS "https://github.com/rhasspy/wyoming-satellite/tree/master/script/run_docker"
    click BDS "https://github.com/rhasspy/wyoming-satellite/tree/master/script/build_docker"
    click SS "https://github.com/rhasspy/wyoming-satellite/tree/master/script/setup"
    click RS "https://github.com/rhasspy/wyoming-satellite/tree/master/script/run"
    click R2 "https://github.com/rhasspy/wyoming-satellite/tree/master/script/run_2mic"
    click R4 "https://github.com/rhasspy/wyoming-satellite/tree/master/script/run_4mic"
    click RUSB "https://github.com/rhasspy/wyoming-satellite/tree/master/script/run_usbmic"
```
