# nalbion/whisper-server architecture

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

- Interactive diagram: https://gitdiagram.com/nalbion/whisper-server
- Repository: https://github.com/nalbion/whisper-server

## Overview

##### Main Components
- Audio Input Service:
- Module responsible for audio capture (found under whisper_server/services/audio, e.g., microphone.py, start_audio.py).
- Whisper Processing Service:
- Server Layer:
- HTTP server implementation that uses Server Sent Events (in whisper_server/services/server/http_server.py).
- GRPC server implementation (in whisper_server/services/server/grpc_server.py) that serves transcriptions as remote procedure calls, including generation and usage of protocol buffers defined in whisper_server/proto.
- Service Orchestration:
- Starter modules (like whisper_server/__main__.py and whisper_server/app.py) that orchestrate the overall flow.
- Auxiliary Components:
- Components for dependency or configuration management (e.g., requirements.txt, Dockerfile, build scripts) that play a role in both development and deployment.

##### Relationships and Interactions
- Audio Input Service feeds raw microphone input into the Whisper Processing Service.
- The processed transcription data flows from Whisper Processing to the Server Layer.
- The HTTP (SSE) and gRPC services then expose data to external clients.
- Data Flow & Dependencies:
- That the abstract whisper service can dynamically switch between different implementations (OpenAI vs. Faster Whisper) based on command-line options.
- That the protocol buffers in the “proto” folder serve as the contract/interface between the whisper processing output and the gRPC server.
- That the system is designed to operate locally, but with configurable options (e.g., SSDP discoverability, device selection) that affect deployment.

##### Architectural Patterns and Design Principles
- Modularity:
- The clear separation among audio capture, processing, and server components encourages modularity.
- Extensibility:
- Support for multiple transcription backends is achieved via an abstract interface.
- Containerization:
- There is a Dockerfile (and even a specialized Dockerfile.cpp hinting at cross-platform considerations) indicating containerized deployment is supported.
- Dual-Communication Interfaces:
- The design clearly separates RESTful (SSE) and RPC (gRPC) communication paths.

##### Technology, Frameworks, and Libraries
- Python 3.10+ is used as the core language.
- gRPC (with generated protobuf files) and HTTP Server (SSE) are key network components.
- Integration with OpenAI Whisper and faster-whisper provides the underlying transcription capabilities.
- Docker is used for containerized deployment and possibly Bazel (BUILD.bazel) for advanced build management.

##### Overall Approach
- That dependencies (such as between the protocol buffers and the gRPC server) and configuration hooks are clearly marked.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Service Orchestration
    subgraph "Service Orchestration"
        SO1["Main Entrypoint"]:::orchestration
        SO2["App Orchestrator"]:::orchestration
    end

    %% Audio Input Service
    subgraph "Audio Input Service"
        AI1["Microphone Service"]:::audio
        AI2["Audio Start Service"]:::audio
    end

    %% Whisper Processing Service
    subgraph "Whisper Processing Service"
        WP5["Whisper Starter"]:::processing
        WP1["Abstract Whisper Service"]:::processing
        WP2["Faster Whisper Service"]:::processing
        WP3["OpenAI Whisper Service"]:::processing
        WP4["Whisper X Service"]:::processing
    end

    %% Server Layer
    subgraph "Server Layer"
        SL1["HTTP Server (SSE)"]:::server
        SL2["gRPC Server"]:::server
        SL3["Protocol Buffers"]:::server
    end

    %% Auxiliary & Deployment
    subgraph "Auxiliary & Deployment"
        AD1["Dependencies (requirements.txt)"]:::auxiliary
        AD2["Dockerfile"]:::auxiliary
        AD3["Dockerfile.cpp"]:::auxiliary
        AD4["Build (BUILD.bazel)"]:::auxiliary
    end

    %% Connections - Orchestration triggers audio services
    SO1 -->|"start_audio"| AI1
    SO1 -->|"init_audio"| AI2

    %% Audio Input feeds into Whisper Processing
    AI1 -->|"raw_audio"| WP5
    AI2 -->|"trigger_capture"| WP5

    %% Whisper Starter invokes the abstract whisper service
    WP5 -->|"invoke_transcription"| WP1

    %% Abstract whisper dynamically selects an implementation
    WP1 -- "selects" --> WP2
    WP1 -- "selects" --> WP3
    WP1 -- "selects" --> WP4

    %% Processed transcription flows to Server Layer
    WP5 -->|"send_transcription"| SL1
    WP5 -->|"send_transcription"| SL2

    %% gRPC Server utilizes Protocol Buffers
    SL2 -->|"uses"| SL3

    %% Orchestration loads auxiliary configurations
    SO2 -->|"load_config"| AD1

    %% Class styles
    classDef orchestration fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef audio fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef processing fill:#abebc6,stroke:#27ae60,stroke-width:2px;
    classDef server fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef auxiliary fill:#d7bde2,stroke:#884ea0,stroke-width:2px;

    %% Click Events
    click SO1 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/__main__.py"
    click SO2 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/app.py"
    click AI1 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/audio/microphone.py"
    click AI2 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/audio/start_audio.py"
    click WP1 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/whisper/abstract_whisper_service.py"
    click WP2 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/whisper/faster_whisper_service.py"
    click WP3 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/whisper/openai_whisper_service.py"
    click WP4 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/whisper/whisper_x_service.py"
    click WP5 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/whisper/start_whisper.py"
    click SL1 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/server/http_server.py"
    click SL2 "https://github.com/nalbion/whisper-server/blob/master/whisper_server/services/server/grpc_server.py"
    click SL3 "https://github.com/nalbion/whisper-server/tree/master/whisper_server/proto"
    click AD1 "https://github.com/nalbion/whisper-server/blob/master/requirements.txt"
    click AD2 "https://github.com/nalbion/whisper-server/tree/master/Dockerfile"
    click AD3 "https://github.com/nalbion/whisper-server/blob/master/Dockerfile.cpp"
    click AD4 "https://github.com/nalbion/whisper-server/blob/master/BUILD.bazel"
```
