PySubtrans

PySubtrans is the subtitle translation engine that powers LLM-Subtrans. It provides tools to read and write subtitle files in various formats, connect to various LLMs as translators and manage a translation workflow. It can also transcribe video and audio files into subtitles that are ready for translation.

This package makes these capabilities available as a library that you can incorporate into your own tools and workflows to take advantage of the best-in-class translation quality that LLM-Subtrans provides.

Installation

Basic installation with support for OpenRouter, DeepSeek or any server with an OpenAI-compatible API.

pip install pysubtrans

Additional specialized provider integrations are delivered as optional extras, so that you only install the SDKs for providers you intend to use:

pip install pysubtrans[openai]
pip install pysubtrans[gemini]
pip install pysubtrans[claude]
pip install pysubtrans[openai,gemini,claude,mistral,bedrock]

Quick start: translate a subtitle file

The quickest way to get started is to use the helper functions exposed at the package root. They wrap the classes used by LLM-Subtrans so that you can execute a full translation pipeline with a few lines of code.

from PySubtrans import SaveSettings, init_options, init_subtitles, init_translator

options = init_options(
    provider="Gemini",
    model="gemini-flash-latest",
    api_key="your-api-key",
    prompt="Translate these subtitles into Spanish"
    )

subtitles = init_subtitles("movie.srt", options=options)

translator = init_translator(options)
translator.TranslateSubtitles(subtitles)

subtitles.SaveTranslation("movie-translated.srt", save_settings=SaveSettings(options))

Subtitle format is auto-detected based on file extension or content.

Basic Usage

Working with a SubtitleProject with init_project

SubtitleProject provides a high level interface for managing a translation job, with methods to read and write a project file to disk and event hooks on scene/batch translation. This is the framework that LLM-Subtrans and GUI-Subtrans use to manage translation workflows, but it is general enough that it could be used in other contexts.

init_project instantiates a SubtitleProject and loads and prepares the source subtitles if a file path is supplied.

from PySubtrans import init_options, init_project, init_translator

# Create a project and translate the subtitles
project_settings = init_options(
    provider='OpenRouter',
    model='qwen/qwen3-235b-a22b:free',
    target_language='Spanish',
    api_key='your-openrouter-api-key',
    preprocess_subtitles=True,
    scene_threshold=60,
    max_batch_size=100,
)

project = init_project(project_settings, filepath='path_to_source_subtitles.srt')

# Translate the subtitles
translator = init_translator(project_settings)
project.TranslateSubtitles(translator)

# Save the translation - filename is automatically generated
project.SaveTranslation()

By default projects are only held in memory, but specifying persistent=True will write a .subtrans project file to disk or reload an existing project, allowing a translation job to be resumed at a future time.

# Create a persistent project that can be resumed later
project = init_project(project_settings, filepath='subtitles.srt', persistent=True)
# ... do some work
project.SaveProject()  # Progress is automatically saved

Initialising Subtitles directly with init_subtitles

init_subtitles creates a Subtitles instance, optionally loading subtitle content from a file or string. It auto-detects the format and, by default, prepares the subtitles for translation.

Parameters:

• filepath: Path to a subtitle file to load (mutually exclusive with content)
• content: Subtitle content as a string (mutually exclusive with filepath)
• options: Optional Options instance providing preprocessing and batching settings

Format detection is automatic based on file extension or content analysis.

Supported formats: .srt, .ass, .ssa, .vtt

Examples:

Load subtitles from a file:

from PySubtrans import init_subtitles

subtitles = init_subtitles(filepath="movie.srt")

Load subtitles from a string:

srt_content = """1
00:00:01,000 --> 00:00:03,000
Hello world

2
00:00:04,000 --> 00:00:06,000
This is a test"""

subtitles = init_subtitles(content=srt_content)

By default init_subtitles preprocesses and batches subtitles to be ready for translation, using the provided options. See batch_subtitles for details.

Initialising a SubtitleTranslator with init_translator

init_translator prepares a SubtitleTranslator instance that can be used to translate Subtitles. It uses the provided Options to initialise a TranslationProvider instance to connect to the chosen translation service.

If you want to validate provider credentials and connection details before starting work, call init_translation_provider first and pass the resulting provider into init_translator. This pattern lets you fail fast when credentials are missing or incorrect and reuse the same provider instance across multiple translators.

