# zeta-loop/subvela architecture

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

- Interactive diagram: https://gitdiagram.com/zeta-loop/subvela
- Repository: https://github.com/zeta-loop/subvela

## Overview

SubVela is a desktop subtitle-production app. Its main workflow runs from video selection through transcription, subtitle review/editing, optional translation, styling and export with burned-in subtitles. The graph includes shared subtitle state and rendering, plus the documented local/cloud model options. Several links come from the SOURCE INDEX or README rather than sampled implementation excerpts, so unsampled details and uncertain runtime wiring are not expanded.

Main entry points: [`app/app.py`](https://github.com/zeta-loop/subvela/blob/master/app/app.py) (Application shell), [`ui/panels/transcribe_panel.py`](https://github.com/zeta-loop/subvela/blob/master/ui/panels/transcribe_panel.py) (Transcription controls), [`ui/panels/export_panel.py`](https://github.com/zeta-loop/subvela/blob/master/ui/panels/export_panel.py) (Export controls), [`ui/panels/style_panel.py`](https://github.com/zeta-loop/subvela/blob/master/ui/panels/style_panel.py) (Subtitle styling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workflow"]
  node_app["Application shell<br/>[app.py]"]
  node_video_panel["Video selection<br/>[video_panel.py]"]
  node_video_preview["Video preview<br/>[video_preview.py]"]
  node_media_utils["Video utilities<br/>[video_utils.py]"]
  node_state["Application state<br/>[state.py]"]
end

subgraph group_speech_translation["Speech and translation"]
  node_transcribe_panel["Transcription controls"]
  node_local_transcriber["Local transcription<br/>[transcriber.py]"]
  node_cloud_transcriber["Cloud transcription"]
  node_translator["Translation router<br/>[translator.py]"]
  node_local_translation["Local NLLB"]
  node_cloud_translation["Cloud translation<br/>[translation_llm.py]"]
end

subgraph group_subtitle_editing["Subtitle editing"]
  node_subtitle_list["Subtitle review<br/>[subtitle_list.py]"]
  node_subtitle_model["Subtitle data model<br/>[subtitle_model.py]"]
  node_style_panel["Subtitle styling<br/>[style_panel.py]"]
  node_presets["Style presets<br/>[presets.py]"]
  node_font_catalog["Font catalog<br/>[font_catalog.py]"]
  node_renderer["Subtitle renderer"]
end

subgraph group_export["Export and rendering"]
  node_export_panel["Export controls<br/>[export_panel.py]"]
  node_burner["Video subtitle burn<br/>[ffmpeg_burner.py]"]
  node_ass_writer["ASS subtitle writer<br/>[ass_writer.py]"]
  node_srt_writer["SRT subtitle writer<br/>[srt_writer.py]"]
  node_txt_writer["Text subtitle writer<br/>[txt_writer.py]"]
  node_text_content["Subtitle text formatting<br/>[text_content.py]"]
end

subgraph group_settings["Settings and services"]
  node_settings_panel["Provider settings<br/>[settings_panel.py]"]
  node_config[("Configuration and keys<br/>[config.py]")]
end

node_user(("Video editor"))
node_ffmpeg["FFmpeg"]
node_speech_service["Cloud speech APIs"]
node_translation_service["Cloud translation APIs"]

node_user -->|"uses"| node_app
node_app -->|"creates"| node_video_panel
node_app -->|"creates"| node_transcribe_panel
node_app -->|"creates"| node_style_panel
node_app -->|"creates"| node_export_panel
node_app -->|"creates"| node_settings_panel
node_app -->|"creates"| node_video_preview
node_app -->|"creates"| node_subtitle_list
node_video_panel -->|"uses"| node_media_utils
node_transcribe_panel -->|"starts local transcription"| node_local_transcriber
node_transcribe_panel -->|"starts cloud transcription"| node_cloud_transcriber
node_cloud_transcriber -->|"uses"| node_media_utils
node_transcribe_panel -->|"starts translation"| node_translator
node_translator -->|"dispatches to"| node_local_translation
node_translator -->|"dispatches to"| node_cloud_translation
node_transcribe_panel -->|"reads API key"| node_config
node_subtitle_list -->|"edits"| node_subtitle_model
node_style_panel -->|"updates styles"| node_subtitle_model
node_style_panel -->|"manages presets"| node_presets
node_style_panel -->|"queries fonts"| node_font_catalog
node_video_preview -->|"renders subtitles"| node_renderer
node_renderer -->|"reads subtitle styles"| node_subtitle_model
node_renderer -->|"resolves fonts"| node_font_catalog
node_export_panel -->|"starts video export"| node_burner
node_export_panel -->|"exports ASS"| node_ass_writer
node_export_panel -->|"exports SRT"| node_srt_writer
node_export_panel -->|"exports text"| node_txt_writer
node_srt_writer -->|"formats text"| node_text_content
node_txt_writer -->|"formats text"| node_text_content
node_burner -->|"renders overlays"| node_renderer
node_burner -->|"reads subtitle data"| node_subtitle_model
node_burner -->|"runs encoding"| node_ffmpeg
node_settings_panel -->|"configures providers"| node_config
node_cloud_transcriber -.->|"requests transcription"| node_speech_service
node_cloud_translation -.->|"requests translation"| node_translation_service

click node_app "https://github.com/zeta-loop/subvela/blob/master/app/app.py"
click node_video_panel "https://github.com/zeta-loop/subvela/blob/master/ui/panels/video_panel.py"
click node_video_preview "https://github.com/zeta-loop/subvela/blob/master/ui/video_preview.py"
click node_media_utils "https://github.com/zeta-loop/subvela/blob/master/core/video_utils.py"
click node_state "https://github.com/zeta-loop/subvela/blob/master/app/state.py"
click node_transcribe_panel "https://github.com/zeta-loop/subvela/blob/master/ui/panels/transcribe_panel.py"
click node_local_transcriber "https://github.com/zeta-loop/subvela/blob/master/core/transcriber.py"
click node_cloud_transcriber "https://github.com/zeta-loop/subvela/blob/master/core/cloud_transcriber.py"
click node_translator "https://github.com/zeta-loop/subvela/blob/master/core/translator.py"
click node_local_translation "https://github.com/zeta-loop/subvela/blob/master/core/translation_nllb.py"
click node_cloud_translation "https://github.com/zeta-loop/subvela/blob/master/core/translation_llm.py"
click node_subtitle_list "https://github.com/zeta-loop/subvela/blob/master/ui/subtitle_list.py"
click node_subtitle_model "https://github.com/zeta-loop/subvela/blob/master/core/subtitle_model.py"
click node_style_panel "https://github.com/zeta-loop/subvela/blob/master/ui/panels/style_panel.py"
click node_presets "https://github.com/zeta-loop/subvela/blob/master/core/presets.py"
click node_font_catalog "https://github.com/zeta-loop/subvela/blob/master/core/font_catalog.py"
click node_renderer "https://github.com/zeta-loop/subvela/blob/master/core/subtitle_renderer.py"
click node_export_panel "https://github.com/zeta-loop/subvela/blob/master/ui/panels/export_panel.py"
click node_burner "https://github.com/zeta-loop/subvela/blob/master/export/ffmpeg_burner.py"
click node_ass_writer "https://github.com/zeta-loop/subvela/blob/master/export/ass_writer.py"
click node_srt_writer "https://github.com/zeta-loop/subvela/blob/master/export/srt_writer.py"
click node_txt_writer "https://github.com/zeta-loop/subvela/blob/master/export/txt_writer.py"
click node_text_content "https://github.com/zeta-loop/subvela/blob/master/export/text_content.py"
click node_settings_panel "https://github.com/zeta-loop/subvela/blob/master/ui/panels/settings_panel.py"
click node_config "https://github.com/zeta-loop/subvela/blob/master/core/config.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_app,node_video_panel,node_video_preview,node_media_utils,node_state toneBlue
class node_transcribe_panel,node_local_transcriber,node_cloud_transcriber,node_translator,node_local_translation,node_cloud_translation toneAmber
class node_subtitle_list,node_subtitle_model,node_style_panel,node_presets,node_font_catalog,node_renderer,node_speech_service,node_translation_service toneMint
class node_export_panel,node_burner,node_ass_writer,node_srt_writer,node_txt_writer,node_text_content toneRose
class node_settings_panel,node_config,node_user,node_ffmpeg toneIndigo
```

## Components

### Desktop workflow

- [Application shell](https://github.com/zeta-loop/subvela/blob/master/app/app.py): `app/app.py`
- [Video selection](https://github.com/zeta-loop/subvela/blob/master/ui/panels/video_panel.py): `ui/panels/video_panel.py`
- [Video preview](https://github.com/zeta-loop/subvela/blob/master/ui/video_preview.py): `ui/video_preview.py`
- [Video utilities](https://github.com/zeta-loop/subvela/blob/master/core/video_utils.py): `core/video_utils.py`
- [Application state](https://github.com/zeta-loop/subvela/blob/master/app/state.py): `app/state.py`

### Speech and translation

- [Transcription controls](https://github.com/zeta-loop/subvela/blob/master/ui/panels/transcribe_panel.py): `ui/panels/transcribe_panel.py`
- [Local transcription](https://github.com/zeta-loop/subvela/blob/master/core/transcriber.py): `core/transcriber.py`
- [Cloud transcription](https://github.com/zeta-loop/subvela/blob/master/core/cloud_transcriber.py): `core/cloud_transcriber.py`
- [Translation router](https://github.com/zeta-loop/subvela/blob/master/core/translator.py): `core/translator.py`
- [Local NLLB](https://github.com/zeta-loop/subvela/blob/master/core/translation_nllb.py): `core/translation_nllb.py`
- [Cloud translation](https://github.com/zeta-loop/subvela/blob/master/core/translation_llm.py): `core/translation_llm.py`

### Subtitle editing

- [Subtitle review](https://github.com/zeta-loop/subvela/blob/master/ui/subtitle_list.py): `ui/subtitle_list.py`
- [Subtitle data model](https://github.com/zeta-loop/subvela/blob/master/core/subtitle_model.py): `core/subtitle_model.py`
- [Subtitle styling](https://github.com/zeta-loop/subvela/blob/master/ui/panels/style_panel.py): `ui/panels/style_panel.py`
- [Style presets](https://github.com/zeta-loop/subvela/blob/master/core/presets.py): `core/presets.py`
- [Font catalog](https://github.com/zeta-loop/subvela/blob/master/core/font_catalog.py): `core/font_catalog.py`
- [Subtitle renderer](https://github.com/zeta-loop/subvela/blob/master/core/subtitle_renderer.py): `core/subtitle_renderer.py`

### Export and rendering

- [Export controls](https://github.com/zeta-loop/subvela/blob/master/ui/panels/export_panel.py): `ui/panels/export_panel.py`
- [Video subtitle burn](https://github.com/zeta-loop/subvela/blob/master/export/ffmpeg_burner.py): `export/ffmpeg_burner.py`
- [ASS subtitle writer](https://github.com/zeta-loop/subvela/blob/master/export/ass_writer.py): `export/ass_writer.py`
- [SRT subtitle writer](https://github.com/zeta-loop/subvela/blob/master/export/srt_writer.py): `export/srt_writer.py`
- [Text subtitle writer](https://github.com/zeta-loop/subvela/blob/master/export/txt_writer.py): `export/txt_writer.py`
- [Subtitle text formatting](https://github.com/zeta-loop/subvela/blob/master/export/text_content.py): `export/text_content.py`

### Settings and services

- [Provider settings](https://github.com/zeta-loop/subvela/blob/master/ui/panels/settings_panel.py): `ui/panels/settings_panel.py`
- [Configuration and keys](https://github.com/zeta-loop/subvela/blob/master/core/config.py): `core/config.py`

### Other components

- **Video editor**
- **FFmpeg**
- **Cloud speech APIs**
- **Cloud translation APIs**

## Connections

- Video editor → Application shell: uses (evidence: `README.md`)
- Application shell → Video selection: creates (evidence: `app/app.py`)
- Application shell → Transcription controls: creates (evidence: `app/app.py`)
- Application shell → Subtitle styling: creates (evidence: `app/app.py`)
- Application shell → Export controls: creates (evidence: `app/app.py`)
- Application shell → Provider settings: creates (evidence: `app/app.py`)
- Application shell → Video preview: creates (evidence: `app/app.py`)
- Application shell → Subtitle review: creates (evidence: `app/app.py`)
- Video selection → Video utilities: uses (evidence: `ui/panels/video_panel.py`)
- Transcription controls → Local transcription: starts local transcription (evidence: `ui/panels/transcribe_panel.py`)
- Transcription controls → Cloud transcription: starts cloud transcription (evidence: `ui/panels/transcribe_panel.py`)
- Cloud transcription → Video utilities: uses (evidence: `core/cloud_transcriber.py`)
- Transcription controls → Translation router: starts translation (evidence: `ui/panels/transcribe_panel.py`)
- Translation router → Local NLLB: dispatches to (evidence: `core/translator.py`)
- Translation router → Cloud translation: dispatches to (evidence: `core/translator.py`)
- Transcription controls → Configuration and keys: reads API key (evidence: `ui/panels/transcribe_panel.py`)
- Subtitle review → Subtitle data model: edits (evidence: `ui/subtitle_list.py`)
- Subtitle styling → Subtitle data model: updates styles (evidence: `ui/panels/style_panel.py`)
- Subtitle styling → Style presets: manages presets (evidence: `ui/panels/style_panel.py`)
- Subtitle styling → Font catalog: queries fonts (evidence: `ui/panels/style_panel.py`)
- Video preview → Subtitle renderer: renders subtitles (evidence: `ui/video_preview.py`)
- Subtitle renderer → Subtitle data model: reads subtitle styles (evidence: `core/subtitle_renderer.py`)
- Subtitle renderer → Font catalog: resolves fonts (evidence: `core/subtitle_renderer.py`)
- Export controls → Video subtitle burn: starts video export (evidence: `ui/panels/export_panel.py`)
- Export controls → ASS subtitle writer: exports ASS (evidence: `ui/panels/export_panel.py`)
- Export controls → SRT subtitle writer: exports SRT (evidence: `ui/panels/export_panel.py`)
- Export controls → Text subtitle writer: exports text (evidence: `ui/panels/export_panel.py`)
- SRT subtitle writer → Subtitle text formatting: formats text (evidence: `export/srt_writer.py`)
- Text subtitle writer → Subtitle text formatting: formats text (evidence: `export/txt_writer.py`)
- Video subtitle burn → Subtitle renderer: renders overlays (evidence: `export/ffmpeg_burner.py`)
- Video subtitle burn → Subtitle data model: reads subtitle data (evidence: `export/ffmpeg_burner.py`)
- Video subtitle burn → FFmpeg: runs encoding (evidence: `README.md`)
- Provider settings → Configuration and keys: configures providers (evidence: `ui/panels/settings_panel.py`)
- Cloud transcription → Cloud speech APIs: requests transcription
- Cloud translation → Cloud translation APIs: requests translation
