# mpaepper/vibevoice architecture

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

- Interactive diagram: https://gitdiagram.com/mpaepper/vibevoice
- Repository: https://github.com/mpaepper/vibevoice

## Overview

##### Main Components
- CLI Interface Module – Represented by src/vibevoice/cli.py. This is the entry point that captures user input (the activation key press and release events) and triggers subsequent actions.
- Audio Processing & Transcription Service – Likely implemented in src/vibevoice/server.py and associated modules. This component handles:
- Capturing spoken audio
- Processing it utilizing the local Whisper model (with support for CUDA/CPU modes)
- Loading Indicator – Indicated by the module src/vibevoice/loading_indicator.py; this visual indicator provides feedback to the user during processing.
- AI Command Mode Engine – An extension to the core transcription function. When activated (using a different key, e.g., scroll_lock), it passes the transcribed text (and optionally a screenshot) to an external LLM:
- Integration with Ollama (an external service) is required to retrieve responses based on the current screen context.
- External Dependencies & Infrastructure – Note dependencies like CUDA, PortAudio, and external utilities (e.g., gnome-screenshot) as part of your platform’s environment. Also include the role of the CuDNN and cuBLAS libraries.
- Configuration & Environment – Highlight configuration through environment variables (e.g., VOICEKEY, VOICEKEY_CMD, OLLAMA_MODEL, etc.) that allow the application to be tuned at runtime.

##### Relationships and Data Flows
- While processing is underway, the Loading Indicator provides real-time feedback. This should be visually connected to the Audio Processing module.

##### Architectural Patterns & Design Principles
- Modularity: Clearly separate the concerns into distinct modules (CLI, Audio Processing, AI Command Mode, UI/Feedback).
- Configuration Driven: Highlight that many behaviors (especially keyboard controls and AI model selection) are configurable using environment variables.
- System Integration: Note the dependencies on GPU/CPU libraries (CUDA, cuDNN) and integration with external command-line utilities (such as gnome-screenshot for screen capture).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Nodes
    user["User Key Input"]:::core
    config["Configuration & Environment (VOICEKEY, VOICEKEY_CMD, OLLAMA_MODEL, etc.)"]:::config
    CLI["CLI Interface Module"]:::core
    Audio["Audio Processing & Transcription Service (Whisper Model)"]:::core
    Loading["Loading Indicator"]:::core
    AI["AI Command Mode Engine (via Ollama)"]:::core
    Output["Output/Typing"]:::core
    Ollama["Ollama LLM Service"]:::external

    %% External Dependencies Subgraph
    subgraph "External Dependencies & Infrastructure"
        CUDA["CUDA"]:::external
        cuDNN["cuDNN"]:::external
        cuBLAS["cuBLAS"]:::external
        PortAudio["PortAudio"]:::external
        Gnome["gnome-screenshot"]:::external
    end

    %% Relationships and Data Flows
    config -.-> CLI
    config -.-> AI
    user --> CLI
    CLI --> Audio
    Audio --> Loading
    Audio -->|"transcription(dictation)"| Output
    Audio -->|"transcription(AI_mode)"| AI
    AI -->|"sends_text+screenshot"| Ollama
    Ollama -->|"LLM_response"| Output

    %% External Dependencies used by Core Components
    Audio ---|"uses"| PortAudio
    Audio ---|"accelerated_by"| CUDA
    CUDA ---|"paired_with"| cuDNN
    CUDA ---|"paired_with"| cuBLAS
    AI ---|"captures_screen_via"| Gnome

    %% Click Events
    click CLI "https://github.com/mpaepper/vibevoice/blob/main/src/vibevoice/cli.py"
    click Audio "https://github.com/mpaepper/vibevoice/blob/main/src/vibevoice/server.py"
    click Loading "https://github.com/mpaepper/vibevoice/blob/main/src/vibevoice/loading_indicator.py"

    %% Styles
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#d33,stroke-width:2px;
    classDef config fill:#dfd,stroke:#363,stroke-width:2px;
```