Instantiating your own SubtitleTranslator allows you to have more fine-grained control over the translation process, e.g. translating individual scenes or batches. You can subscribe to events to receive notifications when individual scenes or batches have been translated to provide realtime feedback or further processing. Event handlers follow the blinker convention, receiving the sender object plus named keyword arguments like scene or batch that describe the update.

Subtitles must be batched prior to translation.

Example

from PySubtrans import init_options, init_translator, init_translation_provider

options = init_options(provider="Gemini", api_key="your-key")
provider = init_translation_provider("Gemini", options)
translator = init_translator(options, translation_provider=provider)
translator.events.scene_translated.connect(on_scene_translated)  # Subscribe to events
translator.TranslateSubtitles(subtitles)

Note that different providers may require different settings. See the LLM-Subtrans documentation for details on supported providers.

OpenRouter and DeepSeek are supported natively, along with connection to any server with an OpenAI chat-compatible API.

from PySubtrans import init_options, init_translation_provider

# Connect to deepseek
options = init_options(
    model="deepseek-chat", 
    api_base="https://api.deepseek.com",
    api_key="sk-..."
)

provider = init_translation_provider("DeepSeek", options)

# Connect to locally hosted model server (e.g. LM Studio)
options = init_options(
    server_address='http://localhost:8000',
    supports_conversation=True,
    max_tokens=4096,
    repetition_penalty=1.1,  # Helps suppress degenerate repetition loops in small models
    min_p=0.05,               # Alternative sampling parameter supported by llama.cpp / vLLM
)

provider = init_translation_provider("Custom Server", options)

Translation Events

SubtitleTranslator emits events during the translation process using the blinker signal library.

Core Translation Events:

• batch_translated: Emitted when a batch completes translation
• batch_updated: Emitted during streaming responses for partial updates
• scene_translated: Emitted when an entire scene is translated
• preprocessed: Emitted when subtitle preprocessing completes
• translation_cost: Emitted when a provider response reports a translation cost (currently only OpenRouter reports costs)

Logging Hooks:

• error: Critical errors that stop translation
• warning: Non-critical issues encountered during translation
• info: General information messages

Configuration with init_options

init_options creates an Options instance and accepts additional keyword arguments for any of the fields documented in Options.default_settings.

The Options class provides a wide range of options to configure the translation process. The default values should work well for most use cases, but some are definitely worth experimenting with.

max_batch_size: controls how many lines will be sent to the LLM in one request. The default is 100 lines. Models like Gemini Flash can easily handle batches of 150 lines or more, which allows for faster translation.

scene_threshold: subtitles are divided into scenes before batching, using this time value as a heuristic to indicate that a scene transition has happened. The default of 60 seconds is very coarse, and may end up with only one scene for dialogue heavy movies or dozens of scenes with only a few lines each for minimalist arthouse films. Depending on your use case, consider setting this very high and relying on the batcher instead.

autosplit_on_error: When a batch fails validation, split it at the largest time-gap nearest the midpoint and retry each half independently. More effective than a straight retry for small local models that struggle with long contexts. Takes priority over retry_on_error when both are set.

postprocess_translation: Runs a pass on the translated subtitles to try to resolve some common problems introduced by translation, e.g. breaking long lines with newlines. The post-processor can perform a range of operations, each of which is enabled by another setting, e.g. break_dialog_on_one_line, normalise_dialog_tags, whitespaces_to_newline, remove_filler_words.

extend_short_subtitles: Extends short subtitles when the translated file is saved, without changing the timestamps stored in the project. The target display time is the greater of min_line_duration and the visible character count multiplied by seconds_per_character. Extensions are capped at the next subtitle's start time minus min_gap. Pass SaveSettings(options) when saving translations directly with a Subtitles instance.

Example usage:

from PySubtrans import init_options

options = init_options(
    provider="Gemini",
    model="gemini-flash-latest",
    api_key="your-key",
    movie_name="French Movie",
    prompt="Translate these subtitles for {movie_name} into German, with cultural references adapted for a German audience",
    max_batch_size=150,
    scene_threshold=120,
    temperature=0.3,
    postprocess_translation=True,
    break_long_lines=True,
    break_dialog_on_one_line=True,
    convert_wide_dashes=True
)

