Srtx

Srtx is a typed, package-first Python library and CLI for translating SRT subtitles and transcribing audio or video with Google Gemini.

It is the clean, object-oriented successor to gemini-srt-translator. Workflows live in reusable services, the Typer CLI is a thin adapter, and the package has no GUI dependency.

Features

• SRT translation with preserved timing, formatting, and RTL text
• Audio and video transcription
• Embedded subtitle and speech-focused audio extraction
• Streaming Gemini responses and configurable generation controls
• AI Studio and Google Cloud Enterprise/Vertex authentication
• Resumable workflows with atomic checkpoints
• Token-aware batching, retries, API-key rotation, and recovery splitting
• Structured progress, operational logs, and safe explanatory events
• Reporter adapters for terminals, files, tests, and GUI applications

Quick start

Srtx requires Python 3.13 or newer. FFmpeg and ffprobe are required for media workflows.

python -m pip install srtx
export GEMINI_API_KEY="your-key"

srtx translate subtitles.srt --language French
srtx transcribe interview.mp4 --output interview.srt
srtx extract movie.mkv --subtitles
srtx models

Use Srtx as a library:

from pathlib import Path

from srtx.domain.settings import GeminiAuthSettings
from srtx.domain.translation import TranslationRequest, TranslationSettings
from srtx.infrastructure.gemini.factory import GeminiClientFactory
from srtx.infrastructure.subtitles import SrtRepository
from srtx.services.translation_service import TranslationService

client = GeminiClientFactory().create(
    GeminiAuthSettings(api_key="your-key")
)
service = TranslationService(
    subtitle_repository=SrtRepository(),
    gemini_client=client,
    token_counter=client,
)
result = service.translate(
    TranslationRequest(
        source_path=Path("input.srt"),
        output_path=Path("output.srt"),
        settings=TranslationSettings(target_language="French"),
    )
)

Documentation

The Srtx wiki contains:

• Installation and authentication
• Complete CLI guide
• Using Srtx inside Python projects
• Translation, transcription, and media API guides
• Progress reporters and GUI integration
• Architecture, development, migration, and troubleshooting

Development

uv sync --all-groups
uv run pytest
uv run ruff check .
uv run pyright
uv build

License

Srtx is licensed under GPL-3.0-only.