# weifeng2333/asrtools architecture

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

- Interactive diagram: https://gitdiagram.com/weifeng2333/asrtools
- Repository: https://github.com/weifeng2333/asrtools

## Overview

##### Project type and purpose
- AsrTools is a desktop GUI application (no separate backend server or database) for batch-processing audio/video files into subtitle formats (.srt, .txt, .ass).
- Built with Python, it uses PyQt5/qfluentwidgets for the UI, a strategy of pluggable ASR engine implementations in bk_asr/, and the requests library to call external ASR services.

##### File structure
- Top‐level files:
- asr_gui.py – entry point, PyQt5 UI setup and event loop
- example.py – demonstration or CLI usage
- requirements.txt – dependencies (requests; optional PyQt5, qfluentwidgets)
- Directory bk_asr/: ASR engine abstraction (BaseASR.py), data structures (ASRData.py), and concrete engine subclasses (JianYingASR.py, KuaiShouASR.py, WhisperASR.py, BcutASR.py).
- resources/: sample media files and screenshots.
- No database or service mesh; multi‐threaded file I/O and HTTP calls to third‐party ASR APIs.

##### README
- Describes user workflow: select ASR engine, add files/folders, click “Start,” then subtitle files appear alongside source.
- Highlights multi‐threaded batch processing, no GPU needed, support for video→audio conversion.

a. Main components
- Presentation/UI Layer – asr_gui.py with PyQt5 windows, controls, drag-drop area, progress indicators
- Application/Controller Layer – task manager or job dispatcher that spins up threads, schedules ASR tasks
- ASR Engine Layer – BaseASR abstraction (strategy pattern) plus concrete classes (Whisper, JianYing, etc.)
- Media Preprocessor – optional ffmpeg subprocess for video→audio conversion
- Subtitle Formatter – logic to build .srt/.txt/.ass from ASRData
- File System – input file picker, output directory writer
- External ASR Service APIs – HTTP endpoints invoked via requests library
b. Relationships and data flows
1. User interacts with UI → sends “start job” event to Controller
2. Controller enqueues jobs → passes file path to Media Preprocessor (if video)
3. Preprocessor outputs audio → hands off to selected ASR Engine
4. ASR Engine (concrete) calls external API or local model → returns ASRData
5. Controller forwards ASRData to Subtitle Formatter → writes subtitle file to disk
6. UI listens for progress/status signals from Controller → updates progress bars/log
c. Architectural patterns/design principles
- Strategy pattern for interchangeable ASREngine implementations
- MVC–like separation: UI (View), Controller (job scheduling, multi-threading), Model (ASRData)
- Single responsibility: each bk_asr/*.py focuses on one engine’s API integration
- Observer pattern (Qt signals/slots) for UI updates on asynchronous tasks
d. Key technologies and libraries
- PyQt5 & qfluentwidgets (UI toolkit)
- Python threading or QThreadPool (concurrency)
- requests (HTTP client for ASR service calls)
- ffmpeg (external binary invoked for video→audio)
- Standard library modules: pathlib/argparse/subprocess/threading

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation/UI Layer"
        GUI["asr_gui.py"]:::internal
        CLI["example.py"]:::internal
    end

    %% Controller Layer
    subgraph "Controller/Task Manager"
        Controller["Controller / Job Dispatcher\n(ThreadPool)"]:::internal
    end

    %% Media Preprocessor
    subgraph "Media Preprocessor"
        Preprocessor["ffmpeg Invoker"]:::external
    end

    %% ASR Engine Layer
    subgraph "ASR Engine Layer"
        BaseASR["BaseASR (Strategy Interface)"]:::internal
        Whisper["WhisperASR"]:::internal
        JianYing["JianYingASR"]:::internal
        KuaiShou["KuaiShouASR"]:::internal
        Bcut["BcutASR"]:::internal
        ASRData["ASRData Model"]:::internal
    end

    %% Formatter
    subgraph "Subtitle Formatter"
        Formatter["Subtitle Formatter"]:::internal
    end

    %% File System
    subgraph "File System"
        InputFS["Input Picker"]:::file
        OutputFS["Output Writer"]:::file
    end

    %% External Services
    subgraph "External Services"
        ASRAPI["Third-Party ASR APIs"]:::external
    end

    %% Documentation & Resources
    subgraph "Docs & Resources"
        Req["requirements.txt"]:::doc
        Res["resources/"]:::file
        RD["README.md"]:::doc
        Lic["LICENSE"]:::doc
    end

    %% Relationships
    GUI -->|"select files"| InputFS
    GUI -->|"start job"| Controller
    CLI -->|"start CLI job"| Controller
    Controller -->|"if video"| Preprocessor
    Preprocessor -->|"audio output"| Controller
    Controller -->|"dispatch task"| BaseASR
    BaseASR --> Whisper
    BaseASR --> JianYing
    BaseASR --> KuaiShou
    BaseASR --> Bcut
    Whisper -->|"calls local model"| ASRData
    JianYing -->|"calls API"| ASRAPI
    KuaiShou -->|"calls API"| ASRAPI
    Bcut -->|"calls API"| ASRAPI
    ASRAPI -->|"returns transcript"| Controller
    Whisper -->|"returns transcript"| Controller
    Controller -->|"transcript data"| ASRData
    Controller -->|"format subtitles"| Formatter
    Formatter -->|"write files"| OutputFS
    Controller -->|"update progress"| GUI

    %% Click Events
    click GUI "https://github.com/weifeng2333/asrtools/blob/main/asr_gui.py"
    click CLI "https://github.com/weifeng2333/asrtools/blob/main/example.py"
    click BaseASR "https://github.com/weifeng2333/asrtools/blob/main/bk_asr/BaseASR.py"
    click ASRData "https://github.com/weifeng2333/asrtools/blob/main/bk_asr/ASRData.py"
    click Whisper "https://github.com/weifeng2333/asrtools/blob/main/bk_asr/WhisperASR.py"
    click JianYing "https://github.com/weifeng2333/asrtools/blob/main/bk_asr/JianYingASR.py"
    click KuaiShou "https://github.com/weifeng2333/asrtools/blob/main/bk_asr/KuaiShouASR.py"
    click Bcut "https://github.com/weifeng2333/asrtools/blob/main/bk_asr/BcutASR.py"
    click Req "https://github.com/weifeng2333/asrtools/blob/main/requirements.txt"
    click Res "https://github.com/weifeng2333/asrtools/tree/main/resources/"
    click RD "https://github.com/weifeng2333/asrtools/blob/main/README.md"
    click Lic "https://github.com/weifeng2333/asrtools/tree/main/LICENSE"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef external fill:#d9ead3,stroke:#333,stroke-width:1px
    classDef file fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef doc fill:#f4cccc,stroke:#333,stroke-width:1px
```