Note that there are a number of options which are only used by the GUI-Subtrans application and have no function in PySubtrans.

Terminology map

build_terminology_map: When enabled, PySubtrans instructs the model to report any names, titles or technical terms with the translation it used, and accumulates them into a terminology map that is injected into each subsequent batch's context, so the same translations are used consistently throughout the file.

The map can be seeded with known translations by passing a terminology_map to init_translator. Accepted forms:

• dict: {"Alice": "アリス", "Wonderland": "ワンダーランド"}
• list[str]: ["Alice::アリス", "Wonderland::ワンダーランド"]
• newline-separated string: "Alice::アリス\nWonderland::ワンダーランド"
• file path: any string without :: is treated as a path to a text file of key::value lines

from PySubtrans import init_options, init_subtitles, init_translator

options = init_options(
    prompt="Translate these subtitles into Japanese",
    build_terminology_map=True,
)

subtitles = init_subtitles("episode2.srt", options=options)

translator = init_translator(options, terminology_map={"Alice": "アリス", "Wonderland": "ワンダーランド"})

def on_terminology_updated(sender, update):
    print(f"New terminology: {update.new_terms}")

translator.events.terminology_updated.connect(on_terminology_updated)
translator.TranslateSubtitles(subtitles)

# Accumulated map is available on the translator after translation
print(translator.terminology_map)

Note: build_terminology_map controls whether the model is asked to report new terms after each batch. A seed terminology_map passed to init_translator is always injected into the prompt context regardless of this setting.

Transcribing media

PySubtrans can also create subtitles from a video or audio file, ready to be translated. init_transcription creates a transcriber with its own provider settings, so the transcription and translation providers can be different. transcribe_media transcribes a file and returns Subtitles divided into scenes and batches, just like init_subtitles.

from PySubtrans import SaveSettings, init_options, init_transcription, init_translator, transcribe_media

options = init_options(provider="Gemini", model="gemini-flash-latest", api_key="your-gemini-key", target_language="English")

transcriber = init_transcription("OpenRouter", api_key="your-openrouter-key", language="Japanese")

subtitles, error = transcribe_media(transcriber, "movie.mkv", options=options)
if error:
    print(f"Transcription is incomplete: {error}")

# Save the transcription first, so it is not lost if translation fails
subtitles.SaveOriginal("movie.ja.vtt")

translator = init_translator(options)
translator.TranslateSubtitles(subtitles)

subtitles.SaveTranslation("movie.en.srt", save_settings=SaveSettings(options))

Transcription requires ffmpeg on the PATH, or pass ffmpeg_path to init_transcription.

Diarization identifies who is speaking, which helps prevent lines spoken by different people from being merged into one subtitle. It is on by default for providers that support it; pass diarize=False to turn it off.

Save the transcription as VTT or ASS rather than SRT. SRT has no way to store speaker labels, so they would be lost if you reload the file later, e.g. to resume or retranslate it.

language accepts a language name or code, e.g. "Japanese" or "ja". If it is omitted, the provider detects the spoken language. Only set it when you are sure: a wrong hint can make the model transcribe some lines in the wrong language.

transcribe_media post-processes and batches the transcribed lines using the options it is given, so pass the translation options to use the same batch settings. Without options it uses the settings the transcriber was created with.

transcribe_media blocks until the transcription is complete, which can take some time for a full-length video. If the transcription stops before the end of the media, the lines transcribed so far are returned along with the error.

Subscribe to transcriber.events for progress updates:

• audio_progress(sender, processed, total): seconds of audio transcribed so far, out of the total length.
• progress(sender, done, span): sent before each chunk of audio is transcribed. The number of chunks is not known in advance, so use audio_progress for overall progress.
• status(sender, text): sent when transcription enters a new phase.

def on_audio_progress(sender, processed, total):
    print(f"Transcribed {processed / total:.0%}")

transcriber.events.audio_progress.connect(on_audio_progress)

Transcription providers

OpenRouter with its default model, microsoft/mai-transcribe-2, is recommended: it gives the best results in our testing.

