# coderconnoisseur/echoline architecture

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

- Interactive diagram: https://gitdiagram.com/coderconnoisseur/echoline
- Repository: https://github.com/coderconnoisseur/echoline

## Overview

##### Project Type and Purpose
- EchoLine is a single-process desktop application (Python) providing real-time speech-to-text captions as an always-on-top overlay.
- Key goals: capture system audio, transcribe it via Vosk, render captions in a movable, transparent UI.

##### File Structure
- Top-level scripts:
- Syscapture.py  → Handles audio capture from Windows Stereo Mix
- Transcription.py → Wraps Vosk model inference
- overlay.py     → Builds and manages the overlay window (probably using Tkinter or PyQt)
- main.py        → Orchestrates capture → transcription → UI
- requirements.txt → Lists external Python libraries (e.g., vosk, PyAudio, GUI toolkit)
- venv/           → Isolated Python environment (dependency context)

##### Extract Insights from README
- External dependencies: Windows Stereo Mix, Vosk speech model in user’s cache directory, Python ≥3.7.
- Runtime characteristics: continuous streaming pipeline, no persistent database.
- User interactions: drag-and-drop overlay, adjustable transparency, auto-scroll.

##### Main Components
a. Operating System Layer
- Windows Audio Subsystem (Stereo Mix driver)
b. Python Runtime
- Virtual Environment (venv)
c. Application Modules
1. Audio Capture Module (Syscapture.py)
2. Speech-to-Text Module (Transcription.py + Vosk Engine)
3. Overlay UI Module (overlay.py)
4. Orchestrator (main.py)
d. External Resources
- Vosk Model Files on disk (C:\Users\<User>\.cache\vosk\vosk-model-small-en-us-0.15)
- Python Libraries (PyAudio, vosk, GUI toolkit)
e. User Interface
- Always-on-top transparent window
- Drag & drop handlers, scrollable text area

##### Relationships and Interactions
- Windows Audio Subsystem → Audio Capture Module: streams PCM data
- Audio Capture Module → Speech-to-Text Module: pushes audio frames/buffers
- Speech-to-Text Module → Overlay UI Module: emits text events
- Overlay UI Module ←→ Orchestrator: receives events, updates display, handles user input (move/resize)
- Orchestrator coordinates lifecycle (start/stop capture, load model, spawn threads)

##### Architectural Patterns & Design Principles
- Pipeline pattern: audio → transcription → display
- Modular separation: capture, processing, UI in distinct scripts
- Single-threaded or multi-threaded design (likely threads or async loops)
- Dependency injection: Vosk model path configurable via environment or CLI

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Windows OS"
        AudioSub["Windows Audio Subsystem"]:::external
    end

    subgraph "Python Runtime"
        venv["venv/"]:::fs
    end

    subgraph "Application Modules"
        main["main.py (Orchestrator)"]:::core
        syscap["Syscapture.py\n(Audio Capture)\nAlways-on-top, transparent"]:::core
        trans["Transcription.py + Vosk\n(Speech Recognition)"]:::core
        ui["overlay.py (Overlay UI)\nDrag/Resize Handlers"]:::core
    end

    subgraph "External Resources"
        libs("(PyAudio, vosk, GUI Toolkit)"):::external
        model["[(vosk-model-small-en-us-0.15)]"]:::fs
        req["requirements.txt"]:::fs
    end

    AudioSub -->|"Stereo Mix enabled"| syscap
    syscap -->|"PCM frames"| trans
    trans -->|"text events"| ui

    main -->|"initialization/control"| syscap
    main -->|"initialization/control"| trans
    main -->|"initialization/control"| ui
    main -->|"load dependencies"| libs
    main -->|"load model"| model
    main -->|"reads"| req
    main -->|"runs in"| venv

    click syscap "https://github.com/coderconnoisseur/echoline/blob/main/Syscapture.py"
    click trans "https://github.com/coderconnoisseur/echoline/blob/main/Transcription.py"
    click ui "https://github.com/coderconnoisseur/echoline/blob/main/overlay.py"
    click main "https://github.com/coderconnoisseur/echoline/blob/main/main.py"
    click req "https://github.com/coderconnoisseur/echoline/blob/main/requirements.txt"
    click venv "https://github.com/coderconnoisseur/echoline/tree/main/venv/"

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef fs fill:#D3D3D3,stroke:#000,stroke-width:1px
```
