machinewrapped/llm-subtrans

TL;DR

LLM‑Subtrans is a desktop‑style app that lets you translate subtitle files (SRT, ASS/SSA, VTT) using any large‑language‑model API you prefer – OpenRouter, OpenAI, Gemini, Claude, Mistral, Bedrock, or a self‑hosted OpenAI‑compatible server. It can also transcribe audio/video (with optional speaker diarisation) and then translate the resulting subtitles. Install via pre‑built Windows/Mac packages or from source, configure API keys, and run either the GUI (gui‑subtrans) or the command‑line tool (llm‑subtrans).

---

What it does

• Batch‑translate subtitle files – splits a file into chunks, sends each chunk to the chosen LLM, writes a new subtitle file in the target language.
• Supports multiple subtitle formats via a plug‑in system (.srt, .ass/.ssa, .vtt).
• Optional transcription – extracts speech from video/audio, optionally adds speaker labels, then feeds the transcript to the translation pipeline.
• Multiple providers – OpenRouter, Requesty, Opper, Google Gemini, OpenAI (including Azure), DeepSeek, Anthropic, Mistral, custom OpenAI‑compatible servers, and Amazon Bedrock. Local transcription via Qwen‑3‑ASR is also available.
• GUI and CLI – a point‑and‑click interface for most users; a full‑featured command line for scripting and batch jobs.
• Project files (.subtrans) – store progress, settings and allow resuming interrupted translations.

---

Who it’s for

• Movie/TV fans, translators, or content creators who need to generate subtitles in another language quickly.
• Developers or power users who want to script bulk subtitle conversion or integrate LLM translation into a pipeline.
• Anyone comfortable providing API keys for cloud LLM services; the tool does not run the models locally (except optional Qwen ASR for transcription).

---

How it works (high‑level)

1. Load a subtitle file (or drag a media file to trigger transcription).
2. Choose a provider and supply the corresponding API key (saved in a .env file or GUI settings).
3. The app splits the subtitles into batches and sends each batch to the LLM using the provider’s chat/completion endpoint. The prompt template inserts the subtitle text ({prompt}) and any speaker labels.
4. The LLM returns the translated lines, which the app writes to a new subtitle file (same format or converted to another format).
5. For transcription, the app calls a speech‑to‑text model (cloud or Qwen‑Local), optionally adds diarisation, and then feeds the result into step 2.

---

Getting started

Quick install (Windows/Mac)

1. Download the appropriate zip from the Releases page.
2. Unzip and run gui‑subtrans.
3. On first launch, enter your API keys for the providers you plan to use.
4. Open a subtitle file, pick a target language, and click Translate.

From source (Linux or custom setup)

git clone https://github.com/machinewrapped/llm-subtrans.git
cd llm-subtrans
# run the installer (creates a venv and optional GUI)
./install.sh   # or install.bat on Windows

Add your keys to a .env file (e.g. OPENAI_API_KEY=…). Install optional extras like qwen-asr if you want local transcription.

---

Key technical details (from the README)

• Python ≥3.10; optional parts need Python 3.12 (Qwen ASR).
• Virtual‑environment based installation; pip install -e . for editable dev installs.
• Provider‑specific notes – e.g., Gemini may block certain content, Claude is expensive, Bedrock requires complex AWS IAM setup.
• Transcription dependencies – ffmpeg/ffprobe must be on the PATH.
• Rate‑limit handling – --ratelimit argument to cap API calls per minute.
• Custom prompt – you can edit the template for servers that need a special format, but must keep the {prompt} placeholder.

---

Pros & cons (summary)

Pros	Cons
Works with any LLM that has an OpenAI‑compatible API, giving flexibility to pick the cheapest or fastest model.	Relies on external APIs – you pay per token and your subtitles/audio are sent to third‑party servers.
GUI makes it accessible to non‑technical users; CLI enables automation.	Local model inference is not supported for translation (only optional local ASR).
Supports several subtitle formats and can also convert between them.	Some providers (e.g., Gemini, Bedrock) have content or rate‑limit restrictions that can interrupt batch jobs.
Project files allow resumable translations.	Setup on Linux/macOS requires building from source and installing Python/ffmpeg dependencies.

---

Bottom line

LLM‑Subtrans is a genuine, functional tool that bridges subtitle files with modern LLM translation services. It’s useful for anyone who needs to generate multilingual subtitles without writing their own API‑calling scripts, while still offering enough configurability for power users.

---

Quick reference cheat‑sheet

Feature	How to use
Translate a file (CLI)	llm-subtrans --auto -l es movie.srt
Choose a specific model	llm-subtrans --model gemini-2.5-flash -l fr subtitles.ass
Convert format while translating	-o out.srt changes the output extension
Transcribe a video	python scripts/transcribe.py film.mkv --language ja
Run GUI	gui-subtrans (or double‑click the packaged exe)
Resume interrupted job	llm-subtrans --project --auto -l de movie.subtrans
Store settings locally	add --portable to the install script or launch command

---

All information above is taken directly from the repository’s README; no external assumptions have been added.