Provider	Model	Speaker identification	Word timings
OpenRouter	microsoft/mai-transcribe-2 (default)	Yes	Yes
OpenRouter	deepgram/nova-3, x-ai/grok-stt-1.0	Yes	Not verified
OpenRouter	openai/whisper-large-v3-turbo	No	Not verified
Gemini	gemini-3.5-transcribe (default)	Yes, on by default	Yes
OpenAI	whisper-1 (default)	No	Yes
OpenAI	gpt-4o-transcribe-diarize	Yes	No, segment timings only
Muse	muse-voice-transcribe-1.0 (default)	Yes	No, turn timings only
Qwen Local	Qwen/Qwen3-ASR-1.7B (default), Qwen/Qwen3-ASR-0.6B	No	Partial, for languages the aligner supports

OpenRouter, OpenAI and Muse work with the basic installation and an API key. Gemini requires pip install pysubtrans[gemini].

Qwen Local runs Qwen3-ASR on your own hardware. Install a PyTorch build for your hardware from pytorch.org first, then pip install pysubtrans[qwen-asr]. The first run downloads the model weights (about 6 GB). Pass allow_cpu_fallback=True to run without a GPU, though this is much slower.

Advanced workflows

PySubtrans is designed to be modular. The helper functions above are convenient entry points, but you are free to use lower-level components directly when you need more control:

Streaming responses

Translations can be streamed for real-time updates rather than waiting for complete batches.

Supported Providers:

• OpenAI (Reasoning Models only)
• Claude
• Google Gemini
• OpenRouter
• DeepSeek

Enabling Streaming:

from PySubtrans import init_options, init_translator

options = init_options(
    provider="Gemini",
    model="gemini-flash-latest",
    api_key="your-key",
    stream_responses=True
)

translator = init_translator(options)

# Subscribe to streaming events for real-time updates
def on_batch_updated(sender, scene=None, batch=None, translations=None):
    """Called for partial translation updates during streaming"""
    print(f"Scene {scene.number}, Batch {batch.number} translated {len(translations)} lines")

def on_batch_translated(sender, scene=None, batch=None):
    """Called when batch translation completes"""
    print(f"Completed: Scene {scene.number}, Batch {batch.number}")

translator.events.batch_updated.connect(on_batch_updated)
translator.events.batch_translated.connect(on_batch_translated)

translator.TranslateSubtitles(subtitles)

Explicitly initialising a TranslationProvider

init_translator will automatically construct a TranslationProvider based on the provided options, but it may be useful to construct one explicitly as each supported provider presents slightly different options.

  from PySubtrans import SubtitleTranslator, SettingsType
  from PySubtrans.Providers.Provider_OpenRouter import OpenRouterProvider

  openrouter = OpenRouterProvider(SettingsType({
      'api_key': 'your_openrouter_api_key',
      'use_default_model': False,
      'model_family': "Google",  # Note: should be "Google" not "Gemini"
      'model': "Gemini 2.5 Flash Lite",
      'temperature': 0.2
  }))

translator = SubtitleTranslator(settings, openrouter)

A provider can be constructed once and then used to initalise multiple SubtitleTranslator instances.

Preprocessing subtitles with preprocess_subtitles

preprocess_subtitles can adjust the source subtitles using various heuristics to help produce more translatable subtitles.

Duration and timing adjustments:

• merge_line_duration: Merge lines with very short durations into the previous line
• max_gap_for_merge: Maximum gap between lines for them to be considered part of the same utterance
• max_line_duration: Split lines longer than specified duration (using punctuation as a guide)
• min_split_chars: Minimum characters required for splitting lines
• min_line_duration: Minimum duration for split lines
• min_gap: Ensure minimum gap between subtitle lines

Text processing:

• whitespaces_to_newline: Convert whitespace blocks to newlines (Chinese subtitles often separate dialog lines with multiple spaces, which confuses the translation)
• break_dialog_on_one_line: Detect mid-line dialog markers and add line breaks (helps the models recognise they are separate speakers, not just a dash in the line)
• normalise_dialog_tags: If one line of a multiline subtitle has a dialog marker, add it to the other(s)
• remove_filler_words: Remove specified filler words from text
• filler_words: Comma-separated list of filler words to remove (err, umm, ah, etc.)
• abbreviations: Comma-separated list of titles whose full stop does not end a sentence (Mr, Dr, Mme, etc.), so lines are not split or broken after them. Also used when transcription divides text into sentences. Matching is case-sensitive. List only titles that come before a name, since suffixes such as Jr. can end a sentence. Initials (J.) and dotted abbreviations (U.S.A.) are always recognised
• full_width_punctuation: Ensure full-width punctuation is used in Asian languages
• convert_wide_dashes: Convert wide dashes (emdash) to standard dashes (an anti-GPT pill)

