# maktail/gemini-srt-translator architecture

> Architecture diagram of the GitHub repository maktail/gemini-srt-translator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maktail/gemini-srt-translator
- Repository: https://github.com/maktail/gemini-srt-translator

## Overview

Gemini SRT Translator accepts subtitle or media jobs through its CLI or Python API, then translates subtitles or transcribes audio/video with Gemini and writes subtitle output. The agent interface exposes translation as resumable batches; sessions preserve progress and subtitle formatting. Media preparation, model discovery, logging, and agent-skill management are additional capabilities. Edges are limited to relationships shown in excerpts, the source index, or README; some documented capabilities have no sampled implementation details.

Main entry points: [`gemini_srt_translator/main.py`](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/main.py) (Translation and transcription engine), [`gemini_srt_translator/cli.py`](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/cli.py) (Command-line interface), [`gemini_srt_translator/__init__.py`](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/__init__.py) (Python API), [`gemini_srt_translator/session.py`](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/session.py) (Subtitle session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_agent_cli["Agent batch interface<br/>[agent_cli.py]"]
  node_skill["Agent skill management<br/>[skill.py]"]
end

subgraph group_translation["Translation Runtime"]
  node_engine["Translation and transcription engine<br/>[main.py]"]
  node_subtitle_session["Subtitle session<br/>[session.py]"]
  node_prompt_builder["Instruction generation<br/>[helpers.py]"]
  node_transcription_session["Transcription session<br/>[session.py]"]
end

subgraph group_media["Media Processing"]
  node_media_tools["FFmpeg media tools<br/>[ffmpeg_utils.py]"]
end

subgraph group_support["Supporting Capabilities"]
  node_model_discovery["Model discovery<br/>[cli.py]"]
  node_logging["Progress and thought logs<br/>[logger.py]"]
  node_utilities["Version and utility functions<br/>[utils.py]"]
end

node_user(("User"))
node_gemini{{"Google Gemini services"}}
node_subtitle_files[("Subtitle files and progress")]
node_media_files[("Audio and video files")]

node_user -->|"runs commands"| node_cli
node_user -->|"configures jobs"| node_python_api
node_cli -->|"configures and invokes"| node_python_api
node_cli -->|"dispatches agent commands"| node_agent_cli
node_cli -->|"dispatches skill commands"| node_skill
node_python_api -->|"constructs and invokes"| node_engine
node_engine -->|"requests model information"| node_gemini
node_engine -->|"generates instructions"| node_prompt_builder
node_engine -->|"uses session state"| node_subtitle_session
node_engine -->|"commits transcription chunks"| node_transcription_session
node_subtitle_session -->|"reads and writes progress"| node_subtitle_files
node_transcription_session -.->|"saves transcription progress"| node_subtitle_files
node_agent_cli -->|"gets batches and commits"| node_subtitle_session
node_engine -->|"uses media extraction"| node_media_tools
node_media_tools -->|"extracts audio"| node_media_files
node_engine -->|"writes translated subtitles"| node_subtitle_files
node_engine -->|"translates and transcribes"| node_gemini
node_cli -->|"lists available models"| node_model_discovery
node_engine -->|"reports progress"| node_logging
node_cli -.->|"uses version utilities"| node_utilities

click node_cli "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/cli.py"
click node_python_api "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/__init__.py"
click node_agent_cli "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/agent_cli.py"
click node_skill "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/skill.py"
click node_engine "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/main.py"
click node_subtitle_session "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/session.py"
click node_prompt_builder "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/helpers.py"
click node_transcription_session "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/session.py"
click node_media_tools "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/ffmpeg_utils.py"
click node_model_discovery "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/cli.py"
click node_logging "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/logger.py"
click node_utilities "https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/utils.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_cli,node_python_api,node_agent_cli,node_skill,node_user toneBlue
class node_engine,node_subtitle_session,node_prompt_builder,node_transcription_session,node_subtitle_files,node_media_files toneAmber
class node_media_tools toneMint
class node_model_discovery,node_logging,node_utilities toneRose
class node_gemini toneIndigo
```

## Components

### User Interfaces

- [Command-line interface](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/cli.py): `gemini_srt_translator/cli.py`
- [Python API](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/__init__.py): `gemini_srt_translator/__init__.py`
- [Agent batch interface](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/agent_cli.py): `gemini_srt_translator/agent_cli.py`
- [Agent skill management](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/skill.py): `gemini_srt_translator/skill.py`

### Translation Runtime

- [Translation and transcription engine](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/main.py): `gemini_srt_translator/main.py`
- [Subtitle session](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/session.py): `gemini_srt_translator/session.py`
- [Instruction generation](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/helpers.py): `gemini_srt_translator/helpers.py`
- [Transcription session](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/session.py): `gemini_srt_translator/session.py`

### Media Processing

- [FFmpeg media tools](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/ffmpeg_utils.py): `gemini_srt_translator/ffmpeg_utils.py`

### Supporting Capabilities

- [Model discovery](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/cli.py): `gemini_srt_translator/cli.py`
- [Progress and thought logs](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/logger.py): `gemini_srt_translator/logger.py`
- [Version and utility functions](https://github.com/maktail/gemini-srt-translator/blob/main/gemini_srt_translator/utils.py): `gemini_srt_translator/utils.py`

### Other components

- **User**
- **Google Gemini services**
- **Subtitle files and progress**
- **Audio and video files**

## Connections

- User → Command-line interface: runs commands (evidence: `README.md`)
- User → Python API: configures jobs (evidence: `README.md`)
- Command-line interface → Python API: configures and invokes (evidence: `gemini_srt_translator/cli.py`)
- Command-line interface → Agent batch interface: dispatches agent commands (evidence: `gemini_srt_translator/cli.py`)
- Command-line interface → Agent skill management: dispatches skill commands (evidence: `gemini_srt_translator/cli.py`)
- Python API → Translation and transcription engine: constructs and invokes (evidence: `gemini_srt_translator/__init__.py`)
- Translation and transcription engine → Google Gemini services: requests model information (evidence: `gemini_srt_translator/main.py`)
- Translation and transcription engine → Instruction generation: generates instructions (evidence: `gemini_srt_translator/main.py`)
- Translation and transcription engine → Subtitle session: uses session state (evidence: `gemini_srt_translator/main.py`)
- Translation and transcription engine → Transcription session: commits transcription chunks (evidence: `gemini_srt_translator/main.py`)
- Subtitle session → Subtitle files and progress: reads and writes progress (evidence: `gemini_srt_translator/session.py`)
- Transcription session → Subtitle files and progress: saves transcription progress
- Agent batch interface → Subtitle session: gets batches and commits (evidence: `gemini_srt_translator/agent_cli.py`)
- Translation and transcription engine → FFmpeg media tools: uses media extraction (evidence: `gemini_srt_translator/main.py`)
- FFmpeg media tools → Audio and video files: extracts audio (evidence: `gemini_srt_translator/ffmpeg_utils.py`)
- Translation and transcription engine → Subtitle files and progress: writes translated subtitles (evidence: `README.md`)
- Translation and transcription engine → Google Gemini services: translates and transcribes (evidence: `README.md`)
- Command-line interface → Model discovery: lists available models (evidence: `README.md`)
- Translation and transcription engine → Progress and thought logs: reports progress (evidence: `gemini_srt_translator/main.py`)
- Command-line interface → Version and utility functions: uses version utilities