# zh-plus/openlrc architecture

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

- Interactive diagram: https://gitdiagram.com/zh-plus/openlrc
- Repository: https://github.com/zh-plus/openlrc

## Overview

##### Main Components
- Core Library (openlrc/):
- Entry Point (likely exposed through openlrc/openlrc.py and the LRCer class in the library)
- Audio/Video Input Handling and Preprocessing (e.g., preprocess.py, context.py, defaults.py, opt.py)
- Transcription Module (transcribe.py): handles audio transcription via faster-whisper.
- Translation Module (translate.py, evaluate.py): routes the transcription text for translation/polishing using one or more LLM engines.
- Prompt and Agent Handling (prompter.py, agents.py, chatbot.py): builds and manages prompts for translation requests and interacts with external Chatbot/LLM APIs.
- Subtitle Generation (subtitle.py): converts results into .lrc/.srt formats.
- Utility and Validation Modules (utils.py, validators.py, logger.py) for logging, file operations, and input validation.
- Graphical User Interface (GUI):
- Streamlit-based interface (located in openlrc/gui_streamlit/) that provides a web-based front end.
- Testing:
- Tests directory contains unit tests targeting core functionality.
- External Dependencies:
- faster-whisper (for transcription)
- External LLM services (e.g., OpenAI, Anthropic, Gemini via specified endpoints)
- Other external libraries (PyTorch for audio processing, ffmpeg for media processing).

##### Relationships and Data Flow
- User/input originates from either:
- The CLI (openlrc/cli.py) or
- The GUI (openlrc/gui_streamlit, using pages and home handlers)
- The process starts with receiving an audio or video file.
- Preprocessing: The file is first passed to preprocessing routines (preprocess.py), which might include noise suppression and loudness normalization.
- Transcription: The preprocessed audio is sent to the transcription component (transcribe.py) which integrates with the faster-whisper engine.
- Translation: The transcription result is passed to the translation module (translate.py) which:
- Generates context-aware prompts (using prompter.py)
- Routes requests to external LLM APIs or chatbot agents (agents.py and chatbot.py). Notice configuration and model routing (as detailed in the README and handled via ModelConfig in the code).
- Subtitle Generation: The translated/polished output is then formatted into subtitle files (using subtitle.py) in the appropriate format (.lrc or .srt).
- Utility and Logging: Throughout the process, utility modules (utils.py, logger.py) and validators ensure consistency and error handling.

##### Architectural Patterns or Design Principles
- Layered/Pipelined Architecture: The process is clearly segmented into stages (input -> preprocessing -> transcription -> translation -> output), each encapsulated in its own module.
- Modular Design: Separation of concerns is evident (e.g., distinct modules for transcription, translation, and prompt generation).
- Extensibility: There are hooks for supporting multiple Chatbot providers and easily integrating new LLM endpoints or custom prompt configurations.
- Concurrency: While transcription per file is handled sequentially (to maintain context), translation is mentioned to run concurrently for each file.

##### Relevant Technologies & Libraries
- Python ecosystem (Poetry for dependency management, pyproject.toml)
- faster-whisper for ASR, PyTorch as backend for audio processing
- Third-party APIs for translation (OpenAI, Anthropic, etc.)
- Streamlit for the Web GUI
- CI/CD pipelines via GitHub workflows configured under .github/workflows

##### Additional Detail Suggestions
- That some operations (like translation) run concurrently per file – this can be annotated near the translation module with a note on “Concurrency” or “Parallel Processing”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI("CLI Interface"):::interface
        GUI("GUI Interface (Streamlit)"):::interface
    end

    %% Core Processing Pipeline
    subgraph "Core Processing Pipeline"
        ENTRY("Core Entry Point"):::core
        PREPROC("Preprocessing"):::core
        TRANSCRIBE("Transcription"):::core
        TRANSLATE("Translation"):::core
        PROMPT("Prompt & Agents"):::core
        SUBTITLE("Subtitle Generation"):::core
        UTIL("Utilities & Validation"):::core
    end

    %% External Services
    subgraph "External Services"
        FAST_WHISPER("faster-whisper Engine"):::external
        LLM("LLM APIs"):::external
        OTHER("Other Dependencies"):::external
    end

    %% Connections for User Interfaces to Core
    CLI -->|"uses"| ENTRY
    GUI -->|"uses"| ENTRY

    %% Core Processing Flow
    ENTRY -->|"initiates"| PREPROC
    PREPROC -->|"prepares file"| TRANSCRIBE
    TRANSCRIBE -->|"calls"| FAST_WHISPER
    FAST_WHISPER -->|"returns transcription"| TRANSCRIBE
    TRANSCRIBE -->|"sends text to"| TRANSLATE
    TRANSLATE -->|"invokes"| PROMPT
    PROMPT -->|"requests via"| LLM
    LLM -->|"returns translation"| PROMPT
    PROMPT -->|"feeds polished text to"| TRANSLATE
    TRANSLATE -->|"outputs result to"| SUBTITLE
    SUBTITLE -->|"formats output"| UTIL
    UTIL -->|"logs/validates"| ENTRY

    %% Concurrency Note on Translation
    TRANSLATE ---|"concurrent processing"| CONCURRENT[("Note: Translation runs concurrently")]

    %% Click Events for Core Library Components
    click ENTRY "https://github.com/zh-plus/openlrc/blob/master/openlrc/openlrc.py"
    click PREPROC "https://github.com/zh-plus/openlrc/blob/master/openlrc/preprocess.py"
    click PREPROC "https://github.com/zh-plus/openlrc/blob/master/openlrc/context.py"
    click PREPROC "https://github.com/zh-plus/openlrc/blob/master/openlrc/defaults.py"
    click PREPROC "https://github.com/zh-plus/openlrc/blob/master/openlrc/opt.py"
    click TRANSCRIBE "https://github.com/zh-plus/openlrc/blob/master/openlrc/transcribe.py"
    click TRANSLATE "https://github.com/zh-plus/openlrc/blob/master/openlrc/translate.py"
    click TRANSLATE "https://github.com/zh-plus/openlrc/blob/master/openlrc/evaluate.py"
    click PROMPT "https://github.com/zh-plus/openlrc/blob/master/openlrc/prompter.py"
    click PROMPT "https://github.com/zh-plus/openlrc/blob/master/openlrc/agents.py"
    click PROMPT "https://github.com/zh-plus/openlrc/blob/master/openlrc/chatbot.py"
    click SUBTITLE "https://github.com/zh-plus/openlrc/blob/master/openlrc/subtitle.py"
    click UTIL "https://github.com/zh-plus/openlrc/blob/master/openlrc/utils.py"
    click UTIL "https://github.com/zh-plus/openlrc/blob/master/openlrc/validators.py"
    click UTIL "https://github.com/zh-plus/openlrc/blob/master/openlrc/logger.py"
    click CLI "https://github.com/zh-plus/openlrc/blob/master/openlrc/cli.py"
    click GUI "https://github.com/zh-plus/openlrc/tree/master/openlrc/gui_streamlit/"

    %% Styles
    classDef core fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef interface fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef external fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    class CONCURRENT core
```