Batching subtitles manually with batch_subtitles

Subtitles must be batched before translation, so if the subtitles were not automatically batched via init_subtitles or init_project you can call batch_subtitles explcitly instead. This returns a list of SubtitleScene containing the batched subtitles.

The parameters are:

scene_threshold: A new scene will be introduced after a gap of N seconds. max_batch_size: If a scene contains too more lines than this it will be subdivided into batches until each batch is no larger than this. min_batch_size: More of a suggestion than a rule, batches are primarily divided to maximise temporal cohesion of each batch. prevent_overlap: If the end time of a subtitle overlaps the start time of the next subtitle it will be reduced to preserve min_gap where possible. min_gap: Minimum gap in seconds to preserve when preventing overlaps.

from PySubtrans import batch_subtitles, init_subtitles

subtitles = init_subtitles("movie.srt", auto_batch=False)
batch_subtitles(subtitles, scene_threshold=90.0, min_batch_size=2, max_batch_size=100)

print(f"Created {subtitles.scenecount} scenes")

Building subtitles programmatically

Use SubtitleBuilder when you want to build subtitles programmatically.

from PySubtrans import Subtitles, SubtitleBuilder
from datetime import timedelta

builder = SubtitleBuilder(max_batch_size=100)
subtitles : Subtitles = (builder
    .AddScene(summary="Opening dialogue")
    .BuildLine(timedelta(seconds=1), timedelta(seconds=3), "Hello, my name is...")
    .BuildLine(timedelta(seconds=4), timedelta(seconds=6), "Nice to meet you!")
    .BuildLine(timedelta(seconds=8), timedelta(seconds=10), "We need to talk.")

    .AddScene(summary="Action sequence")  # New scene
    .BuildLine(timedelta(seconds=65), timedelta(seconds=67), "Look out!")
    # ... 
    .Build()
)

Batching of subtitle lines within each scene is handled automatically.

Preparing subtitles with SubtitleBatcher

SubtitleBatcher can be used to automatically group lines into scenes and batches:

from PySubtrans import Subtitles, SubtitleLine, SubtitleBatcher
from datetime import timedelta

# Initialize subtitles and add lines
lines = [
    SubtitleLine.Construct(1, timedelta(seconds=1), timedelta(seconds=3), "First line"),
    SubtitleLine.Construct(2, timedelta(seconds=4), timedelta(seconds=6), "Second line"),
    SubtitleLine.Construct(3, timedelta(seconds=30), timedelta(seconds=32), "After scene break"),
    #... all the lines for the translation job
]

subtitles = Subtitles()
batcher = SubtitleBatcher({"scene_threshold" : 30, "max_batch_size" : 150})
subtitles.scenes = batcher.BatchSubtitles(lines)

Customising translation with custom instructions

Custom instructions can be supplied via an instruction_file argument or by explicitly overriding prompt and instructions.

prompt is a high level description of the task, whilst instructions provide detailed instructions for the model (as a system prompt, where possible).

This can include directions about how to handle the translation, e.g. "any profanity should be translated without censorship", or notes about the source subtitles (e.g. "the dialogue contains a lot of puns, these should be adapted for the translation").

It is imperative that the instructions contain examples of properly formatted output - see the default instructions for examples.

Your response will be processed by an automated system, so you MUST respond using the required format:

Example (translating to English):

#200
Original>
変わりゆく時代において、
Translation>
In an ever-changing era,

#501
Original>
進化し続けることが生き残る秘訣です。
Translation>
continuing to evolve is the key to survival.

Adapting the examples to your use case can greatly improve the model's performance by teaching it what good looks like.

See LLM-Subtrans for examples of instructions tailored to specific use cases.

A programmatic workflow example

This example shows how to construct subtitles and translate them with progress feedback, working directly with the PySubtrans business logic.

import json
from datetime import timedelta
from PySubtrans import SubtitleBuilder, Options, SubtitleTranslator, TranslationProvider, SubtitleError

