# jeffrey94/windows-whisper architecture

> Architecture diagram of the GitHub repository jeffrey94/windows-whisper, 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/jeffrey94/windows-whisper
- Repository: https://github.com/jeffrey94/windows-whisper

## Overview

##### Project Type and Purpose
- This is a Windows desktop application that provides a lightweight voice-to-text functionality using OpenAI’s Whisper API.
- It is triggered by a global hotkey (Ctrl + Space), captures audio from the microphone, displays a minimal overlay UI during recording, sends the audio to the Whisper API for transcription, and then automatically copies the resulting text to the clipboard.
- Key functionalities include global shortcut triggering, audio recording, transcription via an external API, a modern overlay UI (likely built with a framework like PyQt5), and clipboard integration.

##### Key Components
a. Entry Point:
- main.py: This is the starting point of the application that initializes and coordinates the overall workflow.
b. Configuration:
- config.py and .env file: Used for setting environment parameters like OPENAI_API_KEY, hotkey definitions, recording duration, etc.
c. Global Hotkey Module:
- src/hotkey.py: Listens for the Ctrl + Space shortcut and triggers the recording process.
d. Audio Recording Module:
- src/audio.py: Captures audio input when the hotkey event is triggered.
e. Transcription Module:
- src/whisper_api.py: Interfaces with OpenAI’s Whisper API, sending recorded audio and receiving the transcription.
f. Clipboard Handling Module:
- src/clipboard.py: Automatically copies the transcription to the system clipboard.
g. UI/Overlay Module:
- src/ui/overlay.py: Provides the floating overlay UI that shows the recording status and update indicators.
h. Utility Functions:
- src/utils.py: Contains helper methods that may be used across multiple modules.
i. External Dependencies:
- OpenAI’s Whisper API: An external, cloud-based transcription service.
- PyQt5 (or similar, as inferred from the README and the "Modern UI" reference): For building the overlay interface.
- Windows specific APIs for global hotkey detection and clipboard interaction.

##### Relationships and Interactions
- The main entry point (main.py) interacts with config.py to load environment variables and determine runtime settings.
- On detecting a global hotkey event via src/hotkey.py, the application instructs src/audio.py to begin recording.
- Once the audio is captured, src/whisper_api.py is called to perform transcription by communicating with the external Whisper API.
- After transcription, src/clipboard.py ensures the text is copied to the clipboard automatically.
- Throughout the process, src/ui/overlay.py manages the display of a minimal and informative overlay that reflects recording status, progress, and transient notifications.
- All modules may leverage utility functions from src/utils.py.

##### Architectural Patterns and Design Principles
- Modular design: Each functionality is encapsulated in dedicated modules which simplifies maintenance and testing.
- Separation of concerns: There is a clean differentiation between core business logic (audio processing, transcription, clipboard handling) and UI/OS interactions.
- Event-driven architecture: Hotkey detection serves as the event that triggers the audio recording and subsequent actions.
- External service integration: The transcription functionality is offloaded to OpenAI’s Whisper API.

##### Overall Detailing
- Data flows (audio data, transcribed text) and configuration-driven decision points.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Initialization"
        MAIN["Main Program (main.py)"]:::core
        CONFIG["Configuration (config.py & .env)"]:::core
        UTILS["Utility Functions (src/utils.py)"]:::core
    end

    subgraph "User Interaction"
        HOTKEY["Global Hotkey Module (src/hotkey.py)"]:::user
        UI["Overlay UI (src/ui/overlay.py)"]:::user
    end

    subgraph "Backend Processing"
        AUDIO["Audio Recorder (src/audio.py)"]:::backend
        TRANSCRIPTION["Transcription Module (src/whisper_api.py)"]:::backend
        CLIPBOARD["Clipboard Manager (src/clipboard.py)"]:::backend
    end

    subgraph "External Services"
        WHISPER["OpenAI Whisper API"]:::external
    end

    %% Connections
    MAIN -->|"loads"| CONFIG
    MAIN -->|"initiates"| UTILS
    MAIN -->|"activates"| HOTKEY
    MAIN -->|"displays"| UI

    HOTKEY -->|"triggers"| AUDIO

    AUDIO -->|"sends-audio"| TRANSCRIPTION

    TRANSCRIPTION -->|"calls"| WHISPER
    TRANSCRIPTION -->|"delivers-text"| CLIPBOARD

    UI -->|"updates-status"| MAIN

    %% Click Events
    click MAIN "https://github.com/jeffrey94/windows-whisper/blob/master/main.py"
    click CONFIG "https://github.com/jeffrey94/windows-whisper/blob/master/config.py"
    click UTILS "https://github.com/jeffrey94/windows-whisper/blob/master/src/utils.py"
    click HOTKEY "https://github.com/jeffrey94/windows-whisper/blob/master/src/hotkey.py"
    click AUDIO "https://github.com/jeffrey94/windows-whisper/blob/master/src/audio.py"
    click TRANSCRIPTION "https://github.com/jeffrey94/windows-whisper/blob/master/src/whisper_api.py"
    click CLIPBOARD "https://github.com/jeffrey94/windows-whisper/blob/master/src/clipboard.py"
    click UI "https://github.com/jeffrey94/windows-whisper/blob/master/src/ui/overlay.py"

    %% Styles
    classDef core fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef user fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef backend fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef external fill:#d6eaf8,stroke:#2980b9,stroke-width:2px;
```
