# peng-yt/stt architecture

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

- Interactive diagram: https://gitdiagram.com/peng-yt/stt
- Repository: https://github.com/peng-yt/stt

## Overview

##### Project type and purpose
- This is a local, offline, full-stack speech-to-text web application.
- It provides a browser-based UI for uploading video/audio files, invokes a Flask backend that:
- Calls FFmpeg to preprocess media
- Runs the faster-whisper ASR model (CPU or CUDA)
- Returns transcripts in JSON/SRT/TXT
- It also exposes a POST /api endpoint for programmatic use.

##### File structure
Top-level:
- start.py – entry-point launching the Flask app
- static/ – JS/CSS (layui), images, tmp storage
- templates/ – index.html (UI view)
- stslib/ – internal library (cfg.py, tool.py)
- models/ – local whisper model weights
- ffmpeg.7z – packaged FFmpeg executables for media I/O
- set.ini – runtime config (devtype=cpu/cuda)
- version.json – app version metadata
- requirements.txt – Python dependencies (Flask, torch, etc.)

##### Key components
A. Browser (Client UI)
- index.html + layui assets (.js, .css)
- Drag-and-drop or file-choose widget
- Hits HTTP endpoints on Flask server

B. Flask Backend
- start.py sets up routes:
- GET / → renders index.html
- POST /api → handles file + parameters
- stslib.tool.py provides helper functions (transcoding calls, model loading)
- stslib.cfg.py reads set.ini (select CPU vs CUDA)

C. Media Preprocessor (FFmpeg)
- invoked via subprocess for file → WAV chunks
- resides in project root as ffmpeg.exe/ffprobe.exe on Windows or system bin on Linux/Mac

D. ASR Engine (faster-whisper)
- Python module loaded from models/
- Uses PyTorch (CPU or CUDA) for inference
- Outputs timestamped segments

E. Output Formatter
- Converts raw segments into JSON, SRT, or plain text
- Returns HTTP JSON payload

F. Model Storage
- Local filesystem under models/ directory
- User downloads additional weights into models/

G. Configuration & Versioning
- set.ini controls device type
- version.json provides app version

##### Relationships & Data Flow
1) Browser → Flask (HTTP POST with multipart file + metadata)
2) Flask → stslib.tool → invokes FFmpeg (media preprocessing)
3) Preprocessed audio → faster-whisper ASR model (in-memory via Python API)
4) Transcripts → formatting module → HTTP response
5) Browser renders/transfers result to user UI

##### Architectural patterns & design principles
- Monolithic web service (single Flask process hosting UI & API)
- MVC-like separation:
- View: templates + static assets
- Controller: Flask route handlers
- Model: faster-whisper weights + stslib modules
- Config-driven (set.ini) for runtime flexibility (CPU vs CUDA)
- Pluggable components: media I/O (FFmpeg) and ASR engine

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/UI Layer
    subgraph "Client/UI" 
        direction TB
        Browser["Browser UI<br/>layui UI"]:::ui
        Index["index.html"]:::ui
        CSS["layui.css"]:::ui
        JS["layui.js"]:::ui
        Font["font/ (icons)"]:::ui
        Images["images/"]:::ui
        Tmp["tmp/ (uploads)"]:::ui
    end

    %% Backend Layer
    subgraph "Server/Backend" 
        direction TB
        Start["Flask App<br/>(start.py)"]:::backend
        RunBat["run.bat"]:::backend
        API["POST /api"]:::backend
        Tool["stslib/tool.py"]:::backend
        Init["stslib/__init__.py"]:::backend
        Config["stslib/cfg.py"]:::backend
        SetIni["set.ini"]:::storage
    end

    %% Media Preprocessor
    FFmpeg["ffmpeg.7z<br/>FFmpeg Executables"]:::storage

    %% ML Engine Layer
    subgraph "ASR Engine" 
        direction TB
        Decision{"CPU vs CUDA?"}:::ml
        CPUPath["test.py<br/>CPU Inference"]:::ml
        CUDAPath["testcuda.py<br/>CUDA Inference"]:::ml
        ModelLoad["models/ (whisper weights)"]:::storage
        Inference["faster-whisper<br/>PyTorch Inference"]:::ml
    end

    %% Output Formatter
    Format["Formatting<br/>JSON / SRT / TXT"]:::backend

    %% Version & Dependencies
    Version["version.json"]:::storage
    Req["requirements.txt"]:::storage

    %% Data Flow
    Browser -->|uploads file| Start
    Start -->|routes POST /api| API
    API -->|calls helper| Tool
    Tool -->|reads config| Config
    Tool -->|invokes subprocess| FFmpeg
    FFmpeg -->|outputs WAV chunks| Tool
    Tool -->|calls ASR model| Inference
    Inference -->|segments| Format
    Format -->|HTTP Response| Browser

    %% Decision Path for Device
    Tool --> Decision
    Decision -->|CPU| CPUPath
    Decision -->|CUDA| CUDAPath
    CPUPath --> ModelLoad
    CUDAPath --> ModelLoad
    ModelLoad --> Inference

    %% Click Events
    click Index "https://github.com/peng-yt/stt/blob/main/templates/index.html"
    click CSS "https://github.com/peng-yt/stt/blob/main/static/layui/css/layui.css"
    click JS "https://github.com/peng-yt/stt/blob/main/static/layui/layui.js"
    click Font "https://github.com/peng-yt/stt/tree/main/static/layui/font/"
    click Images "https://github.com/peng-yt/stt/tree/main/static/images/"
    click Tmp "https://github.com/peng-yt/stt/tree/main/static/tmp/"
    click Start "https://github.com/peng-yt/stt/blob/main/start.py"
    click RunBat "https://github.com/peng-yt/stt/blob/main/run.bat"
    click Tool "https://github.com/peng-yt/stt/blob/main/stslib/tool.py"
    click Init "https://github.com/peng-yt/stt/blob/main/stslib/__init__.py"
    click Config "https://github.com/peng-yt/stt/blob/main/stslib/cfg.py"
    click SetIni "https://github.com/peng-yt/stt/blob/main/set.ini"
    click FFmpeg "https://github.com/peng-yt/stt/blob/main/ffmpeg.7z"
    click ModelLoad "https://github.com/peng-yt/stt/tree/main/models/"
    click CPUPath "https://github.com/peng-yt/stt/blob/main/test.py"
    click CUDAPath "https://github.com/peng-yt/stt/blob/main/testcuda.py"
    click Version "https://github.com/peng-yt/stt/blob/main/version.json"
    click Req "https://github.com/peng-yt/stt/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#0366d6,color:#0366d6
    classDef backend fill:#d4edda,stroke:#28a745,color:#155724
    classDef ml fill:#fff3cd,stroke:#e0a800,color:#856404
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef Decision fill:#f8d7da,stroke:#dc3545,color:#721c24,shape:diamond

    class Decision Decision
```
