# sergeytrubkin/voice-over-translation architecture

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

- Interactive diagram: https://gitdiagram.com/sergeytrubkin/voice-over-translation
- Repository: https://github.com/sergeytrubkin/voice-over-translation

## Overview

##### Project type and purpose
- This is a browser user-script (Tampermonkey/Violentmonkey) extension that provides on-the-fly voice-over translation of videos in the browser.
- It hooks into video players on supported sites, downloads audio, sends it to translation APIs or proxy/back-end services, renders subtitles, and mixes original/translated audio.

##### File-structure analysis
- src/ – core TypeScript/JavaScript modules:
– audioDownloader/ – audio capture logic
– core/ – event system, cache manager, translation handler, video manager
– localization/ – all locale files and provider
– subtitles/ – subtitle processing and UI widget
– ui/ – UI components, views, and manager
– utils/ – helpers (iframe connector, storage, API wrappers)
- src/styles/ – SCSS definitions for components and subtitles
- dist/ – built user-script bundles (minified and non-minified)
- scripts/wiki-gen/ – tooling to generate wiki pages from config
- patches/ – patch-package patches for vot.js dependency
- config files – package.json, ESLint, Prettier, tsconfig, bun.lock, biome.json
- tests/ – unit tests and fixtures (headers.json, ui.js)
- .github/ – CI workflows for build and release

##### README insights
- Describes main features: real-time translation via Yandex.Translate, subtitle display (neural/auto-generated), audio saving, hotkey controls, volume syncing, styling customization.
- Lists external services/domains: vot-worker (proxy balancer), media-proxy, VOT-backend for unsupported formats.
- Build instructions: npm or Bun, build scripts for multiple variants.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% In-Browser Modules
    subgraph "In-Browser Modules"
        direction TB
        BSH1["Browser Script Host\n(vot.user.js)"]:::browser
        BSH2["Browser Script Host\n(vot-min.user.js)"]:::browser
        VM["Video Manager"]:::browser
        AD["Audio Downloader"]:::browser
        TH["Translation Handler"]:::browser
        CM["Cache Manager"]:::browser
        EI["Event Implementation"]:::browser
        SPProc["Subtitle Processor"]:::browser
        SPWidget["Subtitle Widget"]:::browser
        UIManager["UI Manager"]:::browser
        UIComponents["UI Components"]:::browser
        Overlay["Overlay View"]:::browser
        Settings["Settings View"]:::browser
        LP["Localization Provider"]:::browser
        Locales["Locale Files"]:::browser
        StorageUtil["Storage Utility"]:::browser
        TranslateAPI["Translate APIs Wrapper"]:::browser
        IframeConn["Iframe Connector"]:::browser
        Config["Configuration"]:::browser
        StylesMain["main.scss"]:::browser
        StylesSub["subtitles.scss"]:::browser
        StylesComp["components SCSS"]:::browser

        BSH1 --> VM
        BSH2 --> VM
        VM --> AD
        AD --> TH
        CM --> TH
        TH --> SPProc
        SPProc --> SPWidget
        SPWidget --> UIManager
        UIManager --> UIComponents
        UIManager --> Overlay
        UIManager --> Settings

        Overlay -->|"uses"| LP
        Settings -->|"uses"| LP
        UIComponents -->|"localized by"| LP
        LP --> Locales

        EI --> VM
        EI --> AD
        EI --> TH
        EI --> SPProc
        UIComponents --> EI
        Overlay --> EI
        Settings --> EI

        StorageUtil --> CM
        StorageUtil --> UIManager

        TranslateAPI --> TH
        IframeConn --> UIManager
        Config --> TH

        StylesMain --> UIComponents
        StylesMain --> Overlay
        StylesMain --> Settings
        StylesSub --> SPWidget
        StylesComp --> UIComponents
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Yandex["Yandex.Translate API"]:::external
        VOTWorker["vot-worker / proxy balancer"]:::external
        MediaProxy["media-proxy"]:::external
        TH -->|calls| Yandex
        TH -->|via proxy| VOTWorker
        AD -->|via proxy| MediaProxy
    end

    %% Storage
    StorageDB[(Browser Storage)]:::storage
    StorageUtil --> StorageDB

    %% Build & Tools
    subgraph "Build & Tooling"
        direction TB
        Patches["patches/@vot.js+core+2.4.3.patch"]:::tools
        WikiGen["scripts/wiki-gen/"]:::tools
        Tests["tests/"]:::tools
    end

    %% Click Events
    click BSH1 "https://github.com/sergeytrubkin/voice-over-translation/blob/master/dist/vot.user.js"
    click BSH2 "https://github.com/sergeytrubkin/voice-over-translation/blob/master/dist/vot-min.user.js"
    click VM "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/core/videoManager.ts"
    click AD "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/audioDownloader/index.ts"
    click TH "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/core/translationHandler.ts"
    click CM "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/core/cacheManager.ts"
    click EI "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/core/eventImpl.ts"
    click SPProc "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/subtitles/processor.ts"
    click SPWidget "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/subtitles/widget.ts"
    click UIManager "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/ui/manager.ts"
    click UIComponents "https://github.com/sergeytrubkin/voice-over-translation/tree/master/src/ui/components/"
    click Overlay "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/ui/views/overlay.ts"
    click Settings "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/ui/views/settings.ts"
    click StylesMain "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/styles/main.scss"
    click StylesSub "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/styles/subtitles.scss"
    click StylesComp "https://github.com/sergeytrubkin/voice-over-translation/tree/master/src/styles/components/"
    click LP "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/localization/localizationProvider.ts"
    click Locales "https://github.com/sergeytrubkin/voice-over-translation/tree/master/src/localization/locales/"
    click StorageUtil "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/utils/storage.ts"
    click TranslateAPI "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/utils/translateApis.ts"
    click IframeConn "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/utils/iframeConnector.ts"
    click Config "https://github.com/sergeytrubkin/voice-over-translation/blob/master/src/config/config.js"
    click Patches "https://github.com/sergeytrubkin/voice-over-translation/blob/master/patches/@vot.js+core+2.4.3.patch"
    click WikiGen "https://github.com/sergeytrubkin/voice-over-translation/tree/master/scripts/wiki-gen/"
    click Tests "https://github.com/sergeytrubkin/voice-over-translation/tree/master/tests/"

    %% Styles
    classDef browser fill:#bbdefb,stroke:#1976d2,color:#0d47a1
    classDef external fill:#c8e6c9,stroke:#388e3c,color:#1b5e20,stroke-dasharray: 5 5
    classDef tools fill:#eeeeee,stroke:#9e9e9e,color:#424242
    classDef storage fill:#fff9c4,stroke:#fbc02d,color:#f57f17,stroke-dasharray: 2 2
```
