# absadiki/pywhispercpp architecture

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

- Interactive diagram: https://gitdiagram.com/absadiki/pywhispercpp
- Repository: https://github.com/absadiki/pywhispercpp

## Overview

##### Project type and purpose
- Project Type: A native-extension library (Python bindings) wrapping a C++ speech-to-text engine (whisper.cpp)
- Purpose: Expose whisper.cpp’s transcription functionality through a Pythonic API, package it as a pip installable wheel, and provide CLI/examples for easy consumption.

##### Top-level components
a. whisper.cpp Core (C++ inference engine)
b. pybind11 Binding Layer (C++ code under pybind11/ + src/main.cpp)
c. Python API Wrapper (pywhispercpp package: model.py, utils.py, constants.py)
d. CLI Entry Points (`pwcpp` and `pwcpp-assistant`) via scripts in setup.py
e. Examples & Tests (pywhispercpp/examples/, tests/)
f. Build & Packaging Pipeline (CMakeLists.txt, setup.py, pyproject.toml, GitHub Workflows)
g. External Dependencies
– Audio preprocessors: ffmpeg, webrtcvad (for assistant example)
– Backends: CUDA, CoreML, Vulkan, OpenBLAS, OpenVINO (optional flags)
– Model files: downloaded at runtime or provided locally

##### Architectural patterns
- Native-Extension Bridge: Python ←→ C++ via pybind11
- Separation of Concerns:
– Inference engine is pure C++ (platform-agnostic)
– Binding layer exposes only C-API surface
– Python wrapper adds user-friendly API, defaults, callbacks
- Plugin-style backends: compile-time flags pick CUDA/CoreML/Vulkan etc.

##### Essential elements checklist
- Component names (whisper.cpp, pybind11, pywhispercpp.model, CLI scripts, GitHub Actions)
- Build pipeline block with CMake & setup.py feeding into artifact outputs (wheels)
- External dependencies around the perimeter (ffmpeg, CUDA, etc.)

## Diagram (Mermaid)

```mermaid
graph TB
    %% User/Application Layer
    subgraph "User & Examples & Tests"
        direction TB
        User["User Script / CLI"]:::python
        subgraph "Examples" 
            direction TB
            Ex_dir["pywhispercpp/examples/"]:::python
            Ex1["assistant.py"]:::python
            Ex2["livestream.py"]:::python
            Ex3["main.py"]:::python
            Ex4["recording.py"]:::python
        end
        subgraph "Tests"
            direction TB
            Test_dir["tests/"]:::python
            T1["test_c_api.py"]:::python
            T2["test_model.py"]:::python
        end
    end

    %% Python API Wrapper
    subgraph "Python API Wrapper" 
        direction TB
        Model_py["model.py"]:::python
        Utils_py["utils.py"]:::python
        Const_py["constants.py"]:::python
        Init_py["__init__.py"]:::python
    end

    %% Binding Layer
    subgraph "pybind11 Binding Layer"
        direction TB
        Pybind11_sub["pybind11/"]:::binding
        Bind_entry["src/main.cpp"]:::binding
    end

    %% C++ Core
    subgraph "whisper.cpp Core"
        direction TB
        Core_src["src/main.cpp"]:::core
        Core_dir["whisper.cpp/"]:::core
        CMake["CMakeLists.txt"]:::core
        subgraph "Compile-time Backend Flags"
            direction TB
            CUDA["CUDA"]:::external
            CoreML["CoreML"]:::external
            Vulkan["Vulkan"]:::external
            BLAS["OpenBLAS"]:::external
            OVINO["OpenVINO"]:::external
        end
    end

    %% Model Store
    ModelStore["Model Store\n(cloud or local FS)"]:::external

    %% Build & Packaging Pipeline
    subgraph "Build & Packaging Pipeline"
        direction TB
        Setup["setup.py"]:::ci
        PyProj["pyproject.toml"]:::ci
        Manifest["MANIFEST.in"]:::ci
        CMakeBP["CMakeLists.txt"]:::ci
        subgraph "GitHub Workflows"
            direction TB
            DocsWF[".github/workflows/docs.yml"]:::ci
            PipWF[".github/workflows/pip.yml"]:::ci
            WheelsWF[".github/workflows/wheels.yml"]:::ci
        end
        Mkdocs["mkdocs.yml"]:::ci
        DocsIdx["docs/index.md"]:::ci
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        FFmpeg["ffmpeg"]:::external
        VAD["webrtcvad"]:::external
    end

    %% Call/Flow Arrows
    User -->|uses| Model_py
    Ex_dir -->|example scripts| Model_py
    T1 -->|tests| Bind_entry
    Model_py -->|calls| Bind_entry
    Utils_py -->|utils| Model_py
    Bind_entry -->|invokes| Core_src
    Core_src -->|returns transcription| Bind_entry
    Bind_entry -->|wraps result| Model_py
    ModelStore -->|download model| Model_py
    Setup -->|defines CLI| User
    PyProj -->|packaging| Setup
    CMakeBP -->|builds native ext| Bind_entry
    DocsWF -->|generates docs| Mkdocs
    PipWF -->|builds wheels| Setup
    WheelsWF -->|build wheels| Setup
    FFmpeg -->|used by| Ex1
    VAD -->|used by| Ex1

    %% Click Events
    click Core_dir "https://github.com/absadiki/pywhispercpp/tree/main/whisper.cpp/"
    click Core_src "https://github.com/absadiki/pywhispercpp/blob/main/whisper.cpp/src/main.cpp"
    click CMake "https://github.com/absadiki/pywhispercpp/blob/main/CMakeLists.txt"
    click Pybind11_sub "https://github.com/absadiki/pywhispercpp/tree/main/pybind11/"
    click Bind_entry "https://github.com/absadiki/pywhispercpp/blob/main/src/main.cpp"
    click Model_py "https://github.com/absadiki/pywhispercpp/blob/main/pywhispercpp/model.py"
    click Utils_py "https://github.com/absadiki/pywhispercpp/blob/main/pywhispercpp/utils.py"
    click Const_py "https://github.com/absadiki/pywhispercpp/blob/main/pywhispercpp/constants.py"
    click Init_py "https://github.com/absadiki/pywhispercpp/blob/main/pywhispercpp/__init__.py"
    click Ex_dir "https://github.com/absadiki/pywhispercpp/tree/main/pywhispercpp/examples/"
    click Test_dir "https://github.com/absadiki/pywhispercpp/tree/main/tests/"
    click Setup "https://github.com/absadiki/pywhispercpp/blob/main/setup.py"
    click PyProj "https://github.com/absadiki/pywhispercpp/blob/main/pyproject.toml"
    click CMakeBP "https://github.com/absadiki/pywhispercpp/blob/main/CMakeLists.txt"
    click DocsWF "https://github.com/absadiki/pywhispercpp/blob/main/.github/workflows/docs.yml"
    click PipWF "https://github.com/absadiki/pywhispercpp/blob/main/.github/workflows/pip.yml"
    click WheelsWF "https://github.com/absadiki/pywhispercpp/blob/main/.github/workflows/wheels.yml"
    click Mkdocs "https://github.com/absadiki/pywhispercpp/blob/main/mkdocs.yml"
    click DocsIdx "https://github.com/absadiki/pywhispercpp/blob/main/docs/index.md"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#000
    classDef binding fill:#FFA500,stroke:#000
    classDef core fill:#D3D3D3,stroke:#000
    classDef ci fill:#90EE90,stroke:#000
    classDef external fill:#FFFFE0,stroke:#000
```
