# rajipilipia/ecoute architecture

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

- Interactive diagram: https://gitdiagram.com/rajipilipia/ecoute
- Repository: https://github.com/rajipilipia/ecoute

## Overview

##### Main Components
- Audio Input/Output Handling – Here you have separate modules for recording audio (AudioRecorder.py) and transcribing it (AudioTranscriber.py). This component is responsible for capturing live audio streams.
- Speech Recognition Engine – The custom_speech_recognition package plays a key role. Its submodules (e.g., audio.py, exceptions.py) as well as the recognizers folder (containing, for example, whisper.py) indicate distinct implementations for transcription.
- Model Management – TranscriberModels.py and the tiny.en.pt file indicate that different transcription models (local “tiny” model or external Whisper API) can be selected.
- External Dependencies – Integration with FFmpeg for audio processing and the optional connection to the OpenAI Whisper API (enabled via the --api flag) should be highlighted.
- Configuration & Environment – Files like requirements.txt and keys.py (created by the user) manage dependencies and runtime configurations (e.g., API keys).

##### Relationships and Data Flow
- From main.py, the program calls upon the Audio Input handler to record both microphone and speaker audio.
- The captured audio is passed to the transcription engine, which has two different processing paths:
- Local Processing using the provided “tiny” Whisper model (tiny.en.pt), for low resource consumption.
- API Processing via the OpenAI Whisper API (triggered by the --api flag) for faster, more accurate, and multi-language support.
- The custom_speech_recognition package serves as a middleware layer that standardizes how audio is processed and how recognizers (including the custom whisper recognizer) are called.
- Error handling is provided by defined exceptions within the package.
- Finally, the transcription text gets output (presumably into the UI textbox as described in the README) where users can view real-time transcriptions.

##### Architectural Patterns & Design Principles
- Modularity: Separation of concerns is clear – recording, transcription, model selection, and error management are decoupled into different modules.
- Adapter/Strategy Pattern: The usage of different transcription backends (local ASR model vs. the Whisper API) suggests an adaptable design where switching or upgrading models does not affect other parts of the system.
- Extensibility: The custom_speech_recognition package is structured to allow future additions (e.g., more recognizers or multi-language capabilities).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    MAIN["main.py"]:::internal

    %% Audio Modules Subgraph
    subgraph "Audio Modules"
        AR["Audio Recorder (AudioRecorder.py)"]:::internal
        AT["Audio Transcriber (AudioTranscriber.py)"]:::internal
    end

    %% Speech Recognition Engine Subgraph
    subgraph "Speech Recognition Engine"
        CSA["Core Package: custom_speech_recognition"]:::core
        CA["Audio Processing (audio.py)"]:::core
        CE["Error Handling (exceptions.py)"]:::core
        CR["Recognizer: Whisper (recognizers/whisper.py)"]:::core
        CP["Fallback Data (pocketsphinx-data)"]:::core
    end

    %% Model Management Subgraph
    subgraph "Model Management"
        TM["Transcriber Models (TranscriberModels.py)"]:::model
        LOCAL["Local Model File (tiny.en.pt)"]:::model
    end

    %% External Dependencies and Integrations
    EXAPI["External OpenAI Whisper API"]:::external
    FF["FFmpeg Utility"]:::external

    %% Configuration & Dependencies
    CON["Configuration: requirements.txt"]:::config

    %% Transcript Output (Real-time UI)
    TOUT["Transcript Output (UI)"]:::internal

    %% Data Flow
    MAIN -->|"initialize"| AR
    MAIN -->|"initialize"| AT
    AR -->|"captured audio"| AT
    AT -->|"process audio"| CSA

    %% Internal Flow within Speech Recognition Engine
    CSA --> CA
    CSA --> CR
    CSA --> CE
    CSA --> CP

    %% Transcription Processing Paths
    AT -->|"local_processing"| TM
    TM -->|"model_usage"| LOCAL
    AT -->|"api_processing|--api"| EXAPI

    %% External Dependency Usage
    AT -->|"audio_conversion"| FF
    MAIN -->|"load_config"| CON

    %% Final Output
    AT -->|"transcription_output"| TOUT

    %% Click Events
    click MAIN "https://github.com/rajipilipia/ecoute/blob/main/main.py"
    click AR "https://github.com/rajipilipia/ecoute/blob/main/AudioRecorder.py"
    click AT "https://github.com/rajipilipia/ecoute/blob/main/AudioTranscriber.py"
    click CSA "https://github.com/rajipilipia/ecoute/tree/main/custom_speech_recognition/"
    click CA "https://github.com/rajipilipia/ecoute/blob/main/custom_speech_recognition/audio.py"
    click CE "https://github.com/rajipilipia/ecoute/blob/main/custom_speech_recognition/exceptions.py"
    click CR "https://github.com/rajipilipia/ecoute/blob/main/custom_speech_recognition/recognizers/whisper.py"
    click CP "https://github.com/rajipilipia/ecoute/tree/main/custom_speech_recognition/pocketsphinx-data/"
    click TM "https://github.com/rajipilipia/ecoute/blob/main/TranscriberModels.py"
    click LOCAL "https://github.com/rajipilipia/ecoute/blob/main/tiny.en.pt"
    click CON "https://github.com/rajipilipia/ecoute/blob/main/requirements.txt"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#239B56,stroke-width:2px;
    classDef model fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef config fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