# Sample data with scene markers
json_data = {
    "movie_name": "Sample Film",
    "description": "A sample film for demonstration",
    "scenes": [
        {
            "summary": "Opening scene",
            "lines": [
                {"start": "00:00:01.000", "end": "00:00:03.000", "text": "Hello world"},
                {"start": "00:00:04.000", "end": "00:00:06.000", "text": "How are you?"}
            ]
        },
        {
            "summary": "Action sequence",
            "lines": [
                {"start": "00:01:05.000", "end": "00:01:07.000", "text": "Look out!"},
                {"start": "00:01:08.000", "end": "00:01:10.000", "text": "Watch out!"}
            ]
        }
    ]
}

# Build subtitles programmatically
builder = SubtitleBuilder(max_batch_size=100)

for scene_data in json_data["scenes"]:
    builder.AddScene(summary=scene_data["summary"])

    for line_data in scene_data["lines"]:
        builder.BuildLine(
            start=line_data["start"],
            end=line_data["end"],
            text=line_data["text"]
        )

subtitles = builder.Build()

# Configure translator with progress tracking
options = Options({
    'provider': "OpenAI",
    'model': "gpt-5-mini",
    'api_key': "your-api-key",
    'prompt': f"Translate subtitles for {json_data['movie_name']} into Spanish",
    'max_batch_size': 5
})

translation_provider = TranslationProvider.get_provider(options)
if not translation_provider.ValidateSettings():
    raise SubtitleError(translation_provider.validation_message)
    
translator = SubtitleTranslator(options, translation_provider)

# Set up event handlers for real-time feedback
def on_batch_translated(sender, batch):
    print(f"Translated batch {batch.number} in scene {batch.scene} ({batch.size} lines)")
    if batch.summary:
        print(f"  Summary: {batch.summary}")

def on_scene_translated(sender, scene):
    print(f"Completed scene {scene.number}: {scene.summary}")
    print(f"   Total: {scene.linecount} lines in {scene.size} batches")

# Subscribe to translation events
translator.events.batch_translated.connect(on_batch_translated)
translator.events.scene_translated.connect(on_scene_translated)

# Execute translation with progress feedback
print(f"Starting translation of {subtitles.linecount} lines...")
translator.TranslateSubtitles(subtitles)
print("\nTranslation completed!")

Using SubtitleEditor to manipulate Subtitles

SubtitleEditor provides a context manager for modifying Subtitles in a thread-safe manner:

from PySubtrans import SubtitleEditor

subtitles = [...]

with SubtitleEditor(subtitles) as editor:
    # Update scene metadata
    editor.UpdateScene(scene_number = 1, update = {"summary": "Opening dialogue"})

    # Split scene 1 at batch 2 (creates a new scene)
    editor.SplitScene(scene_number = 1, batch_number = 2)

    # Merge batches 1 and 2 in scene 3
    editor.MergeBatches(scene_number = 3, batch_numbers = [1, 2])

    # Merge lines 100 and 101 within batch (2, 1)
    editor.MergeLinesInBatch(scene_number = 2, batch_number = 1, line_numbers = [100, 101])

print(f"Final state: {subtitles.scenecount} scenes, {subtitles.linecount} lines")

Learning from LLM-Subtrans and GUI-Subtrans

There are many possible and correct ways to use PySubtrans. LLM-Subtrans and GUI-Subtrans provide two complete end-to-end examples that use PySubtrans in different ways, making use of different workflows and features. They can be used as a reference when integrating PySubtrans into your application if you want to use more advanced features.

Batch automation example

The LLM-Subtransrepository also includes scripts/batch_translate.py as a ready-to-run sample. The script shows how to:

• build an Options instance with init_options, including command line overrides for provider, model and preview settings,
• walk a source directory using SubtitleFormatRegistry.enumerate_formats() to filter files that PySubtrans can translate,
• load subtitles with init_subtitles, initialise a TranslationProvider and SubtitleTranslator, and subscribe to translator events to provide live progress feedback, and
• save translations to a mirrored directory structure while writing a detailed execution log to disk.

If you need to know more

For a more complete breakdown of the module layout and responsibilities of the various components of PySubtrans refer to the LLM-Subtrans architecture guide.

Release History

See CHANGELOG.md for version history and release notes.

License

PySubtrans is released under the MIT License. See LICENSE for details.