LLM-Subtrans is an open source subtitle translator that uses LLMs as a translation service. It can translate subtitles between any language pairs supported by the language model.
Supports multiple subtitle formats through a pluggable system (currently .srt, .ssa/.ass and .vtt).
Provides transcription from video files and audio tracks, with speaker identification to improve translation accuracy, on supported models.
Note: Subtitles and audio clips are sent to the provider's servers, so their privacy policy applies.
For most users the packaged release is the easiest way to use the program. Download a package from the releases page, unzip to a folder and run gui-subtrans. You will be prompted for some basic settings on first run.
If you want to use the command line tools, modify the code or just prefer to have more control over the setup you will need to install from source.
Every release is packaged for Windows as (gui-subtrans-x.x.x.zip).
Packaged builds are (usually) provided for MacOS with Apple Silicon (gui-subtrans-x.x.x.macos-arm64.zip). If you have an Intel Mac you will need to install from source.
Prebuilt Linux packages are not provided so you will need to install from source.
OpenRouter is a service which aggregates models from a wide range of providers. You will need an OpenRouter API Key to use the service, and a credit balance (though some quite capable models are provided free of charge).
You can choose to let OpenRouter select the model automatically (the "Use Default Model" setting in the GUI or --auto on the command line) or you can specify a specific model.
Gemini Flash is probably the leading model for translation speed and fluency, despite some censorship.
You will need a Google Gemini API key from https://ai.google.dev/ or from a project created on https://console.cloud.google.com/. You must ensure that Generative AI is enabled for the api key and project.
Unfortunately Gemini will refuse to translate content that contains certain words or phrases, even with minimal safety settings. If you hit this you will need to use another provider for the batch.
https://openai.com/policies/privacy-policy
You will need an OpenAI API key from https://platform.openai.com/account/api-keys to use OpenAI's GPT models.
You can use the custom api_base parameter to access a custom OpenAI instance (or any other OpenAI-compatible endpoint, though the Custom Server option gives you more control).
You can use an OpenAI Azure installation as a translation provider, but this is only advisable if you know what you're doing - in which case hopefully it will be clear how to configure the Azure provider settings.
https://platform.deepseek.com/downloads/DeepSeek%20Open%20Platform%20Terms%20of%20Service.html
You will need a DeepSeek API key from https://platform.deepseek.com/api_keys to use this provider.
- API Base: You can optionally specify a custom URL, e.g. if you are hosting your own DeepSeek instance.
DeepSeek is quite simple to set up and offers reasonable performance at a very low price, though translation does not seem to be its strongest point.
https://support.anthropic.com/en/collections/4078534-privacy-legal
You will need an Anthropic API key from https://console.anthropic.com/settings/keys to use Claude as a provider. Translation is not Claude's strongest suit, and the API is expensive compared to others.
The API has strict rate limits based on your credit tier, both on requests per minutes and tokens per day.
You will need a Mistral API key from https://console.mistral.ai/api-keys/ to use this provider.
- Server URL: If you are using a custom deployment of the Mistral API, you can specify the server URL using the
--server_urlargument. - Model:
mistral-large-latestis recommended for translation. Smaller models tend to perform poorly and may not follow the system instructions well.
LLM-Subtrans can interface directly with any server that supports an OpenAI compatible API, including locally hosted models e.g. LM Studio.
You should not expect particularly good results from local models. LLMs derive much of their power from their size, so the small, quantized models you can run on a consumer GPU are likely to produce weak translations, or fail to generate valid responses.
Chat and completion endpoints are supported - configure the settings and endpoint based on the model the server is running. The prompt template can be edited if you are using a model that requires a particular format - make sure to include at least the {prompt} tag in the template, as this is where the subtitles that need translating in each batch will be inserted.
https://aws.amazon.com/service-terms/
Bedrock is not recommended for most users: The setup process is complex, requiring AWS credentials, proper IAM permissions, and region configuration. Additionally, not all models on Bedrock support translation tasks or offer reliable results. Bedrock support will not be included in packaged releases - if you can handle setting up AWS, you can handle installing llm-subtrans from source.
To use Bedrock, you must:
- Create an IAM user or role with appropriate permissions (e.g.,
bedrock:InvokeModel,bedrock:ListFoundationModels). - Ensure the model you wish to use is accessible in your selected AWS region and enabled for the IAM user.
LLM-Subtrans can transcribe audio and video files (mp4, mkv, mp3, wav, ...), which can then be translated with the normal workflow. This can produce better results than a text-only translation flow, with more accurate timings and speaker identification (depending on the provider).
Note: Transcription requires ffmpeg/ffprobe to be installed and accessible.
From the GUI, click Transcribe Audio in the toolbar (Ctrl+R) to open a separate dialog for transcription. A successful result will be opened as a translation project upon completion.
- OpenRouter: Provides several speech-to-text models, e.g. the excellent MAI Transcribe 2, DeepGram and Grok.
- Gemini:
gemini-3.5-transcribewith word timestamps and speaker diarization. Very good, but brutal rate limits. - Muse: Meta `muse-voice-transcribe-1. Slow, and only provides approximate timings.
- OpenAI:
whisper-1(word timestamps) andgpt-4o-transcribe-diarize. Experimental support.
Qwen Local runs Qwen3-ASR on your computer without sending audio to a transcription service. This is a beta feature.
It requires a separate PyTorch; install suitable for your hardware. The first run downloads about 6 GB of model weights. For packaged builds, use Set up Torch... in Qwen Local's settings. For source installs the install script will manage the dependencies.
For source installs, qwen-asr's own dependencies (numpy, scipy, librosa) currently require Python 3.12+, higher than the 3.10+ needed for the rest of the project.
If you want to use the command line tools or modify the program, you will need to have Python 3.10+ and pip installed on your system, then follow these steps.
Clone the LLM-Subtrans repository to your local machine using the following command or your preferred tool:
```sh
git clone https://github.com/machinewrapped/llm-subtrans.git
```
The easiest setup method is to run the unified installation script:
- Windows: Run
install.bat - MacOS/Linux: Run
install.sh
These scripts will create a virtual environment and offer install with GUI or install command line only options, with additional options to add support for specific providers. The script will guide you through the setup and generate command scripts to launch the application.
Pass --portable to install.bat or install.sh to create the local .settings directory without prompting. Use --configpath <directory> to configure a different settings and log directory; the installer saves that path in .env.
During the installing process, you can choose to input an API key for each selected provider when prompted, which will be saved in a .env file so that you don't need to provide it every time you run the program. This is largely redundant if you only plan to use the GUI, as keys can be saved in the app settings.
If you ran an install script you can skip the remaining steps. Continue reading only if you want to configure the environment manually instead.
-
Create a new file named .env in the root directory of the project. Add any required settings for your chosen provider to the .env file like this:
OPENROUTER_API_KEY=<your_openrouter_api_key> OPENAI_API_KEY=<your_openai_api_key> GEMINI_API_KEY=<your_gemini_api_key> AZURE_API_KEY=<your_azure_api_key> CLAUDE_API_KEY=<your_claude_api_key>
If you are using Azure:
AZURE_API_BASE=<your api_base, such as https://something.openai.azure.com> AZURE_DEPLOYMENT_NAME=<deployment_name>
If you are using Bedrock:
AWS_ACCESS_KEY_ID=your-access-key-id AWS_SECRET_ACCESS_KEY=your-secret-access-key AWS_REGION=your-region
For OpenAI reasoning models you can set the reasoning effort (default is low):
OPENAI_REASONING_EFFORT=low/medium/high
-
Create a virtual environment for the project by running the following command in the root folder to create a local environment for the Python interpreter (optional, but highly recommended to avoid dependency conflicts with other Python applications):
python -m venv envsubtrans
-
Activate the virtual environment by running the appropriate command for your operating system. You will need to do this each time before running the app.
.\envsubtrans\Scripts\activate # Windows source ./envsubtrans/bin/activate # Mac/Linux
-
Install the project (add the -e switch for an editable install if you want to modify the code):
pip install -e . # Minimal install of command line tools with support for OpenRouter or Custom Server pip install -e ".[gui]" # Core module and default provider with GUI module pip install -e ".[gui,openai,gemini,claude,mistral,bedrock]" # Full install with optional providers (delete to taste)
-
Optionally install
qwen-asrfor local transcription.
First install a hardware-appropriate Torch version, then install the qwen package.
```sh
python scripts/install_torch.py
pip install -e ".[qwen-asr]"
```
This avoids qwen pulling in a generic Torch version without hardware acceleration.
The program works by dividing the subtitles up into batches and sending each one to the translation service in turn.
It can potentially make many API calls for each subtitle file, depending on the batch size. Speed heavily depends on the selected model.
By default The translated subtitles will be written to a new file in the same directory with the target langugage appended to the original filename.
The Subtrans GUI is the best and easiest way to use the program.
After installation, launch the GUI with the gui-subtrans command or shell script, and hopefully the rest should be self-explanatory.
See the project wiki for further details on how to use the program.
LLM-Subtrans can be used as a console command or shell script. The install scripts create a cmd or sh file in the project root for each provider, which will take care of activating the virtual environment and calling the corresponding translation script.
# Use OpenRouter with automatic model selection
llm-subtrans --auto -l <language> <path_to_subtitle_file>
# Use OpenRouter with a specific model
llm-subtrans --model google/gemini-2.5-flash -l <language> <path_to_subtitle_file>
# Convert format while translating (ASS to SRT in this example)
llm-subtrans -l <language> -o output.srt input.ass
# Use any server with an OpenAI-compatible API
llm-subtrans -s <server_address> -e <endpoint> -k <api_key> -l <language> <path_to_subtitle_file>
# Use specific providers
gpt-subtrans --model gpt-5-mini --target-language <target_language> <path_to_subtitle_file>
gemini-subtrans --model gemini-2.5-flash-latest --target-language <target_language> <path_to_subtitle_file>
claude-subtrans --model claude-3-5-haiku-latest --target-language <target_language> <path_to_subtitle_file>
# List supported subtitle formats
llm-subtrans --list-formats
# Batch process files in a folder tree (activate the virtual environment first)
python scripts/batch_translate.py ./subtitles ./translated --provider openai --model gpt-5-mini --apikey sk-... --language SpanishThe output format is inferred from file extensions. To convert between formats, provide an output path with the desired extension.
If the target language is not specified the default is English.
Other options that can be specified on the command line are detailed below.
Transcription is a separate process.
# Transcribe with the default provider (Qwen Local)
python scripts/transcribe.py movie.mkv --language Chinese --format ass
# Use a cloud provider
python scripts/transcribe.py movie.mkv --provider OpenRouter --model mai/mai-transcribe-2 --apikey sk-... --language Japanese --diarizeTranscription options:
--provider— transcription provider (default:Qwen Local; use--list-providersto list)--language— spoken language hint (e.g. Chinese, English)--track— audio track index (default: 0; use--list-tracksto identify audio tracks in the source)--diarize/--no-diarize— request speaker diarization (model-dependent)--align/--no-align— word-level timestamps (default: on)--format— output format:srt,ass, orvtt(default:vtt;ass/vttpreserve speaker labels)-o/--output— output file path (defaults to alongside the media file)-s/--server— server address for the provider-k/--apikey— API key for cloud providers-m/--model— model name
Note: Project files are enabled by default in the GUI.
The --project argument or PROJECT_FILE .env setting control whether a project file will be written to disc for the command line.
If enabled, a file will be created with the .subtrans extension when a subtitle file is loaded, containing details of the project. It will be updated as the translation progresses. Writing a project file allows, amongst other things, resuming a translation that was interrupted. It is highly recommended.
# Use OpenRouter and create a persistent project
llm-subtrans --project --auto -l <language> <path_to_subtitle_file>
# Use OpenRouter and resume a persistent project
llm-subtrans --project --auto -l <language> <path_to_subtrans_file>
llm-subtrans --project --auto -l <language> <path_to_subtitle_file> # Project file will be detected automatically if it is in the same folderThe GUI and command-line tools use the platform's standard application-data directory for settings and logs. Use --portable to store them in a .settings folder in the current directory, or --configpath <directory> to set a specific location. An existing .settings directory will automatically activate portable mode.
LLM-Subtrans is primarily a translation application, and format conversion is probably best handled by dedicated tools, but the option exists to read one format and write another.
# Use OpenRouter and convert from .ass to .srt
llm-subtrans --project --auto -l <language> -o <path_to_output_file.srt> <path_to_subtitle_file.ass>There are a number of command-line arguments that offer more control over the translation process.
To use any of these arguments, add them to the command-line after the path to the source file. For example:
llm-subtrans path/to/my/subtitles.srt --moviename "My Awesome Movie" --ratelimit 10 --substitution cat::dogDefault values for many settings can be set in the .env file, using a NAME_IN_CAPS format. See Options.py and the various Provider_XXX files for the full list.
-
-l,--target-language: The language to translate the subtitles to. -
-o,--output: Specify a filename for the translated subtitles. -
--project: Read or Write a project file for the subtitles being translated (see above for details) -
--ratelimit: Maximum number of requests to the translation service per minute (mainly relevant if you are using an OpenAI free trial account). -
--moviename: Optionally identify the source material to give context to the translator. -
--description: A brief description of the source material to give further context. Less is generally more here, or the AI can start improvising. -
--name,--names: Optionally provide (a list of) names to use in the translation (more powerful AI models are more likely to actually use them). -
--substitution: A pair of strings separated by::, to substitute in either source or translation, or the name of a file containing a list of such pairs. -
--build-terminology-map: Accumulates names, titles and technical terms into a terminology map that is provided to subsequent batches so that consistent translations can be used throughout. -
--terminology: Seed the terminology map with aSOURCE::TRANSLATIONpair, or a path to a text file of such pairs. Repeatable. Example:--terminology "Alice::アリス" --terminology wonderland_locations.txt -
--scenethreshold: Number of seconds between lines to consider it a new scene. -
--minbatchsize: Minimum number of lines to consider starting a new batch to send to the translator. Higher values typically result in faster and cheaper translations but increase the risk of desyncs. -
--maxbatchsize: Maximum number of lines before starting a new batch is compulsory. This needs to take into account the token limit for the model being used, but the "optimal" value depends on many factors, so experimentation is encouraged. Larger batches are more cost-effective but increase the risk of the AI desynchronising, triggering expensive retries. -
--preprocess: Preprocess the subtitles prior to batching. This performs various actions to prepare the subtitles for more efficient translation, e.g. splitting long (duration) lines into multiple lines. Mainly intended for subtitles that have been automatically transcribed with e.g. Whisper. -
--postprocess: Post-process translated subtitles. Performs various actions like adding line breaks to long lines and normalising dialogue tags after a translation request. -
--instruction: An additional instruction for the AI indicating how it should approach the translation. -
--instructionfile: Name/path of a file to load AI system instructions from (otherwise the default instructions.txt is used). -
--maxlines: Maximum number of batches to process. To end the translation after a certain number of lines, e.g. to check the results. -
--temperature: A higher temperature increases the random variance of translations. Default 0. -
--reload: Subtitles will be reloaded from the source file rather than using the subtitles saved in the project (note: this implies--project) -
--retranslate: Existing translations will be ignored and all subtitles will be retranslated (note: this implies--project) -
--reparse: Existing translations will not be sent to the translator again but the translator's response will be reprocessed to extract the translations. This is mainly useful after a bug fix release, but can also be used to reset translations that have been hand-edited (note: this implies--project) -
--preview: Subtitles will be loaded and batched and the translation flow will run, but no calls to the translator will be made. Only useful for debug.
Some additional arguments are available for specific providers.
-
-k,--apikey: Your OpenRouter API Key (the app will look for OPENROUTER_API_KEY in the environment if this is not provided) -
--autoAutomatically select the model to use (selection criteria can be configured in the OpenRouter Dashboard)
-
-k,--apikey: Your OpenAI API Key (the app will look for OPENAI_API_KEY in the environment if this is not provided) -
-b,--apibase: API base URL if you are using a custom instance. if it is not set, the default URL will be used. -
-httpx: Use the HTTPX library for requests (only supported if apibase is specified) -
-m,--model: Specify the AI model to use for translation
-
-k,--apikey: Your Google Gemini API Key. (the app will look for GEMINI_API_KEY in the environment if this is not provided) -
-m,--model: Specify the AI model to use for translation
-
-k,--apikey: Your Anthropic API Key. (the app will look for ANTHROPIC_API_KEY in the environment if this is not provided) -
-m,--model: Specify the AI model to use for translation. This should be the full model name, e.g.claude-3-haiku-20240307
-
-k,--apikey: Your DeepSeek API Key. (the app will look for DEEPSEEK_API_KEY in the environment if this is not provided) -
-b,--apibase: Base URL if you are using a custom deployment of DeepSeek. if it is not set, the official URL will be used. -
-m,--model: Specify the model to use for translation. deepseek-chat is probably the only sensible choice (and default).
-
-k,--apikey: Your Mistral API Key. (the app will look for MISTRAL_API_KEY in the environment if this is not provided) -
--server_url: URL if you are using a custom deployment of Mistral. if unset, the official URL will be used. -
-m,--model: Specify the model to use for translation. mistral-large-latest is recommended, the small models are not very reliable.
-
--deploymentname: Azure deployment name -
-k,--apikey: API key for your deployment. -
-b,--apibase: API backend base address. -
-a,--apiversion: Azure API version.
-
-k,--accesskey: Your AWS Access Key ID. Not required if it is set in the.envfile. -
-s,--secretkey: Your AWS Secret Access Key. Not required if it is set in the.envfile. -
-r,--region: AWS Region where Bedrock is available. You can check the list of regions here. For example:us-east-1oreu-west-1. -
-m,--model: The ID of the Bedrock model to use for translation. Examples includeamazon.titan-text-lite-v1oramazon.titan-text-express-v1.
-
-s,--server: The address the server is running on, including port (e.g. http://localhost:1234). Should be provided by the server -
-e,--endpoint: The API function to call on the server, e.g./v1/completions. Choose an appropriate endpoint for the model running on the server. -
-k,--apikey: API key if required (local servers shouldn't need an api key) -
-m,--model: The model to use for translation if required (for local servers this is probably determined by the server) -
--chat: Specify this argument if the endpoint expects requests in a conversation format - otherwise it is assumed to be a completion endpoint. -
--systemmessages: If using a conversation endpoint, translation instructions will be sent as the "system" user if this flag is specified.
LLM-Subtrans has support for proxies across most providers.
You can configure a proxy using the following arguments:
-
--proxy <URL>: Specify the proxy URL. Supports both HTTP and SOCKS proxies. Example:--proxy http://127.0.0.1:8888or--proxy socks5://127.0.0.1:1080 -
--proxycert <PATH>: Path to a custom CA certificate bundle (PEM format). This is required when using an intercepting proxy (likemitmproxyorFiddler) that uses a self-signed certificate. Example:--proxycert C:\Users\name\.mitmproxy\mitmproxy-ca-cert.pem
# Use a SOCKS proxy for OpenRouter
llm-subtrans --auto -l Spanish input.srt --proxy socks5://127.0.0.1:1080
# Use mitmdump with a custom certificate
llm-subtrans --auto -l French input.srt --proxy http://127.0.0.1:8080 --proxycert ./mitmproxy-ca-cert.pemYou can process files with the following directory structure：
# -SRT
# --fold1
# ---1.srt
# ---2.srt
# ...
# --fold2
# ---1.srt
# ---2.srt
# ...
Use the batch_translate.py script to process multiple subtitle files:
You can modify the DEFAULT_OPTIONS values directly in the script file, or use a combination of script defaults and command line overrides.
# Preview mode to test settings without making API calls
python scripts/batch_translate.py --preview
# Basic usage with command line arguments
python scripts/batch_translate.py ./subtitles ./translated --provider openai --model gpt-5-mini --apikey sk-... --language Spanish
# Override output format
python scripts/batch_translate.py ./subtitles ./translated --provider openai --output-format srt
# Use additional options
python scripts/batch_translate.py ./subtitles ./translated --provider openai --option max_batch_size=40 --option preprocess_subtitles=falseIt is recommended to use an IDE such as Visual Studio Code to run the program when installed from source, and set up a launch.json file to specify the arguments.
Note: Remember to activate the virtual environment every time you work on the project.
Contributions from the community are welcome! To contribute, follow these steps:
Fork the repository onto your own GitHub account.
Clone the repository onto your local machine using the following command:
git clone https://github.com/your_username/llm-subtrans.gitCreate a new branch for your changes using the following command:
git checkout -b feature/your-new-featureInstall pyright as a pre-commit hook (optional but encouraged):
# Install pyright for type checking
pip install pyright
# Install git hooks (runs type checking before commits)
# Windows:
hooks\install.bat
# Linux/Mac:
./hooks/install.shMake your changes to the code and commit them with a descriptive commit message.
Push your changes to your forked repository.
Submit a pull request to the main LLM-Subtrans repository.
LLM-Subtrans uses GNU gettext for UI localization.
- Template (POT):
locales/gui-subtrans.pot - Per‑language catalogs:
locales/<lang>/LC_MESSAGES/gui-subtrans.po - Compiled catalogs:
locales/<lang>/LC_MESSAGES/gui-subtrans.mo
Strings in the code are marked with helpers (see codebase):
_("text")for simple stringstr("context", "text")for contextualized strings
Contributions are very welcome - you can add a new localization in minutes! See docs/localization_contributing.md for detailed instructions (tools, workflow, etc).
This project uses several useful libraries:
- srt (https://github.com/cdown/srt)
- pysubs2 (https://github.com/tkarabela/pysubs2)
- requests (https://github.com/psf/requests)
- regex (https://github.com/mrabarnett/mrab-regex)
- httpx (https://github.com/projectdiscovery/httpx)
- babel (https://github.com/python-babel/)
Translation providers:
- openai (https://platform.openai.com/docs/libraries/python-bindings)
- google-genai (https://github.com/googleapis/python-genai)
- anthropic (https://github.com/anthropics/anthropic-sdk-python)
- mistralai (https://github.com/mistralai/client-python)
- boto3 (Amazon Bedrock) (https://github.com/boto/boto3)
For the GUI:
- pyside6 (https://wiki.qt.io/Qt_for_Python)
- blinker (https://pythonhosted.org/blinker/)
- darkdetect (https://github.com/albertosottile/darkdetect)
- appdirs (https://github.com/ActiveState/appdirs)
For bundled versions:
- python (https://www.python.org/)
- pyinstaller (https://pyinstaller.org/)
Version 1.3 added OpenRouter as the default translation service, opening up access to many more
Version 1.2 added localization for the GUI and support for the GPT-5 model line.
Version 1.1 added support for a more flexible translation format for use with custom instructions.
Version 1.0 is (ironically) a minor update, updating the major version to 1.0 because the project has been stable for some time.
Version 0.7 introduced optional post-processing of translated subtitles to try to fix some of the common issues with LLM-translated subtitles (e.g. adding line breaks), along with new default instructions that tend to produce fewer errors.
Version 0.6 changes the architecture to a provider-based system, allowing multiple AI services to be used as translators. Settings are compartmentalised for each provider. For the intial release the only supported provider is OpenAI.
Version 0.5 adds support for gpt-instruct models and a refactored code base to support different translation engines. For most users, the recommendation is still to use the gpt-3.5-turbo-16k model with batch sizes of between (10,100) lines, for the best combination of performance/cost and translation quality.
Version 0.4 features significant optimisations to the GUI making it more responsive and usable, along with numerous bug fixes.
Version 0.3 featured a major effort to bring the GUI up to full functionality and usability, including adding options dialogs and more, plus many bug fixes.
Version 0.2 employs a new prompting approach that greatly reduces desyncs caused by GPT merging together source lines in the translation. This can reduce the naturalness of the translation when the source and target languages have very different grammar, but it provides a better base for a human to polish the output.
The instructions have also been made more detailed, with multiple examples of correct output for GPT to reference, and the generation of summaries has been improved so that GPT is better able to understand the context of the batch it is translating. Additionally, double-clicking a scene or batch now allows the summary to be edited by hand, which can greatly improve the results of a retranslation and of subsequent batches or scenes. Individually lines can also be edited by double-clicking them.
LLM-Subtrans is licensed under the MIT License. See LICENSE for the 3rd party library licenses.
