# weewrr/subtitletool architecture

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

- Interactive diagram: https://gitdiagram.com/weewrr/subtitletool
- Repository: https://github.com/weewrr/subtitletool

## Overview

Subtitle Tool is a desktop/browser subtitle workbench. The main workflow is to open media and subtitles, edit and review timing, then export; users can also request recognition, translation, dubbing, hard-subtitle rendering, and waveform views. The Vue UI communicates with a Flask API, whose route and service layers provide these capabilities. The README documents the major features and API; sampled source confirms selected wiring, while some feature-specific backend links remain unverified.

Main entry points: [`backend/__init__.py`](https://github.com/weewrr/subtitletool/blob/main/backend/__init__.py) (Flask application), [`frontend/src/App.vue`](https://github.com/weewrr/subtitletool/blob/main/frontend/src/App.vue) (Subtitle workbench), [`backend/services/spark_tts_service.py`](https://github.com/weewrr/subtitletool/blob/main/backend/services/spark_tts_service.py) (TTS generation), [`backend/routes/transcription.py`](https://github.com/weewrr/subtitletool/blob/main/backend/routes/transcription.py) (Recognition routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Editing Workbench"]
  node_workbench["Subtitle workbench<br/>[App.vue]"]
  node_subtitle_state["Subtitle editing<br/>[subtitleStore.js]"]
  node_api_client["API client<br/>[ApiService.js]"]
end

subgraph group_backend["Flask API"]
  node_flask["Flask application<br/>[__init__.py]"]
  node_settings["Settings<br/>[settings.py]"]
  node_subtitle_api["Subtitle routes<br/>[subtitle.py]"]
  node_transcription_api["Recognition routes<br/>[transcription.py]"]
  node_translation_api["Translation routes<br/>[translation.py]"]
  node_spell_api["Spell-check routes<br/>[spell_check.py]"]
  node_tts_api["Dubbing routes<br/>[tts.py]"]
  node_media_api["Media routes<br/>[hard_subtitle.py]"]
  node_waveform_api["Waveform routes<br/>[waveform.py]"]
  node_temp_storage[("Temporary files<br/>[temp_dir.py]")]
end

subgraph group_language["Language Services"]
  node_transcription["Recognition jobs"]
  node_translation["Translation engines"]
  node_spellcheck["Spell checking"]
  node_whisper["Whisper engines<br/>[whisper_service.py]"]
end

subgraph group_media["Media Services"]
end

subgraph group_speech["Speech Engines"]
  node_tts_service["TTS generation"]
  node_spark_model["Spark-TTS model<br/>[SparkTTS.py]"]
  node_qwen_model["Qwen3-TTS model<br/>[qwen3_tts_model.py]"]
  node_alignment["Audio alignment<br/>[tts_alignment.py]"]
end

node_user(("Subtitle editor"))
node_external_services(("External AI services"))
node_ffmpeg["FFmpeg tools"]

node_user -->|"edits media"| node_workbench
node_workbench -->|"manages edits"| node_subtitle_state
node_workbench -.->|"requests features"| node_api_client
node_api_client -->|"calls API"| node_flask
node_flask -->|"registers routes"| node_subtitle_api
node_flask -->|"registers routes"| node_transcription_api
node_flask -->|"registers routes"| node_translation_api
node_flask -->|"registers routes"| node_spell_api
node_flask -->|"registers routes"| node_tts_api
node_flask -->|"registers routes"| node_media_api
node_flask -->|"registers routes"| node_waveform_api
node_transcription_api -.->|"starts jobs"| node_transcription
node_transcription -->|"dispatches engine"| node_whisper
node_translation_api -.->|"submits translation"| node_translation
node_translation -.->|"uses providers"| node_external_services
node_spell_api -.->|"checks text"| node_spellcheck
node_tts_api -->|"starts generation"| node_tts_service
node_tts_service -.->|"generates speech"| node_spark_model
node_tts_service -.->|"selects engine"| node_qwen_model
node_tts_service -.->|"aligns audio"| node_alignment
node_tts_api -->|"uses temp files"| node_temp_storage
node_transcription_api -.->|"uses temp files"| node_temp_storage
node_media_api -.->|"renders subtitles"| node_ffmpeg
node_waveform_api -.->|"extracts waveform"| node_ffmpeg
node_subtitle_state -.->|"imports exports"| node_subtitle_api
node_workbench -.->|"translates subtitles"| node_translation_api
node_workbench -.->|"checks spelling"| node_spell_api
node_workbench -.->|"renders hard subtitles"| node_media_api
node_workbench -.->|"requests waveform"| node_waveform_api

click node_workbench "https://github.com/weewrr/subtitletool/blob/main/frontend/src/App.vue"
click node_subtitle_state "https://github.com/weewrr/subtitletool/blob/main/frontend/src/stores/subtitleStore.js"
click node_api_client "https://github.com/weewrr/subtitletool/blob/main/frontend/src/services/ApiService.js"
click node_flask "https://github.com/weewrr/subtitletool/blob/main/backend/__init__.py"
click node_settings "https://github.com/weewrr/subtitletool/blob/main/backend/config/settings.py"
click node_subtitle_api "https://github.com/weewrr/subtitletool/blob/main/backend/routes/subtitle.py"
click node_transcription_api "https://github.com/weewrr/subtitletool/blob/main/backend/routes/transcription.py"
click node_translation_api "https://github.com/weewrr/subtitletool/blob/main/backend/routes/translation.py"
click node_spell_api "https://github.com/weewrr/subtitletool/blob/main/backend/routes/spell_check.py"
click node_tts_api "https://github.com/weewrr/subtitletool/blob/main/backend/routes/tts.py"
click node_media_api "https://github.com/weewrr/subtitletool/blob/main/backend/routes/hard_subtitle.py"
click node_waveform_api "https://github.com/weewrr/subtitletool/blob/main/backend/routes/waveform.py"
click node_transcription "https://github.com/weewrr/subtitletool/blob/main/backend/services/transcription_service.py"
click node_translation "https://github.com/weewrr/subtitletool/blob/main/backend/services/translation_service.py"
click node_spellcheck "https://github.com/weewrr/subtitletool/blob/main/backend/services/spell_check_service.py"
click node_tts_service "https://github.com/weewrr/subtitletool/blob/main/backend/services/spark_tts_service.py"
click node_spark_model "https://github.com/weewrr/subtitletool/blob/main/Spark-TTS/cli/SparkTTS.py"
click node_qwen_model "https://github.com/weewrr/subtitletool/blob/main/Qwen3-TTS/qwen_tts/inference/qwen3_tts_model.py"
click node_alignment "https://github.com/weewrr/subtitletool/blob/main/tts_alignment.py"
click node_whisper "https://github.com/weewrr/subtitletool/blob/main/backend/services/whisper_service.py"
click node_temp_storage "https://github.com/weewrr/subtitletool/blob/main/backend/utils/temp_dir.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_workbench,node_subtitle_state,node_api_client toneBlue
class node_flask,node_settings,node_subtitle_api,node_transcription_api,node_translation_api,node_spell_api,node_tts_api,node_media_api,node_waveform_api,node_temp_storage toneAmber
class node_transcription,node_translation,node_spellcheck,node_whisper toneMint
class node_tts_service,node_spark_model,node_qwen_model,node_alignment,node_user,node_external_services,node_ffmpeg toneIndigo
```

## Components

### Editing Workbench

- [Subtitle workbench](https://github.com/weewrr/subtitletool/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Subtitle editing](https://github.com/weewrr/subtitletool/blob/main/frontend/src/stores/subtitleStore.js): `frontend/src/stores/subtitleStore.js`
- [API client](https://github.com/weewrr/subtitletool/blob/main/frontend/src/services/ApiService.js): `frontend/src/services/ApiService.js`

### Flask API

- [Flask application](https://github.com/weewrr/subtitletool/blob/main/backend/__init__.py): `backend/__init__.py`
- [Settings](https://github.com/weewrr/subtitletool/blob/main/backend/config/settings.py): `backend/config/settings.py`
- [Subtitle routes](https://github.com/weewrr/subtitletool/blob/main/backend/routes/subtitle.py): `backend/routes/subtitle.py`
- [Recognition routes](https://github.com/weewrr/subtitletool/blob/main/backend/routes/transcription.py): `backend/routes/transcription.py`
- [Translation routes](https://github.com/weewrr/subtitletool/blob/main/backend/routes/translation.py): `backend/routes/translation.py`
- [Spell-check routes](https://github.com/weewrr/subtitletool/blob/main/backend/routes/spell_check.py): `backend/routes/spell_check.py`
- [Dubbing routes](https://github.com/weewrr/subtitletool/blob/main/backend/routes/tts.py): `backend/routes/tts.py`
- [Media routes](https://github.com/weewrr/subtitletool/blob/main/backend/routes/hard_subtitle.py): `backend/routes/hard_subtitle.py`
- [Waveform routes](https://github.com/weewrr/subtitletool/blob/main/backend/routes/waveform.py): `backend/routes/waveform.py`
- [Temporary files](https://github.com/weewrr/subtitletool/blob/main/backend/utils/temp_dir.py): `backend/utils/temp_dir.py`

### Language Services

- [Recognition jobs](https://github.com/weewrr/subtitletool/blob/main/backend/services/transcription_service.py): `backend/services/transcription_service.py`
- [Translation engines](https://github.com/weewrr/subtitletool/blob/main/backend/services/translation_service.py): `backend/services/translation_service.py`
- [Spell checking](https://github.com/weewrr/subtitletool/blob/main/backend/services/spell_check_service.py): `backend/services/spell_check_service.py`
- [Whisper engines](https://github.com/weewrr/subtitletool/blob/main/backend/services/whisper_service.py): `backend/services/whisper_service.py`

### Speech Engines

- [TTS generation](https://github.com/weewrr/subtitletool/blob/main/backend/services/spark_tts_service.py): `backend/services/spark_tts_service.py`
- [Spark-TTS model](https://github.com/weewrr/subtitletool/blob/main/Spark-TTS/cli/SparkTTS.py): `Spark-TTS/cli/SparkTTS.py`
- [Qwen3-TTS model](https://github.com/weewrr/subtitletool/blob/main/Qwen3-TTS/qwen_tts/inference/qwen3_tts_model.py): `Qwen3-TTS/qwen_tts/inference/qwen3_tts_model.py`
- [Audio alignment](https://github.com/weewrr/subtitletool/blob/main/tts_alignment.py): `tts_alignment.py`

### Other components

- **Subtitle editor**
- **External AI services**
- **FFmpeg tools**

## Connections

- Subtitle editor → Subtitle workbench: edits media (evidence: `README.md`)
- Subtitle workbench → Subtitle editing: manages edits (evidence: `frontend/src/App.vue`)
- Subtitle workbench → API client: requests features
- API client → Flask application: calls API (evidence: `README.md`)
- Flask application → Subtitle routes: registers routes (evidence: `backend/__init__.py`)
- Flask application → Recognition routes: registers routes (evidence: `backend/__init__.py`)
- Flask application → Translation routes: registers routes (evidence: `backend/__init__.py`)
- Flask application → Spell-check routes: registers routes (evidence: `backend/__init__.py`)
- Flask application → Dubbing routes: registers routes (evidence: `backend/__init__.py`)
- Flask application → Media routes: registers routes (evidence: `backend/__init__.py`)
- Flask application → Waveform routes: registers routes (evidence: `backend/__init__.py`)
- Recognition routes → Recognition jobs: starts jobs
- Recognition jobs → Whisper engines: dispatches engine (evidence: `backend/services/transcription_service.py`)
- Translation routes → Translation engines: submits translation
- Translation engines → External AI services: uses providers (evidence: `README.md`)
- Spell-check routes → Spell checking: checks text
- Dubbing routes → TTS generation: starts generation (evidence: `backend/routes/tts.py`)
- TTS generation → Spark-TTS model: generates speech
- TTS generation → Qwen3-TTS model: selects engine
- TTS generation → Audio alignment: aligns audio
- Dubbing routes → Temporary files: uses temp files (evidence: `backend/routes/tts.py`)
- Recognition routes → Temporary files: uses temp files
- Media routes → FFmpeg tools: renders subtitles (evidence: `README.md`)
- Waveform routes → FFmpeg tools: extracts waveform (evidence: `README.md`)
- Subtitle editing → Subtitle routes: imports exports (evidence: `README.md`)
- Subtitle workbench → Translation routes: translates subtitles (evidence: `README.md`)
- Subtitle workbench → Spell-check routes: checks spelling (evidence: `README.md`)
- Subtitle workbench → Media routes: renders hard subtitles (evidence: `README.md`)
- Subtitle workbench → Waveform routes: requests waveform (evidence: `README.md`)
