# vaibhavs10/insanely-fast-whisper architecture

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

- Interactive diagram: https://gitdiagram.com/vaibhavs10/insanely-fast-whisper
- Repository: https://github.com/vaibhavs10/insanely-fast-whisper

## Overview

##### Project Type and Purpose
- This is a CLI tool for high-speed audio transcription powered by OpenAI’s Whisper models.
- It is designed for on-device transcription with optimisations for NVIDIA GPUs and macOS (MPS).
- The README also shows benchmark results and example usages, indicating that performance and efficient resource utilization are key.

##### File Structure to Determine Components
- Top-Level Files & Directories:
- Files like README.md, LICENSE, and .gitignore are standard project files.
- The presence of multiple notebooks (in the “notebooks” directory) suggests that there are demo/test cases or experiments to showcase performance and usage.
- “convert_output.py” may be a helper script to process or convert transcription results.
- “tests” directory denotes automated tests for the project.
- Source Code Organization:
- The “src/insanely_fast_whisper” directory is the heart of the project.
- The “cli.py” file contains the implementation of the CLI – the primary entry point.
- The “utils” subdirectory holds supporting modules (like diarization_pipeline.py, diarize.py, and result.py) that encapsulate core functionalities such as speaker diarization and result handling.
- Configuration & Build Files:
- “pdm.lock” and “pyproject.toml” indicate that the project uses PDM for dependency management and packaging.

##### Extract Key Architectural Elements from the README
- The README highlights that the tool supports multiple models and optimisations.
- It mentions integration with external libraries (Transformers, Optimum, flash-attn) and hardware accelerators (CUDA and MPS).

a. Main Components to Include:
- CLI Interface:
- Represented by the “cli.py” module which parses user input and triggers the workflow.
- Core Processing Module/Library:
- Located in “src/insanely_fast_whisper” (with its utility modules) where the transcription logic is implemented.
- Utility Components:
- “utils/diarization_pipeline.py”, “utils/diarize.py”, and “utils/result.py” modules, which handle specific tasks such as audio diarization and formatting of results.
- External Dependencies & Frameworks:
- Transformers and Optimum libraries, along with Flash Attention 2, which are leveraged by the core modules.
- Execution Environment:
- Hardware components (i.e., NVIDIA GPUs and macOS MPS devices) that are integral to performance optimisations.
- Optional Notebooks & Benchmarking:
- The “notebooks” directory, which can be shown as experimental/demo interfaces linking to the core system.

b. Relationships and Interactions:
- The CLI layer acts as the interface that receives user commands and passes parameters to the core processing module.
- The core processing module coordinates with utility functions (diarization, result aggregation) and then calls external libraries for model inference.
- External libraries are responsible for handling the heavy-lifting of audio transcription.

c. Architectural Patterns & Design Principles:
- The project follows a modular structure, separating the CLI, core logic, and auxiliary utilities. This separation of concerns simplifies both development and testing.
- It is an opinionated design that focuses on performance optimization under specific hardware constraints.

d. Relevant Technologies:
- Python, OpenAI's Whisper and distil-Whisper models, Flash Attention 2, PyTorch (for CUDA and MPS support), Transformers, and Optimum.

## Diagram (Mermaid)

```mermaid
graph TD
    ui["User Input: Audio File & CLI args"]:::input
    cli["CLI Interface (cli.py)"]:::cli
    core["Core Processing Module (Insanely Fast Whisper)"]:::core
    util_dp["Diarization Pipeline Utility"]:::utility
    util_d["Diarize Utility"]:::utility
    util_r["Result Handling Utility"]:::utility
    conv["Helper Script for Output Processing"]:::utility
    extlib["External Model Inference (Transformers,Optimum,flash-attn)"]:::external
    hw["Hardware Accelerator (NVIDIA GPU,macOS MPS)"]:::hardware
    note["Optional Notebooks/Demo & Benchmarking"]:::demo

    ui -->|"provides_input"| cli
    cli -->|"triggers_transcription"| core
    core -->|"calls"| util_dp
    core -->|"calls"| util_d
    core -->|"calls"| util_r
    core -->|"calls"| extlib
    extlib -->|"utilizes"| hw
    util_r -->|"formats_results"| conv
    util_r -->|"returns_results"| cli
    note -->|"demonstrates"| core

    classDef cli fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef utility fill:#afa,stroke:#333,stroke-width:2px;
    classDef external fill:#fea,stroke:#333,stroke-width:2px;
    classDef hardware fill:#8af,stroke:#333,stroke-width:2px;
    classDef demo fill:#ffa,stroke:#333,stroke-width:2px;
    classDef input fill:#d3f,stroke:#333,stroke-width:2px;

    click cli "https://github.com/vaibhavs10/insanely-fast-whisper/blob/main/src/insanely_fast_whisper/cli.py"
    click core "https://github.com/vaibhavs10/insanely-fast-whisper/blob/main/src/insanely_fast_whisper/__init__.py"
    click util_dp "https://github.com/vaibhavs10/insanely-fast-whisper/blob/main/src/insanely_fast_whisper/utils/diarization_pipeline.py"
    click util_d "https://github.com/vaibhavs10/insanely-fast-whisper/blob/main/src/insanely_fast_whisper/utils/diarize.py"
    click util_r "https://github.com/vaibhavs10/insanely-fast-whisper/blob/main/src/insanely_fast_whisper/utils/result.py"
    click conv "https://github.com/vaibhavs10/insanely-fast-whisper/blob/main/convert_output.py"
    click note "https://github.com/vaibhavs10/insanely-fast-whisper/tree/main/notebooks/"
```
