# abdeladim-s/subsai architecture

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

- Interactive diagram: https://gitdiagram.com/abdeladim-s/subsai
- Repository: https://github.com/abdeladim-s/subsai

## Overview

##### Project type and purpose
- This is an open-source Python tool and library (“Subs AI”) for generating, translating, and synchronizing subtitles from audio/video.
- It offers three interaction surfaces: a CLI (`subsai`), a local Web-UI (`subsai-webui`), and a Python API (`SubsAI` class).

##### File structure
- Top-level directories/files:
- `src/subsai/` – the core Python package
- `assets/` – sample media and demo assets
- `examples/` – Jupyter notebooks showing usage
- `docs/` + `mkdocs.yml` – static documentation
- `tests/` – unit tests
- Docker files (`Dockerfile`, `docker-compose.yml`, `.github/workflows`) for CI/Deployment
- Within `src/subsai/`:
- `cli.py` – entrypoint for the command-line interface
- `webui.py` – launches the local Web-UI (likely Streamlit or similar)
- `main.py` – core orchestration logic
- `configs.py` – JSON/config parsing utilities
- `models/` – an abstract model interface and multiple implementations (Whisper variants, faster-whisper, whisper.cpp, whisperX, stable-ts, Hugging Face, OpenAI API)
- `utils.py` – common helpers (e.g., format conversion via pysubs2, VAD)

##### README for additional insights
- Confirms supported model backends, subtitle formats, translation via `dl-translate`, auto-sync via `ffsubsync`, merges via `ffmpeg`.
- Shows Docker usage, dependency on `ffmpeg`, optional GPU support.
- Describes three usage modes: Web-UI, CLI, Python API.

##### Main components and their interactions
a. User interfaces (UI layer)
- CLI (`subsai` console command)
- Web-UI (`subsai-webui` command serving a webpage locally)
- Python API (`SubsAI` class)
b. Core orchestration
- `main.py` – initializes configuration, selects model, processes media pipeline
c. Model abstraction layer
- `abstract_model.py` defines the common interface (load, transcribe)
- Concrete implementations in `models/` folder call out to Whisper, Faster-Whisper, Whisper.cpp, WhisperX, Stable-TS, Hugging Face, OpenAI API
d. Pre/Post-processing utilities
- VAD slicing (optional)
- Subtitle formatting and file I/O (via `pysubs2`)
- Translation (calls `dl-translate`)
- Auto-sync (calls `ffsubsync`)
- Merging subtitles back into video (`ffmpeg`)
e. External services & dependencies
- `ffmpeg` (media I/O)
- PyTorch or CTranslate2 backends for model inference
- Hugging Face / OpenAI network calls (if using those backends)

##### Architectural patterns and design principles
- “Plug-in” model pattern: abstract interface + multiple interchangeable backends
- Separation of concerns: UI layer ↔ core engine ↔ model implementations ↔ utils
- Single binary/library with three front-ends (CLI, Web, API) but shared core
- Containerization: Dockerfile + docker-compose for reproducible environments

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Docker Container"
    subgraph "User Interfaces" 
      CLI["CLI Interface\n(cli.py)"]:::ui
      WebUI["Web-UI Interface\n(webui.py)"]:::ui
      API["Python API"]:::ui
    end

    subgraph "Core Engine"
      Core["Core Orchestrator\n(main.py)"]:::core
      Configs["Configuration\n(configs.py)"]:::core
    end

    subgraph "Model Layer"
      Abstract["AbstractModel Interface\n(abstract_model.py)"]:::model
      FW["Faster-Whisper\n(faster_whisper_model.py)"]:::model
      HF["Hugging Face\n(hugging_face_model.py)"]:::model
      ST["Stable-TS\n(stable_ts_model.py)"]:::model
      WX["WhisperX\n(whisperX_model.py)"]:::model
      OA["OpenAI API\n(whisper_api_model.py)"]:::model
      WM["Whisper Base\n(whisper_model.py)"]:::model
      WTM["Whisper Timestamped\n(whisper_timestamped_model.py)"]:::model
      WC["Whisper.cpp\n(whispercpp_model.py)"]:::model
    end

    Util["Pre/Post-Processing Utilities\n(utils.py)"]:::util

    subgraph "Examples & Docs"
      Examples["Usage Examples\n(examples/)"]:::util
      Assets["Sample Media Assets\n(assets/)"]:::util
      Docs["Documentation\n(docs/ & mkdocs.yml)"]:::util
    end

    subgraph "Docker & CI"
      Dockerfile["Dockerfile"]:::util
      Compose["docker-compose.yml"]:::util
      CI["CI Workflows\n(.github/workflows/)"]:::util
    end

    %% Flows
    CLI -->|"invoke"| Core
    WebUI -->|"start webui"| Core
    API -->|"call SubsAI"| Core
    Core -->|"load config"| Configs
    Core -->|"select model"| Abstract
    Abstract --> FW
    Abstract --> HF
    Abstract --> ST
    Abstract --> WX
    Abstract --> OA
    Abstract --> WM
    Abstract --> WTM
    Abstract --> WC
    Core -->|"pre/post process"| Util
    Util -->|"media I/O"| Docs
    Util -->|"assets access"| Assets

    %% External Dependencies
    FW -->|"inference"| Torch["PyTorch/CTranslate2"]:::external
    HF -->|"HF Hub API"| HFapi["Hugging Face API"]:::external
    OA -->|"OpenAI Calls"| OAapi["OpenAI API"]:::external
    Util -->|"media merge"| FFmpeg["ffmpeg"]:::external

  end

  %% Click Events
  click CLI "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/cli.py"
  click WebUI "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/webui.py"
  click Core "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/main.py"
  click Configs "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/configs.py"
  click Abstract "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/abstract_model.py"
  click FW "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/faster_whisper_model.py"
  click HF "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/hugging_face_model.py"
  click ST "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/stable_ts_model.py"
  click WX "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/whisperX_model.py"
  click OA "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/whisper_api_model.py"
  click WM "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/whisper_model.py"
  click WTM "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/whisper_timestamped_model.py"
  click WC "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/models/whispercpp_model.py"
  click Util "https://github.com/abdeladim-s/subsai/blob/main/src/subsai/utils.py"
  click Examples "https://github.com/abdeladim-s/subsai/tree/main/examples/"
  click Assets "https://github.com/abdeladim-s/subsai/tree/main/assets/"
  click Docs "https://github.com/abdeladim-s/subsai/tree/main/docs/"
  click Dockerfile "https://github.com/abdeladim-s/subsai/tree/main/Dockerfile"
  click Compose "https://github.com/abdeladim-s/subsai/blob/main/docker-compose.yml"
  click CI "https://github.com/abdeladim-s/subsai/blob/main/.github/workflows/ci.yml"

  %% Styles
  classDef ui fill:#cce5ff,stroke:#2b7db8,color:#000
  classDef core fill:#d4edda,stroke:#3c763d,color:#000
  classDef model fill:#ffe5b4,stroke:#e69500,color:#000
  classDef util fill:#f0f0f0,stroke:#6c757d,color:#000
  classDef external fill:#d6d8db,stroke:#343a40,color:#000
```
