# xenova/whisper-web architecture

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

- Interactive diagram: https://gitdiagram.com/xenova/whisper-web
- Repository: https://github.com/xenova/whisper-web

## Overview

##### Project type and purpose
- This is a client-side, full-frontend web application (“Whisper Web”) for running Whisper ML speech-to-text entirely in the browser. It uses React (TSX), Vite, Tailwind CSS, and Hugging Face’s Transformers.js, with an optional experimental WebGPU branch.

##### File structure
- Top-level:
- index.html – root HTML file
- package.json & package-lock.json – dependencies & scripts
- Vite/tailwind/postCSS/ESLint/TS config files – build and lint configuration
- Public folder: static assets
- src folder:
- App.tsx + index.tsx – React app entry point
- components/ – UI components (AudioRecorder, AudioPlayer, TranscribeButton, Progress, Transcript, Modal, etc.)
- hooks/ – custom React hooks (useTranscriber for orchestration, useWorker for managing Web Worker)
- utils/ – helper functions for audio handling, constants, blob fixes
- worker.js – Web Worker script that loads the Whisper model via Transformers.js, runs inference
- No backend folders: inference happens entirely client-side.

##### Extract architectural insights from the README
- Core functionality: record or load audio, then transcribe via Whisper model in-browser.
- Uses Transformers.js for model loading/inference.
- Optional WebGPU acceleration path.
- Web Worker required to avoid blocking UI during heavy ML computation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "Browser Host / UI Thread"
        direction TB
        IDX["index.tsx"]:::ui
        APP["App.tsx"]:::ui
        AM["AudioManager"]:::ui
        AR["AudioRecorder"]:::ui
        AP["AudioPlayer"]:::ui
        TBUT["TranscribeButton"]:::ui
        PROG["Progress"]:::ui
        TRANS["Transcript"]:::ui
        MOD["Modal"]:::ui
        URLI["UrlInput"]:::ui
    end

    %% Hooks Layer
    subgraph "State Management (React Hooks)"
        direction TB
        UT["useTranscriber"]:::hooks
        UW["useWorker"]:::hooks
    end

    %% Media & Utils
    subgraph "Media Layer & Utilities"
        direction TB
        AU["AudioUtils"]:::utils
        BF["BlobFix"]:::utils
        CT["Constants"]:::utils
    end

    %% Worker Layer
    subgraph "Web Worker (ML Inference)"
        direction TB
        WK["worker.js"]:::worker
    end

    %% External / Network
    subgraph "External / Network"
        direction TB
        CDN["Model Weights CDN"]:::external
        PUB["public/"]:::external
        ASSET["src/assets/"]:::external
    end

    %% Optional WebGPU
    WEBGPU["WebGPU Path (optional)"]:::optional

    %% Data Flow
    AR -->|"captures audio blob"| AU
    AU -->|"provides PCM blob"| UT
    TBUT -->|"triggers transcription"| UT
    UT -->|"posts audio to worker"| UW
    UW -->|"postMessage audio"| WK
    WK -->|"loads model from CDN"| CDN
    WK -->|"optional WebGPU init"| WEBGPU
    WK -->|"runs inference"| WK
    WK -->|"postMessage transcript"| UW
    UW -->|"callback with transcript"| UT
    UT -->|"updates state"| TRANS
    UT -->|"updates state"| PROG
    UT -->|"provides audio for playback"| AP

    %% Click events
    click IDX "https://github.com/xenova/whisper-web/blob/main/src/index.tsx"
    click APP "https://github.com/xenova/whisper-web/blob/main/src/App.tsx"
    click AM "https://github.com/xenova/whisper-web/blob/main/src/components/AudioManager.tsx"
    click AR "https://github.com/xenova/whisper-web/blob/main/src/components/AudioRecorder.tsx"
    click AP "https://github.com/xenova/whisper-web/blob/main/src/components/AudioPlayer.tsx"
    click TBUT "https://github.com/xenova/whisper-web/blob/main/src/components/TranscribeButton.tsx"
    click PROG "https://github.com/xenova/whisper-web/blob/main/src/components/Progress.tsx"
    click TRANS "https://github.com/xenova/whisper-web/blob/main/src/components/Transcript.tsx"
    click MOD "https://github.com/xenova/whisper-web/blob/main/src/components/modal/Modal.tsx"
    click URLI "https://github.com/xenova/whisper-web/blob/main/src/components/modal/UrlInput.tsx"
    click UT "https://github.com/xenova/whisper-web/blob/main/src/hooks/useTranscriber.ts"
    click UW "https://github.com/xenova/whisper-web/blob/main/src/hooks/useWorker.ts"
    click AU "https://github.com/xenova/whisper-web/blob/main/src/utils/AudioUtils.ts"
    click BF "https://github.com/xenova/whisper-web/blob/main/src/utils/BlobFix.ts"
    click CT "https://github.com/xenova/whisper-web/blob/main/src/utils/Constants.ts"
    click WK "https://github.com/xenova/whisper-web/blob/main/src/worker.js"
    click PUB "https://github.com/xenova/whisper-web/tree/main/public/"
    click ASSET "https://github.com/xenova/whisper-web/tree/main/src/assets/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef hooks fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef utils fill:#fdfdfe,stroke:#d6d8db,color:#6c757d
    classDef worker fill:#ffe5b4,stroke:#ff8c00,color:#8b4513
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef optional fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-dasharray: 5 5
```
